Model

In trackintel, tracking data is split into several classes. It is not generally assumed that data is already available in all these classes, instead, trackintel provides functionality to generate everything starting from the raw GPS positionfix data (consisting of at least (user_id, tracked_at, longitude, latitude) tuples).

  • users: The users for which data is available.

  • positionfixes: Raw GPS data.

  • staypoints: Locations where a user spent a minimal time.

  • triplegs: Segments covered with one mode of transport.

  • locations: Clustered staypoints.

  • trips: Segments between consecutive activity staypoints (special staypoints that are not just waiting points).

  • tours: Sequences of trips which start and end at the same location (if journey is set to True, this location is home).

A detailed (and SQL-specific) explanation of the different classes can be found under Data Model (SQL).

Some of the more time-consuming functions of trackintel generate logging data, as well as extracted features data, and they assume more data about geographic features or characteristics of transport modes are available. These are not explained here yet.

GeoPandas Implementation

In trackintel, we assume that all these classes are available as (Geo)Pandas (Geo)DataFrames. While we do not extend the given DataFrame constructs, we provide accessors that validate that a given DataFrame corresponds to a set of constraints, and make functions available on the DataFrames. For example:

df = trackintel.read_positionfixes_csv('data.csv')
df.as_positionfixes.extract_staypoints()

This will read a CSV into a format compatible with the trackintel understanding of a collection of positionfixes, and the second line will wrap the DataFrame with an accessor providing functions such as extract_staypoints(). You can read up more on Pandas accessors in the Pandas documentation.

Available Accessors

The following accessors are available within trackintel.

trackintel.model.users.UsersAccessor

alias of pandas.api.extensions.

trackintel.model.positionfixes.PositionfixesAccessor

alias of pandas.api.extensions.

trackintel.model.staypoints.StaypointsAccessor

alias of pandas.api.extensions.

trackintel.model.triplegs.TriplegsAccessor

alias of pandas.api.extensions.

trackintel.model.locations.LocationsAccessor

alias of pandas.api.extensions.

trackintel.model.trips.TripsAccessor

alias of pandas.api.extensions.

class trackintel.model.tours.ToursAccessor(pandas_obj)

A pandas accessor to treat DataFrames as collections of tours.

Requires at least the following columns: ['user_id', 'started_at', 'finished_at', 'origin_destination_location_id', 'journey']

The index of the GeoDataFrame will be treated as unique identifier of the trips

For several usecases, the following additional columns are required: ['context']

Notes

Tours are an aggregation level in transport planning that summarize all trips until a person returns to the same location. Tours starting and ending at home (=journey) are especially important.

started_at and finished_at are timezone aware pandas datetime objects.

Examples

>>> df.as_tours.plot()