prographs 0.12.0 → 0.13.0

package/dist/charts/fieldcharts/SpeciesAccumulationCurve.js

@@ -0,0 +1,350 @@
+import { CartesianChart } from "../../core/CartesianChart.js";
+import { ChartFamily, DataShape, Dimension } from "../../core/enums.js";
+import { SampleData } from "../../data/SampleData.js";
+import { AccumulationOrder, RarefactionBasis } from "./fieldEnums.js";
+import { FieldKit } from "./FieldKit.js";
+import { RarefactionCurve } from "./RarefactionCurve.js";
+import { area, line, scaleLinear, symbol, symbolDiamond } from "d3";
+// src/charts/fieldcharts/SpeciesAccumulationCurve.ts
+var STEPS = 48;
+var AHEAD = 24;
+var Z = 1.96;
+var diamond = symbol(symbolDiamond, 64)();
+/** Habitats of an invented pitfall-trap survey: species pool and traps set. Most species are rare, so sampling stops short of the pool. */
+var HABITATS = [
+	[
+		"Riparian forest",
+		58,
+		12
+	],
+	[
+		"Upland forest",
+		40,
+		10
+	],
+	[
+		"Pasture",
+		20,
+		8
+	]
+];
+/**
+* Judge whether sampling has found most of the species at a site: species found against effort, as the collector's
+* curve in the order sampled and as the mean over random orders, carried on towards the estimated total richness.
+*/
+var SpeciesAccumulationCurve = class SpeciesAccumulationCurve extends CartesianChart {
+	static meta = {
+		id: "species-accumulation-curve",
+		name: "Species accumulation curve",
+		family: ChartFamily.Statistical,
+		dimension: Dimension.Two,
+		shape: DataShape.Table,
+		description: "Plots species found against sampling effort per site, as sampled and as the randomised mean with its band, extrapolated towards a Chao richness estimate.",
+		tags: [
+			"ecology",
+			"biodiversity",
+			"species richness",
+			"collector curve",
+			"sampling effort",
+			"extrapolation",
+			"chao",
+			"asymptote"
+		],
+		sample: (seed) => {
+			const { u, n } = SampleData.rng(seed);
+			const poisson = (mean) => {
+				let k = 0;
+				for (let p = u(); p > Math.exp(-mean); p *= u()) k++;
+				return k;
+			};
+			return HABITATS.flatMap(([site, pool, traps]) => {
+				const rates = Array.from({ length: pool }, () => Math.exp(n() * 1.5 - 1.7));
+				return Array.from({ length: traps }, (_, j) => rates.flatMap((rate, s) => {
+					const count = poisson(rate);
+					return count > 0 ? [{
+						site,
+						sample: `Trap ${j + 1}`,
+						species: `sp${s + 1}`,
+						count
+					}] : [];
+				})).flat();
+			});
+		},
+		variants: {
+			order: [
+				AccumulationOrder.Both,
+				AccumulationOrder.Collector,
+				AccumulationOrder.Randomised
+			],
+			effort: [RarefactionBasis.Samples, RarefactionBasis.Individuals],
+			extrapolate: [true, false]
+		}
+	};
+	defaults() {
+		return {
+			site: "site",
+			sample: "sample",
+			species: "species",
+			count: "count",
+			order: AccumulationOrder.Both,
+			effort: RarefactionBasis.Samples,
+			extrapolate: true,
+			reach: 2,
+			yLabel: "Species"
+		};
+	}
+	/** Species found so far after each sample, in the order given. Each sample maps a species to the individuals counted. */
+	static collector(samples) {
+		const seen = /* @__PURE__ */ new Set();
+		let individuals = 0;
+		return samples.map((found) => {
+			const before = seen.size;
+			for (const [name, count] of found) {
+				if (count <= 0) continue;
+				seen.add(name);
+				individuals += count;
+			}
+			return {
+				species: seen.size,
+				added: seen.size - before,
+				individuals
+			};
+		});
+	}
+	/** Chao's bias-corrected count of species present but not found, from those found once and twice. `scale` is (T - 1) / T for T samples and 1 for individuals. */
+	static unseen(ones, twos, scale = 1) {
+		return ones > 1 ? scale * ones * (ones - 1) / (2 * (twos + 1)) : 0;
+	}
+	/**
+	* Expected species `extra` units of effort past the `effort` observed, after Colwell et al. (2012): the curve closes
+	* on the Chao estimate at a rate set by the species found once. The variance treats the frequency counts as
+	* multinomial, so it meets the interpolated band at `extra = 0` and grows to that of the estimate itself.
+	*/
+	static extrapolated(observed, ones, twos, effort, extra, scale = 1) {
+		const gain = (q1, q2) => {
+			const missing = SpeciesAccumulationCurve.unseen(q1, q2, scale);
+			return missing > 0 ? missing * (1 - (1 - q1 / (effort * missing + q1)) ** extra) : 0;
+		};
+		const missing = SpeciesAccumulationCurve.unseen(ones, twos, scale), total = observed + missing;
+		if (!(total > 0)) return {
+			s: 0,
+			variance: 0
+		};
+		const h = 1e-4;
+		const d1 = (gain(ones + h, twos) - gain(ones - h, twos)) / (2 * h), d2 = (gain(ones, twos + h) - gain(ones, twos - h)) / (2 * h);
+		const variance = missing * (1 - missing / total) + 2 * missing * (d1 * ones + d2 * twos) / total + d1 * d1 * ones * (1 - ones / total) + d2 * d2 * twos * (1 - twos / total) - 2 * d1 * d2 * ones * twos / total;
+		return {
+			s: observed + gain(ones, twos),
+			variance: Math.max(0, variance)
+		};
+	}
+	get #bySamples() {
+		return this.options.effort !== RarefactionBasis.Individuals;
+	}
+	get #chao() {
+		return this.#bySamples ? "Chao2" : "Chao1";
+	}
+	#curves() {
+		const { data, site, sample, species, count, extrapolate, reach } = this.options;
+		const sites = /* @__PURE__ */ new Map();
+		for (const row of Array.isArray(data) ? data : []) {
+			const value = FieldKit.number(row?.[count]);
+			if (value === null || value < 0) continue;
+			const key = FieldKit.text(row[site]) || "All", unit = FieldKit.text(row[sample]) || "All", name = FieldKit.text(row[species]);
+			const units = sites.get(key) ?? sites.set(key, /* @__PURE__ */ new Map()).get(key);
+			const found = units.get(unit) ?? units.set(unit, /* @__PURE__ */ new Map()).get(unit);
+			if (name && value > 0) found.set(name, (found.get(name) ?? 0) + value);
+		}
+		const bySamples = this.#bySamples, far = extrapolate ? Math.max(1, Number(reach) || 2) : 1;
+		const point = (n, { s, variance }) => {
+			const half = Z * Math.sqrt(variance);
+			return {
+				n,
+				s,
+				low: Math.max(0, s - half),
+				high: s + half
+			};
+		};
+		return [...sites].map(([key, units]) => {
+			const names = [...units.keys()], samples = [...units.values()];
+			const tally = /* @__PURE__ */ new Map();
+			for (const found of samples) for (const [name, value] of found) {
+				const entry = tally.get(name) ?? tally.set(name, {
+					total: 0,
+					units: 0
+				}).get(name);
+				entry.total += value;
+				entry.units++;
+			}
+			const counts = [...tally.values()].map((entry) => bySamples ? entry.units : Math.round(entry.total)).filter((k) => k > 0);
+			const effort = bySamples ? samples.length : counts.reduce((sum, k) => sum + k, 0), observed = counts.length;
+			const ones = counts.filter((k) => k === 1).length, twos = counts.filter((k) => k === 2).length;
+			const scale = bySamples && effort ? (effort - 1) / effort : 1;
+			const estimate = observed + SpeciesAccumulationCurve.unseen(ones, twos, scale);
+			const ahead = (extra) => SpeciesAccumulationCurve.extrapolated(observed, ones, twos, effort, extra, scale);
+			const drawn = [...new Set(Array.from({ length: 49 }, (_, i) => Math.max(1, Math.round(i / STEPS * effort))))];
+			const half = Z * Math.sqrt(ahead(Infinity).variance);
+			return {
+				site: key,
+				observed,
+				estimate,
+				effort,
+				ceiling: [Math.max(observed, estimate - half), estimate + half],
+				steps: SpeciesAccumulationCurve.collector(samples).map((step, i) => ({
+					...step,
+					key: `${key}\u0000${i}`,
+					site: key,
+					sample: names[i],
+					effort: bySamples ? i + 1 : step.individuals
+				})),
+				mean: effort > 0 ? drawn.map((n) => point(n, RarefactionCurve.samples(counts, effort, n, estimate))) : [],
+				beyond: far > 1 ? Array.from({ length: 25 }, (_, i) => point(effort * (1 + i / AHEAD * (far - 1)), ahead(i / AHEAD * (far - 1) * effort))) : []
+			};
+		}).filter((curve) => curve.effort > 0);
+	}
+	get #collected() {
+		return this.options.order !== AccumulationOrder.Randomised;
+	}
+	get #averaged() {
+		return this.options.order !== AccumulationOrder.Collector;
+	}
+	#label(curve) {
+		return `${this.#chao} ${curve.estimate.toFixed(1)}`;
+	}
+	/** Room on the right for the richness estimates the extrapolation is marked with. */
+	plotMargin() {
+		const margin = super.plotMargin(), marked = this.#curves().filter((curve) => curve.beyond.length);
+		return marked.length ? {
+			...margin,
+			right: 16 + Math.max(...marked.map((curve) => FieldKit.width(this.#label(curve), 10)))
+		} : margin;
+	}
+	scales(ctx) {
+		const curves = this.#curves();
+		const far = Math.max(1, ...curves.map((curve) => curve.beyond.at(-1)?.n ?? curve.effort));
+		const top = Math.max(1, ...curves.flatMap((curve) => [
+			curve.observed,
+			...this.#averaged ? curve.mean.map((p) => p.high) : [],
+			...curve.beyond.map((p) => p.high),
+			...curve.beyond.length ? [curve.estimate] : []
+		]));
+		return {
+			x: scaleLinear([0, far], [0, ctx.plot.width]).nice(),
+			y: scaleLinear([0, top * 1.05], [ctx.plot.height, 0]).nice()
+		};
+	}
+	plotMarks(ctx, { x, y }) {
+		const curves = this.#curves(), { width, height } = ctx.plot;
+		const sx = (n) => x(n) ?? 0, sy = (s) => y(s) ?? 0;
+		const tone = (d) => ctx.palette.color(d.site);
+		const unit = this.#bySamples ? "Samples" : "Individuals", chao = this.#chao;
+		const averaged = this.#averaged ? curves : [], ahead = curves.filter((curve) => curve.beyond.length);
+		const summary = (d) => [
+			["Observed species", d.observed],
+			[unit, d.effort],
+			[`${chao} estimate`, d.estimate.toFixed(1)]
+		];
+		const band = area().x((p) => sx(p.n)).y0((p) => sy(p.low)).y1((p) => sy(p.high));
+		const bands = ctx.marks("intervals", "path", averaged, (d) => d.site).attr("fill", tone).attr("fill-opacity", .16).attr("stroke", "none").attr("pointer-events", "none");
+		ctx.set(bands, { d: (d) => band(d.mean) ?? "" });
+		const cones = ctx.marks("extrapolated-intervals", "path", ahead, (d) => d.site).attr("fill", tone).attr("fill-opacity", .1).attr("stroke", "none").attr("pointer-events", "none");
+		ctx.set(cones, { d: (d) => band(d.beyond) ?? "" });
+		const trace = line().x((p) => sx(p.n)).y((p) => sy(p.s));
+		const dashed = ctx.marks("extrapolated", "path", ahead, (d) => d.site).attr("fill", "none").attr("stroke", tone).attr("stroke-width", 2).attr("stroke-dasharray", "6 4");
+		ctx.set(dashed, { d: (d) => trace(d.beyond) ?? "" });
+		ctx.hover(dashed, (d) => {
+			const end = d.beyond.at(-1);
+			return {
+				title: `${d.site}, extrapolated`,
+				color: tone(d),
+				rows: [
+					[`Expected at ${Math.round(end.n)} ${unit.toLowerCase()}`, end.s.toFixed(1)],
+					["95% interval", `${end.low.toFixed(1)} to ${end.high.toFixed(1)}`],
+					...summary(d)
+				]
+			};
+		});
+		const means = ctx.marks("curves", "path", averaged, (d) => d.site).attr("fill", "none").attr("stroke", tone).attr("stroke-width", 2).attr("stroke-linejoin", "round");
+		ctx.set(means, { d: (d) => trace(d.mean) ?? "" });
+		ctx.drawOn(means);
+		ctx.hover(means, (d) => ({
+			title: `${d.site}, randomised mean`,
+			color: tone(d),
+			rows: summary(d)
+		}));
+		const collected = this.#collected ? curves : [];
+		const walk = line().x((step) => sx(step.effort)).y((step) => sy(step.species));
+		const walks = ctx.marks("collector", "path", collected, (d) => d.site).attr("fill", "none").attr("stroke", tone).attr("stroke-width", this.#averaged ? 1.5 : 2).attr("stroke-linejoin", "round");
+		ctx.set(walks, { d: (d) => walk(d.steps) ?? "" });
+		ctx.hover(walks, (d) => ({
+			title: `${d.site}, as sampled`,
+			color: tone(d),
+			rows: summary(d)
+		}));
+		const roomy = collected.every((curve) => (sx(curve.steps.at(-1).effort) - sx(curve.steps[0].effort)) / curve.steps.length >= 12);
+		const dots = ctx.marks("samples", "circle", roomy ? collected.flatMap((curve) => curve.steps.slice(0, -1)) : [], (step) => step.key).attr("fill", tone).attr("stroke", ctx.theme.surface).attr("stroke-width", 1.5);
+		ctx.set(dots, {
+			cx: (step) => sx(step.effort),
+			cy: (step) => sy(step.species),
+			r: 4
+		}, { r: 0 });
+		ctx.hover(dots, (step) => ({
+			title: `${step.site}, ${step.sample}`,
+			color: tone(step),
+			rows: [
+				["Species so far", step.species],
+				["New in this sample", step.added],
+				[unit, this.#bySamples ? step.effort : Math.round(step.effort)]
+			]
+		}));
+		const ends = ctx.marks("observed", "circle", curves, (d) => d.site).attr("fill", tone).attr("stroke", ctx.theme.surface).attr("stroke-width", 2);
+		ctx.set(ends, {
+			cx: (d) => sx(d.effort),
+			cy: (d) => sy(d.observed),
+			r: 5
+		}, { r: 0 });
+		ctx.hover(ends, (d) => ({
+			title: d.site,
+			color: tone(d),
+			rows: summary(d)
+		}));
+		const place = (d) => `translate(${width},${sy(d.estimate)})`;
+		const marks = ctx.marks("estimates", "path", ahead, (d) => d.site).attr("d", diamond).attr("fill", tone).attr("stroke", ctx.theme.surface).attr("stroke-width", 2).attr("paint-order", "stroke");
+		ctx.set(marks, { transform: place }, { transform: place });
+		ctx.hover(marks, (d) => ({
+			title: d.site,
+			color: tone(d),
+			rows: [
+				[`${chao} estimate`, d.estimate.toFixed(1)],
+				["95% interval", `${d.ceiling[0].toFixed(1)} to ${d.ceiling[1].toFixed(1)}`],
+				["Observed species", d.observed],
+				["Share found", `${Math.round(100 * d.observed / Math.max(d.estimate, 1e-9))}%`]
+			]
+		}));
+		const stacked = [...ahead].sort((a, b) => a.estimate - b.estimate).map((curve) => ({
+			curve,
+			at: sy(curve.estimate) + 3.5
+		}));
+		stacked.forEach((label, i) => {
+			if (i) label.at = Math.min(label.at, stacked[i - 1].at - 11);
+		});
+		const lift = Math.max(0, 9 - (stacked.at(-1)?.at ?? height));
+		const names = ctx.text(ctx.marks("estimate-labels", "text", stacked, (d) => d.curve.site), 10).attr("pointer-events", "none").text((d) => this.#label(d.curve));
+		ctx.set(names, {
+			x: width + 9,
+			y: (d) => d.at + lift
+		}, {
+			x: width + 9,
+			y: (d) => d.at + lift
+		});
+	}
+	/** The x title names the effort unless the caller set their own. */
+	paint() {
+		const title = this.#bySamples ? "Samples taken" : "Individuals counted";
+		if (this.options.xLabel === void 0 || this.options.xLabel === this.#title) this.options.xLabel = title;
+		this.#title = title;
+		super.paint();
+	}
+	#title = "";
+};
+export { SpeciesAccumulationCurve };

package/dist/charts/fieldcharts/fieldEnums.js

@@ -48,6 +48,13 @@ var RarefactionBasis = /* @__PURE__ */ function(RarefactionBasis) {
 	RarefactionBasis["Samples"] = "samples";
 	return RarefactionBasis;
 }({});
+/** Samples added in the order they were taken (the collector's curve), averaged over every order, or both. */
+var AccumulationOrder = /* @__PURE__ */ function(AccumulationOrder) {
+	AccumulationOrder["Collector"] = "collector";
+	AccumulationOrder["Randomised"] = "randomised";
+	AccumulationOrder["Both"] = "collector-and-randomised";
+	return AccumulationOrder;
+}({});
 /** One abundance scale for every species, or each species scaled to its own peak. */
 var KiteScaling = /* @__PURE__ */ function(KiteScaling) {
 	KiteScaling["Shared"] = "shared";
@@ -71,4 +78,4 @@ var KobePath = /* @__PURE__ */ function(KobePath) {
 	KobePath["Terminal"] = "terminal";
 	return KobePath;
 }({});
-export { ConcordiaMarks, ConcordiaProjection, FieldSamples, FieldStyle, KiteScaling, KobePath, PollenStyle, PollenWidth, QapfRocks, RarefactionBasis, SpiderDisplay, SpiderNormaliser };
+export { AccumulationOrder, ConcordiaMarks, ConcordiaProjection, FieldSamples, FieldStyle, KiteScaling, KobePath, PollenStyle, PollenWidth, QapfRocks, RarefactionBasis, SpiderDisplay, SpiderNormaliser };

package/dist/charts/fieldcharts/index.js

@@ -1,4 +1,4 @@
-import { ConcordiaMarks, ConcordiaProjection, FieldSamples, FieldStyle, KiteScaling, KobePath, PollenStyle, PollenWidth, QapfRocks, RarefactionBasis, SpiderDisplay, SpiderNormaliser } from "./fieldEnums.js";
+import { AccumulationOrder, ConcordiaMarks, ConcordiaProjection, FieldSamples, FieldStyle, KiteScaling, KobePath, PollenStyle, PollenWidth, QapfRocks, RarefactionBasis, SpiderDisplay, SpiderNormaliser } from "./fieldEnums.js";
 import { FieldKit } from "./FieldKit.js";
 import { ConcordiaDiagram } from "./ConcordiaDiagram.js";
 import { KiteDiagram } from "./KiteDiagram.js";
@@ -6,6 +6,7 @@ import { KobePlot } from "./KobePlot.js";
 import { PollenDiagram } from "./PollenDiagram.js";
 import { QapfDiagram } from "./QapfDiagram.js";
 import { RarefactionCurve } from "./RarefactionCurve.js";
+import { SpeciesAccumulationCurve } from "./SpeciesAccumulationCurve.js";
 import { SpiderDiagram } from "./SpiderDiagram.js";
 import { FieldDiagram } from "./FieldDiagram.js";
 import { TasDiagram } from "./TasDiagram.js";
@@ -20,6 +21,7 @@ var fieldchartsCatalog = [
 	KiteDiagram,
 	PollenDiagram,
 	WhittakerBiomeDiagram,
-	KobePlot
+	KobePlot,
+	SpeciesAccumulationCurve
 ];
-export { ConcordiaDiagram, ConcordiaMarks, ConcordiaProjection, FieldDiagram, FieldKit, FieldSamples, FieldStyle, KiteDiagram, KiteScaling, KobePath, KobePlot, PollenDiagram, PollenStyle, PollenWidth, QapfDiagram, QapfRocks, RarefactionBasis, RarefactionCurve, SpiderDiagram, SpiderDisplay, SpiderNormaliser, TasDiagram, WhittakerBiomeDiagram, fieldchartsCatalog };
+export { AccumulationOrder, ConcordiaDiagram, ConcordiaMarks, ConcordiaProjection, FieldDiagram, FieldKit, FieldSamples, FieldStyle, KiteDiagram, KiteScaling, KobePath, KobePlot, PollenDiagram, PollenStyle, PollenWidth, QapfDiagram, QapfRocks, RarefactionBasis, RarefactionCurve, SpeciesAccumulationCurve, SpiderDiagram, SpiderDisplay, SpiderNormaliser, TasDiagram, WhittakerBiomeDiagram, fieldchartsCatalog };