Skip to content

Trips

Trips aggregates consecutive triplegs between activity staypoints. It captures the full journey between meaningful activities, including the contributing tripleg IDs and endpoint staypoint IDs.

Catalogue

API Description Example
Trips One row per trip. Compare two flow tables
Trips.common_part_of_commuters Compare trips using globally comparable endpoint location IDs. Compare two flow tables
Trips.common_part_of_commuters_distance Return the distance-weighted CPC score against another trip set. Common part of commuters and links
Trips.common_part_of_links Return the common part of links score against another trip set. Compare two flow tables
Trips.from_triplegs Derive trips from triplegs + activity-flagged staypoints. The same pipeline, step by step
Trips.generate_tours Group consecutive trips into tours (round trips back to the same location). Trips and tours
Trips.to_flow_dataframe Materialize this trip set as aggregated sparse OD flows. Compare two flow tables

Required data

Rows require trip_id, started_at, and finished_at. Generated trips include origin_staypoint_id, destination_staypoint_id, and tripleg_ids. When their staypoints have global location IDs, trips also carry endpoint location IDs for OD comparison and flow aggregation.

flows = trips.to_flow_dataframe()
score = trips.common_part_of_commuters(other_trips)
tours = trips.generate_tours(staypoints_with_locations)

Use FlowDataFrame for a materialized sparse OD table or Tours to group journeys that return to their starting place.

API

Trips

Bases: BaseDataFrame

One row per trip.

.df columns: trip_id, started_at, finished_at, origin_staypoint_id, destination_staypoint_id, tripleg_ids (a list of the tripleg ids making up the trip), plus uid_col when present. origin_staypoint_id is null for a user's very first trip (no staypoint precedes it); destination_staypoint_id is null for a user's last trip if it never reaches another activity staypoint. Optional origin_location_id and destination_location_id columns identify globally comparable locations for sparse OD comparisons.

Parameters:

Name Type Description Default
df dataframe

Source data; any Narwhals-compatible eager backend.

 required
uid_col str

User-ID column name.

 None
validate bool

When True (default), check that required columns are present.

 True

common_part_of_commuters(other)

Compare trips using globally comparable endpoint location IDs.

Returns the common part of commuters (CPC) score.

Examples:

>>> score = trips.common_part_of_commuters(reference_trips)

common_part_of_commuters_distance(other)

Return the distance-weighted CPC score against another trip set.

Examples:

>>> score = trips.common_part_of_commuters_distance(reference_trips)

Return the common part of links score against another trip set.

Examples:

>>> score = trips.common_part_of_links(reference_trips)

from_triplegs(triplegs, staypoints, gap_threshold_min=15.0) staticmethod

Derive trips from triplegs + activity-flagged staypoints.

See fastmob.core.triplegs_dataframe.Triplegs.generate_trips.

Parameters:

Name Type Description Default
triplegs Triplegs

Movement segments to aggregate.

 required
staypoints Staypoints

Staypoints with an activity column.

 required
gap_threshold_min float

Reserved compatibility parameter.

 15.0

Returns:

Type Description
Trips

Activity-to-activity trip summaries.

Examples:

>>> trips = Trips.from_triplegs(triplegs, activity_staypoints)

generate_tours(staypoints_with_location)

Group consecutive trips into tours (round trips back to the same location).

See fastmob.core.tours_dataframe.Tours.from_trips.

Examples:

>>> tours = trips.generate_tours(staypoints_with_location)

to_flow_dataframe()

Materialize this trip set as aggregated sparse OD flows.

CPC does not call this method: it streams endpoint IDs straight to the Rust kernel. Use it only when an explicit FlowDataFrame is required.

Returns:

Type Description
FlowDataFrame

Sparse OD flows aggregated from endpoint location IDs.

Examples:

>>> flows = trips.to_flow_dataframe()

Worked example: Compare two flow tables · Common part of commuters and links · The same pipeline, step by step · Trips and tours