physiodsp 0.1.0__py3-none-any.whl

physiodsp/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

physiodsp/activity/__init__.py

@@ -0,0 +1,5 @@
+from physiodsp.activity.enmo import ENMO
+from physiodsp.activity.zero_crossing import ZeroCrossing
+from physiodsp.activity.time_above_thr import TimeAboveThr
+
+__all__ = ["ENMO", "ZeroCrossing", "TimeAboveThr"]

physiodsp/activity/activity_score.py

@@ -0,0 +1,311 @@
+from typing import Literal
+
+import numpy as np
+from pandas import DataFrame
+from pydantic import BaseModel, Field, PositiveInt, PositiveFloat
+
+from physiodsp.base import BaseAlgorithm
+
+
+class ActivityScoreSettings(BaseModel):
+    """Configuration settings for Activity Score algorithm"""
+
+    # Baseline window (number of days to use for personalization)
+    baseline_window_days: PositiveInt = Field(default=30, description="Number of days to use for computing baselines")
+
+    # Factor weights (must sum to 1.0)
+    step_weight: PositiveFloat = Field(default=0.25, description="Weight for step count factor")
+    sleep_weight: PositiveFloat = Field(default=0.35, description="Weight for sleep factor")
+    training_weight: PositiveFloat = Field(default=0.25, description="Weight for training time factor")
+    resting_weight: PositiveFloat = Field(default=0.15, description="Weight for resting time factor")
+
+    # Step targets (personalized)
+    baseline_daily_steps: PositiveInt = Field(default=8000, description="User's baseline daily steps")
+    step_ceiling: PositiveInt = Field(default=15000, description="Maximum steps for optimal score")
+
+    # Sleep targets (hours)
+    min_sleep_hours: PositiveFloat = Field(default=6.0, description="Minimum healthy sleep duration")
+    optimal_sleep_hours: PositiveFloat = Field(default=8.0, description="Optimal sleep duration")
+    max_sleep_hours: PositiveFloat = Field(default=10.0, description="Maximum sleep before penalty")
+
+    # Training targets (minutes)
+    min_training_minutes: PositiveInt = Field(default=0, description="Minimum training minutes per day")
+    optimal_training_minutes: PositiveInt = Field(default=60, description="Optimal training minutes per day")
+    max_training_minutes: PositiveInt = Field(default=120, description="Maximum training before overtraining penalty")
+
+    # Resting targets (minutes)
+    min_resting_minutes: PositiveInt = Field(default=480, description="Minimum resting minutes (8 hours)")
+    optimal_resting_minutes: PositiveInt = Field(default=540, description="Optimal resting minutes (9 hours)")
+    max_resting_minutes: PositiveInt = Field(default=720, description="Maximum resting minutes (12 hours)")
+
+    # Scoring method
+    scoring_method: Literal["gaussian", "sigmoid", "linear"] = Field(
+        default="gaussian",
+        description="Method to map normalized values to scores"
+    )
+
+
+class ActivityScore(BaseAlgorithm):
+    """
+    Activity Score Algorithm - Personalized Daily Activity Assessment
+
+    Combines multiple health metrics (steps, sleep, training, resting) into a single
+    0-100 score tailored to individual user baselines and targets.
+
+    Based on principles from Oura Ring and WHOOP band scoring algorithms.
+    """
+
+    _algorithm_name = "ActivityScore"
+    _version = "0.1.0"
+
+    def __init__(self, settings: ActivityScoreSettings = ActivityScoreSettings()) -> None:
+        self.settings = settings
+        self._validate_weights()
+        self.user_stats = None
+        self.daily_scores = None
+        self.baseline_stats = None
+        return None
+
+    def _validate_weights(self) -> None:
+        """Validate that weights sum to 1.0"""
+        total_weight = (
+            self.settings.step_weight +
+            self.settings.sleep_weight +
+            self.settings.training_weight +
+            self.settings.resting_weight
+        )
+        if not np.isclose(total_weight, 1.0, atol=0.01):
+            raise ValueError(f"Weights must sum to 1.0, got {total_weight}")
+
+    def _compute_baseline_stats(self, baseline_data: DataFrame) -> dict:
+        """
+        Compute personalized baseline statistics from historical data.
+
+        Args:
+            baseline_data: DataFrame with previous N-1 days
+
+        Returns:
+            Dictionary with computed statistics
+        """
+        return {
+            'steps_median': baseline_data['steps'].median(),
+            'steps_std': baseline_data['steps'].std(),
+            'steps_p75': baseline_data['steps'].quantile(0.75),
+            'sleep_median': baseline_data['sleep_hours'].median(),
+            'sleep_std': baseline_data['sleep_hours'].std(),
+            'training_median': baseline_data['training_minutes'].median(),
+            'training_std': baseline_data['training_minutes'].std(),
+            'resting_median': baseline_data['resting_minutes'].median(),
+            'resting_std': baseline_data['resting_minutes'].std()
+        }
+
+    def _score_steps(self, daily_steps: int, baseline_stats: dict = None) -> float:
+        """
+        Score daily step count (0-100).
+
+        Gaussian distribution centered at user's median baseline.
+        """
+        if baseline_stats is None:
+            baseline = self.settings.baseline_daily_steps
+            ceiling = self.settings.step_ceiling
+        else:
+            # Use personalized baseline from historical data
+            baseline = baseline_stats['steps_median']
+            # Ceiling is 75th percentile or 1.5x median, whichever is higher
+            ceiling = max(baseline * 1.5, baseline_stats['steps_p75'])
+
+        if self.settings.scoring_method == "gaussian":
+            if baseline == 0:
+                return 0.0
+            normalized = daily_steps / baseline
+            peak_normalized = ceiling / baseline
+            std_dev = (peak_normalized - 1.0) / 2.0
+            score = 100 * np.exp(-((normalized - 1.0) ** 2) / (2 * std_dev ** 2))
+            score = np.clip(score, 0, 100)
+        else:
+            if ceiling == 0:
+                return 0.0
+            score = min(100, (daily_steps / ceiling) * 100)
+
+        return float(score)
+
+    def _score_sleep(self, sleep_hours: float, baseline_stats: dict = None) -> float:
+        """
+        Score sleep duration (0-100).
+
+        Centered at user's median sleep, with personalized thresholds.
+        """
+        if baseline_stats is None:
+            optimal = self.settings.optimal_sleep_hours
+            min_sleep = self.settings.min_sleep_hours
+            max_sleep = self.settings.max_sleep_hours
+        else:
+            median_sleep = baseline_stats['sleep_median']
+            std_sleep = baseline_stats['sleep_std'] or 0.5
+            optimal = median_sleep
+            min_sleep = max(4.0, median_sleep - std_sleep * 1.5)
+            max_sleep = min(11.0, median_sleep + std_sleep * 1.5)
+
+        if sleep_hours < min_sleep:
+            deficit = (min_sleep - sleep_hours) / min_sleep
+            score = max(0, 50 - deficit * 50)
+        elif sleep_hours <= optimal:
+            score = ((sleep_hours - min_sleep) / (optimal - min_sleep)) * 100
+        elif sleep_hours <= max_sleep:
+            score = 100 - ((sleep_hours - optimal) / (max_sleep - optimal)) * 30
+        else:
+            excess = sleep_hours - max_sleep
+            score = max(0, 70 - excess * 10)
+
+        return float(np.clip(score, 0, 100))
+
+    def _score_training(self, training_minutes: int, baseline_stats: dict = None) -> float:
+        """
+        Score training time (0-100).
+
+        Rewards consistent moderate training relative to user's baseline.
+        """
+        if baseline_stats is None:
+            optimal = self.settings.optimal_training_minutes
+            max_train = self.settings.max_training_minutes
+        else:
+            median_training = baseline_stats['training_median']
+            std_training = baseline_stats['training_std'] or 15
+            optimal = max(30, median_training)
+            max_train = optimal + std_training * 2
+
+        if training_minutes < 5:
+            score = 50
+        elif training_minutes <= optimal:
+            score = 50 + (training_minutes / optimal) * 50
+        elif training_minutes <= max_train:
+            excess_ratio = (training_minutes - optimal) / (max_train - optimal)
+            score = 100 + (excess_ratio * 10) - 10
+        else:
+            excess = training_minutes - max_train
+            score = max(0, 100 - excess * 0.5)
+
+        return float(np.clip(score, 0, 100))
+
+    def _score_resting(self, resting_minutes: int, baseline_stats: dict = None) -> float:
+        """
+        Score resting/recovery time (0-100).
+
+        Rewards recovery relative to user's baseline.
+        """
+        resting_hours = resting_minutes / 60
+
+        if baseline_stats is None:
+            optimal_hours = self.settings.optimal_resting_minutes / 60
+            min_hours = self.settings.min_resting_minutes / 60
+            max_hours = self.settings.max_resting_minutes / 60
+        else:
+            median_resting = baseline_stats['resting_median'] / 60
+            std_resting = baseline_stats['resting_std'] / 60 or 0.5
+            optimal_hours = median_resting
+            min_hours = max(6.0, median_resting - std_resting * 1.5)
+            max_hours = min(12.0, median_resting + std_resting * 1.5)
+
+        if resting_hours < min_hours:
+            deficit = (min_hours - resting_hours)
+            score = max(0, 50 - deficit * 15)
+        elif resting_hours <= optimal_hours:
+            score = ((resting_hours - min_hours) / (optimal_hours - min_hours)) * 100
+        elif resting_hours <= max_hours:
+            excess_hours = resting_hours - optimal_hours
+            max_excess = max_hours - optimal_hours
+            score = 100 - (excess_hours / max_excess) * 25
+        else:
+            excess_hours = resting_hours - max_hours
+            score = max(0, 75 - excess_hours * 10)
+
+        return float(np.clip(score, 0, 100))
+
+    def run(self, daily_activity_data: DataFrame):
+        """
+        Calculate Activity Score for the most recent day using baseline statistics.
+
+        Args:
+            daily_activity_data: DataFrame with all available data, sorted by date (oldest to newest).
+                Must contain columns:
+                - 'date' or index as date
+                - 'steps': Daily step count
+                - 'sleep_hours': Total sleep duration in hours
+                - 'training_minutes': Total training time in minutes
+                - 'resting_minutes': Total resting/recovery time in minutes
+
+                Should have at least baseline_window_days of data.
+
+        Returns:
+            self with biomarker containing score for the most recent day
+        """
+        if not all(col in daily_activity_data.columns for col in ['steps', 'sleep_hours', 'training_minutes', 'resting_minutes']):
+            raise ValueError("DataFrame must contain: steps, sleep_hours, training_minutes, resting_minutes")
+
+        if len(daily_activity_data) < 2:
+            raise ValueError(f"Need at least 2 days of data, got {len(daily_activity_data)}")
+
+        # Ensure we have the right number of baseline days
+        window_size = min(self.settings.baseline_window_days, len(daily_activity_data) - 1)
+
+        # Split into baseline (all but last) and current day (last)
+        baseline_data = daily_activity_data.iloc[:-1].tail(window_size)
+        current_day_data = daily_activity_data.iloc[-1]
+
+        # Compute personalized baseline statistics
+        self.baseline_stats = self._compute_baseline_stats(baseline_data)
+
+        # Calculate individual scores using personalized baselines
+        step_score = self._score_steps(current_day_data['steps'], self.baseline_stats)
+        sleep_score = self._score_sleep(current_day_data['sleep_hours'], self.baseline_stats)
+        training_score = self._score_training(current_day_data['training_minutes'], self.baseline_stats)
+        resting_score = self._score_resting(current_day_data['resting_minutes'], self.baseline_stats)
+
+        # Weighted combination
+        activity_score = (
+            (step_score * self.settings.step_weight) +
+            (sleep_score * self.settings.sleep_weight) +
+            (training_score * self.settings.training_weight) +
+            (resting_score * self.settings.resting_weight)
+        )
+
+        # Create output DataFrame
+        score_record = {
+            'date': current_day_data.get('date', daily_activity_data.index[-1]) if 'date' in daily_activity_data.columns else daily_activity_data.index[-1],
+            'activity_score': round(activity_score, 1),
+            'step_score': round(step_score, 1),
+            'sleep_score': round(sleep_score, 1),
+            'training_score': round(training_score, 1),
+            'resting_score': round(resting_score, 1),
+            'steps': current_day_data['steps'],
+            'sleep_hours': current_day_data['sleep_hours'],
+            'training_minutes': current_day_data['training_minutes'],
+            'resting_minutes': current_day_data['resting_minutes'],
+            'baseline_days_used': window_size
+        }
+
+        self.biomarker_agg = DataFrame([score_record])
+        self.daily_scores = self.biomarker_agg.copy()
+
+        return self
+
+    def get_activity_score_interpretation(self, activity_score: float) -> str:
+        """
+        Return interpretation of Activity Score.
+
+        Args:
+            activity_score: Activity score (0-100)
+
+        Returns:
+            Interpretation string
+        """
+        if activity_score >= 85:
+            return "Excellent - Outstanding activity and recovery balance"
+        elif activity_score >= 70:
+            return "Good - Healthy activity levels with adequate recovery"
+        elif activity_score >= 50:
+            return "Fair - Room for improvement in activity or recovery"
+        elif activity_score >= 30:
+            return "Poor - Significant imbalance in activity or recovery"
+        else:
+            return "Critical - Urgent attention needed to activity and recovery"

physiodsp/activity/enmo.py

@@ -0,0 +1,74 @@
+from pandas import Series, DataFrame
+from pydantic import BaseModel, Field, PositiveInt
+
+from physiodsp.base import BaseAlgorithm
+from physiodsp.sensors.imu.accelerometer import AccelerometerData
+
+
+class ENMOSettings(BaseModel):
+
+    window_len: PositiveInt = Field(default=1, description="processing window length in seconds")
+
+    aggregation_window: PositiveInt = Field(default=60, description="aggregation window length in seconds")
+
+
+class ENMO(BaseAlgorithm):
+    """Euclidean Norm Minus One"""
+
+    _algorithm_name = "ENMO"
+    _version = "0.1.0"
+
+    def __init__(self,
+                 settings: ENMOSettings = ENMOSettings()
+                 ) -> None:
+        self.settings = settings
+        self._window_len = settings.window_len
+        self._aggregation_window = settings.aggregation_window
+        return None
+
+    def run(self, accelerometer: AccelerometerData):
+        """Run the ENMO algorithm on accelerometer data.
+        ENMO is calculated as the vector magnitude of the three accelerometer
+        axes minus 1g, with negative values set to zero. The algorithm computes
+        the average ENMO over non-overlapping windows of a specified length.
+
+        Args:
+            accelerometer (AccelerometerData): Triaxial accelerometer data.
+
+        Returns:
+            ENMO: Instance of the ENMO algorithm with computed values.
+        """
+
+        enmo = accelerometer.magnitude - 1
+        enmo[enmo < 0] = 0
+
+        self.timestamps = Series(accelerometer.timestamps).rolling(
+            window=int(self._window_len * accelerometer.fs),
+            step=int(self._window_len * accelerometer.fs),
+            min_periods=int(self._window_len * accelerometer.fs),
+            closed="left"
+        ).max()[1:]
+
+        self.values = Series(enmo).rolling(
+            window=int(self._window_len * accelerometer.fs),
+            step=int(self._window_len * accelerometer.fs),
+            min_periods=int(self._window_len * accelerometer.fs),
+            closed="left"
+        ).mean()[1:]
+
+        self.biomarker = DataFrame(
+            list(zip(self.timestamps, self.values)),
+            columns=['timestamps', 'values']
+        )
+
+        return self
+
+    def aggregate(self,
+                  method: str = 'mean'
+                  ):
+        super().aggregate(
+            self.timestamps,
+            self.values,
+            method
+        )
+        return self

physiodsp/activity/pim.py

@@ -0,0 +1,43 @@
+from numpy import abs
+from pandas import DataFrame
+
+from physiodsp.base import BaseAlgorithm
+from physiodsp.sensors.imu.base import IMUData
+
+
+class PIMAlgorithm(BaseAlgorithm):
+    """Proportional Integration Mode"""
+
+    _algorithm_name = "PIMAlgorithm"
+    _version = "0.1.0"
+    _aggregation_window = 5
+
+    def __init__(self) -> None:
+
+        return None
+
+    def estimate(self, data: IMUData):
+
+        self.values_x = abs(data.x)
+        self.values_y = abs(data.y)
+        self.values_z = abs(data.z)
+
+        return self
+
+    def aggregate(self,
+                  method: str = 'sum'
+                  ):
+
+        df = DataFrame(
+            list(zip(self.data.timestamps, self.values_x, self.values_y, self.values_z)),
+            columns=['timestamps', 'x', 'y', 'z']
+        )
+
+        df['timestamps'] = df[
+            'timestamps'].apply(lambda x: x // self.aggregation_window)
+
+        df_agg = df.groupby('timestamps')[["x", "y", "z"]].agg(method).reset_index(drop=False)
+
+        self.biomarker_agg = df_agg
+
+        return self

physiodsp/activity/time_above_thr.py

@@ -0,0 +1,64 @@
+from numpy import abs, concatenate
+from pandas import DataFrame
+from pydantic import BaseModel, Field, PositiveInt, PositiveFloat
+
+from physiodsp.base import BaseAlgorithm
+from physiodsp.sensors.imu.base import IMUData
+
+
+class TimeAboveThrSettings(BaseModel):
+
+    window_len: PositiveInt = Field(default=1, description="processing window length in seconds")
+
+    aggregation_window: PositiveInt = Field(default=60, description="aggregation window length in seconds")
+
+    threshold: PositiveFloat = Field(default=0.1, description="threshold in g")
+
+
+class TimeAboveThr(BaseAlgorithm):
+    """Time Above Threshold Algorithm"""
+
+    _algorithm_name = "TimeAboveThrAlgorithm"
+    _version = "0.1.0"
+
+    def __init__(self,
+                 settings: TimeAboveThrSettings = TimeAboveThrSettings()
+                 ) -> None:
+        self.settings = settings
+        self._window_len = settings.window_len
+        self._aggregation_window = settings.aggregation_window
+        return None
+
+    def run(self, data: IMUData):
+
+        imu_matrix = data.to_matrix()
+        above_thr = (abs(imu_matrix) >= self.settings.threshold).astype(int)
+        # Add timestamp column
+        above_thr = concatenate([data.timestamps.reshape(-1, 1), above_thr], axis=1)
+
+        self.values = DataFrame({"timestamps": above_thr[:, 0], "x": above_thr[:, 1], "y": above_thr[:, 2], "z": above_thr[:, 3]}).rolling(
+            window=int(self._window_len * data.fs),
+            step=int(self._window_len * data.fs),
+            min_periods=int(self._window_len * data.fs),
+            closed="left"
+        ).agg({"timestamps": "max", "x": "sum", "y": "sum", "z": "sum"})[1:]
+
+        return self
+
+    def aggregate(self,
+                  method: str = 'sum'
+                  ):
+
+        df = DataFrame(
+            list(zip(self.data.timestamps, self.values_x, self.values_y, self.values_z)),
+            columns=['timestamps', 'x', 'y', 'z']
+        )
+
+        df['timestamp'] = df[
+            'timestamps'].apply(lambda x: x // self._aggregation_window)
+
+        df_agg = df.groupby('timestamp')[["x", "y", "z"]].agg(method).reset_index(drop=False)
+
+        self.biomarker_agg = df_agg
+
+        return self

physiodsp/activity/zero_crossing.py

@@ -0,0 +1,103 @@
+from numpy import diff, abs
+from pandas import DataFrame
+from pydantic import BaseModel, Field, PositiveInt, PositiveFloat
+from scipy.signal import butter, sosfilt, sosfilt_zi
+
+from physiodsp.base import BaseAlgorithm
+from physiodsp.sensors.imu.base import IMUData
+
+
+class ZeroCrossingSettings(BaseModel):
+
+    window_len: PositiveInt = Field(default=1, description="processing window length in seconds")
+
+    aggregation_window: PositiveInt = Field(default=60, description="aggregation window length in seconds")
+
+    zero_crossing_thr: PositiveFloat = Field(default=0.05, description="ero crossing threshold in g")
+
+    filter_order: PositiveInt = Field(default=4, description="Butterworth filter order for bandpass filtering")
+
+    filter_low_freq: PositiveFloat = Field(default=0.3, description="Lower cutoff frequency in Hz")
+
+    filter_high_freq: PositiveFloat = Field(default=3.5, description="Upper cutoff frequency in Hz")
+
+
+class ZeroCrossing(BaseAlgorithm):
+    """Zero Crossing Algorithm"""
+
+    _algorithm_name = "ZeroCrossingAlgorithm"
+    _version = "0.1.0"
+
+    def __init__(self,
+                 settings: ZeroCrossingSettings = ZeroCrossingSettings(),
+                 ) -> None:
+
+        self.settings = settings
+        self._window_len = settings.window_len
+        self._aggregation_window = settings.aggregation_window
+        self.zero_crossing_thr = settings.zero_crossing_thr
+        return None
+
+    def __preprocess_imu(self, imu_matrix, fs: int):
+        """
+        Apply bandpass Butterworth filter to IMU data.
+
+        Reference: 0.3-3.5 Hz pass band is commonly used for human movement analysis
+        to isolate low-frequency body motion while removing drift and high-frequency noise.
+        Args:
+            imu_matrix: (N, 3) array with columns [x, y, z]
+            fs: Sampling frequency of the IMU data in Hz
+
+        Returns:
+            Filtered (N, 3) array
+        """
+        # Design bandpass filter using second-order sections for numerical stability
+        sos = butter(self.settings.filter_order,
+                     [self.settings.filter_low_freq, self.settings.filter_high_freq],
+                     btype='band',
+                     fs=fs,
+                     output='sos')
+
+        # Initialize filter states for each axis
+        zi = sosfilt_zi(sos)
+
+        # Apply filter to each axis using sosfilt (not filtfilt)
+        filtered_matrix = imu_matrix.copy()
+        for i in range(imu_matrix.shape[1]):
+            filtered_matrix[:, i], _ = sosfilt(sos, imu_matrix[:, i], zi=zi * imu_matrix[0, i])
+
+        return filtered_matrix
+
+    def run(self, data: IMUData):
+
+        # Apply bandpass filter to IMU data
+        imu_matrix = data.to_matrix()
+        imu_matrix_filtered = self.__preprocess_imu(imu_matrix, fs=data.fs)
+        # Compute zero crossings for each axis
+        zcr = abs(diff((imu_matrix_filtered >= self.zero_crossing_thr).astype(int), axis=0))
+
+        self.values = DataFrame({"timestamps": data.timestamps[1:], "x": zcr[:, 0], "y": zcr[:, 1], "z": zcr[:, 2]}).rolling(
+            window=int(self._window_len * data.fs),
+            step=int(self._window_len * data.fs),
+            min_periods=int(self._window_len * data.fs),
+            closed="left"
+        ).agg({"timestamps": "max", "x": "sum", "y": "sum", "z": "sum"})[1:]
+
+        self.biomarker = self.values.copy()
+
+        return self
+
+    def aggregate(self,
+                  method: str = 'sum'
+                  ):
+
+        df = self.values.copy()
+
+        df['timestamps'] = df[
+            'timestamps'].apply(lambda x: (x // self._aggregation_window) * self._aggregation_window)
+
+        df_agg = df.groupby('timestamps')[["x", "y", "z"]].agg(method).reset_index(drop=False)
+
+        self.biomarker_agg = df_agg
+
+        return self