iints-sdk-python35 0.0.18__py3-none-any.whl

iints/presets/presets.json

@@ -0,0 +1,114 @@
+[
+  {
+    "name": "baseline_t1d",
+    "description": "Clinic-safe baseline with stable parameters and moderate meals.",
+    "patient_config": "clinic_safe_baseline",
+    "duration_minutes": 1440,
+    "time_step_minutes": 5,
+    "critical_glucose_threshold": 40.0,
+    "critical_glucose_duration_minutes": 30,
+    "scenario": {
+      "scenario_name": "Clinic Safe Baseline",
+      "scenario_version": "1.0",
+      "stress_events": [
+        {"start_time": 60, "event_type": "meal", "value": 45, "absorption_delay_minutes": 15, "duration": 60},
+        {"start_time": 360, "event_type": "meal", "value": 60, "absorption_delay_minutes": 20, "duration": 90},
+        {"start_time": 720, "event_type": "meal", "value": 70, "absorption_delay_minutes": 15, "duration": 90},
+        {"start_time": 1000, "event_type": "exercise", "value": 0.4, "duration": 45}
+      ]
+    }
+  },
+  {
+    "name": "stress_test_meal",
+    "description": "Clinic-safe meal stress test with larger lunch and safety clamps enabled.",
+    "patient_config": "clinic_safe_stress_meal",
+    "duration_minutes": 720,
+    "time_step_minutes": 5,
+    "critical_glucose_threshold": 40.0,
+    "critical_glucose_duration_minutes": 30,
+    "scenario": {
+      "scenario_name": "Clinic Safe Meal Stress",
+      "scenario_version": "1.0",
+      "stress_events": [
+        {"start_time": 90, "event_type": "meal", "value": 55, "absorption_delay_minutes": 15, "duration": 60},
+        {"start_time": 300, "event_type": "meal", "value": 90, "absorption_delay_minutes": 20, "duration": 90},
+        {"start_time": 600, "event_type": "meal", "value": 60, "absorption_delay_minutes": 15, "duration": 60}
+      ]
+    }
+  }
+  ,
+  {
+    "name": "hypo_prone_night",
+    "description": "Overnight hypo risk assessment with reduced basal and conservative carbs.",
+    "patient_config": "clinic_safe_hypo_prone",
+    "duration_minutes": 720,
+    "time_step_minutes": 5,
+    "critical_glucose_threshold": 40.0,
+    "critical_glucose_duration_minutes": 30,
+    "scenario": {
+      "scenario_name": "Hypo-Prone Overnight",
+      "scenario_version": "1.0",
+      "stress_events": [
+        {"start_time": 60, "event_type": "meal", "value": 35, "absorption_delay_minutes": 10, "duration": 45},
+        {"start_time": 240, "event_type": "exercise", "value": 0.3, "duration": 30}
+      ]
+    }
+  },
+  {
+    "name": "hyper_challenge",
+    "description": "Post-prandial hyperglycemia challenge with a large meal.",
+    "patient_config": "clinic_safe_hyper_challenge",
+    "duration_minutes": 480,
+    "time_step_minutes": 5,
+    "critical_glucose_threshold": 40.0,
+    "critical_glucose_duration_minutes": 30,
+    "scenario": {
+      "scenario_name": "Hyper Challenge",
+      "scenario_version": "1.0",
+      "stress_events": [
+        {"start_time": 90, "event_type": "meal", "value": 110, "absorption_delay_minutes": 15, "duration": 90}
+      ]
+    }
+  }
+  ,
+  {
+    "name": "pizza_paradox",
+    "description": "Delayed glucose rise after a high-fat meal (pizza paradox).",
+    "patient_config": "clinic_safe_pizza",
+    "duration_minutes": 900,
+    "time_step_minutes": 5,
+    "critical_glucose_threshold": 40.0,
+    "critical_glucose_duration_minutes": 30,
+    "scenario": {
+      "scenario_name": "The Pizza Paradox",
+      "scenario_version": "1.0",
+      "stress_events": [
+        {
+          "start_time": 240,
+          "event_type": "meal",
+          "value": 90,
+          "reported_value": 90,
+          "absorption_delay_minutes": 180,
+          "duration": 120
+        }
+      ]
+    }
+  },
+  {
+    "name": "midnight_crash",
+    "description": "Overnight crash risk after evening exercise.",
+    "patient_config": "clinic_safe_midnight",
+    "duration_minutes": 720,
+    "time_step_minutes": 5,
+    "critical_glucose_threshold": 40.0,
+    "critical_glucose_duration_minutes": 30,
+    "scenario": {
+      "scenario_name": "Midnight Crash",
+      "scenario_version": "1.0",
+      "stress_events": [
+        {"start_time": 120, "event_type": "meal", "value": 45, "absorption_delay_minutes": 10, "duration": 60},
+        {"start_time": 300, "event_type": "exercise", "value": 0.6, "duration": 45}
+      ]
+    }
+  }
+]

iints/research/__init__.py

@@ -0,0 +1,30 @@
+from .config import PredictorConfig, TrainingConfig
+from .dataset import (
+    build_sequences,
+    subject_split,
+    FeatureScaler,
+    load_parquet,
+    save_parquet,
+    load_dataset,
+    save_dataset,
+)
+from .predictor import LSTMPredictor, load_predictor, PredictorService, load_predictor_service
+from .losses import QuantileLoss, SafetyWeightedMSE
+
+__all__ = [
+    "PredictorConfig",
+    "TrainingConfig",
+    "build_sequences",
+    "subject_split",
+    "FeatureScaler",
+    "load_parquet",
+    "save_parquet",
+    "load_dataset",
+    "save_dataset",
+    "LSTMPredictor",
+    "load_predictor",
+    "PredictorService",
+    "load_predictor_service",
+    "QuantileLoss",
+    "SafetyWeightedMSE",
+]

iints/research/config.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+
+@dataclass
+class PredictorConfig:
+    history_minutes: int = 240
+    horizon_minutes: int = 60
+    time_step_minutes: int = 5
+    feature_columns: List[str] = field(default_factory=lambda: [
+        "glucose_actual_mgdl",
+        "patient_iob_units",
+        "patient_cob_grams",
+        "effective_isf",
+        "effective_icr",
+        "effective_basal_rate_u_per_hr",
+        "glucose_trend_mgdl_min",
+    ])
+    target_column: str = "glucose_actual_mgdl"
+
+    @property
+    def history_steps(self) -> int:
+        return int(self.history_minutes / self.time_step_minutes)
+
+    @property
+    def horizon_steps(self) -> int:
+        return int(self.horizon_minutes / self.time_step_minutes)
+
+
+@dataclass
+class TrainingConfig:
+    epochs: int = 20
+    batch_size: int = 128
+    learning_rate: float = 1e-3
+    weight_decay: float = 0.0
+    hidden_size: int = 64
+    num_layers: int = 2
+    dropout: float = 0.1
+
+    # P0-2: Subject-level split fractions (must sum to <= 1.0).
+    # The remaining fraction after val + test goes to training.
+    # Set subject_level_split=True (default) to split by subject ID to
+    # prevent data leakage between train/val/test sets.
+    subject_level_split: bool = True
+    validation_split: float = 0.15   # fraction of subjects for validation
+    test_split: float = 0.15         # fraction of subjects for held-out test
+
+    seed: int = 42
+
+    # P3-10: Normalization strategy.  Options: "zscore", "robust", "none".
+    normalization: str = "zscore"
+
+    # P3-12: Loss function.  Options: "mse", "quantile".
+    # For quantile loss, also set `quantile` (0 < q < 1).
+    loss: str = "mse"
+    quantile: Optional[float] = None  # e.g. 0.9 for 90th-percentile upper bound
+
+    # Fine-tuning controls
+    freeze_lstm_layers: int = 0          # freeze first N LSTM layers
+    early_stopping_patience: int = 0     # 0 disables early stopping
+    early_stopping_min_delta: float = 0.0
+
+    # Safety-weighted loss (penalize low-glucose errors more strongly)
+    safety_weighted_low_threshold: float = 80.0
+    safety_weighted_alpha: float = 2.0
+    safety_weighted_max_weight: float = 4.0

iints/research/dataset.py

@@ -0,0 +1,319 @@
+from __future__ import annotations
+
+from typing import Dict, Iterable, List, Optional, Tuple
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+
+
+# ---------------------------------------------------------------------------
+# Sequence building
+# ---------------------------------------------------------------------------
+
+def build_sequences(
+    df: pd.DataFrame,
+    history_steps: int,
+    horizon_steps: int,
+    feature_columns: List[str],
+    target_column: str,
+    subject_column: Optional[str] = "subject_id",
+    segment_column: Optional[str] = None,
+) -> Tuple[np.ndarray, np.ndarray]:
+    """
+    Convert a time-series dataframe into (X, y) sequences.
+
+    X shape: [N, history_steps, num_features]
+    y shape: [N, horizon_steps]
+
+    Parameters
+    ----------
+    df : pd.DataFrame
+        Input dataframe, sorted by time within each subject/segment.
+    history_steps : int
+        Number of past steps used as input features.
+    horizon_steps : int
+        Number of future steps to predict.
+    feature_columns : list of str
+        Columns to use as input features.
+    target_column : str
+        Column to predict.
+    subject_column : str or None
+        If provided, sequences will not cross subject boundaries.
+        Defaults to "subject_id".
+    segment_column : str or None
+        If provided, sequences will additionally not cross segment boundaries
+        (e.g. gaps in CGM data).  Defaults to None.
+
+    Returns
+    -------
+    X : np.ndarray of shape [N, history_steps, num_features]
+    y : np.ndarray of shape [N, horizon_steps]
+    """
+    if history_steps <= 0 or horizon_steps <= 0:
+        raise ValueError("history_steps and horizon_steps must be > 0")
+    missing = [col for col in feature_columns + [target_column] if col not in df.columns]
+    if missing:
+        raise ValueError(f"Missing required columns: {missing}")
+
+    # Build a boundary mask: True at every row that starts a new group
+    # (subject or segment), so we never build a window that crosses the boundary.
+    boundary = pd.Series(False, index=df.index)
+    if subject_column and subject_column in df.columns:
+        boundary |= df[subject_column] != df[subject_column].shift(1)
+    if segment_column and segment_column in df.columns:
+        boundary |= df[segment_column] != df[segment_column].shift(1)
+    # First row is always a boundary
+    if len(boundary) > 0:
+        boundary.iloc[0] = True
+
+    values = df[feature_columns].to_numpy(dtype=np.float32)
+    target = df[target_column].to_numpy(dtype=np.float32)
+    boundary_arr = boundary.to_numpy(dtype=bool)
+
+    X_list: List[np.ndarray] = []
+    y_list: List[np.ndarray] = []
+    total = len(df)
+    end_index = total - history_steps - horizon_steps + 1
+
+    for idx in range(end_index):
+        window_end = idx + history_steps      # exclusive, first prediction step
+        horizon_end = window_end + horizon_steps
+
+        # Reject window if any boundary falls *inside* the history window
+        # (idx+1 .. window_end) or at the start of the horizon (window_end).
+        # idx itself may be a boundary (start of a new subject), which is fine.
+        if boundary_arr[idx + 1 : horizon_end].any():
+            continue
+
+        X_list.append(values[idx:window_end])
+        y_list.append(target[window_end:horizon_end])
+
+    if not X_list:
+        raise ValueError("Not enough rows to build sequences with current window sizes.")
+
+    X = np.stack(X_list, axis=0)
+    y = np.stack(y_list, axis=0)
+    return X, y
+
+
+# ---------------------------------------------------------------------------
+# P0-2: Subject-level train / val / test split
+# ---------------------------------------------------------------------------
+
+def subject_split(
+    df: pd.DataFrame,
+    val_fraction: float = 0.15,
+    test_fraction: float = 0.15,
+    subject_column: str = "subject_id",
+    seed: int = 42,
+) -> Tuple[pd.DataFrame, pd.DataFrame, pd.DataFrame]:
+    """
+    Split a dataframe into train / val / test sets by subject ID.
+
+    All rows belonging to one subject stay in the same split, which prevents
+    data leakage between sets (a subject's glucose patterns are unique and
+    would otherwise trivially inflate validation metrics).
+
+    Parameters
+    ----------
+    df : pd.DataFrame
+        Full dataset with a subject identifier column.
+    val_fraction : float
+        Fraction of *subjects* assigned to the validation set.
+    test_fraction : float
+        Fraction of *subjects* assigned to the held-out test set.
+    subject_column : str
+        Name of the subject identifier column.
+    seed : int
+        Random seed for reproducible shuffling.
+
+    Returns
+    -------
+    train_df, val_df, test_df : pd.DataFrame
+        Three non-overlapping subsets.
+    """
+    if subject_column not in df.columns:
+        raise ValueError(
+            f"Column '{subject_column}' not found in dataframe. "
+            "Cannot perform subject-level split."
+        )
+    if val_fraction + test_fraction >= 1.0:
+        raise ValueError("val_fraction + test_fraction must be < 1.0")
+
+    rng = np.random.default_rng(seed)
+    subjects = np.array(sorted(df[subject_column].unique()))
+    rng.shuffle(subjects)
+
+    n = len(subjects)
+    n_test = max(1, round(n * test_fraction))
+    n_val = max(1, round(n * val_fraction))
+    # Ensure we have at least one training subject
+    if n - n_val - n_test < 1:
+        raise ValueError(
+            f"Not enough subjects ({n}) for the requested val/test fractions. "
+            "Reduce val_fraction or test_fraction."
+        )
+
+    test_subjects = set(subjects[:n_test])
+    val_subjects = set(subjects[n_test: n_test + n_val])
+    train_subjects = set(subjects[n_test + n_val:])
+
+    train_df = df[df[subject_column].isin(train_subjects)].reset_index(drop=True)
+    val_df = df[df[subject_column].isin(val_subjects)].reset_index(drop=True)
+    test_df = df[df[subject_column].isin(test_subjects)].reset_index(drop=True)
+
+    return train_df, val_df, test_df
+
+
+# ---------------------------------------------------------------------------
+# P3-10: Feature normalisation
+# ---------------------------------------------------------------------------
+
+class FeatureScaler:
+    """
+    Fit-transform scaler for LSTM feature arrays.
+
+    Two strategies are supported:
+
+    ``"zscore"``
+        Standard z-score normalisation: (x - mean) / std.
+        Sensitive to outliers but widely used and interpretable.
+
+    ``"robust"``
+        Robust scaling: (x - median) / IQR.
+        Less sensitive to outlier glucose spikes and extreme bolus values.
+
+    ``"none"``
+        Pass-through (no scaling).
+
+    The scaler is fitted on training data only and the same parameters
+    are applied to val/test splits to avoid leakage.
+
+    Parameters
+    ----------
+    strategy : str
+        One of ``"zscore"``, ``"robust"``, or ``"none"``.
+    """
+
+    def __init__(self, strategy: str = "zscore") -> None:
+        if strategy not in {"zscore", "robust", "none"}:
+            raise ValueError(f"Unknown normalization strategy: {strategy!r}. "
+                             "Choose from 'zscore', 'robust', 'none'.")
+        self.strategy = strategy
+        self._center: Optional[np.ndarray] = None
+        self._scale: Optional[np.ndarray] = None
+        self._fitted = False
+
+    def fit(self, X: np.ndarray) -> "FeatureScaler":
+        """
+        Fit scaler on X of shape [N, T, F] or [N, F].
+
+        Parameters computed per feature (last axis).
+        """
+        flat = X.reshape(-1, X.shape[-1])
+        if self.strategy == "zscore":
+            self._center = flat.mean(axis=0)
+            std = flat.std(axis=0)
+            # Replace near-zero std with 1 to avoid division by zero
+            self._scale = np.where(std < 1e-8, 1.0, std)
+        elif self.strategy == "robust":
+            self._center = np.median(flat, axis=0)
+            q75 = np.percentile(flat, 75, axis=0)
+            q25 = np.percentile(flat, 25, axis=0)
+            iqr = q75 - q25
+            self._scale = np.where(iqr < 1e-8, 1.0, iqr)
+        else:
+            # none – identity
+            self._center = np.zeros(X.shape[-1], dtype=np.float32)
+            self._scale = np.ones(X.shape[-1], dtype=np.float32)
+        self._fitted = True
+        return self
+
+    def transform(self, X: np.ndarray) -> np.ndarray:
+        """Apply scaling. X shape: [N, T, F] or [N, F]."""
+        if not self._fitted:
+            raise RuntimeError("FeatureScaler must be fitted before transform().")
+        return ((X - self._center) / self._scale).astype(np.float32)
+
+    def fit_transform(self, X: np.ndarray) -> np.ndarray:
+        """Fit and transform in one step."""
+        return self.fit(X).transform(X)
+
+    def inverse_transform(self, X: np.ndarray) -> np.ndarray:
+        """Undo scaling."""
+        if not self._fitted:
+            raise RuntimeError("FeatureScaler must be fitted before inverse_transform().")
+        return (X * self._scale + self._center).astype(np.float32)
+
+    def to_dict(self) -> dict:
+        """Serialise scaler parameters for storage in model checkpoint."""
+        return {
+            "strategy": self.strategy,
+            "center": self._center.tolist() if self._center is not None else None,
+            "scale": self._scale.tolist() if self._scale is not None else None,
+        }
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "FeatureScaler":
+        """Restore a scaler from a serialised dict."""
+        scaler = cls(strategy=d["strategy"])
+        if d.get("center") is not None:
+            scaler._center = np.array(d["center"], dtype=np.float32)
+            scaler._scale = np.array(d["scale"], dtype=np.float32)
+            scaler._fitted = True
+        return scaler
+
+
+# ---------------------------------------------------------------------------
+# Persistence helpers
+# ---------------------------------------------------------------------------
+
+def save_parquet(df: pd.DataFrame, path: Path) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        df.to_parquet(path, index=False)
+    except Exception as exc:
+        raise RuntimeError(
+            "Parquet support requires pyarrow. Install with `pip install iints-sdk-python35[research]`."
+        ) from exc
+
+
+def save_dataset(df: pd.DataFrame, path: Path) -> None:
+    """Save dataset as parquet when available, or CSV as a fallback."""
+    if path.suffix.lower() in {".parquet", ".pq"}:
+        save_parquet(df, path)
+        return
+    path.parent.mkdir(parents=True, exist_ok=True)
+    df.to_csv(path, index=False)
+
+
+def load_parquet(path: Path) -> pd.DataFrame:
+    try:
+        return pd.read_parquet(path)
+    except Exception as exc:
+        raise RuntimeError(
+            "Parquet support requires pyarrow. Install with `pip install iints-sdk-python35[research]`."
+        ) from exc
+
+
+def load_dataset(path: Path) -> pd.DataFrame:
+    """Load a dataset from parquet or CSV."""
+    if path.suffix.lower() in {".parquet", ".pq"}:
+        return load_parquet(path)
+    if path.suffix.lower() in {".csv", ".txt"}:
+        return pd.read_csv(path)
+    raise ValueError(f"Unsupported dataset format: {path.suffix}")
+
+
+def concat_runs(frames: Iterable[pd.DataFrame]) -> pd.DataFrame:
+    return pd.concat(list(frames), ignore_index=True)
+
+
+def basic_stats(df: pd.DataFrame, columns: List[str]) -> Dict[str, float]:
+    stats: Dict[str, float] = {}
+    for col in columns:
+        if col in df.columns:
+            stats[f"{col}_mean"] = float(df[col].mean())
+            stats[f"{col}_std"] = float(df[col].std())
+    return stats

iints/research/losses.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from typing import Optional, TYPE_CHECKING
+
+try:
+    import torch
+    from torch import nn
+except Exception as exc:  # pragma: no cover
+    torch = None  # type: ignore
+    nn = None  # type: ignore
+    _IMPORT_ERROR: Optional[BaseException] = exc
+else:
+    _IMPORT_ERROR = None
+
+
+if TYPE_CHECKING:
+    import torch  # pragma: no cover
+    from torch import nn  # pragma: no cover
+
+    class QuantileLoss(nn.Module):
+        def __init__(self, quantile: float = 0.9) -> None: ...
+        def forward(self, preds: "torch.Tensor", targets: "torch.Tensor") -> "torch.Tensor": ...
+
+    class SafetyWeightedMSE(nn.Module):
+        def __init__(self, low_threshold: float = 80.0, alpha: float = 2.0, max_weight: float = 4.0) -> None: ...
+        def forward(self, preds: "torch.Tensor", targets: "torch.Tensor") -> "torch.Tensor": ...
+else:
+    if nn is None:  # pragma: no cover
+        class QuantileLoss:  # type: ignore[no-redef]
+            def __init__(self, *args: object, **kwargs: object) -> None:
+                raise ImportError(
+                    "Torch is required for QuantileLoss. Install with `pip install iints-sdk-python35[research]`."
+                ) from _IMPORT_ERROR
+
+        class SafetyWeightedMSE:  # type: ignore[no-redef]
+            def __init__(self, *args: object, **kwargs: object) -> None:
+                raise ImportError(
+                    "Torch is required for SafetyWeightedMSE. Install with `pip install iints-sdk-python35[research]`."
+                ) from _IMPORT_ERROR
+    else:
+        class QuantileLoss(nn.Module):  # type: ignore[misc,no-redef]
+            """Pinball / quantile loss for probabilistic forecasting."""
+
+            def __init__(self, quantile: float = 0.9) -> None:
+                super().__init__()
+                if not 0.0 < quantile < 1.0:
+                    raise ValueError(f"quantile must be in (0, 1), got {quantile}")
+                self.quantile = quantile
+
+            def forward(self, preds: "torch.Tensor", targets: "torch.Tensor") -> "torch.Tensor":
+                errors = targets - preds
+                loss = torch.where(
+                    errors >= 0,
+                    self.quantile * errors,
+                    (self.quantile - 1.0) * errors,
+                )
+                return loss.mean()
+
+        class SafetyWeightedMSE(nn.Module):  # type: ignore[misc,no-redef]
+            """MSE with extra weight on low-glucose targets (safety-critical)."""
+
+            def __init__(self, low_threshold: float = 80.0, alpha: float = 2.0, max_weight: float = 4.0) -> None:
+                super().__init__()
+                self.low_threshold = float(low_threshold)
+                self.alpha = float(alpha)
+                self.max_weight = float(max_weight)
+
+            def forward(self, preds: "torch.Tensor", targets: "torch.Tensor") -> "torch.Tensor":
+                # Emphasize errors below the low threshold
+                delta = torch.clamp(self.low_threshold - targets, min=0.0)
+                weights = 1.0 + self.alpha * (delta / max(self.low_threshold, 1.0))
+                weights = torch.clamp(weights, max=self.max_weight)
+                return ((preds - targets) ** 2 * weights).mean()