Skip to content

Variant identity and normalization

Altar names every variant by its chromosome, position, reference allele and alternate allele, written chr:pos:ref:alt. This ID joins a variant's model scores, annotations and links. One variant written two ways must get one ID, so Altar writes every ID one way and normalizes the alleles.

The variant ID

A variant ID looks like chr1:100:A:G. The position is one-based, as in a VCF. A multi-allelic VCF record becomes one variant per alternate allele.

Altar writes every ID one way:

  • Chromosome: the input may omit the chr prefix or write it in any case; the ID always has it. Primary chromosomes are normalized: 1, chr01 and CHR1 become chr1, and M, MT and chrM become chrM. Other contigs keep their spelling after the prefix, because contig names in a FASTA are case-sensitive: CHRUn_KI270302v1 becomes chrUn_KI270302v1.
  • Position: a positive whole number, written in plain digits.
  • Alleles: uppercased, then made of A, C, G, T and N only. REF and ALT must differ.

So 1:100:a:g is written chr1:100:A:G. Every field is plain ASCII. Spaces around a field are trimmed, and any other whitespace or non-ASCII character is an error.

Some VCF alleles name no sequence, so they have no ID: symbolic alleles such as <DEL>, spanning deletions (*), missing alleles (.), breakends and IUPAC ambiguity codes. Reading a VCF drops these alleles and counts them. A variant TSV has no such records, so a TSV row without a valid ID is an input error that names the row.

An ID may contain N. The reference check decides whether a model can score it.

The rules live in the altar-identity package, which Altar and every model's container image share. See the identity package for its Python interface.

Source identifiers

The VCF ID column, or the optional fifth column of a variant TSV, is kept as the variant's source identifier. An rsID such as rs123 or a cohort label goes there. It is never used in place of the variant ID, so a label cannot break the join between scores and annotations. Model runtimes always build the variant ID from the chromosome, position and alleles.

Genome builds

The variant ID does not include the genome build. chr1:100:A:G on hg19 and on hg38 are different variants with the same ID. The build travels beside the ID: a run names it in [run] genome_build, and every score, source and link records the build it used. Altar spells builds the UCSC way (hg38, hg19, mm10, mm39) and reads the GRC names (GRCh38, GRCh37, GRCm38, GRCm39) as the same builds. hg38 is the default where nothing names one.

Altar never lifts coordinates from one build to another.

Allele normalization

One variant can be written in more than one way. Normalization picks one spelling, so a cohort variant, its scores, and gnomAD's or ClinVar's record of it share an ID. It has two steps:

  1. Trimming removes the bases REF and ALT share at either end, keeping at least one base in each. The position moves past any bases removed from the front. chr1:100:CA:TA becomes the SNV chr1:100:C:T, and chr17:43045710:GG:GT becomes chr17:43045711:G:T. Trimming needs no reference.
  2. Left alignment trims, then shifts an indel left through a repeat, using the reference genome. Take the sequence CAAAAG with its C at position 104. Deleting one A can be written chr1:107:AA:A, and left alignment rewrites it as chr1:104:CA:C. SNVs and MNVs never move.

Writing the ID one way, as in The variant ID, is a separate rule. It fixes the chromosome name and the case of the alleles, and does neither step.

gnomAD and ClinVar publish their variants left-aligned, so their IDs match a cohort that was left-aligned on the same build.

Which paths normalize

Path What it does to the alleles
altar run with [variants] reference_fasta Trims and left-aligns each variant the reference accepts; only trims a variant on a contig the FASTA lacks, or whose REF does not match it
altar run without a reference Trims only
The dataset builders, such as altar-popfreq-build and altar-clinvar-build Trim only
Annotation source lookups Trim the ID for the lookup, and return the row under the ID you gave; see below
Reading variants in Python Depends on the function; Ingest variants and write augmented VCFs says which trim only and which left-align

To left-align a cohort in a run, set [variants] reference_fasta. The run writes the normalized cohort to <work_dir>/variants/<job_id>.candidates.tsv. Without a reference, it reports each indel it could only trim; see Variants a lookup may miss.

Lookups trim but do not left-align

A source lookup trims each ID before it searches, and returns the row under the ID you passed. chr17:43045710:GG:GT finds the gnomAD and ClinVar records stored as chr17:43045711:G:T. An ID that breaks the writing rules, such as 1:100:a:g, is still rejected. No lookup left-aligns, because that needs the reference genome.

Repeat-region indels

A path that only trims leaves an indel where the input wrote it. An indel written at the right end of a repeat then has a different ID from the one left alignment gives it: chr1:107:AA:A stays chr1:107:AA:A instead of becoming chr1:104:CA:C. That ID finds no gnomAD or ClinVar record, and nothing reports the miss. Its scores do not join the scores of the same variant read with a reference. SNVs, MNVs, and indels outside repeats get the same ID either way.

Give the run a reference when the cohort has indels. Left-align IDs from any other path with left_align before you look them up; see Build and check variant IDs.

Scoring checks normalization

Scoring never rewrites an ID. It sets aside each variant that normalization would rewrite, lists it with the reason not_normalized in the run's ineligible-variant report, and does not score it. With a reference it checks left alignment; without one it checks trimming. altar run normalizes the cohort against the same reference first, so its variants pass. A variant the reference rejects is set aside as contig_missing or reference_mismatch instead.

Variant and training assemblies

Two assemblies take part in scoring, and they need not be the same. The variant assembly is the build the variants' coordinates are on. The training assembly is the build the model was trained on. A model trained on mouse (mm10) data can score human (hg38) variants, for example to perturb, in silico, a cell type that cannot be profiled in humans.

Assembly Where it is set What it decides
Variant assembly [run] genome_build in a run spec, or the ingest's --genome-build The reference genome a run reads, and the genome build recorded with each score
Training assembly The model's training_genome_build setting, for a model that has one Which outputs read the model's own coordinates, and so are empty on another variant assembly

A run always reads the reference sequence of the variant assembly. A score computed from that sequence, such as a ChromBPNet logfc, keeps its meaning on any variant assembly. An output that reads the model's own coordinates, such as ChromBPNet's in_peak (overlap with the model's peaks), is stored empty when the two assemblies differ. A prioritization rule that reads such an output treats it as missing, so the rule does not fire on it.

Each annotation source declares the assembly it serves; a source that declares none serves hg38 only. A source's values are joined only to variants of its assembly. When no source serves the variant assembly, as for region annotations on mouse variants, its columns are empty and the run warns. A model's prioritization then reads them as missing.

A model can need a source on the wrong assembly where one on the variants' assembly could exist, such as an hg19 region table as the only region source for hg38 variants. That is an error.

Reference validation

altar run checks each variant against [variants] reference_fasta when it normalizes the cohort. A variant on a contig the FASTA lacks, or whose REF does not match the reference, stays in the export, and each model sets it aside, as Scoring checks normalization describes. Soft-masked (lowercase) reference bases match.

The Python ingest pipeline and validate_variants check each allele more strictly:

  • the chromosome is a primary chromosome (1–22, X, Y or M, under the spellings above), and the FASTA has it under its normalized name, such as chrM;
  • REF and ALT are made of A, C, G and T;
  • REF lies inside the chromosome;
  • REF equals the reference bases at POS.

A failed check gives one reason: invalid_chromosome, invalid_reference, invalid_alternate, position_out_of_range or reference_mismatch. Ingest variants and write augmented VCFs describes what the ingest writes.

Neither check applies a model's sequence window. A SNV at the first or last base of a chromosome, a chrM variant and a long insertion are all valid variants. Each model decides whether its input window fits around a variant.

Supported and unsupported input

altar run reads a VCF, plain or gzipped, and a headerless variant TSV. It refuses BCF. The Python ingest pipeline also refuses a gVCF and an unsorted VCF.

No model scores a symbolic structural variant, a breakend, a spanning deletion or an allele equal to the reference. A run drops these alleles and counts them. The Python ingest pipeline keeps them as unsupported occurrences.

A model or annotation source may accept fewer variants. Enformer, Borzoi, LegNet and Sei score SNVs only, and GPN-Star covers only the biallelic SNVs in its release. Each model page and source page says which variants it covers.

Next