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

iints/analysis/safety_index.py

@@ -0,0 +1,311 @@
+"""
+IINTS-AF Safety Index
+=====================
+A single composite metric (0–100) that summarises the clinical safety of an
+insulin dosing algorithm's output.  Higher is safer.
+
+The index is designed to be:
+* **Clinically meaningful** — components map directly to FDA SaMD guidance
+  and ATTD/ADA consensus recommendations.
+* **Configurable** — researchers can adjust component weights via CLI flags
+  or direct API arguments to match the emphasis of their study protocol.
+* **Transparent** — every component and its contribution is reported
+  separately so the index can be audited and reproduced.
+
+Grades
+------
+A  ≥ 90   Excellent — suitable for well-controlled clinical setting
+B  ≥ 75   Good      — minor improvement recommended
+C  ≥ 60   Acceptable — targeted optimisation required
+D  ≥ 40   Poor      — significant safety concerns
+F  < 40   Fail      — unsafe; do not proceed to clinical evaluation
+
+References
+----------
+* Battelino et al. (2019) ATTD International Consensus on CGM Metrics.
+* Kovatchev et al. (2006) Symmetrisation of the Blood Glucose Measurement Scale.
+* FDA Guidance: Software as a Medical Device (SaMD).
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Dict, Optional, Tuple
+
+import numpy as np
+import pandas as pd
+
+
+# ---------------------------------------------------------------------------
+# Default component weights
+# ---------------------------------------------------------------------------
+
+DEFAULT_WEIGHTS: Dict[str, float] = {
+    "w_below54":     0.40,   # time-below-range critical (<54 mg/dL) — most dangerous
+    "w_below70":     0.25,   # time-below-range mild (<70 mg/dL)
+    "w_supervisor":  0.20,   # safety supervisor trigger rate (interventions/hr)
+    "w_recovery":    0.10,   # mean hypoglycaemia episode duration
+    "w_tail":        0.05,   # tail-risk binary (any glucose ever < 54 mg/dL)
+}
+
+# Normalisation scales — the raw value at which the component contributes
+# its FULL 100-point penalty.  Values above the scale are clamped to 100.
+NORM_SCALES: Dict[str, float] = {
+    "w_below54":    5.0,    # 5 % TBR critical  →  full penalty
+    "w_below70":   20.0,    # 20 % TBR low      →  full penalty
+    "w_supervisor": 12.0,   # 12 supervisor triggers/hr → full penalty
+    "w_recovery":    1.0,   # 1 hour mean episode duration → full penalty
+    "w_tail":        1.0,   # binary 0 or 1
+}
+
+
+def _validate_weights(weights: Dict[str, float]) -> None:
+    for key in DEFAULT_WEIGHTS:
+        if key not in weights:
+            raise ValueError(f"Missing weight key: {key!r}")
+        if weights[key] < 0:
+            raise ValueError(f"Weight {key!r} must be >= 0, got {weights[key]}")
+    total = sum(weights.values())
+    if total <= 0:
+        raise ValueError("Sum of all weights must be > 0")
+
+
+def _norm(value: float, scale: float) -> float:
+    """Normalise raw value to [0, 100] given the full-penalty scale."""
+    if scale <= 0:
+        return 0.0
+    return min(value / scale, 1.0) * 100.0
+
+
+def _grade(score: float) -> str:
+    if score >= 90:
+        return "A"
+    if score >= 75:
+        return "B"
+    if score >= 60:
+        return "C"
+    if score >= 40:
+        return "D"
+    return "F"
+
+
+def _interpret(score: float, penalties: Dict[str, float], weights: Dict[str, float]) -> str:
+    """Generate a one-sentence human-readable interpretation."""
+    grade = _grade(score)
+    grade_labels = {"A": "Excellent", "B": "Good", "C": "Acceptable", "D": "Poor", "F": "Fail"}
+    label = grade_labels[grade]
+
+    # Identify the top penalty contributor
+    weighted = {k: weights[k] * _norm(v, NORM_SCALES[k]) for k, v in penalties.items()}
+    top_key = max(weighted, key=lambda k: weighted[k])
+    key_labels = {
+        "w_below54":    "time critically below 54 mg/dL",
+        "w_below70":    "time below 70 mg/dL",
+        "w_supervisor": "safety supervisor trigger rate",
+        "w_recovery":   "hypoglycaemia episode duration",
+        "w_tail":       "occurrence of critical hypoglycaemia",
+    }
+
+    if score >= 90:
+        return f"{label}: Minimal safety concerns across all components."
+    dominant = key_labels[top_key]
+    return f"{label}: Primary concern is {dominant} (score={score:.1f}/100)."
+
+
+# ---------------------------------------------------------------------------
+# Main result dataclass
+# ---------------------------------------------------------------------------
+
+@dataclass
+class SafetyIndexResult:
+    """Result of the IINTS Safety Index computation."""
+
+    score: float
+    """Composite safety score in [0, 100].  Higher is safer."""
+
+    grade: str
+    """Letter grade: A, B, C, D, or F."""
+
+    components: Dict[str, float]
+    """Normalised (0–100) per-component penalty before weighting."""
+
+    penalties: Dict[str, float]
+    """Raw penalty values (before normalisation and weighting)."""
+
+    weights: Dict[str, float]
+    """Component weights used in this computation."""
+
+    interpretation: str
+    """Human-readable one-sentence summary."""
+
+    def to_dict(self) -> dict:
+        return {
+            "safety_index": self.score,
+            "grade": self.grade,
+            "interpretation": self.interpretation,
+            "components": self.components,
+            "penalties": self.penalties,
+            "weights": self.weights,
+        }
+
+    def __str__(self) -> str:
+        return (
+            f"Safety Index: {self.score:.1f}/100  (Grade: {self.grade})\n"
+            f"  {self.interpretation}\n"
+            f"  Components: "
+            + ", ".join(f"{k.replace('w_', '')}={v:.1f}" for k, v in self.components.items())
+        )
+
+
+# ---------------------------------------------------------------------------
+# Core computation
+# ---------------------------------------------------------------------------
+
+def _compute_hypo_episode_duration(glucose: pd.Series, time_step_minutes: float) -> float:
+    """
+    Compute mean hypoglycaemia episode duration in minutes.
+
+    An episode starts when glucose drops below 70 mg/dL and ends when it
+    rises back above 70 mg/dL.  Returns 0.0 if no episodes.
+    """
+    below = (glucose < 70.0).to_numpy(dtype=bool)
+    if not np.any(below):
+        return 0.0
+
+    episode_lengths: list[int] = []
+    in_episode = False
+    length = 0
+    for b in below:
+        if b:
+            in_episode = True
+            length += 1
+        else:
+            if in_episode:
+                episode_lengths.append(length)
+                in_episode = False
+                length = 0
+    if in_episode and length > 0:
+        episode_lengths.append(length)
+
+    if not episode_lengths:
+        return 0.0
+    return float(np.mean(episode_lengths)) * time_step_minutes
+
+
+def compute_safety_index(
+    results_df: pd.DataFrame,
+    safety_report: Dict,
+    duration_minutes: int,
+    weights: Optional[Dict[str, float]] = None,
+    time_step_minutes: float = 5.0,
+) -> SafetyIndexResult:
+    """
+    Compute the IINTS Safety Index from a simulation run.
+
+    Parameters
+    ----------
+    results_df : pd.DataFrame
+        Output of ``Simulator.run_batch()``.  Must contain
+        ``glucose_actual_mgdl`` and ``safety_triggered`` columns.
+    safety_report : dict
+        Safety report dict returned by ``Simulator.run_batch()``.
+        Must contain ``bolus_interventions_count`` (int).
+    duration_minutes : int
+        Total simulation duration in minutes.
+    weights : dict, optional
+        Component weights.  If None, ``DEFAULT_WEIGHTS`` are used.
+        Must contain keys: ``w_below54``, ``w_below70``, ``w_supervisor``,
+        ``w_recovery``, ``w_tail``.
+    time_step_minutes : float
+        Simulator time step in minutes (default 5).
+
+    Returns
+    -------
+    SafetyIndexResult
+    """
+    if weights is None:
+        weights = dict(DEFAULT_WEIGHTS)
+    else:
+        weights = dict(weights)  # defensive copy
+    _validate_weights(weights)
+
+    glucose_series = results_df["glucose_actual_mgdl"].astype(float)
+    glucose = glucose_series.to_numpy(dtype=float)
+    n = max(len(glucose), 1)
+
+    # --- Component 1: TBR critical < 54 mg/dL (%) ---
+    tbr_critical = float((glucose < 54.0).sum()) / n * 100.0
+
+    # --- Component 2: TBR low < 70 mg/dL (%) ---
+    tbr_low = float((glucose < 70.0).sum()) / n * 100.0
+
+    # --- Component 3: Supervisor trigger rate (triggers / hour) ---
+    duration_hours = max(duration_minutes / 60.0, 1e-9)
+    interventions = int(safety_report.get("bolus_interventions_count", 0))
+    supervisor_rate = interventions / duration_hours
+
+    # --- Component 4: Mean hypo episode duration (hours) ---
+    mean_episode_hr = _compute_hypo_episode_duration(glucose_series, time_step_minutes) / 60.0
+
+    # --- Component 5: Tail-risk binary (1 if any glucose < 54, else 0) ---
+    tail_risk = 1.0 if np.any(glucose < 54.0) else 0.0
+
+    penalties: Dict[str, float] = {
+        "w_below54":    tbr_critical,
+        "w_below70":    tbr_low,
+        "w_supervisor": supervisor_rate,
+        "w_recovery":   mean_episode_hr,
+        "w_tail":       tail_risk,
+    }
+
+    components: Dict[str, float] = {
+        k: _norm(penalties[k], NORM_SCALES[k]) for k in penalties
+    }
+
+    # --- Weighted sum of penalties ---
+    total_weight = sum(weights.values())
+    weighted_penalty = sum(
+        weights[k] * components[k] for k in weights
+    ) / total_weight
+
+    score = float(np.clip(100.0 - weighted_penalty, 0.0, 100.0))
+    grade = _grade(score)
+    interpretation = _interpret(score, penalties, weights)
+
+    return SafetyIndexResult(
+        score=score,
+        grade=grade,
+        components=components,
+        penalties=penalties,
+        weights=dict(weights),
+        interpretation=interpretation,
+    )
+
+
+def safety_weights_from_cli(
+    w_below54: Optional[float] = None,
+    w_below70: Optional[float] = None,
+    w_supervisor: Optional[float] = None,
+    w_recovery: Optional[float] = None,
+    w_tail: Optional[float] = None,
+) -> Dict[str, float]:
+    """
+    Build a weights dict from CLI arguments.  Any ``None`` values fall back
+    to the corresponding default weight.
+
+    Intended usage in CLI commands::
+
+        weights = safety_weights_from_cli(
+            w_below54=args.safety_w_below54,
+            w_below70=args.safety_w_below70,
+            ...
+        )
+        result = compute_safety_index(df, report, duration, weights=weights)
+    """
+    defaults = dict(DEFAULT_WEIGHTS)
+    return {
+        "w_below54":    w_below54    if w_below54    is not None else defaults["w_below54"],
+        "w_below70":    w_below70    if w_below70    is not None else defaults["w_below70"],
+        "w_supervisor": w_supervisor if w_supervisor is not None else defaults["w_supervisor"],
+        "w_recovery":   w_recovery   if w_recovery   is not None else defaults["w_recovery"],
+        "w_tail":       w_tail       if w_tail       is not None else defaults["w_tail"],
+    }

iints/analysis/sensor_filtering.py

@@ -0,0 +1,54 @@
+import numpy as np
+from collections import deque
+
+class SensorNoiseModel:
+    """Realistic sensor noise with drift and filtering."""
+    
+    def __init__(self, white_noise_std=15, drift_rate=0.1, drift_amplitude=10):
+        self.white_noise_std = white_noise_std
+        self.drift_rate = drift_rate
+        self.drift_amplitude = drift_amplitude
+        self.drift_phase = 0
+        
+    def add_noise(self, true_glucose, time_step):
+        """Add realistic sensor noise with drift."""
+        white_noise = np.random.normal(0, self.white_noise_std)
+        drift = self.drift_amplitude * np.sin(self.drift_phase)
+        self.drift_phase += self.drift_rate * time_step / 60  # Convert to hours
+        
+        return true_glucose + white_noise + drift
+
+class KalmanFilter:
+    """Simple Kalman filter for glucose smoothing."""
+    
+    def __init__(self, process_variance=1, measurement_variance=225):
+        self.process_variance = process_variance
+        self.measurement_variance = measurement_variance
+        self.estimate = None
+        self.error_estimate = 1000
+        
+    def update(self, measurement):
+        if self.estimate is None:
+            self.estimate = measurement
+            return measurement
+            
+        # Prediction
+        prediction = self.estimate
+        prediction_error = self.error_estimate + self.process_variance
+        
+        # Update
+        kalman_gain = prediction_error / (prediction_error + self.measurement_variance)
+        self.estimate = prediction + kalman_gain * (measurement - prediction)
+        self.error_estimate = (1 - kalman_gain) * prediction_error
+        
+        return self.estimate
+
+class MovingAverageFilter:
+    """Simple moving average filter."""
+    
+    def __init__(self, window_size=3):
+        self.window = deque(maxlen=window_size)
+        
+    def update(self, value):
+        self.window.append(value)
+        return sum(self.window) / len(self.window)

iints/analysis/validator.py

@@ -0,0 +1,273 @@
+import numpy as np
+import pandas as pd
+from typing import Dict, List, Tuple, Optional, Any
+from dataclasses import dataclass
+from enum import Enum
+
+class ReliabilityLevel(Enum):
+    HIGH = "high"
+    MEDIUM = "medium" 
+    LOW = "low"
+    CRITICAL = "critical"
+
+@dataclass
+class ValidationResult:
+    passed: bool
+    reliability_score: float  # 0-100%
+    level: ReliabilityLevel
+    issues: List[str]
+    warnings: List[str]
+
+class DataIntegrityValidator:
+    """Validates data integrity for reverse engineering analysis."""
+    
+    def __init__(self):
+        # Physiological limits
+        self.max_glucose_rate = 10  # mg/dL per minute
+        self.glucose_range = (20, 600)  # Physiologically possible range
+        self.max_insulin_per_step = 5.0  # Units per 5-min step
+        
+    def validate_glucose_data(self, glucose_values: List[float], timestamps: List[float]) -> ValidationResult:
+        """Validate glucose data for physiological plausibility."""
+        issues = []
+        warnings: List[str] = []
+        score = 100.0
+        
+        # Check range
+        for i, glucose in enumerate(glucose_values):
+            if not (self.glucose_range[0] <= glucose <= self.glucose_range[1]):
+                issues.append(f"Glucose {glucose} at step {i} outside physiological range")
+                score -= 10
+        
+        # Check rate of change
+        for i in range(1, len(glucose_values)):
+            if len(timestamps) > i:
+                time_diff = timestamps[i] - timestamps[i-1]
+                glucose_diff = abs(glucose_values[i] - glucose_values[i-1])
+                rate = glucose_diff / time_diff if time_diff > 0 else float('inf')
+                
+                if rate > self.max_glucose_rate:
+                    issues.append(f"Impossible glucose rate: {rate:.1f} mg/dL/min at step {i}")
+                    score -= 15
+        
+        # Check for missing values (NaN)
+        nan_count = sum(1 for g in glucose_values if pd.isna(g))
+        if nan_count > 0:
+            warnings.append(f"{nan_count} missing glucose values detected")
+            score -= nan_count * 5
+        
+        # Determine reliability level
+        if score >= 90:
+            level = ReliabilityLevel.HIGH
+        elif score >= 70:
+            level = ReliabilityLevel.MEDIUM
+        elif score >= 50:
+            level = ReliabilityLevel.LOW
+        else:
+            level = ReliabilityLevel.CRITICAL
+        
+        return ValidationResult(
+            passed=len(issues) == 0,
+            reliability_score=max(0, score),
+            level=level,
+            issues=issues,
+            warnings=warnings
+        )
+    
+    def validate_insulin_data(self, insulin_values: List[float]) -> ValidationResult:
+        """Validate insulin delivery data."""
+        issues = []
+        warnings: List[str] = []
+        score = 100.0
+        
+        for i, insulin in enumerate(insulin_values):
+            if insulin < 0:
+                issues.append(f"Negative insulin {insulin} at step {i}")
+                score -= 20
+            elif insulin > self.max_insulin_per_step:
+                warnings.append(f"High insulin dose {insulin} at step {i}")
+                score -= 5
+        
+        level = ReliabilityLevel.HIGH if score >= 90 else ReliabilityLevel.MEDIUM if score >= 70 else ReliabilityLevel.LOW
+        
+        return ValidationResult(
+            passed=len(issues) == 0,
+            reliability_score=max(0, score),
+            level=level,
+            issues=issues,
+            warnings=warnings
+        )
+
+class AlgorithmicDriftDetector:
+    """Detects when AI algorithms drift from safe baseline behavior."""
+    
+    def __init__(self, drift_threshold=0.5):  # 50% difference threshold
+        self.drift_threshold = drift_threshold
+        
+    def detect_drift(self, ai_outputs: List[float], baseline_outputs: List[float]) -> ValidationResult:
+        """Compare AI outputs against rule-based baseline."""
+        issues = []
+        warnings: List[str] = []
+        score = 100.0
+        
+        if len(ai_outputs) != len(baseline_outputs):
+            issues.append("AI and baseline output lengths don't match")
+            return ValidationResult(False, 0, ReliabilityLevel.CRITICAL, issues, warnings)
+        
+        drift_count = 0
+        extreme_drift_count = 0
+        
+        for i, (ai_val, baseline_val) in enumerate(zip(ai_outputs, baseline_outputs)):
+            if baseline_val == 0:
+                if ai_val > 0.1:  # AI gives insulin when baseline gives none
+                    drift_count += 1
+                    warnings.append(f"AI delivers insulin ({ai_val:.2f}) when baseline gives none at step {i}")
+            else:
+                relative_diff = abs(ai_val - baseline_val) / baseline_val
+                if relative_diff > self.drift_threshold:
+                    drift_count += 1
+                    if relative_diff > 1.0:  # 100% difference
+                        extreme_drift_count += 1
+                        issues.append(f"Extreme drift: AI={ai_val:.2f}, Baseline={baseline_val:.2f} at step {i}")
+                    else:
+                        warnings.append(f"Drift detected: {relative_diff:.1%} difference at step {i}")
+        
+        # Calculate score based on drift frequency
+        drift_rate = drift_count / len(ai_outputs)
+        extreme_drift_rate = extreme_drift_count / len(ai_outputs)
+        
+        score -= drift_rate * 50  # Penalize drift
+        score -= extreme_drift_rate * 30  # Extra penalty for extreme drift
+        
+        if extreme_drift_count > 0:
+            level = ReliabilityLevel.CRITICAL
+        elif drift_rate > 0.3:
+            level = ReliabilityLevel.LOW
+        elif drift_rate > 0.1:
+            level = ReliabilityLevel.MEDIUM
+        else:
+            level = ReliabilityLevel.HIGH
+        
+        return ValidationResult(
+            passed=extreme_drift_count == 0,
+            reliability_score=max(0, score),
+            level=level,
+            issues=issues,
+            warnings=warnings
+        )
+
+class StatisticalReliabilityChecker:
+    """Checks statistical reliability of Monte Carlo results."""
+    
+    def __init__(self, min_runs=10, max_cv=0.3):  # Max 30% coefficient of variation
+        self.min_runs = min_runs
+        self.max_cv = max_cv
+        
+    def check_monte_carlo_reliability(self, results: List[List[float]]) -> ValidationResult:
+        """Check if Monte Carlo results are statistically reliable."""
+        issues = []
+        warnings: List[str] = []
+        score = 100.0
+        
+        if len(results) < self.min_runs:
+            issues.append(f"Insufficient runs: {len(results)} < {self.min_runs}")
+            score -= 30
+        
+        # Calculate coefficient of variation for each time step
+        if len(results) > 1:
+            results_array = np.array(results)
+            means = np.mean(results_array, axis=0)
+            stds = np.std(results_array, axis=0)
+            
+            # Avoid division by zero
+            cvs = np.divide(stds, means, out=np.zeros_like(stds), where=means!=0)
+            
+            high_variance_steps = np.sum(cvs > self.max_cv)
+            if high_variance_steps > 0:
+                variance_rate = high_variance_steps / len(cvs)
+                if variance_rate > 0.5:
+                    issues.append(f"High variance in {variance_rate:.1%} of time steps")
+                    score -= 40
+                else:
+                    warnings.append(f"Moderate variance in {variance_rate:.1%} of time steps")
+                    score -= 20
+        
+        level = ReliabilityLevel.HIGH if score >= 90 else ReliabilityLevel.MEDIUM if score >= 70 else ReliabilityLevel.LOW
+        
+        return ValidationResult(
+            passed=len(issues) == 0,
+            reliability_score=max(0, score),
+            level=level,
+            issues=issues,
+            warnings=warnings
+        )
+
+class ReverseEngineeringValidator:
+    """Main validator for reverse engineering analysis."""
+    
+    def __init__(self):
+        self.data_validator = DataIntegrityValidator()
+        self.drift_detector = AlgorithmicDriftDetector()
+        self.reliability_checker = StatisticalReliabilityChecker()
+        
+    def validate_simulation_results(self, simulation_df: pd.DataFrame, 
+                                  baseline_results: Optional[List[float]] = None,
+                                  monte_carlo_results: Optional[List[List[float]]] = None) -> Dict[str, ValidationResult]:
+        """Comprehensive validation of simulation results."""
+        
+        results = {}
+        
+        # 1. Data integrity validation
+        glucose_values = simulation_df['glucose_actual_mgdl'].tolist()
+        timestamps = simulation_df['time_minutes'].tolist()
+        insulin_values = simulation_df['delivered_insulin_units'].tolist()
+        
+        results['glucose_integrity'] = self.data_validator.validate_glucose_data(glucose_values, timestamps)
+        results['insulin_integrity'] = self.data_validator.validate_insulin_data(insulin_values)
+        
+        # 2. Algorithmic drift detection
+        if baseline_results:
+            results['algorithmic_drift'] = self.drift_detector.detect_drift(insulin_values, baseline_results)
+        
+        # 3. Statistical reliability
+        if monte_carlo_results:
+            results['statistical_reliability'] = self.reliability_checker.check_monte_carlo_reliability(monte_carlo_results)
+        
+        return results
+    
+    def generate_reliability_report(self, validation_results: Dict[str, ValidationResult]) -> Dict[str, Any]:
+        """Generate comprehensive reliability report."""
+        
+        overall_score = np.mean([result.reliability_score for result in validation_results.values()])
+        
+        all_issues = []
+        all_warnings = []
+        
+        for category, result in validation_results.items():
+            all_issues.extend([f"{category}: {issue}" for issue in result.issues])
+            all_warnings.extend([f"{category}: {warning}" for warning in result.warnings])
+        
+        # Determine overall reliability
+        if overall_score >= 90:
+            overall_level = ReliabilityLevel.HIGH
+            recommendation = "Results are highly reliable for reverse engineering analysis"
+        elif overall_score >= 70:
+            overall_level = ReliabilityLevel.MEDIUM
+            recommendation = "Results are moderately reliable - consider additional validation"
+        elif overall_score >= 50:
+            overall_level = ReliabilityLevel.LOW
+            recommendation = "Results have low reliability - use with caution"
+        else:
+            overall_level = ReliabilityLevel.CRITICAL
+            recommendation = "Results are unreliable - do not use for analysis"
+        
+        return {
+            "overall_reliability_score": overall_score,
+            "overall_level": overall_level.value,
+            "recommendation": recommendation,
+            "total_issues": len(all_issues),
+            "total_warnings": len(all_warnings),
+            "issues": all_issues,
+            "warnings": all_warnings,
+            "category_scores": {category: result.reliability_score for category, result in validation_results.items()}
+        }