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:
alexmandClaude committed 2026-10-18 15:38:31 -04:00
1 parent 7890fa1ad7
commit 3ab96d653f
36 files changed
+1488 -44

No files matched your search

+36
View File
@@ -244,6 +244,42 @@ The first trace is disputed by a reply that says the table is the better passage
The outcomes here are all `current`; [vectors/traces.jsonl](../vectors/traces.jsonl) corrects the draft or the paper and shows the others: `changed` when the passage was reworded but is still found, `stale` when it is gone, `unlinked` when the sentence no longer cites the reference, and `misresolved` when the reference now resolves to another paper.
Resolving a trace also lists the citations inside the passage, so a chain of "as previously reported" is followed one trace at a time.
## Read the structures and sequences tied to a paper's words
This shows how a molecule or a sequence is tied to the words that name it, and how the layer checks what it holds.
Nothing finds a molecule in free text, so a person ties each one: a `structure` annotation holds a SMILES or SMARTS, a `sequence` annotation holds residues, and the span is the annotation's target ([chapter 18](../spec/18-layers.md#186-chemical-structures)).
The main example has a layer of four structures and the draft a layer of three sequences, and `paperspec.structures` and `paperspec.sequences` check each against the rules, with the standard library alone:
```python
import json
from paperspec import sequences, structures
for name, module in (("chemistry", structures), ("biology", sequences)):
for line in open(f"fixtures/records/{name}/annotations.jsonl", encoding="utf-8"):
a = json.loads(line)
quote = a["target"]["selector"][1]["exact"]
print(a["status"], a["body"]["role"], a["body"]["identity"], repr(quote), module.problems(a))
atoms, bonds = structures.scan("O([H])[H]")
print(atoms, sorted(bonds))
```
```text
confirmed names OTMSDBZUPAUEDD-UHFFFAOYSA-N 'ethane' []
proposed names XLYOFNOQVPJJNP-UHFFFAOYSA-N 'Water' []
confirmed parametrizes smarts:2e2a923f840c 'CT–CT' []
confirmed parametrizes XLYOFNOQVPJJNP-UHFFFAOYSA-N 'OW–HW' []
confirmed names protein:5807fcbf6d5567ca 'villin headpiece subdomain HP35' []
confirmed depicts protein:5807fcbf6d5567ca 'LSDEDFKAVFGMTRSAFANLPLWKQQNLKKEKGLF' []
proposed reports protein:5807fcbf6d5567ca 'N68H' []
3 [(0, 1), (0, 2)]
```
Each line gives the annotation's status, what its span does with the structure, the identity, the words, and the rules it breaks, none here.
The identity finds the same thing however it was written: the name a model proposed for water, `O`, and the `O([H])[H]` that Table 1's OW–HW constants are given on are one molecule, and all three annotations of the peptide share one identity.
The last line is the rule that lets a term cite atoms without a chemistry toolkit: `O([H])[H]` writes three atoms, numbered from 0 as it writes them, and the oxygen (0) is bonded to each hydrogen (1 and 2) and the hydrogens are not bonded to each other, so a bond term on atoms 1 and 2, or an angle on atoms 0, 1 and 2, is refused.
[vectors/structures.jsonl](../vectors/structures.jsonl) and [vectors/sequences.jsonl](../vectors/sequences.jsonl) show every rule broken.
## Test your implementation against a vector
A test vector is a recorded input together with the output every correct implementation must produce.