feat: structure and sequence annotation bodies; paperspec.structures and paperspec.sequences
Chemical structures (spec/18 section 18.6) and biological sequences (18.7) tied to
the words of a paper. Minor change: two new body kinds, optional properties and
seven rules, with no valid file made invalid.
- annotation schema: structure (SMILES or SMARTS, role, identity, written, label,
accessions, force-field terms) and sequence (alphabet, role, identity, start,
organism, regions, variants); body_kind in sql/store.sql; nine terms in the
JSON-LD context; rules layer.structure.{value,identity,term} and
layer.sequence.{value,identity,region,variant}.
- paperspec.structures reads the atoms and bonds of a SMILES or SMARTS with the
standard library, so a term's atoms are checked without a toolkit; checked against
RDKit on a corpus and random texts. paperspec.sequences checks alphabets,
identities, regions and variants.
- fixtures/records/chemistry (on the main example) and biology (on the draft, which
gains a last sentence), vectors/structures.jsonl and vectors/sequences.jsonl;
check.py runs both layers and the vectors; counts, guides and CHANGELOG updated.
- the prose check no longer takes organism for a UK spelling.
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B8cL4zN4XpaQF5cBtASzfq
This commit is contained in:
36 files changed
+1488
-44
No files matched your search
+14
-6
@@ -57,14 +57,14 @@ This context defines `kind`, `status`, `audience`, `AnchorSelector` and `anchor`
|
||||
|
||||
## What it defines
|
||||
|
||||
The file defines 27 terms.
|
||||
Twenty-six map to IRIs under `https://paperspec.scient.ing/vocab#`: `format`, `kind`, `status`, `receipt`, `layer`, `audience`, `visibility`, `purpose`, `project`, `docs`, `pin`, `role`, `symbol`, `key`, `verdict`, `reason`, `reference`, `note`, `proposer`, `for`, `category`, `generator`, `exercise`, `anchor`, `rights_use` and the class `AnchorSelector`.
|
||||
Five are renamed: `key`, the key of a `symbol` body's symbol, is `sct:symbolKey`, `for` is `sct:questionFor`, `generator` is `sct:generatedBy`, `proposer`, the tool that found a trace, is `sct:proposedBy`, and `rights_use` is `sct:rightsUse`.
|
||||
The twenty-seventh, `total`, maps to `totalItems` in the ActivityStreams namespace.
|
||||
The file defines 36 terms.
|
||||
Thirty-five map to IRIs under `https://paperspec.scient.ing/vocab#`: `format`, `kind`, `status`, `receipt`, `layer`, `audience`, `visibility`, `purpose`, `project`, `docs`, `pin`, `role`, `symbol`, `key`, `verdict`, `reason`, `reference`, `note`, `proposer`, `identity`, `written`, `alphabet`, `organism`, `start`, `accessions`, `terms`, `regions`, `variants`, `for`, `category`, `generator`, `exercise`, `anchor`, `rights_use` and the class `AnchorSelector`.
|
||||
Six are renamed: `key`, the key of a `symbol` body's symbol, is `sct:symbolKey`, `for` is `sct:questionFor`, `generator` is `sct:generatedBy`, `proposer`, the tool that found a trace, is `sct:proposedBy`, `terms`, the force-field terms of a structure, is `sct:structureTerms`, and `rights_use` is `sct:rightsUse`.
|
||||
The thirty-sixth, `total`, maps to `totalItems` in the ActivityStreams namespace.
|
||||
Two terms carry a type rule.
|
||||
A processor reads `layer` as an IRI, and it always reads `docs` as a set, so a one-element list stays a list.
|
||||
|
||||
The file declares `anchor`, `exercise` and `proposer` as JSON literals (`"@type": "@json"`, a JSON-LD 1.1 feature, which is why the file sets `"@version": 1.1`).
|
||||
The file declares `anchor`, `exercise`, `proposer`, `accessions`, `terms`, `regions` and `variants` as JSON literals (`"@type": "@json"`, a JSON-LD 1.1 feature, which is why the file sets `"@version": 1.1`).
|
||||
A JSON-LD processor then keeps a `scienting-anchor/1` record intact instead of expanding it.
|
||||
An anchor holds hashes (fixed-length fingerprints of text) and a `span`, a pair of character offsets whose order carries meaning.
|
||||
Expansion would drop the anchor's unmapped field names ([JSON-LD 1.1 API, expansion step 13.3](https://www.w3.org/TR/json-ld11-api/#alg-expand-each-key-value)) and would give its arrays no order ([JSON-LD 1.1 §4.3](https://www.w3.org/TR/json-ld11/#sets-and-lists)).
|
||||
@@ -97,6 +97,14 @@ A `trace` body ([spec/18 §18.5](../spec/18-layers.md#185-traced-citations)) fol
|
||||
The Web Annotation context defines `source` and `selector` for a body as it does for a target, so a trace's selector list puts the `AnchorSelector` first and the `TextQuoteSelector` after it, as a target's does.
|
||||
This context adds the rest of the body: `reference`, the reference of the draft that the sentence cites, `note`, `verdict` and `proposer`, which a processor keeps whole, as it keeps an anchor, because its model's hashes and its score are values and not terms.
|
||||
|
||||
## Bodies that hold a structure or a sequence
|
||||
|
||||
A `structure` body ([spec/18 §18.6](../spec/18-layers.md#186-chemical-structures)) ties a molecule, a group or a pattern to a span, and a `sequence` body ([§18.7](../spec/18-layers.md#187-sequences)) ties a protein, DNA or RNA sequence to one.
|
||||
Both are text bodies, so the Web Annotation context supplies `value` and this one adds the rest: `identity`, the key that finds the same structure or sequence however it was written, `written`, `alphabet`, `organism` and `start`.
|
||||
`accessions`, `terms`, `regions` and `variants` are lists of objects whose field names mean nothing outside their body, so the context declares them JSON literals, as it does an anchor, and a processor keeps them whole.
|
||||
`terms` maps to `sct:structureTerms`, because the word alone is too general for a vocabulary that other kinds of body may join.
|
||||
[`fixtures/records/chemistry/annotations.jsonl`](../fixtures/records/chemistry/annotations.jsonl) and [`fixtures/records/biology/annotations.jsonl`](../fixtures/records/biology/annotations.jsonl) hold four structures on the example paper and three sequences on the draft.
|
||||
|
||||
## Using the context
|
||||
|
||||
- Writer: Put both URLs (web addresses), in the order shown, in `@context` of `layer.json` and of every line of `annotations.jsonl`. [Chapter 18](../spec/18-layers.md) defines layers (§18.2), annotations (§18.3) and bodies (§18.4).
|
||||
@@ -104,7 +112,7 @@ This context adds the rest of the body: `reference`, the reference of the draft
|
||||
The file `vectors/resolve.jsonl` resolves seventeen anchors against `fixtures/packages/hale2026harmonic-damb` and gives every outcome.
|
||||
- JSON-LD processor: Use a JSON-LD 1.1 processor; the context relies on `@json` and `@version` 1.1.
|
||||
- Checker: `schemas/annotation.schema.json` and `schemas/layer.schema.json` validate the files.
|
||||
`paperspec check` also checks that each annotation's ID derives from its content and that the receipt of its layer, at `fixtures/records/layer/receipt.json` or `fixtures/records/traces/receipt.json`, covers each `confirmed` annotation.
|
||||
`paperspec check` also checks that each annotation's ID derives from its content and that the receipt of its layer, in the `receipt.json` beside `fixtures/records/layer/`, `traces/`, `chemistry/` or `biology/`, covers each `confirmed` annotation.
|
||||
|
||||
The traps:
|
||||
|
||||
|
||||
@@ -30,6 +30,27 @@
|
||||
"@id": "sct:proposedBy",
|
||||
"@type": "@json"
|
||||
},
|
||||
"identity": "sct:identity",
|
||||
"written": "sct:written",
|
||||
"alphabet": "sct:alphabet",
|
||||
"organism": "sct:organism",
|
||||
"start": "sct:start",
|
||||
"accessions": {
|
||||
"@id": "sct:accessions",
|
||||
"@type": "@json"
|
||||
},
|
||||
"terms": {
|
||||
"@id": "sct:structureTerms",
|
||||
"@type": "@json"
|
||||
},
|
||||
"regions": {
|
||||
"@id": "sct:regions",
|
||||
"@type": "@json"
|
||||
},
|
||||
"variants": {
|
||||
"@id": "sct:variants",
|
||||
"@type": "@json"
|
||||
},
|
||||
"for": "sct:questionFor",
|
||||
"category": "sct:category",
|
||||
"generator": "sct:generatedBy",
|
||||
|
||||
Reference in new issue
Block a user