gaitmap.stride_segmentation.hmm.SimpleHmm#

class gaitmap.stride_segmentation.hmm.SimpleHmm(n_states: int, n_gmm_components: int, *, architecture: Literal['left-right-strict', 'left-right-loose', 'fully-connected'] = 'left-right-strict', algo_train: Literal['viterbi', 'baum-welch', 'labeled'] = 'viterbi', stop_threshold: float = 1e-09, max_iterations: int = 100000000.0, verbose: bool = True, n_jobs: int = 1, name: str = 'my_model', model: HiddenMarkovModel | None = None, data_columns: tuple[str, ...] | None = None)[source]#

Wrap all required information to train a new HMM.

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 is a thin wrapper around the pomegranate HiddenMarkovModel class and basically calls out the pomegranate for all core functionality.

Note

This class is not intended to be used directly, but should be used as stride/transition model in the SegmentationModel. SimpleHmm therefore does not provide the same interface as other gaitmap algorithms. It does not have a dedicated action method, but only has a predict_hidden_state_sequence method that directly returns the hidden state sequence and does not store it on the object. The reason for that is, that we regularly need to call this method with different algorithms on the same model. Hence, it felt more natural to do it that way.

Parameters:

n_states: The number of states in the model.
n_gmm_components: The number of components in the GMMs. Each state will be represented by its own GMM with this number of components.
architecture: The architecture of the model. Can be either “left-right-strict”, “left-right-loose” or “fully-connected”. See Notes for more information.
algo_train: The algorithm to use for training. Can be either “viterbi” or “baum-welch”.
stop_threshold: The threshold for the training algorithm to stop.
max_iterations: The maximum number of iterations for the training algorithm.
name: The name of the model.
verbose: Whether to print progress information during training.
n_jobs: The number of jobs to use for training. If set to -1, all available cores will be used.
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.

See also

TBD

Notes

This model supports currently the following “architectures”:

“left-right-strict”: This will result in a strictly left-right structure, with no self-transitions and start- and end-state bound to the first and last state, respectively. Example transition matrix for a 5-state model:

transition_matrix: 1  1  0  0  0   starts: 1  0  0  0  0
                   0  1  1  0  0   stops:  0  0  0  0  1
                   0  0  1  1  0
                   0  0  0  1  1
                   0  0  0  0  1

“left-right-loose”: This will result in a loose left-right structure, with allowed self-transitions and start- and end-state not specified initially. Example transition matrix for a 5-state model:

transition_matrix: 1  1  0  0  0   starts: 1  1  1  1  1
                   0  1  1  0  0   stops:  1  1  1  1  1
                   0  0  1  1  0
                   0  0  0  1  1
                   1  0  0  0  1

“fully-connected”: This will result in a fully connected structure where all existing edges are initialized with the same probability. Example transition matrix for a 5-state model:

transition_matrix: 1  1  1  1  1   starts: 1  1  1  1  1
                   1  1  1  1  1   stops:  1  1  1  1  1
                   1  1  1  1  1
                   1  1  1  1  1
                   1  1  1  1  1

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_hidden_state_sequence`(feature_data)	Perform prediction based on given data and given model.
`self_optimize`(data_sequence, labels_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__(n_states: int, n_gmm_components: int, *, architecture: Literal['left-right-strict', 'left-right-loose', 'fully-connected'] = 'left-right-strict', algo_train: Literal['viterbi', 'baum-welch', 'labeled'] = 'viterbi', stop_threshold: float = 1e-09, max_iterations: int = 100000000.0, verbose: bool = True, n_jobs: int = 1, name: str = 'my_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_hidden_state_sequence(feature_data: DataFrame, algorithm: Literal['viterbi', 'map'] = 'viterbi') → ndarray[source]#

Perform prediction based on given data and given model.

Parameters:

feature_data: The data to predict the hidden state sequence for. Note, that the data must have at least the same columns as the data used for training. The order of the columns does not matter.
algorithm: The algorithm to use for prediction. Can be either “viterbi” or “map”.

Returns:

np.ndarray: The predicted hidden state sequence.

self_optimize(data_sequence: Sequence[DataFrame], labels_sequence: Sequence[ndarray | Series | DataFrame]) → Self[source]#

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

Parameters:

data_sequence: Sequence of gaitmap sensordata objects.
labels_sequence: Sequence of gaitmap stride lists. The number of stride lists must match the number of sensordata objects (i.e. they must belong together). Each label sequence should only contain integers in the range [0, n_states - 1]. The usage of the labels depends on the train algorithm. In case of viterbi and baum-welch, the labels are only used to identify the initial data clusters.

Returns:

self: The trained model instance.

self_optimize_with_info(data_sequence: Sequence[DataFrame], labels_sequence: Sequence[ndarray | Series | DataFrame]) → tuple[typing_extensions.Self, 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.

Parameters:

data_sequence: Sequence of gaitmap sensordata objects.
labels_sequence: Sequence of gaitmap stride lists. The number of stride lists must match the number of sensordata objects (i.e. they must belong together). Each label sequence should only contain integers in the range [0, n_states - 1]. The usage of the labels depends on the train algorithm. In case of viterbi and baum-welch, the labels are only used to identify the intial data clusters.

Returns:

self: The trained model instance.
history: The history callback containing the training history.

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.SimpleHmm`#

SegmentationModel Training

gaitmap.stride_segmentation.hmm.SimpleHmm#

Examples using gaitmap.stride_segmentation.hmm.SimpleHmm#

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