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.

Catalogue

API Description Example
Locations One row per location in either a user or global scope. Fit and run a gravity model
Locations.from_tessellation Convert a legacy tessellation into a global location catalogue. Fit and run a gravity model
Locations.identify Label each location as "home", "work", or "other". Build the visits
Locations.model_input Return the validated Arrow-ready input used by spatial models. City-wide places instead of per-person places
Locations.require_global Return validated global locations as a Narwhals eager dataframe. City-wide places instead of per-person places
Locations.validate_staypoint_assignments Validate non-null staypoint location identities against this catalogue. Checking inputs

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.

These are the default column names; pass location_id_col, center_lat_col, or center_lng_col to use other names. If center_lng is absent, longitude is detected from center_lon, center_longitude, lng, lon, longitude, or long, in that order. The source column name and data are preserved.

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

Locations

Bases: BaseDataFrame

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

Parameters:

Name Type Description Default
df dataframe

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

Location ID column name. Default is "location_id".

 'location_id'
center_lat_col str

Latitude column name. Default is "center_lat".

 'center_lat'
center_lng_col str

Longitude column name. Default is "center_lng"; if absent, center_lon, center_longitude, lng, lon, longitude, and long are tried in that order. Set this to select another column explicitly.

 'center_lng'
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

Tile table with IDs and centres or geometries.

 required
tile_id_col str

Source column names.

 'tile_id'
lat_col str

Source column names.

 None
lng_col str

Source column names.

 None
geometry_col str

Source column names.

 'geometry'

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 fastmob.preprocessing.identify_locations.

Parameters:

Name Type Description Default
staypoints dataframe 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).

Worked example: Fit and run a gravity model · Build the visits · City-wide places instead of per-person places · Checking inputs