feat(metrics): ✨ 3D impulse-response model #34

[dvorka]

---

This PR brings:

• SOTA 3D impulse-response predictive training model.

Related:

• [Feature] 3D IRM - SOTA performance, fatigue and fitness tracking model #34
  • [Enhancement] 3D activities chart for 3D IR model #44
  • [Feature] 3D IRM workouts clustering @ 3D activities scatter plot #59
  • [Feature] 3D IRM workouts cosine distance @ 3D activities chart #58
  • [Enhancement] menu/Progress/Athlete Metrics - page footer details #57
  • [Enhancement] ActivityEntity.ss_* / .irm3D_* #64

---

Plan 3DIRM:

• perfect workout 3DIRM page implementation: fast, efficient, correct
  • terminology refactor towards MyTraL terms
• perfect insight 3DIRM page implementation: fast, pre-calculation, on-demand completion (spinner + tasks)
  • terminology refactor towards MyTraL terms
  • dot for every workout
  • efficient and smart caching
  • irm3d_cache.json stored in data/[user UUID]/blobs/irm3d_cache.json ... misplaced
  • cache must be update asynchronously - show spinner page (currently not shown when it is supposed to be shown)
• add 3D clustering

[Copilot]

Pull request overview

This PR adds two major analytics capabilities to MyTraL’s training metrics suite: a power-based 3D impulse-response model (IRM3D) with caching/background warmup, and an HR-based Banister fitness–fatigue–performance model (TRIMP_ROCKS) with configurable parameters, richer charts, and per-activity impact analysis.

Changes:

• Introduces IRM3D insight pages + per-activity IRM3D analysis, including a file-based cache and a background warmup task.
• Adds Banister/TRIMP_ROCKS model implementation, UI macros/insights, per-activity TRIMP analysis, and Banister parameter settings page.
• Extends athlete metrics persistence/resolution to include CP / W′ / Pmax and wires feature flags + navigation.

Reviewed changes

Copilot reviewed 66 out of 66 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
tests/test_settings_athlete_metrics.py	Extends settings persistence tests for CP/W′/Pmax fields.
tests/test_irm3d.py	Adds unit tests for IRM3D math/pipeline and chart smoke test.
tests/test_irm3d_route.py	Adds route tests for IRM3D insight pages and fingerprinting.
tests/test_irm3d_cache.py	Adds tests for IRM3D file cache behavior and hashing.
tests/test_athlete_metrics.py	Updates athlete-metrics tests to cover new power-model estimations.
tests/conftest.py	Ensures env vars set before importing MyTraL in tests.
mytral/templates/settings-banister.html	Adds Banister parameter settings page template.
mytral/templates/macros/trimp-kpi-card.html	Adds reusable KPI card macro for TRIMP/Banister UI.
mytral/templates/macros/trimp-insight-card.html	Adds reusable insight card macro with lightweight markup parsing.
mytral/templates/layout.html	Updates navigation + includes for additional chart scripts.
mytral/templates/insight-trimp.html	Enhances TRIMP page with Banister/TRIMP_ROCKS UI when enabled.
mytral/templates/insight-irm3d.html	Adds IRM3D progress page with cache-warming UX.
mytral/templates/insight-irm3d-activities-3d-chart.html	Adds Plotly-based 3D scatter page for activities in strain space.
mytral/templates/activity-get.html	Adds quick-access TRIMP analysis button to activity details.
mytral/templates/activity-analysis.html	Adds links/buttons to IRM3D + TRIMP analysis pages.
mytral/templates/activity-analysis-trimp.html	Adds per-activity Banister/TRIMP impact analysis page.
mytral/templates/activity-analysis-irm3d.html	Adds per-activity IRM3D breakdown page.
mytral/tasks/do/irm3d_cache_warmup.py	Adds background task to warm IRM3D cache asynchronously.
mytral/static/documentation/sharing.html	Updates static docs nav to include Banister model doc page.
mytral/static/documentation/normalization.html	Updates static docs nav to include Banister model doc page.
mytral/static/documentation/metrics.html	Updates static docs nav/content to include Banister model section.
mytral/static/documentation/licenses.html	Updates static docs nav to include Banister model doc page.
mytral/static/documentation/license.html	Updates static docs nav to include Banister model doc page.
mytral/static/documentation/index.html	Updates static docs nav to include Banister model doc page.
mytral/static/documentation/feature_metrics.html	Adds IRM3D mention in feature metrics static docs.
mytral/static/documentation/feature_gpx_2d.html	Updates static docs nav to include Banister model doc page.
mytral/static/documentation/feature_datasets.html	Updates static docs nav to include Banister model doc page.
mytral/static/documentation/feature_3d_irm_metric_suite.html	Updates static docs nav to include Banister model doc page.
mytral/static/documentation/digitalization.html	Updates static docs nav to include Banister model doc page.
mytral/static/documentation/credits.html	Updates static docs nav to include Banister model doc page.
mytral/static/documentation/changelog.html	Updates static docs nav to include Banister model doc page.
mytral/static/documentation/architecture.html	Updates static docs nav to include Banister model doc page.
mytral/static/documentation/analysis_tasks.html	Updates static docs nav to include Banister model doc page.
mytral/static/documentation/about.html	Minor static-doc text tweak + adds Banister doc nav entry.
mytral/static/documentation/.feature_template.html	Updates static docs nav template to include Banister model doc page.
mytral/settings.py	Persists Banister params in UserProfile and adds CP/W′/Pmax to AthleteMetrics.
mytral/run.py	Registers IRM3D blueprint in server entry point.
mytral/run_desktop.py	Registers IRM3D blueprint in desktop entry point.
mytral/routes.py	Adds per-activity IRM3D analysis route and integrates model-param resolution.
mytral/releng.py	Adds feature flags IRM3D + TRIMP_ROCKS and corresponding env vars.
mytral/metrics/irm3d_cache.py	Implements file-based IRM3D cache with JSON (date/dataclass) support.
mytral/metrics/banister/_insights.py	Implements Banister “programmatic insights” card builders.
mytral/metrics/banister/_impact.py	Implements per-activity Banister impact analysis (benefits/risks/ETA).
mytral/metrics/banister/_entities.py	Adds Banister dataclasses for params/rows/insights/impact.
mytral/metrics/banister/init.py	Implements Banister model run/project/annotate and re-exports APIs.
mytral/metrics/init.py	Adds metrics package marker/init file.
mytral/forms.py	Adds WTForms form for editing Banister parameters.
mytral/commons.py	Adds Banister/TRIMP_ROCKS thresholds/constants.
mytral/blueprints/trimp_uri_space.py	Adds Banister/TRIMP_ROCKS route logic, per-activity analysis, settings route.
mytral/blueprints/irm3d_uri_space.py	Adds IRM3D insight routes, caching, and warmup task submission.
mytral/backends/dataset.py	Exposes dataset cache property (incl. setter for tests).
mytral/backends/caches/_cache_passthrough.py	Adds Banister rows cache getters/setters (passthrough).
mytral/backends/caches/_cache_inmemory.py	Adds Banister rows caching + eviction/memory-size integration.
mytral/backends/cache.py	Extends cache interface with Banister rows caching methods.
mytral/athlete_metrics.py	Adds Pmax estimation and resolves effective CP/W′/Pmax in athlete metrics.
Makefile	Enables IRM3D/TRIMP_ROCKS in dev/demo targets and adjusts helper targets.
docs/METRICS.md	Adds Banister model section + link to dedicated doc page.
docs/METRICS.banister.md	Adds dedicated Banister model documentation page.
docs/FEATURE_METRICS.md	Adds IRM3D bullet to feature docs.
docs/FEATURE_ANALYSIS_METRICS_SET_OR_ESTIMATE.md	Minor wording update in docs.
docs/ABOUT.md	Minor wording update in docs.
docs/_SITEMAP.md	Adds Banister doc page to documentation sitemap.