Provided by: samtools_1.21-1_amd64 
NAME
samtools-ampliconstats - produces statistics from amplicon sequencing alignment file
SYNOPSIS
samtools ampliconstats [options] primers.bed in.sam|in.bam|in.cram...
DESCRIPTION
samtools ampliconstats collects statistics from one or more input alignment files and produces tables in
text format. The output can be visualized graphically using plot-ampliconstats.
The alignment files should have previously been clipped of primer sequence, for example by "samtools
ampliconclip" and the sites of these primers should be specified as a bed file in the arguments. Each
amplicon must be present in the bed file with one or more LEFT primers (direction "+") followed by one or
more RIGHT primers. For example:
MN908947.3 1875 1897 nCoV-2019_7_LEFT 60 +
MN908947.3 1868 1890 nCoV-2019_7_LEFT_alt0 60 +
MN908947.3 2247 2269 nCoV-2019_7_RIGHT 60 -
MN908947.3 2242 2264 nCoV-2019_7_RIGHT_alt5 60 -
MN908947.3 2181 2205 nCoV-2019_8_LEFT 60 +
MN908947.3 2568 2592 nCoV-2019_8_RIGHT 60 -
Ampliconstats will identify which read belongs to which amplicon. For purposes of computing coverage
statistics for amplicons with multiple primer choices, only the innermost primer locations are used.
A summary of output sections is listed below, followed by more detailed descriptions.
SS Amplicon and file counts. Always comes first
AMPLICON Amplicon primer locations
FSS File specific: summary stats
FRPERC File specific: read percentage distribution between amplicons
FDEPTH File specific: average read depth per amplicon
FVDEPTH File specific: average read depth per amplicon, full length only
FREADS File specific: numbers of reads per amplicon
FPCOV File specific: percent coverage per amplicon
FTCOORD File specific: template start,end coordinate frequencies per amplicon
FAMP File specific: amplicon correct / double / treble length counts
FDP_ALL File specific: template depth per reference base, all templates
FDP_VALID File specific: template depth per reference base, valid templates only
CSS Combined summary stats
CRPERC Combined: read percentage distribution between amplicons
CDEPTH Combined: average read depth per amplicon
CVDEPTH Combined: average read depth per amplicon, full length only
CREADS Combined: numbers of reads per amplicon
CPCOV Combined: percent coverage per amplicon
CTCOORD Combined: template coordinates per amplicon
CAMP Combined: amplicon correct / double / treble length counts
CDP_ALL Combined: template depth per reference base, all templates
CDP_VALID Combined: template depth per reference base, valid templates only
File specific sections start with both the section key and the filename basename (minus directory and
.sam, .bam or .cram suffix).
Note that the file specific sections are interleaved, ordered first by file and secondly by the file
specific stats. To collate them together, use "grep" to pull out all data of a specific type.
The combined sections (C*) follow the same format as the file specific sections, with a different key.
For simplicity of parsing they also have a filename column which is filled out with "COMBINED". These
rows contain stats aggregated across all input files.
SS / AMPLICON
This section is once per file and includes summary information to be utilised for scaling of plots, for
example the total number of amplicons and files present, tool version number, and command line arguments.
The second column is the filename or "COMBINED". This is followed by the reference name (unless single-
ref mode is enabled), and the summary statistic name and value.
The AMPLICON section is a reformatting of the input BED file. Each line consists of the reference name
(unless single-ref mode is enable), the amplicon number and the start-end coordinates of the left and
right primers. Where multiple primers are available these are comma separated, for example 10-30,15-40
in the left primer column indicates two primers have been multiplex together covering genome coordinates
10-30 inclusive and 14-40 inclusively.
CSS SECTION
This section consists of summary counts for the entire set of input files. These may be useful for
automatic scaling of plots.
Number of amplicons Total number of amplicons listed in primer.bed
Number of files Total number of SAM, BAM or CRAM files
End of summary Always the last item. Marker for end of CSS block.
FSS SECTION
This lists summary statistics specific to an individual input file. The values reported are:
raw total sequences Total number of sequences found in the file
filtered sequences Number of sequences filtered with -F option
failed primer match Number of sequences that did not correspond to
a known primer location
matching sequences Number of sequences allocated to an amplicon
FREADS / CREADS SECTION
For each amplicon, this simply reports the count of reads that have been assigned to it. A read is
assigned to an amplicon if the start and/or end of the read is within a specified number of bases of the
primer sites listed in the bed file. This distance is controlled via the -m option.
FRPERC / CRPERC SECTION
For each amplicon, this lists what percentage of reads were assigned to this amplicon out of the total
number of assigned reads. This may be used to diagnose how uniform this distribution is.
Note this is a pure read count and has no relation to amplicon size.
FDEPTH / CDEPTH / FVDEPTH / CVDEPTH SECTION
Using the reads assigned to each amplicon and their start / end locations on that reference, computed
using the POS and CIGAR fields, we compute the total number of bases aligned to this amplicon and
corresponding the average depth. The VDEPTH variants are filtered to only include templates with end-to-
end coverage across the amplicon. These can be considered to be "valid" or "usable" templates and give
an indication of the minimum depth for the amplicon rather than the average depth.
To compute the depth the length of the amplicon is computed using the innermost set of primers, if
multiple choices are listed in the bed file.
FPCOV / CPCOV SECTION
Similar to the FDEPTH section, this is a binary status of covered or not covered per position in each
amplicon. This is then expressed as a percentage by dividing by the amplicon length, which is computed
using the innermost set of primers covering this amplicon.
The minimum depth necessary to constitute a position as being "covered" is specifiable using the -d
option.
FTCOORD / CTCOORD / FAMP / CAMP SECTION
It is possible for an amplicon to be produced using incorrect primers, giving rise to extra-long
amplicons (typically double or treble length).
The FTCOORD field holds a distribution of observed template coordinates from the input data. Each row
consists of the file name, the amplicon number in question, and tab separated tuples of start, end,
frequency and status (0 for OK, 1 for skipping amplicon, 2 for unknown location). Each template is only
counted for one amplicon, so if the read-pairs span amplicons the count will show up in the left-most
amplicon covered.
Th COORD data may indicate which primers are being utilised if there are alternates available for a given
amplicon.
For COORD lines amplicon number 0 holds the frequency data for data that reads that have not been
assigned to any amplicon. That is, they may lie within an amplicon, but they do not start or end at a
known primer location. It is not recorded for BED files containing multiple references.
The FAMP / CAMP section is a simple count per amplicon of the number of templates coming from this
amplicon. Templates are counted once per amplicon, but and like the FTCOORD field if a read-pair spans
amplicons it is only counted in the left-most amplicon. Each line consists of the file name, amplicon
number and 3 counts for the number of templates with both ends within this amplicon, the number of
templates with the rightmost end in another amplicon, and the number of templates where the other end has
failed to be assigned to an amplicon.
Note FAMP / CAMP amplicon number 0 is the summation of data for all amplicons (1 onwards).
FDP_ALL / CDP_ALL / FDP_VALID / CDP_VALID section
These are for depth plots per base rather than per amplicon. They distinguish between all reads in all
templates, and only reads in templates considered to be "valid". Such templates have both reads (if
paired) matching known primer locations from he same amplicon and have full length coverage across the
entire amplicon.
This FDP_VALID can be considered to be the minimum template depth across the amplicon.
The difference between the VALID and ALL plots represents additional data that for some reason may not be
suitable for producing a consensus. For example an amplicon that skips a primer, pairing 10_LEFT with
12_RIGHT, will have coverage for the first half of amplicon 10 and the last half of amplicon 12.
Counting the number of reads or bases alone in the amplicon does not reveal the potential for non-
uniformity of coverage.
The lines start with the type keyword, file / sample name, reference name (unless single-ref mode is
enabled), followed by a variable number of tab separated tuples consisting of depth,length. The length
field is a basic form of run-length encoding where all depth values within a specified fraction of each
other (e.g. >= (1-fract)*midpoint and <= (1+fract)*midpoint) are combined into a single run. This
fraction is controlled via the -D option.
OPTIONS
-f, --required-flag INT|STR
Only output alignments with all bits set in INT present in the FLAG field. INT can be specified
in hex by beginning with `0x' (i.e. /^0x[0-9A-F]+/) or in octal by beginning with `0' (i.e.
/^0[0-7]+/) [0], or in string form by specifying a comma-separated list of keywords as listed by
the "samtools flags" subcommand.
-F, --filter-flag INT|STR
Do not output alignments with any bits set in INT present in the FLAG field. INT can be
specified in hex by beginning with `0x' (i.e. /^0x[0-9A-F]+/) or in octal by beginning with `0'
(i.e. /^0[0-7]+/) [0], or in string form by specifying a comma-separated list of keywords as
listed by the "samtools flags" subcommand.
-a, --max-amplicons INT
Specify the maximum number of amplicons permitted.
-b, --tcoord-bin INT
Bin the template start,end positions into multiples of NT prior to counting their frequency and
reporting in the FTCOORD / CTCOORD lines. This may be useful for technologies with higher errors
rates where the alignment ends will vary slightly. Defaults to 1, which is equivalent to no
binning.
-c, --tcoord-min-count INT
In the FTCOORD and CTCOORD lines, only record template start,end coordinate combination if they
occur at least INT times.
-d, --min-depth INT
Specifies the minimum base depth to consider a reference position to be covered, for purposes of
the FRPERC and CRPERC sections.
-D, --depth-bin FRACTION
Controls the merging of neighbouring similar depths for the FDP_ALL and FDP_VALID plots. The
default FRACTION is 0.01, meaning depths within +/- 1% of a mid point will be aggregated together
as a run of the same value. This merging is useful to reduce the file size. Use -D 0 to record
every depth.
-l, --max-amplicon-length INT
Specifies the maximum length of any individual amplicon.
-m, --pos-margin INT
Reads are compared against the primer start and end locations specified in the BED file. An
aligned sequence should start precisely at these locations, but sequencing errors may cause the
primer clipping to be a few bases out or for the alignment to add a few extra bases of soft clip.
This option specifies the margin of error permitted when matching a read to an amplicon number.
-o FILE
Output stats to FILE. The default is to write to stdout.
-s, --use-sample-name
Instead of using the basename component of the input path names, use the SM field from the first
@RG header line.
-S, --single-ref
Force the output format to match the older single-reference style used in Samtools 1.12 and
earlier. This removes the reference names from the SS, AMPLICON, DP_ALL and DP_VALID sections.
It cannot be enabled if the input BED file has more than one reference present. Note that plot-
ampliconstats can process both output styles.
-t, --tlen-adjust INT
Adjust the TLEN field by +/- INT to compensate for primer clipping. This defaults to zero, but
if the primers have been clipped and the TLEN field has not been updated using samtools fixmate
then the template length will be wrong by the sum of the forward and reverse primer lengths.
This adjustment does not have to be precise as the --pos-margin field permits some leeway. Hence
if required, it should be set to approximately double the average primer length.
-@ INT Number of BAM/CRAM (de)compression threads to use in addition to main thread [0].
EXAMPLE
To run ampliconstats on a directory full of CRAM files and then produce a series of PNG images named
"mydata*.png":
samtools ampliconstats V3/nCoV-2019.bed /path/*.cram > astats
plot-ampliconstats -size 1200,900 mydata astats
AUTHOR
Written by James Bonfield from the Sanger Institute.
SEE ALSO
samtools(1), samtools-ampliconclip(1) samtools-stats(1), samtools-flags(1)
Samtools website: <http://www.htslib.org/>
samtools-1.21 12 September 2024 samtools-ampliconstats(1)