Sleep Pattern Analyzer

Analyzes sleep data from Apple Health, Fitbit, Oura Ring, or manual logs to identify patterns, correlations, and improvement strategies. Processes your sleep duration, bedtime consistency, wake patterns, and optional lifestyle factors (caffeine, exercise, screen time) to find what actually affects your sleep quality — backed by your own data, not generic advice.

Supported Platforms & Integrations

Platform	Integration Type	Features
Apple Health	XML export import	Sleep stages, heart rate, respiratory rate, movement
Fitbit	JSON/CSV export import	Sleep score, stages (light/deep/REM), SpO2 data
Oura Ring	JSON export import	Sleep score, HRV, temperature deviation, readiness
Garmin Connect	CSV/FIT export import	Sleep stages, body battery, stress tracking
Samsung Health	CSV export import	Sleep duration, stages, blood oxygen
Manual Sleep Log	YAML/CSV entry	Bedtime, wake time, subjective quality, notes

When to Use

• Identifying sleep disruptors: Correlate poor sleep nights with caffeine timing, screen use, exercise, or meal timing from the past 30+ days
• Bedtime consistency analysis: Discover how much your irregular schedule affects sleep quality with statistical evidence
• Seasonal pattern detection: Analyze 3-12 months of data to find seasonal shifts in your sleep architecture
• Sleep improvement tracking: Compare your sleep metrics before and after lifestyle changes to measure real impact
• Doctor visit preparation: Generate a clinical-quality sleep summary with charts for your physician or sleep specialist
• Jet lag recovery planning: Analyze your circadian tendencies to build an optimal adjustment schedule for travel

Alternatives to Consider

• Sleep specialist consultation: If you suspect a sleep disorder (apnea, narcolepsy, restless legs) — this tool identifies patterns but cannot diagnose
• CBT-I therapy apps (Sleepio, Insomnia Coach): If you have chronic insomnia, evidence-based therapy is more effective than data analysis
• Polysomnography (sleep study): If your wearable data shows concerning patterns like frequent waking or low SpO2

Quick Start

Copy
skill: sleep-pattern-analyzer
config:
  data_source: apple-health
  date_range: "2025-01-01 to 2025-03-15"
  analysis_type: comprehensive  # quick | comprehensive | comparison
  lifestyle_factors: true
input:
  sleep_data: export.xml
  lifestyle_log: lifestyle.csv  # optional

Example Input:

Source: Apple Health export (74 nights)
Date range: January 1 - March 15, 2025
Optional lifestyle log:
  Date, Caffeine_Last, Exercise_Min, Screen_Off, Alcohol, Stress_1to5
  2025-01-01, 14:00, 30, 22:30, 0, 2
  2025-01-02, 16:00, 0, 23:45, 2, 4
  ...

Example Output:

SLEEP PATTERN ANALYSIS — 74 Nights
====================================

OVERVIEW:
  Avg Duration:    6h 47m  (Target: 7-9h)  [Below Target]
  Avg Bedtime:     11:42 PM  ± 52 min variance
  Avg Wake Time:   6:29 AM   ± 38 min variance
  Sleep Efficiency: 87%  (Good: >85%)
  Avg Sleep Score:  71/100

STAGE BREAKDOWN (avg per night):
  Light Sleep:  3h 12m  (47%)  — Normal
  Deep Sleep:   1h 04m  (16%)  — Slightly Low
  REM Sleep:    1h 22m  (20%)  — Normal
  Awake:        1h 09m  (17%)  — Slightly High

TOP CORRELATIONS FOUND:
1. Caffeine after 2 PM → -18% sleep quality (p=0.003)
   Nights with late caffeine: avg 5h 52m vs 7h 11m
2. Exercise days → +12% deep sleep (p=0.01)
   30+ min exercise: 1h 18m deep vs 0h 52m no exercise
3. Screen off before 10 PM → +23 min total sleep (p=0.02)
4. Weekend bedtime shift → 1h 14m later avg (social jet lag)
5. Alcohol → -31% REM sleep (p=0.001)

WEEKLY PATTERN:
  Best nights:  Tuesday, Wednesday (avg score: 78)
  Worst nights: Friday, Saturday (avg score: 61)
  Pattern: Weekend social jet lag of 1h+ detected

RECOMMENDATIONS:
1. Move caffeine cutoff to 1 PM (your data shows 2 PM is too late)
2. Maintain weekday bedtime on weekends (±30 min max)
3. Continue exercise routine — clear deep sleep benefit
4. Screen curfew at 10 PM shows measurable improvement

Advanced Configuration

Data Source Configurations

Copy
# Apple Health specific
apple_health:
  include_heart_rate: true
  include_respiratory: true
  include_noise_level: true  # Apple Watch environmental audio

# Oura Ring specific
oura:
  include_hrv: true
  include_temperature: true
  include_readiness: true

Parameters Reference

Parameter	Type	Default	Description
data_source	string	required	apple-health, fitbit, oura, garmin, samsung, manual
date_range	string	"last 30 days"	Analysis date range
analysis_type	string	comprehensive	quick (7-day), comprehensive (30+), comparison
lifestyle_factors	bool	false	Include lifestyle correlation analysis
target_duration	string	"7-9h"	Your target sleep duration range
target_bedtime	string	null	Your target bedtime for consistency scoring
chronotype	string	auto-detect	morning-lark, night-owl, intermediate, auto-detect
correlation_threshold	number	0.05	P-value threshold for significant correlations
compare_periods	array	null	Two date ranges for before/after comparison
include_weekday_weekend	bool	true	Separate weekday vs weekend analysis
generate_doctor_report	bool	false	Generate clinical-format sleep summary
sensitivity	string	normal	normal, high (detects subtle patterns with more data)

Core Concepts

Concept	Description
Sleep Efficiency	Percentage of time in bed actually spent sleeping — above 85% is good, below 75% is concerning
Sleep Architecture	The distribution across light, deep, and REM stages — each serves different restorative functions
Social Jet Lag	The difference between your weekday and weekend sleep timing — a major disruptor of circadian rhythm
Correlation Analysis	Statistical testing to find which lifestyle factors genuinely affect your sleep vs coincidence
Circadian Tendency	Your natural chronotype (morning/evening preference) detected from your free-day sleep timing

Analysis Pipeline:

  Sleep Data Export ──> Parser ──> Normalize ──> Statistical
  (XML/JSON/CSV)        |         & Clean       Analysis
                        v              |              |
                   ┌──────────┐        v              v
                   │ Lifestyle│   Stage Timing   Correlation
                   │ Factor   │   Analysis       Engine
                   │ Import   │        |              |
                   └────┬─────┘        v              v
                        |        ┌────────────────────────┐
                        └───────>│  Pattern Detection     │
                                 │  + Recommendations     │
                                 │  + Trend Visualization │
                                 └────────────────────────┘

Workflow Examples

Scenario 1: New Parent Sleep Recovery

Input: 90 nights of Fitbit data, lifestyle log with baby wake events, comparison: pre-baby vs post-baby Process: Segment analysis by wake event frequency, identify recovery patterns, deep sleep trend analysis Output: Deep sleep down 40%, but improving 2% per week. Best recovery nights correlate with partner sharing nighttime duties. Nap timing recommendations provided.

Scenario 2: Shift Worker Optimization

Input: 60 days of Garmin data, rotating 3-shift schedule logged, blackout curtain install date noted Process: Compare sleep quality across day/evening/night shifts, measure blackout curtain impact Output: Night shift sleep 2.1 hours shorter on average. Blackout curtains improved day-sleep duration by 47 minutes. Recommend specific pre-shift nap timing.

Scenario 3: Insomnia Pattern Investigation

Input: 6 months of Oura Ring data plus detailed lifestyle log (meals, stress, exercise, caffeine) Process: Deep correlation analysis with high sensitivity, weekly cycle detection, HRV trend mapping Output: Strong correlation between high-stress days (4-5/5) and sleep onset latency (+35 min). Evening exercise after 8 PM correlates with delayed sleep onset. Doctor report generated.

Best Practices

1. Collect at least 30 nights: Statistical patterns need a minimum sample size — 7 days shows trends but 30+ enables reliable correlation analysis
2. Log lifestyle factors consistently: Correlation analysis is only as good as your lifestyle data — log caffeine, exercise, screens, and stress daily even if briefly
3. Separate weekdays and weekends: Mixing them obscures your social jet lag pattern, which is often the single biggest sleep quality factor
4. Use comparison mode for changes: When you change a habit (new mattress, caffeine cutoff, meditation), use comparison mode with clear before/after date ranges
5. Share the doctor report: If seeking medical help, the generated clinical summary gives your physician objective data instead of subjective complaints

Common Issues

Issue: Apple Health export is very large and slow to parse Cause: Apple Health XML exports contain all health data, not just sleep — years of data can be gigabytes Fix: Use the date_range parameter to limit analysis scope. The parser filters early and only loads sleep-related records within your specified range.

Issue: Sleep stages missing or inconsistent Cause: Wrist-based wearables estimate stages differently and may have gaps from removal or low battery Fix: The analyzer gracefully handles missing stage data by focusing on total duration and timing metrics. For stage-specific analysis, ensure at least 80% of nights have complete stage data.

Issue: Lifestyle correlations show unexpected results Cause: Confounding variables — exercise days may also be low-stress days, making it look like exercise helps more than it does Fix: The tool uses partial correlation analysis to control for confounders when your dataset has 60+ nights. With fewer nights, correlations are flagged as preliminary.

Privacy & Data Handling

All sleep data analysis runs entirely on your local machine. No health data, sleep metrics, heart rate data, lifestyle logs, or personal health information is transmitted to any external service. Apple Health XML, Fitbit JSON, and Oura exports are read from your local filesystem and processed in memory. No data is cached or stored between sessions. The doctor report is generated locally as a PDF/markdown file on your machine. This tool provides informational analysis only and is not a medical device or diagnostic tool.