From 92e065a340d649d4b7a44ce762caeb67f064381f Mon Sep 17 00:00:00 2001 From: luen Date: Wed, 4 Nov 2026 09:32:46 +1000 Subject: [PATCH 1/2] Charts: show within-shark scar transitions (#126) --- AGENTS.md | 2 + e2e/scar-transitions.spec.ts | 30 +++++++ src/lib/components/ScarTransitions.svelte | 75 ++++++++++++++++ .../server/analytics/scarTransitions.test.ts | 54 ++++++++++++ src/lib/server/analytics/scarTransitions.ts | 86 +++++++++++++++++++ src/lib/server/import/index.ts | 2 +- src/routes/neonates/+page.server.ts | 2 + src/routes/neonates/+page.svelte | 2 + 8 files changed, 252 insertions(+), 1 deletion(-) create mode 100644 e2e/scar-transitions.spec.ts create mode 100644 src/lib/components/ScarTransitions.svelte create mode 100644 src/lib/server/analytics/scarTransitions.test.ts create mode 100644 src/lib/server/analytics/scarTransitions.ts diff --git a/AGENTS.md b/AGENTS.md index ace5450..fe34f01 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -116,6 +116,8 @@ samples/fixture/ synthetic workbooks for tests/CI (committed) ### Adding a new season +- Scar-transition charts (#126) pair consecutive known-stage field observations within a season. Unknown stages are skipped; identity conflicts, same-day pairs and possible lab interruptions are excluded. Backward transitions remain visible. Elapsed observation intervals are not healing times. + 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. ## Charts & design 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..9ab5e1a --- /dev/null +++ b/src/lib/components/ScarTransitions.svelte @@ -0,0 +1,75 @@ + + +
+

Scar changes in the same shark

+

+ Consecutive known-stage field observations within a season; observations without a stage are + skipped. These are days between observations, not healing time or age since birth. A last + unhealed observation does not mean a shark never healed. Repeat pairs from one shark are not + independent evidence. +

+ {#each groups as g (g.species)} +

{g.species === 'Cm' ? 'Blacktip reef sharks' : 'Sicklefin lemon sharks'}

+

+ {g.pairs} pairs from {g.sharks} sharks; {g.unknown} observations with unknown stages and {g.missingIdentityOrDate} + without identity/date (counts can overlap). Excluded pairs: {g.excluded.identity} identity conflicts, + {g.excluded.chronology} same-day/ambiguous chronology, {g.excluded.season} season boundaries, {g + .excluded.lab} possible lab interruptions. {g.backward} backward transitions retained for review. +

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

+ Pairs contributed per shark: {g.contributions + .map( + (r) => + `${r.pairs} pair${r.pairs === 1 ? '' : 's'}: ${r.sharks} shark${r.sharks === 1 ? '' : 's'}` + ) + .join('; ')}. +

+ {:else}

No eligible repeat observations with known scar stages.

{/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..d5f2383 --- /dev/null +++ b/src/lib/server/analytics/scarTransitions.test.ts @@ -0,0 +1,54 @@ +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 }] + }); + expect(r.rows[2].stats?.median).toBe(7); +}); +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..ebe48e1 --- /dev/null +++ b/src/lib/server/analytics/scarTransitions.ts @@ -0,0 +1,86 @@ +import type { Dataset } from '../data'; +import { boxStats } from '#lib/stats'; +import { recapturePairs } from './common'; + +const stages = ['open', 'semi', 'closed']; +export const SCAR_LABELS = ['Open', 'Healing', 'Closed']; + +/** 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'].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: boxStats(ps.map((p) => p.days)) + }; + }) + ); + const contributions = new Map(); + for (const p of pairs) contributions.set(p.id, (contributions.get(p.id) ?? 0) + 1); + return { + species, + 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/lib/server/import/index.ts b/src/lib/server/import/index.ts index 3cfd073..6ce12c6 100644 --- a/src/lib/server/import/index.ts +++ b/src/lib/server/import/index.ts @@ -73,7 +73,7 @@ import { SITE_DEFS } from './sites'; import { readWorkbook } from './xlsx'; /** Bump when import logic changes so existing caches rebuild on the next start. */ -export const IMPORTER_VERSION = '8'; +export const IMPORTER_VERSION = '9'; const MIGRATIONS = import.meta.glob('/drizzle/*.sql', { query: '?raw', 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..5a6fcf8 100644 --- a/src/routes/neonates/+page.svelte +++ b/src/routes/neonates/+page.svelte @@ -1,4 +1,5 @@ -
+

Scar changes in the same shark

- Consecutive known-stage field observations within a season; observations without a stage are - skipped. These are days between observations, not healing time or age since birth. A last - unhealed observation does not mean a shark never healed. Repeat pairs from one shark are not - independent evidence. + 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)} -

{g.species === 'Cm' ? 'Blacktip reef sharks' : 'Sicklefin lemon sharks'}

+ {@const name = speciesName(g.species).toLowerCase()} +

{speciesName(g.species)}

- {g.pairs} pairs from {g.sharks} sharks; {g.unknown} observations with unknown stages and {g.missingIdentityOrDate} - without identity/date (counts can overlap). Excluded pairs: {g.excluded.identity} identity conflicts, - {g.excluded.chronology} same-day/ambiguous chronology, {g.excluded.season} season boundaries, {g - .excluded.lab} possible lab interruptions. {g.backward} backward transitions retained for review. + {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}`, stats: r.stats }))} - yLabel="Days between observations" + .map((r) => ({ + name: `${r.from} → ${r.to}`, + color: SPECIES[g.species].color, + stats: r.stats + }))} + yLabel="Days between captures" />
-

- Pairs contributed per shark: {g.contributions - .map( - (r) => - `${r.pairs} pair${r.pairs === 1 ? '' : 's'}: ${r.sharks} shark${r.sharks === 1 ? '' : 's'}` - ) - .join('; ')}. +

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

- {:else}

No eligible repeat observations with known scar stages.

{/if} + {: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 index d5f2383..e886f08 100644 --- a/src/lib/server/analytics/scarTransitions.test.ts +++ b/src/lib/server/analytics/scarTransitions.test.ts @@ -31,7 +31,20 @@ it('skips unknown stages but retains backward transitions and per-shark contribu backward: 1, contributions: [{ pairs: 2, sharks: 1 }] }); - expect(r.rows[2].stats?.median).toBe(7); + // 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 = { diff --git a/src/lib/server/analytics/scarTransitions.ts b/src/lib/server/analytics/scarTransitions.ts index ebe48e1..4f6c070 100644 --- a/src/lib/server/analytics/scarTransitions.ts +++ b/src/lib/server/analytics/scarTransitions.ts @@ -3,12 +3,15 @@ import { boxStats } from '#lib/stats'; import { recapturePairs } from './common'; const stages = ['open', 'semi', 'closed']; -export const SCAR_LABELS = ['Open', 'Healing', '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'].map((species) => { + 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 @@ -59,7 +62,7 @@ export function scarTransitions(d: Pick p.id)).size, backward: j < i, - stats: boxStats(ps.map((p) => p.days)) + stats: ps.length >= MIN_BOX_PAIRS ? boxStats(ps.map((p) => p.days)) : null }; }) ); @@ -67,6 +70,7 @@ export function scarTransitions(d: Pick rows.slice(i * 3, i * 3 + 3).map((r) => r.pairs)), pairs: pairs.length, diff --git a/src/routes/neonates/+page.svelte b/src/routes/neonates/+page.svelte index 5a6fcf8..0058f75 100644 --- a/src/routes/neonates/+page.svelte +++ b/src/routes/neonates/+page.svelte @@ -26,7 +26,6 @@ when mothers give birth, and how big pups are when they arrive.

-
+ +