Skip to content

Variants and reference genomes

Altar's input variant fields are chr, pos, ref, alt, and an optional source identifier. Positions are one-based. A multi-allelic VCF record becomes one occurrence per alternate allele.

Identity has two layers

The scoring, detail, and annotation join key is the canonical allele tuple chr:pos:ref:alt, exposed as variant_id. Chromosomes use a chr prefix, primary aliases are normalized (1 and chr01 become chr1; M, MT, and chrM become chrM), alleles are uppercase, and positions are positive one-based integers.

The source VCF ID or fifth TSV column is occurrence metadata named source_variant_id in the streaming preprocessing outputs. It is never substituted for the allele key. Model runtimes derive variant_id from the four locus columns, so a label such as rs123 cannot silently break joins between scores and annotations.

For a defensible analysis, the allele tuple is still incomplete without genome-build context. chr1:100:A:G on one assembly is not interchangeable with the same string on another assembly. Altar's source and relation interfaces carry genome-build identity where they cross a dataset boundary; applications should preserve the build in job and result provenance as well.

Canonical spelling is not biological normalization. Altar does not silently left-align or trim indels when constructing a key; genome-aware ingestion must do that first when equivalent representations need to join.

Reference validation

The preprocessing pipeline checks each concrete allele against the configured FASTA:

  • the chromosome is a primary chromosome (1–22, X, Y or M, under the aliases above) and the FASTA contains it under its canonical name, such as chrM;
  • REF and ALT are non-empty uppercase A, C, G and T;
  • REF lies inside the contig;
  • REF equals the reference bases at POS. Soft-masked (lowercase) reference bases match.

A failed check gives one reason: invalid_chromosome, invalid_reference, invalid_alternate, position_out_of_range or reference_mismatch. Coordinate systems are not silently lifted between assemblies.

Validation applies no model's sequence window. A SNV at the first or last base of a contig, a chrM variant and a long insertion are all valid Altar variants. Whether a model's input window fits around a variant is decided by that model's binding or runtime. The streaming manifest records the validation version, and a change to these rules changes that version.

Altar preserves:

  • input order through occurrence ordinals;
  • duplicate occurrences;
  • the index of each alternate allele in a multi-allelic record;
  • rejected alleles and structured rejection reasons;
  • the immutable source VCF for occurrence-aware export.

Supported and unsupported input

The streaming pipeline accepts coordinate-sorted VCF, BGZF-compressed VCF, and canonical headerless TSV. Binary BCF and gVCF are rejected. Symbolic structural variants, breakends, spanning deletions, and ALT == REF remain represented as unsupported occurrences but are not sent to scorers that require concrete alleles.

An individual binding may support a narrower set. For example, the precomputed GPN-Star binding accepts only biallelic SNVs covered by its selected score release. Always apply the integration's variant contract after general Altar validation.

See Prepare VCF input for command-line usage.

Population allele frequencies

Variant annotation (altar.variants.annotation.annotate) reports population allele frequencies from the Open Targets Platform 25.03 variant index. These are the gnomAD adjusted frequencies (*_adj) that Open Targets publishes for GRCh38 alleles. The lookup table ships in the runtimes/variants image. To annotate outside the image, build it as described in Annotation data files.

Field Meaning
in_ot The allele is in the Open Targets variant index.
af_afr, af_ami, af_amr, af_asj, af_eas, af_fin, af_mid, af_nfe, af_sas, af_remaining Alternate-allele frequency in that gnomAD population.

A missing frequency is None, not 0.0:

  • An allele that is not in the index has in_ot set to false and every af_* field None.
  • An allele in the index keeps None for each population that Open Targets does not report.
  • 0.0 means Open Targets reports a frequency of zero for that population.

Frequencies keep the full double-precision value that Open Targets reports. A rare allele reported at 2.19e-05 stays 2.19e-05, so rare-variant cutoffs such as 1e-4 or 1e-5 apply to the reported value.

For frequencies from a gnomAD release you choose, with counts, grpmax, the filtering allele frequency, and the site's filter status, use the gnomAD annotation source. Its columns are prefixed gnomad_, so both can be used together.