Skip to content

Locations

Locations is a catalogue of meaningful places. A catalogue is either user-scoped, where a location ID is meaningful only for one user, or global, where every user shares the same location IDs. This distinction makes OD and collective analysis explicit.

Required data

Rows require location_id, center_lat, and center_lng. User-scoped catalogues also carry a user-ID column; global catalogues must not. The scope and scheme metadata describe identity and whether IDs came from clustering, H3, or an external source.

locations, assigned = staypoints.generate_user_locations(epsilon_km=0.1)
labelled = locations.identify(assigned)

Global catalogues validate assignments used by models and collective measures; user catalogues can be labeled as home, work, or other.

API

fastmob.core.locations_dataframe.Locations

Bases: BaseDataFrame

One row per location in either a user or global scope.

Parameters:

Name Type Description Default
df DataFrame - like

Source data; any Narwhals-compatible eager backend.

 required
uid_col str

User-ID column name for user-scoped locations. Must be None for global locations.

 None
scope ('user', 'global')

Location identity scope. When omitted it is inferred from uid_col.

 "user"
scheme ('cluster', 'h3', 'external')

Location-ID scheme. User locations default to "cluster" and global locations default to "external".

 "cluster"
location_id_col str

Column name overrides.

 'location_id'
center_lat_col str

Column name overrides.

 'location_id'
center_lng_col str

Column name overrides.

 'location_id'
validate bool

When True (default), check that required columns are present.

 True

from_tessellation(tessellation, *, tile_id_col='tile_id', lat_col=None, lng_col=None, geometry_col='geometry') classmethod

Convert a legacy tessellation into a global location catalogue.

Numeric coordinates take precedence over geometry. When they are absent, point or polygon geometry is used solely to derive location centres; the original geometry column is retained as metadata.

Parameters:

Name Type Description Default
tessellation DataFrame - like

Tile table with IDs and centres or geometries.

 required
tile_id_col str

Source column names.

 'tile_id'
lat_col str

Source column names.

 'tile_id'
lng_col str

Source column names.

 'tile_id'
geometry_col str

Source column names.

 'tile_id'

Returns:

Type Description
Locations

Global location catalogue.

Examples:

>>> locations = Locations.from_tessellation(tessellation)

identify(staypoints, method='freq', **kwargs)

Label each location as "home", "work", or "other".

See :func:fastmob.preprocessing.identify_locations.

Parameters:

Name Type Description Default
staypoints DataFrame - like or Staypoints

Location-assigned visits.

 required
method str

Purpose-identification method. Default is "freq".

 'freq'
**kwargs Any

Forwarded to the identification function.

 {}

Returns:

Type Description
Locations

User-scoped catalogue with purpose labels.

Examples:

>>> labelled = user_locations.identify(assigned_staypoints)

model_input()

Return the validated Arrow-ready input used by spatial models.

Returns:

Type Description
ModelLocations

Typed view exposing Arrow-ready location columns.

Examples:

>>> model_locations = global_locations.model_input()

require_global()

Return validated global locations as a Narwhals eager dataframe.

Raises:

Type Description
ValueError

If this is a user-scoped catalogue.

Examples:

>>> frame = global_locations.require_global()

validate_staypoint_assignments(staypoints, *, user_id_col, location_id_col)

Validate non-null staypoint location identities against this catalogue.

The validation runs as backend-native distinct/anti joins instead of materializing Python sets. Global catalogues match location_id; user-scoped catalogues match (user_id, location_id).