protocols/260505_whoop_longitudinal_parse_plan.html

whoop longitudinal parse — план

2023-2026 wearable signal vs travel epochs. цель — ответить на OQ3 (что сработало в LA 2020), увидеть 2024-Q4 inflection в HRV terms, измерить residual cost после Strep 2025-07.

investigation: allostatic_signature resolves: H7 retrospective + OQ3 cost: 5 мин user + ~2h agent blocking: whoop CSV export

как получить доступ к данным whoop

whoop даёт экспорт — это политика с 2023 года. четыре пути от простого к сложному.

01in-app data export

recommended

самый простой путь. whoop ОБЯЗАН выдать данные по GDPR / California CCPA. ZIP с CSV файлами на email.

как сделать
  1. open whoop app
  2. Profile (top right) → Settings (⚙️)
  3. scroll to Account section
  4. tap Export My Data (или Download My Data в свежих версиях)
  5. выбираешь period: All Time
  6. через 5-30 минут на email приходит письмо с ZIP archive
  7. сохраняешь сюда: labs/04_wearables_and_performance/whoop/raw/whoop_export_2026-05-05.zip

ZIP содержит: physiological_cycles.csv · sleeps.csv · workouts.csv · journal_entries.csv

02developer API (OAuth2)

if #1 fails

whoop developer portal даёт public API с 2023. realtime pull, automation possible, но требует регистрации app.

как сделать
  1. зайти на https://developer.whoop.com
  2. create developer account (free)
  3. register new app — получить client_id + client_secret
  4. OAuth2 authorization flow: redirect_uri, scope (read:recovery, read:sleep, read:cycles, read:profile)
  5. exchange code for token, refresh token каждые 60 дней
  6. endpoints: /v1/cycle, /v1/recovery, /v1/activity/sleep, /v1/activity/workout
  7. pagination до 25 records/page, нужен loop по start_date

я могу написать pull-скрипт когда дашь client_id + secret. но #1 быстрее для одноразового анализа.

03third-party integrations

backup

несколько services уже сделали whoop API integration и экспортируют в google sheets / csv:

даёт меньше детализации чем native export. использовать только если #1+#2 заблокированы.

04browser DOM scrape

last resort

через app.whoop.com (если есть web-app) или mobile-mirror — DOM extraction. fragile, нарушает ToS, не рекомендую.

только если whoop откажется выдать данные in-app (что нарушит GDPR — но политики меняются).

важно: в whoop app → Profile → видна дата подключения устройства. найди её. это определяет scope: если whoop с 2020 — full retrospective включая LA anchor (золото для OQ3); если с 2023 — post-2023 only, OQ3 разрешается через proxy (Bali #1 vs #2 same-geography сравнение).

пошаговый план

step 00 · pre-check

узнать дату подключения whoop

ты blocking — 30 сек

open whoop app → Profile → видна или дата signup, или «member since». пиши мне год. это решает: full retrospective vs post-2023.

почему важно: LA 2020 anchor = единственный confirmed случай восстановления оси. whoop signal оттуда — direct evidence для OQ3. без него — proxy через Bali #1 vs #2.
step 01 · export

выгрузить raw csv

ты blocking — 5 мин

путь #01 (in-app export) → ZIP на email → положить в labs/04_wearables_and_performance/whoop/raw/

что я ожидаю получить
файлчто внутриcolumns key
physiological_cycles.csvdaily summarycycle_start, recovery_score, hrv_rmssd, resting_hr, day_strain, sleep_score
sleeps.csvкаждый сонstart, end, duration_min, efficiency, rem_min, sws_min, light_min, awake_min, hr_low, hr_avg
workouts.csvтренировкиstart, sport, hr_avg, hr_max, strain, kcal
journal_entries.csvtags по днямcycle_id, question, answer (caffeine, alcohol, stress, etc)
step 02 · epoch definition

сгенерировать travel_epochs.tsv

я могу делать СЕЙЧАС

не требует whoop. только state/ledgers/travel_history.yaml. epoch skeleton становится reusable input для любого wearable анализа (apple watch, oura, eight sleep).

алгоритм классификации 
for each row in travel_history.rows:
  compute tz_offset(city)
  compute tz_swing_from_prev = abs(tz_now - tz_prev)
  if days >= 14:
      type = ANCHOR
  elif tz_swing >= 4 and total_transit_days_in_window(14d) >= 3:
      type = TRANSIT
  else:
      type = NEUTRAL

# overlay layer
acute_events = [
  ('2013-XX-XX', 'cholecystectomy'),
  ('2020-03-XX', 'covid lockdown'),
  ('2022-02-XX', 'war / emigration'),
  ('2025-07-XX', 'strep + 14-city'),
]
for event in acute_events:
  mark days within ±14 with overlay=event

output: state/derived/travel_epochs.tsv с колонками epoch_id, start, end, type, location, tz_offset_h, tz_swing_from_prev, days, overlay_events

step 03 · per-epoch metrics

извлечь медианы по epoch

я (после step 01) после export

python скрипт tools/whoop_longitudinal_parse.py. могу написать СЕЙЧАС в форме скелета, ждущего CSV.

что считается
метрикаагрегациязачем
HRV (rmssd)median, IQR, slope (linreg в окне)autonomic baseline + drift внутри anchor
resting HRmedian, IQRsympathetic tone proxy
sleep efficiencymean %фрагментация, airway burden косвенно
REM %mean (из TST)HPA восстановление phase
SWS %meanтканевый repair
recovery scoremedian, % green dayscomposite
sleep durationmedian, stdcircadian regularity
sleep onsetmedian hour, stdrhythm stability
daily strainweekly meanload во время epoch
wear coverage%QA flag для epochs <60%
step 04 · cross-epoch compare

ответить на key questions

я после step 03
главные comparisons
сравнениечто разрешает
LA 2020 (341d) vs Bali #1 (2025-2026) vs Bali #2 (2023-2024 144d)OQ3 — geography vs duration vs mode
Bali #1 vs Bali #2 within same location, разные mode/контекстprocessing × duration в same-geography
14-day pre-Strep vs 30/60/90d post-StrepOQ2 — residual cost от 2025-07 trough
2024-Q3 vs 2024-Q4 (когда TZ swings +140%)видим ли inflection в HRV?
transit weeks vs anchor weeksper-trip HRV cost
journal alcohol-tagged nights (pre-2026) vs clean nightsretroactive H12 валидация (теперь дeкоммишена, но retrospective signal интересен)

статистика: median + IQR + non-parametric Mann-Whitney если нужна significance. но чаще magnitude визуально достаточно.

step 05 · output

три артефакта

я финал
artifactpath
метрик-таблицаlabs/04_wearables_and_performance/whoop/derived/whoop_epoch_metrics.tsv
charts (png)labs/04_wearables_and_performance/whoop/derived/charts/
narrative summarylabs/_summaries/2606xx_whoop_longitudinal_parse_v1.md
charts что будут
  • HRV baseline timeline 2020-2026 — main chart. epoch shading (anchor/transit/neutral), vertical lines на compound events (Strep, war, ковид), median + IQR ribbon.
  • recovery score boxplot по epoch type (anchor/transit/neutral) — visual «anchor восстанавливает?»
  • REM % vs anchor duration scatter — есть ли threshold длительности после которого REM normalize
  • cross-epoch heatmap — epochs × metrics, z-scored. находит outlier epochs.

что я могу запустить ПРЯМО СЕЙЧАС

два предзаготовительных шага не требуют whoop. могу делать пока ты запускаешь export.

(а) сгенерировать travel_epochs.tsv

ready

epoch skeleton из travel_history.yaml. reusable для любого wearable.

~30 минут agent time

(б) написать tools/whoop_longitudinal_parse.py

ready

argparse, ждёт ZIP path или папку CSV. вся epoch-логика, metric extraction, chart rendering. unit-tested на mock data.

~1.5 часа agent time

caveats и unknowns

algorithm drift: whoop менял HRV алгоритм минимум раз (2023-ish). check release notes. возможно потребуется normalization для cross-period сравнений.
wear-time gaps: некоторые anchor windows могут иметь incomplete wear. flag epochs с <60% coverage и интерпретировать осторожно.
timezone-of-record: whoop иногда стампит в device-tz, иногда в account-tz. при travel может быть mismatch. проверить на 2-3 known TZ swings перед aggregation.
OQ3 scope conditional: если whoop у тебя с 2023 — LA 2020 не разрешается напрямую. это снижает leverage parse'а на ~30%, но не убивает — Bali #1 vs #2 (same geography) даёт сильный proxy для processing × duration question.

зависимости и связанные объекты