skdh.activity.ActivityLevelClassification#

class skdh.activity.ActivityLevelClassification(short_wlen=5, max_accel_lens=(6, 15, 60), bout_lens=(1, 5, 10), bout_criteria=0.8, bout_metric=4, closed_bout=False, wear_wake_times_round=None, min_wear_time=10, cutpoints='migueles_wrist_adult', day_window=(0, 24), save_epoch_data=False)#

Classify accelerometer data into different activity levels as a proxy for assessing physical activity energy expenditure (PAEE). Levels are sedentary, light, moderate, and vigorous. If provided, sleep time will always be excluded from the activity level classification.

Parameters:
short_wlenint, optional

Short window length in seconds, used for the initial computation acceleration metrics. Default is 5 seconds. Must be a factor of 60 seconds.

max_accel_lensiterable, optional

Windows to compute the maximum mean acceleration metric over, in minutes. Default is (6, 15, 60).

bout_lensiterable, optional

Activity bout lengths. Default is (1, 5, 10).

bout_criteriafloat, optional

Value between 0 and 1 for how much of a bout must be above the specified threshold. Default is 0.8

bout_metric{1, 2, 3, 4, 5}, optional

How a bout of MVPA is computed. Default is 4. See notes for descriptions of each method.

closed_boutbool, optional

If True then count breaks in a bout towards the bout duration. If False then only count time spent above the threshold towards the bout duration. Only used if bout_metric=1. Default is False.

wear_wake_times_round{None, int}, optional

A value in seconds to round the wear/wake start/end times to, relative to the start of the day. For example, if 15 is passed, and the wear/wake period starts at xx:yy:10, (and the day starts at 00:00:00), the start time will be rounded to xx:yy:15.

min_wear_timeint, optional

Minimum wear time in hours for a day to be analyzed. Default is 10 hours.

cutpoints{str, dict, list}, optional

Cutpoints to use for sedentary/light/moderate/vigorous activity classification. Default is “migueles_wrist_adult” [1]. For a list of all available metrics use skdh.activity.get_available_cutpoints(). Custom cutpoints can be provided in a dictionary (see Adding Custom Endpoints).

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.

save_epoch_databool

Save the epochs with calculated metrics. Default is False.

Methods

add(endpoint)

Add an endpoint to the list to be calculated.

convert_timestamps(t)

Convert a timestamp/array of timestamps to a datetime object

predict(*, time, accel[, fs, wear])

Compute the time spent in different activity levels.

save_results(results, file_name)

Save the results of the processing pipeline to a csv file.

Notes

While the bout_metric methods all should yield fairly similar results, there are subtle differences in how the results are computed:

  1. MVPA bout definition from [2] and [3]. Here the algorithm looks for bout_len

    minute windows in which more than bout_criteria percent of the epochs are above the MVPA threshold (above the “light” activity threshold) and then counts the entire window as mvpa. The motivation for this definition was as follows: A person who spends 10 minutes in MVPA with a 2 minute break in the middle is equally active as a person who spends 8 minutes in MVPA without taking a break. Therefore, both should be counted equal.

  2. Look for groups of epochs with a value above the MVPA threshold that span

    a time window of at least bout_len minutes in which more than bout_criteria percent of the epochs are above the threshold. Motivation: not counting breaks towards MVPA may simplify interpretation and still counts the two persons in the above example as each others equal.

  3. Use a sliding window across the data to test bout_criteria per window and

    do not allow for breaks larger than 1 minute, and with fraction of time larger than the bout_criteria threshold.

  4. Same as 3, but also requires the first and last epoch to meet the threshold

    criteria.

  5. Same as 4, but now looks for breaks larger than a minute such that 1 minute

    breaks are allowed, and the fraction of time that meets the threshold should be equal or greater than the bout_criteria threshold.

References

[1]

J. H. Migueles et al., “Comparability of accelerometer signal aggregation metrics across placements and dominant wrist cut points for the assessment of physical activity in adults,” Scientific Reports, vol. 9, no. 1, Art. no. 1, Dec. 2019, doi: 10.1038/s41598-019-54267-y.

[2]

I. C. da Silva et al., “Physical activity levels in three Brazilian birth cohorts as assessed with raw triaxial wrist accelerometry,” International Journal of Epidemiology, vol. 43, no. 6, pp. 1959–1968, Dec. 2014, doi: 10.1093/ije/dyu203.

[3]

S. Sabia et al., “Association between questionnaire- and accelerometer-assessed physical activity: the role of sociodemographic factors,” Am J Epidemiol, vol. 179, no. 6, pp. 781–790, Mar. 2014, doi: 10.1093/aje/kwt330.

add(endpoint)#

Add an endpoint to the list to be calculated.

Parameters:
endpointlist, skdh.activity.ActivityEndpoint

The initialized endpoint, or list of endpoints.

predict(*, time, accel, fs=None, wear=None)#

Compute the time spent in different activity levels.

Parameters:
timenumpy.ndarray

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

accelnumpy.ndarray

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

fs{None, float}, optional

Sampling frequency in Hz. If None will be computed from the first 5000 samples of time.

wear{None, list}, optional

List of length-2 lists of wear-time ([start, stop]). Default is None, which uses the whole recording as wear time.

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.

Returns:
activity_resdict

Computed activity level metrics.

save_results(results, file_name)#

Save the results of the processing pipeline to a csv file. Will also save per epoch metric value if save_epoch_data is true. The file name for per epoch results is the same as the activity endpoints file with “_per_epoch_predictions” added to the end.

Parameters:
resultsdict

Dictionary of results from the output of predict

file_namestr

File name. Can be optionally formatted (see Notes)

Notes

Available format variables available:

  • date: todays date expressed in yyyymmdd format.

  • name: process name.

  • file: file name used in the pipeline, or “” if not found.