This is the Python version of "ImReady4", a matlab app to display recent Heart Rate Variability and Resting Heart Rate statistics for endurance athletes, to help deciding daily training readiness.
- Copy data/config-template.yaml to data/config.yaml
- Enter intervals.icu athlete ID and API Key (in settings)
- Start run.sh
- matplotlib graphs pop up. See NOTES.md for meaning.
- See AGENTS.md for GenAI hints (or self if manual work).
- If you want to change or add things, feel free to fork and send pull requests. Be sure to have good test coverage, and green tests.
General notes about app and idea behind it - mostly from original authors of "myithlete" training guide (now defunct, see https://web.archive.org/web/20241114202544/https://www.myithlete.com/how-to-use-the-ithlete-pro-training-guide/ ), incl user comments, and from author of Matlab version as published on intervals.icu forum (see https://forum.intervals.icu/t/how-to-guide-imready4-app-for-hrv-guided-training/25778 ).
No code or text copied from original myithlete version to Matlab version.
Python code transformed 1:1 from Matlab version with GPT, then built upon slightly.
Full credits for original code to original author @Inigo_Tolosa on intervals.icu forums. Converted to Python and published under GPL with permission.
App computes z-scores for HRV (rMSSD, log-transformed) and Resting Heart Rate (RHR) over rolling 30-day window. Z-scores show how today's values compare to recent baseline:
- Z-score = 0 → exactly at 30-day average
- Z-score > 0 → above average (higher than usual)
- Z-score < 0 → below average (lower than usual)
HRV: higher better (more recovery). RHR: lower better (more rested).
Table maps HRV and RHR z-scores to training advice. Conditions evaluated in order — first match wins:
| # | Label | HRV z-score | RHR z-score | Coaching Hint |
|---|---|---|---|---|
| 1 | ...? | NaN | NaN (either) | No HRV data Today. Take a measurement. |
| 2 | HIT | > 1 | (-1, 1] | Ready for Intensive Training |
| 3 | LIT | [-1, 0) | ≤ -2 | Low intensity training |
| 4 | LIT! | ≥ 0 | ≤ -2 | Keep calm! Acute fatigue signs |
| 5 | Normal | ≥ -1 | < 1.7 | Go on! Train as planned. |
| 6 | LIT | ≥ -1 | ≥ 1.7 | Low intensity training |
| 7 | Rest | < -1 | ≤ -2 | Time to recover. Avoid overtraining |
| 8 | LIT | < -1 | (-2, 1.7] | Low intensity training. Recovery is not complete |
| 9 | REST! | < -1 | > 1.7 | Be careful! Illness or stress detected |
HIT — HRV well above baseline (> 1 std dev) while RHR normal. Autonomic nervous system well-recovered, primed for stress. Ideal day for high-intensity intervals, race-pace work, or max-effort strength.
Normal — Both HRV and RHR within typical range. No excess fatigue or stress. Proceed with planned training — tempo run, endurance ride, or moderate session.
LIT (code 2, RHR elevated or very low) — RHR notably outside normal band (unusually high ≥ 1.7 std dev, or unusually low ≤ -2 std dev) while HRV still acceptable. Something off — early fatigue, mild dehydration, or external stress. Keep training light: easy spins, recovery jogs, yoga, or mobility work.
LIT! (acute fatigue) — RHR dropped hard (≤ -2 std dev) while HRV normal or elevated. Paradoxical pattern often means acute parasympathetic overload from accumulated training stress. Body compensating hard. Train only at very low intensity; prioritize sleep and nutrition.
LIT (incomplete recovery) — HRV suppressed (< -1 std dev) but RHR still reasonable. Recovery from recent training not yet complete. Avoid adding intensity; stick to easy aerobic work or active recovery.
Rest — HRV low and RHR unusually depressed. Autonomic nervous system shows clear overreaching. Take full rest day or at most gentle walk. Focus on recovery: sleep, hydration, nutrition.
REST! (illness/stress alert) — HRV suppressed while RHR much elevated. Combo is red flag for illness, severe psychological stress, or deep overtraining. Do not train. Monitor symptoms; consider consulting physician if pattern persists.
- HRV = -1: Boundary between "acceptable" and "suppressed" HRV
- RHR = -2: Boundary for unusually low resting heart rate (fatigue)
- RHR = 1.7: Boundary for unusually high resting heart rate (stress/illness)
ImReady4's readiness chart is circular (polar) diagram inspired by ithlete Pro Training Guide. Unlike original rectangular four-quadrant layout, this version wraps two physiological axes into radial plot so athlete's state readable from shape and colour at a glance, no numbers to memorise.
- Radial axis (distance from centre) — Recovery (HRV): HRV z-score controls how far dot sits from middle. Closer to centre = higher HRV (better recovery); further out = lower HRV (suppressed recovery).
- Angular axis (left–right sweep) — Activation (RHR): RHR z-score controls angular position. 12-o'clock line = baseline RHR. Dots swing right when HR elevated and left when HR depressed.
- Centre point: Individual 30-day rolling average for both metrics — "all normal" state.
Chart circular, so each zone is curved wedge not rectangular box:
| Zone | Sector location | Interpretation |
|---|---|---|
| Normal | Inner region, near 12 o'clock | Both metrics within their usual band — follow your training plan |
| Intensive | Innermost band, centred at 12 o'clock | Strong parasympathetic recovery with unremarkable cardiac activation — the body can handle demanding sessions |
| Impaired Recovery | Mid-to-outer ring, moderate rightward | HRV is depressed — consider reducing volume or intensity |
| Stress / Illness | Outer ring, swept right (high HR) | Depressed HRV coincides with elevated HR — a warning sign of illness, psychological stress, or overreaching |
| Acute Fatigue | Inner ring, swept left (low HR) | Paradoxically high HRV with unusually low HR — often parasympathetic overload from accumulated training stress, not fitness |
| Overreaching | Outer ring, swept left | Low HRV and depressed HR — clear signs of overreaching; take a full rest day |
- Most recent measurement = bold star marker; previous day = softer grey circle.
- Past several days connected by dashed trace to follow short-term trajectory around chart.
- Older readings (up to ~4 weeks) fade to neutral grey, forming background cloud that reveals typical scatter pattern.
Over training block, cluster of daily dots drifts in characteristic directions on circular chart:
- Positive adaptation — cloud contracts toward centre and drifts slightly left (improved recovery, calm activation).
- Maladaptation / overreaching — readings expand outward and sweep right (suppressed recovery, heightened sympathetic tone).
- Race-ready taper — dots sit near centre with slight rightward lean. Mild increase in activation (sympathetic priming) with near-baseline HRV linked to peak competitive performance.
Circular layout rewards nuance: dot barely drifting out of green sector — especially after several days near centre or during planned overload block — may not need schedule change. Dot far out in stress/illness sector warrants immediate rest regardless of plans. Always weigh chart position against known context (sleep quality, life stressors, training phase).
Some single-metric apps flag any above-baseline HRV reading as caution. Dual-axis model here more discriminating:
- Moderately elevated HRV with unchanged HR → autonomic system recovered well; intensity appropriate.
- Sharply elevated HRV with notably depressed HR → likely acute parasympathetic saturation from cumulative fatigue, not fitness gain. Body down-regulates to protect itself; high effort typically not sustainable.
Examining both variables together — as advocated in research of Dan Plews and colleagues — ImReady4 distinguishes genuine readiness from fatigue-induced vagal overshoot, which single HRV number alone cannot reveal.
- Record one measurement per day, immediately after waking, before getting out of bed or consuming anything.
- Later readings influenced by food, caffeine, posture, accumulated daily stress, making them incomparable to morning reference.
- What matters most: consistency of conditions — same time, same posture, same routine — so day-to-day changes reflect genuine physiological shifts not measurement noise.
When recent activity available, ImReady4 renders three-panel figure: yesterday HR/Power chart, "Power vs Heart rate" regression scatter, and stats panel.
Middle panel plots recorded power (w) against heart rate (bpm) as scatter cloud, then fits linear regression through it.
- Data pooling — points pooled across several recent sample runs
(
regression_streams) not single activity, so fit reflects current aerobic form, not one noisy session. No pooled streams supplied → falls back to single activity. - Filtering — only meaningful aerobic samples kept: power below
180 w and heart rate below 110 bpm discarded, and samples where HR
changes faster than
MAX_HR_SLOPE(1.0 bpm/sample) dropped as transients (activity starts, standing breaks). - Corridor fit — second pass removes points lying more than
REGRESSION_CORRIDORwatts from first-pass line, so outliers don't distort slope. - Readout — fitted line drawn black with equation
y = slope·x + interceptandR²goodness-of-fit shown top left. Fixed reference lineEasy: 0.83x + 115.7shown bottom left for comparison against known easy-effort relationship.
Steeper slope or lower intercept over time = more power produced per heartbeat — marker of improving aerobic efficiency.
On left "Yesterday" chart (labelled with selected activity strategy, e.g. HighestLoad), power drawn blue and heart rate red. Thick orange line is predicted power computed from heart rate via same regression used in scatter panel:
predicted_power = slope · heart_rate + intercept
- Answers "given my heart rate, how much power should I have been producing at current efficiency?"
- Where actual (blue) power sits above orange line you were more efficient than baseline; below it, less efficient (fatigue, heat, terrain, or drift).
- Orange line blanked (not drawn) for timestamps filtered out of regression — start-up, transients, and samples beyond HR stream — so it only appears where prediction meaningful.