gaitmap.trajectory_reconstruction.PieceWiseLinearDedriftedIntegration

class gaitmap.trajectory_reconstruction.PieceWiseLinearDedriftedIntegration(zupt_detector=cf(NormZuptDetector(inactive_signal_threshold=15.0, metric='mean', sensor='gyr', window_length_s=0.15, window_overlap=0.5, window_overlap_samples=None)), level_assumption: bool = True, gravity: ndarray | None = cf(array([0., 0., 9.81])))

Use a piecewise linear drift model based on zupts for integration of acc to estimate velocity and position.

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.

Warning

We assume that the acc signal is already converted into the global/world frame! Refer to the Coordinate System Guide for details.

This method uses the zero-velocity assumption (ZUPT) to perform a drift removal using a piece wise linear drift model. The method can be applied on complete movement sequences without the need for previous stride segmentation. We assume a linear integration error between all detected zupt regions. We further assume, that the signal starts with resting period (i.e. the starting velocity is assumed to be 0).

The ZUPTS update is currently only performed on the gyro norm and with the default settings we expect to find mid-stances as ZUPTS during regular walking.

Further drift correction is applied using a level-assumption (i.e. we assume that the sensor starts and ends its movement at the same z-position/height between zupt regions). If this assumption is not true for your usecase, you can disable it using the level_assumption parameter.

This approach is inspired by [1],[R8b84652974ca-2]_, and [3].

Parameters:

zupt_detector

An instance of a valid Zupt detector that will be used to find ZUPTs.

level_assumption

If True, it is assumed that the stride starts and ends at z=0 and dedrifting in that direction is applied accordingly.

gravityOptional (3,) array, or None

The value of gravity that will be subtracted from each Acc sample before integration. If this is None, no gravity subtraction will be performed. By default 9.81 m/s^2 will be subtracted from the z-Axis.

Other Parameters:

data

The data passed to the estimate method.

sampling_rate_hz

The sampling rate of the data.

Attributes:

velocity_

The velocity estimated by the piece wise linear dedrifted integration.

position_

The position estimated by the piece wise linear dedrifted integration of the dedrifted velocity.

zupts_

The estimated zupt regions.

See also

gaitmap.trajectory_reconstruction

Other implemented algorithms for orientation and position estimation

gaitmap.utils.static_moment_detection

Static moment detector used for estimating zupt updates.

Notes

In detail, the dedrifting works by first identifing all regions of zero velocity. For each region a linear fit is applied to corresonding velocity data. This is done to also compensate for drift during these resting phases.

For the remaing regions (non-ZUPT), a linear interpolation is applied, basically connecting the end of the linear fit applied to one region to the start of the next region with a straight line. For the first value in the sequence, we always assume a velocity of 0 and for the last value we take the final uncorrected velocity value. This multi linear baseline is than substracted from the velocity to correct it.

The same process is repeated for the z-position in case level_walking=True.

[1]

Hannink, J., Ollenschläger, M., Kluge, F., Roth, N., Klucken, J., and Eskofier, B. M. 2017. Benchmarking Foot Trajectory Estimation Methods for Mobile Gait Analysis. Sensors (Basel, Switzerland) 17, 9. https://doi.org/10.3390/s17091940

[2]

M. Zok, C. Mazz`a, and U. Della Croce, “Total body centre of mass displacement estimated using ground reactions during transitory motor tasks: Application to step ascent,” Medical Engineering & Physics, vol. 26, no. 9, pp. 791-798, Nov. 2004. [Online]. Available: https://linkinghub.elsevier.com/retrieve/pii/S1350453304001195

[3]

N. Kitagawa and N. Ogihara, “Estimation of foot trajectory during human walking by a wearable inertial measurement unit mounted to the foot,” Gait & Posture, vol. 45, pp. 110-114, Mar. 2016. [Online]. Available: https://linkinghub.elsevier.com/retrieve/pii/S0966636216000151

Examples

Your data must be a pd.DataFrame with all sensor columns defined. Remember, that this method does not transform your data into another coordinate frame, but just integrates it. If you want to use this method to calculate e.g. a stride length, make sure to convert your data into the global frame using any of the implemented orientation estimation methods.

>>> import pandas as pd
>>> from gaitmap.utils.consts import SF_COLS
>>> from gaitmap.zupt_detection import NormZuptDetector
>>> data = pd.DataFrame(..., columns=SF_COLS)
>>> sampling_rate_hz = 100
>>> # Create an algorithm instance
>>> pwli = PieceWiseLinearDedriftedIntegration(
...     NormZuptDetector(window_length_s=0.15, inactive_signal_threshold=15.0), gravity=np.array([0, 0, 9.81])
... )
>>> # Apply the algorithm
>>> pwli = pwli.estimate(data, sampling_rate_hz=sampling_rate_hz)
>>> # Inspect the results
>>> pwli.position_
<pd.Dataframe with resulting positions>
>>> pwli.velocity_
<pd.Dataframe with resulting velocities>

Methods

clone()	Create a new instance of the class with all parameters copied over.
estimate(data, *, sampling_rate_hz, **_)	Estimate the position of the sensor based on the provided global frame 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__(zupt_detector=cf(NormZuptDetector(inactive_signal_threshold=15.0, metric='mean', sensor='gyr', window_length_s=0.15, window_overlap=0.5, window_overlap_samples=None)), level_assumption: bool = True, gravity: ndarray | None = cf(array([0., 0., 9.81]))) → 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

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

Estimate the position of the sensor based on the provided global frame data.

Parameters:

data

Continuous sensor data that includes at least a Acc with all values in the global world frame

sampling_rate_hz

The sampling rate of the data in Hz

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

Automatic sensor alignment (detailed)

Automatic sensor alignment (detailed)