Skip to main content

altar-identity

altar-identity holds the identity rules that Altar core and every Altar model runtime must agree on. It uses only the Python standard library and supports Python 3.9 and later, so a runtime pinned to an older TensorFlow or PyTorch stack runs the same code as Altar core instead of keeping a copy.

Most users do not install it directly: altar depends on it and re-exports the variant names from altar.variants, altar.models, and altar.sources.

Variant identity

from altar_identity import VariantKey, canonical_chromosome, canonical_variant_id

canonical_chromosome("MT")  # "chrM"
canonical_variant_id("1", 10, "a", "t")  # "chr1:10:A:T"
VariantKey.require_canonical("chr1:10:A:T")  # rejects aliases such as "1:10:A:T"

A key is chromosome:position:REF:ALT with a one-based position, and every field is ASCII. Surrounding ASCII whitespace is trimmed from each field; other whitespace and non-ASCII text raise VariantIdentityError, a ValueError, rather than being folded (an Arabic-Indic or full-width digit never becomes 1).

  • Chromosome: the chr prefix is optional and case-insensitive. Primary chromosomes are normalized in any case (1, chr01, CHR1 → chr1; M, MT → chrM). Every other contig keeps its exact spelling after the prefix (CHRUn_KI270302v1 → chrUn_KI270302v1), because reference contig names are case-sensitive and the key must match the name in the FASTA. The name uses the VCF contig-name characters: letters, digits, and !#$%&*+./;=?@^_|~-, which exclude :.
  • Position: a positive int. In text (VariantKey.parse, variant files, and parse_position for other readers) it is ASCII digits [0-9]+: +5, 1_000, 1e3, and non-ASCII digits are rejected, although Python's int() accepts some of them.
  • Alleles: uppercased, then [ACGTN]+, the VCF base alphabet for REF and a concrete ALT. Symbolic (<DEL>), *, ., breakend, IUPAC-ambiguity and - alleles are rejected, and REF must differ from ALT. N is allowed in the key; reference validation decides whether a keyed variant can be scored.

The key does not left-align or trim indels, and it does not carry the genome build. Variant identity and normalization explains both.

from altar_identity import minimal_representation

minimal_representation(10, "CAT", "CT")  # (10, "CA", "C")
minimal_representation(10, "TCA", "TGA")  # (11, "C", "G")
minimal_representation(10, "A", "AT")  # (10, "A", "AT"): already minimal

minimal_representation trims the bases REF and ALT share, suffix first and then prefix, keeping at least one base in each allele and advancing the position by the number of prefix bases removed. Trimming the suffix first leaves an indel anchored on the base before it, as VCF writes it. The alleles must have a key ([ACGTN]+, differing): symbolic, *, breakend, missing and equal alleles raise VariantIdentityError instead of being trimmed as if their characters were bases. Altar's ingestion applies it before assigning a key, and precomputed lookups such as gnomAD and ClinVar are built in the same representation. Left alignment, which needs the reference sequence, lives in altar.variants.

Variant files

from altar_identity import batched, read_variants

for batch in batched(read_variants("variants.tsv"), 1024):
    ...

Altar writes the variants for a model container as a headerless, tab-separated UTF-8 file with the columns chr, pos, ref, alt, and variant_id. read_variants also accepts four columns, or any label in the fifth, and never uses the fifth column. Fields are never quoted: a " is an ordinary character, and a field cannot hold a tab or line break. A leading UTF-8 byte-order mark is ignored. The reader yields canonical VariantKey values, skips blank lines, and raises VariantFileError naming the file and line for a malformed row. By default a repeated variant_id is an error; pass duplicates="skip" to keep the first occurrence or duplicates="allow" to yield every row. read_variant_rows yields VariantRow(line, key) records instead, for callers that apply their own policy (for example, SNVs only) and need to report the offending line. An empty or blank-only file yields nothing.

Content identity

from altar_identity import sha256_file, verify_file

digest = sha256_file("weights.h5")  # "sha256:<64 lowercase hex>"
verify_file("weights.h5", digest, label="weights")

A digest is sha256: followed by 64 lowercase hexadecimal digits and names the bytes of one regular file. verify_file raises DigestMismatchError when the bytes differ, and also when the path is missing or is a directory. Symlinks are followed. parse_sha256_digest and is_sha256_digest check the exact spelling, and SHA256_DIGEST_PATTERN is the same rule as an unanchored regular expression for schemas that embed it.

A file that many tasks read, such as a reference genome on a shared volume, need not be hashed by every task. verify_file(..., trust_record=True, record=True) accepts a file whose verification record is current and writes a record after a successful hash. The record is a one-line file at <path>.sha256-verified:

verified-file/1 sha256:<64 hex> size=<bytes> mtime=<seconds> ctime=<seconds> inode=<number>

Rewriting, replacing, truncating, or appending to the file changes a recorded value and invalidates the record. has_verification_record, write_verification_record, and verification_record_line are the primitives Altar core's verify_file_digest, its staging backends, and the runtimes share. Anyone who can write the storage can also forge a record, so do not trust records where bytes first arrive, such as a download.

Documentation

The Python interface is documented at https://kundajelab.github.io/altar/reference/identity/.

Development

uv run --isolated --no-project --python 3.9 --with pytest --with-editable identity \
    python -m pytest identity/tests

Licence

altar-identity is copyright 2026 Riya Sinha and released under the MIT License.

Metadata

Release files for altar-identity 0.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for altar-identity 0.4.0
File Size Uploaded Provenance Actions
altar_identity-0.4.0.tar.gz 20.7 kB Without provenance Details for altar_identity-0.4.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for altar-identity 0.4.0
File Interpreter ABI Platform Actions
altar_identity-0.4.0-py3-none-any.whl Python 3 none any Details for altar_identity-0.4.0-py3-none-any.whl

Total release size: 36.8 kB

Release files / altar_identity-0.4.0.tar.gz

Download URL altar_identity-0.4.0.tar.gz
Size 20.7 kB
Tags Source
SHA-256 checksum
How to use checksums
10cc6c77758a57c85886feaeb770a12c27bc05203e7ae2b21b380b08dbc124d5
BLAKE2b-256 checksum
How to use checksums
34537b3401390c552cb53677510523c36126d7ee143bcf5d067ab61479020526
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.12.17 {"installer":{"name":"uv","version":"0.12.17","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"22.04","id":"jammy","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / altar_identity-0.4.0-py3-none-any.whl

Download URL altar_identity-0.4.0-py3-none-any.whl
Size 16.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a12280221287e220e43cf3f2279446fc1375692d5f713ed77128f271be8b69e8
BLAKE2b-256 checksum
How to use checksums
80b99329a07dee8ed1c448269f2c85810720079232f20c894d3ab2199ecae76b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.12.17 {"installer":{"name":"uv","version":"0.12.17","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"22.04","id":"jammy","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for altar-identity 0.4.0

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