sequential_algs

nomad.stop_detection.sequential_algs.detect_stops(data, delta_roam=100, dt_max=15.0, dur_min=5.0, method='sliding', complete_output=False, passthrough_cols=None, keep_col_names=True, traj_cols=None, passthrough_agg=None, **kwargs)

Sequential stop detection using sliding window approach.

Analogous to lachesis function but uses sliding window method.

Parameters:

• data (pd.DataFrame or GeoDataFrame) – Input trajectory with spatial and temporal columns.

• delta_roam (float, default 100) – Maximum distance threshold in meters (for haversine) or map units (for euclidean).

• dt_max (float, default 15.0) – Maximum allowed gap in minutes between consecutive points in a stop.

• dur_min (float, default 5.0) – Minimum duration in minutes for a valid stop.

• method (str, default 'sliding') – Method to use (‘sliding’ currently supported).

• complete_output (bool, default False) – If True, include additional summary statistics in output.

• passthrough_cols (list, optional) – Columns to retain (and summarize/propagate) per stop.

• passthrough_agg (dict, optional) – Aggregation functions for selected passthrough columns.

• keep_col_names (bool, default True) – Whether to keep original column names in output.

• traj_cols (dict, optional) – Mapping for ‘x’, ‘y’, ‘longitude’, ‘latitude’, ‘timestamp’, or ‘datetime’.

• **kwargs – Passed along to column detection helper.

Returns:

Stop table with one row per detected stop.

Return type:

pd.DataFrame

Raises:

ValueError if multiple users found; use detect_stops_per_user instead. –

nomad.stop_detection.sequential_algs.detect_stops_labels(data, delta_roam=100, dt_max=15.0, dur_min=5.0, method='sliding', traj_cols=None, **kwargs)

Scan a trajectory and assign each point to a stop cluster index or -1 for noise.

Uses a sliding window approach where points are grouped into stops based on: - Spatial constraint: all points within delta_roam of first point in window - Temporal constraint: no gaps > dt_max between consecutive points - Duration constraint: total duration >= dur_min

Parameters:

• data (pd.DataFrame or gpd.GeoDataFrame) – Input trajectory with spatial and temporal columns

• delta_roam (float, default 100) – Maximum distance threshold in meters (for haversine) or map units (for euclidean)

• dt_max (float, default 15.0) – Maximum allowed gap in minutes between consecutive points in a stop

• dur_min (float, default 5.0) – Minimum duration in minutes for a valid stop

• method (str, default 'sliding') – Method to use (‘sliding’ or ‘centroid’) for the anchor point of the active stop

• traj_cols (dict, optional) – Mapping for ‘x’, ‘y’, ‘longitude’, ‘latitude’, ‘timestamp’, or ‘datetime’

• **kwargs – Passed along to column detection helper

Returns:

Cluster labels.

Return type:

pd.Series

nomad.stop_detection.sequential_algs.detect_stops_labels_per_user(data, delta_roam=100, dt_max=15.0, dur_min=5.0, method='sliding', traj_cols=None, n_jobs=1, print_progress=False, **kwargs)

Run detect_stops_labels on each user separately and concatenate labels.

Raises if ‘user_id’ not in traj_cols or missing from data.

nomad.stop_detection.sequential_algs.detect_stops_per_user(data, delta_roam=100, dt_max=15.0, dur_min=5.0, method='sliding', complete_output=False, passthrough_cols=None, keep_col_names=True, traj_cols=None, n_jobs=1, print_progress=False, passthrough_agg=None, **kwargs)

Run detect_stops on each user separately, then concatenate results.

Parameters:

• data (pd.DataFrame or GeoDataFrame) – Input trajectory with spatial and temporal columns.

• delta_roam (float, default 100) – Maximum distance threshold in meters (for haversine) or map units (for euclidean).

• dt_max (float, default 15.0) – Maximum allowed gap in minutes between consecutive points in a stop.

• dur_min (float, default 5.0) – Minimum duration in minutes for a valid stop.

• method (str, default 'sliding') – Method to use (‘sliding’ currently supported).

• complete_output (bool, default False) – If True, include additional summary statistics in output.

• passthrough_cols (list, optional) – Columns to retain (and summarize/propagate) per stop.

• passthrough_agg (dict, optional) – Aggregation functions for selected passthrough columns.

• keep_col_names (bool, default True) – Whether to keep original column names in output.

• traj_cols (dict, optional) – Mapping for ‘x’, ‘y’, ‘longitude’, ‘latitude’, ‘timestamp’, or ‘datetime’.

• n_jobs (int, default 1) – Number of parallel jobs to use. 1 means sequential processing.

• print_progress (bool, default False) – Whether to show progress bar during processing.

• **kwargs – Passed along to column detection helper.

Returns:

Concatenated stop table with stops from all users.

Return type:

pd.DataFrame

Raises:

ValueError if 'user_id' not in traj_cols or missing from data. –

nomad.stop_detection.sequential_algs.grid_based(data, time_thresh=120, min_cluster_size=2, dur_min=5, complete_output=False, passthrough_cols=None, traj_cols=None, passthrough_agg=None, **kwargs)

Detect stops in trajectory data using a grid/location-based segmentation, then summarize them.

Parameters:

• data (pd.DataFrame) – Input trajectory data with temporal and location columns.

• time_thresh (int, optional) – Maximum allowed time gap (in minutes) between consecutive pings within a stop. Default is 5.

• min_cluster_size (int, optional) – Minimum number of points required to form a stop. Default is 2.

• dur_min (int, optional) – Minimum duration in minutes for a valid stop. Default is 5.

• complete_output (bool, optional) – If True, include additional stop statistics in the output.

• passthrough_cols (list, optional) – Columns to retain per stop.

• passthrough_agg (dict, optional) – Aggregation functions for selected passthrough columns.

• traj_cols (dict, optional) – Mapping for ‘timestamp’, ‘datetime’, or ‘location_id’ column names.

• **kwargs – Passed through to helper functions for flexible column mapping.

Returns:

One row per stop, summarizing its centroid/medoid, duration, and optionally full stats.

Return type:

pd.DataFrame

nomad.stop_detection.sequential_algs.grid_based_labels(data, time_thresh=inf, min_cluster_size=1, dur_min=0, traj_cols=None, **kwargs)

Detects stops in trajectory data based on time and each ping’s location.

Parameters:

• data (pd.DataFrame) – Input trajectory data containing temporal columns and a location column.

• time_thresh (int) – Maximum allowed time difference (in minutes) between consecutive pings within a stop. time_thresh should be greater than dur_min.

• min_cluster_size (int) – Minimum number of points required to form a stop.

• dur_min (int) – Minimum duration (in minutes) for a valid stop.

• traj_cols (dict, optional) – A dictionary defining column mappings for ‘timestamp’, ‘datetime’ or ‘location_id’. Defaults to None.

Returns:

Integer cluster labels aligned with data.index. Noise gets labels of –1.

Return type:

pd.Series

nomad.stop_detection.sequential_algs.grid_based_labels_per_user(data, time_thresh=inf, min_cluster_size=1, dur_min=0, traj_cols=None, n_jobs=1, print_progress=False, **kwargs)

Run grid_based_labels on each user separately and concatenate labels.

Raises if ‘user_id’ not in traj_cols or missing from data.

nomad.stop_detection.sequential_algs.grid_based_per_user(data, time_thresh=120, min_cluster_size=2, dur_min=5, complete_output=False, passthrough_cols=None, traj_cols=None, n_jobs=1, print_progress=False, passthrough_agg=None, **kwargs)

Run grid_based stop detection on each user separately, then concatenate results. Raises an error if ‘user_id’ is not in traj_cols or kwargs.

nomad.stop_detection.sequential_algs.lachesis(data, delta_roam, dt_max=60, dur_min=5, complete_output=False, passthrough_cols=None, keep_col_names=True, postprocessing=None, eps=None, traj_cols=None, passthrough_agg=None, **kwargs)

Sequential stop detection with diameter stopping criterion

Parameters:

• data (pd.DataFrame or GeoDataFrame) – Input trajectory with spatial and temporal columns.

• dt_max (int) – Maximum allowed gap in minutes between consecutive pings in a stop.

• delta_roam (float) – Maximum spatial diameter for a stop.

• dur_min (int) – Minimum duration in minutes for a valid stop.

• traj_cols (dict, optional) – Mapping for ‘x’, ‘y’, ‘longitude’, ‘latitude’, ‘timestamp’, or ‘datetime’.

• **kwargs – Passed along to the column‐detection helper.

• passthrough_cols (list, optional) – Columns to retain (and summarize/propagate) per stop.

• passthrough_agg (dict, optional) – Aggregation functions for selected passthrough columns.

• postprocessing ({None, 'dbscan'}, optional) – Optional stop postprocessing method.

• eps (float, optional) – DBSCAN neighborhood distance. Required when postprocessing='dbscan'.

Returns:

One row per detected stop.

Return type:

pd.DataFrame

Raises:

ValueError if multiple users found; use lachesis_per_user instead. –

nomad.stop_detection.sequential_algs.lachesis_labels(data, dt_max, delta_roam, dur_min=5, traj_cols=None, return_anchors=False, postprocessing=None, eps=None, **kwargs)

Scan a trajectory and assign each ping to a stop‐cluster index or -1 for noise.

Parameters:

• data (pd.DataFrame or GeoDataFrame) – Input trajectory with spatial and temporal columns.

• dt_max (int) – Maximum allowed gap in minutes between consecutive pings in a stop.

• delta_roam (float) – Maximum spatial diameter for a stop.

• dur_min (int) – Minimum duration in minutes for a valid stop.

• traj_cols (dict, optional) – Mapping for ‘x’, ‘y’, ‘longitude’, ‘latitude’, ‘timestamp’, or ‘datetime’.

• return_anchors (bool, default False) – Return the earliest endpoint of each accepted prefix’s maximum-diameter pair as anchor_time.

• postprocessing ({None, 'dbscan'}, optional) – Optional stop postprocessing method.

• eps (float, optional) – DBSCAN neighborhood distance. Required when postprocessing='dbscan'.

• **kwargs – Passed along to the column‐detection helper.

Returns:

Labels, or labels with aligned diameter-witness anchor_time.

Return type:

pd.Series or pd.DataFrame

nomad.stop_detection.sequential_algs.lachesis_labels_per_user(data, dt_max, delta_roam, dur_min=5, traj_cols=None, return_anchors=False, postprocessing=None, eps=None, n_jobs=1, print_progress=False, **kwargs)

Run lachesis_labels on each user separately and concatenate labels.

Raises if ‘user_id’ not in traj_cols or missing from data.

nomad.stop_detection.sequential_algs.lachesis_per_user(data, dt_max, delta_roam, dur_min=5, complete_output=False, passthrough_cols=None, postprocessing=None, eps=None, traj_cols=None, n_jobs=1, print_progress=False, passthrough_agg=None, **kwargs)

Run lachesis on each user separately, then concatenate results.

Parameters:

• data (pd.DataFrame or GeoDataFrame) – Input trajectory with spatial and temporal columns.

• dt_max (int) – Maximum allowed gap in minutes between consecutive pings in a stop.

• delta_roam (float) – Maximum spatial diameter for a stop.

• dur_min (int) – Minimum duration in minutes for a valid stop.

• complete_output (bool, default False) – If True, include additional summary statistics in output.

• passthrough_cols (list, optional) – Columns to retain (and summarize/propagate) per stop.

• passthrough_agg (dict, optional) – Aggregation functions for selected passthrough columns.

• postprocessing ({None, 'dbscan'}, optional) – Optional stop postprocessing method applied separately to each user.

• eps (float, optional) – DBSCAN neighborhood distance. Required when postprocessing='dbscan'.

• traj_cols (dict, optional) – Mapping for ‘x’, ‘y’, ‘longitude’, ‘latitude’, ‘timestamp’, or ‘datetime’.

• n_jobs (int, default 1) – Number of parallel jobs to use. 1 means sequential processing.

• print_progress (bool, default False) – Whether to show progress bar during processing.

• **kwargs – Passed along to column detection helper.

Returns:

Concatenated stop table with stops from all users.

Return type:

pd.DataFrame

Raises:

ValueError if 'user_id' not in traj_cols or missing from data. –