# Metric reference

Generated from the metric registry, which is the single source of truth shared by the tracking table, the API, the correlation engine and the AI tools. Registry version **2**, **59 metrics**.

`id` is the canonical field name. It is what you pass to any tool that takes a metric, and what appears as a key in stored day data.

## Core

Fields you fill in yourself, in the tracking table or by voice.

| id | Type | Unit | Analytical role | Description |
| --- | --- | --- | --- | --- |
| `date` | date | — | — | Calendar date of the entry |
| `wakeAt7am` | binary | — | behavior (habits) | Woke up by 7am (yes/no) |
| `reading30min` | binary | — | behavior (habits) | Read for at least 30 minutes (yes/no) |
| `takeVitamins` | binary | — | behavior (habits) | Took daily vitamins/supplements (yes/no) |
| `weight` | number | lbs | outcome (fitness) | Body weight in pounds (lbs) |
| `pushUps` | number | reps | outcome (fitness) | Number of push-ups completed |
| `sitUps` | number | reps | outcome (fitness) | Number of sit-ups completed |
| `oneMileRun` | time | MM:SS | outcome (fitness) | Time to run one mile (MM:SS format) |
| `stairsClimbed` | number | flights | outcome (fitness) | Number of floors/flights of stairs climbed |
| `workoutSession` | select | — | — | Type of workout or activity status for the day |
| `breakfast` | text | — | — | What was eaten for breakfast |
| `lunch` | text | — | — | What was eaten for lunch |
| `dinner` | text | — | — | What was eaten for dinner |
| `snacks` | text | — | — | Snacks eaten throughout the day |
| `healthyEating` | select | — | — | Self-assessment of overall eating quality for the day |

## WHOOP

Pulled from WHOOP on a schedule. Present only when the integration is connected.

| id | Type | Unit | Analytical role | Description |
| --- | --- | --- | --- | --- |
| `whoopRecovery` | number | % | outcome (whoop) | WHOOP Recovery score (0-100%). Green 67+, Yellow 34-66, Red <34. Indicates body readiness to perform. |
| `whoopHrv` | number | ms | outcome (whoop) | Heart rate variability in milliseconds (rmssd). Higher = better recovery and lower stress. |
| `whoopSleep` | number | % | outcome (whoop) | Sleep performance percentage. 100% = full sleep need met. |
| `whoopStrain` | number | — | both (whoop) | Daily strain score (0-21). Light 0-9, Moderate 10-13, Hard 14-17, All-out 18+. |
| `whoopRhr` | number | bpm | outcome (whoop) | Resting heart rate in bpm measured during sleep. Lower trending = improving cardiovascular fitness. |
| `whoopDeepSleep` | number | hours | outcome (whoop) | Hours of slow-wave (deep) sleep. Critical for physical recovery and muscle repair. |
| `whoopCalories` | number | kcal | outcome (whoop) | Total calories burned for the day including BMR and activity. |
| `whoopSleepEfficiency` | number | % | outcome (whoop) | Sleep efficiency - percentage of time in bed actually spent sleeping. >85% is good. |
| `whoopDisturbances` | number | — | outcome (whoop) | Number of sleep disturbances detected. Lower = better sleep quality. |
| `whoopSpo2` | number | % | outcome (whoop) | Blood oxygen saturation percentage. Normal is 95-100%. Drops can indicate illness. |
| `whoopRespRate` | number | breaths/min | outcome (whoop) | Respiratory rate during sleep (breaths/min). Elevated can indicate illness or stress. |
| `whoopRemSleep` | number | hours | outcome (whoop) | Hours of REM sleep. Critical for cognitive recovery, memory consolidation, and emotional processing. |
| `whoopLightSleep` | number | hours | outcome (whoop) | Hours of light sleep (stages 1-2). Transition sleep important for overall rest architecture. |
| `whoopSleepCycles` | number | — | outcome (whoop) | Number of complete sleep cycles (each ~90 min). 4-6 cycles is optimal for full restoration. |
| `whoopSkinTemp` | number | °C | outcome (whoop) | Skin temperature during sleep. Deviation above personal baseline often precedes illness by a day or two. |
| `whoopAvgHr` | number | bpm | outcome (whoop) | Average heart rate across the whole day, workouts included. Rising at constant strain suggests overreaching or illness. |
| `whoopMaxHr` | number | bpm | outcome (whoop) | Highest heart rate reached during the day, including efforts never logged as a workout. |
| `whoopTimeInBed` | number | hours | both (whoop) | Total hours spent in bed, asleep or not. Compare against sleep hours to see time lost to restlessness. |
| `whoopAwakeTime` | number | min | outcome (whoop) | Minutes spent awake between falling asleep and getting up. Under 20 is settled; over 40 suggests a disrupted night. |
| `whoopSleepConsistency` | number | % | behavior (whoop) | How closely bed and wake times matched the recent pattern. Circadian regularity predicts next-day recovery about as strongly as duration does. |
| `whoopSleepNeed` | number | hours | outcome (whoop) | WHOOP's calculated sleep requirement for the night: personal baseline plus what recent debt, strain, and naps add to it. |
| `whoopSleepDebt` | number | min | both (whoop) | Accumulated sleep shortfall carried into the night, in minutes of extra sleep owed. |
| `whoopBedtime` | time | — | — | Local clock time the wearer fell asleep (HH:MM, 24-hour). |
| `whoopWakeTime` | time | — | — | Local clock time the wearer woke (HH:MM, 24-hour). |
| `whoopNapTime` | number | min | behavior (whoop) | Total minutes napped during the day, excluded from night-sleep stage totals. |
| `whoopNapCount` | number | — | behavior (whoop) | Number of naps recorded during the day. |
| `whoopWeight` | number | lbs | outcome (whoop) | Body weight as recorded on the WHOOP profile, in pounds. Independent of the manually tracked weight column. |
| `whoopWorkouts` | list | — | — | Per-session workout detail: sport, start time, duration, strain, heart rate, calories, distance, and HR zone split. |
| `whoopWorkoutCount` | number | — | behavior (fitness) | Number of workouts recorded by WHOOP during the day. |
| `whoopWorkoutTime` | number | min | behavior (fitness) | Total minutes of recorded workout time across all sessions. |
| `whoopWorkoutDistance` | number | mi | behavior (fitness) | Total distance covered across recorded workouts, in miles. |
| `whoopCalibrating` | binary | — | — | Set while WHOOP is still establishing the wearer's baseline, which makes that day's recovery score provisional rather than measured. |
| `whoopSleepNoData` | number | min | — | Minutes of the night the strap recorded nothing (taken off, or a sensor dropout). Every sleep-stage total is understated by this much. |
| `whoopZone1` | number | min | behavior (fitness) | Minutes in HR Zone 1 (50-60% max HR). Recovery/warm-up zone. |
| `whoopZone2` | number | min | behavior (fitness) | Minutes in HR Zone 2 (60-70% max HR). Fat-burning/base aerobic zone. |
| `whoopZone3` | number | min | behavior (fitness) | Minutes in HR Zone 3 (70-80% max HR). Aerobic/tempo zone. |
| `whoopZone4` | number | min | behavior (fitness) | Minutes in HR Zone 4 (80-90% max HR). Threshold/anaerobic zone. |
| `whoopZone5` | number | min | behavior (fitness) | Minutes in HR Zone 5 (90-100% max HR). Max effort/VO2max zone. |

## AI-enriched nutrition

Derived from your logged meals by the nightly enrichment pass.

| id | Type | Unit | Analytical role | Description |
| --- | --- | --- | --- | --- |
| `mealQualityScore` | number | — | behavior (nutrition) | AI-estimated meal quality score for the day. |
| `mealProteinEst` | number | g | behavior (nutrition) | AI-estimated protein intake from logged meals. |
| `mealUltraProcessed` | binary | — | behavior (nutrition) | AI-detected ultra-processed eating day (yes/no). |

## Derived

Computed from other fields. These have no column in the table, but they are first-class metrics for analysis.

| id | Type | Unit | Analytical role | Description |
| --- | --- | --- | --- | --- |
| `_exercise` | binary | — | behavior (fitness) | Derived: any exercise happened (workout logged or reps done). |
| `_healthyEating` | number | — | behavior (nutrition) | Derived: manual eating-quality rating as ordinal 0/1/2. |
| `_sleepHours` | number | hours | behavior (whoop) | Derived: total sleep hours from WHOOP sleep stages. |

## Retrieval catalog

**47** metrics are analysable, meaning `get_daily_features` can return them as a numeric series with z-scores. This is the set it returns when you do not name specific metrics.

Your own custom columns are analysable too and are added to this set per account, so they cannot be listed here. Call `list_metrics` for the catalog as it applies to you.

| id | Label | Domain | Role | In discovery scan |
| --- | --- | --- | --- | --- |
| `wakeAt7am` | 7am wake | habits | behavior, binary | yes |
| `reading30min` | Reading | habits | behavior, binary | yes |
| `takeVitamins` | Vitamins | habits | behavior, binary | yes |
| `weight` | Weight | fitness | outcome | yes |
| `pushUps` | Push-ups | fitness | outcome | yes |
| `sitUps` | Sit-ups | fitness | outcome | no — logged too rarely for a daily correlation to mean anything |
| `oneMileRun` | Mile time | fitness | outcome | no — logged too rarely for a daily correlation to mean anything |
| `stairsClimbed` | Stairs climbed | fitness | outcome | no — logged too rarely for a daily correlation to mean anything |
| `whoopRecovery` | Recovery | whoop | outcome | yes |
| `whoopHrv` | HRV | whoop | outcome | yes |
| `whoopSleep` | Sleep performance | whoop | outcome | yes |
| `whoopStrain` | Strain | whoop | both | yes |
| `whoopRhr` | Resting HR | whoop | outcome | yes |
| `whoopDeepSleep` | Deep sleep | whoop | outcome | yes |
| `whoopCalories` | Calories burned | whoop | outcome | no — derived from heart rate, so it restates strain |
| `whoopSleepEfficiency` | Sleep efficiency | whoop | outcome | yes |
| `whoopDisturbances` | Sleep disturbances | whoop | outcome | yes |
| `whoopSpo2` | SpO2 | whoop | outcome | yes |
| `whoopRespRate` | Respiratory rate | whoop | outcome | yes |
| `whoopRemSleep` | REM sleep | whoop | outcome | yes |
| `whoopLightSleep` | Light sleep | whoop | outcome | no — largely total sleep minus deep and REM, which are both present |
| `whoopSleepCycles` | Sleep cycles | whoop | outcome | no — tracks total sleep duration almost exactly |
| `whoopSkinTemp` | Skin temperature | whoop | outcome | yes |
| `whoopAvgHr` | Average HR | whoop | outcome | no — moves with strain, which is present and better understood |
| `whoopMaxHr` | Peak HR | whoop | outcome | no — a workout artifact rather than a daily signal |
| `whoopTimeInBed` | Time in bed | whoop | both | no — sleep hours plus awake time, both present |
| `whoopAwakeTime` | Awake time | whoop | outcome | no — the inverse of sleep efficiency, which is present |
| `whoopSleepConsistency` | Sleep consistency | whoop | behavior | yes |
| `whoopSleepNeed` | Sleep need | whoop | outcome | no — computed by WHOOP from recent debt, strain and naps |
| `whoopSleepDebt` | Sleep debt | whoop | both | no — computed by WHOOP from the sleep history it would be correlated against |
| `whoopNapTime` | Nap time | whoop | behavior | yes |
| `whoopNapCount` | Nap count | whoop | behavior | yes |
| `whoopWeight` | Weight (WHOOP) | whoop | outcome | no — duplicates the manually tracked weight column |
| `whoopWorkoutCount` | Workout count | fitness | behavior | no — training load is represented by strain and training time |
| `whoopWorkoutTime` | Training time | fitness | behavior | yes |
| `whoopWorkoutDistance` | Workout distance | fitness | behavior | no — sport-dependent, so it is not comparable across days |
| `whoopZone1` | HR zone 1 minutes | fitness | behavior | no — strain and calories are computed from HR-zone minutes |
| `whoopZone2` | HR zone 2 minutes | fitness | behavior | no — strain and calories are computed from HR-zone minutes |
| `whoopZone3` | HR zone 3 minutes | fitness | behavior | no — strain and calories are computed from HR-zone minutes |
| `whoopZone4` | HR zone 4 minutes | fitness | behavior | no — strain and calories are computed from HR-zone minutes |
| `whoopZone5` | HR zone 5 minutes | fitness | behavior | no — strain and calories are computed from HR-zone minutes |
| `mealQualityScore` | Meal quality (AI) | nutrition | behavior | yes |
| `mealProteinEst` | Protein intake | nutrition | behavior | yes |
| `mealUltraProcessed` | Ultra-processed eating | nutrition | behavior, binary | yes |
| `_exercise` | Exercise | fitness | behavior, binary | yes |
| `_healthyEating` | Eating quality (manual) | nutrition | behavior | yes |
| `_sleepHours` | Sleep hours | whoop | behavior | yes |

## Discovery catalog

Of those, **27** form the discovery catalog — the pre-registered set the nightly correlation engine tests against each other.

It is narrower than the retrieval catalog on purpose. The engine controls its false discovery rate across the whole batch of candidate pairs, so every metric added to the scan makes the evidence bar higher for every other metric in it. Definitional relationships (calories burned against strain), near-duplicates, and metrics too sparse to estimate are excluded so the budget goes to hypotheses that could actually be wrong.

A metric outside this set is still fully retrievable — you can test it yourself with `get_daily_features`. It simply has no precomputed verdict in `get_correlations`.

## Aliases

Tools that take a metric name accept aliases as well as canonical ids, so `hrv` resolves to `whoopHrv` and `push-ups` to `pushUps`. Custom columns you create are matched fuzzily by label and description.

| Canonical id | Accepted aliases |
| --- | --- |
| `wakeAt7am` | `7am`, `wake`, `wake7am`, `wakeat7am` |
| `reading30min` | `read`, `reading`, `reading30min` |
| `takeVitamins` | `takevitamins`, `vitamin`, `vitamins` |
| `weight` | `weight` |
| `pushUps` | `push ups`, `push-ups`, `pushups` |
| `sitUps` | `sit ups`, `sit-ups`, `situps` |
| `oneMileRun` | `mile`, `miletime`, `onemilerun` |
| `stairsClimbed` | `stairs`, `stairsclimbed` |
| `workoutSession` | `exercise`, `workout`, `workoutsession` |
| `healthyEating` | `eating`, `healthy eating`, `healthyeating` |
| `whoopRecovery` | `recovery` |
| `whoopHrv` | `hrv` |
| `whoopSleep` | `sleepperf`, `sleepperformance` |
| `whoopStrain` | `strain` |
| `whoopRhr` | `restingheartrate`, `rhr` |
| `whoopDeepSleep` | `deepsleep` |
| `whoopCalories` | `calories` |
| `whoopSleepEfficiency` | `sleepefficiency` |
| `whoopDisturbances` | `disturbances` |
| `whoopSpo2` | `bloodoxygen`, `spo2` |
| `whoopRespRate` | `respiratoryrate`, `resprate` |
| `whoopRemSleep` | `rem`, `remsleep` |
| `whoopLightSleep` | `lightsleep` |
| `whoopSleepCycles` | `sleepcycles` |
| `whoopSkinTemp` | `skintemp`, `skintemperature`, `temperature` |
| `whoopAvgHr` | `averageheartrate`, `avghr` |
| `whoopMaxHr` | `maxheartrate`, `maxhr`, `peakhr` |
| `whoopTimeInBed` | `inbed`, `timeinbed` |
| `whoopAwakeTime` | `awaketime`, `timeawake`, `wakeaftersleeponset` |
| `whoopSleepConsistency` | `consistency`, `sleepconsistency` |
| `whoopSleepNeed` | `neededsleep`, `sleepneed` |
| `whoopSleepDebt` | `debt`, `sleepdebt` |
| `whoopBedtime` | `bedtime`, `sleepstart`, `wenttobed` |
| `whoopWakeTime` | `sleepend`, `waketime`, `wokeup` |
| `whoopNapTime` | `napminutes`, `naptime` |
| `whoopNapCount` | `napcount`, `naps` |
| `whoopWeight` | `strapweight`, `whoopweight` |
| `whoopWorkouts` | `whoopworkouts`, `workouts` |
| `whoopWorkoutCount` | `sessions`, `workoutcount` |
| `whoopWorkoutTime` | `trainingtime`, `workouttime` |
| `whoopWorkoutDistance` | `distance`, `workoutdistance` |
| `whoopCalibrating` | `calibrating`, `usercalibrating` |
| `whoopSleepNoData` | `nodata`, `sleepgap`, `sleepnodata` |
| `whoopZone1` | `zone1` |
| `whoopZone2` | `zone2` |
| `whoopZone3` | `zone3` |
| `whoopZone4` | `zone4` |
| `whoopZone5` | `zone5` |
| `mealQualityScore` | `mealquality` |
| `mealProteinEst` | `protein`, `proteinintake` |
| `mealUltraProcessed` | `ultraprocessed` |