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.

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

fastmob.core.trips_dataframe.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 - like

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 :meth: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 :meth: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()