linked-rolls 0.62.0 → 0.63.0

package/README.md

@@ -22,12 +22,15 @@ single undo step.
 
 ```ts
 import { produce } from 'immer'
-import { asJsonLd, connectVersions, createVersion, EditionView, importJsonLd, readFromStanfordAton } from 'linked-rolls'
+import { alignCopy, asJsonLd, connectVersions, createVersion, EditionView, importJsonLd, readFromStanfordAton } from 'linked-rolls'
 
 let edition = importJsonLd(json)
 
-// Add a copy read from a SUPRA analysis file, with a version of its own
-edition = produce(edition, createVersion(readFromStanfordAton(aton)))
+// Add a copy read from a SUPRA analysis file, with a version of its own,
+// and align it with the reference copy, whose millimetres are the axis
+const copy = readFromStanfordAton(aton)
+edition = produce(edition, createVersion(copy))
+edition = produce(edition, alignCopy(copy.id))
 
 // Collate that version against another one
 const view = new EditionView(edition)
@@ -36,6 +39,14 @@ edition = produce(edition, connectVersions(view, childId, parentId))
 const document = asJsonLd(edition)
 ```
 
+Within the library every place along the roll is a place on the edition's
+axis, the millimetres of its reference copy. A document holds each copy's
+features at the copy's own places, as they were read, together with the
+alignment that carries them onto the axis; the import and the export map
+between the two. What the alignments say about the paper of the copies,
+how far each has stretched and how the papers of the systems relate, is
+worked out by `paperOf`.
+
 Documents written by earlier releases are brought up to date on import.
 To check a document against the schema:
 

package/lib/analysis/constraints.js

@@ -1,4 +1,5 @@
-import { speedScalesIn } from "./ownPaper.js";
+import { paperOfVersion } from "./ownPaper.js";
+import { alignmentProblems } from "./paper.js";
 import { idOf } from "../model/Assumption.js";
 import { isCommand, pairsAmong, placementsOf } from "../model/Symbol.js";
 import { keyOf } from "../systems/TrackerBar.js";
@@ -91,17 +92,22 @@ const carriersOffTheirMeaning = (view, version, commands) => {
         .map(symbol => ({ version, symbol: symbol.id, problem: 'carrier-on-another-track' }));
 };
 /**
- * Where the copies of the version's own system disagree about the scale
- * that put them on the edition's shared axis.
+ * Where a copy of the version's own system strays from the others in
+ * its paper by more than paper does.
  *
- * That scale is what takes a place back to the paper the version's roll
- * ran on, so a performance needs one number. Copies disagreeing about it
- * is evidence about the copies, and averaging it away would hide both
- * the disagreement and the fact that the playback rests on a guess.
+ * The paper of the system is what takes a place back to the paper the
+ * version's roll ran on, so a performance needs one figure. A copy far
+ * off it is evidence about the copies, perhaps one cut for another
+ * speed, and averaging it in would hide both that and the fact that the
+ * playback rests on a guess.
  */
-const paperDisagreed = (view, version) => speedScalesIn(view, version).length > 1
-    ? [{ version: version.id, symbol: version.id, problem: 'copies-disagree-on-the-paper' }]
-    : [];
+const paperDisagreed = (view, version) => {
+    const own = new Set(paperOfVersion(view, version)?.copies ?? []);
+    return alignmentProblems(view.edition)
+        .some(({ copy, problem }) => problem === 'paper-beyond-its-spread' && own.has(copy))
+        ? [{ version: version.id, symbol: version.id, problem: 'copies-disagree-on-the-paper' }]
+        : [];
+};
 /**
  * A version's strikes that take nothing out of its text: each deleted
  * symbol has to be one the parent hands down, or one the version put

package/lib/analysis/ownPaper.d.ts

@@ -1,10 +1,8 @@
 import type { EditionView } from "../view/EditionView.js";
 import type { Version } from "../model/Version.js";
-import { RollCopy } from "../model/RollCopy.js";
-/** The copies of the version's own system that carry any of its symbols. */
-export declare const copiesOwning: (view: EditionView, version: Readonly<Version>) => Readonly<RollCopy>[];
-/** The scales of the version's own copies that are not their own paper stretch. */
-export declare const speedScalesIn: (view: EditionView, version: Readonly<Version>) => number[];
+import { PaperOfSystem } from "./paper.js";
+/** What the alignments say about the paper of the version's own system, where they say anything. */
+export declare const paperOfVersion: (view: EditionView, version: Readonly<Version>) => PaperOfSystem | undefined;
 /**
  * How a place on the edition's shared axis relates to the paper of
  * this version: place × factor = millimetres of its own paper.
@@ -12,15 +10,12 @@ export declare const speedScalesIn: (view: EditionView, version: Readonly<Versio
  * Copies cut for different systems are scaled onto one axis so that
  * they can be collated at all, which leaves a version of another
  * system carrying places in the axis copy's millimetres. A
- * performance needs the paper the roll actually ran on, and the
- * factor is the inverse of the scale `alignCopy` recorded.
+ * performance needs the paper the roll actually ran on, unstretched,
+ * and that is what the alignments of all the copies give together
+ * (`paperOf`): the ratio of the version's system to the reference
+ * copy's, over how far the reference copy's paper has stretched.
  *
- * It is read only from the copies of the version's own system, since
- * under the shared axis a green version's notes are carried by red
- * copies too and those say nothing about green paper. A copy whose
- * scale is put down to its own paper having stretched is left out as
- * well: that is a fact about the one exemplar, not about the speed
- * the system's rolls were cut at. Where what remains disagrees,
- * `constraintProblems` reports it rather than averaging it away.
+ * Nothing where no copy of the version's system measures its paper,
+ * which leaves the performance on the axis.
  */
 export declare const toOwnPaperOf: (view: EditionView, version: Readonly<Version>) => number | undefined;

package/lib/analysis/ownPaper.js

@@ -1,22 +1,10 @@
-import { idsOf } from "../model/Assumption.js";
-import { isPaperStretch } from "../model/RollCopy.js";
-import { systemIdOf } from "../systems/TrackerBar.js";
-/** The copies of the version's own system that carry any of its symbols. */
-export const copiesOwning = (view, version) => {
-    const system = systemIdOf(version.system);
-    const carrying = new Set(view.snapshot(version.id)
-        .flatMap(symbol => idsOf(symbol.carriers))
-        .flatMap(id => {
-        const copy = view.copyOf(id);
-        return copy ? [copy.id] : [];
-    }));
-    return view.edition.copies.filter(copy => carrying.has(copy.id) && systemIdOf(copy.production?.system) === system);
+import { defaultTrackerBar, trackerBarOf } from "../systems/index.js";
+import { paperOf } from "./paper.js";
+/** What the alignments say about the paper of the version's own system, where they say anything. */
+export const paperOfVersion = (view, version) => {
+    const system = (trackerBarOf(version.system) ?? defaultTrackerBar).id;
+    return paperOf(view.edition)?.systems.find(paper => paper.system === system);
 };
-/** The scales of the version's own copies that are not their own paper stretch. */
-export const speedScalesIn = (view, version) => [...new Set(copiesOwning(view, version)
-        .filter(copy => !copy.conditions.some(isPaperStretch))
-        .map(copy => copy.measurements.scale)
-        .filter((scale) => scale !== undefined && scale > 0))];
 /**
  * How a place on the edition's shared axis relates to the paper of
  * this version: place × factor = millimetres of its own paper.
@@ -24,18 +12,12 @@ export const speedScalesIn = (view, version) => [...new Set(copiesOwning(view, v
  * Copies cut for different systems are scaled onto one axis so that
  * they can be collated at all, which leaves a version of another
  * system carrying places in the axis copy's millimetres. A
- * performance needs the paper the roll actually ran on, and the
- * factor is the inverse of the scale `alignCopy` recorded.
+ * performance needs the paper the roll actually ran on, unstretched,
+ * and that is what the alignments of all the copies give together
+ * (`paperOf`): the ratio of the version's system to the reference
+ * copy's, over how far the reference copy's paper has stretched.
  *
- * It is read only from the copies of the version's own system, since
- * under the shared axis a green version's notes are carried by red
- * copies too and those say nothing about green paper. A copy whose
- * scale is put down to its own paper having stretched is left out as
- * well: that is a fact about the one exemplar, not about the speed
- * the system's rolls were cut at. Where what remains disagrees,
- * `constraintProblems` reports it rather than averaging it away.
+ * Nothing where no copy of the version's system measures its paper,
+ * which leaves the performance on the axis.
  */
-export const toOwnPaperOf = (view, version) => {
-    const scales = speedScalesIn(view, version);
-    return scales.length === 1 ? 1 / scales[0] : undefined;
-};
+export const toOwnPaperOf = (view, version) => paperOfVersion(view, version)?.toOwnPaper;

package/lib/analysis/paper.d.ts

@@ -0,0 +1,129 @@
+import { Edition } from "../model/Edition.js";
+import { Strain } from "../model/RollCopy.js";
+import { Percent } from "../model/Quantity.js";
+/**
+ * How far the paper of one copy is taken to have stretched or shrunk
+ * along the roll, as a standard deviation, where the edition has too few
+ * copies of one system to say: the three red copies of Welte 225 spread
+ * by 0.19 %. It includes the scanner's error along the roll, which the
+ * alignment cannot tell from the paper's.
+ */
+export declare const PAPER_SPREAD: Percent;
+/**
+ * How far a paper speed a label or the literature states is taken to be
+ * from the speed a copy was cut at: the literature gives the red roll's
+ * three metres a minute as 2.9 as well (Bärtsch 2020), which is 3.4 %.
+ */
+export declare const SPEED_TOLERANCE = 0.035;
+/** What the alignments say about one copy's paper. */
+export interface PaperOfCopy {
+    copy: string;
+    /** The system the copy was cut for, by the id of its bar. */
+    system: string;
+    /** How far its paper has stretched along the roll since it was perforated, and how surely that is known. */
+    along: Strain;
+    /** Whether a strain measured on the copy went into it, rather than the spread of paper alone. */
+    measured: boolean;
+}
+/** What the alignments say about the paper the copies of one system were cut on. */
+export interface PaperOfSystem {
+    /** The system, by the id of its bar. */
+    system: string;
+    /**
+     * The length of this system's paper, unstretched, for a length of the
+     * reference system's: one for the reference copy's own system, about
+     * 0.77 for a Licensee or green re-cut of a red roll. It is the ratio
+     * of the paper speeds the two were cut for.
+     */
+    ratio: number;
+    /** The standard uncertainty of the ratio. */
+    ratioError: number;
+    /**
+     * A place on the axis times this is millimetres of this system's
+     * paper, unstretched: what a performance of one of its versions runs
+     * on (`RollProperties.toOwnPaper`).
+     */
+    toOwnPaper: number;
+    /** The standard uncertainty of `toOwnPaper`. */
+    toOwnPaperError: number;
+    /** The copies of the system it rests on. */
+    copies: string[];
+}
+/** What the alignments of an edition say about the paper of its copies, and how surely. */
+export interface PaperReading {
+    /** The copy whose millimetres are the axis. */
+    reference: string;
+    /**
+     * How far one copy's paper is taken to stray from its system's, and
+     * how many degrees of freedom the copies give it: none where it is
+     * `PAPER_SPREAD` for want of copies.
+     */
+    spread: {
+        value: Percent;
+        degreesOfFreedom: number;
+    };
+    copies: PaperOfCopy[];
+    systems: PaperOfSystem[];
+}
+/**
+ * What the alignments of the edition say about the paper of its copies:
+ * how far each copy's paper has stretched along the roll, and how long
+ * the paper of each system is against the reference copy's.
+ *
+ * An alignment's scale is one number with three causes. A copy cut for
+ * another paper speed is shorter or longer by the ratio of the speeds,
+ * which the system's copies share; its paper has stretched or shrunk as
+ * it alone has, and so has the reference copy's. In true strains, the
+ * logarithms of the ratios of the lengths, the causes add:
+ *
+ *     ln scale = strain_reference − strain_copy − ln ratio_system
+ *
+ * The alignments give the left side to a few parts in a hundred thousand.
+ * The right side has a strain for every copy and a ratio for every
+ * system, so it is found by least squares with each strain taken to lie
+ * about zero by the spread of paper (`PAPER_SPREAD`, or what the copies
+ * show where there are enough of one system), or about a strain
+ * measured on the copy by that measurement's uncertainty. Where a system
+ * has one copy only its ratio takes the whole scale and the copy's strain
+ * stays at zero, known no better than paper varies; where the copies of
+ * the reference system are several, the axis comes out at their mean
+ * paper and not at the reference copy's.
+ *
+ * Copies whose places are not places on the paper, such as a roll
+ * reader's, say nothing about the paper and are left out. Nothing is
+ * said where the edition has no reference copy.
+ */
+export declare const paperOf: (edition: Pick<Edition, 'copies' | 'referenceCopy'>) => PaperReading | undefined;
+/** Where the alignments of the copies, or what they say about the paper, want looking into. */
+export type AlignmentProblem = {
+    copy: string;
+    problem: 
+    /** The copy has features but no alignment, and is not the reference copy. */
+    'not-aligned'
+    /** It was aligned against a copy that is not the reference copy now. */
+     | 'aligned-against-another-copy'
+    /**
+     * The speed stated for it and the reference copy's stated or
+     * nominal one give another ratio of the papers than the
+     * alignments, by more than a stated speed may be off.
+     */
+     | 'speed-disagrees-with-paper'
+    /**
+     * Its paper strays from its system's by more than paper does:
+     * it may have been cut for another speed, or read wrongly.
+     */
+     | 'paper-beyond-its-spread';
+    /**
+     * How far: for a speed, the logarithm of the ratio the speeds give
+     * over the one the alignments give; for a paper, the copy's strain in
+     * per cent.
+     */
+    by?: number;
+};
+/**
+ * Where the alignments of the edition's copies, or what they say about
+ * the paper, want looking into. None of it is recomputed, so it is cheap
+ * to ask; whether an alignment would come out otherwise if found again
+ * is `alignmentFor`'s to say.
+ */
+export declare const alignmentProblems: (edition: Pick<Edition, 'copies' | 'referenceCopy'>) => AlignmentProblem[];

package/lib/analysis/paper.js

@@ -0,0 +1,260 @@
+import { referenceCopyOf } from "../model/Edition.js";
+import { barOf, featuresOf, paperStretchOf } from "../model/RollCopy.js";
+import { certaintyOf, isAsserted } from "../model/Assumption.js";
+import { inMetersPerMinute, percent } from "../model/Quantity.js";
+/**
+ * How far the paper of one copy is taken to have stretched or shrunk
+ * along the roll, as a standard deviation, where the edition has too few
+ * copies of one system to say: the three red copies of Welte 225 spread
+ * by 0.19 %. It includes the scanner's error along the roll, which the
+ * alignment cannot tell from the paper's.
+ */
+export const PAPER_SPREAD = percent(0.2);
+/**
+ * How far a paper speed a label or the literature states is taken to be
+ * from the speed a copy was cut at: the literature gives the red roll's
+ * three metres a minute as 2.9 as well (Bärtsch 2020), which is 3.4 %.
+ */
+export const SPEED_TOLERANCE = 0.035;
+/** The kinds of source that give places on the paper, so that the length between two of them is the paper's. */
+const measuringLength = new Set(['roll', 'scan', 'analysis']);
+/**
+ * Whether the copy's places are places on its paper, so that its length
+ * between two notes is a length of paper: it is the reference copy or
+ * aligned with it, and was read off the roll or an image of it. A copy
+ * that names no source counts as read so. A roll reader measures time,
+ * and places worked out from it are only as long as the speed they were
+ * worked out with.
+ */
+const measuresPaper = (copy, reference) => (copy.id === reference.id || copy.measurements.alignment !== undefined)
+    && featuresOf(copy).length > 0
+    && (!copy.readFrom || measuringLength.has(copy.readFrom.kind));
+/**
+ * A strain in per cent as the fit takes it: the logarithm of the ratio of
+ * the lengths, the true strain, which adds where the causes of a scale
+ * multiply. For the tenths of a per cent paper does it is the same.
+ */
+const logarithmicOf = (value) => Math.log1p(value / 100);
+/** A true strain back in per cent of the length. */
+const percentOf = (logarithmic) => percent(Math.expm1(logarithmic) * 100);
+/** The strain measured on the copy along the roll, where one is and the edition holds it. */
+const measuredAlong = (copy) => {
+    const stretch = paperStretchOf(copy);
+    return stretch && isAsserted(certaintyOf(stretch)) ? stretch.along : undefined;
+};
+/** How closely an alignment's scale is known, as a share of it, at no less than a part in a million. */
+const scaleShareError = (copy) => {
+    const alignment = copy.measurements.alignment;
+    if (!alignment)
+        return 0;
+    const error = alignment.scaleError ?? 0;
+    return Math.max(Number.isFinite(error) ? error / alignment.scale : 0, 1e-6);
+};
+/**
+ * The spread of the copies' papers about their systems', as far as
+ * copies of one system can show it: each copy's length against the axis,
+ * `-ln scale`, differs from another's of its system by their strains
+ * alone, the ratio of the system being common to them.
+ */
+const spreadIn = (lengths) => {
+    const groups = [...lengths.values()];
+    const degreesOfFreedom = groups.reduce((total, group) => total + group.length - 1, 0);
+    if (degreesOfFreedom < 2)
+        return { value: logarithmicOf(PAPER_SPREAD), degreesOfFreedom: 0 };
+    const squares = groups.reduce((total, group) => {
+        const mean = group.reduce((sum, length) => sum + length, 0) / group.length;
+        return total + group.reduce((sum, length) => sum + (length - mean) ** 2, 0);
+    }, 0);
+    return { value: Math.sqrt(squares / degreesOfFreedom), degreesOfFreedom };
+};
+/** The inverse of a symmetric positive definite matrix, by Gauss and Jordan. */
+const inverse = (matrix) => {
+    const n = matrix.length;
+    const work = matrix.map((row, i) => [...row, ...Array.from({ length: n }, (_, j) => (i === j ? 1 : 0))]);
+    for (let column = 0; column < n; column++) {
+        const pivot = work.reduce((best, row, i) => i >= column && Math.abs(row[column]) > Math.abs(work[best][column]) ? i : best, column);
+        [work[column], work[pivot]] = [work[pivot], work[column]];
+        const lead = work[column][column];
+        work[column] = work[column].map(value => value / lead);
+        work.forEach((row, i) => {
+            if (i === column)
+                return;
+            const factor = row[column];
+            work[i] = row.map((value, j) => value - factor * work[column][j]);
+        });
+    }
+    return work.map(row => row.slice(n));
+};
+/**
+ * What the alignments of the edition say about the paper of its copies:
+ * how far each copy's paper has stretched along the roll, and how long
+ * the paper of each system is against the reference copy's.
+ *
+ * An alignment's scale is one number with three causes. A copy cut for
+ * another paper speed is shorter or longer by the ratio of the speeds,
+ * which the system's copies share; its paper has stretched or shrunk as
+ * it alone has, and so has the reference copy's. In true strains, the
+ * logarithms of the ratios of the lengths, the causes add:
+ *
+ *     ln scale = strain_reference − strain_copy − ln ratio_system
+ *
+ * The alignments give the left side to a few parts in a hundred thousand.
+ * The right side has a strain for every copy and a ratio for every
+ * system, so it is found by least squares with each strain taken to lie
+ * about zero by the spread of paper (`PAPER_SPREAD`, or what the copies
+ * show where there are enough of one system), or about a strain
+ * measured on the copy by that measurement's uncertainty. Where a system
+ * has one copy only its ratio takes the whole scale and the copy's strain
+ * stays at zero, known no better than paper varies; where the copies of
+ * the reference system are several, the axis comes out at their mean
+ * paper and not at the reference copy's.
+ *
+ * Copies whose places are not places on the paper, such as a roll
+ * reader's, say nothing about the paper and are left out. Nothing is
+ * said where the edition has no reference copy.
+ */
+export const paperOf = (edition) => {
+    const reference = referenceCopyOf(edition);
+    if (!reference)
+        return undefined;
+    const copies = edition.copies.filter(copy => measuresPaper(copy, reference));
+    if (!copies.some(copy => copy.id === reference.id))
+        return undefined;
+    const referenceSystem = barOf(reference).id;
+    const systemOf = (copy) => barOf(copy).id;
+    const systems = [...new Set(copies.map(systemOf))].filter(system => system !== referenceSystem);
+    const lengthOf = (copy) => copy.id === reference.id ? 0 : -Math.log(copy.measurements.alignment.scale);
+    const lengths = Map.groupBy(copies, systemOf);
+    const spread = spreadIn(new Map([...lengths].map(([system, group]) => [system, group.map(lengthOf)])));
+    // Unknowns: the strain of each copy, then the log ratio of each system but the reference's.
+    const strainAt = new Map(copies.map((copy, i) => [copy.id, i]));
+    const ratioAt = new Map(systems.map((system, i) => [system, copies.length + i]));
+    const referenceAt = strainAt.get(reference.id);
+    const aligned = copies
+        .filter(copy => copy.id !== reference.id)
+        .map(copy => {
+        const ratio = ratioAt.get(systemOf(copy));
+        return {
+            coefficients: new Map([
+                [referenceAt, 1],
+                [strainAt.get(copy.id), -1],
+                ...(ratio !== undefined ? [[ratio, -1]] : [])
+            ]),
+            value: Math.log(copy.measurements.alignment.scale),
+            variance: scaleShareError(copy) ** 2
+        };
+    });
+    const measured = new Map(copies.flatMap(copy => {
+        const strain = measuredAlong(copy);
+        return strain ? [[copy.id, strain]] : [];
+    }));
+    const priors = copies.map(copy => {
+        const strain = measured.get(copy.id);
+        const uncertainty = strain?.uncertainty !== undefined
+            ? strain.uncertainty / (100 + strain.value)
+            : spread.value;
+        return {
+            coefficients: new Map([[strainAt.get(copy.id), 1]]),
+            value: strain ? logarithmicOf(strain.value) : 0,
+            variance: uncertainty ** 2
+        };
+    });
+    const size = copies.length + systems.length;
+    const normal = Array.from({ length: size }, () => Array.from({ length: size }, () => 0));
+    const right = Array.from({ length: size }, () => 0);
+    [...aligned, ...priors].forEach(({ coefficients, value, variance }) => {
+        const weight = 1 / variance;
+        coefficients.forEach((a, i) => {
+            right[i] += weight * a * value;
+            coefficients.forEach((b, j) => { normal[i][j] += weight * a * b; });
+        });
+    });
+    const covariance = inverse(normal);
+    const solution = covariance.map(row => row.reduce((total, value, j) => total + value * right[j], 0));
+    const strainReference = solution[referenceAt];
+    const varianceReference = covariance[referenceAt][referenceAt];
+    const systemReading = (system) => {
+        const at = ratioAt.get(system);
+        const logRatio = at === undefined ? 0 : solution[at];
+        const varianceRatio = at === undefined ? 0 : covariance[at][at];
+        const covarianceWithReference = at === undefined ? 0 : covariance[at][referenceAt];
+        const ratio = Math.exp(logRatio);
+        const toOwnPaper = Math.exp(logRatio - strainReference);
+        return {
+            system,
+            ratio,
+            ratioError: ratio * Math.sqrt(varianceRatio),
+            toOwnPaper,
+            toOwnPaperError: toOwnPaper * Math.sqrt(Math.max(0, varianceRatio + varianceReference - 2 * covarianceWithReference)),
+            copies: copies.filter(copy => systemOf(copy) === system).map(copy => copy.id)
+        };
+    };
+    return {
+        reference: reference.id,
+        spread: { value: percentOf(spread.value), degreesOfFreedom: spread.degreesOfFreedom },
+        copies: copies.map(copy => {
+            const at = strainAt.get(copy.id);
+            return {
+                copy: copy.id,
+                system: systemOf(copy),
+                along: {
+                    value: percentOf(solution[at]),
+                    uncertainty: percent(Math.exp(solution[at]) * Math.sqrt(covariance[at][at]) * 100),
+                    unit: 'percent'
+                },
+                measured: measured.has(copy.id)
+            };
+        }),
+        systems: [referenceSystem, ...systems].map(systemReading)
+    };
+};
+/** A paper speed the edition holds true or likely, in metres a minute. */
+const statedSpeed = (copy) => {
+    const speed = copy.production?.speed;
+    return speed && isAsserted(certaintyOf(speed)) ? inMetersPerMinute(speed) : undefined;
+};
+/** The speed the reference copy was cut at: as stated for it, or as its system runs. */
+const referenceSpeed = (reference) => {
+    const system = barOf(reference).paperSpeed;
+    return statedSpeed(reference) ?? (system && inMetersPerMinute(system));
+};
+/**
+ * Where the alignments of the edition's copies, or what they say about
+ * the paper, want looking into. None of it is recomputed, so it is cheap
+ * to ask; whether an alignment would come out otherwise if found again
+ * is `alignmentFor`'s to say.
+ */
+export const alignmentProblems = (edition) => {
+    const reference = referenceCopyOf(edition);
+    if (!reference)
+        return [];
+    const unaligned = edition.copies
+        .filter(copy => copy.id !== reference.id && !copy.measurements.alignment && featuresOf(copy).length > 0)
+        .map(copy => ({ copy: copy.id, problem: 'not-aligned' }));
+    const elsewhere = edition.copies
+        .filter(copy => {
+        const against = copy.measurements.alignment?.against;
+        return against !== undefined && against !== reference.id;
+    })
+        .map(copy => ({ copy: copy.id, problem: 'aligned-against-another-copy' }));
+    const reading = paperOf(edition);
+    if (!reading)
+        return [...unaligned, ...elsewhere];
+    const beyond = reading.copies
+        .filter(paper => Math.abs(paper.along.value) > 3 * PAPER_SPREAD)
+        .map(paper => ({ copy: paper.copy, problem: 'paper-beyond-its-spread', by: paper.along.value }));
+    const speedOfReference = referenceSpeed(reference);
+    const speeds = speedOfReference === undefined ? [] : reading.copies.flatMap(paper => {
+        const copy = edition.copies.find(c => c.id === paper.copy);
+        const speed = copy.id === reference.id ? undefined : statedSpeed(copy);
+        const system = reading.systems.find(s => s.system === paper.system);
+        if (speed === undefined)
+            return [];
+        const by = Math.log((speed / speedOfReference) / system.ratio);
+        const allowed = SPEED_TOLERANCE + 3 * system.ratioError / system.ratio;
+        return Math.abs(by) > allowed
+            ? [{ copy: copy.id, problem: 'speed-disagrees-with-paper', by }]
+            : [];
+    });
+    return [...unaligned, ...elsewhere, ...beyond, ...speeds];
+};

package/lib/collation/alignment.d.ts

@@ -1,14 +1,34 @@
 import { FeatureOrPatch } from "../model/Feature.js";
-import { RollCopy, Shift } from "../model/RollCopy.js";
+import { Alignment, RollCopy } from "../model/RollCopy.js";
 import { TrackerBar } from "../systems/TrackerBar.js";
 import { Millimeters } from "../model/Quantity.js";
-export declare const applyShift: (shift: Shift, copy: RollCopy) => void;
-/** Scales the copy's features away from the beginning of the roll, and records the factor. */
-export declare const applyScale: (factor: number, copy: RollCopy) => void;
-/** Takes the shift off the copy's features again, as far as one was applied. */
-export declare const revertShift: (copy: RollCopy) => void;
-/** Takes the scale off the copy's features again, as far as one was applied. */
-export declare const revertScale: (copy: RollCopy) => void;
+/** A place on the copy's own paper, on the edition's axis. */
+export declare const toAxis: (alignment: Alignment | undefined) => (place: Millimeters) => Millimeters;
+/** A place on the edition's axis, on the copy's own paper. */
+export declare const fromAxis: (alignment: Alignment | undefined) => (place: Millimeters) => Millimeters;
+/**
+ * Carries the copy's features and tears from its own places onto the
+ * axis, and records how, in place of any alignment it had: that one is
+ * taken off first.
+ */
+export declare const applyAlignment: (alignment: Alignment, copy: RollCopy) => void;
+/** Takes the copy's features and tears back to its own places, as far as it was aligned. */
+export declare const revertAlignment: (copy: RollCopy) => void;
+/**
+ * The copy with its features and tears at its own places, as a document
+ * holds them, and its alignment kept to say how they go onto the axis.
+ * The copy given is left as it is. A copy that is not aligned is the
+ * very same copy.
+ */
+export declare const atOwnPlaces: (copy: RollCopy) => RollCopy;
+/**
+ * Puts the features and tears of a copy read from a document, which
+ * holds them at the copy's own places, onto the axis. The copy given is
+ * changed.
+ */
+export declare const putOnAxis: (copy: RollCopy) => void;
+/** The copy's features at its own places, as it was read, whatever alignment it has. */
+export declare const ownFeaturesOf: (copy: RollCopy) => FeatureOrPatch[];
 /**
  * Takes the extension a pneumatic reader adds off the ends of the
  * copy's chains of holes, and records how much was taken.
@@ -59,6 +79,16 @@ export declare const tooShortToShorten: (extension: Millimeters, copy: RollCopy,
 export declare const shortenChains: (extension: Millimeters, copy: RollCopy, leaving?: ReadonlySet<string>) => void;
 /** Puts the reader's extension back on the chains it was taken off, as far as one was taken off. */
 export declare const revertShortening: (copy: RollCopy) => void;
+/**
+ * The method `alignFeatures` follows, as an alignment records it. Its
+ * 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.
+ */
+export declare const ALIGNMENT_METHOD: {
+    readonly software: 'linked-rolls alignFeatures';
+    readonly version: '1';
+};
 /**
  * How a copy's places are carried onto another copy's:
  * `x_other = (x + shift) · scale`.
@@ -71,6 +101,14 @@ export interface AlignmentResult {
     matched: number;
     /** How far the counterparts still lie apart, as a root mean square in the other copy's millimetres. */
     residual: Millimeters;
+    /**
+     * The standard error of the scale, as for a line of least squares
+     * through the matches: the residual over the spread of the matched
+     * notes along the copy, and over the root of their number. The
+     * robust line is fitted otherwise, but on Welte 225 this comes
+     * within a few per cent of what resampling the matches gives.
+     */
+    scaleError: number;
 }
 /**
  * Finds the shift and scale that carry the places of `rollA` onto those