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

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()}
+        }

iints/api/base_algorithm.py

@@ -0,0 +1,300 @@
+from abc import ABC, abstractmethod
+from typing import Dict, Any, List, Optional
+from dataclasses import dataclass, field
+from datetime import datetime
+
+@dataclass
+class AlgorithmInput:
+    """Dataclass for inputs to the insulin prediction algorithm."""
+    current_glucose: float
+    time_step: float
+    insulin_on_board: float = 0.0
+    carb_intake: float = 0.0
+    patient_state: Dict[str, Any] = field(default_factory=dict)
+    current_time: float = 0.0 # Added current_time
+
+
+@dataclass
+class AlgorithmMetadata:
+    """Metadata for algorithm registration and identification"""
+    name: str
+    version: str = "1.0.0"
+    author: str = "IINTS-AF Team"
+    paper_reference: Optional[str] = None
+    description: str = ""
+    algorithm_type: str = "rule_based"  # 'rule_based', 'ml', 'hybrid'
+    requires_training: bool = False
+    supported_scenarios: List[str] = field(default_factory=lambda: [
+        'standard_meal', 'unannounced_meal', 'exercise', 
+        'stress', 'hypoglycemia', 'hyperglycemia'
+    ])
+    
+    def to_dict(self) -> Dict:
+        return {
+            'name': self.name,
+            'version': self.version,
+            'author': self.author,
+            'paper_reference': self.paper_reference,
+            'description': self.description,
+            'algorithm_type': self.algorithm_type,
+            'requires_training': self.requires_training,
+            'supported_scenarios': self.supported_scenarios
+        }
+
+
+@dataclass
+class AlgorithmResult:
+    """Result of an insulin prediction with uncertainty"""
+    total_insulin_delivered: float
+    bolus_insulin: float = 0.0
+    basal_insulin: float = 0.0
+    correction_bolus: float = 0.0
+    meal_bolus: float = 0.0
+    
+    # Uncertainty quantification
+    uncertainty: float = 0.0  # 0.0 = certain, 1.0 = very uncertain
+    confidence_interval: tuple = (0.0, 0.0)  # (lower, upper)
+    
+    # Clinical reasoning
+    primary_reason: str = ""
+    secondary_reasons: List[str] = field(default_factory=list)
+    safety_constraints: List[str] = field(default_factory=list)
+    
+    # Metadata
+    algorithm_name: str = ""
+    timestamp: datetime = field(default_factory=datetime.now)
+    
+    def to_dict(self) -> Dict:
+        return {
+            'total_insulin_delivered': self.total_insulin_delivered,
+            'bolus_insulin': self.bolus_insulin,
+            'basal_insulin': self.basal_insulin,
+            'correction_bolus': self.correction_bolus,
+            'meal_bolus': self.meal_bolus,
+            'uncertainty': self.uncertainty,
+            'confidence_interval': self.confidence_interval,
+            'primary_reason': self.primary_reason,
+            'secondary_reasons': self.secondary_reasons,
+            'safety_constraints': self.safety_constraints,
+            'algorithm_name': self.algorithm_name,
+            'timestamp': self.timestamp.isoformat()
+        }
+
+
+@dataclass
+class WhyLogEntry:
+    """Single entry in the Why Log explaining a decision reason"""
+    reason: str
+    category: str  # 'glucose_level', 'velocity', 'insulin_on_board', 'safety', 'context'
+    value: Any = None
+    clinical_impact: str = ""
+
+    def to_dict(self) -> Dict:
+        return {
+            'reason': self.reason,
+            'category': self.category,
+            'value': self.value,
+            'clinical_impact': self.clinical_impact
+        }
+
+class InsulinAlgorithm(ABC):
+    """
+    Abstract base class for insulin delivery algorithms.
+
+    All specific insulin algorithms used in the simulation framework should
+    inherit from this class and implement its abstract methods.
+    
+    This class supports the Plug-and-Play architecture, allowing any algorithm
+    to be registered and compared in Battle Mode.
+    """
+
+    def __init__(self, settings: Optional[Dict[str, Any]] = None):
+        """
+        Initializes the algorithm with its specific settings.
+
+        Args:
+            settings (Dict[str, Any]): A dictionary of algorithm-specific parameters.
+        """
+        self.settings = settings if settings is not None else {}
+        self.state: Dict[str, Any] = {}  # To store internal algorithm state across calls
+        self.why_log: List[WhyLogEntry] = []  # Decision reasoning log
+        self._metadata: Optional[AlgorithmMetadata] = None  # Lazy-loaded metadata
+        self.isf = self.settings.get('isf', 50.0)  # Default ISF
+        self.icr = self.settings.get('icr', 10.0)  # Default ICR
+
+    def set_isf(self, isf: float):
+        """Set the Insulin Sensitivity Factor (mg/dL per unit)."""
+        if isf <= 0:
+            raise ValueError("ISF must be a positive value.")
+        self.isf = isf
+        
+    def set_icr(self, icr: float):
+        """Set the Insulin-to-Carb Ratio (grams per unit)."""
+        if icr <= 0:
+            raise ValueError("ICR must be a positive value.")
+        self.icr = icr
+        
+    def get_algorithm_metadata(self) -> AlgorithmMetadata:
+        """
+        Get algorithm metadata. Override in subclasses for custom metadata.
+        
+        Returns:
+            AlgorithmMetadata: Information about the algorithm for registration
+        """
+        if self._metadata is None:
+            # Default metadata - override in subclasses
+            self._metadata = AlgorithmMetadata(
+                name=self.__class__.__name__,
+                version="1.0.0",
+                author="IINTS-AF Team",
+                description=f"Insulin algorithm: {self.__class__.__name__}",
+                algorithm_type="rule_based"
+            )
+        return self._metadata
+    
+    def set_algorithm_metadata(self, metadata: AlgorithmMetadata):
+        """Set custom algorithm metadata"""
+        self._metadata = metadata
+    
+    def calculate_uncertainty(self, data: AlgorithmInput) -> float:
+        """
+        Calculate uncertainty score for the current prediction.
+        
+        Override in subclasses to implement custom uncertainty quantification.
+        
+        Args:
+            data: Current algorithm input
+            
+        Returns:
+            float: Uncertainty score between 0.0 (certain) and 1.0 (very uncertain)
+        """
+        # Default: low uncertainty for rule-based algorithms
+        return 0.1
+    
+    def calculate_confidence_interval(self, 
+                                      data: AlgorithmInput,
+                                      prediction: float,
+                                      uncertainty: float) -> tuple:
+        """
+        Calculate confidence interval for the prediction.
+        
+        Args:
+            data: Current algorithm input
+            prediction: Predicted insulin dose
+            uncertainty: Uncertainty score
+            
+        Returns:
+            tuple: (lower_bound, upper_bound) for the prediction
+        """
+        # Default: ±20% of prediction based on uncertainty
+        margin = prediction * 0.2 * (1 + uncertainty)
+        return (max(0, prediction - margin), prediction + margin)
+    
+    def explain_prediction(self, 
+                          data: AlgorithmInput, 
+                          prediction: Dict[str, Any]) -> str:
+        """
+        Generate human-readable explanation for the prediction.
+        
+        This is used for the Reasoning Log in the Clinical Control Center.
+        
+        Args:
+            data: Algorithm input
+            prediction: Prediction dictionary
+            
+        Returns:
+            str: Explanation like "2 units delivered because glucose rising >2 mg/dL/min"
+        """
+        reasons = []
+        
+        # Glucose level reasoning
+        if data.current_glucose < 70:
+            reasons.append(f"glucose critically low at {data.current_glucose:.0f} mg/dL")
+        elif data.current_glucose < 100:
+            reasons.append(f"glucose approaching low at {data.current_glucose:.0f} mg/dL")
+        elif data.current_glucose > 180:
+            reasons.append(f"glucose elevated at {data.current_glucose:.0f} mg/dL")
+        else:
+            reasons.append(f"glucose in target range at {data.current_glucose:.0f} mg/dL")
+        
+        # Insulin on board
+        if data.insulin_on_board > 2.0:
+            reasons.append(f"high insulin on board ({data.insulin_on_board:.1f} U)")
+        elif data.insulin_on_board > 0.5:
+            reasons.append(f"moderate insulin on board ({data.insulin_on_board:.1f} U)")
+        
+        # Carbs
+        if data.carb_intake > 0:
+            reasons.append(f"meal detected ({data.carb_intake:.0f}g carbs)")
+        
+        if prediction.get('total_insulin_delivered', 0) > 0:
+            return f"{prediction['total_insulin_delivered']:.2f} units delivered because " + ", ".join(reasons)
+        else:
+            return f"No insulin delivered: " + ", ".join(reasons)
+
+    @abstractmethod
+    def predict_insulin(self, data: AlgorithmInput) -> Dict[str, Any]:
+        """
+        Calculates the insulin dose based on current physiological data.
+        This is the primary method to be implemented by custom algorithms.
+
+        Args:
+            data (AlgorithmInput): A dataclass containing all relevant data for the decision.
+
+        Returns:
+            Dict[str, Any]: A dictionary containing the calculated insulin doses.
+                            A key 'total_insulin_delivered' is expected by the simulator.
+                            (e.g., {'total_insulin_delivered': 1.5, 'bolus_insulin': 1.0, 'basal_insulin': 0.5})
+        """
+        # Clear why_log at start of each calculation
+        self.why_log = []
+        raise NotImplementedError("Subclasses must implement predict_insulin method")
+    
+    def _log_reason(self, reason: str, category: str, value: Any = None, clinical_impact: str = ""):
+        """Helper method to add reasoning to why_log"""
+        entry = WhyLogEntry(
+            reason=reason,
+            category=category,
+            value=value,
+            clinical_impact=clinical_impact
+        )
+        self.why_log.append(entry)
+    
+    def get_why_log(self) -> List[WhyLogEntry]:
+        """Get the decision reasoning log for the last calculation"""
+        return self.why_log
+    
+    def get_why_log_text(self) -> str:
+        """Get human-readable why log"""
+        if not self.why_log:
+            return "No decision reasoning available"
+        
+        text = "WHY_LOG:\n"
+        for entry in self.why_log:
+            text += f"- {entry.reason}"
+            if entry.value is not None:
+                text += f" (value: {entry.value})"
+            if entry.clinical_impact:
+                text += f" → {entry.clinical_impact}"
+            text += "\n"
+        return text
+
+    def reset(self):
+        """
+        Resets the algorithm's internal state.
+        This should be called at the start of each new simulation run.
+        """
+        self.state = {}
+        self.why_log = []
+
+    def get_state(self) -> Dict[str, Any]:
+        """
+        Returns the current internal state of the algorithm.
+        """
+        return self.state
+
+    def set_state(self, state: Dict[str, Any]):
+        """
+        Sets the internal state of the algorithm.
+        """
+        self.state = state