Positionfixes

Positionfixes is the raw-observation level of the Trackintel-style mobility hierarchy. It is a semantic subclass of TrajDataFrame: one row represents one GPS fix with a timestamp, coordinates, and optionally a user ID.

Required data

Use the same trajectory columns as TrajDataFrame: datetime, latitude, longitude, and optionally a user identifier. Calling generate_staypoints() returns interval-based Staypoints; generate_triplegs() uses those detected stops to derive movement summaries.

from fastmob import Positionfixes

fixes = Positionfixes(traj, sort=True)
staypoints = fixes.generate_staypoints(minutes_for_a_stop=20)
triplegs = fixes.generate_triplegs(staypoints)

Continue with Staypoints to assign recurring locations or with Triplegs to classify movement.

API

`fastmob.core.positionfixes_dataframe.Positionfixes`

Bases: TrajDataFrame

Semantic alias for TrajDataFrame at the base of the Positionfixes -> Staypoints -> Triplegs -> Trips -> Tours hierarchy.

`generate_staypoints(**kwargs)`

Detect stop locations, returning them as a typed Staypoints level.

Thin wrapper around fastmob.preprocessing.stay_locations: renames its datetime/leaving_datetime output columns to started_at/finished_at and records the stop-detection parameters used (so generate_triplegs can reuse them by default).

Parameters:

Name	Type	Description	Default
`**kwargs`	`Any`	Forwarded to :func:`fastmob.preprocessing.stay_locations` (`minutes_for_a_stop`, `spatial_radius_km`, etc.).	`{}`

Returns:

Type	Description
`Staypoints`

Examples:

>>> import pandas as pd
>>> from fastmob import Positionfixes
>>> base = pd.Timestamp("2024-01-01")
>>> rows = [
...     {"uid": "u1", "datetime": base + pd.Timedelta(minutes=m), "lat": 0.0, "lng": 0.0}
...     for m in range(0, 31, 5)
... ] + [
...     {"uid": "u1", "datetime": base + pd.Timedelta(minutes=30 + i), "lat": 0.0, "lng": 0.01 * i}
...     for i in range(1, 11)
... ] + [
...     {"uid": "u1", "datetime": base + pd.Timedelta(minutes=41 + m), "lat": 0.0, "lng": 0.1}
...     for m in range(0, 31, 5)
... ]
>>> fixes = Positionfixes(pd.DataFrame(rows))
>>> stays = fixes.generate_staypoints(minutes_for_a_stop=20, spatial_radius_km=0.2)
>>> stays.df[["staypoint_id", "lng"]].to_dict("records")
[{'staypoint_id': 0, 'lng': 0.0}, {'staypoint_id': 1, 'lng': 0.1}]

`generate_triplegs(staypoints, gap_threshold_min=15.0, **stop_kwargs)`

Derive movement segments (triplegs) between staypoints.

Parameters:

Name	Type	Description	Default
`staypoints`	`Staypoints`	Staypoints previously generated from this same trajectory (ideally via :meth:`generate_staypoints`, so stop-detection parameters match).	required
`gap_threshold_min`	`float`	Reserved for future gap-based tripleg splitting; unused by the current `"between_staypoints"` method. Default `15.0`.	`15.0`
`**stop_kwargs`	`Any`	Stop-detection parameter overrides forwarded to :func:`fastmob.preprocessing.segment` (`stop_radius_km`, `minutes_for_a_stop`, ...). Defaults to the parameters recorded on `staypoints` (from :meth:`generate_staypoints`) when not given.	`{}`

Returns:

Type	Description
`Triplegs`

Examples:

>>> staypoints = fixes.generate_staypoints(minutes_for_a_stop=20, spatial_radius_km=0.2)
>>> triplegs = fixes.generate_triplegs(staypoints)
>>> triplegs.df[["tripleg_id", "duration_s"]].to_dict("records")
[{'tripleg_id': 1, 'duration_s': 540.0}]