wristpy.core.orchestrator

Python based runner.

Functions

run(input[, output, thresholds, calibrator, ...])

Runs main processing steps for wristpy on single files, or directories.
wristpy.core.orchestrator._compute_activity(acceleration: Measurement, activity_metric: Literal['ag_count', 'mad', 'enmo', 'mims'], epoch_length: float, dynamic_range: tuple[float, float] | None) → Measurement[source]

This is a helper function to organize the computation of the activity metric.

This function organizes the logic for computing the requested physical activity metric at the desired temporal resolution.

Parameters:

  • acceleration – The acceleration data to compute the activity metric from.

  • activity_metric – The metric to be used for physical activity categorization.

  • epoch_length – The temporal resolution in seconds, the data will be down sampled to.

  • dynamic_range – Tuple of the minimum and maximum accelerometer values. This argument is only relevant to the mims metric. Values are taken from watch metadata, if no metadata could be extracted, the default values of (-8,8) are used.

Returns:

A Measurement object with the computed physical activity metric.

wristpy.core.orchestrator._run_directory(input: Path, output: Path | None = None, thresholds: Sequence[Tuple[float, float, float]] | None = None, calibrator: None | Literal['ggir', 'gradient'] = 'gradient', epoch_length: float = 5, nonwear_algorithm: Sequence[Literal['ggir', 'cta', 'detach']] = ['ggir'], verbosity: int = 30, output_filetype: Literal['.csv', '.parquet'] = '.csv', activity_metric: Sequence[Literal['enmo', 'mad', 'ag_count', 'mims']] = ['enmo']) → Dict[str, OrchestratorResults][source]

Runs main processing steps for wristpy on directories.

The _run_directory() function will execute the _run_file() function on entire directories. The input and output (if any) paths must be directories. Output file names will be derived from input file names.

Parameters:

  • input – Path to the input directory of files to be read. Currently, this supports .bin and .gt3x

  • output – Path to directory data will be saved to.

  • thresholds – The cut points for the light, moderate, and vigorous thresholds, given in that order. One threshold tuple must be provided for each activity metric, in the same order the metrics were specified. To use default values for all metrics, leave thresholds as None. Values must be ascending, unique, and greater than 0. Default values are optimized for subjects ages 7-11 [1][2].

  • calibrator – The calibrator to be used on the input data.

  • epoch_length – The temporal resolution in seconds, the data will be down sampled to. It must be > 0.0.

  • nonwear_algorithm – The algorithm to be used for nonwear detection.

  • verbosity – The logging level for the logger.

  • output_filetype – Specifies the data format for the save files.

  • activity_metric – The metric(s) to be used for physical activity categorization. Multiple metrics can be specified as a sequence.

Returns:

All calculated data in a save ready format as a dictionary of OrchestratorResults objects.

Raises:

  • ValueError – If the output given is not a directory.

  • ValueError – If the output_filetype is not a valid type.

  • FileNotFoundError – If the input directory contained no files of a valid type.

References

[1] Hildebrand, M., et al. (2014). Age group comparability of raw accelerometer output from wrist- and hip-worn monitors. Medicine and Science in Sports and Exercise, 46(9), 1816-1824. [2] Karas M, Muschelli J, Leroux A, Urbanek J, Wanigatunga A, Bai J, Crainiceanu C, Schrack J Comparison of Accelerometry-Based Measures of Physical Activity: Retrospective Observational Data Analysis Study JMIR Mhealth Uhealth 2022;10(7):e38077 URL: https://mhealth.jmir.org/2022/7/e38077 DOI: 10.2196/38077

wristpy.core.orchestrator._run_file(input: Path, output: Path | None = None, thresholds: Sequence[Tuple[float, float, float]] | None = None, calibrator: None | Literal['ggir', 'gradient'] = 'gradient', epoch_length: float = 5.0, activity_metric: Sequence[Literal['enmo', 'mad', 'ag_count', 'mims']] = ['enmo'], nonwear_algorithm: Sequence[Literal['ggir', 'cta', 'detach']] = ['ggir'], verbosity: int = 30) → OrchestratorResults[source]

Runs main processing steps for wristpy and returns data for analysis.

The run_file() function will provide the user with the specified physical activity metric(s), anglez, physical activity levels, detected sleep periods, and nonwear data. All measures will be in the same temporal resolution. Users may choose from ‘ggir’ and ‘gradient’ calibration methods, or enter None to proceed without calibration.

Parameters:

  • input – Path to the input file to be read. Currently, this supports .bin and .gt3x

  • output – Path to save data to. The path should end in the save file name in either .csv or .parquet formats.

  • thresholds – The cut points for the light, moderate, and vigorous thresholds, given in that order. One threshold tuple must be provided for each activity metric, in the same order the metrics were specified. To use default values for all metrics, leave thresholds as None. Values must be ascending, unique, and greater than 0. Default values are optimized for subjects ages 7-11 [1]-[3].

  • calibrator – The calibrator to be used on the input data.

  • epoch_length – The temporal resolution in seconds, the data will be down sampled to. It must be > 0.0.

  • activity_metric – The metric(s) to be used for physical activity categorization. Multiple metrics can be specified as a sequence.

  • nonwear_algorithm – The algorithm to be used for nonwear detection. A sequence of algorithms can be provided. If so, a majority vote will be taken.

  • verbosity – The logging level for the logger.

Returns:

All calculated data in a save ready format as a OrchestratorResults object.

Raises:

  • ValueError – If the number of physical activity thresholds does not match the number of provided activity metrics.

  • ValueError – If the physical activity thresholds are not unique or not in ascending order.

  • ValueError – If an invalid Calibrator is chosen.

  • ValueError – If epoch_length is not greater than 0.

References

[1] Hildebrand, M., et al. (2014). Age group comparability of raw accelerometer output from wrist- and hip-worn monitors. Medicine and Science in Sports and Exercise, 46(9), 1816-1824. [2] Aittasalo, M., Vähä-Ypyä, H., Vasankari, T. et al. Mean amplitude deviation calculated from raw acceleration data: a novel method for classifying the intensity of adolescents’ physical activity irrespective of accelerometer brand. BMC Sports Sci Med Rehabil 7, 18 (2015). https://doi.org/10.1186/s13102-015-0010-0. [3] Karas M, Muschelli J, Leroux A, Urbanek J, Wanigatunga A, Bai J, Crainiceanu C, Schrack J Comparison of Accelerometry-Based Measures of Physical Activity: Retrospective Observational Data Analysis Study JMIR Mhealth Uhealth 2022;10(7):e38077 URL: https://mhealth.jmir.org/2022/7/e38077 DOI: 10.2196/38077

wristpy.core.orchestrator.run(input: Path | str, output: str | Path | None = None, thresholds: Sequence[Tuple[float, float, float]] | None = None, calibrator: None | Literal['ggir', 'gradient'] = 'gradient', epoch_length: float = 5, activity_metric: Sequence[Literal['enmo', 'mad', 'ag_count', 'mims']] = ['enmo'], nonwear_algorithm: Sequence[Literal['ggir', 'cta', 'detach']] = ['ggir'], verbosity: int = 30, output_filetype: Literal['.csv', '.parquet'] = '.csv') → OrchestratorResults | Dict[str, OrchestratorResults][source]

Runs main processing steps for wristpy on single files, or directories.

The run() function will execute the run_file() function on individual files, or run_directory() on entire directories. When the input path points to a file, the name of the save file will be taken from the given output path (if any). When the input path points to a directory the output path must be a valid directory as well. Output file names will be derived from original file names in the case of directory processing.

Parameters:

  • input – Path to the input file or directory of files to be read. Currently, this supports .bin and .gt3x

  • output – Path to directory data will be saved to. If processing a single file the path should end in the save file name in either .csv or .parquet formats.

  • thresholds – The cut points for the light, moderate, and vigorous thresholds, given in that order. One threshold tuple must be provided for each activity metric, in the same order the metrics were specified. To use default values for all metrics, leave thresholds as None. Values must be ascending, unique, and greater than 0. Default values are optimized for subjects ages 7-11 [1] [3].

  • calibrator – The calibrator to be used on the input data.

  • epoch_length – The temporal resolution in seconds, the data will be down sampled to. It must be > 0.0.

  • activity_metric – The metric(s) to be used for physical activity categorization. Multiple metrics can be specified as a sequence.

  • nonwear_algorithm – The algorithm to be used for nonwear detection.

  • verbosity – The logging level for the logger.

  • output_filetype – Specifies the data format for the save files. Only used when processing directories.

Returns:

All calculated data in a save ready format as a Results object or as a dictionary of OrchestratorResults objects.

Raises:

  • ValueError – If the number of physical activity thresholds does not match the number of provided activity metrics.

  • ValueError – If the physical activity thresholds are not unique or not in ascending order.

References

[1] Hildebrand, M., et al. (2014). Age group comparability of raw accelerometer output from wrist- and hip-worn monitors. Medicine and Science in Sports and Exercise, 46(9), 1816-1824. [2] Treuth MS, Schmitz K, Catellier DJ, McMurray RG, Murray DM, Almeida MJ, Going S, Norman JE, Pate R. Defining accelerometer thresholds for activity intensities in adolescent girls. Med Sci Sports Exerc. 2004 Jul;36(7):1259-66. PMID: 15235335; PMCID: PMC2423321. [3] Karas M, Muschelli J, Leroux A, Urbanek J, Wanigatunga A, Bai J, Crainiceanu C, Schrack J Comparison of Accelerometry-Based Measures of Physical Activity: Retrospective Observational Data Analysis Study JMIR Mhealth Uhealth 2022;10(7):e38077 URL: https://mhealth.jmir.org/2022/7/e38077 DOI: 10.2196/38077