just_dna_enricher.cpic_notation¶
just_dna_enricher.cpic_notation ¶
CPIC's deletion, insertion and repeat-count notation, spelled as a VCF caller spells it (RM253).
CPIC's variantallele column carries three notations beside plain bases: DEL<bases> (DELTCT),
INS<bases> (INSCGGG) and a repeat count UNIT(n) (UGT1A1's TA(8)). None is a nucleotide string,
so the drafter skipped every one, and UGT1A1 *28, the allele the atazanavir and irinotecan labels key
on, shipped undefined.
The spelling is the one callers write (decided 2026-11-04 on measured VCFs). DeepVariant, DRAGEN,
GATK, Clair3 and the imputation servers all write *28 as the ordinary indel C>CAT at GRCh38
2:233760233, VCF-anchored and left-normalized; none writes a symbolic allele or a repeat count there.
So each notation becomes an anchored REF/ALT pair, left-aligned with the same _left_align the CIViC
drafter uses (RM273), and a module keys the spelling a caller emits.
Where CPIC's position sits, measured on the snapshot against the reference:
DEL<bases>— the position is the first deleted base: every such row's bases match the reference starting there. The anchor is the base before it.INS<bases>— the position is the base the insertion follows: NUDT15*14(INSCGGGat13:48037826) is Ensembl's48037826 G>GCGGG, and TPMT*42(INSTat6:18149032) left-aligns to the same event Ensembl writes one base right.UNIT(n)— the position is the first base of the run; the reference count is read from the reference, never assumed, and the count CPIC gives its reference allele agrees with it at every repeat locus in the snapshot.
A DEL paired with an INS at one locus is a delins. RYR1 writes c.13994_13995delTCinsCT as
DELTC on its Reference allele and INSCT on the variant. Read one row at a time, the reference
allele would be spelled as a deletion it does not carry; read by locus, the pair is the substitution
TC>CT (Ensembl calls rs193922862 exactly that) and the DEL half is the reference state.
What it will not do. It never guesses a base it could not read: an unreadable reference (offline,
an unreachable service, a contig with no refget accession) withholds the row with its reason, and so
does a reference that does not carry what the notation says. A bare DEL states no bases and stays
skipped, as decided. A value listing alternatives (GAGTCG(3) OR GAGTCG(4)) is an uncertainty CPIC
recorded, the same kind of statement as an IUPAC code, and stays skipped too.
Notation
dataclass
¶
One parsed CPIC notation. count is set for a repeat only.
Spelled
dataclass
¶
A VCF-anchored, left-normalized allele. ref == alt is the reference state at that locus.
parse_notation ¶
A CPIC notation → its Notation, or the reason it has none (a NOT_SPELLED_REASONS member).
Source code in enricher/src/just_dna_enricher/cpic_notation.py
delins_partner ¶
The reference bases of a delins site, or None when the locus is not one.
entries is every (allele, variantallele) CPIC states at one locus, across all of the gene's
alleles (never a filtered subset: whether a locus is a delins cannot depend on which alleles an
author asked for). The locus is a delins only when the values are DEL<bases> and INS<bases>
and nothing else, every DEL names the same bases, there is an INS, and the DEL sits on the
gene's reference allele (reference_names). That last condition is what makes the DEL the
reference state rather than a second variant: RYR1's DELTC is on Reference. A locus where the
deletion and the insertion are two variant alleles, or where the reference is written as plain
bases or a bare DEL, is read one row at a time.
Source code in enricher/src/just_dna_enricher/cpic_notation.py
spell ¶
spell(
notation: Notation,
chrom: str,
start: int,
read_window: ReadWindow,
*,
delins_ref: str | None = None,
) -> Spelled | str
Spell one notation at CPIC's start, or return why it cannot be spelled.
delins_ref is the locus's reference bases when the locus is a delins (delins_partner): the
insertion is then the substitution delins_ref>bases and the deletion is the reference state.
Source code in enricher/src/just_dna_enricher/cpic_notation.py
148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 | |