Skip to content

Support existing location IDs and custom algorithms in Lachesis postprocessing #430

Description

@paco-barreras

Why

The Lachesis changes in #403 intentionally keep the public API limited to postprocessing=None and postprocessing="dbscan". Supporting location IDs already present on the input, or arbitrary location and stop-detection algorithms, requires additional callable contracts and parameter dictionaries. Adding those options now would obscure the simple DBSCAN workflow.

Proposed behavior

Add a postprocessing option for single-user pings that already contain the configured location_id column. This path should skip location detection and call _merge_stops_from_labels with grid_based, using Lachesis's dt_max as time_thresh, min_cluster_size=1, and dur_min=0.

Also design an explicitly advanced custom option without changing the simple default API:

  • A custom location detector receives a throw-away, single-user stop table plus traj_cols and a dedicated arguments dictionary. It returns exactly one label per stop, aligned by row. Missing or -1 labels must follow the same no-discard rule as DBSCAN noise.
  • A custom merge-from-labels algorithm receives single-user pings containing the configured location column, traj_cols, time_thresh, and a dedicated arguments dictionary. It returns a stop table with canonical cluster labels numbered from 0 to K.
  • Column-name mappings remain in traj_cols/column keyword arguments. Algorithm parameters must not be mixed into those keyword arguments.
  • The public method requires postprocessing="custom" before accepting either callable. Supplying a callable with another method raises.
  • Multi-user wrappers delegate the complete postprocessing operation to the single-user method and concatenate the results.
  • Intermediate stop tables, detected location IDs, and mapping columns are not included in the returned table unless they were part of the user's requested output.

Acceptance criteria

  • An existing mapped location_id can drive Lachesis postprocessing without running DBSCAN.
  • The built-in existing-location path uses _merge_stops_from_labels with grid_based and the documented fixed arguments.
  • The two custom callable contracts validate output length/type and preserve all noise observations according to NOMAD's conventions.
  • Default and DBSCAN calls retain their current short signatures.
  • Tests cover custom column mappings, empty inputs, one user, multiple users through the wrapper, and invalid method/callable combinations.

This pull request includes code written with the assistance of AI. The code has not yet been reviewed by a human (remove this disclosure after human review).

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions