Skip to main content

PyPI version python-ci

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.

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, and sequence are required in a document. a3_version is "1.0.0".
  • sequence is a string of at least two characters from [A-Za-z*], stored in uppercase.
  • annotations and metadata are optional. Every annotation family and every metadata member defaults to empty, and serialized output contains all of them.
  • Each site, region, ptm, and processing entry is an object with an index and an optional type string, which defaults to "". A site index is a list of positions, a region index is a list of ranges, and a ptm or processing index 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 with start < 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-character from must equal the residue at position.
  • 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

BSD 3-Clause

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)

Source distribution for rtemis-a3 0.2.1
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)

Table of built distributions (wheels) for rtemis-a3 0.2.1
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page