GsdAdaptiveIonescu#

class mobgap.gait_sequences.GsdAdaptiveIonescu( *, min_n_steps: int = 5, active_signal_fallback_threshold: float = 1.4709975, max_gap_s: float = 3.5, min_step_margin_s: float = 1.5, padding: float = 0.75, )[source]#

Implementation of the GSD algorithm by Paraschiv-Ionescu et al. (2019) [1, 2]_ with adaptive threshold.

The algorithm was developed and validated using data recorded in patients with impaired mobility (Parkinson’s disease, multiple sclerosis, hip fracture, post-stroke and cerebral palsy).

The algorithm detects the gait sequences based on identified steps. In order to enhance the step-related features (peaks in acceleration signal), the “active” periods potentially corresponding to locomotion are roughly detected and the statistical distribution of the amplitude of the peaks in these active periods is used to derive an adaptive (data-driven) threshold for detection of step-related peaks. Consecutive steps are associated into gait sequences [1] [2].

This is based on the implementation published as part of the mobilised project [3]. However, this implementation deviates from the original implementation in some places. For details, see the notes section.

Note

Compared to other GSD algorithms, this algorithm only works on the Acc norm and hence, can be used with

out knowing the previous alignment of the sensor. The algorithm therefore allows to pass data in either the body or the sensor frame.

Parameters:

active_signal_fallback_threshold: An upper threshold applied to the filtered signal. Minima and maxima beyond this threshold are considered as detected steps.
min_n_steps: The minimum number of steps allowed in a gait sequence (walking bout). Only walking bouts with equal or more detected steps are considered for further processing.
padding: A float multiplied by the mean of the step times to pad the start and end of the detected gait sequences. The gait sequences are filtered again by number of steps after this padding, removing any gs with too few steps.
max_gap_s: Maximum time (in seconds) between consecutive gait sequences. If a gap is smaller than max_gap_s, the two consecutive gait sequences are merged into one. This is applied after the gait sequences are detected.
min_step_margin_s: The minimum time margin (in seconds) between two consecutive initial contacts within a gait sequence. This is used when combining consecutive steps candidates into gait sequences. The actual threshold is calculated as the mean of the step times plus this parameter.

Other Parameters:

data: The raw IMU data in the body frame passed to the detect method.
sampling_rate_hz: The sampling rate of the IMU data in Hz passed to the detect method.

Attributes:

gs_list_: A dataframe specifying the detected gait sequences. The dataframe has a start and end column, specifying the start and end index of the gait sequence. The values are specified as samples after the start of the recording (i.e. the start of the data). A dataframe containing the start and end times of the detected gait sequences. Each row corresponds to a single gs.
filtered_signal_: The filtered acceleration norm used for step detection. This signal will be different depending on whether the adaptive threshold estimation was successful or not.
threshold_: The threshold used for step detection. This is either the adaptive threshold or the fallback threshold if no active periods were detected.
adaptive_threshold_success_: A boolean indicating whether the adaptive threshold estimation was successful.

Notes

Points of deviation from the original implementation and their reasons:

All parameters and thresholds are converted the units used in mobgap. Specifically, we use m/s^2 instead of g.
We introduced a try/except incase no active periods were detected.
We fixed a bug where the average step time during the “pulse train” identification was calculated using n + 1 steps.
In original implementation, stages for filtering by minimum number of steps are hardcoded as:
- min_n_steps>=4 after find_pulse_trains(MaxPeaks) and find_pulse_trains(MinPeaks)
- min_n_steps>=3 during the gs padding (NOTE: not implemented in this algorithm since it is redundant here)
- min_n_steps>=5 before merging gait sequences if time (in seconds) between consecutive gs is smaller than max_gap_s
This means that original implementation cannot be perfectly replicated with definition of min_n_steps
The original implementation used a check for overlapping gait sequences. We removed this step since it should not occur.

[1]

Paraschiv-Ionescu, A, Soltani A, and Aminian K. “Real-world speed estimation using single trunk IMU: methodological challenges for impaired gait patterns.” 2020 42nd Annual International Conference of the IEEE Engineering in Medicine & Biology Society (EMBC). IEEE, 2020.

[2]

Paraschiv-Ionescu, A, et al. “Locomotion and cadence detection using a single trunk-fixed accelerometer: validity for children with cerebral palsy in daily life-like conditions.” Journal of neuroengineering and rehabilitation 16.1 (2019): 1-11.

[3]

mobilise-d/Mobilise-D-TVS-Recommended-Algorithms

Methods

`clone`()	Create a new instance of the class with all parameters copied over.
`detect`(data, , sampling_rate_hz, *_)	Detect gait sequences in the passed data.
`get_params`([deep])	Get parameters for this algorithm.
`self_optimize`(data_sequences, ...)	Optimize the internal parameters of the algorithm.
`set_params`(**params)	Set the parameters of this Algorithm.

__init__( *, min_n_steps: int = 5, active_signal_fallback_threshold: float = 1.4709975, max_gap_s: float = 3.5, min_step_margin_s: float = 1.5, padding: float = 0.75, ) → None[source]#

clone() → Self[source]#

Create a new instance of the class with all parameters copied over.

This will create a new instance of the class itself and all nested objects

detect(

data: DataFrame,

*,

sampling_rate_hz: float,

**_: Unpack[dict[str, Any]],

) → Self[source]#

Detect gait sequences in the passed data.

Parameters:

data: The raw IMU data in the body frame.
sampling_rate_hz: The sampling rate of the IMU data in Hz.

Returns:

self: The instance of the class with the gs_list_ attribute set to the detected gait sequences.

get_params(deep: bool = True) → dict[str, Any][source]#

Get parameters for this algorithm.

Parameters:

deep: Only relevant if object contains nested algorithm objects. If this is the case and deep is True, the params of these nested objects are included in the output using a prefix like nested_object_name__ (Note the two “_” at the end)

Returns:

params: Parameter names mapped to their values.

self_optimize(

data_sequences: Iterable[DataFrame],

ref_gsd_list_per_sequence: Iterable[DataFrame],

*,

sampling_rate_hz: float | Iterable[float],

**kwargs: Unpack[dict[str, Any]],

) → Self[source]#

Optimize the internal parameters of the algorithm.

This is only relevant for algorithms that have a special internal optimization approach (like ML based algos).

Parameters:

data_sequences: A sequence/iterable/list of dataframes, each containing the raw IMU data of a single sensor. This could be individual trials or data from different participants. The optimization will be performed over all sequences combined.
ref_gsd_list_per_sequence: A sequence/iterable/list of gsd-list, each containing the reference gait sequences for the respective data sequence. They are used as ground-truth to validate the output of the algorithm during optimization.
sampling_rate_hz: The sampling rate of the IMU data in Hz. This can either be a single float, in case all sequences have the same sampling rate, or a sequence of floats, in case the sampling rate differs between the sequences.

Returns: