Docs
How Causal works.
Causal takes check-ins and Apple Health records, turns them into simple numbers, and looks for patterns. That is the whole idea.
It is not a doctor, not a lab, and not proof of medical causality. It is a way to ask better personal questions: what tends to happen after caffeine, alcohol, stress, workouts, sleep, and mood changes?
Getting Started
The app has three jobs: collect low-friction check-ins, read the Health data you allow, and show the comparisons it can justify.
- Grant read-only Apple Health access if you want sleep, HRV, resting heart rate, and workout snapshots.
- Pick factors in Pulse. Mood is always on. Optional factors include caffeine, alcohol, sugar, workouts, stress, and socializing.
- Set the check-in limit and waking-hours window. Two check-ins per day is the default; four is the max.
- Answer prompts when they appear, or add manual check-ins.
- Use Discovery to see snapshots, trends, and causal lever results.
Check-ins
A check-in answer becomes a number. The model cannot use prose; it needs values.
| Answer | Value used |
|---|---|
| Mood | Excellent 4, Good 3, Meh 2, Awful 1 |
| Caffeine, alcohol, sugar, socializing | Within 3h 1.0, 3-6h 0.6, 6-12h 0.3, yesterday or earlier 0.0 |
| Stress | Low 0.0, Moderate 0.5, High 1.0 |
| Workout prompt | None 0.0, <20m 0.25, 20-45m 0.55, 45+m 1.0 |
For recency answers, Causal estimates when the event happened: within 3 hours becomes 1.5 hours before the prompt, 3-6 hours becomes 4.5 hours before, and 6-12 hours becomes 9 hours before.
The backend builds an hourly table. For each treatment it creates exposure windows for the last 1, 3, 6, and 12 hours, plus a morning window from 5:00 AM to noon.
Health Snapshots
Snapshots are local summaries of available records. If there is no record, there is no snapshot.
| Metric | Source | Display | Benchmark | Percentile |
|---|---|---|---|---|
| Sleep | Apple Health sleepAnalysis asleep stages | Hours, one decimal | 7+ hours from AASM/SRS and CDC adult guidance | Personal after 5 prior daily buckets; population when age is available |
| Resting heart rate | Apple Health restingHeartRate | Bpm, whole number | AHA common adult range: 60-100 bpm | Lower is treated as better; population when age is available |
| HRV | Apple Health heartRateVariabilitySDNN | Ms, whole number | No public benchmark shown | Personal only; higher values rank higher |
| Workout duration | Apple Health workouts, plus prompt answers when used by the model | Hours, one decimal | No public duration benchmark | Longer logged duration ranks higher |
Personal baseline
Baselines need at least 5 prior daily buckets for the same metric. If a day has multiple samples, Causal uses that day's median. It compares the latest value with the mean of the latest 14 prior buckets.
Delta means latest value - baseline mean. For resting heart rate, lower is treated as better. For sleep and HRV, higher ranks higher, but longer sleep is not automatically called better sleep.
Percentiles
Personal percentile
Personal percentiles compare today with your own prior daily buckets. They stay hidden until there are at least 5 prior buckets.
Formula: ((betterCount + 0.5 * equalCount) / priorCount) * 100. Ties get half credit. Results are rounded and capped from P1 to P99.
- Resting heart rate: lower values rank better.
- Sleep and HRV: higher values rank higher.
- A personal percentile is not a population percentile.
Population percentile
Population benchmarks use age and sex assigned at birth when available. If sex is unavailable or unmapped, Causal uses an all-people cohort.
The stored NHANES cut points are P5, P10, P25, P50, P75, P90, and P95. Causal interpolates between them. Values below P5 show as P5; values above P95 show as P95.
- Sleep: CDC NHANES Aug 2021-Aug 2023 SLQ_L/DEMO_L.
- Resting heart rate: CDC NHANES 2017-2018 BPX_J/DEMO_J.
- HRV has no population percentile yet because public reference tables are too protocol-dependent.
Causal Levers
Causal levers come from the backend. It merges check-ins and biometrics into an hourly table, then tests treatment-outcome pairs with ordinary least squares regression.
- Treatments: caffeine, alcohol, sugar, stress, socializing, and workouts.
- Outcomes: sleep, HRV, resting heart rate, and mood.
- Each model needs at least 3 overlapping hourly rows and real variation in the exposure.
- For each pair, Causal tries exposure windows and picks the feature with the largest abs(coefficient) * sqrt(sampleSize).
- The coefficient is the estimated outcome change per one unit of exposure, in the outcome's unit.
Community sensitivity
The lever percentile uses absolute coefficient size. Causal compares your coefficient with other stored user coefficients for the same treatment and outcome, excluding you. Early seed coefficients keep the cohort from being empty.
Formula: mean(abs(cohortCoefficient) < abs(userCoefficient)) * 100, capped from 1 to 99. "Higher impact than 88% of users" means your absolute coefficient is larger than 88% of comparison coefficients for that same pair.
The sign still matters. A positive resting-heart-rate coefficient is usually bad. A negative sleep or HRV coefficient is usually bad.
Body Metrics
Body Metrics currently cover manual Weight and Body Fat entries. Weight is stored and displayed in pounds. Body fat is displayed as a percent.
- Trend lines sort entries by timestamp and draw the stored values.
- Change is latest value minus first value. Differences under 0.05 show as no change.
- Mood insights need at least 4 body metric entries and 8 matched mood samples.
- Mood check-ins match to the nearest body metric entry within 3 days.
- Values split around the median; Causal compares average mood on the 1-4 scale across the two sides.
- The insight stays hidden unless each side has at least 3 samples and the mood gap is at least 0.25.
Privacy
Causal reads Apple Health only after permission. Current HealthKit access is read-only for sleep analysis, resting heart rate, HRV, and workouts.
Benchmark profile fields choose comparison cohorts. Age picks an age band. Sex assigned at birth picks female, male, or all-people rows. Height and weight support profile completeness and body metric workflows.
Causal does not use HealthKit data, benchmark profile fields, biometrics, or check-in answers for ads, resale, or unrelated profiling. Delete controls live in Pulse under Privacy & Data. The Privacy Policy has retention and service-provider details.