/** * v1.15.12 A2 — resting-pulse estimation. * * Apple Health maps two distinct signals onto two distinct measurement * types: * - `HKQuantityTypeIdentifierHeartRate` → `PULSE` (every HR * sample, including workout / activity HR — intentionally high) * - `HKQuantityTypeIdentifierRestingHeartRate` → `RESTING_HEART_RATE` * (one clean daily resting figure) * * Up to v1.15.11 every surface that applied a RESTING pulse target (the * "Resting pulse" tile + its consistency strip, the pulse in-target %, * the dashboard resting classification) scored the raw `PULSE` series * against a resting band. For an Apple-Health user a single workout * emits ~500 high samples, so the resting-target evaluation read ~32 % * "over target" even though the user's clean `RESTING_HEART_RATE` * averages a healthy ~72 bpm. That is wrong: workout HR is expected-high, * not a resting excursion. * * The fix: judge a RESTING band against a RESTING series. * * 1. **Prefer `RESTING_HEART_RATE`** on every day that has one (Apple * already separated the clean signal for us). * 2. **Fallback proxy from `PULSE`** on the days that have no * `RESTING_HEART_RATE` (manual-only users, older imports, and the * recent days of an account whose derived rows only reach as far * as the retention fold has run): take a robust * low-percentile of each calendar day's PULSE samples — the resting * heart rate is the floor of the day, not its average, so the daily * 20th percentile estimates resting while excluding the workout * burst that sits in the upper tail. A single high-density workout * cannot drag the estimate up because it lives above the 20th * percentile of the day. * * The raw `PULSE` series, where it is merely charted as "heart rate", * must NOT be judged against the resting band — callers chart it with a * contextual band or no resting overlay. * * Pure & deterministic — unit-tested in `__tests__/resting-pulse.test.ts`. */ import { percentile } from "@/lib/insights/strain-score"; import { toBerlinDayKey } from "@/lib/tz/resolver"; /** A timestamped heart-rate sample. */ export interface PulseSample { measuredAt: Date; value: number; } /** * The percentile of each day's PULSE samples used as that day's resting * estimate. The 20th percentile sits comfortably in the day's low band * (above the rare sleeping-bradycardia outlier, below the bulk of waking * + workout HR), so it tracks resting HR without being pulled up by a * dense workout burst. */ export const RESTING_PROXY_DAILY_PERCENTILE = 20; /** * Minimum PULSE samples a day needs before it can contribute a resting * proxy. A workout-only or single-sample day (n = 1) would otherwise emit * that one sample verbatim — a workout-level value masquerading as * "resting". Below this floor the day is skipped rather than poisoning the * proxy series with a high reading; a real resting day has many ambient * samples and clears it easily. */ export const RESTING_PROXY_MIN_DAILY_SAMPLES = 3; /** * Collapse raw `PULSE` samples into a per-Berlin-day resting-proxy * series: one `{ measuredAt, value }` per day where `value` is the day's * low-percentile PULSE. The `measuredAt` anchors on the day's first * sample so downstream day-bucketing keys it back to the same day. * * Exported for direct testing; production callers use * `resolveRestingPulseSeries`. */ export function deriveRestingProxyFromPulse( pulseSamples: ReadonlyArray, /** * Day-key function used to bucket samples. Defaults to Berlin-day so * direct callers / tests stay zero-config; the targets route passes * its own `userDayKey(d, userTz)` so the proxy buckets align with the * route's consistency-strip day buckets for non-Berlin users. */ dayKeyOf: (d: Date) => string = toBerlinDayKey, ): PulseSample[] { if (pulseSamples.length === 0) return []; const byDay = new Map(); for (const s of pulseSamples) { const key = dayKeyOf(s.measuredAt); const bucket = byDay.get(key); if (bucket) { bucket.values.push(s.value); if (s.measuredAt < bucket.firstAt) bucket.firstAt = s.measuredAt; } else { byDay.set(key, { firstAt: s.measuredAt, values: [s.value] }); } } const out: PulseSample[] = []; for (const { firstAt, values } of byDay.values()) { // Skip degenerate days: too few samples to distinguish a resting floor // from a lone workout reading. Emitting the verbatim value would leak a // workout-level number into the "resting" series. if (values.length < RESTING_PROXY_MIN_DAILY_SAMPLES) continue; out.push({ measuredAt: firstAt, value: Math.round(percentile(values, RESTING_PROXY_DAILY_PERCENTILE)), }); } out.sort((a, b) => a.measuredAt.getTime() - b.measuredAt.getTime()); return out; } /** * Resolve the resting-pulse series a resting-target surface should * score. Merges PER DAY: a day that has a `RESTING_HEART_RATE` row is * represented by that row; a day that has none falls back to the * low-percentile PULSE proxy. * * v1.30.16 made the dense-intraday retention fold mint derived * `RESTING_HEART_RATE` rows (source `COMPUTED`) for the days it folds. * A proxy account therefore now carries derived rows for OLD folded * days and nothing but raw `PULSE` for RECENT not-yet-folded days. The * previous all-or-nothing shape returned the resting branch the moment * a single resting row existed and never consulted the proxy again, so * the visible series stopped dead at the fold horizon. Merging per day * keeps the clean signal where it exists and carries the series * forward across the days that only have the proxy. * * `which` reports how to LABEL the series, and it is deliberately * conservative: `"resting"` only when EVERY point came from a real * resting row, `"proxy"` as soon as one point is proxy-derived. The two * error directions are not symmetric — calling a partly-estimated * series "resting heart rate" is a false statement about the estimated * days, whereas calling a partly-native series "estimated from heart * rate" merely hedges. A labelling signal should hedge, never lie. */ export function resolveRestingPulseSeries(input: { restingSamples: ReadonlyArray; pulseSamples: ReadonlyArray; /** Optional day-key for the proxy buckets (defaults to Berlin-day). */ dayKeyOf?: (d: Date) => string; }): { series: PulseSample[]; which: "resting" | "proxy" | "none" } { const dayKeyOf = input.dayKeyOf ?? toBerlinDayKey; const byTime = (a: PulseSample, b: PulseSample) => a.measuredAt.getTime() - b.measuredAt.getTime(); const resting = [...input.restingSamples].sort(byTime); // Days already covered by a real resting row — the proxy must not // second-guess them. const restingDays = new Set(resting.map((s) => dayKeyOf(s.measuredAt))); const proxy = deriveRestingProxyFromPulse( input.pulseSamples, dayKeyOf, ).filter((p) => !restingDays.has(dayKeyOf(p.measuredAt))); if (resting.length === 0) { return proxy.length > 0 ? { series: proxy, which: "proxy" } : { series: [], which: "none" }; } if (proxy.length === 0) return { series: resting, which: "resting" }; return { series: [...resting, ...proxy].sort(byTime), which: "proxy" }; }