gaitmap.gait_detection.UllrichGaitSequenceDetection#
- class gaitmap.gait_detection.UllrichGaitSequenceDetection(sensor_channel_config: str = 'gyr_ml', peak_prominence: float = 17.0, window_size_s: float = 10, active_signal_threshold: float | None = None, locomotion_band: tuple[float, float] = (0.5, 3), harmonic_tolerance_hz: float = 0.3, merge_gait_sequences_from_sensors: bool = False, additional_margin_s: float | None = None)[source]#
Find gait events in the IMU raw signal based on signal characteristics.
Note
This algorithm is only available via the
gaitmap_madpackage and distributed under a AGPL3 licence. To use it, you need to explicitly install thegaitmap_madpackage. Learn more about that here.UllrichGaitSequenceDetection uses signal processing approaches to find gait sequences by searching for characteristic features in the power spectral density of the imu raw signals as described in Ullrich et al. ( 2020) [1]. For more details refer to the
Notessection.- Parameters:
- sensor_channel_config
The sensor channel or sensor that should be used for the gait sequence detection. Must be a str. If the algorithm should be applied to a single sensor axis the string must be one of the entries in either
BF_ACCorBF_GYR. In order to perform the analysis on the norm of the acc / the gyr signal, you need to pass “acc” or “gyr”. Default value isgyr_mlas by the publication this showed the best results.- peak_prominence
The threshold for the peak prominence that each harmonics peak must provide. This relates to the
peak_prominenceprovided bypeak_prominences. The frequency spectrum of the sensor signal will be investigated at harmonics of the dominant frequency regarding peaks that have apeak_prominencehigher than the specified value. The lower the value, the more inclusive is the algorithm, meaning that the requirements of a signal to be detected as gait are lower. The higher the value the more specific is the algorithm to include a signal as gait.- window_size_s
The algorithm works on a window basis. The
window_size_sspecified the length of this window in seconds. Default value is 10 s. The windowing in this algorithm works with a 50% overlap of subsequent windows.- active_signal_threshold
Before the actual FFT analysis, the algorithm compares the mean signal norm within each window against the
active_signal_thresholdin order to reject windows with rest right from the beginning. Default value is according to the publication is 50 deg / s forsensor_channel_configsettings including the gyroscope or 0.2 * 9.81 m/s^2 forsensor_channel_configsettings including the accelerometer. For higher thresholds the signal in the window must show more activity to be passed to the frequency analysis.- locomotion_band
The
locomotion_banddefines the region within the frequency spectrum of each window to identify the dominant frequency. According to literature [2] typical signals measured during locomotion have their dominant frequency within a locomotion band of 0.5 - 3 Hz. This is set as the default value. For very slow or very fast gait these borders might have to be adapted. Please note that the signal to be analyzed is going to be lowpass filtered with cut-off frequency of 6 Hz. Therefore, values for the upper limit of the locomotion band higher than 6 Hz might not be reasonable. This algorithm expects the dominant frequency of the gait signal to be between 0.5 and 1.5 Hz.- harmonic_tolerance_hz
After identifying the dominant frequency of a window, the algorithm checks for peaks in the frequency spectrum that should appear at harmonics of the dominant frequency. The
harmonic_tolerance_hzsets the tolerance margin for the harmonics. Default value is 0.3 Hz. This means if a harmonic peak is detected up to 0.3 Hz above or 0.3 Hz below the actual harmonic it is still accepted.- merge_gait_sequences_from_sensors
The algorithm processes the data from each sensor individually. Therefore, different gait sequences for example for left and right foot, may occur. If
merge_gait_sequences_from_sensorsis set to True, the gait sequences from all sensors will be merged by applying a logicalORto the single results. This is only allowed for synchronized sensor data.- additional_margin_s
Additional seconds to be added around the detected gait sequences a symmetrical margin window. Resulting overlaps will be handeled by
gaitmap.utils.array_handling.merge_intervalssuch that overlapping gait sequences after adding the margin will be merged. If the margins exceed the limits of the signals, they intervals will be clipped to [0, length(signal)].
- Other Parameters:
- data
The data passed to the
detectmethod.- sampling_rate_hz
The sampling rate of the data
- Attributes:
- gait_sequences_
The result of the
detectmethod holding all gait sequences with their start and end samples. Formatted as pandas DataFrame.start_1D array or dictionary with such valuesJust the start values of all gait sequences.
end_1D array or dictionary with such valuesJust the end values of all gait sequences.
Notes
The underlying algorithm works under the assumption that the IMU gait signal shows a characteristic pattern of harmonics when looking at the power spectral density. This is in contrast to cyclic non-gait signals, where there is usually only one dominant frequency present.
[1]M. Ullrich, A. Küderle, J. Hannink, S. Del Din, H. Gassner, F. Marxreiter, J. Klucken, B.M. Eskofier, F. Kluge, Detection of Gait From Continuous Inertial Sensor Data Using Harmonic Frequencies, IEEE Journal of Biomedical and Health Informatics. (2020) 1-1. https://doi.org/10.1109/JBHI.2020.2975361.
[2]Iluz, T., Gazit, E., Herman, T. et al. Automated detection of missteps during community ambulation in patients with Parkinson`s disease: a new approach for quantifying fall risk in the community setting. J NeuroEngineering Rehabil 11, 48 (2014). https://doi.org/10.1186/1743-0003-11-48
Examples
Find sequences of gait in sensor signal
>>> gsd = UllrichGaitSequenceDetection() >>> gsd = gsd.detect(data, 204.8) >>> gsd.gait_sequences_ gs_id start end 0 0 1024 3072 1 1 4096 8192 ...
Methods
clone()Create a new instance of the class with all parameters copied over.
detect(data, sampling_rate_hz)Find gait sequences in data.
from_json(json_str)Import an gaitmap object from its json representation.
get_params([deep])Get parameters for this algorithm.
set_params(**params)Set the parameters of this Algorithm.
to_json()Export the current object parameters as json.
- __init__(sensor_channel_config: str = 'gyr_ml', peak_prominence: float = 17.0, window_size_s: float = 10, active_signal_threshold: float | None = None, locomotion_band: tuple[float, float] = (0.5, 3), harmonic_tolerance_hz: float = 0.3, merge_gait_sequences_from_sensors: bool = False, additional_margin_s: float | None = None) 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 | dict[Union[collections.abc.Hashable, str], pandas.core.frame.DataFrame], sampling_rate_hz: float) Self[source]#
Find gait sequences in data.
- Parameters:
- data
The data set holding the imu raw data
- sampling_rate_hz
The sampling rate of the data
- Returns:
- self
The class instance with all result attributes populated
- classmethod from_json(json_str: str) Self[source]#
Import an gaitmap object from its json representation.
For details have a look at the this example.
You can use the
to_jsonmethod of a class to export it as a compatible json string.- Parameters:
- json_str
json formatted string
- 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.
