Add model weight display

[d-j-hatton]

Each metric/model combination has a weight. The database stores both a history of these values and the current value in separate tables for speed. These weights are logically attached to the grid.

A gridded heatmap with metrics along x and models along y (or the other way around, doesn't matter) seems the best way to display this information. May then want a time slider to see how the heatmap has changed over time. The whole time series can get large (tens of thousands of points per metric/model combination)

It may be the case that the necessary API endpoints don't yet exist, will investigate

[d-j-hatton]

  

[d-j-hatton]

table QualityPredictionModelWeight, model_name column vs metric_name

[vredchenko]

Issue #67 — Model weight display in apps/smartem

Context

Issue #67 asks for a per-grid view of all (model × metric) weights so users can see at a glance which model is most informative for which metric and how that has evolved. Dan's mock-up (image attached to the issue) shows a 3×3 matrix:

• Rows = Models, columns = Metrics (or vice versa — issue says "doesn't matter").
• Each cell carries two pieces of information at once:
  • Background fill colour — encodes the current weight (the heatmap aspect).
  • An inline sparkline — the historical evolution of that weight over time.
• The image also shows distinct cell border colours per column. We'll treat that as a metric-grouping cue rather than a separate data dimension.
• The issue body adds a future time slider so the heatmap colours snap to a chosen point in history.

Backend support: the API client now exposes useGetModelWeightsForGridGridGridUuidModelWeightsGet (PR #86). Response is Record<string, QualityPredictionModelWeight[]> keyed by prediction_model_name; each entry has metric_name, weight, timestamp, quality_score, etc. The issue note "tens of thousands of points per metric/model combination" applies to time-series scope, not the matrix scope.

Where this lives in the app. The smartem-app primary nav already has a top-level Models link (apps/smartem/src/components/shell/Header.tsx, navLinks → { label: 'Models', to: '/models' }), but no route backs it yet. This view is the home of /models, not a sub-tab under a grid. apps/legacy has a per-model weights page (models.$modelName.grids.$gridId.weights.tsx) that predates the issue's matrix concept — we don't touch legacy.

The issue text says weights are "logically attached to the grid", so a single matrix view shows all (model × metric) weights for one grid at a time. For MVP we hard-code a mock grid id; a grid/acquisition selector becomes a follow-up once the visual lands.

Scope split — four PRs

Issue scope has three concept slices (heatmap, time-series, time-slider) but the time-series slice yields two PRs because the library decision is its own deliverable:

PR 67a — Heatmap matrix, current weights only, mock data

The MVP. Static snapshot of "current weights" rendered as a coloured matrix. No time series, no slider. Done as UI-only on hand-rolled mock data.

Deliverables:

• New route apps/smartem/src/routes/models.tsx (route path /models) — landing page that renders the matrix. The existing Header Models nav link starts working.
• Component apps/smartem/src/components/weights/WeightsMatrix.tsx:
  • Rows = unique prediction_model_name from data.
  • Columns = unique metric_name.
  • Each cell: filled with a sequential colour scale based on weight (0..1), with a tooltip on hover showing model, metric, weight, and the latest timestamp.
  • Empty cells (no weight for that pair) rendered as a clearly-distinct "no data" tile.
  • Built with CSS Grid + MUI Box/Paper. No chart library yet.
• Mock fixture apps/smartem/src/data/mock-model-weights.ts:
  • Three to five realistic models (e.g. resnet-atlas, vit-gridsquare, efficientnet-ice, dae-atlas).
  • A handful of metrics (e.g. defocus, astigmatism, ice_thickness, motion, ctf_resolution).
  • Each (model, metric) cell holds one or more QualityPredictionModelWeight entries with realistic timestamps, so PR 67b2/c can reuse the same fixture.
  • Shaped to match the orval-generated QualityPredictionModelWeight type for drop-in replacement later.
• For MVP: /models reads from a hard-coded mockGridId constant, no grid selector. The page header shows which grid the matrix is for so the temporary scope is obvious to reviewers. A grid/acquisition selector is a stated follow-up.
• No backend wiring yet. useGetModelWeightsForGridGridGridUuidModelWeightsGet stays unused for now.

Optional small touches in this PR if cheap:

• Click on a cell reveals a side-panel with the raw weight value + timestamp (no chart yet).
• Legend (colour scale) shown beneath the matrix.

PR 67b1 — ADR: time-series UI library (gating deliverable)

Tracked separately as DiamondLightSource/smartem-devtools#196 — the comparative analysis and ADR live there because the decision has DLS-wide impact (PATo, Evo, DII and future facility frontends share the question, and sci-react-ui may eventually peer-depend on the chosen lib).

The ADR will land at smartem-devtools/docs/decision-records/decisions/0018-time-series-ui-library.md. Candidate set includes davidia (mandatory), Observable Plot, Nivo, Visx, @mui/x-charts, plotly.js, uPlot, Recharts, ECharts. The full brief, including comparison axes and constraints driving the SmartEM use case (REST data, SSE for live updates, MUI v7 theme integration, sparkline-in-cell + drill-down + slider), is in the issue body.

No chart library gets installed in apps/smartem before this ADR is approved. Once it lands, 67b2 unblocks.

PR 67b2 — Time-series implementation

Lands after 67b1 is approved. Uses whichever library the ADR named.

Deliverables:

• Library install + wiring in apps/smartem.
• Sparkline rendered in each non-empty matrix cell using the time series for that (model, metric) pair.
• Cell click → drill-down view (side panel or sub-route) showing a full-size time-series chart for that cell, with axis labels, tooltips, and quality_score overlay if available.
• Mock fixture extended with realistic time series (a few hundred points per cell — enough to look real, light enough to render fast).
• Real-API integration: replace the mock import with the useGetModelWeightsForGridGridGridUuidModelWeightsGet hook. Keep the mock data file in place — MSW serves it via the dev:mock workflow.

Performance budget for time series (also captured in the ADR):

• Sparklines: downsample to ≤ 100 points per cell for a 9-cell-ish matrix.
• Drill-down: render up to ~5,000 points; downsample (LTTB or naive every-Nth) above that. Defer server-side pagination/aggregation as a follow-up tracked separately.

PR 67c — Time slider (enhancement)

Adds an "as of {timestamp}" slider above the matrix. Moving the slider re-colours all cells using the weight value at (or just before) that timestamp.

This is kept as a separate PR, but it's small once 67b2 is in:

• Reuses the same mock/real data already loaded for 67b2.
• Slider implementation depends on the ADR's chosen library: built-in (plotly rangeslider, echarts dataZoom) vs composed (MUI <Slider> driving selectedTimestamp state — matches the legacy precedent at apps/legacy/src/components/timeseries.tsx:111).

Could fold into 67b2 if the chosen library makes the slider near-trivial — defer the call until 67b2 starts.

Library decisions in this plan

• Chart library: deferred to the ADR in PR 67b1. The plan does not pre-pick a winner. davidia must be assessed; if rejected, the rejection is defended in writing. The MVP (67a) needs no chart lib, so this decision doesn't block PR 67a.
• Heatmap colour scale: sequential, one-hue, dark-to-light (e.g. interpolate gray[100] → info.main → success.main). Pick a palette that survives light mode now and works when dark mode is themed later. Final palette confirmed in 67a; if Val wants a specific accessibility test (e.g. colour-blind safe via viridis), call it out at review.
• Component placement: start in apps/smartem/src/components/weights/, NOT packages/ui. Reasons:
  • packages/ui is currently an empty skeleton (src/index.ts is just export {}).
  • The matrix is initially weight-domain-specific. Premature generalisation would slow the MVP.
  • Once 67a lands and we see how it's used, extract a generic <Heatmap rows= cols= cells= /> (and later a <SparklineMatrix>) into packages/ui as a follow-up. The user has already flagged packages/ui as the eventual home — this is a "make it work, then make it general" sequence.
  • sci-react-ui has no chart components today and is focused on nav/auth/theming. A generic <Heatmap> could land there later once it's stable in packages/ui and proven valuable cross-app.

Critical files

PR 67a — new files:

• apps/smartem/src/routes/models.tsx — route at /models, renders the matrix from mock data using a hard-coded grid id. Run npm run router:generate -w @smartem/app to refresh routeTree.gen.ts.
• apps/smartem/src/components/weights/WeightsMatrix.tsx — matrix component.
• apps/smartem/src/components/weights/cellColor.ts — small helper that maps weight ∈ [0,1] to a colour token (single source of truth for the heatmap palette).
• apps/smartem/src/data/mock-model-weights.ts — fixture keyed by grid id.

PR 67a — modified:

• None of the existing tab/nav code. The Models link already sits in apps/smartem/src/components/shell/Header.tsx; once the route is generated, it stops 404-ing.

PR 67b1 — ADR only, lives in a different repo and is tracked separately:

• Tracker: smartem-devtools#196.
• ADR file: smartem-devtools/docs/decision-records/decisions/0018-time-series-ui-library.md.

PR 67b2 — implementation:

• apps/smartem/package.json — add the library the ADR named.
• apps/smartem/src/components/weights/WeightSparkline.tsx — sparkline-in-cell wrapper.
• apps/smartem/src/components/weights/WeightHistoryPanel.tsx — drill-down full-size chart.

Mock data approach

Hand-rolled fixture, not faker/MSW. Two reasons:

• The matrix is more readable when you can predict cell values (verifying colour mapping against known weights).
• It can pre-encode a believable narrative — e.g. a model that recently dropped on the ice_thickness metric — useful for design review without having to reload random data.

Shape the fixture to match the orval-generated QualityPredictionModelWeight type so the swap to the API hook in 67b2 is just changing the import.

The MSW path stays available — mswHandlers.getDefaultMock() will still serve faker-driven random weights for the real API URL — so testing the eventual real-API wiring with dev:mock still works after 67b2.

Verification

PR 67a:

• npm run typecheck clean.
• npm run check clean.
• npm run dev:smartem (or npm run dev:smartem:mock) — click the Models nav link in the header. Matrix renders. Tooltip on hover shows model/metric/weight. The header link becomes active.
• Visual review against Dan's mock-up — colours and layout broadly match (cells, two-axis labels, no sparklines yet).
• Navigation: round-trip Acquisitions ↔ Models doesn't break either; deep-linking direct to /models works.

PR 67b1 (ADR):

• Reviewed by a DLS-wide audience (not just this team), in particular by anyone working on davidia or sci-react-ui.
• davidia evaluation present and concrete; rejection (if that's the conclusion) defended on architecture / bundle / domain-fit / component-surface grounds with specifics.

PR 67b2 (implementation):

• All PR 67a verification, plus sparklines visible in non-empty cells, click on cell opens drill-down with full-size chart.
• npm run build of both apps succeeds (catches bundle-size regression visually).

PR 67c:

• Slider above matrix; dragging it re-colours cells.
• Edge cases: leftmost / rightmost positions, gaps where one cell has no weight at the chosen time (degrade gracefully to "no data" tile).

Out of scope / follow-ups

• Grid / acquisition selector on /models — MVP hard-codes a mock grid. Add a selector (or ?gridId= query param) once the visual is approved.
• packages/ui extraction: extract a generic <Heatmap> after 67a/b stabilise, then propose upstreaming to sci-react-ui.
• Server-side downsampling / aggregation of weight time series for production-scale data.
• Cross-grid comparisons (e.g. "show weights across all grids in this acquisition").
• Alerting on weight drift — out of scope.

[vredchenko]

ADR for the time-series UI library is now tracked at smartem-devtools#196. It includes the comparative analysis brief, the constraints driving the SmartEM use case (REST data, SSE for live updates, MUI v7), and the candidate list (davidia, Observable Plot, Nivo, Visx, @mui/x-charts, plotly.js, uPlot, Recharts, ECharts).

The plan comment above has been updated to reference it. PR 67b2 (time-series implementation) is gated on that ADR landing. PR 67a (heatmap matrix on mock data) is unaffected and can proceed independently.