gaitmap.event_detection.RamppEventDetection#

class gaitmap.event_detection.RamppEventDetection(ic_search_region_ms: tuple[float, float] = (80, 50), min_vel_search_win_size_ms: float = 100, memory: Memory | None = None, enforce_consistency: bool = True, detect_only: tuple[str, ...] | None = None, input_stride_type: typing_extensions.Literal[segmented, ic] = 'segmented')[source]#

Find gait events in the IMU raw signal based on signal characteristics.

Note

This algorithm is only available via the gaitmap_mad package and distributed under a AGPL3 licence. To use it, you need to explicitly install the gaitmap_mad package. Learn more about that here.

RamppEventDetection uses signal processing approaches to find temporal gait events by searching for characteristic features in the foot-mounted sensor signals as described in Rampp et al. (2014) [1]. For more details refer to the Notes section.

Parameters:

ic_search_region_ms: The region to look for the initial contact in the acc_pa signal in ms given an ic candidate. According to [1], for the ic the algorithm first looks for a local minimum in the gyr_ml signal. The actual ic is then determined in the acc_pa signal in the ic_search_region_ms around that gyr_ml minimum. ic_search_region_ms[0] describes the start and ic_search_region_ms[1] the end of the region to check around the gyr_ml minimum. The values of ic_search_region_ms must be greater or equal than the sample time (1/sampling_rate_hz).
min_vel_search_win_size_ms: The size of the sliding window for finding the minimum gyroscope energy in ms.
memory: An optional joblib.Memory object that can be provided to cache the detection of all events.
enforce_consistency: An optional bool that can be set to False if you wish to disable postprocessing (see Notes section for more information).
detect_only: An optional tuple of strings that can be used to only detect a subset of events. By default, all events (“ic”, “tc”, “min_vel”) are detected. If min_vel is not detected, the min_vel_event_list_ output will not be available. If “ic” is not detected, the pre_ic will also not be available in the output.
input_stride_type: The stride list type that should be either “ic”, or “segmented”. “Segmented” means that the stride list that is provided by the Stride Segmentation method in this package. The start and the end of the stride are defined by the minimum in the gyr_ml signal right before the toe-off. “ic” means that the stride list is defined by the initial contact of the foot with the ground. Stride segmentation methods that focus on the acc, and reference stride lists from mocap data usually provide “ic” stride lists. Even in case of “ic” stride type, we will re-detect the initial contact event according to the definitions of the algorithm by considering a search region (10% stride time back, 20% stride time forward) around the initial contact provided as stride start.

Other Parameters:

data: The data passed to the detect method.
sampling_rate_hz: The sampling rate of the data
stride_list: A list of strides provided by a stride segmentation method. The stride list is expected to have no gaps between subsequent strides. That means for subsequent strides the end sample of one stride should be the start sample of the next stride.

Attributes:

min_vel_event_list_A stride list or dictionary with such values: The result of the detect method holding all temporal gait events and start / end of all strides. The stride borders for the stride_events are aligned with the min_vel samples. Hence, the start sample of each stride corresponds to the min_vel sample of that stride and the end sample corresponds to the min_vel sample of the subsequent stride. Strides for which no valid events could be found are removed. Additional strides might have been removed due to the conversion from segmented or ic to min_vel strides. The ‘s_id’ index is selected according to which segmented stride the pre-ic belongs to.
annotated_original_event_list_A stride list or dictionary with such values: The result of the detect method holding all temporal gait events and start / end of all strides. This version of the results has the same stride borders than the input stride_list and has additional columns for all the detected events. Strides for which no valid events could be found are removed.
segmented_event_list_A stride list or dictionary with such values: Deprecated, use annotated_original_event_list_ instead.

Notes

Rampp et al. implemented the detection of three gait events from foot-mounted sensor data:

terminal contact (tc), originally called toe-off (TO) in the paper [1]:: At tc the movement of the ankle joint changes from a plantar flexion to a dorsal extension in the sagittal plane. This change results in a zero crossing of the gyr_ml signal. Also refer to the image below.
initial contact (ic), originally called heel strike (HS) in the paper [1]:: At ic the foot decelerates rapidly when the foot hits the ground. For the detection of ic only the signal between the absolute maximum and the end of the first half of the gyr_ml signal is considered in the case of “segmented” input stride type whereas the window between [few samples before stride start,.2 of stance phase] is considered in case of “ic” input stride type. Within this segment, ic is found by searching for the minimum between the point of the steepest negative slope and the point of the steepest positive slope in the following signal. After that the acc_pa signal is searched for a maximum in the area before and after the described minimum in the gyr_ml signal. In the original implementation of the paper, this was actually a minimum due to flipped sensor coordinate axes. The default search window is set to 80 ms before and 50 ms after the minimum. The search window borders can be adjusted via the ic_search_region_ms parameter. Also refer to the image below.
minimal velocity (min_vel_), originally called mid stance (MS) in the paper [1]:: At min_vel the foot has the lowest velocity. It is defined to be the middle of the window with the lowest energy in all axes of the gyr signal. The default window size is set to 100 ms with 50 % overlap. The window size can be adjusted via the min_vel_search_win_size_ms parameter. Also refer to the image below.

The detect method provides a stride list min_vel_event_list with the gait events mentioned above and additionally start and end of each stride, which are aligned to the min_vel samples. The start sample of each stride corresponds to the min_vel sample of that stride and the end sample corresponds to the min_vel sample of the subsequent stride. Furthermore, the min_vel_event_list list provides the pre_ic which is the ic event of the previous stride in the stride list.

The RamppEventDetection includes a consistency check that is enabled by default. The gait events within one stride provided by the stride_list must occur in the expected order. For example, in case of “segmented” input stride type, the expected order is [“tc”, “ic”, “min_vel”] whereas the expected order for “ic” input stride type is [“ic”, “min_vel”, “tc”]. Any stride where the gait events are detected in a different order or are not detected at all is dropped! For more infos on this see enforce_stride_list_consistency. If you wish to disable this consistency check, set enforce_consistency to False. In this case, the attribute min_vel_event_list_ will not be set, but you can use annotated_original_event_list_ to get all detected events for the exact stride list that was used as input. Note, that this list might contain NaN for some events.

For the “ic” input stride type, it might happen that the detected ic is actually detected slightly before the original start of the stride. This is because the algorithm looks for the ic in a search region that starts before the actual stride. This is not problematic, as we do not consider the original start/end values for the rest of the processing, but might be supprising at first glance.

Furthermore, during the conversion from the stride list to the “min_vel” stride list, breaks in continuous gait sequences ( with continuous subsequent strides according to the stride_list) are detected and the first (segmented) stride of each sequence is dropped. This is required due to the shift of stride borders between the stride_list and the min_vel_event_list. Thus, the first segmented stride of a continuous sequence only provides a pre_ic and a min_vel sample for the first stride in the min_vel_event_list. Therefore, the min_vel_event_list list has one stride less per gait sequence than the stride_list.

Further information regarding the coordinate system can be found here and regarding the different types of strides can be found here.

The image below gives an overview about the events and where they occur in the signal.

[1] (1,2,3,4,5)

Rampp, A., Barth, J., Schülein, S., Gaßmann, K. G., Klucken, J., & Eskofier, B. M. (2014). Inertial sensor-based stride parameter calculation from gait sequences in geriatric patients. IEEE transactions on biomedical engineering, 62(4), 1089-1097.. https://doi.org/10.1109/TBME.2014.2368211

Examples

Get gait events from single sensor signal

>>> event_detection = RamppEventDetection()
>>> event_detection.detect(data=data, stride_list=stride_list, sampling_rate_hz=204.8)
>>> event_detection.min_vel_event_list_
       start     end      ic      tc  min_vel  pre_ic
s_id
0      519.0   710.0   651.0   584.0    519.0   498.0
1      710.0   935.0   839.0   802.0    710.0   651.0
2      935.0  1183.0  1089.0  1023.0    935.0   839.0
...

Methods

`clone`()	Create a new instance of the class with all parameters copied over.
`detect`(data, stride_list, *, sampling_rate_hz)	Find gait events in data within strides provided by stride_list.
`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__(ic_search_region_ms: tuple[float, float] = (80, 50), min_vel_search_win_size_ms: float = 100, memory: Memory | None = None, enforce_consistency: bool = True, detect_only: tuple[str, ...] | None = None, input_stride_type: typing_extensions.Literal[segmented, ic] = 'segmented')[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], stride_list: DataFrame | dict[Union[collections.abc.Hashable, str], pandas.core.frame.DataFrame], *, sampling_rate_hz: float) → Self[source]#

Find gait events in data within strides provided by stride_list.

Parameters:

data: The data set holding the imu raw data
stride_list: A list of strides provided by a stride segmentation method
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_json method 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.

set_params(**params: Any) → Self[source]#

Set the parameters of this Algorithm.

To set parameters of nested objects use nested_object_name__para_name=.

to_json() → str[source]#

Export the current object parameters as json.

For details have a look at the this example.

You can use the from_json method of any gaitmap algorithm to load the object again.

Warning

This will only export the Parameters of the instance, but not any results!

Examples using `gaitmap.event_detection.RamppEventDetection`#

MaD DiGait Pipeline

Herzer event detection

Rampp event detection

Advanced Kalman Filter Usage

gaitmap.event_detection.RamppEventDetection#

Examples using gaitmap.event_detection.RamppEventDetection#

Examples using `gaitmap.event_detection.RamppEventDetection`#