gaitmap.stride_segmentation.hmm.RothSegmentationHmm#

class gaitmap.stride_segmentation.hmm.RothSegmentationHmm(stride_model: SimpleHmm = cf(SimpleHmm(algo_train='baum-welch', architecture='left-right-strict', data_columns=None, max_iterations=10, model=None, n_gmm_components=6, n_jobs=1, n_states=20, name='stride_model', stop_threshold=1e-09, verbose=True)), transition_model: SimpleHmm = cf(SimpleHmm(algo_train='baum-welch', architecture='left-right-loose', data_columns=None, max_iterations=10, model=None, n_gmm_components=3, n_jobs=1, n_states=5, name='transition_model', stop_threshold=1e-09, verbose=True)), feature_transform: RothHmmFeatureTransformer = cf(RothHmmFeatureTransformer(axes=['gyr_ml'], features=['raw', 'gradient'], low_pass_filter=ButterworthFilter(cutoff_freq_hz=10.0, filter_type='lowpass', order=4), sampling_rate_feature_space_hz=51.2, standardization=True, window_size_s=0.2)), *, algo_predict: Literal['viterbi', 'map'] = 'viterbi', algo_train: Literal['viterbi', 'baum-welch'] = 'baum-welch', stop_threshold: float = 1e-09, max_iterations: int = 1, initialization: Literal['labels', 'fully-connected'] = 'labels', verbose: bool = True, n_jobs: int = 1, name: str = 'segmentation_model', model: HiddenMarkovModel | None = None, data_columns: tuple[str, ...] | None = None)[source]#

A hierarchical HMM model for stride segmentation proposed by Roth et al. [1].

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 model differentiates between strides and transitions. Both data sections are modeled by individual HMMs and are trained separately. A final model is created by combining the transition matrices of the two models and allowing for transitions between these higher level states at the start or end of a stride.

Parameters:

stride_model: The (untrained) hmm representing the strides in the data. This will be updated during the optimization step (see notes).
transition_model: The (untrained) hmm representing the transitions in the data. This will be updated during the optimization step (see notes).
feature_transform: An instance of a FeatureTransformHMM that can transform the data (and the labeled stride list) into the feature space required by the HMM. If you want to use custome feature extraction,
algo_train: The algorithm to use for training the HMM.
algo_predict: The algorithm to use for prediction with the HMM.
stop_threshold: The loss threshold to stop the optimization. Note, that is the threshold for the “combined” training of the final model. This is less important, as we recommend to train the combined model only for a single iteration anyway. If you want to adjust the stop threshold for the individual models, you can do so by adjusting the respective parameters of the stride and transition model (stride_model.stop_threshold and transition_model.stop_threshold).
max_iterations: The maximum number of iterations to perform during the optimization. Note, that this is the value for the “combined” training of the final model. We recommend keeping this value at 1, as the combined model training only adjusts the transition matrix. If you want to adjust the max iterations for the individual models, you can do so by adjusting the respective parameters of the stride and transition model (stride_model.max_iterations and transition_model.max_iterations).
initialization: The initialization method to use for the HMM during optimization. fully-connected assumes that all states are reachable from any other state with the same probability. labels will derive the allowed transitions and probabilities from the given labels. In both cases, distributions will be derived from the data during optimization. We recommend using labels here, as this is kind of the default mode we expect these segmentation models to be used. If you select fully-connected, you might want to increase the max_iterations parameter to allow the model to actually be trained.
verbose: If True, print additional information during optimization.
n_jobs: The number of parallel jobs to use during optimization. If set to -1, all available cores will be used.
name: The name of the final pomegranate model.
model: The actual pomegranate HMM model. This can be set to None initially. A model will then be created during the optimization step. If you want to use a pre-trained model, you can set this parameter to the respective model. However, we recommend to ideally export this entire class instead of just the model to make sure that things like the feature transform are also exported/stored.
data_columns: The expected columns of the input data in feature space. This will be automatically set based on the feature transform output during the optimization step. This does not affect the output, but is used as a sanity check to ensure that valid input data is provided and that the column order is correct.

Other Parameters:

data: The data passed to the segment method.
sampling_rate_hz: The sampling rate of the data

Attributes:

feature_space_data_: The data in feature space. This is only here for debugging purposes.
hidden_state_sequence_: The hidden state sequence predicted by the model with the same sampling rate as the input data.
hidden_state_sequence_feature_space_: The predicted hidden-state sequence in feature space.

Notes

Note, that we are also store the trained stride and transition model during the optimization step. These are not required for prediction, as all there information is also contained in the fused model. However, inspecting the trained models might provide further inside into possible training issues. As the models are generally small, this should not impact RAM (or disk usage during export) in a relevant way.

References

[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

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.
`predict`(data, sampling_rate_hz)	Perform prediction based on given data and given model.
`self_optimize`(data_sequence, ...)	Create and train the HMM model based on the given data and labels.
`self_optimize_with_info`(data_sequence, ...)	Create and train the HMM model based on the given data and labels.
`set_params`(**params)	Set the parameters of this Algorithm.
`to_json`()	Export the current object parameters as json.

__init__(stride_model: SimpleHmm = cf(SimpleHmm(algo_train='baum-welch', architecture='left-right-strict', data_columns=None, max_iterations=10, model=None, n_gmm_components=6, n_jobs=1, n_states=20, name='stride_model', stop_threshold=1e-09, verbose=True)), transition_model: SimpleHmm = cf(SimpleHmm(algo_train='baum-welch', architecture='left-right-loose', data_columns=None, max_iterations=10, model=None, n_gmm_components=3, n_jobs=1, n_states=5, name='transition_model', stop_threshold=1e-09, verbose=True)), feature_transform: RothHmmFeatureTransformer = cf(RothHmmFeatureTransformer(axes=['gyr_ml'], features=['raw', 'gradient'], low_pass_filter=ButterworthFilter(cutoff_freq_hz=10.0, filter_type='lowpass', order=4), sampling_rate_feature_space_hz=51.2, standardization=True, window_size_s=0.2)), *, algo_predict: Literal['viterbi', 'map'] = 'viterbi', algo_train: Literal['viterbi', 'baum-welch'] = 'baum-welch', stop_threshold: float = 1e-09, max_iterations: int = 1, initialization: Literal['labels', 'fully-connected'] = 'labels', verbose: bool = True, n_jobs: int = 1, name: str = 'segmentation_model', model: HiddenMarkovModel | None = None, data_columns: tuple[str, ...] | 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.

predict(data: DataFrame, sampling_rate_hz: float) → Self[source]#

Perform prediction based on given data and given model.

This generates the hidden state sequence and stores it in the hidden_state_sequence_ attribute. Data will first be transformed using the feature transform and then the trained model will be used to predict the individual hidden states.

Parameters:

data: The data to predict the hidden state sequence for. Note, that this must have the same columns than the data used during training.
sampling_rate_hz: The sampling rate of the data.

Returns:

self: The instance with the result objects attached.

self_optimize(data_sequence: Sequence[DataFrame], stride_list_sequence: Sequence[DataFrame], sampling_rate_hz: float) → Self[source]#

Create and train the HMM model based on the given data and labels.

This will first apply the feature transformation to the given data and then train the HMM model in three steps:

Train the stride model on the stride data
Train the transition model on the transition data
Assemble the final model by combining the stride and transition model and train it for a couple further iterations

Parameters:

data_sequence: Sequence of gaitmap sensordata objects.
stride_list_sequence: Sequence of gaitmap stride lists. The number of stride lists must match the number of sensordata objects (i.e. they must belong together).
sampling_rate_hz: Sampling frequency of the data.

Returns:

self: The trained model instance.

self_optimize_with_info(data_sequence: Sequence[DataFrame], stride_list_sequence: Sequence[DataFrame], sampling_rate_hz: float) → tuple[typing_extensions.Self, dict[Literal['self', 'transition_model', 'stride_model'], pomegranate.callbacks.History]][source]#

Create and train the HMM model based on the given data and labels.

This is identical to self_optimize, but returns additional information about the training process. The dictionary returned as second parameter contains the training history for each of the three models ( stride-model, transition-model, and the combined final model “self”).

Parameters:

data_sequence: Sequence of gaitmap sensordata objects.
stride_list_sequence: Sequence of gaitmap stride lists. The number of stride lists must match the number of sensordata objects (i.e. they must belong together).
sampling_rate_hz: Sampling frequency of the data.

Returns:

self: The trained model instance.
history: Dictionary containing the training history for each of the three models

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.hmm.RothSegmentationHmm`#

SegmentationModel Training

gaitmap.stride_segmentation.hmm.RothSegmentationHmm#

Examples using gaitmap.stride_segmentation.hmm.RothSegmentationHmm#

Examples using `gaitmap.stride_segmentation.hmm.RothSegmentationHmm`#