TdElGohary#

class mobgap.turning.TdElGohary( *, smoothing_filter: BaseFilter | None = cf(ButterworthFilter(cutoff_freq_hz=0.5, filter_type='lowpass', order=4, zero_phase=True)), min_peak_angle_velocity_dps: float = 15, lower_threshold_velocity_dps: float = 5, min_gap_between_turns_s: float = 0.05, allowed_turn_duration_s: tuple[float, float] = (0.5, 10), allowed_turn_angle_deg: tuple[float, float] = (45, inf), orientation_estimation: BaseOrientationEstimation | None = None, )[source]#

Detect turns in the continuous yaw signal of a lower back IMU based on the algorithm by El-Gohary et al.

Warning

There are some issues with matching the results of the ElGohary algorithm to the reference system. The performance, we are observing here is far below the expected performance. We are investigating this currently, but until then, we recommend to do your own testing and validation before using this algorithm in production.

This algorithm uses the lowpass filtered yaw-signal, then identifies peaks in its norm higher than min_peak_angle_velocity_dps. Each peak is considered a turn-candidate and the start and end of each turn is identified as the first and last samples before and after the respective peak that are below a certain threshold (lower_threshold_velocity_dps). Consecutive turns candidates in the same direction that are closer than min_gap_between_turns_s are merged. The final turns are then filtered based on their duration and the turning angle.

Parameters:

smoothing_filter: The filter to apply to the yaw signal before detecting the turns. That should be a lowpass filter, only preserving the main movements corresponding to the walking pattern.
min_peak_angle_velocity_dps: The minimum angular velocity in degrees per second that a peak in the yaw signal must have to be considered a turn candidate.
lower_threshold_velocity_dps: The threshold in degrees per second below which the signal is considered to be not turning. The algorithm finds the start and end of a turn as the first and last sample around each peak that is below this threshold.
min_gap_between_turns_s: The minimum gap in seconds between two turns to be considered separate turns. If two turn candidates that turn in the same direction are closer than this, they are merged.
allowed_turn_duration_s: The allowed duration of a turn in seconds. This is evaluated as the final step of the algorithm.
allowed_turn_angle_deg: The allowed turning angle of a turn in degrees. This is evaluated as the final step of the algorithm.
orientation_estimation: An optional instance of an orientation estimation algorithm to transform the IMU signal to the global frame. The version used in Mobilise-D did not use this, but the version described in the original publication did apply the algorithm to data from the global frame. This also makes the global_frame_data_ attribute available, which contains the transformed data.

Other Parameters:

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

Attributes:

turn_list_: The detected turns. The dataframe has the columns “start”, “end”, “duration_s”, “turn_angle_deg”, and “direction”. The “direction” column specifies the direction of the turn as “left” or “right”.
raw_turn_list_: The detected turns before filtering based on duration and angle. This df also contains an additional center column, which marks the position of the originally detected peak. This might be helpful for debugging or further analysis.
yaw_angle_: The yaw angle of the IMU signal estimated through the integration of the gyr_is signal. This is used to estimate the turn angle. This might be helpful for debugging or further analysis.
global_frame_data_: The data in the global frame, if an orientation estimation algorithm was used. Otherwise, this is None.

Notes

Implementation Details:

If a turn has no crossing with lower_threshold_velocity_dps, as it happens close to the start or the end of the signal, the start/ends of the turn are replaced with the start/end of the signal. This might not always result in accurate turn angles for these turns, and for certain cases you might want to remove these turns from the list.
The turn angle is calculated by integrating the raw unfiltered signal.

Compared to original publication:

We skip the global frame transformation and assume that the z axis roughly aligns with the turning axis. If you want to run the turn algorithm in the global frame, perform a orientation estimation and coordinate system transformation before running this algorithm.

Compared to matlab implementation:

We fix a bug, that only the start and the end of a turn was detected on the signed signal instead of the absolute signal. This made it “harder” to detect turns in one direction than the other.

Methods

`clone`()	Create a new instance of the class with all parameters copied over.
`detect`(data, , sampling_rate_hz, *_)	Detect turns in the passed data..
`get_params`([deep])	Get parameters for this algorithm.
`set_params`(**params)	Set the parameters of this Algorithm.

__init__( *, smoothing_filter: BaseFilter | None = cf(ButterworthFilter(cutoff_freq_hz=0.5, filter_type='lowpass', order=4, zero_phase=True)), min_peak_angle_velocity_dps: float = 15, lower_threshold_velocity_dps: float = 5, min_gap_between_turns_s: float = 0.05, allowed_turn_duration_s: tuple[float, float] = (0.5, 10), allowed_turn_angle_deg: tuple[float, float] = (45, inf), orientation_estimation: BaseOrientationEstimation | 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

detect(

data: DataFrame,

*,

sampling_rate_hz: float,

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

) → Self[source]#

Detect turns in the passed data..

Parameters:

data: The raw IMU data in the body frame. This should usually represent a single gait sequence or walking bout.
sampling_rate_hz: The sampling rate of the IMU data in Hz.

Returns:

self: The instance of the class with the turn_list_ attribute set to the detected turns.

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

Examples using `mobgap.turning.TdElGohary`#

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

ElGohary Turning Algo

TdElGohary#

Examples using mobgap.turning.TdElGohary#

Examples using `mobgap.turning.TdElGohary`#