Why are the allele percentages in my Allele Plot different than the values in the accompanying Allele Table?

[kclem]

The Problem

You may have noticed that the allele percentages and counts in your allele plot (9.Alleles_frequency_table_around_gRNA.pdf) don't exactly match the values reported in the accompanying data table (Alleles_frequency_table_around_gRNA.txt). This is due to some differences in collapsing alleles for visualization, and can sometimes arise when you provide multiple guides or your quantification window is larger than your plotting window size.

Quick Solution

If you want to have the values on the allele plot match the values in the allele table, you can run CRISPResso with the parameter --expand_allele_plots_by_quantification. However, to understand why this isn't the default behavior, and why the numbers in your allele plot don't exactly match the numbers in your allele table, read on.

Explanation

When alleles are reported in the Alleles_frequency_table_around_gRNA.txt file, alleles are defined by:

1. the aligned read sequence around the gRNA cut site (default 20bp up- and downstream from the cut site),
2. the aligned reference sequence around the cut site,
3. whether the read is edited,
4. the number of inserted bases in the quantification window
5. the number of deleted bases in the quantification window, and
6. the number of substitutions in the quantification window.

When alleles are plotted, alleles collapsed based only on the read sequence and the reference sequence (1 and 2 above). This collapses several alleles that might otherwise have different values for the other properties (3-6 above). For this reason, the numbers in the allele plot are always the same or greater than the values in the allele table (because the allele table has un-collapsed alleles that are summed together in the allele plot). We chose to do this because the allele plot doesn't represent the other properties (3-6 above), so it could be considered misleading or confusing to plot two alleles with the same sequence on two different rows in the plot.

Verification

You can verify the allele plot counts by collapsing the alleles in the allele table by sequence using the following code. Replace the Alleles_frequency_table_around_gRNA.txt file with the path to your allele table.

# Read in the allele frequency table
import pandas as pd
df = pd.read_csv('Alleles_frequency_table_around_gRNA.txt',sep="\t")

# Examine the allele frequencies
df.head()

# Now, collapse by the Aligned_Sequence and Reference Sequence
df_to_plot = df.groupby(['Aligned_Sequence', 'Reference_Sequence']).sum().reset_index()
df_to_plot.sort_values(by=['#Reads', 'Aligned_Sequence', 'Reference_Sequence'], inplace=True, ascending=[False, True, True])

# These allele counts should exactly match the values on the plot.
df_to_plot.head()

Demo

You can explore the allele-collapsing behavior yourself using the following code:

First, get some demo data and run CRISPResso.

To get the allele frequency table above, I ran the following short demo analysis:

wget http://crispresso.pinellolab.org/static/demo/nhej.r1.fastq.gz
wget http://crispresso.pinellolab.org/static/demo/nhej.r2.fastq.gz
CRISPResso -r1 nhej.r1.fastq.gz -r2 nhej.r2.fastq.gz -a AATGTCCCCCAATGGGAAGTTCATCTGGCACTGCCCACAGGTGAGGAGGTCATGATCCCCTTCTGGAGCTCCCAACGGGCCGTGGTCTGGTTCATCATCTGTAAGAATGGCTTCAAGAGGCTCGGCTGTGGTT -n nhej -g CTGGAGCTCCCAACGGGCCG,CATCTGGCACTGCCCACAGGTGA -w 3

The allele plot shows:

Now, compare these values to those in the allele table.

# Read in the allele frequency table
import pandas as pd
df = pd.read_csv('Alleles_frequency_table_around_gRNA.txt',sep="\t")

# Examine the allele frequencies
df.head()

	Aligned_Sequence	Reference_Sequence	Unedited	n_deleted	n_inserted	n_mutated	#Reads	%Reads
0	CTTCTGGAGCTCCCAACGGGCCGTGGTCTGGTTCATCATC	CTTCTGGAGCTCCCAACGGGCCGTGGTCTGGTTCATCATC	True	0	0	0	5903	24.116518
1	CTTCTGGAGCTCCCAACG-----TGGTCTGGTTCATCATC	CTTCTGGAGCTCCCAACGGGCCGTGGTCTGGTTCATCATC	False	5	0	0	4905	20.039220
2	CTTCTGGAGCTCCCAACGGGGCCGTGGTCTGGTTCATCAT	CTTCTGGAGCTCCCAACGGG-CCGTGGTCTGGTTCATCAT	False	0	1	0	1450	5.923929
3	CTTCTGGAGCTCCCAACGG-CCGTGGTCTGGTTCATCATC	CTTCTGGAGCTCCCAACGGGCCGTGGTCTGGTTCATCATC	False	1	0	0	1157	4.726886
4	CTTCTGGAGC-----------CGTGGTCTGGTTCATCATC	CTTCTGGAGCTCCCAACGGGCCGTGGTCTGGTTCATCATC	False	11	0	0	603	2.463537

Note that the most frequent allele has a frequency of 24.12% (the allele is shown as 24.18% in the allele plot above).

# Now, collapse by the Aligned_Sequence and Reference Sequence
df_to_plot = df.groupby(['Aligned_Sequence', 'Reference_Sequence']).sum().reset_index()
df_to_plot.sort_values(by=['#Reads', 'Aligned_Sequence', 'Reference_Sequence'], inplace=True, ascending=[False, True, True])

# These allele counts should exactly match the values on the plot above.
df_to_plot.head()

	Aligned_Sequence	Reference_Sequence	Unedited	n_deleted	n_inserted	n_mutated	#Reads	%Reads
738	CTTCTGGAGCTCCCAACGGGCCGTGGTCTGGTTCATCATC	CTTCTGGAGCTCCCAACGGGCCGTGGTCTGGTTCATCATC	1	1	0	1	5919	24.181885
635	CTTCTGGAGCTCCCAACG-----TGGTCTGGTTCATCATC	CTTCTGGAGCTCCCAACGGGCCGTGGTCTGGTTCATCATC	0	15	8	1	4917	20.088246
760	CTTCTGGAGCTCCCAACGGGGCCGTGGTCTGGTTCATCAT	CTTCTGGAGCTCCCAACGGG-CCGTGGTCTGGTTCATCAT	0	0	2	1	1454	5.940270
690	CTTCTGGAGCTCCCAACGG-CCGTGGTCTGGTTCATCATC	CTTCTGGAGCTCCCAACGGGCCGTGGTCTGGTTCATCATC	0	2	0	1	1158	4.730972
341	CTTCTGGAGC-----------CGTGGTCTGGTTCATCATC	CTTCTGGAGCTCCCAACGGGCCGTGGTCTGGTTCATCATC	0	11	0	0	603	2.463537

Now, the most-frequent allele sequence has an allele frequency of 24.18, which matches the allele plot above 😤.

Demo using --expand_allele_plots_by_quantification

We could also run the original command with the flag --expand_allele_plots_by_quantification to produce an allele plot with the same counts as the allele table.

CRISPResso -r1 nhej.r1.fastq.gz -r2 nhej.r2.fastq.gz -a AATGTCCCCCAATGGGAAGTTCATCTGGCACTGCCCACAGGTGAGGAGGTCATGATCCCCTTCTGGAGCTCCCAACGGGCCGTGGTCTGGTTCATCATCTGTAAGAATGGCTTCAAGAGGCTCGGCTGTGGTT -n nhej_expanded -g CTGGAGCTCCCAACGGGCCG,CATCTGGCACTGCCCACAGGTGA -w 3  --expand_allele_plots_by_quantification

This produces the output plot with counts that match the allele table.

I hope that clears things up!