The trackintel framework

trackintel is a library for the analysis of spatio-temporal tracking data with a focus on human mobility. The core of trackintel is the hierarchical data model for movement data that is used in GIS, transport planning and related fields. We provide functionalities for the full life-cycle of human mobility data analysis: import and export of tracking data of different types (e.g, trackpoints, check-ins, trajectories), preprocessing, data quality assessment, semantic enrichment, quantitative analysis and mining tasks, and visualization of data and results. Trackintel is based on Pandas and GeoPandas.

You can find the documentation on the trackintel documentation page.

Try trackintel online in a MyBinder notebook:

Please star this repo and cite our paper if you find our work is helpful for you.

Data model

An overview of the data model of trackintel:

positionfixes (Raw tracking points, e.g., GPS recordings or check-ins)
staypoints (Locations where a user spent time without moving, e.g., aggregations of positionfixes or check-ins). Staypoints can be classified into the following categories:
- activity staypoints. Staypoints with a purpose and a semantic label, e.g., stopping at a cafe to meet with friends or staying at the workplace.
- non-activity staypoints. Staypoints without an explicit purpose, e.g., waiting for a bus or stopping in a traffic jam.
locations (Important places that are visited more than once, e.g., home or work location)
triplegs (or stages) (Continuous movement without changing mode, vehicle or stopping for too long, e.g., a taxi trip between pick-up and drop-off)
trips (The sequence of all triplegs between two consecutive activity staypoints)
tours (A collection of sequential trips that return to the same location)

An example plot showing the hierarchy of the trackintel data model can be found below:

The image below explicitly shows the definition of locations as clustered staypoints, generated by one or several users.

You can enter the trackintel framework if your data corresponds to any of the above mentioned movement data representation. Here are some of the functionalities that we provide:

Import: Import from the following data formats is supported: geopandas dataframes (recommended), csv files in a specified format, postGIS databases. We also provide specific dataset readers for popular public datasets (e.g, geolife).
Aggregation: We provide functionalities to aggregate into the next level of our data model. E.g., positionfixes→staypoints; positionfixes→triplegs; staypoints→locations; staypoints+triplegs→trips; trips→tours
Enrichment: Activity semantics for staypoints; Mode of transport semantics for triplegs; High level semantics for locations

How it works

trackintel provides support for the full life-cycle of human mobility data analysis.

[1.] Import data.

import geopandas as gpd
import trackintel as ti

# read pfs from csv file
pfs = ti.io.read_positionfixes_csv(".\examples\data\pfs.csv", sep=";", index_col="id")
# or with predefined dataset readers (here geolife) 
pfs, _ = ti.io.read_geolife(".\tests\data\geolife_long")

[2.] Data model generation.

# generate staypoints and triplegs
pfs, sp = pfs.generate_staypoints(method='sliding')
pfs, tpls = pfs.generate_triplegs(sp, method='between_staypoints')

[3.] Visualization.

# plot the generated tripleg result
ti.plot(positionfixes=pfs, staypoints=sp, triplegs=tpls, radius_sp=10)

[4.] Analysis.

# e.g., predict travel mode labels based on travel speed
tpls = tpls.predict_transport_mode()
# or calculate the temporal tracking coverage of users
tracking_coverage = ti.temporal_tracking_quality(tpls, granularity='all')

[5.] Save results.

# save the generated results as csv file 
sp.to_csv(r'.\examples\data\sp.csv')
tpls.to_csv(r'.\examples\data\tpls.csv')

For example, the plot below shows the generated staypoints and triplegs from the imported raw positionfix data.

Installation and Usage

trackintel is on pypi.org and conda-forge. We recommend installing trackintel via conda-forge:

conda install -c conda-forge trackintel

Alternatively, you can install it with pip in a GeoPandas available environment using:

pip install trackintel

You should then be able to run the examples in the examples folder or import trackintel using:

import trackintel as ti

ti.print_version()

Requirements and dependencies

Numpy
GeoPandas
Matplotlib
Pint
NetworkX
GeoAlchemy2
scikit-learn
tqdm
OSMnx
similaritymeasures

Development

You can find the development roadmap under ROADMAP.md and further development guidelines under CONTRIBUTING.md.

Contributors

trackintel is primarily maintained by the Mobility Information Engineering Lab at ETH Zurich (mie-lab.ethz.ch). If you want to contribute, send a pull request and put yourself in the AUTHORS.md file.

Citation

If you find this code useful for your work or use it in your project, please consider citing:

@article{Martin_2023_trackintel,
  doi = {10.1016/j.compenvurbsys.2023.101938},
  volume = {101},
  pages = {101938},
  author = {Henry Martin and Ye Hong and Nina Wiedemann and Dominik Bucher and Martin Raubal},
  keywords = {Human mobility analysis, Open-source software, Transport planning, Data mining, Python, Tracking studies},
  title = {Trackintel: An open-source Python library for human mobility analysis},
  journal = {Computers, Environment and Urban Systems},
  year = {2023},
}

henrymartin1/trackintel