wristpy.processing.metrics¶
Calculate base metrics, anglez and enmo.
Functions
|
Compute Actigraph acitivty counts. |
|
Calculate the angle of the acceleration vector relative to the horizontal plane. |
|
This function uses the both temperature and acceleration data to detect non-wear. |
|
This function implements the scikit DETACH algorithm for non-wear detection. |
|
Set non_wear_flag based on accelerometer data. |
|
Compute ENMO, the Euclidean Norm Minus One (1 standard gravity unit). |
|
Calculate the mean amplitude deviation of the acceleration data. |
Calculates monitor independent movement summary units (MIMS). |
- wristpy.processing.metrics._cleanup_isolated_ones_nonwear_value(nonwear_value_array: ndarray) ndarray[source]¶
Helper function to clean up isolated ones in nonwear value array.
This function finds isolated ones in the nonwear value array and sets them to 2 if they are surrounded by values > 1.
- Parameters:
nonwear_value_array – The nonwear value array that needs to be cleaned up. It is a 1D numpy array.
- Returns:
The modified nonwear value array.
- wristpy.processing.metrics._compute_nonwear_value_array(grouped_acceleration: DataFrame, n_short_epoch_in_long_epoch: int, std_criteria: float) ndarray[source]¶
Helper function to calculate the nonwear value array.
This function calculates the nonwear value array based on the GGIR 2023 methodology. It computes the nonwear value for each axis, based on the acceleration data that makes up one long epoch window. That nonwear value is then applied to all the short windows that make up the long window. It iterates forward by one short_window length and repeats the process. For the overlapping short windows, the maximum nonwear value is kept and is assigned to the nonwear value array.
- Parameters:
grouped_acceleration – The acceleration data grouped into short windows.
n_short_epoch_in_long_epoch – Number of short epochs that makeup one long epoch.
std_criteria – Threshold criteria for standard deviation.
- Returns:
Non-wear value array.
- wristpy.processing.metrics._compute_nonwear_value_per_axis(axis_acceleration_data: Series, std_criteria: float) bool[source]¶
Helper function to calculate the nonwear criteria per axis.
- Parameters:
axis_acceleration_data – The long window acceleration data for one axis. It is a pl.Series chunked into short windows where each row is a list of the acceleration data of one axis (length of each list is the number of samples that make up short_epoch_length in seconds).
std_criteria – Threshold criteria for standard deviation
- Returns:
Non-wear value for the axis.
- wristpy.processing.metrics._group_acceleration_data_by_time(acceleration: Measurement, window_length: int) DataFrame[source]¶
Helper function to group the acceleration data by short windows.
- Parameters:
acceleration – The Measurement instance that contains calibrated acceleration.
window_length – The window size, in seconds.
- Returns:
A polars DataFrame with the acceleration data grouped by window_length.
- wristpy.processing.metrics._pre_process_temperature(temperature: Measurement, acceleration: Measurement) DataFrame[source]¶
Pre-process temperature data for non-wear detection.
This function is used specificall for the CTA, it ensures that the temperature and acceleration Measurements end at the same time (due to the inherent sampling rate differences on the device), upsamples the temperature data to 1 second intervals and then low-pass filters the data by applying a 2 minute rolling mean.
- Parameters:
temperature – The Measurement instance that contains the temperature data.
acceleration – The Measurement instance that contains the acceleration data.
- Returns:
A polars DataFrame with the pre-processed temperature data.
- Raises:
ValueError – If the acceleration data ends before the temperature data.
- wristpy.processing.metrics.actigraph_activity_counts(acceleration: Measurement, epoch_length: float = 5.0, name: str | None = None) Measurement[source]¶
Compute Actigraph acitivty counts.
This function computes the Actigraph activity counts based on [1]. The acceleration data is downsample to 30Hz, bandpass filtered, scaled, and then thresholded. The counts are then summed along each axis for the chosen epoch length.
- Parameters:
acceleration – The calibrated acceleration data.
epoch_length – The length of the epoch in seconds, defaults to 60s.
name – the name of the Measurement object
- Returns:
The activity counts as a Measurement object.
References
[1] A. Neishabouri et al., “Quantification of acceleration as activity counts in ActiGraph wearable,” Sci Rep, vol. 12, no. 1, Art. no. 1, Jul. 2022, doi: 10.1038/s41598-022-16003-x.
- wristpy.processing.metrics.angle_relative_to_horizontal(acceleration: Measurement, epoch_length: float = 5.0) Measurement[source]¶
Calculate the angle of the acceleration vector relative to the horizontal plane.
The data can be downsampled to a temporal resolution of epoch_length seconds.
- Parameters:
acceleration – the three-dimensional accelerometer data. A Measurement object,
measurements (it will have two attributes. 1))
three-dimensional (containing the)
time (accelerometer data in a np.array and 2))
containing (a pl.Series)
objects. (datetime.datetime)
epoch_length – The temporal resolution of the downsampled anglez, in seconds. Must be greater than 0. Defaults to 5.0s.
- Returns:
A Measurement instance containing the values of the angle relative to the horizontal plane and the associated timestamps taken from the input unaltered. The angle is measured in degrees.
- wristpy.processing.metrics.combined_temp_accel_detect_nonwear(acceleration: Measurement, temperature: Measurement, std_criteria: float = 0.013, temperature_threshold: float = 26.0) Measurement[source]¶
This function uses the both temperature and acceleration data to detect non-wear.
The function implements the algorithm described in the Zhou 2015 paper. Briefly, data is chunked into one minute windows. Each windows is classified as “wear” or “non-wear”, here denoted by 0 and 1, respectively.
- Parameters:
acceleration – The Measurement instance that contains calibrated acceleration.
temperature – The Measurement instance that contains the temperature data.
std_criteria – Threshold criteria for standard deviation.
temperature_threshold – The temperature threshold for non-wear detection.
- Returns:
A new Measurement instance with the non-wear flag and corresponding timestamps. The temporal resolutions is one minute.
References
Zhou S, Hill RA, Morgan K, et al, Classification of accelerometer wear and non-wear events in seconds for monitoring free-living physical activityBMJ Open 2015; 5:e007447. doi: 10.1136/bmjopen-2014-007447.
- wristpy.processing.metrics.detach_nonwear(acceleration: Measurement, temperature: Measurement, std_criteria: float = 0.013) Measurement[source]¶
This function implements the scikit DETACH algorithm for non-wear detection.
The nonwear array is downsampled to 60 second resolution.
- Parameters:
acceleration – The Measurement instance that contains calibrated acceleration.
temperature – The Measurement instance that contains the temperature data.
std_criteria – The acceleration STD threshold for non-wear detection.
- Returns:
A new Measurement instance with the non-wear flag and corresponding timestamps. The temporal resolutions is one minute.
References
A. Vert et al., “Detecting accelerometer non-wear periods using change in acceleration combined with rate-of-change in temperature,” BMC Medical Research Methodology, vol. 22, no. 1, p. 147, May 2022, doi: 10.1186/s12874-022-01633-6.
- wristpy.processing.metrics.detect_nonwear(acceleration: Measurement, short_epoch_length: int = 900, n_short_epoch_in_long_epoch: int = 4, std_criteria: float = 0.013) Measurement[source]¶
Set non_wear_flag based on accelerometer data.
This implements a modified version of the GGIR “2023” non-wear detection algorithm. Briefly, the algorithm, creates a sliding window of long epoch length that steps forward by the short epoch length. The long epoch length is an integer multiple of the short epoch length, that can be specified by the user. It checks if the acceleration data in that long window, for each axis, meets the criteria threshold for the standard deviation of acceleration values to compute a non-wear value. The total non-wear value (0, 1, 2, 3) for the long window is the sum of each axis. The non-wear value is applied to all the short windows that make up the long window. Additionally, as the majority of the short windows are part of multiple long windows, the value of a short window is updated to the maximum nonwear value from these overlaps. Finally, there is a pass to find isolated “1s” in the non-wear value, and set them to 2 if surrounded by > 1 values. The non-wear flag is set to 1 (true) if the non-wear value is >= 2, and 0 (false) otherwise.
- Parameters:
acceleration – The Measurement instance that contains the calibrated acceleration data.
short_epoch_length – The short window size, in seconds.
n_short_epoch_in_long_epoch – Number of short epochs that makeup one long epoch.
std_criteria – Threshold criteria for standard deviation.
- Returns:
A new Measurement instance with the non-wear flag and corresponding timestamps.
- wristpy.processing.metrics.euclidean_norm_minus_one(acceleration: Measurement, epoch_length: float = 5.0, name: str | None = None) Measurement[source]¶
Compute ENMO, the Euclidean Norm Minus One (1 standard gravity unit).
Negative values of ENMO are set to zero because ENMO is meant as a measure of physival activity. Negative values steming from imperfect calibration or noise from the device would have no meaningful interpretation in this context and would be detrimental to the intended analysis.
The data can be downsampled to a temporal resolution of epoch_length seconds.
- Parameters:
acceleration – the three-dimensional accelerometer data. A Measurement object,
measurements (it will have two attributes. 1))
three-dimensional (containing the)
time (accelerometer data in an np.array and 2))
containing (a pl.Series)
objects. (datetime.datetime)
epoch_length – The temporal resolution of the downsampled enmo, in seconds. Must be greater than 0. Defaults to 5.0s.
name – The name of the Measurement object.
- Returns:
A Measurement object containing the calculated ENMO values and the associated time stamps taken from the input.
- wristpy.processing.metrics.mean_amplitude_deviation(acceleration: Measurement, epoch_length: float = 5.0, name: str | None = None) Measurement[source]¶
Calculate the mean amplitude deviation of the acceleration data.
An alternative to ENMO to quantify the intensity of physical activity. It is calculated as the mean of the absolute difference between acceleration values and the mean of those acceleration values in a 5s window.
- Parameters:
acceleration – the calibrated acceleration data.
epoch_length – The length of the window in seconds.
name – The name of the Measurement object
- Returns:
A new Measurement object containing the MAD values.
References
Vähä-Ypyä H, Vasankari T, Husu P, Suni J, Sievänen H. A universal, accurate intensity-based classification of different physical activities using raw data of accelerometer. Clin Physiol Funct Imaging. 2015 Jan;35(1):64-70. doi: 10.1111/cpf.12127. Epub 2014 Jan 7. PMID: 24393233.
- wristpy.processing.metrics.monitor_independent_movement_summary_units(acceleration: Measurement, combination_method: Literal['sum', 'vector_magnitude'] = 'sum', epoch: float = 60.0, interpolation_frequency: int = 100, dynamic_range: tuple[float, float] = (-8.0, 8.0), cutoffs: Tuple[float, float] = (0.2, 5.0), order: int = 4, *, rectify: bool = True, name: str | None = None) Measurement[source]¶
Calculates monitor independent movement summary units (MIMS).
This function processes raw acceleration data to calculate MIMS units, based on the original R implementation by John et al.(2019). The main processing steps as described in the original paper are interpolation (100Hz by default), extrapolation of any values that went beyond the dynamic range of the device, filtering using a 4th order butterworth filter, aggregation by calculating the area under the curve over a given epoch, and finally truncation of small values. The MIMS value per axis is then combined through a sum or vector magnitude, and returned as a single vector.
- Parameters:
acceleration – Triaxial acceleration data to be processed.
combination_method – Method to combine MIMS values across axes.
epoch – Duration over which each MIMS value will be calculated. Measured in seconds.
interpolation_frequency – Frequency to interpolate acceleration data, defaults to 100 Hz as described in John et al. 2019.
dynamic_range – Tuple specifying the minimum and maximum values (in g) of the accelerometer’s dynamic range.
cutoffs – Tuple specifying the low and high cutoff frequencies (in Hz) for the Butterworth filter.
order – Order of the Butterworth filter.
rectify – Specifies if data should be rectified before integration. If True any value below -150 will assign the value of that axis to -1 for that epoch. Additionally the absolute value of accelerometer data will be used for integration.
name – The name of the Measurement object.
- Returns:
Processed MIMS values after combining the values of each axis with the provided method.
References
John, D., Tang, Q., Albinali, F. and Intille, S., 2019. An Open-Source Monitor-Independent Movement Summary for Accelerometer Data Processing. Journal for the Measurement of Physical Behaviour, 2(4), pp.268-281.