gaitmap.trajectory_reconstruction.MahonyAHRS#

class gaitmap.trajectory_reconstruction.MahonyAHRS(kp: float = 1.0, ki: float = 0.0, initial_orientation: ndarray | Rotation = cf(array([0., 0., 0., 1.])), use_magnetometer: bool = False, memory: Memory | None = None)[source]#

The MahonyAHRS algorithm to estimate the orientation of an IMU.

This method applies gyroscope integration with proportional-integral feedback based on the estimated gravity direction from the accelerometer data. If requested, the magnetometer can be used as an additional heading reference. This implementation is based on the paper [1] and the open source x-io reference implementation [2].

Parameters:

kp: Proportional gain of the feedback term. Higher values make the algorithm react faster to accelerometer or magnetometer based corrections. A value of 0 disables the proportional correction.
ki: Integral gain of the feedback term. This term can compensate constant gyro bias over time, but can also introduce drift or overshoot if chosen too large. A value of 0 disables the integral correction.
initial_orientation: The initial orientation of the sensor that is assumed. It is critical that this value is close to the actual orientation. Otherwise, the estimated orientation will drift until the real orientation is found. If you pass an array, the element order must be x, y, z, w.
use_magnetometer: If the magnetometer data should be used to correct the orientation. This requires magnetometer columns to be present in the input data. If True, the Mahony AHRS variant with magnetic heading correction will be used.
memory: An optional joblib.Memory object that can be provided to cache the calls to the Mahony update series.

Other Parameters:

data: The data passed to estimate. It must be a single-sensor dataframe with accelerometer and gyroscope columns in the sensor frame. If use_magnetometer=True, magnetometer columns are required as well.
sampling_rate_hz: The sampling rate of data in Hz.

Attributes:

orientation_: Orientations as pd.DataFrame.
orientation_object_: The orientations as a single scipy Rotation object.
rotated_data_: Rotated data.

See also

gaitmap.trajectory_reconstruction: Other implemented algorithms for orientation and position estimation
gaitmap.trajectory_reconstruction.StrideLevelTrajectory: Apply the method for each stride of a stride list.

Notes

This class uses Numba as a just-in-time compiler to achieve fast run times. As a result, the first execution of the algorithm will take longer because the methods need to be compiled first.

[1]

Mahony, R., Hamel, T., & Pflimlin, J.-M. (2008). Nonlinear complementary filters on the special orthogonal group. IEEE Transactions on Automatic Control, 53(5), 1203-1218. https://doi.org/10.1109/TAC.2008.923738

[2]

https://x-io.co.uk/open-source-imu-and-ahrs-algorithms/

Examples

Your data must be a pd.DataFrame with columns defined by SF_COLS or SF_COLS_WITH_MAG.

>>> import numpy as np
>>> import pandas as pd
>>> from gaitmap.utils.consts import SF_COLS
>>> data = pd.DataFrame(..., columns=SF_COLS)
>>> sampling_rate_hz = 100
>>> mahony = MahonyAHRS(kp=0.8, ki=0.05, initial_orientation=np.array([0, 0, 0, 1.0]))
>>> mahony = mahony.estimate(data, sampling_rate_hz=sampling_rate_hz)
>>> mahony.orientation_
<pd.DataFrame with resulting quaternions>
>>> mahony.orientation_object_
<scipy.Rotation object>

Methods

`clone`()	Create a new instance of the class with all parameters copied over.
`estimate`(data, , sampling_rate_hz, *_)	Estimate the orientation of the sensor.
`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__(kp: float = 1.0, ki: float = 0.0, initial_orientation: ndarray | Rotation = cf(array([0., 0., 0., 1.])), use_magnetometer: bool = False, memory: Memory | 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

estimate(data: DataFrame, *, sampling_rate_hz: float, **_) → Self[source]#

Estimate the orientation of the sensor.

Parameters:

data: Continuous sensor data including gyro and acc values. If use_magnetometer=True, magnetometer values must be present as well. The gyroscope data is expected to be in deg/s.
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[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.

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.trajectory_reconstruction.MahonyAHRS`#

Mahony and Madgwick Orientation Estimation

gaitmap.trajectory_reconstruction.MahonyAHRS#

Examples using gaitmap.trajectory_reconstruction.MahonyAHRS#

Examples using `gaitmap.trajectory_reconstruction.MahonyAHRS`#