Add the data annotation body (spec 18.8)
A data body says what kind of data a table, figure panel or passage presents: one of fifteen kinds, the dataset that holds the values, what each field measures (with the dataset's own unit) and the molecules and sequences it is about, by the identities of structure and sequence bodies. Where the values came from stays the dataset's origin. - spec/18 section 18.8, the body in annotation.schema.json, 'data' in the store's body_kind CHECK, five terms in the JSON-LD context. - paperspec.data.problems and the rules layer.data.type, layer.data.quantity, layer.data.subject and layer.data.dataset. Units are compared as strings with the dataset's; no unit library is needed. - fixtures/records/data/ (three annotations on the main example) and vectors/data.jsonl (35 cases); paperspec check covers both, and the determinism rebuild matches. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01B8cL4zN4XpaQF5cBtASzfq
This commit is contained in:
25 files changed
+670
-33
No files matched your search
@@ -55,6 +55,7 @@ Replies are annotations that target annotations, so discussions are threads anch
|
||||
| `trace` | `SpecificResource` | `source`, `selector`, `reference`, `note`, `verdict`, `proposer` | That the target's sentence cites `reference` on the strength of a passage of the cited document ([18.5](#185-traced-citations)). |
|
||||
| `structure` | `TextualBody` | `format`, `role`, `identity`, `written`, `label`, `accessions`, `terms` | That the span names, draws, gives parameters for or uses a chemical structure ([18.6](#186-chemical-structures)). |
|
||||
| `sequence` | `TextualBody` | `alphabet`, `role`, `identity`, `start`, `label`, `organism`, `accessions`, `regions`, `variants` | That the span names, shows, uses or reports a variant of a protein, DNA or RNA sequence ([18.7](#187-sequences)). |
|
||||
| `data` | `TextualBody` | `data_type`, `role`, `dataset`, `quantities`, `subjects`, `method`, `label`, `accessions` | That the span presents data of a kind, what its fields measure and which molecules and sequences it is about ([18.8](#188-data)). |
|
||||
| `translation` | `TextualBody` | `language` | The span in another language. |
|
||||
| `description` | `TextualBody` | `role` | A description of a figure, panel or table for readers who cannot see it: `alt`, a short text equivalent, or `long`, a full description. |
|
||||
| `generated` | `TextualBody` | `generator` | Text a model wrote about the span; never mistaken for source. `generator` is `{model, run}` as a correction's model author is ([11.2](11-corrections.md#112-every-correction-records)). |
|
||||
@@ -198,3 +199,51 @@ A sequence body breaks `layer.sequence.value` when its letters are not those of
|
||||
The reference implementation is `paperspec.sequences.problems`.
|
||||
It needs no toolkit, since an alphabet is a set of letters; a producer that knows the molecule SHOULD also check the sequence against the `accessions` it names.
|
||||
`vectors/sequences.jsonl` mints identities and breaks every rule, and `fixtures/records/biology/` holds a layer of three annotations on the draft `writer2027fixed-ynr7.v3`, whose last sentence tests its charges on the villin headpiece subdomain HP35: the words that name it, the printed sequence with its three helices as regions, and a model's proposal of the N68H variant, in the numbering 42 to 76 that the headpiece uses.
|
||||
|
||||
## 18.8 Data
|
||||
|
||||
A paper reports data in a table, a figure or a passage, and a dataset ([15](15-datasets.md)) holds its values.
|
||||
A `data` annotation says what kind of data its span presents, what the dataset's fields measure and which molecules and sequences it is about, so that data can be found by kind and by subject.
|
||||
Its target is the span, as for any annotation.
|
||||
The words and the dataset stay as they are, the kind is one reader's reading, attributed and withdrawable, and a model's tie stays `proposed` until a person confirms it.
|
||||
Whether the values hold is a claim ([18.1](#181-one-rule-decides-what-is-a-claim-and-what-is-a-layer)); this body says only what they are.
|
||||
|
||||
| Property | Required | Holds |
|
||||
| --- | --- | --- |
|
||||
| `value` | Yes | The data in a few words: what it is and what it is about. |
|
||||
| `data_type` | Yes | What kind of data it is, one of the kinds below. |
|
||||
| `role` | Yes | What the span does with the data: `reports` it (the span is the table, figure panel or passage that gives it) or `uses` it (the span relies on data given elsewhere). |
|
||||
| `dataset` | No | The ID of the dataset that holds the values, `ds-` and a key ([15](15-datasets.md)). |
|
||||
| `quantities` | No | What the dataset's fields measure: a list of `{field, name, unit?}`, with the `field` of the dataset, a `name` in words (`harmonic bond force constant`) and the `unit` as the dataset spells it. |
|
||||
| `subjects` | No | The molecules and sequences the data is about: a list of `{kind, identity, label?}`, with `kind` `structure` or `sequence` and the `identity` of a `structure` ([18.6](#186-chemical-structures)) or `sequence` ([18.7](#187-sequences)) body. |
|
||||
| `method` | No | How the data was obtained, in the paper's words: `isothermal titration calorimetry`, `DFT, B3LYP/6-31G*`. |
|
||||
| `label` | No | A short name. |
|
||||
| `accessions` | No | Entries of outside databases or vocabularies that the data is, or is of: a list of `{db, id}`, with `db` in lower case (`zenodo`, `geo`, `edam`, `chmo`). |
|
||||
|
||||
| `data_type` | Covers |
|
||||
| --- | --- |
|
||||
| `abundance` | Counts, expression levels or concentrations measured in samples. |
|
||||
| `benchmark` | How well a method or model does against a reference or against other methods: errors, scores, run times. |
|
||||
| `binding-affinity` | How tightly molecules bind: dissociation constants, inhibition constants, IC50, binding free energies. |
|
||||
| `dose-response` | A response as a function of dose or concentration. |
|
||||
| `energy-profile` | Energy along a coordinate: scans, potentials of mean force, reaction paths. |
|
||||
| `force-field-parameters` | Constants a force field or model uses for bonded and non-bonded terms. |
|
||||
| `geometry` | Lengths, angles, torsions, distances or deviations of structures. |
|
||||
| `kinetics` | Rates, rate constants, half-lives and barriers. |
|
||||
| `physical-property` | A property of a substance: density, melting point, pKa, logP, solubility. |
|
||||
| `sequence-property` | Values for the positions of a sequence: conservation, disorder, fitness scores. |
|
||||
| `simulation-observable` | A quantity computed from a simulation: distributions, time series, order parameters. |
|
||||
| `spectrum` | A spectrum or its peaks: NMR, infrared, Raman, ultraviolet-visible, mass. |
|
||||
| `thermodynamics` | Enthalpy, entropy, free energy, heat capacity, or a melting temperature of a process. |
|
||||
| `variant-effect` | What a change to a sequence or a structure does to a property. |
|
||||
| `other` | Data none of these describes; the `value` says what it is. |
|
||||
|
||||
The list is fixed by this chapter, and a new kind is a minor change ([0.4](00-introduction.md#04-status)).
|
||||
Where a kind has an outside term, `accessions` carries it, so a producer is not limited to this list when it says what the data is.
|
||||
A dataset's `origin` ([15](15-datasets.md)) says where its values came from, so the body does not repeat whether they were reported, digitized, computed or measured.
|
||||
|
||||
A data body breaks `layer.data.type` when its `data_type` or its `role` is not one the body allows, `layer.data.quantity` when two quantities are for one field, `layer.data.subject` when a subject's identity is not of the form its kind gives or a subject repeats another, and `layer.data.dataset` when `dataset` is not a dataset ID or, for a checker given the dataset's descriptor, is not that dataset, or a quantity names a field the dataset lacks or gives it a unit other than the dataset's ([22.4](22-conformance.md#224-rules)).
|
||||
The reference implementation is `paperspec.data.problems`, which takes the descriptor as an optional second argument.
|
||||
It compares units as strings and needs no unit library; a producer SHOULD also check that each unit parses and that its dimension fits the quantity it is given for, and that each subject's identity belongs to a `structure` or `sequence` annotation of the same layer or another.
|
||||
`vectors/data.jsonl` breaks every rule, and `fixtures/records/data/` holds a layer of three annotations on `hale2026harmonic-damb`: the caption of Table 1, tied to its dataset as force-field parameters for ethane, water and the CT–CT pattern with its force constant and equilibrium length; the caption of Figure 1a, tied to the dataset read from the scan as an energy profile of ethane; and the sentence that introduces Table 1, tied by a model and still `proposed`.
|
||||
The subjects' identities are those of the annotations in `fixtures/records/chemistry/`.
|
||||
@@ -6,7 +6,7 @@
|
||||
| --- | --- | --- |
|
||||
| `vectors/*.jsonl` | Inputs and expected outputs, one case per line. | Computes every expected output from its input. |
|
||||
| `fixtures/packages/` | Valid packages: a converted chemistry paper with corrections, receipts, a multi-level-header table and a dataset; its checks-only export; an open-access paper with two witnesses; a Typst draft; a tiny document, as a folder and as the zip of [12.2](12-package.md#122-paths). | Accepts each, and recomputes every value it contains. |
|
||||
| `fixtures/records/` | A valid record of every other format that is a JSON file of its own, and three more layers: traced citations ([18.5](18-layers.md#185-traced-citations)), whose traces resolve as `vectors/traces.jsonl` says, chemical structures ([18.6](18-layers.md#186-chemical-structures)) and sequences ([18.7](18-layers.md#187-sequences)), whose rules `vectors/structures.jsonl` and `vectors/sequences.jsonl` pin; the stage requirements and stamp rules are in `registry/`, and a bundle is built by `paperspec load --bundle`. | Accepts each. |
|
||||
| `fixtures/records/` | A valid record of every other format that is a JSON file of its own, and four more layers: traced citations ([18.5](18-layers.md#185-traced-citations)), whose traces resolve as `vectors/traces.jsonl` says, chemical structures ([18.6](18-layers.md#186-chemical-structures)), sequences ([18.7](18-layers.md#187-sequences)) and data ([18.8](18-layers.md#188-data)), whose rules `vectors/structures.jsonl`, `vectors/sequences.jsonl` and `vectors/data.jsonl` pin; the stage requirements and stamp rules are in `registry/`, and a bundle is built by `paperspec load --bundle`. | Accepts each. |
|
||||
| `fixtures/invalid/` | Invalid packages, each with `expect.json` naming the rule it breaks. | Refuses each, and SHOULD name that rule. |
|
||||
| `fixtures/keys/` | The test keys that signed the fixtures and the team secret of the checks-only export. | Never uses them for anything else. |
|
||||
|
||||
@@ -49,10 +49,10 @@ Rule IDs are stable: a rule's meaning never changes, and a retired rule's ID is
|
||||
| `doc.receipt.`, `doc.qa.`, `doc.fidelity.` | Receipts, spot-checks and levels. |
|
||||
| `doc.witness.`, `doc.page.`, `doc.location.`, `doc.reference.` | Witnesses and geometry. |
|
||||
| `grade.` | Grading. |
|
||||
| `layer.` | Annotations: `layer.trace.source` and `layer.trace.target`, which refer to documents ([18.5](18-layers.md#185-traced-citations)); `layer.structure.value`, `layer.structure.identity` and `layer.structure.term` ([18.6](18-layers.md#186-chemical-structures)); and `layer.sequence.value`, `layer.sequence.identity`, `layer.sequence.region` and `layer.sequence.variant` ([18.7](18-layers.md#187-sequences)). |
|
||||
| `layer.` | Annotations: `layer.trace.source` and `layer.trace.target`, which refer to documents ([18.5](18-layers.md#185-traced-citations)); `layer.structure.value`, `layer.structure.identity` and `layer.structure.term` ([18.6](18-layers.md#186-chemical-structures)); `layer.sequence.value`, `layer.sequence.identity`, `layer.sequence.region` and `layer.sequence.variant` ([18.7](18-layers.md#187-sequences)); and `layer.data.type`, `layer.data.quantity`, `layer.data.subject` and `layer.data.dataset` ([18.8](18-layers.md#188-data)). |
|
||||
|
||||
A package is validated by [22.2](#222-validating-a-package), but a layer is not part of one.
|
||||
The `layer.` rules are reported for an annotation, in the form `annotation: rule: message`, by a validator that has the annotation and, for a trace, the states of the documents it names; the reference implementation does so in `paperspec.traces.problems`, `paperspec.structures.problems` and `paperspec.sequences.problems`.
|
||||
The `layer.` rules are reported for an annotation, in the form `annotation: rule: message`, by a validator that has the annotation and, for a trace, the states of the documents it names; the reference implementation does so in `paperspec.traces.problems`, `paperspec.structures.problems`, `paperspec.sequences.problems` and `paperspec.data.problems`.
|
||||
|
||||
## 22.5 Stability
|
||||
|
||||
|
||||
Reference in new issue
Block a user