diff --git a/AGENTS.md b/AGENTS.md index 5f0464b..2ff7e0d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -133,6 +133,11 @@ samples/fixture/ synthetic workbooks for tests/CI (committed) - The national data has slips (the 2023 November break "starts" on 28 September): fix them in `SCHOOL_ERRATA`. The job throws if breaks overlap, so a new typo fails the weekly refresh instead of reaching the site. - `dayType` precedence: public holiday > festive window > school holidays > weekend. The pressure page also compares school-holiday weekdays with term-time weekdays, which keeps weekends out of the contrast. +### Sampling conditions (#124) + +- `analytics/samplingConditions.ts` compares daily rain, daily maximum wind and SST on fieldwork nights (distinct dates with a nursery gillnet set: island-wide series, so a night counts once) with every day of the same calendar months. Each month's days are weighted by its fieldwork nights ÷ its days with a value, so the reference has the fieldwork's seasonal mix. One nursery-month holds a median of two nights, too few to plot alone. +- The reference contains the fieldwork nights, so no two-sample test: the statistic is checked against seeded random draws of the same number of days from each month (`DRAWS`). Fieldwork nights are a little drier and calmer than their months (about 0.7 mm less rain); describe it as coverage, not as weather stopping trips. + ### Adding a new season Drop the workbook in `data/` named like `Physioshark_Shark Log 2026-2027.xlsx` (the `YYYY-YYYY` in the file name sets the season). Check the Data quality page for unknown sites, unmatched headers ("Sheet not imported") and unit warnings, and extend aliases if needed. Never rename columns in the workbook to make the importer happy. diff --git a/e2e/sampling-conditions.spec.ts b/e2e/sampling-conditions.spec.ts new file mode 100644 index 0000000..5f0f91b --- /dev/null +++ b/e2e/sampling-conditions.spec.ts @@ -0,0 +1,20 @@ +import { expect, test } from '@playwright/test'; +import AxeBuilder from '@axe-core/playwright'; +test('sampling conditions fit a phone and pass axe in both themes', async ({ page }) => { + await page.setViewportSize({ width: 375, height: 800 }); + await page.goto('/effort'); + await expect( + page.getByRole('heading', { name: 'Which conditions did fieldwork sample?', 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(); +}); diff --git a/src/lib/components/SamplingConditions.svelte b/src/lib/components/SamplingConditions.svelte new file mode 100644 index 0000000..58e4fef --- /dev/null +++ b/src/lib/components/SamplingConditions.svelte @@ -0,0 +1,81 @@ + + +
+

Which conditions did fieldwork sample?

+

+ The weather on the {plural(data.nights, 'night')} with a gillnet set, against every day of the same + {plural(data.months, 'month')} ({month(data.first)} to {month(data.last)}). Months with more + fieldwork count for more, so the comparison isn't just wet season against dry. The weather and + sea temperature are one series for the whole island, so a night counts once however many + nurseries were netted. +

+

+ The reference includes the fieldwork nights themselves. A difference shows which conditions the + data covers; it doesn't say why a trip went ahead or how the sharks responded. +

+ {#if data.nights} +
+ {#each data.metrics as m (m.key)} + + {#if m.rows.length} + r.bin)} + series={[ + { + name: 'Fieldwork nights', + color: 'var(--series-1)', + values: m.rows.map((r) => r.sampledPct) + }, + { + name: 'All days, same months', + color: 'var(--muted)', + values: m.rows.map((r) => r.referencePct) + } + ]} + yLabel="Share (%)" + valueFormat={(v) => `${num(v, v < 10 ? 1 : 0)}%`} + /> + {:else} +

No values for the fieldwork nights.

+ {/if} +
+ {/each} +
+ {:else} +

No nursery gillnet sets to compare.

+ {/if} +
diff --git a/src/lib/server/analytics/samplingConditions.test.ts b/src/lib/server/analytics/samplingConditions.test.ts new file mode 100644 index 0000000..711f843 --- /dev/null +++ b/src/lib/server/analytics/samplingConditions.test.ts @@ -0,0 +1,115 @@ +import { expect, it } from 'vitest'; +import type { Dataset } from '../data'; +import { samplingConditions } from './samplingConditions'; + +type D = Pick; +const days = (month: string, n: number) => + Array.from({ length: n }, (_, i) => `${month}-${String(i + 1).padStart(2, '0')}`); +const make = ( + nights: { date: string; site?: string }[], + precip: (date: string) => number | null, + months: [string, number][] +) => + ({ + sites: [ + { id: 'a', name: 'A', kind: 'nursery' }, + { id: 'b', name: 'B', kind: 'nursery' }, + { id: 'x', name: 'Adults', kind: 'adult' } + ], + sets: nights.map((n) => ({ siteId: n.site ?? 'a', date: n.date, gear: 'Gillnet' })), + weather: months.flatMap(([m, n]) => + days(m, n).map((date) => ({ date, precip: precip(date), windMax: 20 })) + ), + ocean: [] + }) as unknown as D; + +it('counts a night once across sets and nurseries, and ignores other sites and gear', () => { + const d = make( + [ + { date: '2020-02-03' }, + { date: '2020-02-03' }, + { date: '2020-02-03', site: 'b' }, + { date: '2020-02-29', site: 'x' } + ], + () => 0, + [['2020-02', 29]] + ); + d.sets.push({ siteId: 'a', date: '2020-02-10', gear: 'Hook and line' } as D['sets'][number]); + const r = samplingConditions(d); + expect(r).toMatchObject({ nights: 1, months: 1, first: '2020-02', last: '2020-02' }); + expect(r.metrics[0].sampled).toBe(1); +}); + +it('weights each month by its fieldwork, so a dry month and a wet month do not mix', () => { + // January is wet (10 mm every day), March is dry (0 mm). Fieldwork: 3 January nights, 1 in March. + const d = make( + [ + { date: '2021-01-05' }, + { date: '2021-01-06' }, + { date: '2021-01-07' }, + { date: '2021-03-31' } + ], + (date) => (date.startsWith('2021-01') ? 10 : 0), + [ + ['2021-01', 31], + ['2021-03', 31] + ] + ); + const rain = samplingConditions(d).metrics[0]; + // Unweighted, the reference would average 5 mm; weighted 3:1 it matches the fieldwork exactly. + expect(rain.sampledMean).toBeCloseTo(7.5); + expect(rain.refMean).toBeCloseTo(7.5); + // Nights drawn from their own months always give the same mean, so p is 1. + expect(rain.p).toBe(1); + const pct = (k: 'sampledPct' | 'referencePct') => rain.rows.map((r) => r[k]); + expect(pct('sampledPct')).toEqual(pct('referencePct')); + expect(rain.rows.reduce((n, r) => n + r.referencePct, 0)).toBeCloseTo(100, 0); + expect(rain.rows.at(-1)!.bin).toBe('40+'); +}); + +it('keeps missing values missing and stays inside the months with fieldwork', () => { + // 2024-02 has 29 days; two have no rain value, one of them a fieldwork night. + const d = make( + [{ date: '2024-02-01' }, { date: '2024-02-29' }], + (date) => (date === '2024-02-29' || date === '2024-02-10' ? null : 1), + [ + ['2024-01', 31], + ['2024-02', 29] + ] + ); + const rain = samplingConditions(d).metrics[0]; + expect(rain).toMatchObject({ sampled: 1, nightsMissing: 1, refDays: 27, refMissing: 2 }); + // January had no fieldwork: none of its 31 days enter the reference. + expect(rain.rows.reduce((n, r) => n + r.reference, 0)).toBe(27); + // No SST at all: the metric is empty, not zero. + expect(samplingConditions(d).metrics[2]).toMatchObject({ sampled: 0, rows: [] }); +}); + +it('flags fieldwork that picks the dry days of each month', () => { + // Rain on odd days only; every fieldwork night is an even (dry) day. + const months: [string, number][] = [ + ['2019-01', 31], + ['2019-02', 28], + ['2019-03', 31], + ['2019-04', 30] + ]; + const nights = months.flatMap(([m]) => + [2, 4, 6, 8, 10].map((day) => ({ date: `${m}-${String(day).padStart(2, '0')}` })) + ); + const d = make(nights, (date) => (Number(date.slice(8)) % 2 ? 12 : 0), months); + const rain = samplingConditions(d).metrics[0]; + expect(rain.sampledMean).toBe(0); + expect(rain.refMean).toBeGreaterThan(5); + expect(rain.p).toBeLessThan(0.01); + expect(rain.stats).toMatch(/randomisation test, p [<=]/); + // Same seed, same answer on every render. + expect(samplingConditions(d).metrics[0].p).toBe(rain.p); +}); + +it('returns an empty comparison without nursery fieldwork', () => { + expect(samplingConditions({ sites: [], sets: [], weather: [], ocean: [] })).toMatchObject({ + nights: 0, + months: 0, + first: null + }); +}); diff --git a/src/lib/server/analytics/samplingConditions.ts b/src/lib/server/analytics/samplingConditions.ts new file mode 100644 index 0000000..f80df4b --- /dev/null +++ b/src/lib/server/analytics/samplingConditions.ts @@ -0,0 +1,209 @@ +/** + * Conditions on fieldwork nights against the record (#124). The weather and SST series are one + * point for the whole island, so a night counts once however many nurseries or sets it had. + * + * Fieldwork clusters in some months, and the weather changes through the year, so nights are only + * compared with days of the months they fell in. Each calendar month with fieldwork is a stratum, + * and its days carry weight (fieldwork nights ÷ days with a value), so every month counts as much + * in the reference as in the fieldwork. The reference includes the fieldwork nights themselves: + * the two groups overlap, so instead of a two-sample test the statistic is checked against random + * draws of the same number of days from each month (a within-month randomisation test). + */ +import { num, pValue } from '#lib/format'; +import type { Dataset } from '../data'; +import { round } from './common'; + +/** Draws for the randomisation test; p can't go below 1/(DRAWS + 1). */ +export const DRAWS = 5000; + +/** Seeded uniform draws (mulberry32), so the page shows the same p on every render. */ +function rng(seed: number) { + return () => { + seed = (seed + 0x6d2b79f5) | 0; + let t = Math.imul(seed ^ (seed >>> 15), 1 | seed); + t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t; + return ((t ^ (t >>> 14)) >>> 0) / 4294967296; + }; +} + +const daysOf = (month: string) => { + const [y, m] = month.split('-').map(Number); + const n = new Date(Date.UTC(y, m, 0)).getUTCDate(); + return Array.from({ length: n }, (_, i) => `${month}-${String(i + 1).padStart(2, '0')}`); +}; + +interface Variable { + key: string; + label: string; + unit: string; + dp: number; + get: (date: string) => number | null | undefined; + /** Bin edges. With `open`, the last edge starts a final open-ended bin. */ + edges: (values: number[]) => number[]; + open?: boolean; +} + +/** Equal-width edges at multiples of `step` that cover every value. */ +const steps = (step: number) => (values: number[]) => { + const lo = Math.floor(Math.min(...values) / step) * step; + const hi = Math.max(lo + step, Math.ceil((Math.max(...values) + 1e-9) / step) * step); + return Array.from({ length: Math.round((hi - lo) / step) + 1 }, (_, i) => + round(lo + i * step, 3)! + ); +}; + +export function samplingConditions(d: Pick) { + const nurseries = new Set(d.sites.filter((s) => s.kind === 'nursery').map((s) => s.id)); + const nights = new Set( + d.sets + .filter((s) => s.gear === 'Gillnet' && s.date && s.siteId && nurseries.has(s.siteId)) + .map((s) => s.date!) + ); + const byMonth = new Map(); + for (const date of [...nights].sort()) { + const m = date.slice(0, 7); + byMonth.set(m, [...(byMonth.get(m) ?? []), date]); + } + const months = [...byMonth.keys()]; + const weather = new Map(d.weather.map((r) => [r.date, r])); + const ocean = new Map(d.ocean.map((r) => [r.date, r])); + const variables: Variable[] = [ + { + key: 'rain', + label: 'Rain that day', + unit: 'mm', + dp: 1, + get: (x) => weather.get(x)?.precip, + edges: () => [0, 1, 5, 10, 20, 40], + open: true + }, + { + key: 'wind', + label: 'Strongest wind that day', + unit: 'km/h', + dp: 1, + get: (x) => weather.get(x)?.windMax, + edges: steps(5) + }, + { + key: 'sst', + label: 'Sea-surface temperature', + unit: '°C', + dp: 2, + // Same source as the per-set SST (OISST where present, else Coral Reef Watch; #154). + get: (x) => ocean.get(x)?.oisst ?? ocean.get(x)?.crwSst, + edges: steps(0.5) + } + ]; + + const metrics = variables.map((v, vi) => { + const value = (x: string) => { + const y = v.get(x); + return y != null && Number.isFinite(y) ? y : null; + }; + // One stratum per month with fieldwork: its valid days and its valid fieldwork nights. + const strata = months + .map((m) => ({ + days: daysOf(m) + .map(value) + .filter((y): y is number => y != null), + nights: byMonth + .get(m)! + .map(value) + .filter((y): y is number => y != null) + })) + .filter((s) => s.nights.length && s.days.length); + const sampledN = strata.reduce((n, s) => n + s.nights.length, 0); + const nightsMissing = nights.size - sampledN; + const refDays = strata.reduce((n, s) => n + s.days.length, 0); + const refMissing = + months.reduce((n, m) => n + daysOf(m).length, 0) - + months.reduce((n, m) => n + daysOf(m).filter((x) => value(x) != null).length, 0); + if (!sampledN) return { key: v.key, label: v.label, unit: v.unit, sampled: 0, rows: [] }; + + const all = strata.flatMap((s) => s.days); + const edges = v.edges(all); + // Closed scales have one bin per pair of edges (the last includes its top edge); an open + // scale's last edge starts a final "and above" bin. + const nBins = v.open ? edges.length : edges.length - 1; + const bin = (y: number) => { + let i = nBins - 1; + while (i > 0 && y < edges[i]) i--; + return i; + }; + const sampled = new Array(nBins).fill(0); + const refCount = new Array(nBins).fill(0); + const refShare = new Array(nBins).fill(0); + let sampledSum = 0, + refMean = 0; + for (const s of strata) { + const w = s.nights.length / sampledN / s.days.length; + for (const y of s.nights) { + sampled[bin(y)]++; + sampledSum += y; + } + for (const y of s.days) { + refCount[bin(y)]++; + refShare[bin(y)] += w; + refMean += w * y; + } + } + const sampledMean = sampledSum / sampledN; + const diff = sampledMean - refMean; + + // Within-month randomisation: draw each month's number of nights from its own days. + const rand = rng(124 + vi); + let extreme = 0; + for (let b = 0; b < DRAWS; b++) { + let total = 0; + for (const s of strata) { + const pool = s.days.slice(); + for (let i = 0; i < s.nights.length; i++) { + const j = i + Math.floor(rand() * (pool.length - i)); + [pool[i], pool[j]] = [pool[j], pool[i]]; + total += pool[i]; + } + } + if (Math.abs(total / sampledN - refMean) >= Math.abs(diff) - 1e-9) extreme++; + } + const p = (extreme + 1) / (DRAWS + 1); + + const fmt = (y: number) => num(y, v.dp === 2 ? 1 : 0); + const rows = sampled.map((n, i) => ({ + bin: + v.open && i === nBins - 1 ? `${fmt(edges[i])}+` : `${fmt(edges[i])}–${fmt(edges[i + 1])}`, + sampled: n, + sampledPct: round((100 * n) / sampledN, 1)!, + reference: refCount[i], + referencePct: round(100 * refShare[i], 1)! + })); + const shown = round(diff, v.dp)!; + const gap = + shown === 0 + ? `0 ${v.unit}` + : `${shown > 0 ? '+' : '−'}${num(Math.abs(shown), v.dp)} ${v.unit}`; + const stats = `Fieldwork nights averaged ${num(sampledMean, v.dp)} ${v.unit} against ${num(refMean, v.dp)} ${v.unit} on all days of the same months, weighted by fieldwork per month (${gap}; within-month randomisation test, ${pValue(p)}, ${num(DRAWS)} draws).`; + return { + key: v.key, + label: v.label, + unit: v.unit, + sampled: sampledN, + nightsMissing, + refDays, + refMissing, + sampledMean: round(sampledMean, v.dp + 1), + refMean: round(refMean, v.dp + 1), + p, + stats, + rows + }; + }); + + return { + nights: nights.size, + months: months.length, + first: months[0] ?? null, + last: months.at(-1) ?? null, + metrics + }; +} diff --git a/src/routes/effort/+page.server.ts b/src/routes/effort/+page.server.ts index 9a33446..d1aae0a 100644 --- a/src/routes/effort/+page.server.ts +++ b/src/routes/effort/+page.server.ts @@ -1,4 +1,5 @@ import { memo } from '#lib/server/data'; +import { samplingConditions } from '#lib/server/analytics/samplingConditions'; import { activeNurseries, cpueOf, @@ -83,6 +84,7 @@ export const load: PageServerLoad = () => g, n: d.sets.filter((s) => s.gear === g).length })), - other: d.sets.filter((s) => s.siteId && d.siteById.get(s.siteId)?.kind !== 'nursery').length + other: d.sets.filter((s) => s.siteId && d.siteById.get(s.siteId)?.kind !== 'nursery').length, + samplingConditions: samplingConditions(d) }; }); diff --git a/src/routes/effort/+page.svelte b/src/routes/effort/+page.svelte index 5d57ca8..34ac2de 100644 --- a/src/routes/effort/+page.svelte +++ b/src/routes/effort/+page.svelte @@ -1,5 +1,6 @@