find_gait

The find_gait command-line tool is the second executable stage of the pipeline. It reads bilateral activity windows from PostgreSQL, retrieves raw inertial data from InfluxDB, detects effective movement in each leg, derives bilateral gait episodes, enriches those episodes with GPS-based metrics, and optionally stores the results in PostgreSQL.

Purpose

This command performs the movement and gait detection stage of the project:

  1. retrieve candidate bilateral windows from activity_all

  2. expand those windows into one row per leg

  3. fetch raw inertial signals for each leg from InfluxDB

  4. resample the inertial series to a fixed temporal grid

  5. detect effective_movement from spectral and temporal criteria

  6. intersect left and right effective movement to derive effective_gait

  7. enrich gait intervals with GPS-derived metrics

  8. optionally store effective_movement and effective_gait

Input modes

The command supports two retrieval modes.

Explicit ID mode

Provide one or more activity_all IDs with -i / --ids:

python -m ms_monitoring.find_gait \
  -c config.yaml \
  -i "1,5,10-15" \
  --save 1 \
  -v 2

Recent-hours mode

If --ids is omitted, the command retrieves candidate windows from the last N hours:

python -m ms_monitoring.find_gait \
  -c config.yaml \
  --hours-back 25 \
  --save 0 \
  -v 1

Arguments

The tool accepts the following arguments:

  • -c, --config: path to config.yaml (required)

  • -i, --ids: range/list of activity_all IDs

  • -l, --lang: interface language (es or en)

  • -o, --output: optional XLSX export of raw sensor data

  • -v, --verbose: verbosity level

  • --head-rows: number of preview rows to print

  • --hours-back: fallback time window when --ids is omitted

  • --save: whether to persist results in PostgreSQL (1) or run in dry mode (0)

High-level execution flow

The command performs the following steps:

  1. initialize translations

  2. create a MovementDetector

  3. retrieve bilateral candidate windows from activity_all

  4. expand them into one row per leg

  5. detect per-leg effective_movement

  6. optionally store effective_movement

  7. detect bilateral effective_gait

  8. validate/enrich gait intervals with GPS-derived metrics

  9. optionally store effective_gait

Detection details

The inertial stage is based on:

  • raw accelerometer and gyroscope signals

  • fixed-rate resampling before analysis

  • magnitude computation for acceleration and gyroscope

  • Welch spectral power inside a configurable frequency band

  • temporal continuity criteria

  • merging of nearby valid windows

  • minimum-duration filtering

The gait stage is based on:

  • temporal overlap between left and right effective-movement intervals

  • minimum gait-duration filtering

  • optional GPS enrichment using distance, elapsed time, average speed, and a boolean validation flag

GPS enrichment

Each detected gait interval may be enriched with the following fields:

  • gps_points

  • gps_distance_m

  • gps_elapsed_sec

  • gps_avg_speed_m_s

  • gps_validated

These values are derived from the GPS trace associated with the same participant and time interval.

Dry-run mode

When --save 0 is used:

  • the full detection pipeline is still executed

  • results are printed for inspection

  • no rows are written to PostgreSQL

Typical outputs

The command may generate:

  • per-leg rows in effective_movement

  • bilateral rows in effective_gait enriched with GPS metrics

Implementation notes

  • timestamps are normalized consistently before querying the databases

  • inertial data is resampled before windowing to mitigate packet loss and improve temporal alignment

  • the final partial inertial window can be kept when it is large enough

  • GPS enrichment is part of the final pipeline before storing effective_gait

API reference

class ms_monitoring.find_gait.VAction(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)[source]

Bases: Action

Custom argparse Action to handle cumulative verbosity (-v).

ms_monitoring.find_gait._default_last_hours_window(hours_back: int) → tuple[str, str][source]

Return ISO timestamps (UTC) for the last hours_back hours window.

Args: hours_back: Number of hours to look back from now.

Returns: tuple[str, str]: (fstart, fend) as ISO strings with “Z” suffix.

ms_monitoring.find_gait.main() → None[source]
ms_monitoring.find_gait.parse_range_list(rango_str: str) → list[int][source]

Convert a string like ‘1-271’ or ‘1,5,10-15’ into a list of integers.

Args: rango_str: Range/list specification.

Returns: list[int]: Sorted list of IDs.