# Health Analytics Service

The Health Analytics Service provides advanced statistical analysis capabilities for health-related data. It's designed to identify patterns, correlations, and insights in health metrics through a high-performance native C++ implementation with a Dart interface.

This service leverages Foreign Function Interface (FFI) to bridge Dart applications with the C++ analytics engine, enabling complex health data analysis with minimal computational overhead in Flutter applications.

Key capabilities include statistical computations, correlation identification, time series analysis, anomaly detection, clustering, and health-specific analyses like medication impact and hormone level monitoring.


## Table of Contents
- [Core Features](#core-features)
- [API Reference](#api-reference)
  - [Basic Statistics](#basic-statistics)
  - [Trend Analysis](#trend-analysis)
  - [Correlation Analysis](#correlation-analysis)
  - [Multivariate Analysis](#multivariate-analysis)
  - [Cluster Analysis](#cluster-analysis)
  - [Time Series Forecasting](#time-series-forecasting)
  - [Anomaly Detection](#anomaly-detection)
  - [Factor Impact Analysis](#factor-impact-analysis)
  - [Date Pattern Analysis](#date-pattern-analysis)
  - [Cycle Analysis](#cycle-analysis)
  - [Medication Impact Analysis](#medication-impact-analysis)
  - [Hormone Analysis](#hormone-analysis)
  - [Comprehensive Analysis](#comprehensive-analysis)
- [Data Models](#data-models)
- [Example Usage](#example-usage)
- [Performance Considerations](#performance-considerations)
- [Troubleshooting](#troubleshooting)

## Core Features

The Health Analytics Service provides the following core functionalities:

- **Statistical Analysis**: Calculate mean, median, variance, standard deviation, quartiles, skewness, and kurtosis for health metrics.
- **Trend Detection**: Identify increasing, decreasing, cyclic, or variable trends in time series data.
- **Correlation Analysis**: Find relationships between various health factors and determine their significance.
- **Multivariate Analysis**: Explore complex relationships between multiple health variables.
- **Clustering**: Group similar health patterns together to identify natural categories.
- **Time Series Forecasting**: Predict future values of health metrics based on historical data.
- **Anomaly Detection**: Identify unusual patterns or outliers in health data.
- **Factor Impact Analysis**: Determine which factors have the strongest influence on target health metrics.
- **Temporal Pattern Analysis**: Discover cyclical patterns and date-related trends (e.g., weekly patterns).
- **Medication Impact Analysis**: Assess how medications affect various health metrics.
- **Hormone Analysis**: Evaluate hormone levels and their impact on health factors.
- **Comprehensive Analysis**: Integrate multiple analysis techniques for holistic health insights.

## API Reference

### Basic Statistics

Calculate fundamental statistics for a health metric:

```dart
HealthStatistics stats = analyticsService.calculateStatistics(values);
```

The `HealthStatistics` object provides:

- mean
- median 
- min/max values
- standard deviation
- variance
- skewness
- kurtosis
- quartiles (Q1, Q3)
- interquartile range (IQR)

### Trend Analysis

Detect trends in time series data:

```dart
TrendAnalysis trend = analyticsService.detectTrend(values);
```

This returns a `TrendAnalysis` with:

- trend type (increasing, decreasing, cyclic, variable, or none)
- strength (0-1 scale)
- description of the detected trend

### Correlation Analysis

Find correlations between a target variable and multiple factors:

```dart
List<FactorCorrelation> correlations = analyticsService.findCorrelations(
  targetValues,
  factorData,
);
```

Where:

- `targetValues` is a list of double values for the target metric
- `factorData` is a map of factor names to lists of double values

Returns a list of `FactorCorrelation` objects with:

- factor name
- correlation coefficient (-1 to 1)
- p-value
- confidence level

### Multivariate Analysis

Find complex relationships between multiple factors:

```dart
List<MultivariateRelationship> relationships = analyticsService.findMultivariateCorrelations(
  factorData,
);
```

This identifies various relationship types (direct correlation, mediation, network effects) between three or more factors.

### Cluster Analysis

Group similar data points based on multiple factors:

```dart
List<ClusterPattern> clusters = analyticsService.performClusterAnalysis(
  factorData,
  maxClusters,
);
```

This identifies natural groupings in the data, returning:

- cluster ID and name
- number of points in each cluster
- significance score
- key factors defining each cluster
- detailed description

### Time Series Forecasting

Predict future values of a health metric:

```dart
TimeSeriesPrediction forecast = analyticsService.predictTimeSeries(
  factorName,
  timeSeriesData,
  stepsAhead,
);
```

Returns predictions with confidence intervals and seasonality information.

### Anomaly Detection

Identify unusual patterns or outliers in health data:

```dart
List<AnomalyResult> anomalies = analyticsService.detectAnomalies(
  factorName,
  timeSeriesData,
  dates,
  threshold,
);
```

Detects statistical outliers, contextual anomalies, and trend changes.

### Factor Impact Analysis

Determine which factors have the strongest influence on a target metric:

```dart
List<FactorImpact> impacts = analyticsService.rankFactorImpacts(
  factorData,
  targetData,
);
```

This analyzes both direct and indirect effects of factors, returning:

- impact score
- direct effect
- indirect effect (through other factors)
- confidence level
- mechanism description

### Date Pattern Analysis

Discover patterns related to specific times (day of week, month, etc.):

```dart
List<DatePattern> patterns = analyticsService.analyzeDatePatterns(
  factorName,
  values,
  dates,
);
```

Identifies weekly, monthly, or custom periodicity patterns.

### Cycle Analysis

Analyze cyclical patterns in health data:

```dart
CycleAnalysis cycles = analyticsService.analyzeCycles(
  factorName,
  values,
  dates,
);
```

Returns information about:

- cycle length
- amplitude
- phase shift
- confidence level
- variance in cycle length

### Medication Impact Analysis

Assess how medications affect health metrics:

```dart
MedicationImpactResult impact = analyticsService.analyzeMedicationImpact(
  medicationName,
  factorName,
  beforeData,
  afterData,
);
```

Compares health metrics before and after medication, providing:

- mean values before and after
- magnitude and significance of changes
- overall impact score
- estimated days to effect

### Hormone Analysis

Evaluate hormone levels and their impact on health factors:

```dart
HormoneImpactResult hormoneImpact = analyticsService.analyzeHormoneImpact(
  hormoneName,
  hormoneLevels,
  factorData,
  minOptimalLevel,
  maxOptimalLevel,
);
```

Provides information about:

- current vs. optimal hormone levels
- deviation from optimal range
- impact on mood and energy
- correlations with other health factors

### Comprehensive Analysis

Generate a holistic analysis combining multiple techniques:

```dart
ComprehensiveHealthAnalysis analysis = await analyticsService.generateComprehensiveAnalysis(
  moodEntries: moodEntries,
  medications: medications,
  takenMedications: takenMedications,
  bloodworkEntries: bloodworkEntries,
  timeframe: "3 months",
);
```

This integrates all analysis methods to provide a complete health overview.

## Data Models

The service uses the following core data models:

### Health Statistics
```dart
class HealthStatistics {
  final double mean;
  final double median;
  final double min;
  final double max;
  final double stdDev;
  final double variance;
  final double skewness;
  final double kurtosis;
  final double q1;
  final double q3;
  final double iqr;
}
```

### Trend Analysis
```dart
class TrendAnalysis {
  final TrendType type; // enum: none, increasing, decreasing, cyclic, variable
  final double strength;
  final String description;
}
```

### Factor Correlation
```dart
class FactorCorrelation {
  final String factorName;
  final double correlation;
  final double pValue;
  final double confidence;
}
```

### Multivariate Relationship
```dart
class MultivariateRelationship {
  final List<String> factorNames;
  final double correlationStrength;
  final String description;
  final double confidence;
  final List<double> factorWeights;
  final RelationshipType relationshipType;
}
```

### Cluster Pattern
```dart
class ClusterPattern {
  final int id;
  final String name;
  final String description;
  final int pointCount;
  final double significance;
  final List<String> keyFactors;
  final List<double> factorImportance;
}
```

### Time Series Prediction
```dart
class TimeSeriesPrediction {
  final String factorName;
  final List<double> predictions;
  final List<List<double>> confidenceIntervals;
  final double confidence;
  final int seasonalityPeriod;
  final TimeUnit timeUnit;
}
```

### Anomaly Result
```dart
class AnomalyResult {
  final String factorName;
  final int dataPointIndex;
  final double anomalyScore;
  final String description;
  final double originalValue;
  final double expectedValue;
  final DateTime? date;
  final double confidence;
  final AnomalyType anomalyType;
}
```

### Factor Impact
```dart
class FactorImpact {
  final String factorName;
  final double impactScore;
  final double directEffect;
  final double indirectEffect;
  final double confidence;
  final String mechanism;
}
```

### Date Pattern
```dart
class DatePattern {
  final PatternType type;
  final int periodicity;
  final double strength;
  final String description;
  final List<double> peakValues;
  final int peakDayOfWeek;
  final int peakDayOfMonth;
  final int peakMonth;
}
```

### Cycle Analysis
```dart
class CycleAnalysis {
  final double cycleLength;
  final double cycleLengthVariance;
  final double amplitude;
  final double phaseShift;
  final double confidence;
  final String description;
}
```

### Medication Impact Result
```dart
class MedicationImpactResult {
  final String medicationName;
  final String factorName;
  final double beforeMean;
  final double afterMean;
  final double changeMagnitude;
  final double changeSignificance;
  final double overallImpact;
  final int daysToEffect;
  final String description;
}
```

### Hormone Impact Result
```dart
class HormoneImpactResult {
  final String hormoneName;
  final double currentLevel;
  final double optimalLevel;
  final double optimalRangeLower;
  final double optimalRangeUpper;
  final double deviation;
  final double impactOnMood;
  final double impactOnEnergy;
  final Map<String, double> factorImpacts;
  final String description;
}
```

### Comprehensive Health Analysis
```dart
class ComprehensiveHealthAnalysis {
  final TrendAnalysis moodTrend;
  final List<MultivariateRelationship> factorCorrelations;
  final List<ClusterPattern> clusters;
  final List<AnomalyResult> anomalies;
  final List<FactorImpact> factorImpacts;
  final List<TimeSeriesPrediction> predictions;
  final List<DatePattern> datePatterns;
  final List<CycleAnalysis> cycleAnalyses;
  final List<HormoneImpactResult> hormoneImpacts;
  final List<MedicationImpactResult> medicationImpacts;
  final DateTime analysisDate;
  final String timeframe;
}
```

## Example Usage

```dart
import 'package:nokken/src/features/health_analytics/health_analytics_service.dart';
import 'package:nokken/src/features/mood_tracker/models/mood_entry.dart';
import 'package:nokken/src/features/medication_tracker/models/medication.dart';
import 'package:nokken/src/features/bloodwork_tracker/models/bloodwork.dart';

Future<void> generateHealthInsights(
  List<MoodEntry> moodEntries,
  List<Medication> medications,
  List<Bloodwork> bloodworkEntries,
) async {
  final analyticsService = HealthAnalyticsService();
  await analyticsService.initialize();
  
  if (!analyticsService.isInitialized) {
    print('Failed to initialize analytics service');
    return;
  }
  
  // Determine which medications the user is currently taking
  final takenMedications = medications
      .where((med) => med.isActive)
      .map((med) => med.id)
      .toSet();
  
  // Generate comprehensive analysis
  final analysis = await analyticsService.generateComprehensiveAnalysis(
    moodEntries: moodEntries,
    medications: medications,
    takenMedications: takenMedications,
    bloodworkEntries: bloodworkEntries,
    timeframe: '3 months',
  );
  
  // Present key insights
  print('=== HEALTH INSIGHTS ===');
  print('Analysis date: ${analysis.analysisDate}');
  print('Timeframe: ${analysis.timeframe}');
  
  // Mood trend
  print('\n== Mood Trend ==');
  print(analysis.moodTrend.description);
  
  // Key correlations
  print('\n== Key Correlations ==');
  for (final correlation in analysis.factorCorrelations.take(3)) {
    print(correlation.description);
  }
  
  // Anomalies
  print('\n== Anomalies Detected ==');
  for (final anomaly in analysis.anomalies.take(5)) {
    print('${anomaly.factorName}: ${anomaly.description}');
    if (anomaly.date != null) {
      print('Date: ${anomaly.date}');
    }
  }
  
  // Medication impacts
  print('\n== Medication Impacts ==');
  for (final impact in analysis.medicationImpacts) {
    print('${impact.medicationName} → ${impact.factorName}: ${impact.description}');
  }
  
  // Predictions
  print('\n== Predictions ==');
  for (final prediction in analysis.predictions.take(3)) {
    print('${prediction.factorName} next week: ${prediction.predictions.first.toStringAsFixed(1)} (confidence: ${(prediction.confidence * 100).toStringAsFixed(1)}%)');
  }
}
```

## Performance Considerations

The Health Analytics Service uses a high-performance C++ implementation for computation-intensive operations, but there are still important considerations for optimal usage:

1. **Data Volume**: The service performs well with typical health tracking data volumes (hundreds to thousands of data points), but very large datasets may require batching or sampling.

2. **Memory Management**: The service handles memory allocation and deallocation for native resources, but be mindful of large data structures in Dart code.

3. **Initialization Cost**: The first call to `initialize()` has a one-time overhead for loading the native library.

4. **Operation Complexity**: Operations like cluster analysis and multivariate correlation have higher computational complexity.

5. **Platform Differences**: Performance may vary across platforms. iOS and Android have different native code optimization levels.

## Troubleshooting

### Common Issues

#### Native Library Loading Failures

If you encounter issues loading the native library:

1. Verify the native libraries are correctly placed in platform-specific directories
2. Check that library names match expected platform conventions:

   |Platform|Library|
   |-------|------|
   |Android|`libhealth_analytics.so`|
   |iOS|Framework or dynamic library|
   |Linux|`libhealth_analytics.so`|

3. For Android, ensure the correct ABIs are supported in your `build.gradle`:

```gradle
android {
    defaultConfig {
        ndk {
            abiFilters 'armeabi-v7a', 'arm64-v8a', 'x86', 'x86_64'
        }
    }
}
```

#### Insufficient Data Errors

Many analysis methods require minimum data points:

- Basic statistics: at least 1 data point
- Trend analysis: at least 3 data points
- Correlation analysis: at least 3 matched pairs
- Cycle analysis: at least 20 data points
- Cluster analysis: at least 5 data points

Always check data volumes before calling analysis methods and provide appropriate fallbacks or messages when data is insufficient.

