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.

Canonical JSON

from altar_identity import canonical_json, sha256_json

canonical_json({"b": 1, "a": "é"})  # '{"a":"é","b":1}'
sha256_json({"b": 1, "a": "é"})  # "sha256:<64 hex>" over those UTF-8 bytes

canonical_json sorts object keys, uses , and : without spaces, writes non-ASCII text as UTF-8 and refuses NaN and infinity. It is the text every Altar identity is hashed over: Altar core's canonical_json and deterministic_hash reduce dataclasses, enums and sets to plain JSON values and then call it, and runtimes call it directly.

Reference genome identity

from altar_identity import fasta_seqcol_digest, fasta_sequence_collection_file

collection = fasta_sequence_collection_file("genome.fa")  # names, lengths and refget sequence digests
collection.digest  # the level-0 seqcol digest: 32 URL-safe base64 characters
fasta_seqcol_digest("genome.fa", "sha256:<64 hex>", trust_record=True, record=True)

A FASTA's SHA-256 names its bytes; its GA4GH refget sequence-collection (seqcol) digest names its content: the contig names and each contig's uppercased sequence, in file order. A soft-masked and an uppercased copy, or two copies wrapped at different widths, share a seqcol. The level-0 digest covers the inherent attributes names and sequences; lengths appears only in the level-1 object (SequenceCollection.level1()). A contig's name is its header text up to the first space or tab. The reader streams the file in bounded chunks and raises SequenceCollectionError for a gzip stream (read the decompressed bytes), bytes before the first header, a repeated or non-ASCII name, an empty sequence, and any sequence byte other than a letter, * or -.

fasta_seqcol_digest reads the file once, checking its SHA-256 as it computes the seqcol, and can keep the result in a record at <path>.seqcol-verified, pinned to the file's status exactly as a SHA-256 verification record is:

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

Reference contigs

from altar_identity import UnscorableVariantError, reference_contig_name

reference_contig_name({"1", "MT"}, "chr1")  # "1"
reference_contig_name({"chrM"}, "chrM")  # "chrM"
reference_contig_name({"chr1"}, "chr2")  # raises UnscorableVariantError

A key spells a chromosome chr1 or chrM; a reference FASTA may name the same contig 1 or MT. reference_contig_name returns the FASTA's name for a chromosome by the key's own rule, canonical_chromosome: a contig named exactly as the key names it wins, and otherwise the first contig whose name the rule spells the same way (1, CHR01, MT, chrMT). Altar's batch preparation checks a reference by the same rule, so a variant it admits is one every runtime finds. A chromosome the FASTA lacks raises UnscorableVariantError, a ValueError: the key is valid, but there is no sequence to score it on. The model runtimes catch it, give that variant a row with null scores, log the reason and score the rest of the batch.

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.9.3

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.9.3
File Size Uploaded Provenance Actions
altar_identity-0.9.3.tar.gz 31.9 kB Without provenance Details for altar_identity-0.9.3.tar.gz

Built distribution (wheel)

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

Total release size: 57.1 kB

Release files / altar_identity-0.9.3.tar.gz

Download URL altar_identity-0.9.3.tar.gz
Size 31.9 kB
Tags Source
SHA-256 checksum
How to use checksums
57681a80cdccabb5062f2f4f2f6b738cde7929e6ea1ba1d6549ed5cc92194341
BLAKE2b-256 checksum
How to use checksums
115e50ad2e3ecf67bb9720a60e2ead476dc4d8db326ce4e68c87a0567837ec4b
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.9.3-py3-none-any.whl

Download URL altar_identity-0.9.3-py3-none-any.whl
Size 25.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
e639c776736b107e83a7fa8433e9ff2d28a93921de9a18658c22e312522c0aaa
BLAKE2b-256 checksum
How to use checksums
1fae9394563a2bf75ac1c12a4b2197799e61242a4a26d48b74c5f93ae55320ee
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.9.3

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