Integration

PyMove-style spatial and spatiotemporal joins: augment a trajectory dataframe with columns describing its nearest point(s) of interest or nearest event, rather than aggregating the trajectory into a per-user summary like the measures under fastmob.measures.

API	Description
`join_with_pois`	Join each trajectory point with its single nearest point of interest.
`join_with_pois_by_category`	Join each trajectory point with its nearest POI in each category.
`join_with_events`	Join each trajectory point with the nearest event within a time window.

POI/event nearest-neighbor lookup runs through FastMOB's native Rust spatial kernel; no additional installation is required.

import pandas as pd
from fastmob.integration import join_with_pois, join_with_pois_by_category, join_with_events

traj = pd.DataFrame(...)   # lat, lng, datetime columns
pois = pd.DataFrame(...)   # lat, lng, id, name_poi, type_poi columns
events = pd.DataFrame(...) # lat, lng, datetime, event_id, event_type columns

with_pois = join_with_pois(traj, pois)
with_pois_by_cat = join_with_pois_by_category(traj, pois)
with_events = join_with_events(traj, events, time_window_s=900)

A trajectory point with no in-window event, or a pois/events frame with zero rows, reports a real null (None/inf) rather than the untyped NaN/inf sentinel PyMove itself uses.

`fastmob.integration.join_with_pois(traj, pois_df, *, lat_col=None, lng_col=None, poi_lat_col='lat', poi_lng_col='lng', poi_id_col='id', poi_name_col='name_poi')`

Join each trajectory point with its single nearest point of interest.

Mirrors PyMove's join_with_pois: an unconditional single-nearest lookup with no distance cutoff (contrast with :func:fastmob.network.snap_locations_to_graph, which reports "unsnapped" past max_distance_m).

Parameters:

Name	Type	Description	Default
`traj`	`Any`	Trajectory dataframe; any Narwhals-compatible eager backend.	required
`pois_df`	`Any`	Points of interest; any Narwhals-compatible eager backend, with `poi_lat_col`/`poi_lng_col` columns and, unless overridden, `poi_id_col`/`poi_name_col` columns.	required
`lat_col`	`str \| None`	Explicit trajectory column overrides; auto-detected when None.	`None`
`lng_col`	`str \| None`	Explicit trajectory column overrides; auto-detected when None.	`None`
`poi_lat_col`	`str`	Column names on `pois_df`.	`'lat'`
`poi_lng_col`	`str`	Column names on `pois_df`.	`'lat'`
`poi_id_col`	`str`	Column names on `pois_df`.	`'lat'`
`poi_name_col`	`str`	Column names on `pois_df`.	`'lat'`

Returns:

Type	Description
`DataFrame`	`traj`'s columns plus `id_poi`, `dist_poi`, `name_poi`, in the same backend as `traj`. A `pois_df` with zero rows produces `None`/`inf`/`None` for every trajectory point.

`fastmob.integration.join_with_pois_by_category(traj, pois_df, *, lat_col=None, lng_col=None, poi_lat_col='lat', poi_lng_col='lng', poi_id_col='id', category_col='type_poi')`

Join each trajectory point with its nearest POI in each category.

Mirrors PyMove's join_with_pois_by_category: for every distinct value in pois_df[category_col], adds an id_<category>/ dist_<category> column pair holding the nearest POI of that category to each trajectory point (unlike :func:join_with_pois, which only reports the single nearest POI overall).

Returns:

Type	Description
`DataFrame`	`traj`'s columns plus one `id_<category>`/`dist_<category>` column pair per distinct category value present in `pois_df`, in the same backend as `traj`.

`fastmob.integration.join_with_events(traj, events_df, *, lat_col=None, lng_col=None, datetime_col=None, event_lat_col='lat', event_lng_col='lng', event_datetime_col='datetime', event_id_col='event_id', event_type_col='event_type', time_window_s=900.0)`

Join each trajectory point with the nearest event within a time window.

Mirrors PyMove's join_with_events: among events whose timestamp falls within [t - time_window_s, t + time_window_s] of a trajectory point's own timestamp t, picks the spatially nearest one (not the temporally nearest one) and adds event_id, event_type, dist_event columns.

A trajectory point with no event in its window gets a real null for event_id/event_type and inf for dist_event (fastmob's own null-handling convention, unlike PyMove's untyped NaN/inf sentinel columns).

Parameters:

Name	Type	Description	Default
`traj`	`Any`	Trajectory dataframe; any Narwhals-compatible eager backend.	required
`events_df`	`Any`	Events; any Narwhals-compatible eager backend, with `event_lat_col`/`event_lng_col`/`event_datetime_col` columns and, unless overridden, `event_id_col`/`event_type_col` columns.	required
`lat_col`	`str \| None`	Explicit trajectory column overrides; auto-detected when None.	`None`
`lng_col`	`str \| None`	Explicit trajectory column overrides; auto-detected when None.	`None`
`datetime_col`	`str \| None`	Explicit trajectory column overrides; auto-detected when None.	`None`
`time_window_s`	`float`	Symmetric time window (seconds) around each trajectory point's timestamp to search for a matching event.	`900.0`

Returns:

Type	Description
`DataFrame`	`traj`'s columns plus `event_id`, `event_type`, `dist_event`, in the same backend as `traj`.