LrcBenMansour#

class mobgap.laterality.LrcBenMansour( smoothing_filter: BaseFilter = cf(ButterworthFilter(cutoff_freq_hz=1, filter_type='lowpass', order=4, zero_phase=True)), )[source]#

LrcBenMansour algorithm for laterality detection of initial contacts.

The BenMansour algorithm [1] uses the derivative of the mediolateral acceleration in order to classify left/right initial contacts.

The first step is to filter the signal using a low-pass fourth-order zero-lag Butterworth filter at 1 Hz.

Second, the derivative of the filtered signal is obtained. This should be approximately sinusoidal. An initial contact during a positive derivative is taken as a left initial contact, a negative derivative as a right initial contact.

Data Requirements: Uses accelerometer data only. Requires body-frame mediolateral acceleration acc_ml. Gyroscope data is not used.

Parameters:

smoothing_filter: The filter to use for smoothing the signal. The filter should be a low-pass filter to obtain a low frequency sinusoidal signal from the mediolateral acceleration.

Other Parameters:

data: The raw IMU data passed to the detect method.
ic_list: The list of initial contacts passed to the detect method.
sampling_rate_hz: The sampling rate of the IMU data in Hz passed to the detect method.

Attributes:

ic_lr_list_: The predicted left and right foot initial contacts. The dataframe is identical to the input ic_list, but with the lr column added. The lr column specifies if the respective IC belongs to the left or the right foot.
smoothed_data_: The smoothed mediolateral acceleration used for the laterality detection. This might be helpful for debugging or further analysis.

Notes

In the edge case of data == 0, the right side is assumed.

[1]

Ben Mansour, K., Rezzoug, N., & Gorce, P. (2015). Foot side detection from lower lumbar spine acceleration. Gait & Posture, 42(3), 386-389, available at: https://doi.org/10.1016/j.gaitpost.2015.05.021

Methods

`clone`()	Create a new instance of the class with all parameters copied over.
`get_params`([deep])	Get parameters for this algorithm.
`predict`(data, ic_list, , sampling_rate_hz, *_)	Assign a left/right label to each initial contact in the passed data..
`self_optimize`(data_sequences, ...)	Optimize the internal parameters of the algorithm.
`set_params`(**params)	Set the parameters of this Algorithm.

__init__( smoothing_filter: BaseFilter = cf(ButterworthFilter(cutoff_freq_hz=1, filter_type='lowpass', order=4, zero_phase=True)), ) → None[source]#

clone() → Self#

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

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

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.

predict(

data: DataFrame,

ic_list: DataFrame,

*,

sampling_rate_hz: float,

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

) → Self[source]#

Assign a left/right label to each initial contact in the passed data..

Parameters:

data: The raw IMU of a single sensor. This should usually represent a single gait sequence or walking bout.
ic_list: The list of initial contacts within the data. The ic_list is expected to have a column ic with the indices of the detected initial contacts relative to the start of the passed data.
sampling_rate_hz: The sampling rate of the IMU data in Hz.

Returns:

self: The instance of the class with the ic_lr_list_ attribute set to the passed ICs with a new left/right column.

self_optimize(

data_sequences: Iterable[DataFrame],

ic_list_per_sequence: Iterable[DataFrame],

ref_ic_lr_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. Each sequence should usually contain the data of a single gait sequence/walking bout. The optimization will be performed over all sequences combined.
ic_list_per_sequence: A sequence/iterable/list of gsd-list, each containing the list of detected ics for the respective data sequence. The ic_list is expected to have a column ic with the indices of the detected initial contacts relative to the start of the each passed data sequence.
ref_ic_lr_list_per_sequence: A sequence/iterable/list of reference ic_lr_list, each containing the reference left/right initial contacts. They are expected to have the exact same structure as the ic_lists passed as ic_list_per_sequence, but should contain the ground-truth left/right labels in a additional column called lr_label. 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: