rtemis.a3
Amino Acid Annotation (A3) Format
Implements the Amino Acid Annotation (A3) format using 'S7' classes. The A3 format is a structured schema for annotating amino acid sequences with site, region, post-translational modification (PTM), processing event, and variant information. Provides functions to create, read, and write A3 objects, and to import annotations from 'UniProt', 'AlphaFold', 'PDBe', 'ClinVar', and 'Ensembl'.
rtemis.a3
R implementation of the Amino Acid Annotation (A3) format — a structured JSON format for amino acid sequences with site, region, PTM, processing, and variant annotations.
Part of the rtemis-org/a3 monorepo, which provides A3 implementations in R, Python, Julia, TypeScript, and Rust.
Installation
CRAN
install.packages("rtemis.a3")
R-universe
pak::repo_add(myuniverse = "https://rtemis-org.r-universe.dev")
pak::pak("rtemis.a3")
GitHub
pak::pak("rtemis-org/a3/r")
Quick Start
library(rtemis.a3)
a3 <- create_A3(
sequence = "MKTAYIAKQR",
site = list(
"Active site" = annotation_position(c(3L, 5L), type = "active site")
),
region = list(
"Repeat 1" = annotation_range(rbind(c(1L, 4L)))
),
ptm = list(
Phosphorylation = annotation_position(c(7L))
),
uniprot_id = "P12345",
description = "Example protein",
organism = "Homo sapiens"
)
Read / Write JSON
write_A3json(a3, "path/to/protein.json")
a3 <- read_A3json("path/to/protein.json")
API
Construction
| Function | Description |
|---|---|
create_A3(sequence, site, region, ptm, ...) |
Create an A3 object |
annotation_position(x, type) |
Create a position-indexed annotation entry |
annotation_range(x, type) |
Create a range-indexed annotation entry |
annotation_variant(x, info) |
Create a variant annotation |
I/O
| Function | Description |
|---|---|
write_A3json(x, path) |
Write an A3 object to a JSON file |
read_A3json(path) |
Read an A3 object from a JSON file |
S7 Class Hierarchy
A3
├── sequence: A3Sequence
├── annotations: A3Annotation
│ ├── site: named list of A3Site (A3Position index)
│ ├── region: named list of A3Region (A3Range index)
│ ├── ptm: named list of A3PTM (A3Index — position or range)
│ ├── processing: named list of A3Processing (A3Index — position or range)
│ └── variant: list of A3Variant
└── metadata: A3Metadata
├── uniprot_id
├── description
├── reference
└── organism
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. Each issue carries a stable code and an
RFC 6901 JSON Pointer path, both of
which are identical across the R, Python, Julia, TypeScript, and Rust
implementations of A3. Messages are for humans and are not contractual.
Two entry points, two behaviors, on purpose:
| Entry point | Behavior |
|---|---|
read_A3json(path) |
collect-all — aborts once with every issue in the failing stage |
validate_A3json(path) |
collect-all, non-throwing — returns the issues as a data frame |
create_A3(...) |
fail-fast — one corrective message, from the S7 validators |
A 500-annotation document assembled from four public resources should not be fixed one error per run. A programmer who passed a bad argument wants one specific message immediately.
validate_A3json("mapt.a3.json")
#> code stage path message
#> 1 A3E_POS_OUT_OF_BOUNDS 4 /annotations/site/Active/index/2 Position 999 is out of ...
read_A3json() attaches the issue list to the condition object, so it is
reachable without parsing the message:
issues <- tryCatch(
read_A3json("broken.a3.json"),
a3_validation_error = function(e) e[["issues"]]
)
See spec/error-codes.md
for the full rule registry and
spec/error-paths.md
for the path grammar.