gaitmap.stride_segmentation.BarthDtw#

class gaitmap.stride_segmentation.BarthDtw(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.0, min_match_length_s: float | None = 0.6, max_match_length_s: float | None = 3.0, max_template_stretch_ms: float | None = None, max_signal_stretch_ms: float | None = None, snap_to_min_win_ms: float | None = 300, snap_to_min_axis: str | None = 'gyr_ml', conflict_resolution: bool = True, memory: Memory | None = None)[source]#

Segment strides using a single stride template and Dynamic Time Warping.

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.

BarthDtw uses a manually created template of an IMU stride to find multiple occurrences of similar signals in a continuous data stream. The method is not limited to a single sensor-axis or sensor, but can use any number of dimensions of the provided input signal simultaneously. For more details refer to the Notes section.

This method was first published in [1].

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.ConstrainedBarthDtw: Version with defaults for the local constrains
gaitmap.stride_segmentation.BaseDtw: Dtw base class with more details on the method

Notes

Post Processing: This algorithm uses an optional post-processing step that “snaps” the stride borders to the closest local minimum in the raw data. This helps to align the end of one stride with the start of the next stride (which is a requirement for certain event detection algorithms) and resolve small overlaps between neighboring strides. However, this assumes that the start and the end of each match is marked by a clear minimum in one axis of the raw data. If you are using a template that does not assume this, this post-processing step might lead to unexpected results and you should deactivate it in such a case by setting snap_to_min_win_ms to None. Note, that snapping only works if both the data and the template are based on pandas DataFrames.
Template: The BarthOriginalTemplate covers a gait signal starting from the minimum in gyr_ml before a terminal contact until the same minimum of the next gait cycle. It is advisable that any custom template starts and ends with a clear peak as well, as this improves the matching performance in the border regions.
Initiation and Termination Strides: Be aware that initiation and termination strides can usually not be matched with the same template as regular strides. However, depending on the gait of the subject and the chosen max_cost parameters it might however happen that some of them are matched on occasion. If this is an issue for your analysis, you should try to develop further post-processing steps to exclude these strides as part of your pipeline.
Differences to implementation by Barth et al [1]: In the original paper, the distance matrix for each of the selected axis was calculated individually and then summed up to create the final matrix. The resulting distance function is therefore the Manhatten distance between two samples. This implementation calculates only a single distance matrix using the Euclidian distance. The Euclidian distance is always a little smaller than the Manhatten distance, but captures the same similarity.

[1] (1,2,3)

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

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.0, min_match_length_s: float | None = 0.6, max_match_length_s: float | None = 3.0, max_template_stretch_ms: float | None = None, max_signal_stretch_ms: float | None = None, 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[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

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.

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

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[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.stride_segmentation.BarthDtw`#

MaD DiGait Pipeline

BarthDtw stride segmentation

Constrained BarthDtw stride segmentation

Stride segmentation with Regions of Interest

BarthDtw stride segmentation with Custom Template

Grid Search optimal Algorithm Parameter

Optimizable Pipelines

Cross Validation

GridSearchCV

Running multiple pipelines in parallel

Export Algorithms to JSON

Caching algorithm outputs

gaitmap.stride_segmentation.BarthDtw#

Examples using gaitmap.stride_segmentation.BarthDtw#

Examples using `gaitmap.stride_segmentation.BarthDtw`#