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

+421
View File
@@ -59,6 +59,218 @@
"additionalProperties": false
}
]
},
"accession": {
"description": "An entry of an outside database that a structure or a sequence is: `db` names the database in lower case (pubchem, chebi, cas, uniprot, genbank, refseq, ensembl, pdb) and `id` is the entry's identifier there (spec/18 §18.6).",
"type": "object",
"properties": {
"db": {
"type": "string",
"pattern": "^[a-z][a-z0-9-]*$",
"maxLength": 32
},
"id": {
"type": "string",
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$",
"maxLength": 128
}
},
"required": [
"db",
"id"
],
"additionalProperties": false
},
"structureTerm": {
"description": "A bond, angle, torsion or improper that a paper gives values for, citing the structure's atoms by number (spec/18 §18.6).",
"type": "object",
"properties": {
"kind": {
"enum": [
"bond",
"angle",
"torsion",
"improper"
]
},
"atoms": {
"description": "Atom numbers, from 0 in the order the value writes its atoms. An improper lists its central atom first.",
"type": "array",
"items": {
"type": "integer",
"minimum": 0
},
"minItems": 2,
"maxItems": 4,
"uniqueItems": true
},
"types": {
"description": "The force field's atom types, one for each atom.",
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 16
},
"minItems": 2,
"maxItems": 4
},
"values": {
"description": "The parameters the paper gives, by the name it uses (k_r, r_eq, theta_0).",
"type": "object",
"additionalProperties": {
"$ref": "common.schema.json#/$defs/decimal"
},
"minProperties": 1
},
"units": {
"description": "The unit of each value, by the same names.",
"type": "object",
"additionalProperties": {
"type": "string",
"minLength": 1
}
},
"source": {
"description": "Where in the paper the values are given.",
"type": "string",
"minLength": 1
}
},
"required": [
"kind",
"atoms"
],
"additionalProperties": false,
"allOf": [
{
"if": {
"properties": {
"kind": {
"const": "bond"
}
},
"required": [
"kind"
]
},
"then": {
"properties": {
"atoms": {
"minItems": 2,
"maxItems": 2
}
}
}
},
{
"if": {
"properties": {
"kind": {
"const": "angle"
}
},
"required": [
"kind"
]
},
"then": {
"properties": {
"atoms": {
"minItems": 3,
"maxItems": 3
}
}
}
},
{
"if": {
"properties": {
"kind": {
"const": "torsion"
}
},
"required": [
"kind"
]
},
"then": {
"properties": {
"atoms": {
"minItems": 4,
"maxItems": 4
}
}
}
},
{
"if": {
"properties": {
"kind": {
"const": "improper"
}
},
"required": [
"kind"
]
},
"then": {
"properties": {
"atoms": {
"minItems": 4,
"maxItems": 4
}
}
}
}
]
},
"region": {
"description": "A stretch of a sequence, by residue number, both ends included (spec/18 §18.7).",
"type": "object",
"properties": {
"start": {
"type": "integer",
"minimum": 1
},
"end": {
"type": "integer",
"minimum": 1
},
"label": {
"type": "string",
"minLength": 1
}
},
"required": [
"start",
"end"
],
"additionalProperties": false
},
"variant": {
"description": "A substitution, stop or deletion at one residue: `ref` is the residue the value has there, `alt` what the variant has (`*` a stop, `-` a deletion) (spec/18 §18.7).",
"type": "object",
"properties": {
"position": {
"type": "integer",
"minimum": 1
},
"ref": {
"type": "string",
"pattern": "^[A-Z*]$"
},
"alt": {
"type": "string",
"pattern": "^[A-Z*-]$"
}
},
"required": [
"position",
"ref",
"alt"
],
"additionalProperties": false
}
},
"type": "object",
@@ -540,6 +752,215 @@
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"const": "TextualBody"
},
"kind": {
"const": "structure"
},
"value": {
"description": "The structure as a SMILES or a SMARTS, whichever `format` says (spec/18 §18.6).",
"type": "string",
"minLength": 1,
"maxLength": 20000
},
"format": {
"enum": [
"chemical/x-daylight-smiles",
"chemical/x-daylight-smarts"
]
},
"role": {
"enum": [
"names",
"depicts",
"parametrizes",
"uses"
]
},
"identity": {
"description": "The InChIKey of a SMILES that has one; otherwise `smiles:` or `smarts:` and the first twelve hex digits of the SHA-256 of the value.",
"type": "string",
"pattern": "^([A-Z]{14}-[A-Z]{10}-[A-Z]|(smiles|smarts):[0-9a-f]{12})$"
},
"written": {
"description": "The structure as the paper writes it, when that is not SMILES or SMARTS: R-OH, CT-CT.",
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"accessions": {
"type": "array",
"items": {
"$ref": "#/$defs/accession"
},
"minItems": 1,
"uniqueItems": true
},
"terms": {
"type": "array",
"items": {
"$ref": "#/$defs/structureTerm"
},
"minItems": 1
}
},
"required": [
"type",
"kind",
"value",
"format",
"role",
"identity"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"const": "TextualBody"
},
"kind": {
"const": "sequence"
},
"value": {
"description": "The residues in capital letters, a gap as `-` (spec/18 §18.7).",
"type": "string",
"minLength": 1,
"maxLength": 100000
},
"alphabet": {
"enum": [
"protein",
"dna",
"rna"
]
},
"role": {
"enum": [
"names",
"depicts",
"uses",
"reports"
]
},
"identity": {
"description": "The alphabet, a colon and the first sixteen hex digits of the SHA-256 of the residues with the gaps taken out.",
"type": "string",
"pattern": "^(protein|dna|rna):[0-9a-f]{16}$"
},
"start": {
"description": "The number of the first residue of the value in the molecule's own numbering; 1 when omitted.",
"type": "integer",
"minimum": 1
},
"label": {
"type": "string",
"minLength": 1
},
"organism": {
"type": "string",
"minLength": 1
},
"accessions": {
"type": "array",
"items": {
"$ref": "#/$defs/accession"
},
"minItems": 1,
"uniqueItems": true
},
"regions": {
"type": "array",
"items": {
"$ref": "#/$defs/region"
},
"minItems": 1
},
"variants": {
"type": "array",
"items": {
"$ref": "#/$defs/variant"
},
"minItems": 1
}
},
"required": [
"type",
"kind",
"value",
"alphabet",
"role",
"identity"
],
"additionalProperties": false,
"allOf": [
{
"if": {
"properties": {
"alphabet": {
"const": "protein"
}
},
"required": [
"alphabet"
]
},
"then": {
"properties": {
"value": {
"pattern": "^[ACDEFGHIKLMNPQRSTVWYBXZJUO*-]+$"
}
}
}
},
{
"if": {
"properties": {
"alphabet": {
"const": "dna"
}
},
"required": [
"alphabet"
]
},
"then": {
"properties": {
"value": {
"pattern": "^[ACGTRYKMSWBDHVN-]+$"
}
}
}
},
{
"if": {
"properties": {
"alphabet": {
"const": "rna"
}
},
"required": [
"alphabet"
]
},
"then": {
"properties": {
"value": {
"pattern": "^[ACGURYKMSWBDHVN-]+$"
}
}
}
}
]
},
{
"type": "object",
"properties": {