skdh.gait.GaitLumbar#

class skdh.gait.GaitLumbar(downsample=False, height_factor=0.53, provide_leg_length=False, min_bout_time=8.0, max_bout_separation_time=0.5, gait_event_method='AP CWT', correct_orientation=True, filter_cutoff=20.0, filter_order=4, ap_axis_filter_kw=None, ic_prom_factor=0.6, ic_dist_factor=0.5, fc_prom_factor=0.6, fc_dist_factor=0.6, use_cwt_scale_relation=True, wavelet_scale='default', round_scale=False, max_stride_time='default', loading_factor='default', bout_processing_pipeline=None, day_window=(0, 24))#

Process lumbar IMU data to extract metrics of gait. Detect gait, extract gait events (heel-strikes, toe-offs), and compute gait metrics from inertial data collected from a lumbar mounted wearable inertial measurement unit. If angular velocity data is provided, turns are detected, and steps during turns are noted.

Parameters:
downsamplebool, optional

Downsample acceleration data to either 50hz (for sampling rates >50hz) or 20hz (for sampling rates <50hz but >20hz). Default is False.

height_factorfloat, optional

The factor multiplied by height to obtain an estimate of leg length. Default is 0.53 [4]. Ignored if leg_length is True

provide_leg_lengthbool, optional

If the actual leg length will be provided. Setting to true would have the same effect as setting height_factor to 1.0 while providing leg length. Default is False.

min_bout_timefloat, optional

Minimum time in seconds for a gait bout. Default is 8s (making a minimum of 3 3-second windows).

max_bout_separation_timefloat, optional

Maximum time in seconds between two bouts of gait for them to be merged into 1 gait bout. Default is 0.5s.

gait_event_method{“AP CWT”, “Vertical CWT”}, optional

The method to use for gait event detection, case-insensitive. “AP CWT” uses skdh.gaitv3.substeps.ApCwtGaitEvents(), while “Vertical CWT” uses skdh.gaitv3.substeps.VerticalCwtGaitEvents(). Default is “AP CWT”.

day_windowarray-like

Two (2) element array-like of the base and period of the window to use for determining days. Default is (0, 24), which will look for days starting at midnight and lasting 24 hours. None removes any day-based windowing.

Methods

add_endpoints(endpoints)

Add endpoints to be computed

convert_timestamps(t)

Convert a timestamp/array of timestamps to a datetime object

predict(time, accel, *[, gyro, fs, height, ...])

Get the gait events and endpoints from a time series signal

save_results(results, file_name)

Save the results of the processing pipeline to a csv file
Other Parameters:
correct_orientationbool, optional

[skdh.gaitv3.substeps.PreprocessGaitBout()] Correct the accelerometer orientation if it is slightly mis-aligned with the anatomical axes. Default is True. Used in the pre-processing step of the bout processing pipeline.

filter_cutofffloat, optional

[skdh.gaitv3.substeps.PreprocessGaitBout()] Low-pass filter cutoff in Hz for the acceleration data for future use in bout processing. Default is 20.0.

filter_orderint, optional

[skdh.gaitv3.substeps.PreprocessGaitBout()] Low-pass filter order. Default is 4.

ap_axis_filter_kw{None, dict}, optional

Key-word arguments for the filter applied to the acceleration data before cross-correlation when estimating the AP axis. If None (default), the following are used:

  • N: 4

  • Wn: [0.25, 7.5] - NOTE, this should be in Hz, not radians. fs will be passed into the filter setup at filter creation time.

  • btype: band

  • output: sos - NOTE that this will always be set/overriden

See scipy.signal.butter() for full options.

ic_prom_factorfloat, optional

[skdh.gaitv3.substeps.ApCwtGaitEvents()] Factor multiplied by the standard deviation of the CWT coefficients to obtain a minimum prominence for IC peak detection. Default is 0.6.

ic_dist_factorfloat, optional

[skdh.gaitv3.substeps.ApCwtGaitEvents()] Factor multiplying the mean step samples to obtain a minimum distance (in # of samples) between IC peaks. Default is 0.5.

fc_prom_factorfloat, optional

[skdh.gaitv3.substeps.ApCwtGaitEvents()] Factor multiplying the standard deviation of the CWT coefficients to obtain a minimum prominence for FC peak detection. Default is 0.6

fc_dist_factorfloat, optional

[skdh.gaitv3.substeps.ApCwtGaitEvents()] Factor multiplying the mean step samples to obtain a minimum distance (in # of samples) between FC peaks. Default is 0.6.

use_cwt_scale_relationbool, optional

[skdh.gaitv3.substeps.VerticalCwtGaitEvents()] Use the optimal scale/frequency relationship.

wavelet_scale{“default”, float, int}, optional

[skdh.gaitv3.substeps.VerticalCwtGaitEvents()] The wavelet scale to use.

round_scalebool, optional

[skdh.gaitv3.substeps.VerticalCwtGaitEvents()] Round the wavelet scale. Default is False.

max_stride_time{“default”, callable, float}, optional

[skdh.gaitv3.substeps.CreateStridesAndQc()] Definition of how the maximum stride time is calculated. Either a callable with the input of the mean step time, or a float, which will be used as a static limit. Default (“default”) is the function \(2.0 * mean\_step\_time + 1.0\).

loading_factor{“default”, callable, float}, optional

[skdh.gaitv3.substeps.CreateStridesAndQc()] Definition of the loading factor. Either a callable with the input of mean step time, or a float (between 0.0 and 1.0) indicating a static factor. Default (“default”) is the function \(0.17 * mean\_step\_time + 0.05\).

bout_processing_pipeline{None, Pipeline}, optional

The processing pipeline to use on bouts of gait. Default is None, which creates a standard pipeline (see Notes). If you need more than these steps, you can provide your own pipeline. NOTE that you must set flatten_results=True when creating the custom pipeline.

Notes

The default pipeline is the following steps:

  • skdh.gaitv3.substeps.PreprocessGaitBout()

  • skdh.gaitv3.substeps.ApCwtGaitEvents() or skdh.gaitv3.substeps.VerticalCwtGaitEvents()

  • skdh.gaitv3.substeps.CreateStridesAndQc()

  • skdh.gaitv3.substeps.TurnDetection()

3 optimizations are performed on the detected events to minimize false positives.

1. Loading time (initial double support) must be less than \(loading\_factor * max\_stride\_time\)

2. Stance time must be less than \((max\_stride\_time/2) + loading\_factor * max\_stride\_time\)

  1. Stride time must be less than max_stride_time

If angular velocity data is provided, turns are detected [8], and steps during turns are noted in the results. Values are assigned as follows:

  • -1: Turns not detected (lacking angular velocity data)

  • 0: No turn found

  • 1: Turn overlaps with either Initial or Final contact

  • 2: Turn overlaps with both Initial and Final contact

References

[1]

B. Najafi, K. Aminian, A. Paraschiv-Ionescu, F. Loew, C. J. Bula, and P. Robert, “Ambulatory system for human motion analysis using a kinematic sensor: monitoring of daily physical activity in the elderly,” IEEE Transactions on Biomedical Engineering, vol. 50, no. 6, pp. 711–723, Jun. 2003, doi: 10.1109/TBME.2003.812189.

[2]

W. Zijlstra and A. L. Hof, “Assessment of spatio-temporal gait parameters from trunk accelerations during human walking,” Gait & Posture, vol. 18, no. 2, pp. 1–10, Oct. 2003, doi: 10.1016/S0966-6362(02)00190-X.

[3]

J. McCamley, M. Donati, E. Grimpampi, and C. Mazzà, “An enhanced estimate of initial contact and final contact instants of time using lower trunk inertial sensor data,” Gait & Posture, vol. 36, no. 2, pp. 316–318, Jun. 2012, doi: 10.1016/j.gaitpost.2012.02.019.

[4]

S. Del Din, A. Godfrey, and L. Rochester, “Validation of an Accelerometer to Quantify a Comprehensive Battery of Gait Characteristics in Healthy Older Adults and Parkinson’s Disease: Toward Clinical and at Home Use,” IEEE J. Biomed. Health Inform., vol. 20, no. 3, pp. 838–847, May 2016, doi: 10.1109/JBHI.2015.2419317.

[5]

C. Caramia, C. De Marchis, and M. Schmid, “Optimizing the Scale of a Wavelet-Based Method for the Detection of Gait Events from a Waist-Mounted Accelerometer under Different Walking Speeds,” Sensors, vol. 19, no. 8, p. 1869, Jan. 2019, doi: 10.3390/s19081869.

[6]

C. Buckley et al., “Gait Asymmetry Post-Stroke: Determining Valid and Reliable Methods Using a Single Accelerometer Located on the Trunk,” Sensors, vol. 20, no. 1, Art. no. 1, Jan. 2020, doi: 10.3390/s20010037.

[7]

R. Moe-Nilssen, “A new method for evaluating motor control in gait under real-life environmental conditions. Part 1: The instrument,” Clinical Biomechanics, vol. 13, no. 4–5, pp. 320–327, Jun. 1998, doi: 10.1016/S0268-0033(98)00089-8.

[8]

M. H. Pham et al., “Algorithm for Turning Detection and Analysis Validated under Home-Like Conditions in Patients with Parkinson’s Disease and Older Adults using a 6 Degree-of-Freedom Inertial Measurement Unit at the Lower Back,” Front. Neurol., vol. 8, Apr. 2017, doi: 10.3389/fneur.2017.00135.

add_endpoints(endpoints)#

Add endpoints to be computed

Parameters:
endpoints{Iterable, GaitEventEndpoint, GaitBoutEndpoint}

Either an iterable of GaitEventEndpoint or GaitBoutEndpoint references or an individual GaitEventEndpoint/GaitBoutEndpoint reference to be added to the list of endpoints to be computed.

Examples

>>> class NewGaitEndpoint(gait_metrics.GaitEventEndpoint):
>>>     pass
>>>
>>> gait = GaitV3()
>>> gait.add_endpoints(NewGaitEndpoint)

>>> class NewGaitEndpoint(gait_metrics.GaitEventEndpoint):
>>>     pass
>>> class NewGaitEndpoint2(gait_metrics.GaitEventEndpoint):
>>>     pass
>>>
>>> gait = GaitV3()
>>> gait.add_endpoints([NewGaitEndpoint, NewGaitEndpoint2])
predict(time, accel, *, gyro=None, fs=None, height=None, gait_pred=None, v_axis=None, ap_axis=None, tz_name=None)#

Get the gait events and endpoints from a time series signal

Parameters:
timenumpy.ndarray

(N, ) array of unix timestamps, in seconds

accelnumpy.ndarray

(N, 3) array of accelerations measured by a centrally mounted lumbar inertial measurement device, in units of ‘g’.

gyronumpy.ndarray

(N, 3) array of angular velocities measured by a centrally mounted lumbar inertial measurement device, in units of ‘rad/s’. If provided, will be used to indicate if steps occur during turns. Default is None.

fsfloat, optional

Sampling frequency in Hz of the accelerometer data. If not provided, will be computed form the timestamps.

heightfloat, optional

Either height (False) or leg length (True) of the subject who wore the inertial measurement device, in meters, depending on leg_length. If not provided, spatial endpoints will not be computed.

gait_boutsnumpy.ndarray, optional

(N, 2) array of gait starts (column 1) and stops (column 2). Either this or gait_pred is required in order to have gait analysis be performed on the data. gait_bouts takes precedence over gait_pred.

gait_pred{any, numpy.ndarray}, optional

(N, ) array of boolean predictions of gait, or any value that is not None. If not a ndarray but not None, the entire recording will be taken as gait. If not provided (or None), gait classification will be performed on the acceleration data. Default is True.

v_axis{None, 0, 1, 2}, optional

Vertical axis index. Default is None, which indicates it will be estimated from the acceleration data each gait bout.

ap_axis{None, 0, 1, 2}, optional

AP axis index. Default is None, which indicates that it will be estimated from the acceleration data each bout.

Returns:
gait_resultsdict

The computed gait endpoints. For a list of endpoints and their definitions, see Event Level Gait Metrics and Bout Level Gait Metrics.

Other Parameters:
tz_name{None, str}, optional

IANA time-zone name for the recording location if passing in time as UTC timestamps. Can be ignored if passing in naive timestamps.

Raises:
ValueError

If both gait_bouts and gait_pred are None.

LowFrequencyError

If the sampling frequency is less than 20Hz

Notes

The vertical axis is estimated as the axis with the highest absolute average acceleration during a gait bout. Since the acceleromter should be approximately aligned with the anatomical axes, this is a fairly easy estimation to perform

The AP axis estimation is a little trickier, and depending on how the observed accelerometer wearer was walking, the AP and ML axes can be confused. The AP axis is estimated by first applying a butterworth filter (4th order, 3.0hz cutoff) to the acceleration data, and then computing the auto-covariance function 10 seconds or the bout length, whichever is shorter. The axis that has the closest autocorrelation with the vertical axis is then chosen as the AP axis.