Skip to content

Output files

Jump to bottom
martinghunt edited this page Mar 4, 2022 · 7 revisions

WARNING: this is under construction, and incomplete.

Overview

There are three output files:

  1. results.tsv - this is the overall file of results for the run. It is most likely the file you want. It is a tab-delimited file of counts of the truth bases vs what was called in the consensus.
  2. results.json - this contains the same information as in results.tsv, but is in JSON format.
  3. per_position.tsv - a detailed tab-delimited file, containing one line per reference position. It shows the multiple alignment of the reference, truth (inferred from the truth VCF file), and the sequence being evaluated. At each position the assigned category of truth and called bases is shown, where the categories are the same as those used in results.tsv.

Categorising each base of the genome

We will describe the per_position.tsv file first, since it understanding it is necessary to understand results.tsv.

The overall method is to first make an inferred "truth genome" by applying all the variants in the input truth VCF file to the reference genome. Then a multiple sequence alignment (MSA) of the reference, inferred truth, and sequence to be evaluated is made. This MSA is inspected at each position to categorise the correctness of the sequence to be evaluated. The results of this per-position evaluation is written to per_position.tsv. It will look like this:

Ref_pos  Ref  Truth  Consensus  Truth_category  Consensus_category
31       A    A      A          True_ref        Called_ref
32       C    C      C          True_ref        Called_ref
33       C    C      C          True_ref        Called_ref
... etc for the rest of the aligned genomes ...

In this case, it starts at position 31 because this example is the start of output where the amplicon scheme was ARTIC version 3. The first amplicon starts at position 31, so we do not evaluate positions before 31.

There are many possibilities in the Truth_category and Consensus_category! In the above 3 rows, the reference, truth genome, and consensus sequence were in agreement. The truth category True_ref means that the "truth" call is that the consensus should match the reference. Since it does match, the consensus category is Called_ref because it did indeed call the reference base. Most lines of this file will look like this (unless you evaluate terrible consensus!), since most positions will have no variation.

The possible truth categories are:

  • True_ref: the reference and truth bases are the same
  • SNP_true_alt: the truth base is different from the reference, and is one of A, C, G, T.
  • SNP_true_mixed: the truth base is different from the reference, and is a heterozygous call - one of the ambiguous heterozygous IUPAC codes K, M, R, S, W, Y.
  • Unknown_truth: the truth is unknown, for which we use N.
  • True_indel: there should be an insertion or deletion, which means either the reference or truth base will be -.
  • Dropped_amplicon: we expect the amplicon to have no consensus called because it was missing from the sequencing reads. The truth base will be Z in this case.

The consensus categories are:

  • Called_ref: the consensus base is the same as the reference
  • Called_correct_alt: the truth is a homozygous SNP or indel and the consensus called it correctly
  • Called_wrong_alt: the consensus has an incorrect homozygous SNP
  • Called_N: the consensus called an N
  • Called_correct_IUPAC: the consensus correctly called a heterozygous SNP
  • Called_wrong_IUPAC: the consensus incorrectly called a heterozygous SNP
  • Called_wrong_indel: the consensus incorrectly called an indel
  • Dropped_amplicon: the consensus looks like a dropped amplicon. This is determined by inspecting all runs of Ns in the consensus sequence. If such a run covers an amplicon, then the Ns at the amplicon position are replaced with Z, which is used to denote a dropped amplicon.
  • Called_other: when the truth is not known (Unknown _truth), this consensus category is used (except when the category is Dropped_amplicon, No_call_genome_ends, or called N).
  • No_call_genome_ends: depending on the method used to generate the consensus, the consensus may not begin at the start of the first amplicon, or finish at the end of the last amplicon. Such positions are classified as No_call_genome_ends, instead of calling them a deletion.

Clone this wiki locally