mirror of
https://github.com/hanzoskill/oura-analytics.git
synced 2026-10-30 21:10:57 +00:00
369 lines
13 KiB
Python
369 lines
13 KiB
Python
#!/usr/bin/env python3
|
|
"""
|
|
Oura Baseline & Comparison Analysis
|
|
|
|
Calculate baselines from historical data and compare current metrics.
|
|
Provides statistical significance (z-score, percentiles) and actionable insights.
|
|
"""
|
|
|
|
import argparse
|
|
import sys
|
|
import json
|
|
from datetime import datetime, timedelta
|
|
from pathlib import Path
|
|
from typing import Dict, List, Optional, Tuple
|
|
from dataclasses import dataclass
|
|
import statistics
|
|
|
|
# Add scripts directory to path for imports
|
|
sys.path.insert(0, str(Path(__file__).resolve().parent))
|
|
|
|
from oura_api import OuraClient
|
|
from schema import NightRecord
|
|
|
|
|
|
@dataclass
|
|
class BaselineMetrics:
|
|
"""Statistical baseline for a metric."""
|
|
mean: float
|
|
median: float
|
|
std_dev: float
|
|
min: float
|
|
max: float
|
|
p25: float # 25th percentile
|
|
p75: float # 75th percentile
|
|
sample_size: int
|
|
|
|
def z_score(self, value: float) -> float:
|
|
"""Calculate z-score (standard deviations from mean)."""
|
|
if self.std_dev == 0:
|
|
return 0.0
|
|
return (value - self.mean) / self.std_dev
|
|
|
|
def percentile_rank(self, value: float, samples: List[float]) -> float:
|
|
"""Calculate percentile rank of value in distribution."""
|
|
if not samples:
|
|
return 50.0
|
|
below = sum(1 for s in samples if s < value)
|
|
return (below / len(samples)) * 100
|
|
|
|
def interpret_delta(self, value: float) -> Tuple[str, str, str]:
|
|
"""
|
|
Interpret delta from baseline.
|
|
Returns: (emoji, label, severity)
|
|
"""
|
|
z = self.z_score(value)
|
|
|
|
if z >= 1.5:
|
|
return "🔥", "Well above baseline", "excellent"
|
|
elif z >= 0.5:
|
|
return "↗️", "Above baseline", "good"
|
|
elif z >= -0.5:
|
|
return "➡️", "Within baseline", "normal"
|
|
elif z >= -1.5:
|
|
return "↘️", "Below baseline", "attention"
|
|
else:
|
|
return "⚠️", "Well below baseline", "concern"
|
|
|
|
|
|
@dataclass
|
|
class Baseline:
|
|
"""Complete baseline analysis."""
|
|
sleep_score: BaselineMetrics
|
|
readiness: BaselineMetrics
|
|
sleep_hours: BaselineMetrics
|
|
efficiency: BaselineMetrics
|
|
hrv: Optional[BaselineMetrics]
|
|
rhr: Optional[BaselineMetrics]
|
|
period_days: int
|
|
end_date: str
|
|
|
|
|
|
def calculate_baseline_metrics(values: List[float]) -> Optional[BaselineMetrics]:
|
|
"""Calculate statistical baseline from a list of values."""
|
|
if not values or len(values) < 3:
|
|
return None
|
|
|
|
sorted_values = sorted(values)
|
|
|
|
try:
|
|
return BaselineMetrics(
|
|
mean=round(statistics.mean(values), 1),
|
|
median=round(statistics.median(values), 1),
|
|
std_dev=round(statistics.stdev(values), 1) if len(values) > 1 else 0,
|
|
min=round(min(values), 1),
|
|
max=round(max(values), 1),
|
|
p25=round(sorted_values[len(values) // 4], 1),
|
|
p75=round(sorted_values[3 * len(values) // 4], 1),
|
|
sample_size=len(values)
|
|
)
|
|
except Exception:
|
|
return None
|
|
|
|
|
|
def calculate_sleep_score(sleep_data: dict) -> float:
|
|
"""Calculate sleep score from sleep data (matches weekly_report.py logic)."""
|
|
efficiency = sleep_data.get("efficiency", 0)
|
|
duration_hours = sleep_data.get("total_sleep_duration", 0) / 3600 if sleep_data.get("total_sleep_duration") else 0
|
|
|
|
eff_score = min(efficiency, 100)
|
|
dur_score = min(duration_hours / 8 * 100, 100)
|
|
return round((eff_score * 0.6) + (dur_score * 0.4), 1)
|
|
|
|
|
|
def build_baseline(sleep_data: List[dict], readiness_data: List[dict], period_days: int) -> Baseline:
|
|
"""Build baseline from historical data."""
|
|
# Build readiness lookup
|
|
readiness_by_day = {r.get("day"): r for r in readiness_data}
|
|
|
|
# Extract metrics
|
|
sleep_scores = []
|
|
readiness_scores = []
|
|
sleep_hours = []
|
|
efficiencies = []
|
|
hrv_values = []
|
|
rhr_values = []
|
|
|
|
for sleep in sleep_data:
|
|
day = sleep.get("day")
|
|
|
|
# Sleep score
|
|
score = calculate_sleep_score(sleep)
|
|
if score > 0:
|
|
sleep_scores.append(score)
|
|
|
|
# Sleep hours
|
|
duration_sec = sleep.get("total_sleep_duration", 0)
|
|
if duration_sec:
|
|
sleep_hours.append(round(duration_sec / 3600, 1))
|
|
|
|
# Efficiency
|
|
eff = sleep.get("efficiency")
|
|
if eff:
|
|
efficiencies.append(eff)
|
|
|
|
# HRV
|
|
hrv = sleep.get("average_hrv")
|
|
if hrv:
|
|
hrv_values.append(hrv)
|
|
|
|
# RHR
|
|
rhr = sleep.get("lowest_heart_rate")
|
|
if rhr:
|
|
rhr_values.append(rhr)
|
|
|
|
# Readiness
|
|
r = readiness_by_day.get(day)
|
|
if r and r.get("score"):
|
|
readiness_scores.append(r["score"])
|
|
|
|
return Baseline(
|
|
sleep_score=calculate_baseline_metrics(sleep_scores),
|
|
readiness=calculate_baseline_metrics(readiness_scores),
|
|
sleep_hours=calculate_baseline_metrics(sleep_hours),
|
|
efficiency=calculate_baseline_metrics(efficiencies),
|
|
hrv=calculate_baseline_metrics(hrv_values) if hrv_values else None,
|
|
rhr=calculate_baseline_metrics(rhr_values) if rhr_values else None,
|
|
period_days=period_days,
|
|
end_date=sleep_data[-1].get("day") if sleep_data else ""
|
|
)
|
|
|
|
|
|
def compare_to_baseline(current_data: dict, baseline: Baseline, metric_name: str, current_value: float, baseline_metric: BaselineMetrics) -> Dict:
|
|
"""Compare current value to baseline and generate insight."""
|
|
delta = current_value - baseline_metric.mean
|
|
z_score = baseline_metric.z_score(current_value)
|
|
emoji, label, severity = baseline_metric.interpret_delta(current_value)
|
|
|
|
return {
|
|
"metric": metric_name,
|
|
"current": round(current_value, 1),
|
|
"baseline_mean": baseline_metric.mean,
|
|
"baseline_range": f"{baseline_metric.p25}-{baseline_metric.p75}",
|
|
"delta": round(delta, 1),
|
|
"z_score": round(z_score, 2),
|
|
"emoji": emoji,
|
|
"label": label,
|
|
"severity": severity
|
|
}
|
|
|
|
|
|
def format_baseline_report(baseline: Baseline) -> str:
|
|
"""Format baseline report for console output."""
|
|
lines = []
|
|
lines.append(f"\n📊 Baseline Analysis ({baseline.period_days}-day period)")
|
|
lines.append(f" Period ending: {baseline.end_date}")
|
|
lines.append("")
|
|
|
|
metrics = [
|
|
("Sleep Score", baseline.sleep_score, "/100"),
|
|
("Readiness", baseline.readiness, "/100"),
|
|
("Sleep Duration", baseline.sleep_hours, "h"),
|
|
("Efficiency", baseline.efficiency, "%"),
|
|
]
|
|
|
|
if baseline.hrv:
|
|
metrics.append(("HRV", baseline.hrv, "ms"))
|
|
if baseline.rhr:
|
|
metrics.append(("RHR", baseline.rhr, "bpm"))
|
|
|
|
for name, metric, unit in metrics:
|
|
if metric:
|
|
lines.append(f" {name}:")
|
|
lines.append(f" Mean: {metric.mean}{unit} (±{metric.std_dev})")
|
|
lines.append(f" Range: {metric.min}-{metric.max}{unit}")
|
|
lines.append(f" P25-P75: {metric.p25}-{metric.p75}{unit}")
|
|
lines.append(f" Samples: {metric.sample_size}")
|
|
lines.append("")
|
|
|
|
return "\n".join(lines)
|
|
|
|
|
|
def format_comparison_report(comparisons: List[Dict], period_label: str) -> str:
|
|
"""Format comparison report for console output."""
|
|
lines = []
|
|
lines.append(f"\n📈 Current vs Baseline ({period_label})")
|
|
lines.append("")
|
|
|
|
for comp in comparisons:
|
|
emoji = comp["emoji"]
|
|
metric = comp["metric"]
|
|
current = comp["current"]
|
|
delta = comp["delta"]
|
|
z = comp["z_score"]
|
|
label = comp["label"]
|
|
|
|
delta_str = f"+{delta}" if delta > 0 else str(delta)
|
|
lines.append(f" {emoji} {metric}: {current} ({delta_str}, z={z})")
|
|
lines.append(f" {label}")
|
|
lines.append("")
|
|
|
|
# Summary
|
|
concerns = [c for c in comparisons if c["severity"] == "concern"]
|
|
if concerns:
|
|
lines.append("⚠️ Metrics needing attention:")
|
|
for c in concerns:
|
|
lines.append(f" • {c['metric']}: {c['label']}")
|
|
else:
|
|
lines.append("✅ All metrics within or above baseline range")
|
|
|
|
return "\n".join(lines)
|
|
|
|
|
|
def main():
|
|
parser = argparse.ArgumentParser(description="Oura Baseline & Comparison Analysis")
|
|
parser.add_argument("--baseline-days", type=int, default=30, help="Days for baseline calculation (default: 30)")
|
|
parser.add_argument("--current-days", type=int, default=7, help="Days for current period comparison (default: 7)")
|
|
parser.add_argument("--token", help="Oura API token")
|
|
parser.add_argument("--json", action="store_true", help="Output JSON format")
|
|
parser.add_argument("--baseline-only", action="store_true", help="Show baseline without comparison")
|
|
|
|
args = parser.parse_args()
|
|
|
|
try:
|
|
client = OuraClient(args.token)
|
|
|
|
# Fetch baseline period data
|
|
baseline_end = datetime.now()
|
|
baseline_start = baseline_end - timedelta(days=args.baseline_days)
|
|
|
|
baseline_sleep = client.get_sleep(
|
|
baseline_start.strftime("%Y-%m-%d"),
|
|
baseline_end.strftime("%Y-%m-%d")
|
|
)
|
|
baseline_readiness = client.get_readiness(
|
|
baseline_start.strftime("%Y-%m-%d"),
|
|
baseline_end.strftime("%Y-%m-%d")
|
|
)
|
|
|
|
# Calculate baseline
|
|
baseline = build_baseline(baseline_sleep, baseline_readiness, args.baseline_days)
|
|
|
|
if args.baseline_only:
|
|
if args.json:
|
|
print(json.dumps({
|
|
"baseline": {
|
|
"sleep_score": baseline.sleep_score.__dict__ if baseline.sleep_score else None,
|
|
"readiness": baseline.readiness.__dict__ if baseline.readiness else None,
|
|
"sleep_hours": baseline.sleep_hours.__dict__ if baseline.sleep_hours else None,
|
|
"efficiency": baseline.efficiency.__dict__ if baseline.efficiency else None,
|
|
"hrv": baseline.hrv.__dict__ if baseline.hrv else None,
|
|
"rhr": baseline.rhr.__dict__ if baseline.rhr else None,
|
|
"period_days": baseline.period_days,
|
|
"end_date": baseline.end_date
|
|
}
|
|
}, indent=2))
|
|
else:
|
|
print(format_baseline_report(baseline))
|
|
return
|
|
|
|
# Fetch current period data
|
|
current_end = datetime.now()
|
|
current_start = current_end - timedelta(days=args.current_days)
|
|
|
|
current_sleep = client.get_sleep(
|
|
current_start.strftime("%Y-%m-%d"),
|
|
current_end.strftime("%Y-%m-%d")
|
|
)
|
|
current_readiness = client.get_readiness(
|
|
current_start.strftime("%Y-%m-%d"),
|
|
current_end.strftime("%Y-%m-%d")
|
|
)
|
|
|
|
# Calculate current averages
|
|
readiness_by_day = {r.get("day"): r for r in current_readiness}
|
|
|
|
current_sleep_scores = [calculate_sleep_score(s) for s in current_sleep if calculate_sleep_score(s) > 0]
|
|
current_readiness_scores = [r.get("score") for r in current_readiness if r.get("score")]
|
|
current_sleep_hours = [s.get("total_sleep_duration", 0) / 3600 for s in current_sleep if s.get("total_sleep_duration")]
|
|
current_efficiencies = [s.get("efficiency") for s in current_sleep if s.get("efficiency")]
|
|
|
|
avg_sleep_score = statistics.mean(current_sleep_scores) if current_sleep_scores else 0
|
|
avg_readiness = statistics.mean(current_readiness_scores) if current_readiness_scores else 0
|
|
avg_sleep_hours = statistics.mean(current_sleep_hours) if current_sleep_hours else 0
|
|
avg_efficiency = statistics.mean(current_efficiencies) if current_efficiencies else 0
|
|
|
|
# Generate comparisons
|
|
comparisons = []
|
|
|
|
if baseline.sleep_score and avg_sleep_score:
|
|
comparisons.append(compare_to_baseline({}, baseline, "Sleep Score", avg_sleep_score, baseline.sleep_score))
|
|
|
|
if baseline.readiness and avg_readiness:
|
|
comparisons.append(compare_to_baseline({}, baseline, "Readiness", avg_readiness, baseline.readiness))
|
|
|
|
if baseline.sleep_hours and avg_sleep_hours:
|
|
comparisons.append(compare_to_baseline({}, baseline, "Sleep Duration", avg_sleep_hours, baseline.sleep_hours))
|
|
|
|
if baseline.efficiency and avg_efficiency:
|
|
comparisons.append(compare_to_baseline({}, baseline, "Efficiency", avg_efficiency, baseline.efficiency))
|
|
|
|
# Output
|
|
period_label = f"Last {args.current_days}d vs {args.baseline_days}d baseline"
|
|
|
|
if args.json:
|
|
print(json.dumps({
|
|
"baseline": {
|
|
"period_days": baseline.period_days,
|
|
"end_date": baseline.end_date
|
|
},
|
|
"current": {
|
|
"period_days": args.current_days,
|
|
"avg_sleep_score": round(avg_sleep_score, 1),
|
|
"avg_readiness": round(avg_readiness, 1),
|
|
"avg_sleep_hours": round(avg_sleep_hours, 1),
|
|
"avg_efficiency": round(avg_efficiency, 1)
|
|
},
|
|
"comparisons": comparisons
|
|
}, indent=2))
|
|
else:
|
|
print(format_comparison_report(comparisons, period_label))
|
|
|
|
except Exception as e:
|
|
print(f"Error: {e}", file=sys.stderr)
|
|
sys.exit(1)
|
|
|
|
|
|
if __name__ == "__main__":
|
|
main()
|