Skip to content

Staypoints

Staypoints represents intervals during which a person remained at a place. It is normally created from Positionfixes.generate_staypoints(), and keeps the metadata needed to resolve its user, coordinates, start time, and end time.

Catalogue

API Description Example
Staypoints One row per detected stop: a place a user stayed for a while. City-wide places instead of per-person places
Staypoints.associate_global_locations Validate preassigned exact global IDs against a location catalogue. City-wide places instead of per-person places
Staypoints.build_stvd Aggregate these staypoints against a global Locations catalogue into an STVD frame. Compare when things happen
Staypoints.coerce Return a validated Staypoints wrapper for value. Checking inputs
Staypoints.create_activity_flag Flag each staypoint as a genuine "activity" by dwell time. Which stops are activities?
Staypoints.generate_daily_motifs Compute one home-anchored mobility motif per user and day. One motif per person and day, from the typed tables
Staypoints.generate_global_locations Assign staypoints to shared H3 locations and return their catalogue. Law 2
Staypoints.generate_user_locations Cluster each user's staypoints into recurring locations. Build the visits
Staypoints.interest_network Return the collective interest network over global locations. When and where is each place busy?
Staypoints.resolve_dataframe Normalize staypoint input, resolve measure columns, and validate starts. Checking inputs
Staypoints.validate Check required interval columns and chronological ordering. Checking inputs

Required data

Each row needs a start timestamp and, when validation is enabled, an end timestamp no earlier than the start. Latitude and longitude are used by location generation. staypoint_id is added during hierarchy generation and connects staypoints to later trips.

locations, assigned = staypoints.generate_user_locations(epsilon_km=0.1)
active = assigned.create_activity_flag(time_threshold_min=15)

Use user-scoped locations for personal recurring places, or generate_global_locations() when multiple users need a shared catalogue.

API

Staypoints

Bases: BaseDataFrame

One row per detected stop: a place a user stayed for a while.

Parameters:

Name Type Description Default
df dataframe

Source data; any Narwhals-compatible eager backend.

 required
uid_col str

Explicit column name overrides; auto-detected when None.

 None
lat_col str

Explicit column name overrides; auto-detected when None.

 None
lng_col str

Explicit column name overrides; auto-detected when None.

 None
started_at_col str

Explicit column name overrides; auto-detected when None.

 None
finished_at_col str

Explicit column name overrides; auto-detected when None.

 None
validate bool

When True (default), check that required columns are present and that finished_at >= started_at for every row.

 True

associate_global_locations(locations, location_id_col='location_id')

Validate preassigned exact global IDs against a location catalogue.

Parameters:

Name Type Description Default
locations Locations

Global catalogue containing every permitted location ID.

 required
location_id_col str

Assignment column in this table. Default is "location_id".

 'location_id'

Returns:

Type Description
Staypoints

Copy whose assignment column is named location_id.

Raises:

Type Description
ValueError

If the catalogue is not global or an assigned ID is unknown.

Examples:

>>> assigned = staypoints.associate_global_locations(global_locations)

build_stvd(locations, **kwargs)

Aggregate these staypoints against a global Locations catalogue into an STVD frame.

See fastmob.measures.collective.build_stvd.

Parameters:

Name Type Description Default
locations Locations

Global location catalogue.

 required
**kwargs Any

Forwarded to fastmob.measures.collective.build_stvd.

 {}

Returns:

Type Description
DataFrame

Spatio-temporal visitation distribution.

Examples:

>>> stvd = assigned_staypoints.build_stvd(global_locations)

coerce(value, **column_overrides) classmethod

Return a validated Staypoints wrapper for value.

Existing instances are returned unchanged. Raw dataframe-like inputs are constructed with the same column detection and validation as Staypoints, so measures can share one explicit boundary for accepting raw staypoint data.

Parameters:

Name Type Description Default
value Staypoints or dataframe

Existing wrapper or raw interval table.

 required
**column_overrides Any

Explicit column names, accepted only for a raw table.

 {}

Returns:

Type Description
Staypoints

A validated wrapper.

Examples:

>>> import pandas as pd
>>> from fastmob import Staypoints
>>> raw = pd.DataFrame({"started_at": [pd.Timestamp("2024-01-01")],
...                     "finished_at": [pd.Timestamp("2024-01-01 01:00")]})
>>> Staypoints.coerce(raw)

create_activity_flag(method='time_threshold', time_threshold_min=15.0)

Flag each staypoint as a genuine "activity" by dwell time.

See fastmob.preprocessing.create_activity_flag.

Parameters:

Name Type Description Default
method str

Activity-classification method. Default is "time_threshold".

 'time_threshold'
time_threshold_min float

Minimum dwell duration in minutes. Default is 15.

 15.0

Returns:

Type Description
Staypoints

Copy with a boolean activity column.

Examples:

>>> active = staypoints.create_activity_flag(time_threshold_min=20)

generate_daily_motifs(locations)

Compute one home-anchored mobility motif per user and day.

See fastmob.measures.individual.motifs.daily_motifs_from_staypoints.

Parameters:

Name Type Description Default
locations Locations

Global catalogue with home-location labels available to the motif method.

 required

Returns:

Type Description
DataFrame

One motif result per user and day.

Examples:

>>> motifs = assigned_staypoints.generate_daily_motifs(global_locations)

generate_global_locations(h3_resolution=9)

Assign staypoints to shared H3 locations and return their catalogue.

The returned Locations has global scope and one row per occupied H3 cell; the returned staypoints carry that cell as location_id.

Parameters:

Name Type Description Default
h3_resolution int

H3 resolution from 0 through 15. Default is 9.

 9

Returns:

Type Description
tuple[Locations, Staypoints]

Shared H3 catalogue and its assigned staypoints.

Examples:

>>> locations, assigned = staypoints.generate_global_locations(h3_resolution=9)

generate_user_locations(epsilon_km=0.1, min_samples=1)

Cluster each user's staypoints into recurring locations.

Parameters:

Name Type Description Default
epsilon_km float

Approximate spatial scale, in km, used to select an H3 grid resolution. Default 0.1.

 0.1
min_samples int

Minimum staypoints in an H3 cell for it to be active. Default 1.

 1

Returns:

Type Description
tuple[Locations, Staypoints]

The detected locations, and a copy of self with a new location_id column (null where a staypoint didn't join any recurring location).

Examples:

>>> locations, assigned = staypoints.generate_user_locations(epsilon_km=0.1)

interest_network(locations)

Return the collective interest network over global locations.

See fastmob.measures.collective.interest_network.

Returns:

Type Description
DataFrame

Weighted interest-network edge list.

Examples:

>>> network = assigned_staypoints.interest_network(global_locations)

resolve_dataframe(staypoints, user_id_col=None, timestamp_col=None, lat_col=None, lng_col=None, require_coordinates=False) staticmethod

Normalize staypoint input, resolve measure columns, and validate starts.

Staypoints metadata takes precedence over candidate detection. Raw dataframe inputs stay supported for measures whose historical API did not require an interval end column.

Returns:

Type Description
tuple

Normalized Narwhals frame and resolved user, time, and coordinate names.

Examples:

>>> frame, uid, started_at, lat, lng = Staypoints.resolve_dataframe(staypoints)

validate(df, started_at_col, finished_at_col=None) staticmethod

Check required interval columns and chronological ordering.

Parameters:

Name Type Description Default
df dataframe

Staypoint interval table.

 required
started_at_col str

Start-time column.

 required
finished_at_col str or None

End-time column to validate.

 None

Raises:

Type Description
ValueError

If a required column is missing or an interval ends before it starts.

Examples:

>>> import pandas as pd
>>> from fastmob import Staypoints
>>> frame = pd.DataFrame({"started_at": [pd.Timestamp("2024-01-01")],
...                       "finished_at": [pd.Timestamp("2024-01-01 01:00")]})
>>> Staypoints.validate(frame, "started_at", "finished_at")

Worked example: City-wide places instead of per-person places · Compare when things happen · Checking inputs · Which stops are activities? · One motif per person and day, from the typed tables · Law 2 · Build the visits · When and where is each place busy?