linked-rolls 0.62.0 → 0.63.0

package/lib/schema.json

@@ -58,6 +58,64 @@
             ],
             "description": "The role an agent plays in the context of the edition."
         },
+        "Alignment": {
+            "description": "How the copy's own places are carried onto the edition's axis, which is the millimetres of its reference copy (`Edition.referenceCopy`):\n\n    x_axis = (x + shift.horizontal) · scale     track_axis = track + shift.vertical\n\nIt is found, not given: `alignCopy` matches the copy's notes with the reference copy's and records what it found, and can find it again. The document holds the copy's features and tears at its own places, as they were read, and this beside them; `importJsonLd` puts them onto the axis and `asJsonLd` takes them back, so that within the library every place along the roll is a place on the axis.\n\nWhat the scale is put down to, the paper or the speed the copy was cut for, is worked out from all the alignments together (`paperOf`). Not exported to RDF.",
+            "properties": {
+                "against": {
+                    "description": "The copy it was found against, by id: the edition's reference copy at the time. Left out by alignments recorded before this was.",
+                    "type": "string"
+                },
+                "foundBy": {
+                    "description": "The software that found it, and when.",
+                    "properties": {
+                        "date": {
+                            "description": "The day it was found.",
+                            "format": "date",
+                            "type": "string"
+                        },
+                        "software": {
+                            "description": "The name of the method.",
+                            "type": "string"
+                        },
+                        "version": {
+                            "description": "Its revision (`ALIGNMENT_METHOD`).",
+                            "type": "string"
+                        }
+                    },
+                    "required": [
+                        "software",
+                        "version",
+                        "date"
+                    ],
+                    "type": "object"
+                },
+                "matched": {
+                    "description": "How many notes of the copy found their counterpart on the reference copy.",
+                    "type": "number"
+                },
+                "residual": {
+                    "$ref": "#/definitions/Millimeters",
+                    "description": "How far the counterparts still lie apart, as a root mean square in millimetres of the axis."
+                },
+                "scale": {
+                    "description": "Own millimetres to the axis's, applied after the shift.",
+                    "type": "number"
+                },
+                "scaleError": {
+                    "description": "The standard error of the scale: the residual over the spread of the matched notes along the roll, as for a line of least squares.",
+                    "type": "number"
+                },
+                "shift": {
+                    "$ref": "#/definitions/Shift",
+                    "description": "Applied before the scale."
+                }
+            },
+            "required": [
+                "shift",
+                "scale"
+            ],
+            "type": "object"
+        },
         "AnyArgumentation": {
             "anyOf": [
                 {
@@ -169,7 +227,7 @@
             "ontology": "crminf:I2 Belief"
         },
         "BeliefAdoption": {
-            "description": "A belief adoption adopts someone else's belief. This type is used to indicate e.g. knowledge through private communication or from secondary literature, or a belief published elsewhere under an IRI of its own, such as a premise from a catalogue of premises.",
+            "description": "A belief adoption takes over someone else's belief without checking it: knowledge through private communication, from the secondary literature, or from another edition. Like every reason, it concludes the belief it is a reason of, which is the edition's own and holds of the edition's statement what the adopted belief held. An inference that relies on it names that belief among its premises.\n\nThe editor's own beliefs need no adoption, wherever they are published: an inference names them directly (see `Inference`).",
             "properties": {
                 "actor": {
                     "$ref": "#/definitions/Person",
@@ -177,7 +235,7 @@
                     "ontology": "crm:P14 carried out by"
                 },
                 "adopted": {
-                    "description": "The beliefs this adoption takes over, by IRI, where they are published with one. An inference that uses such a belief names it among its premises by the same IRI; the adoption says where it comes from.",
+                    "description": "The beliefs this adoption takes over, by IRI, where they are published with one. They are someone else's, and stay theirs: what the edition holds is the belief the adoption concludes.",
                     "items": {
                         "type": "string"
                     },
@@ -568,6 +626,10 @@
                     "type": "string",
                     "ontology": "dcterms:license"
                 },
+                "referenceCopy": {
+                    "description": "The copy whose millimetres are the edition's axis, by id: every place the edition gives along the roll is a place on this copy's paper, counted from where its scan begins, and every other copy is aligned onto it. Choosing it is the one editorial decision the alignment leaves; a copy scanned whole and without tears serves best, since its places are what notes and readers cite. Left out, it is the first copy with features that is not aligned (`referenceCopyOf`). Not exported to RDF.",
+                    "type": "string"
+                },
                 "roll": {
                     "$ref": "#/definitions/Roll",
                     "description": "The roll which is edited in this edition.",
@@ -898,7 +960,7 @@
                     "ontology": "crm:P3 has note"
                 },
                 "premises": {
-                    "description": "References (by `@id`) to the beliefs from which the conclusion is drawn.",
+                    "description": "References (by `@id`) to the beliefs from which the conclusion is drawn.\n\nA belief the editor holds and publishes elsewhere under an IRI of its own, such as a bound from a catalogue of premises the editor keeps, is named by that IRI. Someone else's belief is not: it is adopted first, and the belief of the edition's own that the adoption concludes is named instead.",
                     "items": {
                         "type": "string"
                     },
@@ -906,7 +968,7 @@
                     "ontology": "crminf:J1 used as premise"
                 },
                 "used": {
-                    "description": "References (by `@id`) to what the inference worked on besides beliefs, such as the versions it compared or the analysis output it cites.",
+                    "description": "References (by `@id`) to what the inference worked on besides beliefs, such as the versions it compared, the analysis output it cites, or the document holding a premise named by IRI, in the state it was read in, since a belief published elsewhere may move after the edition has used it.",
                     "items": {
                         "type": "string"
                     },
@@ -1687,7 +1749,7 @@
             "type": "object",
             "ontology": "reo:Note"
         },
-        "ObjectAssumption<(GeneralRollCondition|PaperStretch)>": {
+        "ObjectAssumption<(GeneralRollCondition|PaperStretch|Tear)>": {
             "anyOf": [
                 {
                     "properties": {
@@ -1748,6 +1810,16 @@
                             ],
                             "type": "object"
                         },
+                        "across": {
+                            "$ref": "#/definitions/Strain",
+                            "description": "The strain across the roll. Paper stretches more across than along, so this is no measure of the other.",
+                            "ontology": "reo:strainAcross"
+                        },
+                        "along": {
+                            "$ref": "#/definitions/Strain",
+                            "description": "The strain along the roll, the direction the alignment measures.",
+                            "ontology": "reo:strainAlong"
+                        },
                         "conditionType": {
                             "const": "paper-stretch",
                             "description": "The kind of condition, from the list the roll or the kind of feature allows.",
@@ -1758,16 +1830,73 @@
                             "description": "A free-text description of the condition, providing details beyond the type classification.",
                             "type": "string",
                             "ontology": "crm:P3 has note"
+                        }
+                    },
+                    "required": [
+                        "conditionType"
+                    ],
+                    "type": "object"
+                },
+                {
+                    "properties": {
+                        "@annotation": {
+                            "description": "An optional annotation expressing a belief about this assumption. Uses the JSON-LD-star `@annotation` mechanism to attach epistemic metadata (certainty and reasons) to any triple.",
+                            "properties": {
+                                "belief": {
+                                    "$ref": "#/definitions/Belief",
+                                    "description": "The belief held about the annotated statement.",
+                                    "ontology": "crminf:J4i is subject of"
+                                },
+                                "@id": {
+                                    "description": "A unique identifier for this object.",
+                                    "type": "string"
+                                }
+                            },
+                            "required": [
+                                "belief",
+                                "@id"
+                            ],
+                            "type": "object"
                         },
-                        "factor": {
-                            "description": "The stretch factor, e.g. 1.02 means the paper has stretched by 2% compared to its original dimensions.",
-                            "type": "number",
-                            "ontology": "rdf:value"
+                        "conditionType": {
+                            "const": "torn",
+                            "description": "The kind of condition, from the list the roll or the kind of feature allows.",
+                            "type": "string",
+                            "ontology": "crm:P2 has type"
+                        },
+                        "depiction": {
+                            "description": "IIIF region pointing to a depiction of the tear in the scan.",
+                            "type": "string",
+                            "ontology": "crm:P138i has representation"
+                        },
+                        "depth": {
+                            "$ref": "#/definitions/Measure%3C%22mm%22%3E",
+                            "description": "How far the tear reaches into the paper, taken across the roll from the edge it runs in from.",
+                            "ontology": "reo:depth"
+                        },
+                        "description": {
+                            "description": "A free-text description of the condition, providing details beyond the type classification.",
+                            "type": "string",
+                            "ontology": "crm:P3 has note"
+                        },
+                        "edge": {
+                            "description": "The edge of the paper the tear runs in from, where it runs in from one.",
+                            "enum": [
+                                "bass",
+                                "treble"
+                            ],
+                            "type": "string",
+                            "ontology": "reo:edge"
+                        },
+                        "horizontal": {
+                            "$ref": "#/definitions/HorizontalSpan",
+                            "description": "Where along the roll the tear lies, measured as the copy's features are, so that it moves with them when the copy is aligned.",
+                            "ontology": "reo:horizontal"
                         }
                     },
                     "required": [
                         "conditionType",
-                        "factor"
+                        "horizontal"
                     ],
                     "type": "object"
                 }
@@ -2751,6 +2880,10 @@
             "type": "object",
             "ontology": "reo:Patch"
         },
+        "Percent": {
+            "$ref": "#/definitions/Quantity%3C%22percent%22%3E",
+            "description": "A share of a length, such as how far the paper has stretched: dimensionless, in hundredths."
+        },
         "Perforator": {
             "description": "The machine that punched the copy. It stands for this production alone. Whether it is the one another copy was punched on is left to a statement of identity made about it elsewhere, which its id allows.",
             "properties": {
@@ -2883,7 +3016,7 @@
                 },
                 "speed": {
                     "$ref": "#/definitions/ObjectAssumption%3CPaperSpeed%3E",
-                    "description": "The paper speed the copy was cut for. A copy cut from the same master for another speed comes out longer or shorter than the roll it is aligned with by the ratio of the speeds, which is what the alignment then measures.",
+                    "description": "The paper speed the copy was cut for. A copy cut from the same master for another speed comes out longer or shorter than the roll it is aligned with by the ratio of the speeds. The alignment measures that ratio far more closely than a label states a speed, so the speed is held against what the alignments give (`alignmentProblems`) rather than used to find it.",
                     "ontology": "reo:paperSpeed"
                 },
                 "system": {
@@ -2907,6 +3040,9 @@
         "Quantity<\"mm\">": {
             "type": "number"
         },
+        "Quantity<\"percent\">": {
+            "type": "number"
+        },
         "Quantity<\"px\">": {
             "type": "number"
         },
@@ -3020,8 +3156,8 @@
             "ontology": "lrmoo:F1 Work"
         },
         "RollConditionAssignment": {
-            "$ref": "#/definitions/ObjectAssumption%3C(GeneralRollCondition%7CPaperStretch)%3E",
-            "description": "An assignment of a condition (general or paper-stretch) to a roll copy, annotatable with a belief about its certainty."
+            "$ref": "#/definitions/ObjectAssumption%3C(GeneralRollCondition%7CPaperStretch%7CTear)%3E",
+            "description": "An assignment of a condition (general, paper-stretch or a tear) to a roll copy, annotatable with a belief about its certainty."
         },
         "RollCopy": {
             "description": "A physical copy of a roll, held at a specific location. Each roll copy has its own measurements, conditions and modifications, and states its features in the act that brought each of them about. Multiple copies of the same roll may exist across different archives or collections.",
@@ -3035,7 +3171,7 @@
                     "ontology": "crm:P128 carries"
                 },
                 "conditions": {
-                    "description": "Condition assessments of this roll copy (e.g. paper stretch, general wear). Each condition is an assumption annotatable with a belief.",
+                    "description": "Condition assessments of this roll copy (e.g. paper stretch, general wear, a tear). Each condition is an assumption annotatable with a belief.",
                     "items": {
                         "$ref": "#/definitions/RollConditionAssignment"
                     },
@@ -3048,8 +3184,12 @@
                     "ontology": "crm:P50 has current keeper"
                 },
                 "measurements": {
-                    "description": "Physical measurements of this roll copy, including dimensions, hole separation, margins, shift corrections, and information about the measuring software. What the perforations tell about the machine that cut them is stated with the production.",
+                    "description": "Physical measurements of this roll copy, including dimensions, hole separation, margins, the alignment onto the edition's axis, and information about the measuring software. What the perforations tell about the machine that cut them is stated with the production.",
                     "properties": {
+                        "alignment": {
+                            "$ref": "#/definitions/Alignment",
+                            "description": "How the copy's places are carried onto the edition's axis. Left out for the reference copy, whose places are the axis, and for a copy not aligned yet. Not exported to RDF."
+                        },
                         "dimensions": {
                             "description": "The physical dimensions of the roll.",
                             "properties": {
@@ -3149,19 +3289,11 @@
                             ],
                             "type": "object"
                         },
-                        "scale": {
-                            "description": "The factor this copy's features were scaled by to align them with the others. What it is put down to is stated apart: a paper-stretch condition, or the speed the copy was cut for. Not exported to RDF.",
-                            "type": "number"
-                        },
                         "scanResolution": {
                             "$ref": "#/definitions/Measure%3C%22px%2Fin%22%3E",
                             "description": "The resolution this copy's scan was read at, along the roll. It is what the measurements given in pixels are to be read against, and what every conversion between a place in the scan and one on the paper goes through. A scanner may read across the roll at another resolution, which the analysis files do not state.",
                             "ontology": "reo:scanResolution"
                         },
-                        "shift": {
-                            "$ref": "#/definitions/Shift",
-                            "description": "The shift applied to align this copy with the others. Not exported to RDF."
-                        },
                         "trackCalibration": {
                             "$ref": "#/definitions/TrackCalibration",
                             "description": "Relates this copy's scan to the tracker bar: how the scanning software's hole numbering was shifted onto the bar, and where the track grid sits in the image. Not exported to RDF."
@@ -3227,7 +3359,7 @@
             "ontology": "reo:RollCopy"
         },
         "Shift": {
-            "description": "A shift correction applied to a roll copy to align it with other copies. The shift is defined as horizontal (along the roll length, in mm) and vertical (across tracks).",
+            "description": "How far an alignment moves a copy's places before it scales them: along the roll, in the copy's own millimetres, and across it, in tracks.",
             "properties": {
                 "horizontal": {
                     "$ref": "#/definitions/Millimeters",
@@ -3274,6 +3406,33 @@
             ],
             "type": "string"
         },
+        "Strain": {
+            "description": "How far the paper has stretched, or shrunk where it is negative, since it was perforated, as a share of its length then: the strain ΔL / L. It is a ratio of two lengths and so has no unit of its own, and it is stated in per cent because what paper does is a matter of tenths of one. It is taken in one direction, along the roll or across it, since machine-made paper does not stretch the same way in both.",
+            "properties": {
+                "uncertainty": {
+                    "$ref": "#/definitions/Percent",
+                    "description": "The standard uncertainty of the value, one standard deviation. Left out where the measurement gave none, which leaves it no more precise than paper is known to vary.",
+                    "ontology": "reo:uncertainty"
+                },
+                "unit": {
+                    "const": "percent",
+                    "description": "The unit of measurement.",
+                    "type": "string",
+                    "ontology": "crm:P91 has unit"
+                },
+                "value": {
+                    "$ref": "#/definitions/Quantity%3C%22percent%22%3E",
+                    "description": "The measured value.",
+                    "ontology": "crm:P90 has value"
+                }
+            },
+            "required": [
+                "unit",
+                "value"
+            ],
+            "type": "object",
+            "ontology": "crm:E54 Dimension"
+        },
         "Technique": {
             "description": "How a trace was put on the paper.",
             "enum": [

package/lib/spec/context.json

@@ -106,6 +106,7 @@
             "@type": "xsd:date"
         },
         "collationTolerance": null,
+        "referenceCopy": null,
         "annotation": null,
         "roll": "lrmoo:R3i_realises",
         "catalogueNumber": "dcterms:identifier",
@@ -166,6 +167,7 @@
             "@context": {
                 "shift": null,
                 "scale": null,
+                "alignment": null,
                 "readerExtension": null,
                 "trackCalibration": null,
                 "margins": null,
@@ -210,7 +212,37 @@
         "drive": "reo:drive",
         "company": "crm:P14_carried_out_by",
         "paper": "crm:P126_employed",
-        "conditions": "crm:P44_has_condition",
+        "conditions": {
+            "@id": "crm:P44_has_condition",
+            "@context": {
+                "horizontal": "reo:horizontal",
+                "edge": {
+                    "@id": "reo:edge",
+                    "@type": "@vocab",
+                    "@context": { "@vocab": "https://w3id.org/reo/type/" }
+                },
+                "depth": {
+                    "@id": "reo:depth",
+                    "@context": {
+                        "value": "crm:P90_has_value"
+                    }
+                },
+                "along": {
+                    "@id": "reo:strainAlong",
+                    "@context": {
+                        "value": "crm:P90_has_value",
+                        "uncertainty": "reo:uncertainty"
+                    }
+                },
+                "across": {
+                    "@id": "reo:strainAcross",
+                    "@context": {
+                        "value": "crm:P90_has_value",
+                        "uncertainty": "reo:uncertainty"
+                    }
+                }
+            }
+        },
         "condition": "crm:P44_has_condition",
         "conditionType": {
             "@id": "crm:P2_has_type",

package/lib/systems/ReproducingSystem.d.ts

@@ -103,15 +103,16 @@ export type RollProperties = {
     tempo?: RollTempo;
     /**
      * Place on the edition's shared axis × this = millimetres of the version's
-     * own paper. About 0.775 for a green issue of a red recording, 1 for a
-     * version on the axis it was measured on, which is the default.
+     * own paper, unstretched. About 0.775 for a green issue of a red
+     * recording, and close to 1 for a version of the reference copy's own
+     * system, which is the default.
      *
      * Versions of several systems share one place axis, so a green version's
      * places are in red millimetres and would play about 29 % long if the
-     * spool read them as green paper. The factor is the inverse of the scale
-     * `alignCopy` recorded when it put the copy on the shared axis, taken from
-     * the copies of the version's own system: red copies carry a green
-     * version's notes too and say nothing about green paper.
+     * spool read them as green paper. The factor is what the alignments of
+     * all the copies give together for the paper of the version's system
+     * (`paperOf`): red copies carry a green version's notes too, but only
+     * the green copies' alignments say anything about green paper.
      *
      * It scales **places only**. Punch diameter, the chain gap and the tracker
      * bore are measured on the version's own paper already, and scaling them

package/package.json

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