gaitmap.stride_segmentation.ConstrainedBarthDtw

class gaitmap.stride_segmentation.ConstrainedBarthDtw(template: BaseDtwTemplate | dict[Union[collections.abc.Hashable, str], gaitmap_mad.stride_segmentation.dtw._dtw_templates.templates.BaseDtwTemplate] | None = cf(BarthOriginalTemplate(scaling=FixedScaler(offset=0, scale=500.0), use_cols=None)), resample_template: bool = True, find_matches_method: typing_extensions.Literal[min_under_thres, find_peaks] = 'find_peaks', max_cost: float | None = 4, min_match_length_s: float | None = 0.6, max_match_length_s: float | None = 3.0, max_template_stretch_ms: float | None = 120, max_signal_stretch_ms: float | None = 120, snap_to_min_win_ms: float | None = 300, snap_to_min_axis: str | None = 'gyr_ml', conflict_resolution: bool = True, memory: Memory | None = None)

A version of BarthDtw that uses local warping constraints by default.

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.

This method is identical to BarthDtw, but uses local constraints for the template and the signal by default. This help to prevent issues, where only the region from TC to IC is mapped as the entire stride. For more information on this see the example.

This exists as a separate class, so that users are aware, they are using a different method that might impact their results.

This method is based on [1] and the modification of the constrained warping path is inspired by [2].

Parameters:

template

The template used for matching. The required data type and shape depends on the use case. For more details see BaseDtw. By default, the BarthOriginalTemplate is used with default settings.

resample_template

If True the template will be resampled to match the sampling rate of the data. This requires a valid value for template.sampling_rate_hz value.

max_cost

The maximal allowed cost to find potential match in the cost function. Note that the cost is roughly calculated as: sqrt(|template - data/template.scaling|). Its usage depends on the exact find_matches_method used. Refer to the specific function to learn more about this. The default value should work well with healthy gait (with the default template).

min_match_length_s

The minimal length of a sequence in seconds to be considered a stride. Matches that result in shorter sequences, will be ignored. In general, this exclusion is performed as a post-processing step after the matching. If “find_peaks” is selected as find_matches_method, the parameter is additionally used in the detection of matches directly.

max_match_length_s

The maximal length of a sequence in seconds to be considered a stride. Matches that result in longer sequences will be ignored. This exclusion is performed as a post-processing step after the matching.

max_template_stretch_ms

A local warping constraint for the DTW. It describes how many ms of the template are allowed to be mapped to just a single datapoint of the signal. The ms value will internally be converted to samples using the template sampling-rate (or the signal sampling-rate, if resample_template=True). If no template sampling-rate is provided, this constrain can not be used.

max_signal_stretch_ms

A local warping constraint for the DTW. It describes how many ms of the signal are allowed to be mapped to just a single datapoint of the template. The ms value will internally be converted to samples using the data sampling-rate

find_matches_method

Select the method used to find matches in the cost function.

• “min_under_thres”

  Matches the implementation used in the paper [1] to detect strides in foot mounted IMUs. In this case find_matches_min_under_threshold will be used as method.

• “find_peaks”

  Uses find_peaks with additional constraints to find stride candidates. In this case find_matches_find_peaks will be used as method.

snap_to_min_win_ms

The size of the window in ms used to search local minima during the post processing of the stride borders. If this is set to None, this postprocessing step is skipped. Refer to the Notes section for more details.

snap_to_min_axis

The axis of the data used to search for minima during the processing of the stride borders. The axis label must match one of the axis label in the data. Refer to the Notes section for more details.

conflict_resolution

This enables a set of checks that handle cases where stride matches overlap with other strides. The following steps will be performed:

• If multiple matches have the same start point, only the match with the lowest cost will be kept.

memory

An optional joblib.Memory object that can be provided to cache the creation of cost matrizes and the peak detection.

Other Parameters:

data

The data passed to the segment method.

sampling_rate_hz

The sampling rate of the data

Attributes:

stride_list_A stride list or dictionary with such values

Return start and end of each match as pd.DataFrame.

matches_start_end_2D array of shape (n_detected_strides x 2) or dictionary with such values

The start (column 1) and end (column 2) of each detected stride.

costs_List of length n_detected_strides or dictionary with such values

The cost value associated with each stride.

acc_cost_mat_array with the shapes (length_template x length_data) or dictionary with such values

The accumulated cost matrix of the DTW. The last row represents the cost function.

cost_function_1D array with the same length as the data or dictionary with such values

Cost function extracted from the accumulated cost matrix.

paths_list of arrays with length n_detected_strides or dictionary with such values

The full path through the cost matrix of each detected stride.

matches_start_end_original_2D array of shape (n_detected_strides x 2) or dictionary with such values

Return the starts and end directly from the paths.

See also

gaitmap.stride_segmentation.BarthDtw

For all details on the method

Notes

[1] (1,2)

Barth, J., Oberndorfer, C., Kugler, P., Schuldhaus, D., Winkler, J., Klucken, J., & Eskofier, B. (2013). Subsequence dynamic time warping as a method for robust step segmentation using gyroscope signals of daily life activities. Proceedings of the Annual International Conference of the IEEE Engineering in Medicine and Biology Society, EMBS, 6744-6747. https://doi.org/10.1109/EMBC.2013.6611104

[2]

M. Müller, Fundamentals of Music Processing - Using Python and Jupyter Notebooks, 2nd ed. Springer Verlag, 2021.

Methods

clone()	Create a new instance of the class with all parameters copied over.
from_json(json_str)	Import an gaitmap object from its json representation.
get_params([deep])	Get parameters for this algorithm.
segment(data, sampling_rate_hz, **_)	Find matches by warping the provided template to the data.
set_params(**params)	Set the parameters of this Algorithm.
to_json()	Export the current object parameters as json.

__init__(template: BaseDtwTemplate | dict[Union[collections.abc.Hashable, str], gaitmap_mad.stride_segmentation.dtw._dtw_templates.templates.BaseDtwTemplate] | None = cf(BarthOriginalTemplate(scaling=FixedScaler(offset=0, scale=500.0), use_cols=None)), resample_template: bool = True, find_matches_method: typing_extensions.Literal[min_under_thres, find_peaks] = 'find_peaks', max_cost: float | None = 4, min_match_length_s: float | None = 0.6, max_match_length_s: float | None = 3.0, max_template_stretch_ms: float | None = 120, max_signal_stretch_ms: float | None = 120, snap_to_min_win_ms: float | None = 300, snap_to_min_axis: str | None = 'gyr_ml', conflict_resolution: bool = True, memory: Memory | None = None) → None

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

classmethod from_json(json_str: str) → Self

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]

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.

segment(data: ndarray | DataFrame | dict[Union[collections.abc.Hashable, str], pandas.core.frame.DataFrame], sampling_rate_hz: float, **_) → Self

Find matches by warping the provided template to the data.

Parameters:

dataarray, single-sensor dataframe, or multi-sensor dataset

The input data. For details on the required datatypes review the class docstring.

sampling_rate_hz

The sampling rate of the data signal. This will be used to convert all parameters provided in seconds into a number of samples and it will be used to resample the template if resample_template is True.

Returns:

self

The class instance with all result attributes populated

set_params(**params: Any) → Self

Set the parameters of this Algorithm.

To set parameters of nested objects use nested_object_name__para_name=.

to_json() → str

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.stride_segmentation.ConstrainedBarthDtw

Constrained BarthDtw stride segmentation

Constrained BarthDtw stride segmentation