rtemis-a3
Python implementation of the Amino Acid Annotation (A3) format, a JSON format for an amino acid sequence with site, region, PTM, processing, and variant annotations.
- Canonical JSON Schema:
https://schema.rtemis.org/a3/v1/schema.json(source:schema/a3.schema.json) - Conformance contract:
spec/ - Monorepo, with the R, Julia, TypeScript, and Rust implementations: rtemis-org/a3
Installation
pip install rtemis-a3
# or with uv
uv add rtemis-a3
The distribution is rtemis-a3; the import package is rtemis.a3.
Usage
from rtemis.a3 import create_a3, residue_at, variants_at
a3 = create_a3(
"MKTAYIAKQR",
site={
"Active site": {"index": [3, 5], "type": "activeSite"},
},
region={
"Repeat 1": {"index": [[1, 4]], "type": ""},
},
ptm={
"Phosphorylation": {"index": [7], "type": ""},
},
variant=[{"position": 3, "from": "T", "to": "A"}],
metadata={
"uniprot_id": "P12345",
"description": "Example protein",
"organism": "Homo sapiens",
},
)
len(a3.sequence) # 10
residue_at(a3, 1) # 'M'
variants_at(a3, 3) # [VariantRecord(position=3, from='T', to='A')]
create_a3 adds $schema and a3_version to the document it builds.
Reading a document
from rtemis.a3 import a3_from_json, A3ParseError, A3ValidationError
try:
a3 = a3_from_json(json_string)
except A3ParseError as e:
print(e) # the text is not JSON
except A3ValidationError as e:
print(e.issues) # list[A3Issue]: code, path, message
File I/O
from rtemis.a3 import read_a3json, write_a3json
a3 = read_a3json("protein.a3.json")
write_a3json(a3, "output.a3.json", indent=2)
Serialization
from rtemis.a3 import a3_to_json
json_string = a3_to_json(a3) # compact
json_string = a3_to_json(a3, indent=2) # pretty-printed
Document format
{
"$schema": "https://schema.rtemis.org/a3/v1/schema.json",
"a3_version": "1.0.0",
"sequence": "MKTAYIAKQR",
"annotations": {
"site": { "Active site": { "index": [3, 5], "type": "activeSite" } },
"region": { "Repeat 1": { "index": [[1, 4]], "type": "" } },
"ptm": { "Phosphorylation": { "index": [7], "type": "" } },
"processing": {},
"variant": [{ "position": 3, "from": "T", "to": "A" }]
},
"metadata": {
"uniprot_id": "P12345",
"description": "Example protein",
"reference": "",
"organism": "Homo sapiens"
}
}
$schema,a3_version, andsequenceare required in a document.a3_versionis"1.0.0".sequenceis a string of at least two characters from[A-Za-z*], stored in uppercase.annotationsandmetadataare optional. Every annotation family and every metadata member defaults to empty, and serialized output contains all of them.- Each
site,region,ptm, andprocessingentry is an object with anindexand an optionaltypestring, which defaults to"". Asiteindex is a list of positions, aregionindex is a list of ranges, and aptmorprocessingindex is either, never both. - Positions are 1-based integers. They are sorted ascending on read; a duplicate position is an error.
- A range is an inclusive
[start, end]pair withstart < end. Ranges are sorted by start on read; overlapping ranges are an error. - A variant record requires
position. Its other members are free-form JSON values and are preserved verbatim. A single-characterfrommust equal the residue atposition. - Metadata members are free-text strings.
Package versions and a3_version are independent. This package reads and writes A3 format version 1.0.0.
Validation
Validation is collect-all. A document is checked in four stages (envelope, structural, intra-field, contextual), and every issue in the earliest failing stage is reported at once. A later stage runs only when every earlier stage produced no issue. Each issue carries a stable code and an RFC 6901 JSON Pointer path; both are identical across the R, Python, Julia, TypeScript, and Rust implementations of A3. The message is human-readable text and is not part of the contract. The rule registry is spec/error-codes.md.
a3_from_json, read_a3json, and create_a3 raise an A3ValidationError that carries every issue of the failing stage:
from rtemis.a3 import a3_from_json, A3ValidationError
try:
a3 = a3_from_json(text)
except A3ValidationError as exc:
print(exc.stage) # 4
for issue in exc.issues:
print(issue.code, issue.path)
# A3E_POS_OUT_OF_BOUNDS /annotations/site/Active site/index/2
validate_a3 is the non-throwing entry point, for a form or a live-validation panel:
import json
from rtemis.a3 import validate_a3
issues = validate_a3(json.loads(text)) # [] when the document is valid
API
Functions
| Function | Description |
|---|---|
create_a3(sequence, *, site, region, ptm, processing, variant, metadata) |
Builds and validates an A3 object from its parts. Raises A3ValidationError. |
a3_from_json(text) |
Parses and validates a JSON string. Raises A3ParseError or A3ValidationError. |
validate_a3(raw) |
Validates a parsed value; returns list[A3Issue], empty when the document is valid. |
a3_to_json(a3, *, indent=None) |
Serializes to a JSON string; indent=None gives compact output. |
read_a3json(path) |
Reads and validates a file. Raises A3ParseError when the file cannot be read or is not JSON. |
write_a3json(a3, path, *, indent=None) |
Writes a3_to_json(a3, indent=indent) to a file. |
residue_at(a3, position) |
Residue at a 1-based position. Raises ValueError when the position is out of bounds. |
variants_at(a3, position) |
Every variant record at a 1-based position. |
Errors and issues
| Name | Description |
|---|---|
A3ValidationError |
issues: every issue in the earliest failing stage. stage: that stage, 1 to 4. messages: one message per issue. |
A3ParseError |
The input could not be parsed or read before validation. |
A3Issue |
One issue: code, path, message, and stage. |
A3IssueCode |
A StrEnum of every code in the rule registry. |
Pydantic model hierarchy
A3
├── sequence: str
├── annotations: A3Annotations
│ ├── site: dict[str, A3Position] (position index)
│ ├── region: dict[str, A3Range] (range index)
│ ├── ptm: dict[str, A3Flex] (position or range index)
│ ├── processing: dict[str, A3Flex] (position or range index)
│ └── variant: list[VariantRecord]
└── metadata: A3Metadata
└── uniprot_id, description, reference, organism
Every model is immutable (frozen=True) and rejects unknown fields. create_a3 and a3_from_json construct them.
License
Metadata
Release files for rtemis-a3 0.2.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| rtemis_a3-0.2.1.tar.gz | 20.6 kB | Without provenance | Details for rtemis_a3-0.2.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| rtemis_a3-0.2.1-py3-none-any.whl | Python 3 | none | any | Details for rtemis_a3-0.2.1-py3-none-any.whl |
Total release size: 44.8 kB
Release files / rtemis_a3-0.2.1.tar.gz
| Download URL | rtemis_a3-0.2.1.tar.gz |
|---|---|
| Size | 20.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ffaf6be9a32882514ab45c8ce40ae9a0ee93faa72a65b651ab02b5d1e1584434
|
|
BLAKE2b-256 checksum How to use checksums |
fe2d0b0872b07c9c4d926eca694389a6260cbabcdd0db4b6c6a01ca45aeb6912
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / rtemis_a3-0.2.1-py3-none-any.whl
| Download URL | rtemis_a3-0.2.1-py3-none-any.whl |
|---|---|
| Size | 24.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3f565e742a1e1f3d28ea9a9a45d3b4c7d3c4683ae61d1f42c134946ad60b72fd
|
|
BLAKE2b-256 checksum How to use checksums |
71cbe8fe22437097b2ef4446170587995e4b162957bf6d2339294039ec699800
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for rtemis-a3 0.2.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.