linked-rolls 0.70.0 → 0.72.0

package/lib/analysis/witnesses.js

@@ -38,6 +38,7 @@ const carriersIn = perState((edition) => {
  * the latest state it bears. A version left out is reached only through
  * the versions derived from it, or is attested by statement alone, and
  * its text is a reconstruction rather than a reading.
+ * @category Analysis
  */
 export const attestedVersions = (edition) => new Set(carriersIn(edition).latestOf.values());
 const witnessesIn = (carriers, edition, versionId) => {
@@ -74,11 +75,13 @@ const witnessesIn = (carriers, edition, versionId) => {
  * A statement is the editor's own about the version it names and is
  * reported as it stands. A version whose edits are not stated inserts
  * nothing and is witnessed by statement alone.
+ * @category Analysis
  */
 export const witnessesOf = (edition, versionId) => versionIn(edition, versionId) ? witnessesIn(carriersIn(edition), edition, versionId) : [];
 /**
  * The versions the copy bears witness to, each with how, in the order the
  * edition lists its versions.
+ * @category Analysis
  */
 export const versionsWitnessedBy = (edition, copyId) => {
     const carriers = carriersIn(edition);
@@ -90,6 +93,7 @@ export const versionsWitnessedBy = (edition, copyId) => {
  * Where a copy's statement that it carries a version cannot stand: one
  * made although the copy's features carry symbols, which say by
  * themselves what it carries, and one naming a version the edition lacks.
+ * @category Analysis
  */
 export const carriageProblems = (edition) => {
     const carrying = copiesCarrying(edition, edition.versions.flatMap(insertedBy));

package/lib/collation/Collation.d.ts

@@ -2,12 +2,18 @@ import { Edit } from "../model/Edit.js";
 import { HorizontalSpan } from "../model/Feature.js";
 import { AnySymbol } from "../model/Symbol.js";
 import { Millimeters } from "../model/Quantity.js";
-/** A value taken at each end of a feature: where it begins and where it stops. */
+/**
+ * A value taken at each end of a feature: where it begins and where it stops.
+ * @category Collation and alignment
+ */
 export interface BothEnds<T> {
     from: T;
     to: T;
 }
-/** How far one text puts a feature from where another puts it, at either end. */
+/**
+ * How far one text puts a feature from where another puts it, at either end.
+ * @category Collation and alignment
+ */
 export type Displacement = BothEnds<Millimeters>;
 /**
  * The window two readings of one feature must fall in to be collated:
@@ -21,6 +27,7 @@ export type Displacement = BothEnds<Millimeters>;
  * tolerance stand for the scatter only. A window that names none is
  * centred on nothing, which is what every window written before the
  * offset was held here means.
+ * @category Format types
  */
 export interface CollationTolerance {
     /** How far the two readings may lie apart at the start of a feature, measured from `offsetStart`. */
@@ -43,10 +50,21 @@ export interface CollationTolerance {
     /** The same at the end of a feature, in the same direction. */
     offsetEnd?: Millimeters;
 }
+/**
+ * The window a derivation that states none is collated at: five
+ * millimetres at either end, centred on nothing.
+ * @category Collation and alignment
+ */
 export declare const defaultCollationTolerance: CollationTolerance;
-/** Where the window is centred at the start of a feature, on nothing where it names no offset. */
+/**
+ * Where the window is centred at the start of a feature, on nothing where it names no offset.
+ * @category Collation and alignment
+ */
 export declare const offsetStartOf: (tolerance: CollationTolerance) => Millimeters;
-/** Where the window is centred at the end of a feature. */
+/**
+ * Where the window is centred at the end of a feature.
+ * @category Collation and alignment
+ */
 export declare const offsetEndOf: (tolerance: CollationTolerance) => Millimeters;
 /**
  * Whether the window admits the displacement at each end, taken apart.
@@ -67,23 +85,39 @@ export declare const offsetEndOf: (tolerance: CollationTolerance) => Millimeters
  * report something other than the punched slot, as a pneumatic reader
  * reports how long a valve stayed open. Long held notes are where the
  * second is likeliest, since that is where the chains are.
+ * @category Collation and alignment
  */
 export declare const admittedAtEnds: (tolerance: CollationTolerance, displacement: Displacement) => BothEnds<boolean>;
-/** Whether the window admits the displacement: within the tolerance of the offset, at both ends. */
+/**
+ * Whether the window admits the displacement: within the tolerance of the offset, at both ends.
+ * @category Collation and alignment
+ */
 export declare const admits: (tolerance: CollationTolerance, displacement: Displacement) => boolean;
-/** Where a symbol lies along the roll, as its carriers put it, or nothing for a symbol without a place. */
+/**
+ * Where a symbol lies along the roll, as its carriers put it, or nothing for a symbol without a place.
+ * @category Collation and alignment
+ */
 export type Locate = (symbol: AnySymbol) => Readonly<HorizontalSpan> | undefined;
 /**
  * Two symbols collate when they are of one kind, say the same thing
  * (pitch, or expression type and scope), and lie at about the same
  * place along the roll.
+ * @category Collation and alignment
  */
 export declare const isCollatable: (a: AnySymbol, b: AnySymbol, locate: Locate, tolerance?: CollationTolerance) => boolean;
+/**
+ * One of a version's own symbols together with an inherited symbol it
+ * collates with, as `collationsOf` pairs them.
+ * @category Collation and alignment
+ */
 export type Collation = {
     symbol: Readonly<AnySymbol>;
     counterpart: Readonly<AnySymbol>;
 };
-/** Each of the own symbols with every inherited symbol it collates with, both in the order given. */
+/**
+ * Each of the own symbols with every inherited symbol it collates with, both in the order given.
+ * @category Collation and alignment
+ */
 export declare const collationsOf: (own: readonly Readonly<AnySymbol>[], inherited: readonly Readonly<AnySymbol>[], locate: Locate, tolerance?: CollationTolerance) => Collation[];
 /**
  * The motivation a collation writes on what it makes, saying that
@@ -98,9 +132,13 @@ export declare const collationsOf: (own: readonly Readonly<AnySymbol>[], inherit
  * It does not make an edit the editor's. `isCollationsOwn` passes over
  * this motivation exactly, so a collation rewrites what it marked
  * before, and only what somebody has actually written stays.
+ * @category Collation and alignment
  */
 export declare const unchecked = "unchecked";
-/** The version's statement of what the unchecked motivation means, to stand in its `motivations`. */
+/**
+ * The version's statement of what the unchecked motivation means, to stand in its `motivations`.
+ * @category Collation and alignment
+ */
 export declare const uncheckedMotivation: {
     readonly type: 'motivation';
     readonly id: "unchecked";
@@ -126,5 +164,6 @@ export declare const uncheckedMotivation: {
  * A recoding that only inserts or only deletes is the editor's: a
  * collation types no one-sided edit, so one typed so is a reading of
  * the transfer that collating again must not undo.
+ * @category Collation and alignment
  */
 export declare const isCollationsOwn: (edit: Readonly<Edit>) => boolean;

package/lib/collation/Collation.js

@@ -2,10 +2,21 @@ import { keyOf } from "../systems/TrackerBar.js";
 import { distance, mm } from "../model/Quantity.js";
 import { partitionPoint } from "../shared/sorted.js";
 import { groupBy } from "../shared/utils.js";
+/**
+ * The window a derivation that states none is collated at: five
+ * millimetres at either end, centred on nothing.
+ * @category Collation and alignment
+ */
 export const defaultCollationTolerance = { toleranceStart: mm(5), toleranceEnd: mm(5) };
-/** Where the window is centred at the start of a feature, on nothing where it names no offset. */
+/**
+ * Where the window is centred at the start of a feature, on nothing where it names no offset.
+ * @category Collation and alignment
+ */
 export const offsetStartOf = (tolerance) => tolerance.offsetStart ?? mm(0);
-/** Where the window is centred at the end of a feature. */
+/**
+ * Where the window is centred at the end of a feature.
+ * @category Collation and alignment
+ */
 export const offsetEndOf = (tolerance) => tolerance.offsetEnd ?? mm(0);
 /**
  * Whether the window admits the displacement at each end, taken apart.
@@ -26,12 +37,16 @@ export const offsetEndOf = (tolerance) => tolerance.offsetEnd ?? mm(0);
  * report something other than the punched slot, as a pneumatic reader
  * reports how long a valve stayed open. Long held notes are where the
  * second is likeliest, since that is where the chains are.
+ * @category Collation and alignment
  */
 export const admittedAtEnds = (tolerance, displacement) => ({
     from: distance(displacement.from, offsetStartOf(tolerance)) <= tolerance.toleranceStart,
     to: distance(displacement.to, offsetEndOf(tolerance)) <= tolerance.toleranceEnd
 });
-/** Whether the window admits the displacement: within the tolerance of the offset, at both ends. */
+/**
+ * Whether the window admits the displacement: within the tolerance of the offset, at both ends.
+ * @category Collation and alignment
+ */
 export const admits = (tolerance, displacement) => {
     const ends = admittedAtEnds(tolerance, displacement);
     return ends.from && ends.to;
@@ -50,6 +65,7 @@ const nearby = (here, there, tolerance) => admits(tolerance, displacementBetween
  * Two symbols collate when they are of one kind, say the same thing
  * (pitch, or expression type and scope), and lie at about the same
  * place along the roll.
+ * @category Collation and alignment
  */
 export const isCollatable = (a, b, locate, tolerance = defaultCollationTolerance) => {
     if (kindOf(a) !== kindOf(b))
@@ -79,7 +95,10 @@ const nearOnsetOf = (kind, span, tolerance) => {
     const end = partitionPoint(kind, candidate => candidate.horizontal.from <= highest);
     return kind.slice(first, end);
 };
-/** Each of the own symbols with every inherited symbol it collates with, both in the order given. */
+/**
+ * Each of the own symbols with every inherited symbol it collates with, both in the order given.
+ * @category Collation and alignment
+ */
 export const collationsOf = (own, inherited, locate, tolerance = defaultCollationTolerance) => {
     const kinds = byKindInOrderOfOnset(placed(inherited, locate));
     return placed(own, locate).flatMap(({ symbol, horizontal }) => nearOnsetOf(kinds.get(kindOf(symbol)) ?? [], horizontal, tolerance)
@@ -102,9 +121,13 @@ const drawnByCollation = 'recoding';
  * It does not make an edit the editor's. `isCollationsOwn` passes over
  * this motivation exactly, so a collation rewrites what it marked
  * before, and only what somebody has actually written stays.
+ * @category Collation and alignment
  */
 export const unchecked = 'unchecked';
-/** The version's statement of what the unchecked motivation means, to stand in its `motivations`. */
+/**
+ * The version's statement of what the unchecked motivation means, to stand in its `motivations`.
+ * @category Collation and alignment
+ */
 export const uncheckedMotivation = {
     type: 'motivation',
     id: unchecked,
@@ -130,6 +153,7 @@ export const uncheckedMotivation = {
  * A recoding that only inserts or only deletes is the editor's: a
  * collation types no one-sided edit, so one typed so is a reading of
  * the transfer that collating again must not undo.
+ * @category Collation and alignment
  */
 export const isCollationsOwn = (edit) => (edit.editType === drawnByCollation && !!edit.insert?.length && !!edit.delete?.length)
     || (edit.editType === undefined

package/lib/collation/alignment.d.ts

@@ -2,9 +2,15 @@ import { FeatureOrPatch } from "../model/Feature.js";
 import { Alignment, RollCopy } from "../model/RollCopy.js";
 import { TrackerBar } from "../systems/TrackerBar.js";
 import { Millimeters } from "../model/Quantity.js";
-/** A place on the copy's own paper, on the edition's axis. */
+/**
+ * A place on the copy's own paper, on the edition's axis.
+ * @category Collation and alignment
+ */
 export declare const toAxis: (alignment: Alignment | undefined) => (place: Millimeters) => Millimeters;
-/** A place on the edition's axis, on the copy's own paper. */
+/**
+ * A place on the edition's axis, on the copy's own paper.
+ * @category Collation and alignment
+ */
 export declare const fromAxis: (alignment: Alignment | undefined) => (place: Millimeters) => Millimeters;
 /**
  * Carries the copy's features and tears from its own places onto the
@@ -27,7 +33,10 @@ export declare const atOwnPlaces: (copy: RollCopy) => RollCopy;
  * changed.
  */
 export declare const putOnAxis: (copy: RollCopy) => void;
-/** The copy's features at its own places, as it was read, whatever alignment it has. */
+/**
+ * The copy's features at its own places, as it was read, whatever alignment it has.
+ * @category Collation and alignment
+ */
 export declare const ownFeaturesOf: (copy: RollCopy) => FeatureOrPatch[];
 /**
  * Takes the extension a pneumatic reader adds off the ends of the
@@ -63,6 +72,7 @@ export declare const ownFeaturesOf: (copy: RollCopy) => FeatureOrPatch[];
  * the port. What to do with them is an editorial question — a condition
  * on the feature, a reading of the chain, a smaller extension — and
  * `shortenChains` throws rather than answer it.
+ * @category Sources
  */
 export declare const tooShortToShorten: (extension: Millimeters, copy: RollCopy, leaving?: ReadonlySet<string>) => Readonly<FeatureOrPatch>[];
 /**
@@ -84,6 +94,7 @@ export declare const revertShortening: (copy: RollCopy) => void;
  * revision changes when the method does and at no other release, so
  * that an alignment found by an earlier method can be told from one
  * that would be found again as it stands.
+ * @category Collation and alignment
  */
 export declare const ALIGNMENT_METHOD: {
     readonly software: 'linked-rolls alignFeatures';
@@ -92,6 +103,7 @@ export declare const ALIGNMENT_METHOD: {
 /**
  * How a copy's places are carried onto another copy's:
  * `x_other = (x + shift) · scale`.
+ * @category Collation and alignment
  */
 export interface AlignmentResult {
     /** Applied before the scale. */
@@ -125,5 +137,6 @@ export interface AlignmentResult {
  * positions on different tracks, but they agree on the pitch each track
  * sounds, and it is the pitches that are matched. Where a copy's holes
  * have already been put onto the edition's bar, that bar reads it.
+ * @category Collation and alignment
  */
 export declare function alignFeatures(rollA: readonly FeatureOrPatch[], rollB: readonly FeatureOrPatch[], barA?: TrackerBar, barB?: TrackerBar): AlignmentResult | undefined;

package/lib/collation/alignment.js

@@ -2,9 +2,15 @@ import { featuresOf, isTear, tearsOf } from "../model/RollCopy.js";
 import { defaultTrackerBar } from "../systems/index.js";
 import { add, mm, subtract, track } from "../model/Quantity.js";
 import { partitionPoint } from "../shared/sorted.js";
-/** A place on the copy's own paper, on the edition's axis. */
+/**
+ * A place on the copy's own paper, on the edition's axis.
+ * @category Collation and alignment
+ */
 export const toAxis = (alignment) => (place) => alignment ? mm((place + alignment.shift.horizontal) * alignment.scale) : place;
-/** A place on the edition's axis, on the copy's own paper. */
+/**
+ * A place on the edition's axis, on the copy's own paper.
+ * @category Collation and alignment
+ */
 export const fromAxis = (alignment) => (place) => alignment ? mm(place / alignment.scale - alignment.shift.horizontal) : place;
 const acrossToAxis = (alignment) => (position) => alignment ? track(position + alignment.shift.vertical) : position;
 const acrossFromAxis = (alignment) => (position) => alignment ? track(position - alignment.shift.vertical) : position;
@@ -104,7 +110,10 @@ export const putOnAxis = (copy) => {
     if (alignment)
         moveOnto(alignment, copy);
 };
-/** The copy's features at its own places, as it was read, whatever alignment it has. */
+/**
+ * The copy's features at its own places, as it was read, whatever alignment it has.
+ * @category Collation and alignment
+ */
 export const ownFeaturesOf = (copy) => {
     const alignment = copy.measurements.alignment;
     if (!alignment)
@@ -156,6 +165,7 @@ const extensionOnAxis = (extension, copy) => mm(extension * (copy.measurements.a
  * the port. What to do with them is an editorial question — a condition
  * on the feature, a reading of the chain, a smaller extension — and
  * `shortenChains` throws rather than answer it.
+ * @category Sources
  */
 export const tooShortToShorten = (extension, copy, leaving = new Set()) => {
     const onAxis = extensionOnAxis(extension, copy);
@@ -205,6 +215,7 @@ export const revertShortening = (copy) => {
  * revision changes when the method does and at no other release, so
  * that an alignment found by an earlier method can be told from one
  * that would be found again as it stands.
+ * @category Collation and alignment
  */
 export const ALIGNMENT_METHOD = { software: 'linked-rolls alignFeatures', version: '1' };
 const byPlace = (x, y) => x.at - y.at || x.pitch - y.pitch;
@@ -369,6 +380,7 @@ const resultOf = ({ line, matches }) => {
  * positions on different tracks, but they agree on the pitch each track
  * sounds, and it is the pitches that are matched. Where a copy's holes
  * have already been put onto the edition's bar, that bar reads it.
+ * @category Collation and alignment
  */
 export function alignFeatures(rollA, rollB, barA = defaultTrackerBar, barB = barA) {
     const a = noteOnsets(rollA, barA);

package/lib/collation/scatter.d.ts

@@ -16,7 +16,10 @@ import { Edition } from "../model/Edition.js";
  * the measurement yields is a screen: it says which readings the curve
  * does not account for, and an editor says which of those are acts.
  */
-/** Where one copy puts a symbol, against where the copies read with it put it. */
+/**
+ * Where one copy puts a symbol, against where the copies read with it put it.
+ * @category Collation and alignment
+ */
 export interface Reading {
     symbol: Readonly<AnySymbol>;
     /** The copies under test less the rest, at either end of the symbol. */
@@ -43,6 +46,7 @@ export interface Reading {
  *
  * A symbol only one side carries measures nothing and is passed over,
  * which leaves out exactly the insertions and the deletions.
+ * @category Collation and alignment
  */
 export declare const readingsOf: (edition: Edition, symbols: readonly Readonly<AnySymbol>[], copies: ReadonlySet<string>) => Reading[];
 /**
@@ -59,8 +63,14 @@ export declare const readingsOf: (edition: Edition, symbols: readonly Readonly<A
  * notes. Once the alignment carries a skew term, one sample will do,
  * which is why this is a parameter of the estimator and not a field
  * anywhere.
+ * @category Collation and alignment
  */
 export type Grouping = (symbol: Readonly<AnySymbol>) => string;
+/**
+ * How `scatterOf` takes the readings apart into samples, counts them,
+ * and reports on them.
+ * @category Collation and alignment
+ */
 export interface ScatterOptions {
     /** What sample a reading belongs to. By default what the symbol is: a note, an expression, a text. */
     groupOf?: Grouping;
@@ -69,7 +79,10 @@ export interface ScatterOptions {
     /** The tolerance the derivation states at present, against which each departure is reported as still admitted or not. */
     stated?: CollationTolerance;
 }
-/** A reading the calculated tolerance does not admit. */
+/**
+ * A reading the calculated tolerance does not admit.
+ * @category Collation and alignment
+ */
 export interface Departure {
     /** The symbol read. */
     symbol: string;
@@ -103,14 +116,20 @@ export interface Departure {
      */
     admittedAsStated?: boolean;
 }
-/** How far a sample departs from the normal shape the tolerance assumes of it. */
+/**
+ * How far a sample departs from the normal shape the tolerance assumes of it.
+ * @category Collation and alignment
+ */
 export interface Normality {
     /** How much heavier its tails are than a normal sample's. Nothing for a normal shape. */
     excessKurtosis: number;
     /** What it puts beyond two, three and four times the scatter, against what a normal sample would. */
     tails: Tail[];
 }
-/** A histogram with the curve its counts are held to follow. */
+/**
+ * A histogram with the curve its counts are held to follow.
+ * @category Collation and alignment
+ */
 export interface FittedHistogram extends Histogram<'mm'> {
     /**
      * The normal curve, in the counts' own units, so that an overlay is
@@ -123,7 +142,10 @@ export interface FittedHistogram extends Histogram<'mm'> {
         area: number;
     };
 }
-/** How far one sample of readings scatters, and the tolerance that follows from it. */
+/**
+ * How far one sample of readings scatters, and the tolerance that follows from it.
+ * @category Collation and alignment
+ */
 export interface Scatter {
     /** The sample, as the grouping named it. */
     group: string;
@@ -157,19 +179,25 @@ export interface Scatter {
  * point beyond which fewer than one reading of a sample of this size is
  * expected to fall by chance. For the samples an edge of the stemma
  * yields, some hundreds of readings, this lands between 3.0 and 3.2.
+ * @category Collation and alignment
  */
 export declare const departureThreshold: (n: number) => number;
 /**
  * How the readings scatter, one sample per group. A group whose
  * readings all sit at one place yields nothing, since no scatter can be
  * read off such a sample.
+ * @category Collation and alignment
  */
 export declare const scatterOf: (readings: readonly Reading[], options?: ScatterOptions) => Scatter[];
-/** How one copy's readings of a version's text scatter against the readings of the copies it is collated with. */
+/**
+ * How one copy's readings of a version's text scatter against the readings of the copies it is collated with.
+ * @category Collation and alignment
+ */
 export declare const scatterOfCopy: (edition: Edition, versionId: string, copyId: string, options?: ScatterOptions) => Scatter[];
 /**
  * Which side of a derivation a measurement was taken over: the version
  * derived, or the version it is read against.
+ * @category Collation and alignment
  */
 export type Side = 'child' | 'parent';
 /**
@@ -201,9 +229,13 @@ export type Side = 'child' | 'parent';
  * expressions show. `changesBetween` makes that visible as readings the
  * window moves; it is the price of one tolerance per derivation, and it
  * is the same skew the grouping stands in for.
+ * @category Collation and alignment
  */
 export declare const toleranceAcross: (scatters: readonly Scatter[], named: Side) => CollationTolerance | undefined;
-/** What putting one window in force in place of another would do to a collation. */
+/**
+ * What putting one window in force in place of another would do to a collation.
+ * @category Collation and alignment
+ */
 export interface Changes {
     /** Readings the window in force joins and the proposed one would take apart. */
     separated: Reading[];
@@ -225,14 +257,21 @@ export interface Changes {
  * reading `admittedAsStated` off the departures, which sees separations
  * only. An edge both windows agree about throughout needs no
  * re-collation at all, and its tolerance may simply be stated.
+ * @category Collation and alignment
  */
 export declare const changesBetween: (readings: readonly Reading[], inForce: CollationTolerance, proposed: CollationTolerance) => Changes;
-/** How many of a side's symbols a copy bears. */
+/**
+ * How many of a side's symbols a copy bears.
+ * @category Collation and alignment
+ */
 export interface Attestation {
     copy: string;
     symbols: number;
 }
-/** The copies attesting each side of a derivation, each side in order of how much it bears. */
+/**
+ * The copies attesting each side of a derivation, each side in order of how much it bears.
+ * @category Collation and alignment
+ */
 export interface Sides {
     /** The copies bearing what the child inserts: the reading the derivation moves to. */
     child: Attestation[];
@@ -255,6 +294,7 @@ export interface Sides {
  * A fully collated edge inserts and deletes nothing and so attests
  * neither side, which is the case where the edition has genuinely
  * stopped saying and an editor has to.
+ * @category Collation and alignment
  */
 export declare const sidesOf: (edition: Edition, versionId: string) => Sides | undefined;
 /**
@@ -268,5 +308,6 @@ export declare const sidesOf: (edition: Edition, versionId: string) => Sides | u
  * sample only as far as the sample is normal, and a sample far from
  * that shape makes the number unreliable rather than wrong, which is
  * what `normality` is reported for.
+ * @category Collation and alignment
  */
 export declare const inferredTolerance: (scatters: readonly Scatter[], used?: readonly string[]) => Belief;

package/lib/collation/scatter.js

@@ -35,6 +35,7 @@ const sitsOn = (edition, copies) => (feature) => {
  *
  * A symbol only one side carries measures nothing and is passed over,
  * which leaves out exactly the insertions and the deletions.
+ * @category Collation and alignment
  */
 export const readingsOf = (edition, symbols, copies) => {
     const tested = sitsOn(edition, copies);
@@ -58,6 +59,7 @@ const DEFAULT_BIN_WIDTH = mm(0.25);
  * point beyond which fewer than one reading of a sample of this size is
  * expected to fall by chance. For the samples an edge of the stemma
  * yields, some hundreds of readings, this lands between 3.0 and 3.2.
+ * @category Collation and alignment
  */
 export const departureThreshold = (n) => normalQuantile(1 - 1 / (2 * n));
 const estimate = (values, binWidth) => {
@@ -118,10 +120,14 @@ const scatterIn = (group, sample, { binWidth = DEFAULT_BIN_WIDTH, stated }) => {
  * How the readings scatter, one sample per group. A group whose
  * readings all sit at one place yields nothing, since no scatter can be
  * read off such a sample.
+ * @category Collation and alignment
  */
 export const scatterOf = (readings, options = {}) => [...groupBy(readings, reading => (options.groupOf ?? byWhatItIs)(reading.symbol))]
     .flatMap(([group, sample]) => scatterIn(group, sample, options));
-/** How one copy's readings of a version's text scatter against the readings of the copies it is collated with. */
+/**
+ * How one copy's readings of a version's text scatter against the readings of the copies it is collated with.
+ * @category Collation and alignment
+ */
 export const scatterOfCopy = (edition, versionId, copyId, options = {}) => scatterOf(readingsOf(edition, snapshotOf(edition, versionId), new Set([copyId])), options);
 const covering = (windows) => {
     const lowest = Math.min(...windows.map(window => window.offset - window.tolerance));
@@ -157,6 +163,7 @@ const covering = (windows) => {
  * expressions show. `changesBetween` makes that visible as readings the
  * window moves; it is the price of one tolerance per derivation, and it
  * is the same skew the grouping stands in for.
+ * @category Collation and alignment
  */
 export const toleranceAcross = (scatters, named) => {
     if (scatters.length === 0)
@@ -186,6 +193,7 @@ export const toleranceAcross = (scatters, named) => {
  * reading `admittedAsStated` off the departures, which sees separations
  * only. An edge both windows agree about throughout needs no
  * re-collation at all, and its tolerance may simply be stated.
+ * @category Collation and alignment
  */
 export const changesBetween = (readings, inForce, proposed) => ({
     separated: readings.filter(({ displacement }) => admits(inForce, displacement) && !admits(proposed, displacement)),
@@ -220,6 +228,7 @@ const copiesBearing = (edition, symbols) => {
  * A fully collated edge inserts and deletes nothing and so attests
  * neither side, which is the case where the edition has genuinely
  * stopped saying and an editor has to.
+ * @category Collation and alignment
  */
 export const sidesOf = (edition, versionId) => {
     const version = versionIn(edition, versionId);
@@ -251,6 +260,7 @@ const warrantFor = (scatters) => 'The tolerance is calculated from the scatter o
  * sample only as far as the sample is normal, and a sample far from
  * that shape makes the number unreliable rather than wrong, which is
  * what `normality` is reported for.
+ * @category Collation and alignment
  */
 export const inferredTolerance = (scatters, used = []) => ({
     type: 'belief',

package/lib/collation/statistics.d.ts

@@ -9,9 +9,15 @@ import { Quantity } from "../model/Quantity.js";
  * stood out; a median and a median absolute deviation leave them out of
  * account.
  */
-/** The middle of a sample, the mean of the two middle values where it has an even number of them. */
+/**
+ * The middle of a sample, the mean of the two middle values where it has an even number of them.
+ * @internal
+ */
 export declare const medianOf: <U extends string>(values: readonly Quantity<U>[]) => Quantity<U> | undefined;
-/** Where a sample sits and how far it scatters. */
+/**
+ * Where a sample sits and how far it scatters.
+ * @category Collation and alignment
+ */
 export interface Spread<U extends string> {
     /** How many measurements it was taken over. */
     n: number;
@@ -25,27 +31,44 @@ export interface Spread<U extends string> {
      */
     sigma: Quantity<U>;
 }
-/** Where the sample sits and how far it scatters, or nothing for an empty sample. */
+/**
+ * Where the sample sits and how far it scatters, or nothing for an empty sample.
+ * @internal
+ */
 export declare const spreadOf: <U extends string>(values: readonly Quantity<U>[]) => Spread<U> | undefined;
-/** How far the value lies from the centre of the spread, in units of its scatter. */
+/**
+ * How far the value lies from the centre of the spread, in units of its scatter.
+ * @internal
+ */
 export declare const standardise: <U extends string>(value: Quantity<U>, spread: Spread<U>) => number;
-/** The share of a normal sample lying below `z` standard deviations. */
+/**
+ * The share of a normal sample lying below `z` standard deviations.
+ * @internal
+ */
 export declare const normalBelow: (z: number) => number;
-/** The share of a normal sample lying further than `z` standard deviations from its centre, on either side. */
+/**
+ * The share of a normal sample lying further than `z` standard deviations from its centre, on either side.
+ * @internal
+ */
 export declare const normalBeyond: (z: number) => number;
 /**
  * How many standard deviations out the given share of a normal sample
  * lies below, after Acklam's rational approximation, whose relative
  * error stays below 1.15e-9. The inverse of `normalBelow`.
+ * @internal
  */
 export declare const normalQuantile: (share: number) => number;
 /**
  * How much heavier the tails of a standardised sample are than a normal
  * sample's. Zero for a normal shape, positive where more of the sample
  * lies far out than the curve allows.
+ * @internal
  */
 export declare const excessKurtosisOf: (standardised: readonly number[]) => number;
-/** How much of a sample lies beyond a given distance from its centre, against how much would under a normal curve. */
+/**
+ * How much of a sample lies beyond a given distance from its centre, against how much would under a normal curve.
+ * @category Collation and alignment
+ */
 export interface Tail {
     /** The distance from the centre, in standard deviations. */
     beyond: number;
@@ -54,9 +77,15 @@ export interface Tail {
     /** How many a normal sample of the same size would put there. */
     expected: number;
 }
-/** What the sample puts beyond the given distance, against what a normal sample would. */
+/**
+ * What the sample puts beyond the given distance, against what a normal sample would.
+ * @internal
+ */
 export declare const tailOf: (standardised: readonly number[], beyond: number) => Tail;
-/** A sample counted into bins of one width. */
+/**
+ * A sample counted into bins of one width.
+ * @category Collation and alignment
+ */
 export interface Histogram<U extends string> {
     /** The bounds of the bins, in order, one more of them than there are counts. */
     edges: Quantity<U>[];
@@ -67,5 +96,6 @@ export interface Histogram<U extends string> {
  * The sample counted into bins of the given width, laid out on
  * multiples of that width so that two histograms of one width share
  * their bounds. Nothing for an empty sample or a width of nothing.
+ * @internal
  */
 export declare const histogramOf: <U extends string>(values: readonly Quantity<U>[], binWidth: Quantity<U>) => Histogram<U> | undefined;