diff --git a/AGENTS.md b/AGENTS.md index a45a0c4..887e1cb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -121,6 +121,11 @@ samples/fixture/ synthetic workbooks for tests/CI (committed) - φ is apparent: death and leaving look the same, and moving to another nursery counts as leaving. Nurseries need ≥ 10 pups seen again in a later fortnight of the same season. The transience model gives the first fortnight after tagging its own φ. - `fitCjs` is generic and validated on simulated histories in `survival.test.ts`. Reuse it rather than writing another fitter. Wald intervals are on the logit scale and are null at the boundary (φ ≈ 1). +### Scar transitions (#126) + +- `analytics/scarTransitions.ts` pairs consecutive field captures of one shark within a season that both have a scar stage. Unknown stages are skipped. These pairs are left out: identity conflicts, a capture sharing its day with another, pairs spanning two seasons and pairs with a lab stay in between. Backward transitions stay visible and are counted for the lab. +- The days are time between captures, not healing time or age. A transition gets a box only from five pairs (`MIN_BOX_PAIRS`). Labels match the rest of /neonates: open, healing, healed. + ### School holidays (#25) - `fetch-external.mjs --only=school` writes `external/school-holidays.csv` (first and last day off, local dates). 2013-14 to 2016-17 are transcribed in the script from the Polynesian government's calendar orders for collèges and lycées (arrêtés 0270/CM 2013, 0399, 0401 and 0403/CM 2014), archived from education.pf by the Wayback Machine; the national dataset only starts in 2017-18. From 2017-18 it is the Ministry's `fr-en-calendrier-scolaire` open data (Polynésie, Licence Ouverte 2.0, credit it): pupils only, a day counts when either level is off, `end_date` is the day classes resume. diff --git a/e2e/scar-transitions.spec.ts b/e2e/scar-transitions.spec.ts new file mode 100644 index 0000000..956d1e7 --- /dev/null +++ b/e2e/scar-transitions.spec.ts @@ -0,0 +1,30 @@ +import { expect, test } from '@playwright/test'; +import AxeBuilder from '@axe-core/playwright'; + +test('scar transitions remain readable on mobile in both themes', async ({ page }) => { + await page.setViewportSize({ width: 375, height: 800 }); + for (const theme of ['light', 'dark'] as const) { + await page.emulateMedia({ colorScheme: theme }); + await page.goto('/neonates'); + await expect( + page.getByRole('heading', { name: 'Scar changes in the same shark' }) + ).toBeVisible(); + const card = page + .locator('figure') + .filter({ has: page.getByRole('heading', { name: 'Observed scar transitions' }) }) + .first(); + await expect(card).toBeVisible(); + await card.locator('svg').focus(); + await page.keyboard.press('ArrowRight'); + await expect(card.locator('.tip')).toBeVisible(); + await page.keyboard.press('Escape'); + await expect(card.getByRole('button', { name: /Download CSV/ })).toBeVisible(); + const result = await new AxeBuilder({ page }).include('main').analyze(); + expect( + result.violations.filter((v) => ['serious', 'critical'].includes(v.impact ?? '')) + ).toEqual([]); + expect( + await page.evaluate(() => document.documentElement.scrollWidth - innerWidth) + ).toBeLessThanOrEqual(1); + } +}); diff --git a/src/lib/components/ScarTransitions.svelte b/src/lib/components/ScarTransitions.svelte new file mode 100644 index 0000000..117fc34 --- /dev/null +++ b/src/lib/components/ScarTransitions.svelte @@ -0,0 +1,88 @@ + + +
+

Scar changes in the same shark

+

+ Each pair is two consecutive captures of one shark in the same season with a scar stage recorded + both times; captures without a stage are skipped. The days are the time between those captures, + not how long the scar took to heal or the shark's age: the change happened somewhere in between. + A last unhealed record doesn't mean the scar never healed, and pairs from one shark aren't + independent. +

+ {#each groups as g (g.species)} + {@const name = speciesName(g.species).toLowerCase()} +

{speciesName(g.species)}

+

+ {plural(g.pairs, 'pair')} from {plural(g.sharks, 'shark')}. Left out: {plural( + g.excluded.identity, + 'pair' + )} from sharks whose records disagree (sex, species or a shrinking length), {num( + g.excluded.chronology + )} with two captures on one day, {num(g.excluded.season)} spanning two seasons and {num( + g.excluded.lab + )} with a lab stay in between. {plural(g.unknown, 'capture')} had no scar stage recorded{g.missingIdentityOrDate + ? `, and ${plural(g.missingIdentityOrDate, 'capture')} no tag or date` + : ''}. {g.backward + ? `${plural(g.backward, 'pair goes', 'pairs go')} backwards (a healed scar later recorded as open or healing); they stay in the chart for the lab to check.` + : 'No pair goes backwards.'} +

+ {#if g.pairs} +
+ + + + + r.stats) + .map((r) => ({ + name: `${r.from} → ${r.to}`, + color: SPECIES[g.species].color, + stats: r.stats + }))} + yLabel="Days between captures" + /> + +
+

+ Pairs per shark: {g.contributions + .map((r) => `${plural(r.sharks, 'shark')} gave ${plural(r.pairs, 'pair')}`) + .join(', ')}. +

+ {:else}

No sharks were recorded at a known scar stage twice in one season.

{/if} + {/each} +
diff --git a/src/lib/server/analytics/scarTransitions.test.ts b/src/lib/server/analytics/scarTransitions.test.ts new file mode 100644 index 0000000..e886f08 --- /dev/null +++ b/src/lib/server/analytics/scarTransitions.test.ts @@ -0,0 +1,67 @@ +import { expect, it } from 'vitest'; +import type { Dataset, Capture } from '../data'; +import { scarTransitions } from './scarTransitions'; + +const cap = (id: string, date: string, stage: string | null, extra = {}) => + ({ + individualId: id, + date, + umbilical: stage, + season: '2020-2021', + species: 'Cm', + kind: 'field', + ...extra + }) as Capture; +it('skips unknown stages but retains backward transitions and per-shark contributions', () => { + const d = { + captures: [ + cap('a', '2020-10-01', 'open'), + cap('a', '2020-10-03', null), + cap('a', '2020-10-08', 'closed'), + cap('a', '2020-10-10', 'semi') + ], + individuals: [], + labSharks: [] + }; + const [r] = scarTransitions(d); + expect(r).toMatchObject({ + pairs: 2, + sharks: 1, + unknown: 1, + backward: 1, + contributions: [{ pairs: 2, sharks: 1 }] + }); + // One open → healed pair: counted, but too few for a box. + expect(r.rows[2]).toMatchObject({ from: 'Open', to: 'Healed', pairs: 1, stats: null }); +}); +it('draws a days-between box once a transition has five pairs', () => { + const d = { + captures: ['a', 'b', 'c', 'd', 'e'].flatMap((id, i) => [ + cap(id, '2020-10-01', 'open'), + cap(id, `2020-10-${String(5 + i * 2).padStart(2, '0')}`, 'closed') + ]), + individuals: [], + labSharks: [] + }; + // Gaps of 4, 6, 8, 10 and 12 days. + expect(scarTransitions(d)[0].rows[2].stats?.median).toBe(8); +}); +it('excludes conflicts, same-day observations, season boundaries and lab interruptions', () => { + const d = { + captures: ['a', 'b', 'c', 'd'].flatMap((id) => [ + cap(id, '2020-10-01', 'open'), + cap( + id, + id === 'b' ? '2020-10-01' : '2020-10-08', + 'closed', + id === 'c' ? { season: '2021-2022' } : {} + ) + ]), + individuals: [{ id: 'a', conflict: 'sex' }], + labSharks: [{ individualId: 'd', arrivalDate: '2020-10-03', releaseDate: '2020-10-06' }] + } as Pick; + expect(scarTransitions(d)[0]).toMatchObject({ + pairs: 0, + excluded: { identity: 1, chronology: 1, season: 1, lab: 1 } + }); +}); diff --git a/src/lib/server/analytics/scarTransitions.ts b/src/lib/server/analytics/scarTransitions.ts new file mode 100644 index 0000000..4f6c070 --- /dev/null +++ b/src/lib/server/analytics/scarTransitions.ts @@ -0,0 +1,90 @@ +import type { Dataset } from '../data'; +import { boxStats } from '#lib/stats'; +import { recapturePairs } from './common'; + +const stages = ['open', 'semi', 'closed']; +// The labels /neonates uses elsewhere ("open → healing → healed"). +export const SCAR_LABELS = ['Open', 'Healing', 'Healed']; +/** A transition needs this many pairs before its days-between box is drawn. */ +export const MIN_BOX_PAIRS = 5; + +/** Consecutive known-stage field observations, within one season; never infer healing dates. */ +export function scarTransitions(d: Pick) { + const conflicts = new Set(d.individuals.filter((i) => i.conflict).map((i) => i.id)); + return (['Cm', 'Na'] as const).map((species) => { + const field = d.captures.filter((c) => c.kind === 'field' && c.species === species); + const known = field.filter( + (c) => c.umbilical && stages.includes(c.umbilical) && c.date && c.individualId + ); + const excluded = { identity: 0, chronology: 0, season: 0, lab: 0 }; + const dayCounts = new Map(); + for (const c of known) { + const key = `${c.individualId}|${c.date}`; + dayCounts.set(key, (dayCounts.get(key) ?? 0) + 1); + } + const pairs = recapturePairs(known).filter((p) => { + if (conflicts.has(p.id)) { + excluded.identity++; + return false; + } + if ( + p.days <= 0 || + dayCounts.get(`${p.id}|${p.a.date}`)! > 1 || + dayCounts.get(`${p.id}|${p.b.date}`)! > 1 + ) { + excluded.chronology++; + return false; + } + if (p.a.season !== p.b.season) { + excluded.season++; + return false; + } + if ( + p.a.toLab || + d.labSharks.some( + (l) => + l.individualId === p.id && + (!l.arrivalDate || l.arrivalDate <= p.b.date!) && + (!l.releaseDate || l.releaseDate >= p.a.date!) + ) + ) { + excluded.lab++; + return false; + } + return true; + }); + const rows = stages.flatMap((from, i) => + stages.map((to, j) => { + const ps = pairs.filter((p) => p.a.umbilical === from && p.b.umbilical === to); + return { + from: SCAR_LABELS[i], + to: SCAR_LABELS[j], + pairs: ps.length, + sharks: new Set(ps.map((p) => p.id)).size, + backward: j < i, + stats: ps.length >= MIN_BOX_PAIRS ? boxStats(ps.map((p) => p.days)) : null + }; + }) + ); + const contributions = new Map(); + for (const p of pairs) contributions.set(p.id, (contributions.get(p.id) ?? 0) + 1); + return { + species, + labels: SCAR_LABELS, + rows, + values: stages.map((_, i) => rows.slice(i * 3, i * 3 + 3).map((r) => r.pairs)), + pairs: pairs.length, + sharks: contributions.size, + unknown: field.filter((c) => !c.umbilical || !stages.includes(c.umbilical)).length, + missingIdentityOrDate: field.filter((c) => !c.date || !c.individualId).length, + excluded, + backward: rows.filter((r) => r.backward).reduce((n, r) => n + r.pairs, 0), + contributions: [...new Set(contributions.values())] + .sort((a, b) => a - b) + .map((n) => ({ + pairs: n, + sharks: [...contributions.values()].filter((v) => v === n).length + })) + }; + }); +} diff --git a/src/routes/neonates/+page.server.ts b/src/routes/neonates/+page.server.ts index bd041ca..6c7ccdf 100644 --- a/src/routes/neonates/+page.server.ts +++ b/src/routes/neonates/+page.server.ts @@ -1,4 +1,5 @@ import { memo } from '#lib/server/data'; +import { scarTransitions } from '#lib/server/analytics/scarTransitions'; import { fieldCaptures, firstPerSeason, @@ -181,6 +182,7 @@ export const load: PageServerLoad = () => ) }; return { + scarTransitions: scarTransitions(d), stats, weeks, openCm: openShare('Cm'), diff --git a/src/routes/neonates/+page.svelte b/src/routes/neonates/+page.svelte index 4ceb06d..0058f75 100644 --- a/src/routes/neonates/+page.svelte +++ b/src/routes/neonates/+page.svelte @@ -1,4 +1,5 @@