Skip to content

Tours

Tours represents a sequence of trips that starts and ends at the same location. It is the highest aggregation level in the Trackintel-style hierarchy and can contain multiple trips.

Required data

Rows require tour_id, started_at, and finished_at. Generated tours also store their anchor location_id, the list of trip IDs in journey, and a user ID when applicable.

tours = trips.generate_tours(staypoints_with_locations)
print(tours.df)

Tour generation requires location-assigned staypoints, typically produced by Staypoints.generate_user_locations() or a validated global assignment.

API

fastmob.core.tours_dataframe.Tours

Bases: BaseDataFrame

One row per tour (a sequence of trips returning to its starting location).

.df columns: tour_id, started_at, finished_at, location_id (the anchor location the tour starts and ends at), journey (list of the trip ids making up the tour), plus uid_col when present.

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

from_trips(trips, staypoints_with_location) staticmethod

Group consecutive trips into tours.

See :meth:fastmob.core.trips_dataframe.Trips.generate_tours.

Parameters:

Name Type Description Default
trips Trips

Trip summaries to scan chronologically.

 required
staypoints_with_location Staypoints

Staypoints carrying staypoint_id and location_id columns.

 required

Returns:

Type Description
Tours

Round-trip summaries with an anchor location and journey IDs.

Raises:

Type Description
ValueError

If staypoint location assignments are unavailable.

Examples:

>>> tours = Tours.from_trips(trips, staypoints_with_location)