Skip to content

Trips

labda.Subject.detect_trips

detect_trips(
    gap_duration: timedelta,
    stop_radius: int | float,
    stop_duration: timedelta,
    *,
    max_speed: int | float | None = None,
    min_distance: int | float | None = None,
    pause_radius: int | float | None = None,
    pause_duration: timedelta | None = None,
    pause_fill: str | None = None,
    min_duration: timedelta | None = None,
    min_length: int | float | None = None,
    cut_points: dict[str, Any] | None = None,
    window: int | None = None,
    activity: bool = False,
    indoor_limit: float | None = None,
    overwrite: bool = False
) -> None

Detects trips and transportation modes in the subject's data based on the specified parameters. The detected trips are stored in the subject's timeline and DataFrame is annotated with trip and transportation mode information.

You can load prepared cut points for transportation mode detection or provide your own, see the example below.

Parameters:

Name Type Description Default
gap_duration timedelta

The minimum duration to consider a gap, i.e. if there is missing data for longer than this duration, the data is split into a new segment and analysed separately.

required
stop_radius int | float

The maximum radius that subject needs to stay in to be considered a stop.

required
stop_duration timedelta

The minimum duration to subject need to stay in specified radius to be considered a stop.

required
max_speed int | float | None

The maximum speed between points. If the speed between points is higher than this value, data are split into a new segment and analysed separately.

None
min_distance int | float | None

The minimum distance between points. Points that are closer than this distance are filtered out.

None
pause_radius int | float | None

The maximum radius that subject needs to stay in to be considered a as a trip pause.

None
pause_duration timedelta | None

The minimum duration to subject need to stay in specified radius to be considered as a trip pause.

None
pause_fill str | None

If pauses should also have transportation mode. Options are "forward" or "backward" fill (based on the previous or next transportation mode of the trip).

None
min_duration timedelta | None

The minimum duration of a trip. Trips shorter than this duration are annotated as stationary (stop) points.

None
min_length int | float | None

The minimum length of a trip. Trips shorter than this length are annotated as stationary (stop) points.

None
cut_points dict[str, Any] | None

Dictionary of cut points for transportation modes identification. If not provided, transportation modes are not detected.

None
window int | None

The window size for moving average for transportation mode detection.

None
activity bool

Wheter to use data from activity intensity column for transportation mode detection (combination of cut points and activity intensity column is used for detection).

False
indoor_limit float | None

How much of the data needs to be identified as indoor for the whole trip to be removed (changed to stationary).

None
overwrite bool

Whether to overwrite existing trip data.

False

Raises:

Type Description
ValueError

If the subject's CRS is not defined.

ValueError

If the timeline already exists and 'overwrite' is False.

Examples:

Here's how to call the function. For this example we assume that the subject's data has information for physical activity intensity and environment (indoor/outdoor) and data are collected in less than 1 minute intervals.

from datetime import timedelta

from labda import Subject
from labda.assets import TRANSPORTATION_CUT_POINTS

subject = Subject.from_parquet("subject.parquet")

subject.detect_trips(
    "gap_duration": timedelta(minutes=1),
    "stop_radius": 25,
    "stop_duration": timedelta(minutes=3),
    "max_speed": 220,
    "min_distance": None,
    "pause_radius": 15,
    "pause_duration": timedelta(minutes=1.5),
    "pause_fill": "forward",
    "min_duration": timedelta(minutes=2),
    "min_length": None,
    "cut_points": TRANSPORTATION_CUT_POINTS[1],
    "window": 3,
    "activity": True,
    "indoor_limit": 92.5,
    "overwrite": True,
    )