wristpy.processing.calibration¶

Calibrate accelerometer data.

Functions

`cast`(typ, val)	Cast a value to a type.
`dataclass`([cls, init, repr, eq, order, ...])	Add dunder methods based on the fields defined in the class.

Classes

`AbstractCalibrator`()	Abstract class defining the interface for the different calibration methods.
`CalibrationDispatcher`(name)	Class used to select and implement appropriate calibrator.
`ConstrainedMinimizationCalibration`([...])	Calibrates accelerometer data using the default wristpy method.
`Generator`()
`GgirCalibration`([chunked, min_acceleration, ...])	Implements the GGIR calibration on accelerometer data.
`LinearTransformation`(scale, offset)	Data class that contains scale and offset values for calibration.
`datetime`(year, month, day[, hour[, minute[, ...)	The year, month and day arguments are required.

class wristpy.processing.calibration.AbstractCalibrator[source]¶

Bases: ABC

Abstract class defining the interface for the different calibration methods.

abstract run_calibration(acceleration: Measurement) → Measurement[source]¶

The calibration method must contain a run_calibration function.

The function must take the acceleration measurement object as input and return a measurement object that contains the calibrated acceleration data.

class wristpy.processing.calibration.CalibrationDispatcher(name: Literal['ggir', 'gradient'])[source]¶

Bases: object

Class used to select and implement appropriate calibrator.

run(acceleration: Measurement, *, return_input_on_error: bool = False) → Measurement[source]¶

Runs calibration on acceleration data.

Parameters:

acceleration – the accelerometer data containing x,y,z axis data and time stamps.
return_input_on_error – If true, will return the input acceleration data if calibration fails. If false, will raise an exception.

Returns:

A Measurement object that contains the calibrated acceleration data.

Raises:

CalibrationError – If the calibration process fails to converge or the final error exceeds the max_calibration_error threshold.
SphereCriteriaError – If the sphere is not sufficiently populated, i.e. every axis does not have at least 1 value both above and below the + and - value of min_acceleraiton.
NoMotionError – If no portions of data meet no motion criteria as defined by no_motion_check.

class wristpy.processing.calibration.ConstrainedMinimizationCalibration(no_motion_threshold: float = 0.013, max_iterations: int = 1000, max_calibration_error: float = 0.01)[source]¶

Bases: AbstractCalibrator

Calibrates accelerometer data using the default wristpy method.

This is a modification of the method proposed by Van Hees et al. (2014), in which we use all available data, make use of the scipy optimize minimize function to solve for the scaling and offset parameters of a LinearTransformation that will be applied to the data. The minimization function looks to minimize the error between the no_motion_data and the unit sphere.

acceleration¶: The accelerometer data that we want to calibrate.

no_motion_threshold¶: Minimum standard deviation for no-motion detection.

_closest_point_fit(no_motion_data: ndarray) → LinearTransformation[source]¶

Find linear transformation parameters that minimizes distance to unit sphere.

This function implements the scipy optimize.minimize function to find the optimal scale and offset parameters that will minimize the error function, which is defined as the distance of the no_motion acceleration data from the unit sphere (where the unit sphere represents the ideal data points under 1g acceleration due to Earth’s gravity). The initial guess for the scale and offset are chosen as 1/0, we provide constrained bounds for the scale and offset parameters to avoid the case where the scale can be set to 0 and offset to 1/sqrt(3) (exact unit sphere).

Parameters:: no_motion_data – The acceleration data during periods of no motion.
Returns:: A LinearTransformation object with scale and offset parameters to be applied to acceleration data for calibration.
Raises:: CalibrationError – If the optimization process fails to converge or if the calibration error is not sufficiently minimized.

run_calibration(acceleration: Measurement) → Measurement[source]¶

Runs calibration on acceleration data.

Parameters:: acceleration – the accelerometer data containing x,y,z axis data and time stamps.
Returns:: A Measurement object that contains the calibrated acceleration data.
Raises:: CalibrationError – If the calibration process fails to converge or the final error exceeds the max_calibration_error threshold.

class wristpy.processing.calibration.GgirCalibration(chunked: bool = False, min_acceleration: float = 0.3, min_calibration_hours: int = 72, no_motion_threshold: float = 0.013, max_iterations: int = 1000, error_tolerance: float = 1e-10, max_calibration_error: float = 0.01)[source]¶

Bases: AbstractCalibrator

Implements the GGIR calibration on accelerometer data.

This class implements methods for autocalibrating accelerometer data using either entire dataset or subsets, as determined by the settings. Depending on the settings a scale and offset value is determined and applied to the data which, if successful, is returned to the user.

chunked¶: If true will perform calibration on subsets of data if false will calibrate on entire dataset.

min_acceleration¶: Minimum acceleration for sphere criteria, in g-force.

min_calibration_hours¶: Minimum hours of data required for calibration.

no_motion_threshold¶: Minimum standard deviation for no-motion detection.

max_iterations¶: Maximum number of iterations for optimization.

error_tolerance¶: Tolerance for optimization convergence.

max_calibration_error¶: Threshold for the maximum allowable calibration error.

_calibrate(acceleration: Measurement) → LinearTransformation[source]¶

Calibrates data and returns scale and offset values.

The acceleration data is processed by the _extract_no_motion function, which returns the portions of the data where the subject was still. This data ideally should all have points with a norm of 1. If we take a unit sphere, all the points in no_motion_data should be found along it’s surface. As this is not the case we calibrate by finding offset and scale values that will most closely make the whole of our data lie along this unit sphere. This is done by the _closest_point_fit function. We then transform the data by applying the scale and offset values we have found, and if the error has been sufficiently reduced, these values are returned. If not calibration fails and raises a calibration error.

Parameters:: acceleration – the accelerometer data containing x,y,z axis data and time stamps.
Returns:: A LinearTransformation object with scale and offset attributes to be applied to acceleration data for calibration.
Raises:: CalibrationError – If the calibration process fails to converge or the final error exceeds the max_calibration_error threshold.

References

van Hees VT, Fang Z, Langford J, et al. Autocalibration of accelerometer data for free-living physical activity assessment using local gravity and temperature: an evaluation on four continents. J Appl Physiol (1985) 2014 Oct 1;117(7):738-44. doi: 10.1152/japplphysiol.00421.2014.

_chunked_calibration(acceleration: Measurement) → LinearTransformation[source]¶

Chunks the data into subsets, to calibrate on smaller sections of data.

The first chunk is determined by the min_calibration_hours. Should calibration fail on that subset of data, additional chunks of data are added to attempt calibration on. This continues until all data is tried, or calibration succeeds. Chunks are added in increments of 12 hours.

Parameters:: acceleration – the accelerometer data containing x,y,z axis data and time stamps.
Returns:: A LinearTransformation object with scale and offset attributes to be applied to acceleration data for calibration.
Raises:: CalibrationError – If all possible chunks have been used and the calibration process fails to get below the max_calibration_error threshold.

_closest_point_fit(no_motion_data: ndarray) → LinearTransformation[source]¶

Applies closest point fit to no motion data to calibrated accelerometer data.

This method implements an iterative algorithm that finds the optimal scale and offset for calibrating accelerometer data. The ndarray it processes contains the periods of “no motion” identified by the _extract_no_motion method. This data is then fit to an idealized unit sphere which represents the accelerometer data under noiseless conditions. The scale and offset derived from this process are used to calibrate our data along each axis.

Parameters:

no_motion_data – The acceleration data during periods of no motion, in order to determine scale and offset.

Returns:

A LinearTransformation object with scale and offset attributes to be applied to acceleration data for calibration.

Raises:

SphereCriteriaError – If the sphere is not sufficiently populated, i.e. every axis does not have at least 1 value both above and below the + and - value of min_acceleraiton.
ZeroScaleError – Numerical instability inherent to the algorithm may cause values of the scale vector to tend toward zero under certain conditions. This will cause calibration to fail.

References

_get_chunk(acceleration: Measurement) → Generator[Measurement, None, None][source]¶

Takes a subset of acceleration data to be used for calibration.

Parameters:: acceleration – the accelerometer data containing x,y,z axis data and time stamps.
Returns:: The minimum hours of accelerometer data + additional 12 hour chunks of data every time the generator function is called.

static _get_sampling_rate(timestamps: Series) → int[source]¶

Get the sampling rate.

Parameters:

timestamps – polars series of datetime objects representing the time points
data. (of each sample in the acceleration)

Returns:

sampling rate in Hz.

run_calibration(acceleration: Measurement) → Measurement[source]¶

Runs calibration on acceleration data based on settings.

If the chunked argument is set to true, it will run calibration on an initial chunk of the data the size of which is set to min_calibration_hours. If it fails to calibrate based on this subset, it will add 12-hour chunks to the subset until calibration succeeds, or fails on the entire dataset. Otherwise, if chunked is false (default) calibration will be conducted on the whole of the dataset. Calibration is successful when scale and offset values, that sufficiently minimize error when applied to the data, are found. The scale and offset values are then applied to every data point in the dataset which is then returned as calibrated models.Measurement object.

Parameters:

acceleration – the accelerometer data containing x,y,z axis data and time stamps.

Returns:

A Measurement object that contains the calibrated acceleration data.

Raises:

ValueError – If the acceleration data does not meet the specified minimum hours of data as given by min_calibration_hours.
SphereCriteriaError – If the sphere is not sufficiently populated, i.e. every axis does not have at least 1 value both above and below the + and - value of min_acceleraiton.
CalibrationError – If the calibration process fails to get below the max_calibration_error threshold.

class wristpy.processing.calibration.LinearTransformation(scale: ndarray, offset: ndarray)[source]¶

Bases: object

Data class that contains scale and offset values for calibration.

scale¶

3-element 1-D array of floats used to scale accelerameter data for calibration. Each element corresponds to the scaling factor for each axis.

Type:: numpy.ndarray

offset¶

3-element 1-D array of floats used to offset accelerameter data for calibration. Each element corresponds to the offset value for each axis.

Type:: numpy.ndarray

offset: ndarray¶

scale: ndarray¶

wristpy.processing.calibration._extract_no_motion(acceleration: Measurement, no_motion_threshold: float = 0.013) → ndarray[source]¶

Identifies areas of stillness using standard deviation and mean.

The function first takes a moving standard deviation and a moving mean of the acceleration data in 10 second epochs. These ndarrays are then used to identify the portions of the data that have a standard deviation below no_motion_threshold and a mean value < 2. These epochs are determined to be the periods where the accelerometer was influenced by no motion beyond the force of gravity. If periods of no motion are found, the ndarray is returned, to be fit to the idealized unit sphere for the purposes of calibration.

Parameters:

acceleration – the accelerometer data containing x,y,z axis data and time stamps.
no_motion_threshold – Threshold for the standard deviaton of acceleration data used to find periods of no motion.

Returns:

An ndarray containing the accelerometer data determined to have no motion.

Raises:

NoMotionError – If no portions of data meet no motion criteria as defined by no_motion_check.

References