linked-rolls 0.72.0 → 0.73.0

package/README.md

@@ -103,7 +103,11 @@ Which versions there are, lost ones included, how they derive from each
 other and which edits belong to which can be proposed from the copies
 alone. `proposeStemma` collates the transcribed copies all at once,
 notes which copies have, lack or cannot show each reading, and scores
-every stemma the copies admit, up to seven copies. A reading arising
+every stemma the copies admit. Copies of one system that differ in no
+more than a few readings, or that the edition gives one version, are
+taken to carry one text, and so one version, as pressings of one master
+do; what one of them lacks is a deviation of that copy. The search
+covers up to seven such texts, however many copies carry them. A reading arising
 costs ten times a reading lost. Losses count for less where the
 editorial principles of an edition say they are weak evidence: a
 redundancy cleaned up, or what a re-cut for another system lacks. On

package/lib/filiation/adoption.js

@@ -47,8 +47,7 @@ export const adoptionOf = (edition, proposal) => {
     const copiesBelow = new Map(proposal.versions.map(proposed => [proposed.id, new Set()]));
     for (const proposed of proposal.versions) {
         for (let at = proposed.id; at !== undefined; at = parentOf.get(at)) {
-            if (proposed.copy)
-                copiesBelow.get(at).add(proposed.copy);
+            proposed.copies.forEach(copy => copiesBelow.get(at).add(copy));
         }
     }
     const arising = new Map();
@@ -92,7 +91,7 @@ export const adoptionOf = (edition, proposal) => {
         const reading = standingFor.get(symbol.id);
         return reading ? { ...symbol, carriers: carriersOf(readingOf.get(reading), symbol.carriers) } : symbol;
     };
-    const idFor = (proposed) => proposed.version ?? v5(`version|${proposed.copy ?? ''}|${[...proposed.inserts].sort().join(',')}`, ADOPTED);
+    const idFor = (proposed) => proposed.version ?? v5(`version|${proposed.copies.join(',')}|${[...proposed.inserts].sort().join(',')}`, ADOPTED);
     const ids = new Map(proposal.versions.map(proposed => [proposed.id, idFor(proposed)]));
     const staying = new Set(ids.values());
     const versions = proposal.versions.map((proposed) => {
@@ -142,7 +141,7 @@ export const adoptionOf = (edition, proposal) => {
         const hypotheses = (before?.basedOn ?? [])
             .filter(other => other !== principal && staying.has(idOf(other)) && idOf(other) !== parent);
         const basedOn = [...(derivation ? [derivation] : []), ...hypotheses];
-        const copy = proposed.copy ? edition.copies.find(copy => copy.id === proposed.copy) : undefined;
+        const copy = edition.copies.find(copy => copy.id === proposed.copies[0]);
         const bar = barNamed(proposed.system);
         const system = copy?.production?.system ?? before?.system ?? (bar ? systemOf(bar) : { id: proposed.system, name: proposed.system, sameAs: [] });
         const { basedOn: _, edits: __, ...rest } = before ?? {};

package/lib/filiation/index.d.ts

@@ -10,3 +10,4 @@ export { transfersOf, systemAbove } from "./systems.js";
 export { proposeStemma, defaultMovedWithin, type FiliationOptions, type ProposedVersion, type StemmaProposal, type Unpinned } from "./proposal.js";
 export { adoptionOf, adoptStemma, type Adoption } from "./adoption.js";
 export { stemmaChanges, type VersionChange } from "./changes.js";
+export { sharedTexts, differencesBetween, defaultSameText, type SharedText, type KeptApart } from "./texts.js";

package/lib/filiation/index.js

@@ -10,3 +10,4 @@ export { transfersOf, systemAbove } from "./systems.js";
 export { proposeStemma, defaultMovedWithin } from "./proposal.js";
 export { adoptionOf, adoptStemma } from "./adoption.js";
 export { stemmaChanges } from "./changes.js";
+export { sharedTexts, differencesBetween, defaultSameText } from "./texts.js";

package/lib/filiation/proposal.d.ts

@@ -8,6 +8,7 @@ import { Millimeters } from "../model/Quantity.js";
 import { CopyCollation, Recoding } from "./readings.js";
 import { PresenceMatrix } from "./presence.js";
 import { Costs, Scored, Support } from "./search.js";
+import { KeptApart, SharedText } from "./texts.js";
 /**
  * How near a reading of the same kind on the other side of the root
  * makes a reading on the less refined side a moved one, where nothing
@@ -34,8 +35,18 @@ export interface FiliationOptions {
     movedWithin?: Millimeters;
     /** How far beyond its text, or the edge of a tear, a copy cannot say what it lacks (3 mm). */
     margin?: Millimeters;
-    /** Whether the edits the editor wrote hold their versions to what they insert and delete (yes). */
+    /**
+     * Whether the editor's decisions hold (yes): the edits the editor
+     * wrote hold their versions to what they insert and delete, and
+     * copies the edition gives one version carry one text.
+     */
     pin?: boolean;
+    /**
+     * How many readings two copies of one system may differ in and still
+     * be taken to carry the same text (`defaultSameText`). Below zero,
+     * only what the edition states is taken for one text.
+     */
+    sameText?: number;
     /** How many runners-up to report (5). */
     alternatives?: number;
 }
@@ -46,8 +57,8 @@ export interface FiliationOptions {
 export interface ProposedVersion {
     /** A name within the proposal: the versions are numbered from the root down. */
     id: string;
-    /** The copy carrying the version at first hand; none for a lost state. */
-    copy?: string;
+    /** The copies carrying the version at first hand; none for a lost state. */
+    copies: string[];
     /** The system the version is coded for, by its identifier. */
     system: string;
     /** The version it derives from, by its name within the proposal. */
@@ -60,8 +71,11 @@ export interface ProposedVersion {
     deletes: string[];
     /** The held commands that stand for a latched pair, among what the version inserts and deletes. */
     recodings: Recoding[];
-    /** The readings the version holds that the copy carrying it lacks. */
-    deviations: string[];
+    /** The readings the version holds that a copy carrying it lacks. */
+    deviations: {
+        copy: string;
+        reading: string;
+    }[];
     /** The edits the editor wrote on `version` that the proposal keeps as they are. */
     pinned: string[];
 }
@@ -83,6 +97,11 @@ export type Unpinned = {
  */
 export interface StemmaProposal {
     copies: string[];
+    /** The copies grouped by the text they carry, each group one version of the stemma. */
+    texts: SharedText[];
+    /** The closest copies of one system that were kept apart, closest first. */
+    apart: KeptApart[];
+    sameText: number;
     costs: Costs;
     movedWithin: Millimeters;
     margin: Millimeters;

package/lib/filiation/proposal.js

@@ -10,6 +10,7 @@ import { defaultMargin, presenceIn } from "./presence.js";
 import { defaultCosts, searchStemmata, statesOf } from "./search.js";
 import { barNamed, transfersOf } from "./systems.js";
 import { MAX_COPIES } from "./trees.js";
+import { defaultSameText, sharedTexts } from "./texts.js";
 /**
  * How near a reading of the same kind on the other side of the root
  * makes a reading on the less refined side a moved one, where nothing
@@ -101,16 +102,16 @@ const deleting = (tree, states, v) => !states[v] && tree.parent[v] >= 0 && state
  * a reading of the same kind within the window and this branch does not
  * (moved), or where it is ineffective (cleaned up, as redundancies are).
  */
-const baseTextOf = (tree, readings, matrix, placement, held, within, systems) => {
+const baseTextOf = (tree, readings, matrix, placement, held, within, texts, systems) => {
     const root = tree.copy.length - 1;
     const children = childrenOf(tree)[root];
     if (tree.copy[root] >= 0 || children.length !== 2)
         return [];
-    const copiesBelow = (v) => matrix.copies.filter((_, c) => tree.below[v] & (1 << c));
+    const copiesBelow = (v) => texts.filter((_, t) => tree.below[v] & (1 << t)).flat();
     const rootSystem = tree.system[root];
-    /** How many dynamic perforations the copies of the root's system below the node carry, on average. */
+    /** How many expression perforations the copies of the root's system below the node carry, on average. */
     const densityOf = (v) => {
-        const copies = matrix.copies.filter((_, c) => (tree.below[v] & (1 << c)) && systems[c] === rootSystem);
+        const copies = texts.filter((_, t) => (tree.below[v] & (1 << t)) && systems[t] === rootSystem).flat();
         if (copies.length === 0)
             return Infinity;
         const counts = copies.map(copy => readings.filter(reading => reading.meaning.type === 'expression' && matrix.presence[reading.id][copy] === 'present').length);
@@ -185,23 +186,36 @@ export const proposeStemma = (edition, options = {}) => {
     const copies = transcribed(edition).filter(id => !options.copies || options.copies.includes(id));
     if (copies.length < 2)
         throw new Error('A stemma needs at least two copies with features');
-    if (copies.length > MAX_COPIES)
-        throw new Error(`The exhaustive search covers at most ${MAX_COPIES} copies`);
     const costs = { ...defaultCosts, ...options.costs };
     const movedWithin = options.movedWithin ?? defaultMovedWithin;
     const margin = options.margin ?? defaultMargin;
+    const sameText = options.sameText ?? defaultSameText;
     const copyOf = new Map(edition.copies.map(copy => [copy.id, copy]));
-    const names = copies.map(id => copyOf.get(id).siglum ?? id);
-    const systems = copies.map(id => barOf(copyOf.get(id)).id);
+    const systemOfCopy = new Map(copies.map(id => [id, barOf(copyOf.get(id)).id]));
     const transfers = transfersOf();
+    const firstHandOf = (copy) => versionsWitnessedBy(edition, copy)
+        .find(witness => witness.by === 'carriers' && witness.through === undefined)?.version;
     const collation = collateCopies(edition, copies);
     const matrix = presenceIn(edition, collation, margin);
+    // Copies carrying one text are one version, and the search is over texts.
+    const stated = options.pin === false ? [] : [...Map.groupBy(copies.flatMap(copy => { const version = firstHandOf(copy); return version ? [{ copy, version }] : []; }), ({ version }) => version).values()].map(group => group.map(({ copy }) => copy));
+    const shared = sharedTexts(matrix, copies.map(copy => systemOfCopy.get(copy)), sameText, stated);
+    const texts = shared.texts.map(text => text.copies);
+    if (texts.length > MAX_COPIES) {
+        throw new Error(`The exhaustive search covers at most ${MAX_COPIES} different texts, and these copies carry ${texts.length}`);
+    }
+    const names = texts.map(text => text.map(id => copyOf.get(id).siglum ?? id).join('+'));
+    const systems = texts.map(text => systemOfCopy.get(text[0]));
     const redundant = new Set(matrix.redundant);
+    const textPresence = (reading, text) => {
+        const each = text.map(copy => matrix.presence[reading][copy]);
+        return each.includes('present') ? 'present' : each.includes('absent') ? 'absent' : 'unknown';
+    };
     const rows = collation.readings.map(reading => ({
-        presence: copies.map(copy => matrix.presence[reading.id][copy]),
+        presence: texts.map(text => textPresence(reading.id, text)),
         redundant: redundant.has(reading.id)
     }));
-    const search = searchStemmata(copies, names, systems, rows, costs, transfers, options.alternatives ?? 5);
+    const search = searchStemmata(texts, names, systems, rows, costs, transfers, options.alternatives ?? 5);
     const tree = search.best;
     const size = tree.copy.length;
     const place = (fixed) => {
@@ -226,14 +240,13 @@ export const proposeStemma = (edition, options = {}) => {
     const standsFor = new Map();
     const claimed = new Set();
     for (let v = 0; v < size; v++) {
-        const copy = tree.copy[v];
-        if (copy < 0)
+        const text = tree.copy[v];
+        if (text < 0)
             continue;
-        const firstHand = versionsWitnessedBy(edition, copies[copy])
-            .find(witness => witness.by === 'carriers' && witness.through === undefined);
-        if (firstHand && !claimed.has(firstHand.version)) {
-            standsFor.set(v, firstHand.version);
-            claimed.add(firstHand.version);
+        const firstHand = texts[text].map(firstHandOf).find(version => version !== undefined && !claimed.has(version));
+        if (firstHand) {
+            standsFor.set(v, firstHand);
+            claimed.add(firstHand);
         }
     }
     const insertsAt = (placement, v) => collation.readings.filter(reading => inserting(tree, placement.get(reading.id), v)).map(reading => symbols[reading.id] ?? reading.id);
@@ -306,7 +319,7 @@ export const proposeStemma = (edition, options = {}) => {
     }
     const { placement, failed } = place(fixed);
     const held = new Set([...fixed.keys()].filter(reading => !failed.has(reading)));
-    const baseText = baseTextOf(tree, collation.readings, matrix, placement, held, movedWithin, systems);
+    const baseText = baseTextOf(tree, collation.readings, matrix, placement, held, movedWithin, texts, systems);
     recode(tree, collation.readings, placement);
     for (const [v, edits] of pins) {
         for (const { edit, readings } of edits) {
@@ -334,14 +347,13 @@ export const proposeStemma = (edition, options = {}) => {
                 return fits;
             })
             : [];
-        const copy = tree.copy[v];
-        const inner = copy >= 0 && tree.below[v] !== 1 << copy;
-        const deviations = inner
-            ? collation.readings.filter(reading => placement.get(reading.id)[v] && matrix.presence[reading.id][copies[copy]] === 'absent').map(reading => reading.id)
-            : [];
+        const carrying = tree.copy[v] >= 0 ? texts[tree.copy[v]] : [];
+        const deviations = carrying.flatMap(copy => collation.readings
+            .filter(reading => placement.get(reading.id)[v] && matrix.presence[reading.id][copy] === 'absent')
+            .map(reading => ({ copy, reading: reading.id })));
         return {
             id: nameOf.get(v),
-            ...(copy >= 0 && { copy: copies[copy] }),
+            copies: [...carrying],
             system: tree.system[v],
             ...(tree.parent[v] >= 0 && { parent: nameOf.get(tree.parent[v]) }),
             ...(standsFor.has(v) && { version: standsFor.get(v) }),
@@ -357,6 +369,9 @@ export const proposeStemma = (edition, options = {}) => {
         .filter(({ versions }) => versions.length > 1);
     return {
         copies,
+        texts: shared.texts,
+        apart: shared.apart,
+        sameText,
         costs,
         movedWithin,
         margin,

package/lib/filiation/search.d.ts

@@ -79,8 +79,12 @@ export interface Scored {
 export interface Support {
     /** The copies the grouping holds, as the copies of a node and those below it. */
     copies: string[];
-    /** Whether it is the grouping of a copy carrying a version above others, rather than of the copies below a node. */
-    ancestor?: string;
+    /**
+     * Where it is the grouping of a version carried by copies and lying
+     * above others, rather than of the copies below a node: the copies
+     * carrying that version.
+     */
+    ancestor?: string[];
     margin: number;
 }
 /** The outcome of the search. */
@@ -92,12 +96,13 @@ export interface Search {
     supports: Support[];
 }
 /**
- * Scores every stemma of the copies and keeps the best, the runners-up
- * and, for each grouping of the best, the best stemma without it. Ties
- * go to fewer lost states, then to the notation, so that the outcome
- * depends on nothing but the copies and the costs.
+ * Scores every stemma of the texts, each carried by one copy or by
+ * several, and keeps the best, the runners-up and, for each grouping of
+ * the best, the best stemma without it. Ties go to fewer lost states,
+ * then to the notation, so that the outcome depends on nothing but the
+ * copies and the costs.
  */
-export declare const searchStemmata: (copies: readonly string[], names: readonly string[], systems: readonly string[], rows: readonly {
+export declare const searchStemmata: (texts: readonly (readonly string[])[], names: readonly string[], systems: readonly string[], rows: readonly {
     presence: readonly Presence[];
     redundant: boolean;
 }[], costs: Costs, transfers: ReadonlyMap<string, ReadonlySet<string>>, keep: number) => Search;

package/lib/filiation/search.js

@@ -138,13 +138,14 @@ const scoreOf = (tree, classes, costs, absent, present) => {
 };
 const before = (a, b) => a.cost < b.cost - 1e-9 || (Math.abs(a.cost - b.cost) <= 1e-9 && (a.lost < b.lost || (a.lost === b.lost && a.notation < b.notation)));
 /**
- * Scores every stemma of the copies and keeps the best, the runners-up
- * and, for each grouping of the best, the best stemma without it. Ties
- * go to fewer lost states, then to the notation, so that the outcome
- * depends on nothing but the copies and the costs.
+ * Scores every stemma of the texts, each carried by one copy or by
+ * several, and keeps the best, the runners-up and, for each grouping of
+ * the best, the best stemma without it. Ties go to fewer lost states,
+ * then to the notation, so that the outcome depends on nothing but the
+ * copies and the costs.
  */
-export const searchStemmata = (copies, names, systems, rows, costs, transfers, keep) => {
-    const n = copies.length;
+export const searchStemmata = (texts, names, systems, rows, costs, transfers, keep) => {
+    const n = texts.length;
     const classes = classesOf(rows, n, costs);
     const pool = 2 * n;
     const absent = Array.from({ length: pool }, () => new Float64Array(classes.weight.length));
@@ -189,7 +190,7 @@ export const searchStemmata = (copies, names, systems, rows, costs, transfers, k
         throw new Error('No stemma of these copies is admissible');
     const best = top[0];
     const supports = [];
-    const named = (mask) => copies.filter((_, c) => mask & (1 << c));
+    const named = (mask) => texts.filter((_, c) => mask & (1 << c)).flat();
     const seen = new Set();
     for (let v = 0; v < best.tree.copy.length; v++) {
         const mask = best.tree.below[v];
@@ -203,7 +204,7 @@ export const searchStemmata = (copies, names, systems, rows, costs, transfers, k
             supports.push({ copies: named(mask), margin: without[mask] - best.cost });
         }
         if (copy >= 0)
-            supports.push({ copies: named(mask), ancestor: copies[copy], margin: notAncestor[copy] - best.cost });
+            supports.push({ copies: named(mask), ancestor: [...texts[copy]], margin: notAncestor[copy] - best.cost });
     }
     return {
         best: best.tree,

package/lib/filiation/texts.d.ts

@@ -0,0 +1,54 @@
+/** Which copies carry the same text, and so one version between them. */
+import { PresenceMatrix } from "./presence.js";
+/**
+ * Copies taken to carry one text: copies of one system, punched from one
+ * master, that differ in no more readings than a transcription and the
+ * wear of a copy explain.
+ * @category Filiation
+ */
+export interface SharedText {
+    /** The copies, in the order the proposal was given them. */
+    copies: string[];
+    /** The most readings any two of them differ in, where both can tell. */
+    differences: number;
+    /** Whether the edition says so: the copies carry one version at first hand there. */
+    stated: boolean;
+}
+/**
+ * Two copies of one system the proposal keeps apart, and how many
+ * readings they differ in, for the closest pairs: what was near being
+ * taken for one text.
+ * @category Filiation
+ */
+export interface KeptApart {
+    copies: [string, string];
+    differences: number;
+}
+/**
+ * How many readings two copies of one system may differ in and still be
+ * taken to carry the same text, where nothing else is said. A version
+ * can differ from the one it derives from by a handful of edits: WM 225's
+ * L2 differs from R4 in seven readings. Copies punched from one master,
+ * transcribed with care, differ in fewer.
+ * @category Filiation
+ */
+export declare const defaultSameText = 3;
+/** In how many readings the two copies differ where both can tell: one has it, the other lacks it. */
+export declare const differencesBetween: (matrix: PresenceMatrix, one: string, other: string) => number;
+/**
+ * The copies in groups that carry the same text.
+ *
+ * Copies of different systems never carry one text, since a version is a
+ * reading in one system's words. Copies the edition gives one version at
+ * first hand stay together (`stated`). Beyond that, the two groups whose
+ * copies differ least are joined first, as long as every copy of the one
+ * differs from every copy of the other in no more than `within` readings
+ * where both can tell, so that a chain of small differences never joins
+ * copies far apart. Ties go to the order the copies were given in.
+ * `within` below zero joins only what the edition states.
+ * @category Filiation
+ */
+export declare const sharedTexts: (matrix: PresenceMatrix, systems: readonly string[], within: number, stated?: readonly (readonly string[])[]) => {
+    texts: SharedText[];
+    apart: KeptApart[];
+};

package/lib/filiation/texts.js

@@ -0,0 +1,96 @@
+/**
+ * How many readings two copies of one system may differ in and still be
+ * taken to carry the same text, where nothing else is said. A version
+ * can differ from the one it derives from by a handful of edits: WM 225's
+ * L2 differs from R4 in seven readings. Copies punched from one master,
+ * transcribed with care, differ in fewer.
+ * @category Filiation
+ */
+export const defaultSameText = 3;
+/** In how many readings the two copies differ where both can tell: one has it, the other lacks it. */
+export const differencesBetween = (matrix, one, other) => {
+    let count = 0;
+    for (const presence of Object.values(matrix.presence)) {
+        const a = presence[one];
+        const b = presence[other];
+        if ((a === 'present' && b === 'absent') || (a === 'absent' && b === 'present'))
+            count++;
+    }
+    return count;
+};
+/**
+ * The copies in groups that carry the same text.
+ *
+ * Copies of different systems never carry one text, since a version is a
+ * reading in one system's words. Copies the edition gives one version at
+ * first hand stay together (`stated`). Beyond that, the two groups whose
+ * copies differ least are joined first, as long as every copy of the one
+ * differs from every copy of the other in no more than `within` readings
+ * where both can tell, so that a chain of small differences never joins
+ * copies far apart. Ties go to the order the copies were given in.
+ * `within` below zero joins only what the edition states.
+ * @category Filiation
+ */
+export const sharedTexts = (matrix, systems, within, stated = []) => {
+    const copies = matrix.copies;
+    const index = new Map(copies.map((copy, i) => [copy, i]));
+    const distance = copies.map((one, i) => copies.map((other, j) => i === j ? 0 : j < i ? NaN : differencesBetween(matrix, one, other)));
+    const between = (i, j) => i < j ? distance[i][j] : distance[j][i];
+    const groupOf = copies.map((_, i) => i);
+    const members = new Map(copies.map((_, i) => [i, [i]]));
+    const statedGroups = new Set();
+    const join = (a, b) => {
+        const [keep, drop] = a < b ? [a, b] : [b, a];
+        for (const i of members.get(drop))
+            groupOf[i] = keep;
+        members.set(keep, [...members.get(keep), ...members.get(drop)].sort((x, y) => x - y));
+        members.delete(drop);
+    };
+    for (const group of stated) {
+        const known = group.map(copy => index.get(copy)).filter((i) => i !== undefined);
+        for (const i of known.slice(1)) {
+            if (systems[i] !== systems[known[0]] || groupOf[i] === groupOf[known[0]])
+                continue;
+            join(groupOf[i], groupOf[known[0]]);
+        }
+        if (known.length > 1)
+            statedGroups.add(groupOf[known[0]]);
+    }
+    const pairs = [];
+    for (let i = 0; i < copies.length; i++) {
+        for (let j = i + 1; j < copies.length; j++) {
+            if (systems[i] === systems[j])
+                pairs.push({ i, j, d: between(i, j) });
+        }
+    }
+    pairs.sort((a, b) => a.d - b.d || a.i - b.i || a.j - b.j);
+    if (within >= 0) {
+        for (const { i, j, d } of pairs) {
+            if (d > within)
+                break;
+            const a = groupOf[i];
+            const b = groupOf[j];
+            if (a === b)
+                continue;
+            const close = members.get(a).every(x => members.get(b).every(y => between(x, y) <= within));
+            if (!close)
+                continue;
+            const wasStated = statedGroups.has(a) || statedGroups.has(b);
+            join(a, b);
+            if (wasStated)
+                statedGroups.add(Math.min(a, b));
+        }
+    }
+    const texts = [...members.entries()]
+        .sort(([a], [b]) => a - b)
+        .map(([group, list]) => ({
+        copies: list.map(i => copies[i]),
+        differences: Math.max(0, ...list.flatMap(x => list.filter(y => y > x).map(y => between(x, y)))),
+        stated: statedGroups.has(group)
+    }));
+    const apart = pairs
+        .filter(({ i, j }) => groupOf[i] !== groupOf[j])
+        .slice(0, 5)
+        .map(({ i, j, d }) => ({ copies: [copies[i], copies[j]], differences: d }));
+    return { texts, apart };
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "linked-rolls",
-  "version": "0.72.0",
+  "version": "0.73.0",
   "description": "Digital editions of piano rolls: import, collation, editorial assumptions, JSON-LD export, and emulation through a reproducing system",
   "license": "MIT",
   "repository": {