skdh.context.Ambulation#

class skdh.context.Ambulation(pthresh=0.65)#

Processes accelerometer data to extract bouts of ambulation.

The ambulation detection module is an algorithm for detecting ambulation or gait-like activities from raw tri-axial accelerometer data. The model used is a binary machine learning classifier that takes several signal features as input and produces predictions in three second non-overlapping epochs.

The original purpose of this module was to aid in context detection for nocturnal scratch detection. The scratch model is specifically trained to differentiate restless activity from scratch activity during sleep, and therefore has issues dealing with unseen activities such as walking. These activities sometimes occur during at home recordings and increase the false positive rate of the scratch module. The ambulation detection module was designed to help exclude these activities and therefore improve the performance of the scratch module by minimizing false positives.

An additional use of this model has been as a base-level context detection tool for step detection. Unlike the gait-bout detection algorithm, the ambulation detection module is not built to detect well-defined bouts of consistent gait for gait parameter estimation. It is rather a tool for detecting the presence of walking-similar activities, which makes it a good candidate for performing context detection for step counting.

Input requirements:

1. Accelerometer data must be collected with a sampling frequency of at least 20hz. If the frequency is greater than 20hz the signal will be automatically downsampled.

2. Accelerometer data is expected to be tri-axial. Orientation does not affect algorithm performance.

  1. Acceleration units are expected to be in G’s.

4. A minimum of 60 samples (or the equivalent of a single 3-second window) is required for predictions to be made.

Parameters:
pthreshfloat

Probability threshold for the classifier.

Methods

convert_timestamps(t)

Convert a timestamp/array of timestamps to a datetime object

predict(time, accel[, fs])

Function to detect ambulation or gait-like activity from 20hz accelerometer data collected on the wrist.

save_results(results, file_name)

Save the results of the processing pipeline to a csv file
predict(time, accel, fs=None)#

Function to detect ambulation or gait-like activity from 20hz accelerometer data collected on the wrist.

Parameters:
timenumpy.ndarray

(N, ) array of unix timestamps, in seconds.

accelnumpy.ndarray

(N, 3) array of acceleration, in units of ‘g’, collected at 20hz.

fsfloat, optional

Sampling rate. Default None. If not provided, will be inferred.

Returns:
resultsdict

Results dictionary including 3s epoch level predictions, probabilities, and unix timestamps.

dict

Results dictionary for downstream pipeline use including start and stop times for ambulation bouts.

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.