diff --git a/AGENTS.md b/AGENTS.md index 5f0464b..0df1b9c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -110,6 +110,8 @@ samples/fixture/ synthetic workbooks for tests/CI (committed) - `analytics/catchModel.ts`: negative-binomial counts per timed gillnet set, offset log(net-hours), natural-spline day of season (knots at the 0/25/50/75/100% quantiles), nursery and season as effect-coded fixed effects (each level vs the average; no random effects), and nine environment terms per +1 SD. Complete cases only; nurseries need ≥ 30 complete sets, and a species gets a nursery effect only where ≥ 10 of it were caught (otherwise the estimate runs off to zero or infinity). - The headline: sea temperature's raw link with catch rate (≈ −25% per °C) vanishes once day of the season is in the model. Don't describe SST as a driver of catches on other pages. - `glm.ts` is generic (IRLS + ML θ, Wald intervals via `contrast`); reuse it rather than writing another fitter. +- `selectCatchModel()` holds the sample filters (`MIN_SITE_SETS`, `MIN_SITE_CATCH`, `MIN_MODEL_SETS`); the fits and the "Which sets does the model use?" chart (#123, `modelSelectionFlow`) both call it, so change filters there. The first steps are sequential; each species model restarts from the all-shark sample. +- Measurement coverage on /data-quality (#123, `analytics/measurementCoverage.ts`) counts records with a value over eligible records, per season: availability, not validity. Zero is recorded; a cell with no eligible records stays empty, not 0%. Lavage results only count captures marked lavaged or with a result. ### Sex ratio mixed model (#117) diff --git a/e2e/measurement-coverage.spec.ts b/e2e/measurement-coverage.spec.ts new file mode 100644 index 0000000..fd04569 --- /dev/null +++ b/e2e/measurement-coverage.spec.ts @@ -0,0 +1,31 @@ +import { expect, test } from '@playwright/test'; +import AxeBuilder from '@axe-core/playwright'; + +test('coverage heatmaps fit a phone and pass axe in both themes', async ({ page }) => { + await page.setViewportSize({ width: 375, height: 800 }); + await page.goto('/data-quality'); + await expect( + page.getByRole('heading', { name: 'What was recorded, season by season', exact: true }) + ).toBeVisible(); + for (const colorScheme of ['light', 'dark'] as const) { + await page.emulateMedia({ colorScheme }); + const results = await new AxeBuilder({ page }).include('main').analyze(); + expect( + results.violations.filter((v) => v.impact === 'serious' || v.impact === 'critical') + ).toEqual([]); + } + expect( + await page.evaluate(() => document.documentElement.scrollWidth - innerWidth) + ).toBeLessThanOrEqual(1); + await expect(page.getByRole('button', { name: /Download CSV/ }).first()).toBeVisible(); + // The notes table is wider than a phone: it scrolls and takes keyboard focus (#150). + const notes = page.getByRole('region', { name: 'Data notes' }); + await notes.focus(); + await expect(notes).toBeFocused(); +}); + +test('the catch model shows which sets it uses', async ({ page }) => { + await page.goto('/drivers'); + await page.getByText('Which sets does the model use?', { exact: true }).click(); + await expect(page.getByRole('heading', { name: 'Sets left after each filter' })).toBeVisible(); +}); diff --git a/src/app.css b/src/app.css index a9d5e17..ae5fb44 100644 --- a/src/app.css +++ b/src/app.css @@ -43,6 +43,8 @@ --seq-5: #256abf; --seq-6: #184f95; --seq-7: #0d366b; + /* Text on the strong end of the scale (seq-5 to seq-7): dark cells in light mode, pale in dark. */ + --seq-strong-ink: #ffffff; --div-neg: #2a78d6; --div-mid: #f0efec; --div-pos: #e34948; @@ -83,6 +85,7 @@ --seq-5: #5598e7; --seq-6: #86b6ef; --seq-7: #cde2fb; + --seq-strong-ink: #08111f; --div-mid: #2a3446; --shadow: 0 1px 2px rgb(0 0 0 / 0.3); } @@ -120,6 +123,7 @@ --seq-5: #5598e7; --seq-6: #86b6ef; --seq-7: #cde2fb; + --seq-strong-ink: #08111f; --div-mid: #2a3446; --shadow: 0 1px 2px rgb(0 0 0 / 0.3); } diff --git a/src/lib/components/ChartCard.svelte b/src/lib/components/ChartCard.svelte index ec5df09..bb76198 100644 --- a/src/lib/components/ChartCard.svelte +++ b/src/lib/components/ChartCard.svelte @@ -71,7 +71,7 @@ {#if table && table.rows.length}
Show data ({table.rows.length} rows) - +
{/if} {#if canDownload} diff --git a/src/lib/components/DataTable.svelte b/src/lib/components/DataTable.svelte index 2cf96b8..2524c0e 100644 --- a/src/lib/components/DataTable.svelte +++ b/src/lib/components/DataTable.svelte @@ -13,8 +13,31 @@ let { columns, rows, - max = 200 - }: { columns: Column[]; rows: Record[]; max?: number } = $props(); + max = 200, + label = 'Data table' + }: { + columns: Column[]; + rows: Record[]; + max?: number; + /** Names the scroll region for screen readers. */ + label?: string; + } = $props(); + + // A table wider than its box scrolls sideways, so keyboard users need to focus it (#150). The + // server can't measure, so it renders every table focusable; after mount only tables that + // overflow keep the tab stop. + let box = $state(); + let overflows = $state(true); + $effect(() => { + const el = box; + if (!el) return; + const check = () => (overflows = el.scrollWidth > el.clientWidth + 1); + check(); + const ro = new ResizeObserver(check); + ro.observe(el); + if (el.firstElementChild) ro.observe(el.firstElementChild); + return () => ro.disconnect(); + }); const shown = $derived(rows.slice(0, max)); const fmt = (v: unknown, c: Column) => v == null || v === '' @@ -24,7 +47,14 @@ : String(v); -
+ +
diff --git a/src/lib/components/MeasurementCoverage.svelte b/src/lib/components/MeasurementCoverage.svelte new file mode 100644 index 0000000..407bbbb --- /dev/null +++ b/src/lib/components/MeasurementCoverage.svelte @@ -0,0 +1,68 @@ + + +
+

What was recorded, season by season

+

+ The share of records with a value for each measurement, which shows what each comparison on this + site can draw on. It is not a check that the values are right, and it says nothing about the + lab's work. A zero counts as recorded. A blank can't tell a skipped measurement from one the + protocol didn't call for that season. A dashed cell has no records to count. Each table gives + the counts. +

+

+ Lavage results count only captures marked as lavaged or with a result. Of the rest, {plural( + data.unknownLavage, + 'capture doesn’t', + 'captures don’t' + )} say whether the shark was lavaged and {plural(data.notLavaged, 'was', 'were')} marked as not lavaged. +

+ {#each panels as p (p.title)} + + + + {/each} +
diff --git a/src/lib/components/ModelSelection.svelte b/src/lib/components/ModelSelection.svelte new file mode 100644 index 0000000..095aadc --- /dev/null +++ b/src/lib/components/ModelSelection.svelte @@ -0,0 +1,74 @@ + + +
+ Which sets does the model use? +

+ Each bar is the number of sets left after a filter, counted by the same code the model uses. The + first three filters run in order and leave the sample for all sharks. Each species model then + starts again from that sample and drops the nurseries where that species was rarely caught. +

+ {#if incomplete} +

+ Of the {plural(incomplete, 'set')} missing a model variable, {missingText.length > 1 + ? `${missingText.slice(0, -1).join(', ')} and ${missingText.at(-1)}` + : missingText[0]}{flow.missing.length > 1 ? `; a set can lack more than one` : ''}. +

+ {/if} +

+ Being in the sample doesn't guarantee a fit: the model also needs at least {num( + flow.minModelSets + )} sets, two nurseries and two seasons. The sample for all sharks has {plural( + flow.modelSets, + 'set' + )} from {plural(flow.nurseries, 'nursery', 'nurseries')} over {plural(flow.seasons, 'season')}. +

+ + r.stage)} + series={[ + { name: 'Sets', color: 'var(--series-1)', values: flow.rows.map((r) => r.remaining) } + ]} + valueFormat={(v) => num(v)} + /> + +
+ + diff --git a/src/lib/components/charts/Heatmap.svelte b/src/lib/components/charts/Heatmap.svelte index c790a63..40ea86d 100644 --- a/src/lib/components/charts/Heatmap.svelte +++ b/src/lib/components/charts/Heatmap.svelte @@ -49,22 +49,27 @@ const hi = $derived(domain?.[1] ?? (flat.length ? Math.max(...flat) : 1)); const absMax = $derived(Math.max(Math.abs(lo), Math.abs(hi)) || 1); - function fill(v: number | null): { color: string; opacity: number; dark: boolean } { + function fill(v: number | null): { color: string; opacity: number; ink: string } { // No data: an empty dashed cell, never a colour from the scale (the lightest steps are // close to --surface-2, in dark mode especially). - if (v == null || !Number.isFinite(v)) return { color: 'none', opacity: 1, dark: false }; + if (v == null || !Number.isFinite(v)) return { color: 'none', opacity: 1, ink: 'var(--ink)' }; if (mode === 'div') { const t = Math.max(-1, Math.min(1, v / absMax)); - if (Math.abs(t) < 0.06) return { color: 'var(--div-mid)', opacity: 1, dark: false }; + if (Math.abs(t) < 0.06) return { color: 'var(--div-mid)', opacity: 1, ink: 'var(--ink)' }; return { color: t < 0 ? 'var(--div-neg)' : 'var(--div-pos)', opacity: 0.18 + 0.82 * Math.abs(t), - dark: Math.abs(t) > 0.6 + ink: Math.abs(t) > 0.6 ? '#ffffff' : 'var(--ink)' }; } const t = hi === lo ? 1 : (v - lo) / (hi - lo); const k = Math.min(7, 1 + Math.floor(t * 6.999)); - return { color: `var(--seq-${k})`, opacity: 1, dark: k >= 5 }; + // The strong end is dark in light mode and pale in dark mode, so its text flips with it. + return { + color: `var(--seq-${k})`, + opacity: 1, + ink: k >= 5 ? 'var(--seq-strong-ink)' : 'var(--ink)' + }; } let tip = $state(null); @@ -133,7 +138,7 @@ dy="0.32em" text-anchor="middle" font-size="10" - fill={f.dark ? '#ffffff' : 'var(--ink)'} + fill={f.ink} pointer-events="none">{format(v)} {/if} diff --git a/src/lib/server/analytics/catchModel.ts b/src/lib/server/analytics/catchModel.ts index 3c328bb..65570ff 100644 --- a/src/lib/server/analytics/catchModel.ts +++ b/src/lib/server/analytics/catchModel.ts @@ -24,7 +24,9 @@ const TERMS = [ 'crew' ] as const; /** Nurseries need this many complete sets to get their own effect. */ -const MIN_SITE_SETS = 30; +export const MIN_SITE_SETS = 30; +/** The model needs this many sets from supported nurseries (and two nurseries, two seasons). */ +export const MIN_MODEL_SETS = 200; const SPLINE_KNOTS = [0, 0.25, 0.5, 0.75, 1]; type Response = 'all' | 'Cm' | 'Na'; @@ -46,9 +48,10 @@ function count(s: SetRow, r: Response): number { } /** A species gets its own nursery effect only where it was caught at least this often. */ -const MIN_SITE_CATCH = 10; +export const MIN_SITE_CATCH = 10; -export function catchModel(d: Dataset) { +/** The sample selection behind every fit; /drivers shows it step by step (#123). */ +export function selectCatchModel(d: Dataset) { const vars = TERMS.map((k) => SET_VARIABLES.find((v) => v.key === k)!); const complete = effortSets(d).filter( (s) => s.cpue != null && s.date && s.siteId && vars.every((v) => v.get(s) != null) @@ -61,7 +64,18 @@ export function catchModel(d: Dataset) { .sort(); const base = complete.filter((s) => sites.includes(s.siteId!)); const seasons = [...new Set(base.map((s) => s.season))].sort(); - if (base.length < 200 || sites.length < 2 || seasons.length < 2) return null; + const selectSpecies = (r: Response) => { + const caught = new Map(); + for (const s of base) caught.set(s.siteId!, (caught.get(s.siteId!) ?? 0) + count(s, r)); + const own = sites.filter((id) => r === 'all' || (caught.get(id) ?? 0) >= MIN_SITE_CATCH); + return { own, rows: base.filter((s) => own.includes(s.siteId!)) }; + }; + return { vars, complete, perSite, sites, base, seasons, selectSpecies }; +} + +export function catchModel(d: Dataset) { + const { vars, perSite, sites, base, seasons, selectSpecies } = selectCatchModel(d); + if (base.length < MIN_MODEL_SETS || sites.length < 2 || seasons.length < 2) return null; // Scales and spline knots come from the full model so every species shares the same units. const scale = vars.map((v) => { @@ -79,10 +93,7 @@ export function catchModel(d: Dataset) { const iEnv = 1; const iDay = iEnv + vars.length; const fitFor = (r: Response) => { - const caught = new Map(); - for (const s of base) caught.set(s.siteId!, (caught.get(s.siteId!) ?? 0) + count(s, r)); - const own = sites.filter((id) => r === 'all' || (caught.get(id) ?? 0) >= MIN_SITE_CATCH); - const rows = base.filter((s) => own.includes(s.siteId!)); + const { own, rows } = selectSpecies(r); const ownSeasons = seasons.filter((x) => rows.some((s) => s.season === x)); const days = rows.map((s) => seasonDay(s.date!)); const meanBasis = new Array(nSpline).fill(0); diff --git a/src/lib/server/analytics/measurementCoverage.test.ts b/src/lib/server/analytics/measurementCoverage.test.ts new file mode 100644 index 0000000..69b5c50 --- /dev/null +++ b/src/lib/server/analytics/measurementCoverage.test.ts @@ -0,0 +1,50 @@ +import { expect, it } from 'vitest'; +import { dataset } from '../data'; +import { catchModel } from './catchModel'; +import { coverageCell, measurementCoverage, modelSelectionFlow } from './measurementCoverage'; + +it('distinguishes zero, missing and no eligible records', () => { + expect(coverageCell([0, null, 2], (v) => v != null)).toEqual({ + available: 2, + eligible: 3, + percent: 200 / 3 + }); + expect( + coverageCell( + [1], + () => true, + () => false + ) + ).toEqual({ available: 0, eligible: 0, percent: null }); +}); + +it('keeps empty strata missing rather than 0%', () => { + const c = measurementCoverage(dataset()); + for (const p of [c.captures, c.sets]) { + expect(p.values).toHaveLength(p.seasons.length); + for (const r of p.rows) { + if (r.eligible === 0) expect(r.percent).toBeNull(); + else expect(r.percent).toBeCloseTo((100 * r.available) / r.eligible, 1); + } + } +}); + +it('reconciles the selection flow with the fitted samples', () => { + const d = dataset(); + const f = modelSelectionFlow(d); + const [timed, complete, base, cm, na] = f.rows; + expect(f.rows.every((r) => r.excluded >= 0)).toBe(true); + // Sequential steps: each set is left out once. + expect(timed.remaining - complete.excluded - base.excluded).toBe(base.remaining); + // Species steps start again from the all-shark sample. + for (const r of [cm, na]) expect(base.remaining - r.excluded).toBe(r.remaining); + // Missing variables overlap: together they cover at least the sets left out for them. + expect(f.missing.reduce((n, m) => n + m.n, 0)).toBeGreaterThanOrEqual(complete.excluded); + const model = catchModel(d); + if (model) { + expect(model.n).toBe(base.remaining); + expect(model.dropped).toBe(timed.remaining - base.remaining); + if (model.cm) expect(model.cm.n).toBe(cm.remaining); + if (model.na) expect(model.na.n).toBe(na.remaining); + } +}); diff --git a/src/lib/server/analytics/measurementCoverage.ts b/src/lib/server/analytics/measurementCoverage.ts new file mode 100644 index 0000000..f2b5013 --- /dev/null +++ b/src/lib/server/analytics/measurementCoverage.ts @@ -0,0 +1,142 @@ +/** + * Measurement coverage (#123): how many records have a value for each measurement, season by + * season, and the sample selection behind the catch model. Coverage is availability, not validity. + */ +import type { Dataset, Capture, SetRow } from '../data'; +import { effortSets, round } from './common'; +import { MIN_MODEL_SETS, MIN_SITE_CATCH, MIN_SITE_SETS, selectCatchModel } from './catchModel'; + +/** Availability is distinct from validity; zero is a recorded value. */ +export function coverageCell( + rows: T[], + present: (r: T) => boolean, + eligible: (r: T) => boolean = () => true +) { + const subset = rows.filter(eligible), + available = subset.filter(present).length; + return { + available, + eligible: subset.length, + percent: subset.length ? (100 * available) / subset.length : null + }; +} + +export function measurementCoverage(d: Dataset) { + const captures = d.captures.filter((c) => c.kind === 'field'); + const sets = d.sets.filter((s) => s.gear === 'Gillnet'); + const panel = ( + rows: T[], + fields: { label: string; present: (r: T) => boolean; eligible?: (r: T) => boolean }[] + ) => { + const table = d.seasons.flatMap((season) => + fields.map((f) => { + const c = coverageCell( + rows.filter((r) => r.season === season), + f.present, + f.eligible + ); + return { season, field: f.label, ...c, percent: round(c.percent, 1) ?? null }; + }) + ); + return { + fields: fields.map((f) => f.label), + seasons: d.seasons, + rows: table, + values: d.seasons.map((s) => table.filter((r) => r.season === s).map((r) => r.percent)) + }; + }; + return { + captures: panel(captures, [ + { label: 'Length', present: (c) => c.tlMm != null }, + { label: 'Mass', present: (c) => c.massKg != null }, + { label: 'Length + mass', present: (c) => c.tlMm != null && c.massKg != null }, + { label: 'Sex', present: (c) => c.sex === 'M' || c.sex === 'F' }, + { label: 'Scar', present: (c) => c.umbilical != null }, + { label: 'Capture time', present: (c) => c.captureMin != null }, + { + label: 'Lavage result', + present: (c) => c.stomach != null, + eligible: (c) => c.lavage === 1 || c.stomach != null + } + ]), + sets: panel(sets, [ + { label: 'Duration', present: (s) => s.durationMin != null }, + { label: 'Start time', present: (s) => s.startMin != null }, + { label: 'Crew size', present: (s) => s.crewSize != null }, + { label: 'Water °C', present: (s) => s.waterTemp != null }, + { label: 'pH', present: (s) => s.ph != null }, + { label: 'Oxygen', present: (s) => s.doMg != null }, + { label: 'Salinity', present: (s) => s.salinity != null }, + { label: 'SST', present: (s) => s.sst != null }, + { label: 'Rain', present: (s) => s.rain24h != null }, + { label: 'Tide', present: (s) => s.tideMidMm != null } + ]), + unknownLavage: captures.filter((c) => c.lavage == null && c.stomach == null).length, + notLavaged: captures.filter((c) => c.lavage === 0 && c.stomach == null).length + }; +} + +/** + * The catch model's sample, filter by filter, from the same selectCatchModel() the fits use. The + * first three steps are sequential; each species model then drops nurseries from the all-shark + * sample, so its "left out" counts from that sample, not from the bar above. + */ +export function modelSelectionFlow(d: Dataset) { + const s = selectCatchModel(d); + const timed = effortSets(d).filter((x) => x.cpue != null); + const step = (stage: string, rule: string, rows: SetRow[], from: number) => ({ + stage, + rule, + remaining: rows.length, + nurseries: new Set(rows.map((x) => x.siteId).filter(Boolean)).size, + excluded: from - rows.length + }); + const rows = [ + step('Timed gillnet sets', 'Gillnet sets with a duration', timed, timed.length), + step( + 'Every variable recorded', + 'Date, nursery and every model variable', + s.complete, + timed.length + ), + step( + `Nurseries with ≥ ${MIN_SITE_SETS} sets`, + `The sample for all sharks: nurseries with at least ${MIN_SITE_SETS} of those sets`, + s.base, + s.complete.length + ), + ...( + [ + ['Cm', 'Blacktip model', 'blacktips'], + ['Na', 'Sicklefin lemon model', 'sicklefin lemons'] + ] as const + ).map(([code, label, plural]) => + step( + label, + `From the all-shark sample: nurseries where at least ${MIN_SITE_CATCH} ${plural} were caught`, + s.selectSpecies(code).rows, + s.base.length + ) + ) + ]; + // A set can miss several variables, so these overlap and can add up to more than the step. + const missing = [ + { label: 'date', n: timed.filter((x) => !x.date).length }, + { label: 'nursery', n: timed.filter((x) => !x.siteId).length }, + ...s.vars.map((v) => ({ + label: v.label.toLowerCase(), + n: timed.filter((x) => v.get(x) == null).length + })) + ] + .filter((m) => m.n > 0) + .sort((a, b) => b.n - a.n); + return { + rows, + missing, + minModelSets: MIN_MODEL_SETS, + minSiteSets: MIN_SITE_SETS, + modelSets: s.base.length, + nurseries: s.sites.length, + seasons: s.seasons.length + }; +} diff --git a/src/routes/data-quality/+page.server.ts b/src/routes/data-quality/+page.server.ts index c0c1ce4..40e51e8 100644 --- a/src/routes/data-quality/+page.server.ts +++ b/src/routes/data-quality/+page.server.ts @@ -1,4 +1,5 @@ import { memo } from '#lib/server/data'; +import { measurementCoverage } from '#lib/server/analytics/measurementCoverage'; import type { PageServerLoad } from './$types'; export const load: PageServerLoad = () => @@ -11,6 +12,7 @@ export const load: PageServerLoad = () => cats.set(k, c); } return { + coverage: measurementCoverage(d), summary: [...cats.values()].sort((a, b) => b.n - a.n), issues: d.issues.map((i) => ({ ...i, diff --git a/src/routes/data-quality/+page.svelte b/src/routes/data-quality/+page.svelte index 2cd3127..30fd08e 100644 --- a/src/routes/data-quality/+page.svelte +++ b/src/routes/data-quality/+page.svelte @@ -1,4 +1,5 @@