Data Structures
fastmob uses small, typed wrappers around backend-native DataFrames. They retain the underlying pandas, Polars, or other Narwhals-compatible frame while making the columns and operations for a mobility-analysis level explicit.
Choose a structure
| Structure | Use it for | Next step |
|---|---|---|
TrajDataFrame |
Generic timestamped trajectory points and the original fastmob trajectory API. | Measure, clean, map, or convert trajectories. |
Positionfixes |
Raw GPS fixes in the Trackintel-style hierarchy. | Generate staypoints and triplegs. |
Staypoints |
Intervals where a person remained at a place. | Assign activity flags and locations. |
Locations |
Recurring user places or a shared global location catalogue. | Identify purposes or validate assignments. |
Triplegs |
Single movement segments between staypoints. | Predict mode or aggregate into trips. |
Trips |
Connected triplegs between activity staypoints. | Compare OD demand, create flows, or generate tours. |
Tours |
Round trips that return to their starting location. | Analyze journeys as a whole. |
FlowDataFrame |
Sparse origin-destination flows. | Query, compare, or convert the OD matrix. |
Mobility hierarchy
The hierarchy follows the Trackintel vocabulary. Start from raw
Positionfixes, detect
Staypoints and
Triplegs, then aggregate them into
Locations, Trips,
and Tours. A trip collection with global location
IDs can also become a FlowDataFrame.
TrajDataFrame remains the general-purpose trajectory wrapper. Positionfixes
is its semantic, hierarchy-aware subclass, so existing trajectory workflows can
adopt the hierarchy incrementally.
Shared behavior
Every wrapper exposes .df for its original DataFrame and .to_native() to
return the native backend object. Use .to_pandas() or .to_polars() when a
specific native dataframe backend is required. Hierarchy wrappers also inherit
comparison and chart helpers from BaseDataFrame; the generated API on each
page documents the operations defined for that structure.