GitHub ↗
Synthetic demo data — not a real athlete

Docs

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 rendered overview and daily Markdown 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 reads done, planned or missed (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 the subT Report over 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 yearly E values 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 as reports.sh session renders 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 on event_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 — the recovery-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, the sickness report for the same window, and a data-completeness note.
  • docs.html (Docs) — the hobbyjogging-reports README, 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 from experiments/README.md, the list of current experiment scripts with their one-line summaries, and the metric registry from docs/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 a Seasons table (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 N for 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 --bucket and --limit leave 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 --limit it 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 without target_distance_m use 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, where E is that half's weighted efficiency over steady runs in the 40–75 min band (Σdistance / Σexcess beats, in m/excess beat) and RHR is 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|efficiency and --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, eff activities 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:

  • --from and --to together select exactly that inclusive range.
  • --from alone runs from that date through today.
  • --to alone counts back --days (or the command default) from that date.
  • With neither, count back --days (or the command default) from today.
  • planned looks forward instead: --from alone runs --days from that date, --to alone runs from today through that date, and with neither it lists the next --days days (default 28).
  • The old forms still work: classify 30 and subt out.png. An explicit --days / --output wins when both are supplied.
  • The fixed presets (daily, weekly, monthly, yearly, all) keep their existing windows; use report for a custom range. report defaults 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 — the DataSource protocol.
  • 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 (reads source_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 into common, averages, load, zones, subt, planned, and recovery modules.
  • 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 in hobbyjogging_core.classify and 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 a DataSource.
  • 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.