linked-rolls 0.13.0 → 0.14.0

package/README.md

@@ -33,6 +33,41 @@ the keeper and the production metadata are nodes with a name and
 authority links, and the roll names its reproducing system. Exports
 are always in the current format.
 
+## Where a copy's features come from
+
+`readFrom` states what a copy's features were read from: the roll
+itself, a `scan` of it, an `analysis` somebody else measured on a
+scan, an `emulation` in which the roll has already been read into
+notes and commands, or a `recording` captured while the copy was
+played. Beside the kind it holds who carried the capture out, on what
+device, when, and a note. What is not known is left out.
+
+This says where the numbers of the edition come from and nothing
+about the state of the paper, which is a condition of the copy. In
+RDF it is `reo:capture`, an activity typed by what it read from; the
+file it produced is `crmdig:L11 had output`, the machine it ran on
+`crmdig:L12 happened on device`.
+
+Nothing records that a copy is doubtful. `reservationsAbout` works
+out from what a copy states what the edition cannot vouch for in it:
+that it names no source, that the making of its source is
+undocumented, that its features are somebody else's reading, that its
+source bears no physical evidence, that no measuring software is
+recorded, that it is not calibrated. A reservation goes away when the
+gap it names is filled.
+
+```ts
+import { reservationsAbout, stateSource } from 'linked-rolls'
+
+const next = produce(edition, stateSource(copyId, {
+    kind: 'emulation',
+    output: 'https://example.org/wm225.mid',
+    note: 'MIDI from a third party; the emulator is not named.'
+}))
+
+reservationsAbout(next.copies[0]).map(reservation => reservation.note)
+```
+
 ## Emulation
 
 `Emulation` turns a version of the edition into MIDI. The core of the

package/lib/FeatureSource.d.ts

@@ -0,0 +1,65 @@
+import { ActorAssignment, DateAssignment } from "./Assumption";
+import { Concept } from "./Agent";
+import { WithNote } from "./utils";
+/**
+ * What a copy's features were read from. The kinds run from the paper
+ * itself to a file in which the roll has already been read into notes
+ * and commands.
+ */
+export declare const sourceKinds: readonly ['roll', 'scan', 'analysis', 'emulation', 'recording'];
+export type SourceKind = typeof sourceKinds[number];
+/** How each kind of source is referred to in prose. */
+export declare const sourceLabels: Record<SourceKind, string>;
+/**
+ * Whether a source of this kind gives positions that were measured.
+ * An emulation and a recording give the reading somebody else made:
+ * the roll has been turned into notes and commands already, and
+ * turning those back into holes reconstructs them.
+ */
+export declare const isMeasured: (kind: SourceKind) => boolean;
+/**
+ * Whether a source of this kind bears witness to the paper. Punch
+ * diameter, hole separation, punching pattern, marks and writings can
+ * be observed on the roll and on an image of it, and on nothing else.
+ */
+export declare const bearsPhysicalEvidence: (kind: SourceKind) => boolean;
+/**
+ * The capture by which a copy's features became data: what they were
+ * read from, who read them, on what device and when. It states where
+ * the numbers of the edition come from and says nothing about the
+ * state of the paper, which is a condition.
+ *
+ * What is not known is left out. A reader is told about the gap by
+ * `reservationsAbout`, which works out what a copy cannot vouch for
+ * from what it states here.
+ * @see crm:E7 Activity
+ */
+export interface FeatureSource extends WithNote {
+    /**
+     * What the features were read from.
+     * @see crm:P2 has type
+     */
+    kind: SourceKind;
+    /**
+     * The file the capture produced, where it has an address.
+     * @see crmdig:L11 had output
+     */
+    output?: string;
+    /**
+     * Who carried out the capture.
+     * @see crm:P14 carried out by
+     */
+    actor?: ActorAssignment;
+    /**
+     * The make and model of the scanner, camera or player the capture
+     * ran on.
+     * @see crmdig:L12 happened on device
+     */
+    device?: Concept;
+    /**
+     * When the capture took place.
+     * @format date
+     * @see dcterms:date
+     */
+    date?: DateAssignment;
+}

package/lib/FeatureSource.js

@@ -0,0 +1,35 @@
+/**
+ * What a copy's features were read from. The kinds run from the paper
+ * itself to a file in which the roll has already been read into notes
+ * and commands.
+ */
+export const sourceKinds = [
+    'roll',
+    'scan',
+    'analysis',
+    'emulation',
+    'recording'
+];
+/** How each kind of source is referred to in prose. */
+export const sourceLabels = {
+    roll: 'the roll itself',
+    scan: 'a scan of the roll',
+    analysis: 'a hole analysis of a scan',
+    emulation: 'an emulated MIDI file',
+    recording: 'a MIDI recording of the copy being played'
+};
+const measured = ['roll', 'scan', 'analysis'];
+const physical = ['roll', 'scan'];
+/**
+ * Whether a source of this kind gives positions that were measured.
+ * An emulation and a recording give the reading somebody else made:
+ * the roll has been turned into notes and commands already, and
+ * turning those back into holes reconstructs them.
+ */
+export const isMeasured = (kind) => measured.includes(kind);
+/**
+ * Whether a source of this kind bears witness to the paper. Punch
+ * diameter, hole separation, punching pattern, marks and writings can
+ * be observed on the roll and on an image of it, and on nothing else.
+ */
+export const bearsPhysicalEvidence = (kind) => physical.includes(kind);

package/lib/RollCopy.d.ts

@@ -6,6 +6,7 @@ import { AnyFeature } from "./Feature";
 import { ActorAssignment, DateAssignment, ObjectAssumption } from "./Assumption";
 import { WithId, WithType } from "./utils";
 import { Agent, Concept } from "./Agent";
+import { FeatureSource } from "./FeatureSource";
 import { Measure, Millimeters, Quantity, Track } from "./Quantity";
 /**
  * This condition state is used to describe the roll's
@@ -282,6 +283,13 @@ export interface RollCopy extends WithType<'RollCopy'>, WithId {
      * @see crm:P138i has representation
      */
     scan?: string;
+    /**
+     * What this copy's features were read from. A copy that states no
+     * source is one whose features reached the edition by a way that
+     * was not written down.
+     * @see reo:capture
+     */
+    readFrom?: FeatureSource;
 }
 /**
  * Reads the features of a copy as the tracker bar would read them.

package/lib/editionOps.d.ts

@@ -5,6 +5,7 @@ import { AnySymbol, PlacementRelation } from "./Symbol";
 import { CollationTolerance } from "./Collation";
 import { Edit } from "./Edit";
 import { RollCopy, ScaleReading, Shift } from "./RollCopy";
+import { FeatureSource } from "./FeatureSource";
 import { AnyArgumentation, Certainty } from "./Assumption";
 /**
  * A change to an edition, written onto an immer draft of it. One
@@ -30,6 +31,10 @@ export declare const alignCopy: (copyId: string, shift: Shift, scale: number, re
  * being a fact about the copy.
  */
 export declare const unalignCopy: (copyId: string) => EditionOp;
+/** States what the copy's features were read from, in place of any earlier statement. */
+export declare const stateSource: (copyId: string, source: FeatureSource) => EditionOp;
+/** Takes back the statement, leaving the copy silent about its source again. */
+export declare const clearSource: (copyId: string) => EditionOp;
 /** The symbols of the versions that no other copy carries. */
 export declare const symbolsCarriedOnlyBy: (edition: Edition, copyId: string) => AnySymbol[];
 /** Takes the features off the copy, and out of the versions with what only they carried. */

package/lib/editionOps.js

@@ -96,6 +96,14 @@ export const unalignCopy = (copyId) => onCopy(copyId, copy => {
     revertShift(copy);
     copy.conditions = without(copy.conditions, isPaperStretch);
 });
+/** States what the copy's features were read from, in place of any earlier statement. */
+export const stateSource = (copyId, source) => onCopy(copyId, copy => {
+    copy.readFrom = source;
+});
+/** Takes back the statement, leaving the copy silent about its source again. */
+export const clearSource = (copyId) => onCopy(copyId, copy => {
+    copy.readFrom = undefined;
+});
 const featureIdsOf = (copy) => new Set(copy.features.map(feature => feature.id));
 /**
  * A symbol every carrier of which lies among the features loses its

package/lib/index.d.ts

@@ -14,7 +14,9 @@ export * from './systems/welteT100/bar';
 export * from './systems/welteLicensee/bar';
 export * from './systems';
 export * from './ReproducingSystem';
+export * from './FeatureSource';
 export * from './RollCopy';
+export * from './reservations';
 export * from './alignment';
 export * from './Edition';
 export * from './EditionView';

package/lib/index.js

@@ -14,7 +14,9 @@ export * from './systems/welteT100/bar';
 export * from './systems/welteLicensee/bar';
 export * from './systems';
 export * from './ReproducingSystem';
+export * from './FeatureSource';
 export * from './RollCopy';
+export * from './reservations';
 export * from './alignment';
 export * from './Edition';
 export * from './EditionView';

package/lib/reservations.d.ts

@@ -0,0 +1,23 @@
+import { RollCopy } from "./RollCopy";
+export declare const reservationTypes: readonly ['source-not-stated', 'source-undocumented', 'features-interpreted', 'no-physical-evidence', 'measurement-undocumented', 'not-calibrated'];
+export type ReservationType = typeof reservationTypes[number];
+/**
+ * Something an edition cannot vouch for in one of its copies.
+ *
+ * A reservation is worked out from what the copy states about itself
+ * and is never written into the edition: it says that knowledge of
+ * the copy is incomplete, so filling in what is missing makes it go
+ * away. Nothing here describes the state of the paper, which is a
+ * condition of the copy.
+ */
+export interface Reservation {
+    type: ReservationType;
+    /** What the reservation means for a reader, in one sentence. */
+    note: string;
+}
+/**
+ * What the edition cannot vouch for in a copy, in the order the
+ * checks are listed: where its features came from first, then what
+ * the measurement leaves open.
+ */
+export declare const reservationsAbout: (copy: RollCopy) => Reservation[];

package/lib/reservations.js

@@ -0,0 +1,53 @@
+import { bearsPhysicalEvidence, isMeasured, sourceLabels } from "./FeatureSource";
+import { calibrationOf } from "./RollCopy";
+export const reservationTypes = [
+    'source-not-stated',
+    'source-undocumented',
+    'features-interpreted',
+    'no-physical-evidence',
+    'measurement-undocumented',
+    'not-calibrated'
+];
+const sourceStated = copy => copy.readFrom ? undefined : {
+    type: 'source-not-stated',
+    note: 'The copy does not state what its features were read from.'
+};
+const sourceDocumented = copy => {
+    const source = copy.readFrom;
+    if (!source || source.actor || source.device || source.date)
+        return undefined;
+    return {
+        type: 'source-undocumented',
+        note: `The copy names ${sourceLabels[source.kind]} as its source, but records nobody who made it, no device and no date.`
+    };
+};
+const featuresMeasured = copy => copy.readFrom && !isMeasured(copy.readFrom.kind) ? {
+    type: 'features-interpreted',
+    note: `The features come from ${sourceLabels[copy.readFrom.kind]}, in which the roll has already been read into notes and commands by somebody else.`
+} : undefined;
+const physicalEvidence = copy => copy.readFrom && !bearsPhysicalEvidence(copy.readFrom.kind) ? {
+    type: 'no-physical-evidence',
+    note: 'Punch diameter, hole separation, punching pattern, marks and writings cannot be observed on this source.'
+} : undefined;
+const measurementDocumented = copy => !copy.measurements.measuredBy && copy.readFrom?.kind !== 'roll' ? {
+    type: 'measurement-undocumented',
+    note: 'No measuring software is recorded for this copy.'
+} : undefined;
+const calibrated = copy => calibrationOf(copy) ? undefined : {
+    type: 'not-calibrated',
+    note: 'The copy is not calibrated against the tracker bar, so its track positions rest on the numbering its source used.'
+};
+const checks = [
+    sourceStated,
+    sourceDocumented,
+    featuresMeasured,
+    physicalEvidence,
+    measurementDocumented,
+    calibrated
+];
+/**
+ * What the edition cannot vouch for in a copy, in the order the
+ * checks are listed: where its features came from first, then what
+ * the measurement leaves open.
+ */
+export const reservationsAbout = (copy) => checks.flatMap(check => check(copy) ?? []);

package/lib/schema.json

@@ -543,6 +543,40 @@
             ],
             "type": "string"
         },
+        "FeatureSource": {
+            "description": "The capture by which a copy's features became data: what they were read from, who read them, on what device and when. It states where the numbers of the edition come from and says nothing about the state of the paper, which is a condition.\n\nWhat is not known is left out. A reader is told about the gap by `reservationsAbout`, which works out what a copy cannot vouch for from what it states here. [ontology: crm:E7 Activity]",
+            "properties": {
+                "actor": {
+                    "$ref": "#/definitions/ActorAssignment",
+                    "description": "Who carried out the capture. [ontology: crm:P14 carried out by]"
+                },
+                "date": {
+                    "$ref": "#/definitions/DateAssignment",
+                    "description": "When the capture took place. [ontology: dcterms:date]",
+                    "format": "date"
+                },
+                "device": {
+                    "$ref": "#/definitions/Concept",
+                    "description": "The make and model of the scanner, camera or player the capture ran on. [ontology: crmdig:L12 happened on device]"
+                },
+                "kind": {
+                    "$ref": "#/definitions/SourceKind",
+                    "description": "What the features were read from. [ontology: crm:P2 has type]"
+                },
+                "note": {
+                    "description": "A free-text note providing additional context. [ontology: crm:P3 has note]",
+                    "type": "string"
+                },
+                "output": {
+                    "description": "The file the capture produced, where it has an address. [ontology: crmdig:L11 had output]",
+                    "type": "string"
+                }
+            },
+            "required": [
+                "kind"
+            ],
+            "type": "object"
+        },
         "GluedOn": {
             "description": "A piece of material (paper or tape) glued onto the roll surface. Glued-on features are typically used to cover perforations (for corrections) or to reinforce damaged areas. They may themselves carry other features such as writings or additional holes. [ontology: crm:E22 Human-Made Object]",
             "properties": {
@@ -1816,6 +1850,10 @@
                     "$ref": "#/definitions/ProductionEvent",
                     "description": "The production event that created this roll copy. [ontology: lrmoo:R28i was produced by]"
                 },
+                "readFrom": {
+                    "$ref": "#/definitions/FeatureSource",
+                    "description": "What this copy's features were read from. A copy that states no source is one whose features reached the edition by a way that was not written down. [ontology: reo:capture]"
+                },
                 "scan": {
                     "description": "The scan URL or IIIF URL of the roll. [ontology: crm:P138i has representation]",
                     "type": "string"
@@ -1861,6 +1899,16 @@
             ],
             "type": "object"
         },
+        "SourceKind": {
+            "enum": [
+                "roll",
+                "scan",
+                "analysis",
+                "emulation",
+                "recording"
+            ],
+            "type": "string"
+        },
         "Text": {
             "description": "A textual symbol, e.g. a label or annotation found on the roll. [ontology: crm:E33 Linguistic Object]",
             "properties": {

package/lib/spec/context.json

@@ -165,6 +165,22 @@
             "@id": "crm:P138i_has_representation",
             "@type": "@id"
         },
+        "readFrom": {
+            "@id": "reo:capture",
+            "@context": {
+                "kind": {
+                    "@id": "crm:P2_has_type",
+                    "@type": "@vocab",
+                    "@context": { "@vocab": "https://w3id.org/reo/type/" }
+                },
+                "output": {
+                    "@id": "crmdig:L11_had_output",
+                    "@type": "@id"
+                },
+                "device": "crmdig:L12_happened_on_device",
+                "note": "crm:P3_has_note"
+            }
+        },
         "depiction": {
             "@id": "crm:P138i_has_representation",
             "@type": "@id"

package/package.json

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