Computing CDS integrity statistics - hillerlab/TOGA2 GitHub Wiki

Codon classification for CDS integrity statistics
Integrity statistics
Using alternative frame codons for integrity statistics
Fetching CDS integrity properties from the output files

This page describes details on how TOGA2 determines the presence and intactness of the reading frame.

To infer frameshift or stop codon mutations, TOGA2 considers all reference codons. A reference codon always contains three nucleotides but might correspond to more or less than three nucleotides in the query in case of insertions or deletions, respectively. Depending on whether the number of inserted/deleted nucleotides in the query is divisible by three, these insertion/deletion events might be frame-preserving or frame-shifting; the latter are considered inactivating mutations by default.

[!TIP] If you’re looking for where to find the CDS intactness statistics (reported in inactivating_mutations.tsv in TOGA1), go to Fetching CDS integrity properties from the output files

Codon classification for CDS integrity statistics

Depending on their status, reference codons are classified into the following categories.

Intact (I): Codons present in the query sequence and not affected by any inactivating mutations. A single reference codon can refer to more than one codon (nucleotide triplet) in the query as long as the inserted triplets do not shift the reading frame:

## intact codon; the codon is present in the query and does not contain any inactivating mutations
ref   CTT
query CCT
## also intact
ref   CTT---
query CCTGAA

Deleted (D): Codons either fully deleted in the query (triple indel - symbols in the aligned query sequenced) or located in the exon classified as Deleted in the query:

## deleted codon; the second reference codon is precisely deleted in the query
ref    ATG CGC CTT
query  ATG --- CCT

Missing (M): codons located in the exons classified as Missing in the query:

## missing codons
ref    GAA CGC CTT
query  NNN NNN NNN

Lost (L): Codons from Present exons affected by unmasked inactivating mutations:

## lost codon; reference codon corresponds to two nucleotides in the query sequence, 
## indicating frameshifting mutation in the query
ref    ACC
query  AG-
## example of a frameshifting insertion
ref    ACC-
query  ACCC

Alternative frame (A): Codons lying within the sequence between the compensated frameshifting mutations. Two or more frameshifts are called compensated, or mutually compensating, if the sum of inserted/deleted nucleotides is divisible by three and the restored frame is free of premature stop codons. See more on frameshift compensation in the Inactivating mutations page.

## alternative frame codons; codons 1 and 3 in the query contain frameshifts 
## the sum of which is divisible by three, 
## and the alternative frame contains no inactivating mutations:
ref   ATG CGT CCA
query A-- TGG -TA
## this alignment can be rearranged as follows:
ref   ATG CGT CCA
query ATG --- GTA
## as you can see, the alternative frame is preserved and contains no inactivating mutations

To illustrate how the intactness statistics are assessed, consider the following (rather improbable) example. The reference sequence aligned in both cases comprises of 30 nucleotides (10 codons) organised in three exons. For visual clarity, codons are separated by whitespaces, and exon boundaries are denoted with pipe (“|") symbols. Exon statuses are stated in the exon line, and inactivating mutations are marked in the muts line.

In this example, the coding sequence is intact:

## case 1: intact query projection, with a single deleted codon and no inactivating mutations 
ref   | ATG CGC CTT | ACC CAA | TTG GAT GCG AGA CAT TAA |
query | ATG --- CCT | ATC CAA | TTA CAG GCG AAA TAC TGA |
exon  |      I      |    I    |           I             |
muts  |             |         |                         |

In this example, several inactivating mutations occurred:

Exon 1 has a frameshifting 1 bp deletion,
Exon 2 aligns to an assembly gap (undefined nucleotides N) and is classified as Missing, and
Exon 3 has both a stop codon and a frameshifting insertion (+2 bases).

## case 2: query projection is severely disrupted, with an exon missing and a few inactivating mutations
ref   | ATG CGC CTT | ACC CAA | TTG GAT GCG A--GA CAT TAA |
query | ATG --- -CT | NNN NNN | TAG CAG GTT AATAA TAC TGA |
exon  |      I      |    M    |           I              |
muts  |         *   |         |  *           *           |

Following the codon status notation above, the codon sequences can be represented as follows (see codons line):

## case 1
ref    | ATG CGC CTT | ACC CAA | TTG GAT GCG AGA CAT TAA |
query  | ATG --- CCT | ATC CAA | TTA CAG GCG AAA TAC TGA |
codons |  I   D   I  |  I   I  |  I   I   I   I   I   I  |

## case 2
ref    | ATG CGC CTT | ACC CAA | TTG GAT GCG A--GA CAT TAA |
query  | ATG --- -CT | NNN NNN | TAG CAG GTT AATAA TAC TGA |
codons |  I   D   L  |  M   M  |  L   I   I    L    I   I  |

## summarising the codon intactness for two projections:
case 1: IDIIIIIIIII
case 2: IDLMMLIILII

Integrity statistics

Longest non-deleted codon streak

The longest subsequence of Intact or Missing codons after omitting Deleted codons, divided by the codon number in the reference. The parameter represents the longest fraction of reference sequence that lacks inactivating mutations in the query projection. Ranges between 0% if all codons in the projection are Lost or Deleted and 100% if all codons are Intact or Missing.

## write both sequences as codon symbols sequences; 
## total codon number in both cases equals 10
case 1: IDIMMIIIIII
case 2: IDLMMLIILII

## omit Deleted codons
case 1: IIMMIIIIII
case 2: ILMMLIILII

## split sequences by Lost codon symbols
case 1: IIMMIIIIII
case 2: I MM II II

## find the longest sequence of Intact/Missing codons
case 1: IIMMIIIIII
case 2: II

## divide the length of the longest subsequence by the original codon number
case 1: 9 / 10 = 0.9
case 2: 2 / 10 = 0.2

Longest intact codon streak

Same as Longest non-deleted codon streak but Missing codon symbols are also omitted. The parameter represents the longest fraction of reference sequence that is strictly Intact in the query projection. Ranges between 0% if all codons in the projection are Lost, Missing, or Deleted and 100% if all codons are Intact.

## different example to illustrate the difference to Longest present codon streak
## initial codon number is 14
case 3: IDIIMMIIIILIII
## omit Deleted and Missing codons
case 3: IIIIIIILIII
## split sequences by Lost codon symbols
case 3: IIIIIII III
## find the longest sequence of Intact codons
case 3: IIIIIII
## divide the length of the longest subsequence by the original codon number
case 3: 7 / 14 = 0.5

Total CDS intactness

Percentage of Intact and Alternative Frame codons among all the non-Missing codons in the reference coding sequence. Ranges from 0% if all codons are Deleted, Lost, or Missing, to 100% if all codons are Intact or lie in the alternative frame.

## write both sequences as codon symbols sequences; 
## total codon number in both cases equals 10
case 1: IDIIIIIIIII
case 2: IDLMMLIILII

## remove the Missing codons, record the number of remaining codons
case 1: IDIIIIIIIII ## length=10
case 2: IDLLIILII   ## length=8

## remove non-Intact/Alternative symbols
case 1: IIIIIIIIII
case 2: IIIII

## divide the number of the Intact/Alternative codons by the number of all non-Missing codons
case 1: 9 / 10 = 90%
case 2: 5 / 8 = 62.5%

Middle 80% CDS presence

Indicates whether middle 80% of the reference CDS is free of Missing codons (assembly gaps, ambiguous symbols, or codons from the exons classified as Missing).

## start with the same two sequences;
## initial codon number equals 10 in both cases
case 1: IDIIIIIIIII
case 2: IDLMMLIILII

## define middle 80% of CDS;
## 10 * 0.8 = 8 => split 1 codon from both N- and C-termini
case 1: I | DIIIIIIII | I
case 2: I | DLMMLIILI | I

## assess whether middle 80% contain any Missing codons
case 1: DIIIIIIII => no Missing codons
case 2: DLMMLIILI => two Missing codons

## return the parameter value
case 1: Middle 80% CDS presence = True
case 2: Middle 80% CDS presence = False

Middle 80% CDS intactness

Indicates whether middle 80% of the reference CDS is free of mutations (Lost codons).

## again, initial codon number equals 10 in both cases
case 1: IDIIIIIIIII
case 2: IDLMMLIILII

## define middle 80% of CDS as before
case 1: I | DIIIIIIII | I
case 2: I | DLMMLIILI | I

## assess if these middle 80% contain any Lost codons
case 1: DIIIIIIII => no Lost codons
case 2: DLMMLIILI => three Lost codons

## return the parameter value
case 1: Middle 80% CDS intactness = True
case 2: Middle 80% CDS intactness = False

Using alternative frame codons for integrity statistics

“Alternative codons” are located between compensated frameshifts and are considered functionally intact (or, at least, not inactivated), as they are essentially encode different amino acids but cannot contain stop codons. However, projections having long and/or numerous regions affected by shifted reading frames encode a potential protein that is significantly different from the reference protein.

for the purpose of calculating the “longest streak” statistics (Longest present codon streak and Longest intact codon streak), Alternative codons are treated as Lost;
for “middle 80%” statistics (Middle 80% CDS presence and Middle 80% CDS intactness), Alternative codons are treated as intact

## let's slightly modify case 2 above: 
insertion in codon 8 is now one instead of two bases:
ref    | ATG CGC CTT | ACC CAA | TTG GAT GCG A-GA CAT TAA |
query  | ATG --- -CT | NNN NNN | TAG CAG GTT AAAA TAC TGA |
codons |  I   D   L  |  M   M  |  L   I   I    L   I   I  |
                 [----alternative frame---------]
## sequence between codons 3 (-CT, one base deletion) and 8 (ATAA, one base insertion)
## contain no mutated codons (missing/deleted exons are not relevant here)
aligned      | ATG --- -CT TAG CAG GTT ATAA TAC TGA |
compensated  | ATG --- CTT AGC AGG TTA AAA  TAC TGA |

## no mutations indeed! the codon status sequence can be now modified as follows:
ref    | ATG CGC CTT | ACC CAA | TTG GAT GCG A-GA CAT TAA |
query  | ATG --- -CT | NNN NNN | TAG CAG GTT AAAA TAC TGA |
codons |  I   D   A  |  M   M  |  A   A   A   A    I   I  |

## rewrite projection sequence as a sequence of codon symbols
IDAMMAAAAII

## calculate "longest streak" statistics
## 1) omit Deleted codons
IAMMAAAAII
## 2) replace Alternative codons with Lost codon symbols
ILMMLLLLII
## 3) split the sequence by Lost codons; for presence parameter, omit Missing codons
presence   I       II
Longest present codon streak: 2 / 10 = 0.2
intactness I MM    II 
Longest intact codon streak: 2 / 10 = 0.2
## so, neither of these statistics improved upon treating the frame 
## between two frameshifts as Alternative

## now, calculate the "middle 80% statistics"
## 1) define middle 80%; 10 * 0.8 = 8 => assess middle 8 codons
I | DAMMAAAAI | I
## 2) check middle 80% for Missing and Lost codons
DAMMAAAAI => 2 missing, 0 Lost codons
Middle 80% CDS presence = False
Middle 80% CDS intactness = True
## thus, frame compensation imroved one of four status compared to the original case 2

Fetching CDS integrity properties from the output files

CDS-related statistics are stored in transcript_meta.tsv file located at meta/ directory:

projection	loss_status	nuc_id%	blosum_id%	longest_intact_fraction	longest_nondeleted_fraction	total_intact_fraction	middle_80%_intact	middle_80%_present
ENST00000361902.5#GPX6#97	FI	80.63063063063063	74.82876712328768	1.0	1.0	1.0	MIDDLE_IS_INTACT	MIDDLE_IS_PRESENT

The statistics described above are contained in the following columns:

Longest intact codon streak - column 5 (longest_intact_fraction); contains a floating point number ranging between 0 and 1;
Longest non-deleted codon streak - column 6 (longest_nondeleted_fraction); contains a floating point number ranging between 0 and 1;
Total CDS intactness - column 7 (total_intact_fraction); contains a floating point number ranging between 0 and 1;
Middle 80% CDS intactness - column 8 (middle_80%_intact); set to MIDDLE_IS_INTACT if middle 80% CDS are intact, MIDDLE_IS_AFFECTED otherwise;
Middle 80% CDS presence - column 9 (middle_80%_present); set to MIDDLE_IS_PRESENT if middle 80% CDS do not contain missing codons, MIDDLE_IS_MISSING otherwise