gaitmap.stride_segmentation.hmm.HmmStrideSegmentation

class gaitmap.stride_segmentation.hmm.HmmStrideSegmentation(model: ~gaitmap_mad.stride_segmentation.hmm._hmm_stride_segmentation.BaseSegmentationHmmT = cf(RothSegmentationHmm(algo_predict='viterbi', algo_train='baum-welch', data_columns=['raw__gyr_ml', 'gradient__gradient__gyr_ml'], feature_transform=RothHmmFeatureTransformer(axes=['gyr_ml'], features=['raw', 'gradient'], low_pass_filter=ButterworthFilter(cutoff_freq_hz=10, filter_type='lowpass', order=4), sampling_rate_feature_space_hz=51.2, standardization=True, window_size_s=0.2), initialization='labels', max_iterations=1, model=HiddenMarkovModel[name=segmentation_model](...), n_jobs=1, name='segmentation_model', stop_threshold=1e-09, stride_model=SimpleHmm(algo_train='baum-welch', architecture='left-right-strict', data_columns=['raw__gyr_ml', 'gradient__gradient__gyr_ml'], max_iterations=10, model=HiddenMarkovModel[name=stride_model-trained](...), n_gmm_components=6, n_jobs=1, n_states=20, name='stride_model', stop_threshold=1e-09, verbose=True), transition_model=SimpleHmm(algo_train='baum-welch', architecture='left-right-loose', data_columns=['raw__gyr_ml', 'gradient__gradient__gyr_ml'], max_iterations=10, model=HiddenMarkovModel[name=transition_model-trained](...), n_gmm_components=3, n_jobs=1, n_states=5, name='transition_model', stop_threshold=1e-09, verbose=True), verbose=True)), *, snap_to_min_win_ms: float | None = 100, snap_to_min_axis: str = 'gyr_ml')

Segment strides using a pre-trained Hidden Markov Model.

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 does not care about the implementation details of the HMM used. As long as it is a valid subclass of BaseSegmentationHmm, it can be used here. On top of the segmentation, this class implements a postprocessing step that snaps the minima in the raw signals and contains convenience methods that ensure that outputs conform to the expected gaitmap formats.

Note, that this class only supports prediction. To train your own HMM, use the self_optimize method on the model that you were planning to use here.

This is based on the work of Roth et al. 2021 [1] and the implementation is using done with pomegranate [2].

Parameters:

model

The HMM class need a valid pre-trained model to segment strides

snap_to_min_win_ms

The size of the window in seconds 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.

Other Parameters:

data

The data passed to the segment method.

sampling_rate_hz

The sampling rate of the data

Attributes:

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.

stride_list_A stride list or dictionary with such values

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

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 hidden state sequence.

hidden_state_sequence_List of length n_detected_strides or dictionary with such values

The cost value associated with each stride.

result_model_

The copy of the model used for the segmentation with all the result parameters attached.

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

[1]

Roth, N., Küderle, A., Ullrich, M. et al. Hidden Markov Model based stride segmentation on unsupervised free-living gait data in Parkinson`s disease patients. J NeuroEngineering Rehabil 18, 93 (2021). https://doi.org/10.1186/s12984-021-00883-7

[2]

J. Schreiber, “Pomegranate: Fast and flexible probabilistic modeling in python,” Journal of Machine Learning Research, vol. 18, no. 164, pp. 1-6, 2018.

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 predicting a hidden state sequence using a pre-trained Hidden Markov Model.
set_params(**params)	Set the parameters of this Algorithm.
to_json()	Export the current object parameters as json.

__init__(model: ~gaitmap_mad.stride_segmentation.hmm._hmm_stride_segmentation.BaseSegmentationHmmT = cf(RothSegmentationHmm(algo_predict='viterbi', algo_train='baum-welch', data_columns=['raw__gyr_ml', 'gradient__gradient__gyr_ml'], feature_transform=RothHmmFeatureTransformer(axes=['gyr_ml'], features=['raw', 'gradient'], low_pass_filter=ButterworthFilter(cutoff_freq_hz=10, filter_type='lowpass', order=4), sampling_rate_feature_space_hz=51.2, standardization=True, window_size_s=0.2), initialization='labels', max_iterations=1, model=HiddenMarkovModel[name=segmentation_model](...), n_jobs=1, name='segmentation_model', stop_threshold=1e-09, stride_model=SimpleHmm(algo_train='baum-welch', architecture='left-right-strict', data_columns=['raw__gyr_ml', 'gradient__gradient__gyr_ml'], max_iterations=10, model=HiddenMarkovModel[name=stride_model-trained](...), n_gmm_components=6, n_jobs=1, n_states=20, name='stride_model', stop_threshold=1e-09, verbose=True), transition_model=SimpleHmm(algo_train='baum-welch', architecture='left-right-loose', data_columns=['raw__gyr_ml', 'gradient__gradient__gyr_ml'], max_iterations=10, model=HiddenMarkovModel[name=transition_model-trained](...), n_gmm_components=3, n_jobs=1, n_states=5, name='transition_model', stop_threshold=1e-09, verbose=True), verbose=True)), *, snap_to_min_win_ms: float | None = 100, snap_to_min_axis: str = 'gyr_ml') → 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: DataFrame | dict[Union[collections.abc.Hashable, str], pandas.core.frame.DataFrame], sampling_rate_hz: float, **_) → Self

Find matches by predicting a hidden state sequence using a pre-trained Hidden Markov Model.

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 perform the required feature transformation`.

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.hmm.HmmStrideSegmentation

HMM stride segmentation - Prediction with pre-trained model

HMM stride segmentation - Prediction with pre-trained model

SegmentationModel Training

SegmentationModel Training