ReorientationMethodDM#

class mobgap.re_orientation.ReorientationMethodDM( *, grav_threshold_ms2: float = 6.37, gait_frequency_band_filter: BaseFilter = cf(FirFilter(cutoff_freq_hz=(0.5, 2.5), filter_type='bandpass', order=100, window='hamming', zero_phase=True)), correction_mode: Literal['full', 'trust_gravity'] = 'trust_gravity', gravity_detection_error_type: Literal['raise', 'warn', 'ignore'] = 'warn', pa_direction_detection_error_type: Literal['raise', 'warn', 'ignore'] = 'warn', )[source]#

Detects and corrects IMU sensor orientation for lower-back-worn devices.

Warning

This method cannot correct arbitrary misalignments. It makes concrete assumptions about the possible orientation errors. See Notes for details.

Parameters:

correction_mode{‘full’, ‘trust_gravity’}: Default: "trust_gravity". full - applies PA direction correction to every walking bout. trust_gravity - assumes mounting orientation is correct if gravity already points up along sensor x (is_up) and skips PA direction correction. This intentionally ignores possible 180 deg front/back flips in this case. Before choosing this parameter for a pipeline, read the primary example Reorientation Method DM, which contains the mode-selection decision tree.
grav_threshold_ms2: Minimum absolute mean acceleration in m/s² for an axis to be treated as capturing gravity.
gait_frequency_band_filter: The filter applied to acc_x (IS) and acc_z (positive or negative PA), after the initial gravity alignment and before calculating the cross-spectral phase.
gravity_detection_error_type{‘raise’, ‘warn’, ‘ignore’}: How to handle gait sequences where gravity can not be detected. Note that errors in gravity detection will always skip the PA direction correction, even when not raising an error.
pa_direction_detection_error_type{‘raise’, ‘warn’, ‘ignore’}: How to handle gait sequences where the PA direction can not be detected.

Other Parameters:

data: The raw IMU data in the sensor frame passed to the detect_correct method.
sampling_rate_hz: The sampling rate of the raw IMU data in Hz.

Attributes:

corrected_data_: The reoriented IMU data in the anatomical frame.
result_ReorientationResult: Full detection and correction diagnostics including family, phase, correction flags, unresolved detection reason, and the gravity/PA correction rotations.

Notes

This method is designed to correct the most common orientation errors for lower-back-worn devices. It assumes that the sensor is a flat rectangular device mounted with one of its large flat surfaces against the body. For the rest of this explanation, we refer to the sensor axis that points through the body as the PA axis. In a correct mounting orientation, the PA axis (posterior to anterior) is aligned with the sensor z-axis, the vertical IS axis is aligned with the sensor x-axis, and the ML axis is aligned with the sensor y-axis. See the coordinate system guide for more details.

The method focuses on correcting mounting errors rather than small misalignments. It only corrects 90 deg or 180 deg rotations around the sensor axes, not arbitrary rotations that would require more complex corrections.

With this assumption, there are only eight possible mounting orientations, grouped into two independent error types:

Rotations around the PA axis that cause gravity to point in the wrong direction in the sensor frame. We correct four potential orientations of this type, which we call “orientation families”:
- is_up: gravity points up in sensor x (correct orientation) -> no correction.
- is_down: gravity points down in sensor x (180 deg rotation around sensor z).
- ml_up: gravity points up in sensor y (90 deg rotation around sensor z).
- ml_down: gravity points down in sensor y (90 deg rotation around sensor z, then 180 deg rotation around sensor x).
Independent of the gravity direction, the sensor could be flipped front-to-back around the vertical IS axis, which causes the PA axis to point in the wrong direction in the sensor frame. We correct this potential error by estimating PA direction from the cross-spectral phase between acc_x and acc_z. If the phase indicates a reversed PA direction, we apply a 180 deg rotation around the corrected sensor x-axis.

Important

Knowing the mounting orientation is always preferable to recovering it from data. If the orientation is known, apply a manual rotation before using mobgap and do not add data-driven orientation correction. If orientation errors are possible, first decide whether they can occur within a recording or only for a full recording/session. Read Reorientation Method DM before choosing a diagnostic workflow or a per-GS/WB correction mode for real data.

To correctly detect and apply these corrections, we make the following assumptions about the data:

The sensor axes of your data follow the expected directions under correct mounting (x: IS, y: ML, z: PA).
The sensor is mounted with one of its large flat surfaces against the body, not edge-on.
For the data segments where the algorithm is applied, the participant is in an upright posture and is walking the majority of the time. Extremely hunched postures, non-walking activities, or extremely pathological gait patterns might cause the algorithm to fail. However, most other steps of the MOBGAP pipeline are also likely to fail on such data.

Examples

>>> algo = ReorientationMethodDM(correction_mode="trust_gravity")
>>> algo = algo.detect_correct(wb_data, sampling_rate_hz=100.0)
>>> corrected = algo.result_.data_corrected

Methods

`clone`()	Create a new instance of the class with all parameters copied over.
`detect_correct`(data, , sampling_rate_hz, *_)	Detect sensor orientation and apply correction to the body frame.
`get_params`([deep])	Get parameters for this algorithm.
`set_params`(**params)	Set the parameters of this Algorithm.

__init__( *, grav_threshold_ms2: float = 6.37, gait_frequency_band_filter: BaseFilter = cf(FirFilter(cutoff_freq_hz=(0.5, 2.5), filter_type='bandpass', order=100, window='hamming', zero_phase=True)), correction_mode: Literal['full', 'trust_gravity'] = 'trust_gravity', gravity_detection_error_type: Literal['raise', 'warn', 'ignore'] = 'warn', pa_direction_detection_error_type: Literal['raise', 'warn', 'ignore'] = 'warn', ) → None[source]#

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

property corrected_data_: DataFrame#: The reoriented IMU data in the anatomical frame.

detect_correct(

data: DataFrame,

*,

sampling_rate_hz: float,

**_: Unpack[dict[str, Any]],

) → Self[source]#

Detect sensor orientation and apply correction to the body frame.

Parameters:

data: The raw IMU data in the sensor frame. Expected columns: acc_x, acc_y, acc_z, gyr_x, gyr_y, gyr_z.
sampling_rate_hz: The sampling rate of the raw IMU data in Hz.

Returns:

self: The instance of the class with the corrected_data_ attribute set to the reoriented data.

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=.

Examples using `mobgap.re_orientation.ReorientationMethodDM`#

The Mobilise-D pipeline: Step-by-Step Breakdown

Reorientation Method DM

Full-pipeline validation under simulated mounting errors

Performance of the reorientation algorithm on simulated TVS misorientations

Revalidation of the reorientation algorithm

ReorientationMethodDM#

Examples using mobgap.re_orientation.ReorientationMethodDM#

This Page

Examples using `mobgap.re_orientation.ReorientationMethodDM`#