wristpy.processing.mims

Calculate Monitor Independent Movement Summary Units.

Functions

aggregate_mims(acceleration[, epoch, ...])	Calculate the area under the curve(AUC), per epoch, per axis.
butterworth_filter(acceleration[, ...])	Apply butterworth IIR filter to acceleration data.
combine_mims(acceleration[, combination_method])	Combine MIMS values of xyz axis into one MIMS value.
extrapolate_points(acceleration[, ...])	Identify maxed out values, and extrapolate points.
interpolate_measure(acceleration[, ...])	Interpolate the measure to a new sampling rate using natural cubic spline.

wristpy.processing.mims._aggregate_epoch(group: DataFrame, epoch: float = 60.0, sampling_rate: int = 100, *, rectify: bool = True) → DataFrame

Calculate the area under the curve(AUC), per epoch.

Parameters:

• group – The epoch given by .map_groups()

• epoch – The desired epoch length in seconds that data will be aggregated over. Defaults to 1 minute as per MIMS-unit paper.

• sampling_rate – The sampling rate of the accelerometer data in Hz.

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

Returns:

A polars DataFrame containing the XYZ AUC values for one epoch.

wristpy.processing.mims._align_edges(marker_length: int, left: ndarray, right: ndarray, out_of_range_threshold: int, sign: Literal['hill', 'valley']) → DataFrame

Aligns left and right edges of maxed-out regions and handles edge cases.

Parameters:

• marker_length – Length of marker array.

• left – 1D vector of indices indicating the left edge of a potential maxed-out region.

• right – 1D vector of indices indicating the right edge of a potential maxed-out region.

• out_of_range_threshold – The number of samples that determines if an un matched edge extends beyond the data range, or if the edge is spurious. Typically 5 seconds worth of data.

• sign – Indicates if maxed out region is a hill or valley.

Returns:

A DataFrame with the left and right edges of each maxed-out region.

Raises:

• ValueError – If the difference in length between the left and right arrays is

• greater than 1. –

wristpy.processing.mims._brute_force_k(standard_deviation: float, k_max: float = 0.5, k_min: float = 0.001, k_step: float = 0.001, scale: float = 1.0, target_probability: float = 0.95) → float

Find the shape parameter(k) for the gamma distribution.

Parameters:

• standard_deviation – The point at which to evaluate the gamma cumulative distribution function, should be 3 times the noise.

• k_max – Maximum value for the shape parameter search range. Default is 0.5.

• k_min – Minimum value for the shape parameter search range. Default is 0.001.

• k_step – Step size for the shape parameter search.

• scale – Scale value (theta) for gamma distribution. Typically set at 1.

• target_probability – Threshold used in determining the shape parameter (k) of the gamma distribution. Probability that a value 3 standard deviations from the buffer zone is maxed-out.

• scale – Scale value (theta) for gamma distribution. Typically set at 1.

Returns:

The optimal shape parameter that makes the gamma CDF at the given standard deviation approximately equal to the target probability.

wristpy.processing.mims._extrapolate_edges(marker: ndarray, confidence_threshold: float = 0.5, sampling_rate: int = 100) → DataFrame

Find edges of maxed out regions and identify them as hills(+) or valleys (-).

Parameters:

• marker – Array containing values that mark the probability that each sample is maxed-out. Values close to ±1 indicate high likelihood that the value is near the limit of the dynamic range, with the sign indicating if it’s near the upper bound, or lower bound. Values close to zero indicate low likelihood of being near range limit.

• confidence_threshold – Threshold for what constitutes a significant change in marker values.

• sampling_rate – Sampling rate of acceleration data, typically 100hz following interpolation.

Returns:

DataFrame containing indices for hills and valleys.

wristpy.processing.mims._extrapolate_fit(axis: ndarray, time_numeric: ndarray, marker: ndarray, neighbors: DataFrame, smoothing: float = 0.6, neighborhood_size: float = 0.05, sampling_rate: int = 100) → List[Tuple[float, float]]

Extrapolate peak of maxed regions by fitting weighted splines on nearby points.

Parameters:

• axis – Original acceleration data along one axis.

• time_numeric – Time series data given in epoch time (ns).

• marker – Array the same size as axis, containing values that mark the probability that each sample is maxed-out. Values close to ±1 indicate high likelihood that the value is near the limit of the dynamic range, with the sign indicating if it’s near the upper bound, or lower bound. Values close to zero indicate low likelihood of being near range limit.

• neighbors – A polars DataFrame containing the start and end indices for the maxed out regions, as well as the neighborhoods to the left and right of regions.

• smoothing – Smoothing value for UniveriateSpline. Determines how closely the spline adheres to the data points. Higher values will give a smoother result.

• neighborhood_size – Duration of neighborhood in seconds to use around each maxed-out region for regression fitting. Default is 0.05 (50ms).

• sampling_rate – Sampling rate, default is 100Hz

Returns:

A List of Tuples representing the peaks of maxed out regions as (timestamp, value) pairs. Times are given in epoch time (ns).

wristpy.processing.mims._extrapolate_interpolate(axis: ndarray, time_numeric: ndarray, marker: ndarray, points: list, confidence_threshold: float = 0.5) → ndarray

Interpolate the original signal with extrapolated points.

Parameters:

• axis – Original acceleration data along one axis.

• time_numeric – Time series data given in epoch time (ns).

• marker – Array the same size as axis, containing values that mark the probability that each sample is maxed-out. Values close to ±1 indicate high likelihood that the value is near the limit of the dynamic range, with the sign indicating if it’s near the upper bound, or lower bound. Values close to zero indicate low likelihood of being near range limit.

• points – List of tuples with extrapolated points (time, value). Times are given in epoch time (ns).

• confidence_threshold – Threshold for maxed-out identification.

Returns:

np.ndarray of axis data, with extrapolated values.

wristpy.processing.mims._extrapolate_neighbors(marker: ndarray, confidence_threshold: float = 0.5, neighborhood_size: float = 0.05, sampling_rate: int = 100) → DataFrame

Find neighborhoods around maxed-out regions for regression fitting.

Parameters:

• marker – Array containing values that mark the probability that each sample is maxed-out. Values close to ±1 indicate high likelihood that the value is near the limit of the dynamic range, with the sign indicating if it’s near the upper bound, or lower bound. Values close to zero indicate low likelihood of being near range limit.

• confidence_threshold – Threshold for what constitutes a significant change in marker values.

• neighborhood_size – Duration of neighborhood in seconds to use around each maxed-out region for regression fitting. Default is 0.05 (50ms).

• sampling_rate – The sampling rate of the data in Hz. Default is 100Hz as data should be interpolated to 100hz prior to this step.

Returns:

DataFrame containing the indices of maxed-out regions (start, end) and their expanded neighborhoods (left_neighborhood, right_neighborhood). A value of -1 indicates a boundary case where the region extends to the beginning or end of the data.

wristpy.processing.mims._find_markers(axis: ndarray, dynamic_range: Tuple[float, float], noise: float = 0.03, scale: float = 1.0, target_probability: float = 0.95) → ndarray

Determine the likelihood that each sample is near the limits of the device range.

Parameters:

• axis – Acceleration data along one axis.

• dynamic_range – Tuple of floats indicating the device’s value range. This information can be gathered from watch metadata.

• noise – Typical noise value for device.

• scale – Scale value (theta) for gamma distribution. Typically set at 1.

• target_probability – Threshold used in determining the shape parameter (k) of the gamma distribution. Probability that a value 3 standard deviations from the buffer zone is maxed-out.

Returns:

Array indicating the likelihood that corresponding value in the axis data is ‘maxed-out’.

wristpy.processing.mims._fit_weighted(axis: ndarray, time_numeric: ndarray, marker: ndarray, start: int, end: int, smoothing: float = 0.6, neighborhood_size: float = 0.05, sampling_rate: int = 100) → UnivariateSpline | None

Fit weighted spline regression model to a section of the data.

Parameters:

• axis – Original acceleration data along one axis.

• time_numeric – Time series data given in epoch time (ns).

• marker – Array the same size as axis, containing values that mark the probability that each sample is maxed-out. Values close to ±1 indicate high likelihood that the value is near the limit of the dynamic range, with the sign indicating if it’s near the upper bound, or lower bound. Values close to zero indicate low likelihood of being near range limit.

• start – Index marking the beginning of the maxed out zone.

• end – Index marking end of maxed out zone.

• smoothing – Smoothing value for UniveriateSpline. Determines how closely the spline adheres to the data points. Higher values will give a smoother result. Default is 0.6 as optimized in the MIMS-unit paper.

• neighborhood_size – Duration of neighborhood in seconds to use around each maxed-out region for regression fitting. Default is 0.05 (50ms).

• sampling_rate – Sampling rate, default is 100Hz

Returns:

A UnivariateSpline function fitted to the data segment with weights based on the probability of not being maxed-out. Returns None if the input data is insufficient or invalid (-1).

wristpy.processing.mims.aggregate_mims(acceleration: Measurement, epoch: float = 60.0, sampling_rate: int = 100, *, rectify: bool = True, truncate: bool = True) → Measurement

Calculate the area under the curve(AUC), per epoch, per axis.

When an epoch has less than 90% of the expected values (based on the sampling rate and epoch length), the AUC for that epoch is given as -1 for each axis. If rectify is True, any axis with values below -150 will have the AUC value for that axis be -1 for that epoch. Finally, following integration, any value greater than (16 * sampling_rate * epoch) will be set to -1.

Parameters:

• acceleration – Acceleration data to be aggregated.

• epoch – The desired epoch length in seconds that data will be aggregated over.

• sampling_rate – The sampling rate of the accelerometer data in Hz.

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

• truncate – Specifies if data <= 0.001 should be truncated to 0.

Returns:

A models.Measurement instance with the area under the curve values for each epoch.

wristpy.processing.mims.butterworth_filter(acceleration: Measurement, sampling_rate: int = 100, cutoffs: tuple[float, float] = (0.2, 5.0), order: int = 4) → Measurement

Apply butterworth IIR filter to acceleration data.

Implements third portion of MIMS algorithm following interpolate, and extrapolation.

Parameters:

• acceleration – Acceleration data to be filtered.

• sampling_rate – Sampling rate of acceleration data in Hz.

• cutoffs – Cutoff values for bandpass filter.

• order – Order of the filter, defaults to 4th order.

Returns:

Acceleration Measurement of filtered data.

wristpy.processing.mims.combine_mims(acceleration: Measurement, combination_method: Literal['sum', 'vector_magnitude'] = 'sum') → Measurement

Combine MIMS values of xyz axis into one MIMS value.

If any value in an epoch is -1, the ‘combined_mims’ value for that epoch will be set to -1 to flag it as an invalid epoch.

Parameters:

• acceleration – An object containing per-axis MIMS measurements and their corresponding timestamps.

• combination_method – The method to combine MIMS values across axes. Defaults to “sum”.

Returns:

A Measurement object with combined MIMS values and corresponding timestamps.

wristpy.processing.mims.extrapolate_points(acceleration: Measurement, dynamic_range: Tuple[float, float] = (-8.0, 8.0), noise: float = 0.03, smoothing: float = 0.6, scale: float = 1, target_probability: float = 0.95, confidence_threshold: float = 0.5, neighborhood_size: float = 0.05, sampling_rate: int = 100) → Measurement

Identify maxed out values, and extrapolate points.

Parameters:

• acceleration – Acceleration data that has been interpolated to 100Hz.

• dynamic_range – Dynamic range of device used. This information can be gathered from device metadata.

• noise – Device noise level.

• smoothing – Smoothing parameter for spline function. A value of 0 fits the data exactly, higher values will fit the data more smoothly.

• scale – Theta value, scale parameter for gamma distribution.

• target_probability – Threshold used in determining the shape parameter (k) of the gamma distribution. Probability that a value 3 standard deviations from the buffer zone is maxed-out.

• confidence_threshold – Threshold for what constitutes a major jump or drop in value.

• neighborhood_size – Duration of neighborhood in seconds. This parameter determines how much data on each side of the maxed-out region is used for fitting the local regression model. The parameter is used to calculate the number of points to create in the oversampled data (n_over).

• sampling_rate – The sampling rate in Hz. Assumed to take place after interpolation so it will typically be 100.

Returns:

A Measurement object with maxed out regions replaced with extrapolated values.

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.

wristpy.processing.mims.interpolate_measure(acceleration: Measurement, new_frequency: int = 100) → Measurement

Interpolate the measure to a new sampling rate using natural cubic spline.

Parameters:

• acceleration – Accelerometer data and associated timestamps.

• new_frequency – The new frequency the measure will be interpolated to in Hz. For the purposes of the MIMS algorithm defaults to 100Hz.

Returns:

A Measurement object with interpolated acceleration data.