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
chrprefix or write it in any case; the ID always has it. Primary chromosomes are normalized:1,chr01andCHR1becomechr1, andM,MTandchrMbecomechrM. Other contigs keep their spelling after the prefix, because contig names in a FASTA are case-sensitive:CHRUn_KI270302v1becomeschrUn_KI270302v1. - Position: a positive whole number, written in plain digits.
- Alleles: uppercased, then made of
A,C,G,TandNonly. 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:
- 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:TAbecomes the SNVchr1:100:C:T, andchr17:43045710:GG:GTbecomeschr17:43045711:G:T. Trimming needs no reference. - Left alignment trims, then shifts an indel left through a repeat, using the reference genome. Take the sequence
CAAAAGwith itsCat position 104. Deleting oneAcan be writtenchr1:107:AA:A, and left alignment rewrites it aschr1: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,GandT; - 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¶
- What prioritized means explains the flag each variant result carries.
- Give a run its variants sets the cohort, the reference and the genome build in a run spec.