Metadata-Version: 2.4
Name: fastmob
Version: 0.3.4
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Dist: narwhals>=1.0
Requires-Dist: numpy
Requires-Dist: pyarrow>=14
Requires-Dist: geopandas ; extra == 'geo'
Requires-Dist: shapely ; extra == 'geo'
Requires-Dist: pyproj ; extra == 'geo'
Requires-Dist: fastmob-vis>=0.1.1,<0.2 ; extra == 'vis'
Provides-Extra: geo
Provides-Extra: vis
License-File: LICENSE
Summary: High-performance mobility analysis with a Rust-accelerated core and backend-agnostic DataFrame API.
Author: Gustavo Henrique Bruno dos Santos
License-Expression: BSD-3-Clause
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Documentation, https://gefgu.github.io/fastmob/
Project-URL: Homepage, https://github.com/gefgu/fastmob
Project-URL: Issues, https://github.com/gefgu/fastmob/issues
Project-URL: Repository, https://github.com/gefgu/fastmob

<p align="center">
  <img src="docs/src/assets/logo_filled.svg" alt="Fastkit-Mobility logo" width="280">
</p>

# Fastkit-Mobility

[![PyPI version](https://img.shields.io/pypi/v/fastmob)](https://pypi.org/project/fastmob/)
[![Total downloads](https://static.pepy.tech/badge/fastmob)](https://pepy.tech/projects/fastmob)
[![Python versions](https://img.shields.io/pypi/pyversions/fastmob)](https://pypi.org/project/fastmob/)
[![License](https://img.shields.io/pypi/l/fastmob)](LICENSE)

**Fastkit-Mobility** helps researchers turn location data into insights about how
people move. Clean GPS traces, find stops and trips, measure travel patterns,
and simulate mobility using familiar Python dataframes. Its Rust engine handles
compute-intensive work while you work with pandas or Polars.

[Get started](https://gefgu.github.io/fastmob/learn/) · [Explore the examples](https://gefgu.github.io/fastmob/learn/) · [API reference](https://gefgu.github.io/fastmob/reference/) · [Benchmarks](https://gefgu.github.io/fastmob/features/benchmarks/)


<p align="center">
  <img src="docs/src/assets/images/home/home-geolife-staypoints-triplegs.png" alt="GPS fixes, detected stops and trips for one day of a GeoLife participant in Beijing" width="650">
</p>

One day of GeoLife GPS data: grey points are GPS fixes, gold circles are detected
stops (staypoints), and coloured lines show movement between them (triplegs). Follow the [complete GeoLife example](https://gefgu.github.io/fastmob/learn/notebooks/stay-point-detection-geolife/).

## Try it

Install Fastkit-Mobility and pandas for this example (Python 3.9 or newer):

```bash
pip install fastmob pandas
```

Calculate each person's **radius of gyration**: a measure, in kilometres, of
how widely their observed locations spread around their centre of movement.

```python
import pandas as pd
from fastmob import radius_of_gyration

df = pd.DataFrame({
    "uid": ["alice"] * 3 + ["bob"] * 3,
    "datetime": pd.to_datetime(["2020-01-01 08:00", "2020-01-01 09:00", "2020-01-01 10:00"] * 2),
    "lat": [41.9, 42.0, 42.1, 40.7, 40.8, 41.0],
    "lng": [12.5, 12.5, 12.6, -74.0, -74.0, -73.9],
})

print(radius_of_gyration(df))
```

```text
     uid  radius_of_gyration
0  alice            9.878827
1    bob           14.423721
```

In this small example, Bob's observed locations are more spread out than
Alice's. Explore more [individual and collective measures](https://gefgu.github.io/fastmob/learn/individual-and-collective-measures/).

## What can you study?

- **Clean and segment traces:** filter noisy GPS data and separate movement from stops. [Learn how](https://gefgu.github.io/fastmob/learn/clean-and-segment/).
- **Find stops and recurring places:** identify where people spend time and group repeated visits to locations. [Learn how](https://gefgu.github.io/fastmob/learn/staypoints-and-locations/).
- **Measure movement:** study individual ranges and travel patterns, or flows across a population. [Explore measures](https://gefgu.github.io/fastmob/learn/individual-and-collective-measures/).
- **Work with transport networks:** route and match GPS traces to road and rail networks. [Explore network analysis](https://gefgu.github.io/fastmob/learn/network-analysis/).
- **Model mobility:** generate synthetic trajectories or flows and compare models with observations. [Explore models](https://gefgu.github.io/fastmob/reference/models/).


## Performance and compatibility

Fastkit-Mobility uses Rust for compute-intensive operations and supports pandas,
Polars and other eager dataframes through Narwhals. Many measure names and
signatures follow [scikit-mobility](https://github.com/scikit-mobility/scikit-mobility).

<p align="center">
  <img src="docs/src/assets/images/home/home-benchmark-speedup.png" alt="Execution times for five mobility measures: Fastkit-Mobility with pandas compared with scikit-mobility on approximately four million Brightkite check-ins" width="800">
</p>

Average execution time for five measures on approximately 4 million time-sorted
Brightkite check-ins. Fastkit-Mobility uses pandas; the comparison is with
scikit-mobility. Times are averages of three runs on an Intel Core i7-10700 with
Python 3.12, and the chart uses a logarithmic scale. The scikit-mobility input
contained 3,999,891 rows and the Fastkit-Mobility input 4,000,000. Results depend
on the operation, data and environment. See the [raw benchmark record](https://github.com/gefgu/fastmob_benchmarks/blob/main/benchmarks/measures/results/py312_intel_core_i7_10700_16c_brightkite4M/measures_benchmarks.json)
and [more comparisons](https://gefgu.github.io/fastmob/features/benchmarks/).

For citing a specific software release, see the [citation guide](https://gefgu.github.io/fastmob/about/#cite-fastkit-mobility).

## More resources

- [Guides and tutorials](https://gefgu.github.io/fastmob/learn/) · [API reference](https://gefgu.github.io/fastmob/reference/) · [Release notes](https://gefgu.github.io/fastmob/release_notes/)
- [Contributing and development setup](docs/CONTRIBUTING.md)
- [Report an issue](https://github.com/gefgu/fastmob/issues): include package versions, dataframe backend, a minimal example, expected behavior and the full error.

For a fastmob release, set the version in `fastmob-py/Cargo.toml`, run the
release checks, and tag the tested commit `fastmob-v<version>` (for example,
`fastmob-v0.3.4`). Push that tag to trigger the wheel builds and PyPI release.
Tags named only `v<version>` do not trigger the fastmob release workflow.

## Status and support

Fastmob is actively developed. Please include versions, dataframe backend, a
minimal reproducible input, expected behavior, and the full error when opening
an issue.

## Citation

If you use Fastkit-Mobility in research, please cite the
[NetMob 2026 paper](https://inria.hal.science/hal-05755990):

```bibtex
@inproceedings{santos2026fastkit,
  author    = {Santos, Gustavo H. and Viana, Aline Carneiro and
               Pappalardo, Luca and Silva, Thiago H.},
  title     = {Fastkit-Mobility: A High-Performance, DataFrame-Agnostic Library for Mobility Analysis},
  booktitle = {NetMob 2026},
  address   = {Niter{\'o}i, Brazil},
  year      = {2026},
  month     = oct,
  url       = {https://inria.hal.science/hal-05755990}
}
```

