Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,7 @@ src/lib/server/analytics common.ts (CPUE, Fulton's K, recapture pairs…) · env
events.ts (cyclones and heavy-rain days vs catches)
glm.ts (NB/Poisson GLM, splines) · catchModel.ts (joint catch model)
glmm.ts (binomial mixed model, crossed random intercepts) · sex.ts
tests.ts (the statistic behind each chart, worded for ChartCard stats)
src/lib/server/astro.ts sunset/twilight/moon (local formulas) · tides.ts (extrema, interpolation)
src/lib/server/holidays.ts French Polynesia public holidays (Easter-based too), festive window,
school holidays (schoolDays) and the one-label-per-date dayType
Expand Down Expand Up @@ -121,6 +122,7 @@ Drop the workbook in `data/` named like `Physioshark_Shark Log 2026-2027.xlsx` (

- Follow the dataviz method: categorical slots in fixed order (`--series-1…8`, validated light and dark), sequential = one hue (`--seq-*`), diverging = blue ↔ red with a neutral midpoint, one y-axis only (never dual axes), legends for ≥ 2 series, text in ink tokens (never the series colour), 4 px rounded bar ends, 2 px lines, hover tooltips, data tables via `ChartCard table`.
- Every chart registers its data with the enclosing `ChartCard` (`registerCsv` in `charts/csv.ts`), which shows **Download CSV**. A new chart component must call `registerCsv` too. An explicit `ChartCard table` takes precedence.
- Back every trend, relationship or group difference with a test (#119): compute it in the load function with `analytics/tests.ts` and pass the sentence to `ChartCard stats`. Catch rates: `rateTest`/`rateText` (negative-binomial LRT with log net-hours offset, raw and adjusted for nursery, season and day of the season; pass `skip` for the factor under test). Values across groups: `groupsText` (Kruskal–Wallis). Shares: `tableText` (χ²). One value per season: `trendText`. Scatters: `fitText` (R², p, Spearman) or `rankText`. Copy and findings that name a "best" or "highest" group must check the test first (the moon finding picked the best of eight phases, #118).
- Cite the study behind a chart with `<ChartCard papers={['debaere2024lunar']}>` (ids in `src/lib/publications.ts`). Link only papers that analysed the same question with this dataset; check the abstract first. PDFs are served at `rummerlab.com/papers/<file>` (metadata in the rummerlab-website repo, `data/papers.json`).
- Species colours come from `src/lib/species.ts` (blacktip = slot 1, sicklefin lemon = slot 2).
- Charts measure their width (`bind:clientWidth`) and carry a `viewBox` so pre-hydration renders scale down instead of overflowing.
Expand Down
26 changes: 26 additions & 0 deletions src/lib/components/ChartCard.svelte
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@
title,
subtitle,
note,
stats,
source,
id,
table,
Expand All @@ -17,6 +18,8 @@
title: string;
subtitle?: string;
note?: string;
/** The test behind the chart's pattern (#119); nulls (too little data) are skipped. */
stats?: string | null | (string | null | undefined)[];
source?: string;
id?: string;
table?: { columns: Column[]; rows: Record<string, unknown>[] };
Expand All @@ -25,6 +28,10 @@
children: Snippet;
} = $props();

const statLines = $derived(
(Array.isArray(stats) ? stats : [stats]).filter((x): x is string => !!x)
);

// Charts inside the card register their data; the button needs JS, so it appears on mount.
const sources = collectCsv();
let canDownload = $state(false);
Expand Down Expand Up @@ -58,6 +65,9 @@
</figcaption>
<div class="body">{@render children()}</div>
{#if note}<p class="note">{note}</p>{/if}
{#if statLines.length}
<p class="stats"><span class="k">Statistics</span> {statLines.join(' ')}</p>
{/if}
{#if table && table.rows.length}
<details class="tbl">
<summary>Show data ({table.rows.length} rows)</summary>
Expand Down Expand Up @@ -107,6 +117,22 @@
margin: 10px 0 0;
line-height: 1.5;
}
.stats {
font-size: 0.82rem;
color: var(--ink-2);
margin: 8px 0 0;
line-height: 1.5;
font-variant-numeric: tabular-nums;
}
.stats .k {
display: inline-block;
font-size: 0.7rem;
font-weight: 650;
letter-spacing: 0.06em;
text-transform: uppercase;
color: var(--accent);
margin-right: 4px;
}
.papers {
font-size: 0.78rem;
color: var(--ink-2);
Expand Down
64 changes: 46 additions & 18 deletions src/lib/server/analytics/findings.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
* Auto-generated findings (#55): records, quirks and patterns computed live from the data, so
* they update when a new season's workbook is added. Each links to the page with the chart.
*/
import { clock, date, num, pct, season as seasonFmt } from '#lib/format';
import { clock, date, num, pct, pValue, season as seasonFmt } from '#lib/format';
import { speciesName } from '#lib/species';
import { binomTestHalf, mean, median, pairs, spearman } from '#lib/stats';
import { moonPhaseName } from '../astro';
Expand All @@ -23,6 +23,7 @@ import { cloudWater } from './cloud';
import { diet } from './diet';
import { dailyMaxBySite, versusSst } from './insitu';
import { sexModel } from './sex';
import { rateTest } from './tests';

export interface Finding {
id: string;
Expand Down Expand Up @@ -72,23 +73,39 @@ function compute(d: Dataset): Finding[] {
});
}

// Moon phase
const phases = Array.from({ length: 8 }, (_, i) =>
eff.filter((s) => s.moonPhase != null && Math.round(s.moonPhase * 8) % 8 === i)
);
// Moon phase (#118): name a best phase only if the phases differ beyond chance. Picking the
// highest of eight raw rates always finds a "best" one.
const phaseOf = (s: (typeof eff)[number]) =>
s.moonPhase == null ? null : Math.round(s.moonPhase * 8) % 8;
const phases = Array.from({ length: 8 }, (_, i) => eff.filter((s) => phaseOf(s) === i));
const phaseCpue = phases.map((p) => ({ n: p.length, cpue: cpueOf(p) }));
const valid = phaseCpue.map((p, i) => ({ ...p, i })).filter((p) => p.n >= 25 && p.cpue != null);
if (valid.length >= 4) {
const moonTest = rateTest(eff, { groupOf: phaseOf });
if (valid.length >= 4 && moonTest) {
const best = valid.reduce((a, b) => (b.cpue! > a.cpue! ? b : a));
const worst = valid.reduce((a, b) => (b.cpue! < a.cpue! ? b : a));
out.push({
id: 'moon',
kind: 'pattern',
title: 'Best moon for finding pups',
value: moonPhaseName(best.i / 8),
text: `Nets set around the ${moonPhaseName(best.i / 8).toLowerCase()} caught ${num(best.cpue!, 2)} sharks per net-hour, against ${num(worst.cpue!, 2)} around the ${moonPhaseName(worst.i / 8).toLowerCase()} (${best.n} and ${worst.n} sets).`,
href: '/moon'
});
const p = moonTest.adjusted?.p ?? moonTest.raw.p;
const test = `negative-binomial test across all eight phases, adjusted for ${moonTest.adjustedFor}: ${pValue(p)}, ${num(moonTest.n)} sets`;
const phase = (i: number) => moonPhaseName(i / 8).toLowerCase();
out.push(
p < 0.05
? {
id: 'moon',
kind: 'pattern',
title: 'Best moon for finding pups',
value: moonPhaseName(best.i / 8),
text: `Nets set around the ${phase(best.i)} caught ${num(best.cpue!, 2)} sharks per net-hour, against ${num(worst.cpue!, 2)} around the ${phase(worst.i)}; the phases differ beyond chance (${test}).`,
href: '/moon'
}
: {
id: 'moon',
kind: 'pattern',
title: "The moon doesn't change the catch",
value: 'No effect',
text: `The ${phase(best.i)} (${num(best.cpue!, 2)} sharks per net-hour) and the ${phase(worst.i)} (${num(worst.cpue!, 2)}) look different, but across all eight phases the spread is what chance alone produces (${test}). Debaere et al. (2024) reached the same conclusion with this dataset.`,
href: '/moon'
}
);
}

// Timing after sunset
Expand Down Expand Up @@ -217,14 +234,20 @@ function compute(d: Dataset): Finding[] {
cm: cpueOf(x.sets, 'cpueCm')!
}));
if (siteCpue.length) {
const nurseryTest = rateTest(
eff.filter((s) => siteCpue.some((x) => x.id === s.siteId)),
{ groupOf: (s) => s.siteId },
'cpue',
['nursery']
);
const top = siteCpue.reduce((a, b) => (b.cpue > a.cpue ? b : a));
const low = siteCpue.reduce((a, b) => (b.cpue < a.cpue ? b : a));
out.push({
id: 'best-nursery',
kind: 'pattern',
title: 'Most productive nursery',
value: siteName(d, top.id),
text: `${num(top.cpue, 2)} sharks per net-hour on average, ${num(top.cpue / low.cpue, 1)}× the rate at ${siteName(d, low.id)} (${num(low.cpue, 2)}).`,
text: `${num(top.cpue, 2)} sharks per net-hour on average, ${num(top.cpue / low.cpue, 1)}× the rate at ${siteName(d, low.id)} (${num(low.cpue, 2)}).${nurseryTest ? ` Nurseries differ ${(nurseryTest.adjusted?.p ?? nurseryTest.raw.p) < 0.05 ? 'well beyond' : 'no more than'} chance (negative-binomial test, adjusted for ${nurseryTest.adjustedFor}: ${pValue(nurseryTest.adjusted?.p ?? nurseryTest.raw.p)}).` : ''}`,
href: `/nurseries/${top.id}`
});
const lemon = siteCpue.reduce((a, b) => (b.na / (b.cpue || 1) > a.na / (a.cpue || 1) ? b : a));
Expand Down Expand Up @@ -360,15 +383,20 @@ function compute(d: Dataset): Finding[] {
const wk = eff.filter((s) => s.weekday != null);
const weekend = cpueOf(wk.filter((s) => s.weekday === 0 || s.weekday === 6));
const weekday = cpueOf(wk.filter((s) => s.weekday !== 0 && s.weekday !== 6));
if (weekend != null && weekday != null)
const weekendTest = rateTest(wk, {
groupOf: (s) => (s.weekday === 0 || s.weekday === 6 ? 'weekend' : 'weekday')
});
if (weekend != null && weekday != null && weekendTest) {
const p = weekendTest.adjusted?.p ?? weekendTest.raw.p;
out.push({
id: 'weekend',
kind: 'quirk',
title: 'Weekend effect?',
value: `${num(weekend, 2)} vs ${num(weekday, 2)}`,
text: `Sharks per net-hour on weekend nights against weeknights. Weekends bring more people to the beaches; ${weekend < weekday ? 'catches are a little lower then' : 'catches are no lower then'}.`,
text: `Sharks per net-hour on weekend nights against weeknights. Weekends bring more people to the beaches, but ${p < 0.05 ? `catches really are ${weekend < weekday ? 'lower' : 'higher'} then` : 'the gap is within chance'} (negative-binomial test adjusted for ${weekendTest.adjustedFor}: ${pValue(p)}).`,
href: '/drivers'
});
}

// Strongest driver
const vars: [string, keyof (typeof eff)[number]][] = [
Expand Down Expand Up @@ -472,7 +500,7 @@ function compute(d: Dataset): Finding[] {
kind: 'pattern',
title: 'Heat stress and newborn condition',
value: `ρ = ${num(kr.rho, 2)}`,
text: `Correlation between Coral Reef Watch degree heating weeks on the capture date and the body condition (Fulton's K) of newborn blacktips (n = ${num(kr.n)}).`,
text: `Correlation between Coral Reef Watch degree heating weeks on the capture date and the body condition (Fulton's K) of newborn blacktips (n = ${num(kr.n)}, ${pValue(kr.p)}${kr.p < 0.05 ? '' : ': no more than chance'}).`,
href: '/ocean'
});

Expand Down
101 changes: 101 additions & 0 deletions src/lib/server/analytics/tests.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,101 @@
import { describe, expect, it } from 'vitest';
import type { SetRow } from '../data';
import { groupsText, rateEffects, rateTest, rateText, tableText, trendText } from './tests';

/** Seeded uniform draws (mulberry32). */
function rng(seed: number) {
let a = seed;
return () => {
a = (a + 0x6d2b79f5) | 0;
let t = Math.imul(a ^ (a >>> 15), 1 | a);
t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
};
}

/** Poisson draw by inversion (small means). */
function poisson(u: () => number, mu: number) {
let k = 0;
let p = Math.exp(-mu);
let s = p;
const x = u();
while (x > s && k < 200) {
k++;
p *= mu / k;
s += p;
}
return k;
}

/** Synthetic timed sets: two nurseries, three seasons, a group factor with given rate ratios. */
function sets(seed: number, ratio: Record<string, number>): SetRow[] {
const u = rng(seed);
const groups = Object.keys(ratio);
return Array.from({ length: 600 }, (_, i) => {
// Blocks of seven so groups don't line up with nursery (i % 2) or season (i % 3).
const g = groups[Math.floor(i / 7) % groups.length];
const hours = 1.5 + u();
const n = poisson(u, 0.8 * hours * ratio[g]);
const month = ['10', '11', '12', '01'][i % 4];
const year = month === '01' ? 2020 : 2019;
return {
id: i,
season: ['2019-2020', '2020-2021', '2021-2022'][i % 3],
siteId: i % 2 ? 'a' : 'b',
date: `${year + (i % 3)}-${month}-${String(1 + (i % 27)).padStart(2, '0')}`,
durationMin: hours * 60,
nTotal: n,
cpue: n / hours,
cpueCm: n / hours,
cpueNa: 0,
group: g
} as unknown as SetRow;
});
}
const groupOf = (s: SetRow) => (s as unknown as { group: string }).group;

describe('chart statistics (#119)', () => {
it('finds a real catch-rate difference between groups and names the adjustment', () => {
const t = rateTest(sets(3, { x: 1, y: 2 }), { groupOf })!;
expect(t.df).toBe(1);
expect(t.raw.p).toBeLessThan(0.001);
expect(t.adjusted!.p).toBeLessThan(0.001);
expect(t.adjustedFor).toBe('nursery, season and day of the season');
expect(rateText(t, 'groups')).toMatch(/^Catch rates differ between groups/);
const fx = rateEffects(sets(3, { x: 1, y: 2 }), groupOf)!;
expect(fx[1].rr / fx[0].rr).toBeGreaterThan(1.6);
expect(fx[1].rr / fx[0].rr).toBeLessThan(2.5);
});

it('does not invent a difference, and skips the adjustment being tested', () => {
const t = rateTest(sets(5, { x: 1, y: 1, z: 1 }), { groupOf }, 'cpue', ['nursery'])!;
expect(t.adjusted!.p).toBeGreaterThan(0.05);
expect(t.adjustedFor).toBe('season and day of the season');
expect(rateText(t, 'groups')).toMatch(/^No detectable difference/);
});

it('words trends, rank tests and tables', () => {
expect(trendText([1, 2, 3, 4, 5, 6], 'mm')).toMatch(
/^Trend across 6 seasons: \+1\.0 mm per season \(R² = 1\.00/
);
expect(trendText([1, null, 2], 'mm')).toBeNull();
expect(
groupsText(
[
[1, 2, 3, 4],
[11, 12, 13, 14]
],
'groups'
)
).toMatch(/^Differs between groups \(Kruskal–Wallis H = 5\.3, df = 1/);
expect(
tableText(
[
[10, 20],
[20, 10]
],
'groups'
)
).toBe('Differs between groups (χ²(1) = 6.7, p = 0.010).');
});
});
Loading
Loading