Merge branch 'main' into feature/issue-200/update-output

Author: Asanto32

poetry.lock

@@ -40,6 +40,7 @@ class ActivityMetric(str, Enum):
     enmo = "enmo"
     mad = "mad"
     ag_count = "ag_count"
+    mims = "mims"
 
 
 class NonwearAlgorithms(str, Enum):
@@ -85,7 +86,7 @@ def main(
         "-a",
         "--activity-metric",
         help="Metric used for physical activity categorization. "
-        "Choose from 'enmo', 'mad', or 'ag_count'.",
+        "Choose from 'enmo', 'mad', 'ag_count', or 'mims'.  ",
         case_sensitive=False,
     ),
     thresholds: tuple[float, float, float] = typer.Option(

src/wristpy/core/cli.py

@@ -112,6 +112,7 @@ class WatchData(BaseModel):
     capsense: Optional[Measurement] = None
     temperature: Optional[Measurement] = None
     idle_sleep_mode_flag: Optional[bool] = None
+    dynamic_range: Optional[tuple[float, float]] = None
 
     @field_validator("acceleration")
     def validate_acceleration(cls, v: Measurement) -> Measurement:

src/wristpy/core/models.py

@@ -30,7 +30,7 @@ def run(
         Literal["ggir", "gradient"],
     ] = "gradient",
     epoch_length: float = 5,
-    activity_metric: Literal["enmo", "mad", "ag_count"] = "enmo",
+    activity_metric: Literal["enmo", "mad", "ag_count", "mims"] = "enmo",
     nonwear_algorithm: Sequence[Literal["ggir", "cta", "detach"]] = ["ggir"],
     verbosity: int = logging.WARNING,
     output_filetype: Optional[Literal[".csv", ".parquet"]] = None,
@@ -52,7 +52,7 @@ def run(
             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. Values must be asscending, unique, and greater than 0.
-            Default values are optimized for subjects ages 7-11 [1].
+            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.
@@ -80,6 +80,10 @@ def run(
         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
     """
     logger.setLevel(verbosity)
 
@@ -92,8 +96,10 @@ def run(
         thresholds = thresholds or (0.029, 0.338, 0.604)
     elif activity_metric == "ag_count":
         thresholds = thresholds or (100, 3000, 5200)
+    elif activity_metric == "mims":
+        thresholds = thresholds or (10.558, 15.047, 19.614)
 
-    if not (0 <= thresholds[0] < thresholds[1] < thresholds[2]):
+    if not (0 <= thresholds[0] < thresholds[1] < thresholds[2]):  # type: ignore
         message = "Threshold values must be >=0, unique, and in ascending order."
         logger.error(message)
         raise ValueError(message)
@@ -123,6 +129,7 @@ def run(
         thresholds=thresholds,
         calibrator=calibrator,
         epoch_length=epoch_length,
+        activity_metric=activity_metric,
         verbosity=verbosity,
         output_filetype=output_filetype,
         nonwear_algorithm=nonwear_algorithm,
@@ -141,6 +148,7 @@ def _run_directory(
     nonwear_algorithm: Sequence[Literal["ggir", "cta", "detach"]] = ["ggir"],
     verbosity: int = logging.WARNING,
     output_filetype: Optional[Literal[".csv", ".parquet"]] = None,
+    activity_metric: Literal["enmo", "mad", "ag_count", "mims"] = "enmo",
 ) -> Dict[str, writers.OrchestratorResults]:
     """Runs main processing steps for wristpy on  directories.
 
@@ -156,13 +164,14 @@ def _run_directory(
         output: Path to directory data will be saved to.
         thresholds: The cut points for the light, moderate, and vigorous thresholds,
             given in that order. Values must be asscending, unique, and greater than 0.
-            Default values are optimized for subjects ages 7-11 [1].
+            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 to be used for physical activity categorization.
 
     Returns:
         All calculated data in a save ready format as a dictionary of
@@ -178,6 +187,10 @@ def _run_directory(
         [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
     """
     if output is None and output_filetype is not None:
         raise ValueError("If no output is given, output_filetype must be None.")
@@ -220,6 +233,7 @@ def _run_directory(
                 epoch_length=epoch_length,
                 verbosity=verbosity,
                 nonwear_algorithm=nonwear_algorithm,
+                activity_metric=activity_metric,
             )
         except Exception as e:
             logger.error("Did not run file: %s, Error: %s", file, e)
@@ -236,7 +250,7 @@ def _run_file(
         Literal["ggir", "gradient"],
     ] = "gradient",
     epoch_length: float = 5.0,
-    activity_metric: Literal["enmo", "mad", "ag_count"] = "enmo",
+    activity_metric: Literal["enmo", "mad", "ag_count", "mims"] = "enmo",
     nonwear_algorithm: Sequence[Literal["ggir", "cta", "detach"]] = ["ggir"],
     verbosity: int = logging.WARNING,
 ) -> writers.OrchestratorResults:
@@ -255,7 +269,7 @@ def _run_file(
             either .csv or .parquet formats.
         thresholds: The cut points for the light, moderate, and vigorous thresholds,
             given in that order. Values must be ascending, unique, and greater than 0.
-            Default values are optimized for subjects ages 7-11 [1].
+            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.
@@ -279,6 +293,10 @@ def _run_file(
         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
     """
     logger.setLevel(verbosity)
     if output is not None:
@@ -328,7 +346,10 @@ def _run_file(
         calibrated_acceleration, epoch_length=epoch_length
     )
     activity_measurement = _compute_activity(
-        calibrated_acceleration, activity_metric, epoch_length
+        calibrated_acceleration,
+        activity_metric,
+        epoch_length,
+        dynamic_range=watch_data.dynamic_range,
     )
 
     sleep_detector = analytics.GgirSleepDetection(anglez)
@@ -339,6 +360,7 @@ def _run_file(
         temperature=watch_data.temperature,
         non_wear_algorithms=nonwear_algorithm,
     )
+
     nonwear_epoch = nonwear_utils.nonwear_array_cleanup(
         nonwear_array=nonwear_array,
         reference_measurement=activity_measurement,
@@ -383,8 +405,9 @@ def _run_file(
 
 def _compute_activity(
     acceleration: models.Measurement,
-    activity_metric: Literal["ag_count", "mad", "enmo"],
+    activity_metric: Literal["ag_count", "mad", "enmo", "mims"],
     epoch_length: float,
+    dynamic_range: Optional[tuple[float, float]],
 ) -> models.Measurement:
     """This is a helper function to organize the computation of the activity metric.
 
@@ -396,6 +419,10 @@ def _compute_activity(
         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.
@@ -407,4 +434,14 @@ def _compute_activity(
         )
     elif activity_metric == "mad":
         return metrics.mean_amplitude_deviation(acceleration, epoch_length=epoch_length)
+    elif activity_metric == "mims":
+        if dynamic_range is None:
+            return metrics.monitor_independent_movement_summary_units(
+                acceleration,
+                epoch=epoch_length,
+            )
+        return metrics.monitor_independent_movement_summary_units(
+            acceleration, epoch=epoch_length, dynamic_range=dynamic_range
+        )
+
     return metrics.euclidean_norm_minus_one(acceleration, epoch_length=epoch_length)

src/wristpy/core/orchestrator.py

@@ -1,6 +1,5 @@
 """Function to read accelerometer data from a file."""
 
-import os
 import pathlib
 from typing import Literal, Union
 
@@ -39,22 +38,62 @@ def read_watch_data(file_name: Union[pathlib.Path, str]) -> models.WatchData:
             measurements[sensor_name] = models.Measurement(
                 measurements=sensor_values, time=time
             )
+
+    file_type = pathlib.Path(file_name).suffix
     idle_sleep_mode_flag = False
-    if os.path.splitext(file_name)[1] == ".gt3x":
+    if file_type == ".gt3x":
         idle_sleep_mode_flag = (
             data["metadata"]["device_feature_enabled"]["sleep_mode"].lower() == "true"
         )
 
+    dynamic_range = _extract_dynamic_range(
+        metadata=data["metadata"],
+        file_type=file_type,  # type: ignore[arg-type]
+    )
+
     return models.WatchData(
         acceleration=measurements["acceleration"],
         lux=measurements.get("light"),
         battery=measurements.get("battery_voltage"),
         capsense=measurements.get("capsense"),
         temperature=measurements.get("temperature"),
         idle_sleep_mode_flag=idle_sleep_mode_flag,
+        dynamic_range=dynamic_range,
     )
 
 
+def _extract_dynamic_range(
+    metadata: dict, file_type: Literal[".gt3x", ".bin"]
+) -> tuple[float, float]:
+    """Extract the dynamic range from metadata.
+
+    Args:
+        metadata: Metadata subdictionary where accelerometer range values can be found.
+        file_type: Accelerometer data file type. Supports .gt3x and .bin.
+
+    Returns:
+        A tuple containing the accelerometer range.
+
+    Raises:
+        ValueError: If file type is not supported.
+    """
+    if file_type == ".gt3x":
+        return (
+            float(metadata.get("info", {}).get("Acceleration Min")),
+            float(metadata.get("info", {}).get("Acceleration Max")),
+        )
+    elif file_type == ".bin":
+        range_str = (
+            metadata.get("Device Capabilities", {})
+            .get("Accelerometer Range")
+            .strip()
+            .split(" to ")
+        )
+        return (float(range_str[0]), float(range_str[1]))
+
+    raise ValueError(f"Unsupported file type given: {file_type}")
+
+
 def unix_epoch_time_to_polars_datetime(
     time: np.ndarray, units: Literal["ns", "us", "ms", "s", "d"] = "ns"
 ) -> pl.Series:

src/wristpy/io/readers/readers.py

@@ -1,12 +1,15 @@
 """Calculate base metrics, anglez and enmo."""
 
+from typing import Literal, Tuple
+
 import numpy as np
 import polars as pl
 from scipy import interpolate, signal
 from skdh.preprocessing import wear_detection
 
 from wristpy.core import computations, config, models
 from wristpy.io.readers import readers
+from wristpy.processing import mims
 
 logger = config.get_logger()
 
@@ -605,3 +608,79 @@ def _pre_process_temperature(
         [pl.mean("temperature")]
     )
     return low_pass_temp
+
+
+def monitor_independent_movement_summary_units(
+    acceleration: models.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,
+) -> models.Measurement:
+    """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 trunction of small values.
+    The MIMS value per axis is then combined through a sum or vector magnitude, and
+    returned as a single vector.
+
+    Args:
+        acceleration: Triaxial acceleration data to be processed.
+        combination_method: Method to combine MIMS values accross 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.
+
+    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.
+
+    """
+    interpolated_measure = mims.interpolate_measure(
+        acceleration=acceleration,
+        new_frequency=interpolation_frequency,
+    )
+    extrapolated_measure = mims.extrapolate_points(
+        acceleration=interpolated_measure,
+        dynamic_range=dynamic_range,
+        sampling_rate=interpolation_frequency,
+    )
+    filtered_measure = mims.butterworth_filter(
+        acceleration=extrapolated_measure,
+        sampling_rate=interpolation_frequency,
+        cutoffs=cutoffs,
+        order=order,
+    )
+    aggregated_measure = mims.aggregate_mims(
+        acceleration=filtered_measure,
+        epoch=epoch,
+        sampling_rate=interpolation_frequency,
+        rectify=rectify,
+    )
+    combined_mims = mims.combine_mims(
+        acceleration=aggregated_measure, combination_method=combination_method
+    )
+    return combined_mims