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.

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

`fastmob.core.staypoints_dataframe.Staypoints`

Bases: BaseDataFrame

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

Parameters:

Name	Type	Description	Default
`df`	`DataFrame - like`	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 :func:fastmob.measures.collective.build_stvd.

Parameters:

Name	Type	Description	Default
`locations`	`Locations`	Global location catalogue.	required
`**kwargs`	`Any`	Forwarded to :func:`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 :class:Staypoints, so measures can share one explicit boundary for accepting raw staypoint data.

Parameters:

Name	Type	Description	Default
`value`	`Staypoints or DataFrame - like`	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 :func: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 :func: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 :func: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 - like`	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")

Staypoints

Required data

API

fastmob.core.staypoints_dataframe.Staypoints

associate_global_locations(locations, location_id_col='location_id')

build_stvd(locations, **kwargs)

coerce(value, **column_overrides) classmethod

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

generate_daily_motifs(locations)

generate_global_locations(h3_resolution=9)

generate_user_locations(epsilon_km=0.1, min_samples=1)

interest_network(locations)

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

validate(df, started_at_col, finished_at_col=None) staticmethod

`fastmob.core.staypoints_dataframe.Staypoints`

`associate_global_locations(locations, location_id_col='location_id')`

`build_stvd(locations, **kwargs)`

`coerce(value, **column_overrides)` `classmethod`

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

`generate_daily_motifs(locations)`

`generate_global_locations(h3_resolution=9)`

`generate_user_locations(epsilon_km=0.1, min_samples=1)`

`interest_network(locations)`

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

`validate(df, started_at_col, finished_at_col=None)` `staticmethod`