gaitmap.zupt_detection.NormZuptDetector

class gaitmap.zupt_detection.NormZuptDetector(*, sensor: typing_extensions.Literal[acc, gyr] = 'gyr', window_length_s: float = 0.15, window_overlap: float | None = 0.5, window_overlap_samples: int | None = None, metric: typing_extensions.Literal[maximum, variance, mean, median, squared_mean] = 'mean', inactive_signal_threshold: float = 15)

Detect ZUPTs based on either the Acc or the Gyro norm.

The ZUPT method uses a sliding window approach with overlap. For overlapping windows the results will be combined with a logical “or” in the region of the overlap. I.e. if one of the overlapping windows is considered static, the entire region is. Neighboring static windows will be combined to a static region.

All calculations are always performed on the norm of the selected sensor.

At the moment only single sensor data is supported.

Note

Using the gyro signal with the metric “squared_mean” and a window overlap of len(window) - 1 samples, this ZUPT detector is equivalent to the ARED Zupt detector presented in [1]. We also provide the AredZuptDetector class for convenience that has these values as default.

Warning

Due to edge cases at the end of the input data where window size and overlap might not fit your data, the last window might be discarded for analysis and will therefore always be considered as non-static!

Parameters:

sensor

The sensor (either acc or gyr) to apply the detection to. The detector will calculate the norm for the respective sensor.

window_length_sint

Length of desired window in seconds. The real window length is calculated as window_length_samples = round(sampling_rate_hz * window_length_s)

window_overlapfloat

The overlap between two neighboring windows as a fraction of the window length. Must be 0 <= window_overlap < 1. Note that the window length is first converted into samples, before the effective overlap is calculated. The overlap in samples is calculated as overlap_samples = round(window_length_samples * window_overlap).

When window_overlap is specified, window_overlap_samples must be None.

window_overlap_samplesint

The overlap between two neighboring windows in samples. This can be used as alternative to window_overlap, when you want to set the overlap independent of the sampling rate. The values can be negative. In this case, it will be interpreted as len(window_length_samples) - window_overlap_samples. This can be helpful if you want to set the overlap to the maximum possible value. Then set window_overlap_samples to -1.

When window_overlap_samples is specified, window_overlap must be None.

inactive_signal_thresholdfloat

Threshold to decide whether a window should be considered as active or inactive. Window will be tested on metric(norm_window) <= threshold. The unit of this value depends on the selected sensor and metric.

metricstr

Metric which will be calculated per window on the norm of the signal, one of the following strings

‘mean’ (default)

Calculates mean value per window

‘squared_mean’

The same as mean, but the norm of the signal is squared before calculating the mean.

‘maximum’

Calculates maximum value per window

‘median’

Calculates median value per window

‘variance’

Calculates variance value per window

Other Parameters:

data

The data passed to the detect method

sampling_rate_hz

The sampling rate of this data

Attributes:

zupts_

Get the start and end values of all zupts.

per_sample_zupts_

A bool array with length len(data). If the value is True for a sample, it is part of a static region.

window_length_samples_

The internally calculated window length in samples. This might be helpful for debugging.

window_overlap_samples_

The internally calculated window overlap in samples. This might be helpful for debugging.

min_vel_index_

The index of the sample with the minimum velocity. This is calculated as the center of the window with the minimum velocity.

min_vel_value_

The minimum velocity value. This is calculated as the value of the window with the minimum velocity. If no window is below the threshold, this value is np.nan. Note, that in this case, min_vel_index is still set to a proper value.

See also

gaitmap.utils.array_handling.sliding_window_view

Details on the used windowing function for this method.

References

[1]

I. Skog, J.-O. Nilsson, P. Händel, and J. Rantakokko, “Zero-velocity detection—An algorithm evaluation,” IEEE Trans. Biomed. Eng., vol. 57, no. 11, pp. 2657-2666, Nov. 2010.

Methods

clone()	Create a new instance of the class with all parameters copied over.
detect(data, *, sampling_rate_hz, **_)	Detect all ZUPT regions in the data.
from_json(json_str)	Import an gaitmap object from its json representation.
get_params([deep])	Get parameters for this algorithm.
set_params(**params)	Set the parameters of this Algorithm.
to_json()	Export the current object parameters as json.

__init__(*, sensor: typing_extensions.Literal[acc, gyr] = 'gyr', window_length_s: float = 0.15, window_overlap: float | None = 0.5, window_overlap_samples: int | None = None, metric: typing_extensions.Literal[maximum, variance, mean, median, squared_mean] = 'mean', inactive_signal_threshold: float = 15) → 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

detect(data: DataFrame, *, sampling_rate_hz: float, **_) → Self

Detect all ZUPT regions in the data.

Parameters:

data

The data set holding the imu raw data

sampling_rate_hz

The sampling rate of the data

Returns:

self

The class instance with all result attributes populated

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.

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

Automatic sensor alignment (detailed)

Automatic sensor alignment (detailed)

Advanced Kalman Filter Usage

Advanced Kalman Filter Usage