Docs
The report reference, rendered from the repository README. Metric definitions and their promotion history live on the Lab tab.
Reports guide
hobbyjogging-reports
This package is part of the
hobbyjogging workspace; run the
commands below from the repository root. The demo dashboard renders this README
on its Docs tab, so it has to read well in a browser too.
Produces the static training dashboard and the Markdown reports behind it, from the canonical hobbyjogging database. The dashboard is the main view; the Markdown reports carry the same numbers for the terminal.
Dashboard
A self-contained static site, generated from the same analysis layer as the Markdown reports.
dashboard writes it to
$HOBBYJOGGING_DASHBOARD_DIR/dashboard when that variable is set, or to
data/dashboard otherwise. --output DIR overrides the location exactly.
./dashboard.sh prints the generated directory and opens the browser;
./sync.sh regenerates it after a successful sync without opening a browser.
./dashboard.sh
./dashboard.sh --days 30 --activities 100
./dashboard.sh --chart-days 90 --future-days 21
./dashboard.sh --output /tmp/dashboard
./dashboard.sh --demo-label "Synthetic demo data"
./dashboard.sh --timing
The build wraps the source in a read-only per-build cache: activity ranges
are memoized and narrower ranges are served from a covering block, while
intervals and laps are cached by activity id. --timing prints per-phase
seconds and the number of cache misses.
Pages:
index.html— a 7/42/182-day EWMA overview (weekly equivalents of runs, cross sessions, time, km, running load, and Z3+4) plus a planned weekly average for the next 14 days; the main overview chart; and the daily report. Upcoming races live on the Performance tab, and the plan itself on the activities tab (rows and event pages), so Overview no longer repeats the planned report. The EWMA overview and the daily report are the renderedoverviewanddailyMarkdown reports; the chart uses the last 182 days plus the next 14 by default.activities.html— a training log: the recent activities (default 50) with workout methods and targets, linked to per-activity pages, plus a row for every planned event in the shown range and the next 14 days that has no matching activity. The Status column readsdone,plannedormissed(past date, no activity); planned rows show the target time, distance and load, and link to their event page. Long log tables — activities, race results, PBs, the review queue and gear — collapse past 20 rows behind a native checkbox toggle: the first 20 stay visible, the label says "Show all N rows", and every row remains in the HTML, so the links and the browser's find keep working. It is CSS only, with no JavaScript and no build option; the Markdown reports are unchanged.analysis.html— the weekly volume, weekly time-by-pace-zone, and load/RPE charts, plus the pace-vs-heart-rate scatter with its two regression halves and two dashed efficiency lines, over the last two years (--analysis-days, default 731). Runs with stored weather carry the temperature and wind in their hover and the chart notes how many runs have it and the range those cover. The next 42 days are drawn as well: planned weeks as faded, hatched bars in the running-volume colour (stacked on the current week's actual bar), planned zone bars in the same faded zone colours as the actuals in both the time and share panels (the current week's plan stacks on its actual bar, with the share panel normalized to the combined week), and weekly planned load stacked on the current week's actual bar. Each week stacks hard done, hard planned, easy done, easy planned from the bottom up. Season bands shade the volume and load charts behind the bars, with a quiet label at each band start and the dates in the hover. Running time reads in hours on the left; the hard-running averages sit on a right-hand axis in minutes per week that mirrors the hour ticks (2 h = 120 min), so the lines and bars keep one vertical scale. The total, hard and zone averages project through the plan (hard time from the planned zones), with the projected zone area drawn translucent; the averages use the shared line scheme (7d solid, 42d dashed, 182d dash-dot) and the same pale halo as the overview so they read over the bars. The tab ends with a running-streaks card: the current streak (always a bold table row with?as its open end, after an ellipsis when it is below the top five), the run-day and streak totals, and the five longest across all history.nsa.html(NSA) — the subT EWMA report (7/42/182-day pace, heart-rate, and efficiency EWMAs per category), the subT/LT1 chart, and thesubT Reportover the last year. The report's long per-category tables collapse past 20 rows like the activities log (the summary stays open); sessions read newest first.compare.html— volume (km/week), time (hours/week), and efficiency EWMA lines per calendar year over a fixed Jan–Dec axis (--compare-window, default 182), with dashed projected volume/time lines that follow actual values through today and then the plan, a Garmin running VO2max line plot with one raw value per activity, a pace-vs-heart-rate scatter coloured by year with weather in its hover and one dashed steady-efficiency line per year (HR = RHR + v·60/E, with the yearlyEvalues in the chart note), plus the year and month comparison reports (which include the period average Garmin VO2max and a weighted efficiency column). All charts show only the five most recent years by default; older years remain available from the legend. The efficiency chart drops years with fewer than 20 HR-backed runs and years without a resting-HR baseline (currently 2022–2026 only, because resting HR starts in Sep 2022).activity/<id>.html— the session report body (metrics, weather when it is recorded, workout methods and targets, zone times, description, the raw segment table, and subT/LT1 work reps), exactly asreports.sh sessionrenders it. Its planned block links to the day's event page.event/<id>.html— one planned session: date, sport, planned time, distance and load, methods and targets, the planned zone distribution, and the description. When an activity matches the event by date and sport, the page adds an approximate plan-vs-actual table and links to that activity; exact links wait onevent_activity_links. Untyped notes have no page.performance.html(Performance) — upcoming races, race results, personal bests, a per-bucket PB progression chart in pace (5k/10k/HM/M only, with the races that missed the line as hollow dots in the bucket's colour and slow ones above the axis marked), a log-log race chart whose dashed Riegel line passes through the reference race, and an equivalent-times table for 5k, 7k, 10k, 15k, HM, 30k and the marathon with the predicted and PB pace for each. Results and PBs link to per-race pages with splits and execution details.gear.html(Gear) — gear mileage bars with target markers, the gear table, per-year coverage with and without gear, and retirement candidates.recovery.html— therecovery-report(7/42/182-day moving averages, the 365-day baseline column, and the last four nights), then HRV, resting HR, and sleep as interactive plotly panels over the last two years (--recovery-days, default 730) with 7-day averages, readiness bands, illness periods shaded behind each panel, thesicknessreport for the same window, and a data-completeness note.docs.html(Docs) — thehobbyjogging-reportsREADME, rendered as HTML with a table of contents. The overview, daily, planned, recovery, NSA, and compare reports are embedded on their own pages, so there is no separate Reports tab.lab.html(Lab) — the experiments notebook fromexperiments/README.md, the list of current experiment scripts with their one-line summaries, and the metric registry fromdocs/METRICS.md, each with a contents list.health.html(Data Health) — the open review queue (severity, category, detail, linked activity, reported date), the activities hidden by review, missing-data counts, and a per-year data-coverage table (activities and how many carry stored weather; max HR joins it once the model exposes it).
The --reports dashboard option is accepted as a compatibility no-op;
those Markdown reports are already embedded on their relevant pages. The Docs
tab renders the README; the Lab tab renders the experiments notebook, scripts
and metric registry. A demo build (--demo-label) shows the lab's bench rules
only: the notebook, the script list, and the registry hold this athlete's own
results and are left out.
The main chart shows daily running minutes on an axis sized to the
typical day (see Chart axes below),
stacked as hard (Z3+Z4) at the base, easy (Z1+Z2) above it, and
unzoned on top. It draws 7/42/182-day EWMAs for hard and total
running, with the hard lines in reds at the base and the total lines in blues
above them, and the Garmin VO2max standing value as a black line on a second
axis on the right. It defaults to 182 days back and 14 days forward;
--chart-days and --future-days change those. Planned workouts appear as
hatched bars on days without a recorded run, including today, so an
uncompleted planned session is visible; once a run is recorded, the actual bar
replaces the plan bar. Events without pace zones count as unzoned.
Charts are plotly figures built by one shared layer: the CLI writes PNGs via
kaleido, and the dashboard embeds the exact same figures as HTML, so the
overview can be zoomed and panned. The pages remain static snapshots: there
is no client-side data fetching and no server-side report process.
plotly.min.js is bundled into the generated site so it works offline.
Chart axes follow the data instead of a fixed template: each y-axis drops the
top few percent of the plotted values, adds a little headroom and rounds up to
a step suited to the chart (20 km, 1 h, 25 load, 15 min for the overview).
That keeps the axis fitted to a normal training week, so one ultra or a
24-hour day cannot flatten a year of training. Bars above the axis are drawn
clipped and marked with a grey triangle; hover shows the real value. The
42/182-day averages are included when choosing the axis, the 7-day average is
not, so a single spike can briefly leave the top instead of stretching the
whole chart. Every chart draws a thin vertical guide at the nearest day and
a horizontal guide that follows the cursor, so a value can be read off either
axis. Every series the unified hover can show is named: planned segments by
zone (Z4 planned), projections under the line they extend, and subT session
markers by category. An unnamed trace would surface as trace N, which says
nothing about the series, so range sticks and halos skip the hover instead.
Every page carries a GitHub link to the source repository in the top-right
corner. Generation builds a temporary directory and atomically swaps it into
place.
It refuses to replace a non-empty directory unless it is a previous
dashboard (marked with .hobbyjogging-dashboard).
The data-health banner counts activities with open review items, missing
load, missing pace zones, missing HR, and missing distance. The health page
also lists the open review queue itself (severity, category, detail, linked
activity, date) through DataSource.review_items(status="open").
Synthetic demo database
demo-db writes a complete, deterministic training database with an
invented athlete who follows a four-year story: four weeks of continuous
running and a first 5k, a rest week, a classical build to 10k and half
marathon, a 10-day injury and a careful return, a first marathon, six
boom-and-bust weeks, then a threshold-focused Norwegian singles block with
double-threshold days. Thirteen races, intervals, a fartlek, zone times,
wellness, planned workouts, two future races and four shoes. One fitness curve
(5k pace plus an endurance factor per distance) drives every race time,
training pace and the Garmin VO2max value, so they stay in line while still
moving: easy and long runs stay in zones 1–2, workouts carry the hard zones,
the Garmin VO2max estimate only updates on a quality or long run (held on a
0.1 grid in between, and absent on rides), and the 16-week future plan mirrors
the last four complete weeks. It never reads the canonical database or any
personal data.
python -m hobbyjogging_report demo-db --out build/demo.db
# optional: smaller/larger, reproducible seed, fixed build date,
# a couple of review items for screenshots, or overwrite
python -m hobbyjogging_report demo-db --out build/demo.db \
--months 12 --seed 7 --today 2026-11-12 \
--with-review-items --force
--out is required and an existing file is refused without --force;
the canonical HOBBYJOGGING_DB is never used. The file is about 5.2 MB
and contains no raw source payloads.
Build the demo site from it with an explicit database path and the synthetic-data badge:
HOBBYJOGGING_DB=build/demo.db ./dashboard.sh \
--demo-label "Synthetic demo data — not a real athlete"
--demo-label is opt-in and prints a banner on every page; normal
dashboard builds are unchanged.
Data sources
Reports depend on the DataSource protocol from hobbyjogging-core. The
only adapter is DatabaseSource, which reads the canonical SQLite database;
raw payloads stay in source_records, so there is no live API path to keep
in sync with the importers.
Reports and charts
Reads activity, wellness and planned-session data through the canonical
database DataSource and produces the Markdown reports and charts. A single
session or planned workout shows its time as M:SS (H:MM:SS past an hour),
including the elapsed time and zone splits; week, month and category totals
stay compact (1h02).
- daily — Yesterday's activities, today's planned workout, and recovery (HRV / RHR / sleep) from the last nights.
- overview — 7/42/182-day EWMAs for runs, cross sessions, run time, km, running load, and Z3+4, plus the planned weekly average for the next 14 days, plus an Efficiency row in the same table using the trailing 7/42/182-day weighted steady efficiency (40–75 min, no planned value).
- weekly — Aggregated running and cross-training stats, quality sessions and recovery over the last 7 days, including weighted steady efficiency (40–75 min) in the running block and category table.
- monthly — Same summary over the last 30 days.
- yearly — Same summary over the last 365 days.
- all — Daily + weekly + monthly + yearly in one report.
- report — A summary report for an arbitrary inclusive date range
(
--days,--from,--to), with the same weighted steady efficiency total and category column. Period reports also print aSeasonstable (label, kind, dates or ongoing, days inside the range) and the illness days inside the range. - subt-report — All subT and LT1 sessions in a range, grouped by short/medium/long/LT1. Shows work-block and summary tables.
- races — Race results, personal bests per distance bucket (5k, 10k,
HM, M, trail, other with short-course tolerance), upcoming races, a
Riegel exponent fit over every race, and equivalent-time predictions at
5k, 7k, 10k, 15k, HM, 30k and the marathon, each with the predicted pace
and the PB pace. The predictions scale from the reference race (the
newest road 10k, else the newest road race), which the Performance tab's
chart line passes through as well. Standard-distance PBs require a
measured distance within 2% of the standard, so a 4.2 km race cannot win
the 5k PB; Trail and Other are labelled raw, keep the fastest raw time,
and get no PB progression line. Filter with
--bucket 5k|10k|HM|M|Trail|Other,--year YYYY(or--from/--to), and--limit Nfor the latest results, e.g../reports.sh races --bucket 10k --year 2026 --limit 10. Filters scope the results and PB tables; a date filter also scopes upcoming races, while--bucketand--limitleave them unfiltered. - race
— One race-day report: splits, first/second-half pace, planned-vs-actual zones and duration/distance when a race event exists on the same date. - streaks — The current running streak (days, span, km, time, and
whether today is already run) and the longest streaks with the same
fields, cut by
--limit N(default 10). A streak day needs one run of at least 10 minutes; a rest day ends the streak and a ride never extends it, so cross-training cannot hold a running streak. All history from the first activity is used, review-excluded runs do not count, and a run later today is not reported as a missed day. The current streak is always a table row, bold with?for its open end; when it falls below--limitit follows an ellipsis row. The Analysis card uses the same rows and selection logic with five longest (the CLI defaults to ten) and the same totals. - sickness — Illness episodes in a range (default the last 365 days): episode count, illness days and their share of the range, the longest and current (or last) episode, and a newest-first table of each episode with the sessions, time and load done inside it. Illness days are shaded, never excluded from the aggregates.
- equipment — Gear mileage and use from
equipment→activity_equipment→ activities: sessions, km, km/month, last used, target/wear, coverage per year, and retirement candidates. Shoes withouttarget_distance_muse an 800 km default. - recovery-report — HRV, resting HR, and sleep with simple 7/42/182-day moving averages ending today, plus the robust 365-day baseline used by the recovery chart bands, and the last four nights' values in the same layout as the daily report. Missing days are skipped.
- subt-ewma-report — 7/42/182-day EWMAs of the work-interval pace, session heart rate, and efficiency (m/excess beat) for short, medium, long, and LT1, ending today.
- planned — Upcoming planned workouts starting tomorrow, as a compact key-facts table (date, weekday, workout, sport, distance, time, planned Z3+4 time, load); ends with weekly-average total time and Z3+4 time. Next 28 days by default.
- session [date|id|last] — Detailed report for one session, chosen by
date, activity id, or
last(the default): category, workout methods and targets, tags, VO2max (qualified with the sport on a non-run, because Garmin keeps one estimate per sport), review status and open items, totals including efficiency (m/excess beat), zones, description, the day's planned workout and wellness, one raw segment table (typed intervals when there is more than one, otherwise device laps when there is more than one), subT/LT1 work reps, and Intervals/Garmin Connect links when the source knows them. - debug — Dump raw API data (activities, wellness, events, intervals).
- overview-chart — the main training chart (
./charts.sh overview): daily running minutes, stacked hard (Z3+Z4) / easy (Z1+Z2) / unzoned, with hard and total 7/42/182-day EWMAs and hatched planned days, plus the Garmin VO2max standing value as a black line on a second axis on the right. Long days above the axis are marked and clipped. - volume — Weekly running volume chart with 182/42/7-day distance averages and the planned weekly distance; last 90 days by default. Bigger weeks above the axis are marked and clipped.
- load — Weekly load bars stacked as running and cross load (the sum of each Monday-to-Sunday week), with 182-day base, 42-day fitness and 7-day fatigue exponentially weighted averages of running load only, scaled to load per week. Cross load stays as context and does not feed the averages; the lab found no positive transfer to running fitness. Planned running and cross load stack on the current week, and the three session-RPE EWMAs sit on a right-hand axis (RPE carries the last rated value between sessions). The RPE axis is scaled to the RPE series (minimum 6), not to the load axis, so the overlay always fits.
- time — Weekly running time stacked by pace zone (Z1 on top, higher zones at the bottom; Z1/Z2 in blues and Z3/Z4 in reds), with 182/42/7-day time averages, a share-of-week panel, a per-zone EWMA panel, and planned weekly time including planned pace zone distributions. Bigger weeks above the axis are marked and clipped.
- recovery — HRV, resting HR, and sleep trends with a rolling calendar-day average and planned-workout markers. Readiness bands shade the background using a robust 365-day baseline computed at the end of the displayed range: the centre is the median and the spread is 1.4826 × MAD. HRV is green at/above the centre, amber down to one spread below, red below; resting HR mirrored; sleep is absolute (green 7–9 h, amber 6–7 h or 9–10 h, red outside). A one-year window is deliberate: a short window becomes a long illness (March 2026 read RHR 58 green), while in a stable period its tiny SD makes a 2 bpm rise red instead of amber.
- subt — subT and LT1 work intervals over the last 365 days by default, with pace, average HR, and efficiency (m/excess beat) as three stacked panels sharing a date axis. Dots are color-coded by rep length (short/medium/long) or LT1; pace ranges show fastest–slowest, HR ranges show average–max, and the efficiency panel shows each session's worst–best work rep. The pace/HR lines are 42-day EWMAs and the efficiency average is a 42-day weighted mean (sum(distance)/sum(excess beats)); the worst and best reps are shown as the range only, because trends for them overloaded the panel. The pace axis is fixed at 4:20–3:15 min/km (faster up), HR at 140–180 bpm, and efficiency follows the bulk (the top and bottom 5 % are rounded away) so one extreme rep cannot flatten the panel; the hover keeps the full values.
- vo2max — Garmin running VO2max values as daily dots with 7- and 42-day exponentially weighted averages; last 365 days by default.
- pace-hr — Scatter of average speed vs average heart rate, one point
per run, for aerobic-efficiency analysis. The x axis is linear speed
(m/s) labelled in min/km ticks; the point colour runs from blue (oldest)
to red (newest) with a shared year colour bar. Each run category gets its
own fixed marker symbol (easy ○, recovery ◇, intervals □, long run △,
race ★, tempo +, fartlek ⬟, race support ▽, other ×) so the aerobic cloud
does not mix protocols, and the legend/annotation spells out the key. A
least-squares line is fitted to the older and newer half of the runs
(parameters on the chart and printed by the CLI). Each half also gets a
dashed efficiency line,
HR = RHR + v·60/E, whereEis that half's weighted efficiency over steady runs in the 40–75 min band (Σdistance / Σexcess beats, in m/excess beat) andRHRis its median resting-HR baseline; the label shows both values and the band. The scatter keeps every run, but the steady-band points that feed those dashed lines carry a dark outline, and the chart note says so. The compare page keeps the same fixed per-year colours and uses the same category symbols per point. - compare — One EWMA line per calendar year over a fixed Jan–Dec axis;
--metric volume|time|load|runs|efficiencyand--window N(default 182) choose the metric and smoothing. Each year keeps one fixed colour across the compare charts, regardless of the data range. Volume is in km/week and time in hours/week, matching the dedicated volume and time charts. Volume and time also draw dashed projection lines for the current and future years: actual values through today, then the planned events. If today has no run yet, today's planned value is used. The textual year/month comparison reports include the period average Garmin VO2max for each period. The EWMA is computed over the whole history, so each year starts on the previous year's closing value. Only the five most recent years are visible by default; older years stay in the legend and can be enabled there. The current year is partial and marks today. - classify — Print the workout category for each activity over the last N days (default 30).
- activities — Table of recent activities (default: last 20), with selectable columns.
Setup
Install dependencies:
uv sync
Create environment (.env):
export HOBBYJOGGING_DB=<your/path/databasefile.db>
export HOBBYJOGGING_DASHBOARD_DIR=<your/path/dashboard-parent>
The dashboard is written to
$HOBBYJOGGING_DASHBOARD_DIR/dashboard when that variable is set, and to
data/dashboard otherwise.
Run:
uv run --env-file .env python -m hobbyjogging_report daily
uv run --env-file .env python -m hobbyjogging_report overview
uv run --env-file .env python -m hobbyjogging_report weekly
uv run --env-file .env python -m hobbyjogging_report monthly
uv run --env-file .env python -m hobbyjogging_report yearly
uv run --env-file .env python -m hobbyjogging_report all
uv run --env-file .env python -m hobbyjogging_report dashboard
uv run --env-file .env python -m hobbyjogging_report report --days 90
uv run --env-file .env python -m hobbyjogging_report subt-report --days 90
uv run --env-file .env python -m hobbyjogging_report planned
uv run --env-file .env python -m hobbyjogging_report activities --limit 20
uv run --env-file .env python -m hobbyjogging_report session
uv run --env-file .env python -m hobbyjogging_report session 2026-02-22
uv run --env-file .env python -m hobbyjogging_report session 7a2bf884-2b25-585f-8430-530749f80afa
uv run --env-file .env python -m hobbyjogging_report debug
uv run --env-file .env python -m hobbyjogging_report volume [output.png]
uv run --env-file .env python -m hobbyjogging_report overview-chart [output.png]
uv run --env-file .env python -m hobbyjogging_report load [output.png]
uv run --env-file .env python -m hobbyjogging_report time [output.png]
uv run --env-file .env python -m hobbyjogging_report recovery [output.png]
uv run --env-file .env python -m hobbyjogging_report subt [output.png]
uv run --env-file .env python -m hobbyjogging_report vo2max [output.png]
uv run --env-file .env python -m hobbyjogging_report classify [days]
Every command supports --help, for example:
uv run --env-file .env python -m hobbyjogging_report time --help
./charts.sh time --help
./reports.sh session --help
Quick reports
reports.sh wraps the long uv run command, copies the generated
Markdown to the clipboard with wl-copy, and renders headings, lists
and tables for the terminal:
./reports.sh # daily
./reports.sh daily
./reports.sh overview
./reports.sh monthly
./reports.sh report --days 90
./reports.sh report --from 2026-01-01 --to 2026-03-31
./reports.sh subt-report --days 90
./reports.sh planned
./reports.sh planned --days 56
./reports.sh session 2026-10-22
./reports.sh session 7a2bf884-2b25-585f-8430-530749f80afa
./reports.sh session last
The static dashboard has its own wrapper:
./dashboard.sh
./dashboard.sh --days 30 --activities 100
./dashboard.sh --no-open
dashboard.sh also opens the generated index.html in the browser. Use
--no-open or NO_OPEN=1 to skip that.
The clipboard receives the original Markdown before terminal
formatting, so pasting gives clean Markdown. Use NO_COPY=1 to skip
the clipboard, NO_COLOR=1 to disable ANSI colours, or NO_PRETTY=1
to print raw Markdown.
When stdout is a terminal, the direct CLI also displays reports with the same formatting. Redirected or piped output remains raw Markdown.
Charts
Every chart is a plotly figure from the same shared layer the dashboard embeds, so a PNG and a dashboard panel always show the same thing.
Quick charts
charts.sh wraps the chart commands and prints the generated file path:
./charts.sh # weekly volume, last 90 days
./charts.sh overview
./charts.sh overview --chart-days 90 --future-days 21
./charts.sh volume --days 90
./charts.sh volume --output dist.png
./charts.sh volume --planned-days 0
./charts.sh load --days 180
./charts.sh load --base-days 182 --fitness-days 42 --fatigue-days 7
./charts.sh time --days 90
./charts.sh time --zones 4 --zone-window base
./charts.sh recovery --days 90
./charts.sh subt --days 365
./charts.sh subt --output subt.png
./charts.sh subt --from 2026-01-01 --to 2026-06-30 --output subt.png
./charts.sh vo2max --days 365
Charts accept the same --days / --from / --to / --output options
as the direct CLI.
Load chart
load shows weekly load bars stacked as running and cross load, plus three
exponentially weighted averages of running load, all in load per week:
- Base (182d) — long-term training base
- Fitness (42d) — medium-term fitness
- Fatigue (7d) — short-term fatigue
The averages use time-constant EWMA (alpha = 1 - exp(-1 / days)) and are
computed from running load with history before the displayed range and scaled
by seven to per-week units. Cross load is drawn as context but excluded from
the averages, following the lab's cross-training load transfer result (the
best transfer factor is zero). Planned running and cross load continue the
averages into the future as dashed lines and stack on the current week's
actual bars as faded, hatched bars. Change the horizons with --base-days,
--fitness-days, and --fatigue-days.
Activities without training_load are treated as zero load and get a note.
The database currently only has load data from late 2025, so the 182-day
line will still be warming up in earlier charts.
The volume chart applies the same three windows to daily running
distance and scales them to weekly equivalents, so volume and its trends
share one km / week axis. Volume bars are Monday–Sunday weeks.
Time chart
time shows weekly running time in hours as Monday–Sunday bars,
stacked by pace zone. It uses running activities only and defaults to
four zones (Z1–Z4).
The top panel overlays the 182/42/7-day averages of total running time,
scaled to weekly hours. The lower panel stacks the pace-zone EWMAs for the
selected --zone-window (base, fitness, or fatigue; default
fitness / 42 days), also in weekly hours. Its boundary lines are
cumulative: Z4, Z3+Z4, Z2+Z3+Z4, then all zones.
Planned running workouts that carry a pace zone distribution are drawn as
hatched stacked bars over the actual week. Zones beyond --zones fold
into the last displayed zone, and SS buckets are ignored. Planned zones
of other kinds (HR or power) are ignored so the stack matches the actual
pace zones. Weeks whose planned workouts have no pace zones keep the
dashed total-time outline. The lower EWMA panel continues through planned
pace zones as dashed projections, using planned daily zone time and
treating unplanned days as rest.
./charts.sh time
./charts.sh time --days 90
./charts.sh time --zones 4 --zone-window base
./charts.sh time --base-days 182 --fitness-days 42 --fatigue-days 7
Time outside recorded pace zones is shown as an Unzoned segment, so each
bar still totals the recorded running time. Weekly charts expand the
requested range to whole Monday–Sunday weeks.
Recovery chart
recovery shows HRV, resting HR, and sleep as three panels sharing a
date axis:
- daily values as points,
-
a calendar-day rolling average (default 7 days).
./charts.sh recovery ./charts.sh recovery --days 90 ./charts.sh recovery --window 14
Missing values are skipped rather than treated as zero, so a gap in the wellness data does not pull an average down.
VO2max chart
vo2max plots Garmin's running VO2max as one dot per day, with 7-day
and 42-day exponentially weighted averages. The Compare tab has a separate
raw version: one line per year through the activity readings, no daily
averaging or EWMA. Both use
running activities only and ignore Runalyze estimates and cycling/swimming
VO2max values.
Same-day Garmin values are averaged. Days without a measurement carry
the last value forward, so the averages track the metric's standing
value rather than dropping to zero. The averages use
alpha = 1 - exp(-1 / days) and 210 days of history before the display
range. The chart defaults to the last 365 days.
./charts.sh vo2max
./charts.sh vo2max --days 365
./charts.sh vo2max --from 2026-01-01 --to 2026-06-30
Planned workouts
The volume, load, time, and recovery charts include planned workouts.
Unless --to is given, they extend the right edge of the chart by
--planned-days N (default 28); --planned-days 0 disables the
extension.
- volume — planned running distance per Monday–Sunday week, as a dashed target line.
- time — planned running time per week, as an outlined bar over the actual pace-zone stack. Planned pace zone distributions, when available, are drawn as hatched stacked bars; other planned events keep the total-time outline.
- load — planned load per day for all sports, as outlined daily bars.
- recovery — one tick per planned workout along the bottom of the sleep panel.
Events without a sport type (illness or travel notes) are ignored. The volume chart also skips planned events without a distance.
The 182/42/7-day EWMA lines continue through the planned days as dashed segments, using planned daily distance, time, or load and treating unplanned days as rest. The time chart's weekly pace-zone stack and its pace-zone EWMA panel include planned pace zones; the recovery averages stay actual-only.
Session detail
session renders one detailed activity report at a time:
./reports.sh session # most recent session
./reports.sh session last # same
./reports.sh session 2026-10-22 # all sessions on that day
./reports.sh session <activity-id> # one exact activity
The report includes the activity id and date, category, review status, duration/elapsed time, distance and pace, efficiency, HR/load/RPE/feel/ intensity, tags, VO2max, equipment, pace and HR zones, a fenced description block, the day's planned workout and wellness, a table of every recorded one raw segment table, and the subT/LT1 work-rep summary when applicable. The segment table shows typed intervals when there is more than one; otherwise it falls back to device laps when there is more than one; a single segment on either side is skipped because it only restates the activity. Open review items for the session are listed with their severity and detail.
Id lookup scans recent history and expands up to about 20 years. If an
activity is hidden by an open import review item, add --include-review.
Planned workouts report
planned always starts tomorrow, even if --from is today or in the past.
The table lists the planned sessions and ends with a summary:
- total planned time per 7 days;
- planned Z3+4 time per 7 days.
Both are averaged over the report range; a range shorter or longer than a week is scaled to a weekly rate.
subT report
subt-report collects name-marked subT and LT1 sessions in a range and
groups their work into short, medium, long, and LT1 tables:
./reports.sh subt-report # last 90 days
./reports.sh subt-report --days 365
./reports.sh subt-report --from 2026-01-01 --to 2026-06-30
A row is one work block: all same-category reps in a session are merged. A session with work in several categories therefore appears in each relevant group. LT1 sessions always go to the LT1 group, and sessions without usable work reps are omitted.
subT EWMA report
subt-ewma-report smooths each category's work pace, session heart rate,
and efficiency over the last 7, 42, and 182 days:
./reports.sh subt-ewma-report
| Category | 7-day EWMA | 42-day EWMA | 182-day EWMA |
|---|---:|---:|---:|
| Short | 3:28/km | 3:29/km | 3:33/km |
| Medium | 3:38/km | 3:36/km | 3:41/km |
| Long | 3:43/km | 3:45/km | 3:47/km |
| LT1 | 3:48/km | 3:51/km | 3:58/km |
A second table repeats the shape for average heart rate, and a third for efficiency (sum(distance) / sum(excess beats)). Days between sessions keep the last measured value, so the tables describe the standing level of each category. The report also tops the NSA dashboard tab.
The report starts with a summary table (sessions, reps, weekly work time and distance, weighted pace, average/max HR) and then shows one table per non-empty category. Work pace, fastest/slowest rep pace, and HR are derived from the same work reps used by the classification and charts.
Efficiency (m/excess beat)
Metres per heartbeat above resting:
distance_m / ((avg_hr - resting_hr) × duration_min). The definition, the
365-day resting baseline, the validation numbers and the caveats live in the
metric card.
Which runs feed which number:
- Session report, daily compact line,
effactivities column: one raw per-activity value, no duration band. - Period/category, overview and compare aggregates: steady non-quality runs from 40–75 min, with the band printed next to the number. The 40-minute floor includes short easy runs; the duration term makes one read about 1.5 % lower than a 60-minute run, and printing the band keeps that bias visible.
- Pace/HR chart: every run in the scatter; only the dashed efficiency lines use steady 40–75 min runs, whose points carry a dark outline.
- subT chart and summary tables: work-rep efficiency, not steady runs.
Aggregates are always Σdistance / Σexcess beats, never the mean of
per-sample ratios. Resting HR starts in Sep 2022 in the current database, so
older years have no measured baseline and are left out of the compare
efficiency chart. The session report and the eff column still show a value
for those older runs by back-filling the earliest baseline, marked
(estimated baseline); the trend aggregates never use that estimate.
Activities table
activities lists recent activities as a Markdown table.
./reports.sh activities # last 20 activities
./reports.sh activities --limit 50 # last 50
./reports.sh activities --days 30 # everything in the last 30 days
./reports.sh activities --days 90 --limit 10 # newest 10 from the last 90 days
./reports.sh activities --add id,category # defaults plus id and category
./reports.sh activities --columns date,name,distance
Without a date range, the table covers the most recent activities up to
--limit (default 20). With a range, every activity in the range is shown,
capped by --limit if given. Rows are newest first.
Default columns: date, sport, name, duration, distance, pace, avg HR,
load, RPE, feel, methods, targets. --columns replaces them (in the order
given); --add appends. Available columns: id, date, started (UTC), sport,
name, duration, elapsed, distance, pace, avg_hr, load, rpe, feel, intensity,
category, methods, targets, eff (m/excess beat). The category is only computed when requested,
and uses intervals for subT/LT1-named sessions. Methods and targets are the
canonical set tokens with their display labels.
Date ranges
report, subt-report, volume, load, time, recovery,
subt, classify and activities accept:
--days N look back N days from today
--from YYYY-MM-DD start date (inclusive)
--to YYYY-MM-DD end date (inclusive)
planned uses the same options but looks forward:
--days N next N days from today (default 28)
--from YYYY-MM-DD start date (inclusive)
--to YYYY-MM-DD end date (inclusive)
The chart commands also accept:
--output FILE chart output path
Examples:
uv run --env-file .env python -m hobbyjogging_report report --days 90
uv run --env-file .env python -m hobbyjogging_report report --from 2026-01-01 --to 2026-03-31
uv run --env-file .env python -m hobbyjogging_report classify --days 90
uv run --env-file .env python -m hobbyjogging_report classify --from 2026-01-01 --to 2026-03-31
uv run --env-file .env python -m hobbyjogging_report subt --from 2026-02-01
uv run --env-file .env python -m hobbyjogging_report subt --to 2026-06-30 --days 120 --output subt.png
uv run --env-file .env python -m hobbyjogging_report planned
uv run --env-file .env python -m hobbyjogging_report planned --days 56
uv run --env-file .env python -m hobbyjogging_report planned --to 2026-12-31
Rules:
--fromand--totogether select exactly that inclusive range.--fromalone runs from that date through today.--toalone counts back--days(or the command default) from that date.- With neither, count back
--days(or the command default) from today. plannedlooks forward instead:--fromalone runs--daysfrom that date,--toalone runs from today through that date, and with neither it lists the next--daysdays (default 28).- The old forms still work:
classify 30andsubt out.png. An explicit--days/--outputwins when both are supplied. - The fixed presets (
daily,weekly,monthly,yearly,all) keep their existing windows; usereportfor a custom range.reportdefaults to the last 30 days when no range is given.
Workout categories
quality
├── intervals
│ ├── subt-short (avg rep <= 4:00)
│ ├── subt-medium (avg rep 4:01-7:00)
│ ├── subt-long (avg rep > 7:00)
│ ├── lt1
│ └── other
├── longrun (> 90 min)
├── race
├── race-support (warmup / cooldown)
└── tempo
non-quality
├── easy
└── recovery
cross-training
unknown
The heuristic lives in hobbyjogging_core.classify; its module docstring is
the reference. It prefers the stored method/target sets and falls back to
name, RPE and intensity when an activity is unclassified.
Reports add two things on top: weekly, monthly and yearly reports include a category breakdown (sessions, time, load and share per category), and subT sessions are refined by rep length when interval data is available.
Feel ratings
Intervals.icu's 1–5 feel rating is shown alongside RPE in the daily
and session reports (- Feel: 2 (Good)). Weekly, monthly and yearly
reports show the average feel for running and cross-training
separately. The scale is reversed compared with some watches:
| Feel | Meaning |
|---|---|
| 1 | Strong |
| 2 | Good |
| 3 | Normal |
| 4 | Poor |
| 5 | Weak |
Architecture
Data access and analysis are separated so the data source can be replaced (e.g. Intervals.icu API → local database) without touching analysis or chart code:
hobbyjogging_core/model.py— source-agnostic types (Activity,WellnessDay,Event,Interval).hobbyjogging_core/datasource.py— theDataSourceprotocol.cli.py— shared command-line date-range and source parsing.commands.py— command registry and per-command help.command_support.py— shared review/fetch helpers for CLI handlers.report_commands.py— report command handlers.chart_commands.py— chart command handlers.recent.py— widening-lookback search shared by session and activity selection.sessions.py— session selection and the detailed session report.debug.py— raw stored payload dump (readssource_records).sources/__init__.py— the data-source factory.sources/database.py— canonical SQLite database adapter.analysis/— pure metrics over model objects (no API, no plotting), split intocommon,averages,load,zones,subt,planned, andrecoverymodules.series.py— pure daily-series, moving-average, and EWMA helpers.summary.py— period totals, quality-session lists, and recovery averages.classify.py— category aggregation for display (CategoryStat,category_breakdown). The heuristic lives inhobbyjogging_core.classifyand prefers the stored workout classification (activity_workout_methods/targets), falling back to name/RPE/intensity when an activity is unclassified.charts.py— plotly chart builders shared by the CLI and dashboard.format.py— model-based report formatting helpers.links.py— Intervals and Garmin Connect URLs for canonical activities.mdpretty.py— dependency-free terminal Markdown renderer.daily.py,period_report.py,subt_report.py— the Markdown reports; one file per report, obtaining model objects through aDataSource.activity_list.py— the recent-activities table (selection, columns, rendering).
The debug command dumps the payloads already stored in the database.
To add a visualization: compute the metric in analysis/ from model
objects, then plot it in charts.py.