If primer coordinates are known (recommended)

Provide a BED file with at least 4 columns: chrom, chromStart, chromEnd, primerName. Additional columns can be included: pool, strand, sequence, but their order must be maintained.

For example, chrom, chromStart, chromEnd, primerName, pool for 5-column BED format:

#chrom  chromStart  chromEnd  primerName     pool
seqX    0           15        primer1_LEFT   1
seqX    1745        1760      primer1_RIGHT  1
seqY    0           15        primer2_LEFT   2
seqY    1015        1030      primer2_RIGHT  2

And chrom, chromStart, chromEnd, primerName, pool, strand, sequence for 7-column BED format:

#chrom  chromStart  chromEnd  primerName     pool  strand  sequence
seqX    0           15        primer1_LEFT   1     +       GGGCAAACCTAAAGG
seqX    1745        1760      primer1_RIGHT  1     -       GTTATGTAAAGGTGC
seqY    0           15        primer2_LEFT   2     +       GGGCGAAACTAAAGG
seqY    1015        1030      primer2_RIGHT  2     -       GTTATGTAAAGGTGC

If primer coordinates are unknown

Option 1. One line per amplicon with 3 columns: ampliconName, forwardSequence,reverseSequence.

#ampliconName  forwardSequence  reverseSequence
amplicon1      GGGCAAACCTAAAGG  GTTATGTAAAGGTGC
amplicon2      GGGCGAAACTAAAGG  GTTATGTAAAGGTGC

Option 2. One line per primer with 3 columns: primerName, sequence, pool.

#primerName       sequence         pool
primer1_LEFT      GGGCAAACCTAAAGG  1
primer1_LEFT_alt  GGGCGAAACTAAAGG  1
primer1_RIGHT     GTTATGTAAAGGTGC  1

Formatting rules

• General

  • All text is case sensitive.

  • Any line starting with '#' is ignored. This can be used to add a header line with column names.

  • Every line must have the same number of columns and format (except those starting with '#').

  • Any number of spaces can separate the columns. A value within a single column should not have any space.

• BED format

  • Per standard BED conventions, sequence coordinates are given as 0-based, half-open intervals, such that the chromStart field (2nd column) contains the first nucleotide in the primer binding site and the last nucleotide in the primer binding site is the value in the chromEnd field (3rd column) minus 1.

  • chrom field must contain a sequence identifier that matches the header of the FASTA file containing the sequence that the coordinates are relative to.

  • Multiple sequence identifiers (chrom) are permitted within one file.

• Primer name

  • primerName must be unique and encode the name of the amplicon for which the primer is designed, the direction tag indicating which side of the amplicon, left or right, the primer belongs to, and an optional indicator that the primer is an alternative primer for that amplicon.

  • In addition to _LEFT and _RIGHT, we permit _L and _R as direction tags in primerName. Any text after the direction tag should be separated by an underscore.

  • Text in primerName before the direction tag is considered to be an amplicon identifier. Ensure that the text of the amplicon identifier is unique for that amplicon and that the direction tag occurs only once in primerName.

  • Each amplicon must have at least one left and right primer (including alternative primers) associated with it.

  • Alternative primers are used to bind to locations that avoid sequence variation in the default primer binding site that may disrupt hybridization. An amplicon may have an arbitrary number of alternative primers (as long as the primer name is unique), but most amplicons will have none. Alternative primers are indicated by the presence of the _alt after the direction tag in primerName, followed by optional text to distinguish between different alternative primers, such as a number.

  • Examples of valid primer names:

    • MY_SEQUENCE_434_A_LEFT

    • virus1_L

    • amplicon_4934m_RIGHT_alt

    • amplicon_4934m_RIGHT_alt1

    • amplicon_4934m_R_altprimerB

  • Examples of invalid primer names:

    • LEFT_MY_SEQUENCE_434_A

    • virus1_l

    • amplicon_4934m_RIGHT_L

1. Launch the DRAGEN Targeted Microbial BaseSpace application.

2. After choosing a name and destination project for the Analysis, choose either “Biosample” or “Project” as input type. Selecting “Project” will result in all biosamples in the selected project being analyzed.

3. Next, choose between Enrichment and Amplicon for Experiment Type. Libraries prepared with IMAP should be run as “Amplicon” experiments. Choose the appropriate Amplicon Primer Set that matches the primer design used to prepare your samples or choose “Custom” to provide your own genome references and primer designs. Note that all provided files must first be uploaded to a BaseSpace project before they can be selected in the software.

4. To use a custom reference and primer design, click the “Custom Reference” block to expand it.

5. At a minimum, the user must provide a custom genome reference containing one or more target sequences (to be used for alignment, variant calling and consensus generation) in the form of a FASTA file.

   1. Optionally, the user may provide a BED file that assigns human-readable names and segment numbers (if applicable) to each sequence in the provided FASTA file. Note that the accessions in the genome definition file must match the first part (before whitespace) of the FASTA headers. See the pages for “Genome Definition File Format Specification” in the “Supporting Information” section of this user guide for information on the required format of this file.

   2. Optionally, the user may provide a file containing the locations or sequences of the primers used to prepare this sample. These primer definitions are important to guide the trimming of primer sequence from reads that overlap the binding sites, as well as to define the boundaries of the amplicons whose coverage is used to determine if the sample has sufficient viral material to reliably call variants and generate consensus sequence.

   3. Optionally, the user may choose one or more NextClade datasets to use for phylogenetic analysis of the consensus sequences generated from the samples.

6. Check the appropriate boxes to enable or disable Pangolin and/or NextClade analysis if desired. These tools perform phylogenetic analysis and lineage assignment for SARS-CoV-2 (Pangolin) and other viruses (NextClade). Depending on the chosen Amplicon primer set, not all of these options may be applicable.

7. Click “Launch Application” to begin the Analysis.

In addition to the built-in options, DRAGEN Targeted Microbial supports the use of custom reference genomes and primer definitions. These files must be uploaded to a BaseSpace Project before they can be used. See for more information about importing files into BaseSpace. These files can be used for both Enrichment and Amplicon libraries, when choosing the 'Custom' option for 'Enrichment Panel' or 'Amplicon Primer Set', respectively. Expand the 'Custom Reference' settings block to access the options for custom files. The following controls are applicable to the specified experiment type:

Custom Enrichment Panel

• Custom Reference FASTA for Consensus Generation (required)

• Custom Reference BED (optional)

Custom Amplicon Primer Set

• Custom Reference FASTA for Consensus Generation (required)

• Custom Reference BED (optional)

• Custom PCR Primer Definitions (optional)

Custom genome references

The user may provide one or more reference genomes as the target for read alignment (and as the basis for generating consensus sequences). At a minimum, the user must provide a FASTA file containing the sequences of the reference genomes. The software will generate the required DRAGEN hash tables and other auxiliary files automatically, so there is no need to process the FASTA file with a separate app. Use the 'Custom Reference FASTA for Consensus Generation' control to select the previously-uploaded FASTA file containing the reference sequences.

Optionally, a genome definition BED file may also be provided, which tells the software more information about each sequence, such as a human-readable common name to be used in the reports. For multi-segment genomes such as Influenza, the genome definition file provides the segment name of each sequence and indicates that all the segments of a single genome belong together. Use the 'Custom Reference BED' control to select the previously-uploaded BED file containing the genome definition. See the following page for a description of the format of the genome definition file:

Custom primer sets

For amplicon experiments, the user may optionally provide a file that defines the primer sequences or locations. The primers defined in this file are used for two purposes:

1. The primer binding locations are used to trim reads, which eliminates sequence data that may be contributed by the primer sequences themselves (which we do not want) from sequence data contributed by the sample (which we do want). This is important to avoid reference bias that can depress the observed allele frequency of sequence variants in primer binding sites.

2. The primers are matched to define the boundaries of the expected amplicons resulting from the PCR reaction. The read coverage within the unique (non-overlapping) regions of these amplicons is used to determine whether or not each amplicon is reliably observed. The fraction of observed amplicons is a function of the concentration of the sample, and is used to determine whether or not sufficient material exists within the sample to reliably and accurately call variants and generate a consensus sequence. See this page for a more in-depth discussion:

Use the 'Custom PCR Primer Definitions' control to select the previously-uploaded primer definition file. The allowed formats for this file are described here:

Required custom input based on reference type for amplicon experiments

A BED-like tab-separated value (TSV) file with no header row, consisting of the following columns:

1. chrom: each sequence name as it appears in Custom Reference FASTA

2. chromStart: start position (always set to 0)

3. chromEnd: end position (sequence length)

4. genomeName: full name of the virus the sequence belongs to (e.g. Monkeypox virus clade II)

5. (optional) segmentName: how this sequence is labeled within the virus (e.g. Segment 4 (HA)). Set to 'Full' if the sequence is the full genome

Guidelines

• This file affects how sequences are labeled in the output.

• Sequence names must match those in Custom Reference FASTA. The same set of sequences must appear in both.

• If there are multiple viruses, their names should be unique. For example, if there are multiple Influenza genomes, they should not be labeled with the same virus name in the 4th column.

• If the Custom Reference FASTA includes sequences from multiple segments, it is recommended to provide this BED file. Otherwise, each segment will be treated independently and not all of them may be used as reference.

Example

Metrics by Sample Table

At the top of the report, after the app version display, is the Metrics by Sample table which provides a top-line summary of each of the analyzed samples.

The first element is a button that will trigger downloading of a FASTA-formatted file containing all consensus sequences generated across all samples.

The "Download CSV" button allows for downloading the contents of the table as a text comma-separated value (CSV) file. Note that for fields with multiple entries, these entries will be combined as a semicolon-separated list in the corresponding fields in the CSV file.

Next is the table itself, which contains one row per sample. The various genomes generated for each sample are nested as sub-rows within this row.

The table contains one row per sample and the following columns:

1. Sample: The name of the BaseSpace sample analyzed. The sample name is a clickable link that will take you directly to the Result Report for that sample.

3. Num genomes: The number of genomes chosen during the reference selection stage of the pipeline

4. Genomes generated: The names of each genome chosen during the reference selection stage. If the percentage of callable bases (callable bases are defined as genomic positions with read coverage above the minimum read coverage depth for consensus sequence generation, 10x by default) for a genome is below the minimum percentage of consensus sequence generated to label as confident (5% by default), the cell is highlighted in yellow to indicate that there is only marginal evidence that the indicated genome is present in the sample and should be treated with caution. For amplicon experiments, if the sample is considered to have insufficient titer for VC because the percentage of detected amplicons is below the minimum percentage required for reliable variant calling (80% by default), cells are highlighted in orange. For genomes for which a consensus sequence was generated, clicking on the name of that genome initiates a download of a FASTA file containing the consensus sequences of that genome only.

5. % callable bases: The percentage of the selected reference genome whose bases are considered "callable." Callable bases are those for which reliable variant calling can be performed and therefore for which the software can output a base call. Callable bases are defined as genomic positions with read coverage above the minimum read coverage depth for consensus sequence generation (10x by default). Note that genomic positions below the confidence threshold are hard-masked with "N" characters to avoid reference bias (inclusion of a reference base when the actual base cannot be accurately determined). Note that this percentage is calculated over the lengths of the reference genome(s), not the reported consensus sequence(s).

6. Status: The overall outcome of the analysis for this virus

   1. Full analysis (consensus, VC) means that the sample analysis completed normally, that a sufficient number of amplicons were detected to ensure reliable variant calling (amplicon experiments only), and that the percentage of callable bases was above the minimum percentage of consensus sequence generated to label as confident (5% by default)

   2. Low confidence means that there is at lease one callable base but the overall percentage of callable bases was below the minimum percentage of consensus sequence generated to label as confident (5% by default)

   3. No callable bases indicates that zero positions in the indicated reference genome were callable and no consensus sequence is therefore provided.
7. Consensus FASTA: This column contains links to download a FASTA-formatted text file containing all of the consensus genomes generated for a sample. If no consensus genomes were generated for a sample, this column contains "N/A."

8. Input read count: The number of reads (or read pairs / clusters for paired-end samples) in the sample.

9. Mapped read count: The number of reads that could be mapped to any reference genome.

10. Unmapped reads: Displays buttons that initiate downloads of gzipped FASTQ files containing reads that could not be mapped to any reference genomes.

11. Raw Contigs: Displays a button that initiates a download of a FASTA file containing all contigs generated during the de novo assembly step of the pipeline. If a contig could be mapped to a reference genome the contig name contains information about the reference genome they aligned to.

Pangolin Report (optional)

This table contains the results of the Pangolin analysis performed on the generated consensus sequences across all samples. Pangolin is run if the "Enable Pangolin" box is checked on the input form and one of the following is true:

• 'Enrichment Panel' is set to a non-custom panel (e.g. VSP) and a consensus sequence was generated using SARS-CoV-2 as reference

• 'Amplicon Primer Set' is set to a non-custom set with SARS-CoV-2 as reference (e.g. SARS-CoV-2, ARTIC v5.3.2 primers) and a valid consensus sequence was generated

• Either 'Enrichment Panel' or 'Amplicon Primer Set' is set to 'Custom'. In this case, Pangolin is applied to every consensus sequence generated for the sample since the software assumes all of them to be potentially SARS-CoV-2 sequences.

The Pangolin report contains a "Download CSV" button which allows the user to download the contents of the report as a text CSV file.

NextClade Report (optional)

This table contains the results of the NextClade analysis performed on the generated consensus sequences across all samples. NextClade is run if the "Enable NextClade" box is checked on the input form and one of the following is true:

• 'Enrichment Panel' is set to a non-custom panel (e.g. VSP) and a consensus sequence was generated using a reference with NextClade dataset available.

• 'Amplicon Primer Set' is set to a non-custom set with a reference with NextClade dataset available (e.g. SARS-CoV-2, ARTIC v5.3.2 primers) and a valid consensus sequence was generated.

• Either 'Enrichment Panel' or 'Amplicon Primer Set' is set to 'Custom' and one or more NextClade datasets are selected under 'Custom Reference'. In this case, each of the selected NextClade datasets is applied to each consensus sequence generated for the sample. This may result in multiple NextClade results for each consensus sequence, some of which may not be meaningful (e.g. "flu_h1n1pdm_ha" dataset applied to a NA segment of an Influenza genome).

The NextClade Report contains a button labeled "Group table by" with a drop-down menu allowing the user to group the results by various fields, including "None". The default is "Dataset" which means that all of the results for each NextClade dataset will be grouped together. For example, if a user is only interested in phylogenetic analysis performed on the HA segment of Influenza A H1N1, these results for each sample can be viewed together in the "flu_h1n1pdm_ha" collapsible group.

The NextClade report also contains a "Download CSV" button which allows the user to download the contents of the report as a text CSV file.

▶️ DRAGEN Targeted Microbial App Documentation

Overview

Summary

DRAGEN Targeted Microbial is a software application designed to analyze sequencing data from enrichment and amplicon library preps (both DNA and RNA) on microbiological samples, with an emphasis on viruses. Illumina sequencing reads are processed to remove human-origin sequence, then assembled into consensus sequences that represent a best estimate of the population of viral sequences in each sample. Where appropriate, these consensus sequences are further analyzed by the phylogenetic analysis tools NextClade and/or Pangolin to provide an identification of the clade or lineage of each sequence.

Inputs

• Samples / biosamples with FASTQ datasets (see details in library preparation documents)

• A project containing one or more samples / biosamples with FASTQ datasets

  • all samples / biosamples in the selected project will be analyzed

Supported hybrid-capture enrichment panels

Supported amplicon primer schemes

Custom genomes and panels

Supports uploading FASTA files to use as reference genomes for both enrichment and amplicon panels, as well as custom primer definitions for amplicon panels. Multiplexed amplicon panels targeting multiple organisms in the same reaction are supported.

Analysis Pipeline

6. The best matching reference for each contig is selected for short read mapping.

7. The scrubbed reads from step 2 are aligned to the selected reference genomes using DRAGEN v4.2.4

8. Sequence variants are called from the alignments using DRAGEN Somatic Small Variant Caller v4.2.4 and applied to the corresponding reference sequences to create consensus sequences.

9. If applicable, Pangolin and/or Nextclade are run on the consensus sequences.

Outputs

The software generates consensus sequences representing a best estimate of the population of targeted sequences in the sample. NextClade and Pangolin analysis are run on select organisms. See this page for details:

Important Notes

• The sequences are labeled according to the best match in the panel references. These references are not exhaustive and the labels should not be taken as definitive for strain-typing. If strain typing is needed, the built-in NextClade and/or Pangolin tools can be used for supported organisms. Alternatively, a BLAST or similar search of nucleotide databases may provide a more detailed match.

• Because of sequence homology, it is possible that organisms with very few reads will result in the generation of a sequence not present (false positive). Although the de novo assembly step of this software largely mitigates such instances, sequences with very low horizontal coverage (< 5%) should be treated with caution and are highlighted as "low confidence" in the reports.

Currently supported platforms

• BaseSpace Sequence Hub (native BaseSpace app)

Amplicon sequencing, especially of RNA viruses, requires additional bioinformatics processing to ensure maximum quality of the resulting data.

In RT-PCR, a reverse transcriptase enzyme first generates cDNA molecules using the RNA molecules in the sample as templates, before amplifying the cDNA sequences using a DNA polymerase enzyme during PCR. These amplified cDNA sequences are then further processed to generate the sequencing libraries. Both of these enzymes can potentially introduce an incorrect base into a sequence, generating a position where the resulting sequence does not match the sequence in the sample -- that is, an error.

Reverse transcriptases exhibit error rates that are multiple orders of magnitude higher than those of DNA polymerases.

When large numbers of nucleic acid molecules are present in a reaction, these individual misincorporation errors are largely uncorrelated and appear at very low frequencies, so that they are typically ignored by variant callers.

However, when the number of incoming nucleic acid molecules is small, such as for a low-titer virus sample, an error that occurs during the RT step or early in the PCR reaction can, as a result of sampling noise, be amplified to high frequencies in the resulting sequencing libraries. When the variant caller encounters such a position, it will be treated as a sequence variant, since it is a true sequence variant in the context of the library provided to the instrument. As a result, these artifactual sequence variants often have high allele frequency and very good quality scores, which makes them very difficult to detect and remove. This can result in a false positive variant call that, at a sufficiently high allele frequency, will also be incorporated into the consensus sequence. It is also possible for a true sequence variant to have its allele frequency depressed by this same process (if the error results in a reversion to the reference sequence), but this is much less common.

Since it is difficult to identify enzyme-introduced false variants after the fact, we instead take a pre-emptive approach to ensuring data quality. As noted above, sampling noise as a function of molecular abundance is the mechanism responsible for boosting of the frequency of individual enzymatic errors into artifactual variants, and therefore the magnitude of this effect is largely a function of the concentration of the nucleic acids in the reaction. Therefore, the software first attempts to determine whether there is sufficient sample material present before proceeding with variant calling and consensus sequence generation.

To determine this, the software takes advantage of the fact that the probability of each amplicon being amplified is a function of the nucleic acid concentration, with higher concentrations leading to a higher probability of amplification. By counting the observed proportion of amplicons with detectable sequence coverage, we can estimate this probability and compare it to an experimentally-determined threshold that corresponds to the minimum concentration needed to produce reliable variant calls.

To compute this, we calculate the number of amplicons with at least 1x coverage for at least 90% of the non-overlapping portion of the amplicon sequence. The 1x coverage threshold used here is fixed and independent of the minimum read coverage depth for consensus sequence generation which defaults to 10x. The number of amplicons that meet this threshold is then divided by the total number of amplicons in the experiment, which is the number of amplicons whose location falls in reference sequences selected for short read alignment. If the resulting fraction is at least 80%, the sample is considered to have sufficient material for accurate variant calling and the variant calling and consensus sequence generation steps are performed. If it is below this threshold, the sample is not processed further to avoid spurious variant calls. The user can override the 80% threshold in the "Minimum percentage of amplicons with at least 90% coverage ≥ 1x to enable variant calling and consensus sequence generation" control in the "Advanced Workflow Settings" section. See App Settings.

For each sample, the pipeline generates a directory named after the sample. This directory contains the following subdirectories:

• consensus/

  • {sample_name}_sample_consensus.fasta : Contains all hard-masked consensus sequences for the sample. Regions with coverage below minimum coverage depth for consensus sequence generation (10x by default) are considered not callable and are therefore “hard-masked” with letter N. Variant calling is not applied to these regions. If the user selected specific VSP or RVOP organisms to be reported, this file excludes consensus sequences that are generated but do not belong to the selected organisms.

  • {sample_name}.consensus_hard_masked_sequence.fa : Identical to {sample_name}_sample_consensus.fasta, except for sequence headers. Moreover, even if the user selected specific VSP or RVOP organisms to be reported, this file contains all consensus sequences, including those that do not belong to the selected organisms

  • {sample_name}.consensus_soft_masked_sequence.fa : Identical to {sample_name}.consensus_hard_masked_sequence.fa, except low-coverage regions are “soft-masked” with lower-case letters that match the reference. Variant calling is not performed in these regions.

  • {sample_name}{virus_name}_virus_consensus.fasta : Contains hard-masked consensus sequences generated for a particular virus. If the virus is not segmented (i.e. one reference sequence for the virus), this file contains a single sequence and is identical to {sample_name}{virus_name}{segment_name}{sequence_accession} consensus.fasta.

  • {sample_name}_{virus_name}_{segment_name}_{sequence_accession}_consensus.fasta : Contains a hard-masked consensus sequence generated with a particular reference sequence.

  • {sample_name}.consensus_from_vcf.log : Log file generated during consensus sequence generation.

• contig/

  • {sample_name}_sample_contig.fasta : Contains all de novo assembled contigs generated for the sample.

  • {sample_name}_unmapped_contig.fasta : Contains de novo assembled contigs that could not be mapped to any reference sequence. Because de novo assembly is reference-free, these contigs may correspond to sequences that are too diverged from those in the reference database or sequences not included in the database.

  • {sample_name}_{virus_name}_virus_contig.fasta : Contains de novo assembled contigs that mapped to a particular virus.

  • {sample_name}_{virus_name}_{segment_name}_{sequence_accession}_contig.fasta : Contains de novo assembled contigs that mapped to a particular reference sequence, which resulted in choosing the reference sequence for short-read alignment and generating {sample_name}_{virus_name}_{segment_name}_{sequence_accession}_consensus.fasta.

  • {sample_name}_reference_selection.log : Log file generated during reference selection.

• map_align/

  • {sample_name}_unfiltered_tumor.bam or {sample_name}_unfiltered_tumor_primertrim_with_unmapped_reads.bam : Short reads mapped to all selected reference sequences. If a primer set is available and properly mapped to the reference sequences, {sample_name}_unfiltered_tumor_primertrim_with_unmapped_reads.bam is provided as output. Its reads have primer sequences trimmed based on primer binding site coordinates.

  • {sample_name}-unmapped_S1_L001_R1_001.fastq.gz, {sample_name}-unmapped_S1_L001_R2_001.fastq.gz : Short reads that do not map to any selected reference sequences. These may be used to find organisms not reported by the pipeline.

• variant_calling/

  • {sample_name}.consensus_filtered_variants.vcf.gz : Contains variant calls that passed consensus filter and were therefore applied to consensus sequences. They are a subset of variants listed in {sample_name}.hard-filtered.vcf.gz.

  • {sample_name}.consensus_filtered_variants_vcf_stats.txt : Summarizes all variant calls in {sample_name}.consensus_filtered_variants.vcf.gz. Outputted by bcftools stats.

  • {sample_name}.consensus_filtered_variants_summary.csv : Describes each variant call in {sample_name}.consensus_filtered_variants.vcf.gz.

  • {sample_name}.hard-filtered.vcf.gz : Contains all variant calls.

  • {sample_name}.consensus_input_vcf_stats.txt : Summarizes all variant calls in {sample_name}.hard-filtered.vcf.gz. Outputted by bcftools stats.

  • {sample_name}.consensus_all_variants_summary.csv : Describes each variant call in {sample_name}.hard-filtered.vcf.gz.

• metrics/

  • {sample_name}_num_reads.tsv : Reports number of input reads, reads filtered out at each pre-processing step, reads mapped to each selected reference sequence, etc.

  • {sample_name}_metadata.json : Reports parameters, read counts, amplicon counts, analysis results, and other metadata.

  • {sample_name}.consensus_metrics.csv : Reports consensus metrics (e.g. total length of pre-trimmed sequence, fraction of masked bases, number of callable bases) for each generated consensus sequence

  • {sample_name}.consensus_coverage_from_filtered_bam.tsv : Reports base-pair-resolution read coverage for all reference sequences based on short-read map/align step. Its three columns correspond to: chrom/accession, base position, coverage.

  • {sample_name}.consensus_callable_regions_from_filtered_bam.bed : Reports callable regions in all reference sequences based on base-pair-resolution read coverage and minimum coverage depth for consensus sequence generation (10x by default). Bases outside of these regions are masked in consensus FASTA.

• amplicon/

  • {sample_name}_processed_non_overlapping_amplicon.bed : Lists all non-overlapping amplicon regions (i.e. covered with exactly one amplicon). If a custom primer set is provided, this file also lists selected reference sequences lacking amplicons. While amplicons are defined based on primer binding sites, for viruses like Influenza, reference sequences often lack primer binding sites, which are located at sequence ends. This results in defining fewer or sometimes no amplicons for an entire viral genome. To avoid this, each reference sequence without any amplicons defined is considered an amplicon and is listed in this file. All regions in this file are used for amplicon detection to infer sample concentration and determine if it is sufficient to apply variant calling and consensus sequence generation.

  • {sample_name}_calculate_amplicon_coverage.csv : Reports coverage metrics (e.g. median coverage, fraction of bases with at least 1x coverage) for each non-overlapping amplicon region listed in {sample_name}_ processed_non_overlapping_amplicon.bed.

  • {sample_name}_generate_all_primer_bed.log : Log file generated while defining amplicons for selected reference sequences and writing relevant BED files.

• tertiary/

  • nextclade_{sample_name}_{sequence_accession}_{dataset_name}.csv : CSV output file generated by NextClade given a consensus sequence (generated with the specified sequence as reference) and a NextClade dataset.

  • nextclade_{sample_name}_{sequence_accession}_{dataset_name}.tsv : Same as nextclade_{sample_name} _{sequence_accession}_{dataset_name}.csv except in TSV format.

  • nextclade_{sample_name}_{sequence_accession}_{dataset_name}.json : Same as nextclade_{sample_name} _{sequence_accession}_{dataset_name}.csv except in JSON format.

  • nextclade_{sample_name}_{sequence_accession}_{dataset_name}_log.txt : Log file generated by NextClade given a consensus sequence (generated with the specified sequence as reference) and a NextClade dataset.

  • pangolin_{sample_name}_{sequence_accession}_lineage_report.csv : CSV output file generated by Pangolin given a consensus sequence (generated with the specified sequence as reference) as input.

  • pangolin_{sample_name}_{sequence_accession}_log.txt : Log file generated by Pangolin given a consensus sequence (generated with the specified sequence as reference) as input.

• reference/

  • reference.bed : Describes all reference sequences. If a custom reference was provided, sequence names may appear different in this BED file.

  • reference.json : Same as reference.bed but with more detail. If any of the sequences were renamed during the pipeline, this file provides the mapping between the original and renamed versions.

Q: After processing my sample with an enrichment panel, the majority of my reads are removed in preprocessing and/or I only have a small amount of viral reads. Is the enrichment panel working?

A: The enrichment protocols can create a several thousand fold increase in the abundance of the targeted viral species. However, it is important to keep in mind that in many sample types, especially clinical, wastewater, or environmental samples, viral RNA or DNA makes up a tiny proportion of the total nucleic acids present, with the remainder dominated by host (human) or bacteria/archaea. So even with a dramatic enrichment of abundance over what you would obtain without enrichment, the percentage of viral reads can still be low. E.g. you may have a sample with only 2% viral reads, but without enrichment you might have only obtained 0.1% viral reads. If it is low abundance after enrichment, it is likely extremely low abundance prior to enrichment.

Q: The contig default min coverage is 10x, but is that across the entire contig, median, average.. or?

A: The 10x threshold is applied per-nucleotide. Any positions below 10x coverage will be hard-masked with "N".

Q: In the demo data, I downloaded the consensus sequence FASTA file and each sequence line would say “Panel reference sequences are not necessarily comprehensive and should not be used for strain typing.” Does that mean even though VSP provide full-genome resolution of all 66 viruses, the app can only strain-type the strains listed because of the reference sequences the app uses?

A: Correct, we only align to a limited number of reference sequences for each virus type, so the sequence accession in the consensus genomes (and coverage plots, etc) merely reflects the best match chosen from that subset. There could be sequences in RefSeq that are a closer match. Furthermore, strain typing is not necessarily as simple as choosing the closest matching genome; there are further complexities that can go into it, and we have not systematically developed or tested any strain typing capability to date. The noted message is to warn users that the sequence accession in the consensus genome does not necessarily reflect the true phylogeny of the organisms in the sample and should not be taken as such.

Q: Why am I seeing some segments from one Influenza A subtype and some from another subtype? Does my sample contain both subtypes?

A: For each de novo assembled contig, we aim to find the best matching reference sequence rather than an entire reference genome. If the best match for one contig is a reference sequence from one subtype and the best match for another contig is a reference sequence from another subtype, then we will report them as such. This is not necessarily indicative of a mixed infection, reassortment, or error. It is usually reflective of how similar certain segments can be across different subtypes.

Influenza A viruses are classified into different subtypes based on the hemagglutinin (HA) and neuraminidase (NA) proteins, which are encoded by segments 4 and 6, respectively. Therefore, we recommend focusing on those segments to infer the subtype. If there is a sequence generated from segment 8 of an H3N2 genome but all the rest of the consensus sequences are generated from reference sequences from an H1N1 genome (indicating H1 and N1 subtypes), then the sample likely contains H1N1, not H3N2. One possible explanation is that segment 8 from H1N1 and segment 8 from H3N2 were both good matches for a particular contig but the one from H3N2 was a slightly better match and therefore chosen as final reference. Similarly, if there is a sequence generated from segment 4 of an H1N1 genome (indicating H1 subtype) and a sequence generated from segment 6 of an H5N1 genome (indicating N1 subtype), then the sample likely contains H1N1, not H5N1.

Q: Why does the "Detected Amplicons" column show 7 in the denominator for an Influenza genome when there should be 8 amplicons in total?

A: The denominator in the "Detected Amplicons" columns is based on the reference sequences selected based on de novo assembled contigs. Depending on the quality of the sample and/or reads, the assembler may not have enough data to generate a contig for some segments. Shorter segments are more likely to be missed. If only 7 segments are selected as final reference for short read alignment, then we expect 7 amplicons in total. If you believe that the sample should contain all 8 segments, you can download the contig FASTA file from our report page and submit it to NCBI BLAST to see if all 8 segments are present in the contig sequences.

One known issue is that chimeric reads can be generated during library preparation, which can lead to chimeric contigs, where the contig sequence contains sequences from more than one segment. This can result in missing an entire segment in the reference selection stage. A workaround may be to filter out chimeric reads from your FASTQ files before running the app.

Alternatively, you can force the app to use all 8 segments of a particular Influenza genome by providing a custom reference FASTA file with all 8 segment sequences and a custom reference BED file with the genomeName column to set to the same value (e.g. Influenza A). This way, the app will not perform assembly and use all 8 segments as the reference sequences for short read alignemnt.

Q: What is the difference between the "Detected Amplicons" and "% callable bases" columns?

A: The "Detected Amplicons" column shows the number of amplicons detected over the total number of amplicons expected for that genome. The percentage of amplicons detected is used to infer if the sample is of sufficient quality for variant calling. The "% callable bases" column shows the percentage of the selected reference genome whose bases are above the minimum read coverage depth for consensus sequence generation, which is computed independent of amplicon coordinates. Both metrics are useful to assess the quality of the sample, but the percentage of detected amplicons is used by the app after short read alignment to filter out low-titer samples and the percentage of callable bases is not.

Q: I don't see the virus I'm interested in listed in the "Genomes generated" column. Does that mean the virus is not present in my sample?

A: Not necessarily. Your virus of interest may be present in the sample, but the app may not have generated a consensus sequence for it for various reasons. One reason could be that there are too few reads coming from that virus. Tools like DRAGEN Metagenomics can be used to characterize what is in the sample more broadly. Another reason could be that the virus in your sample is too divergent from the reference sequences used in the app. In such cases, we recommend downloading the contig FASTA file from our report page and submitting it to NCBI BLAST. If you do see a sequence that matches your virus of interest, you can provide that sequence to the app as a custom reference genome.

Q: I am using the custom analysis workflow and my analysis aborted or shows an error, why?

A: While there may be quite a few causes for the analysis to fail, some of the most common cases are that the custom database was not formatted correctly. Below are requirements for the Custom Reference FASTA For Consensus Generation:

• Do not use Spaces in the file name, instead use an underscore "_"

• Do not exceed 25 characters in the file name

• File extension must be .fasta or .fa

• Do not exceed the file size limitation: 16GB for a single file or 25GB for multiple files

• Do not have duplicate entries

• If providing a Custom Reference BED and/or Custom PCR Primer Definitions in BED format, the names in the first column of the BED file (chrom) must match the names that appear in the FASTA (text after > and before the first whitespace character) Please see this link on general guidelines to upload data to BaseSpace for more details: https://help.basespace.illumina.com/manage-data/import-data If you continue having issues, reach out to techsupport@illumina.com

1. For version 1.1 and later, consensus FASTA files generated for each sample, virus, and reference sequence incorrectly contain soft-masked sequences instead of hard-masked sequences. To get hard-masked sequences, use {sample_name}.consensus_hard_masked_sequence.fa or convert lowercase nucleotides to "N".

Version information

At the top of the report is version information for the App and any third-party components.

FASTA downloads

Two buttons provide the ability to download relevant FASTA-formatted text files for this sample. The "Consensus" button initiates a download of a FASTA file containing all consensus sequences generated for this sample. The "Contig" button initiates a download of a FASTA file containing all assembled contigs for this sample.

Metrics by virus

The metrics by virus table contains information about each viral genome generated. Each row summarizes all sequences assigned to that virus. In the case of multi-segment viruses like Influenza, a row will summarize information across all segment sequences generated for a single viral genome. It contains buttons to download the contents of the table as a CSV, JSON or PDF file. The table itself contains rows for every virus with at least one generated genome in the sample. It contains the following columns:

1. Virus: The name of the virus. For custom references, this will be the part of the FASTA header before the first whitespace character for the corresponding reference sequence if no custom genome definition file is provided. If a custom genome definition file is provided, this will be the value of the genomeName column that corresponds to the selected reference (matched by the value in the chrom column of the genome definition file and the part of the FASTA header before the first whitespace character).

2. Detected Amplicons (only if 'Experiment Type' is set to 'Amplicon'): The number of amplicons detected over the total number of amplicons expected for that sequence. The percentage of amplicons detected is used to to determine if the sample is sufficient quality for variant calling. See Special considerations for amplicon sequencing with IMAP protocols for more details.

3. % callable bases: The percentage of the selected reference genome whose bases are considered "callable." Callable bases are those for which reliable variant calling can be performed and therefore for which the software can output a base call. Callable bases are defined as genomic positions with read coverage above the minimum read coverage depth for consensus sequence generation (10x by default). Note that genomic positions below the confidence threshold are hard-masked with "N" characters to avoid reference bias (inclusion of a reference base when the actual base cannot be accurately determined). Note that this percentage is calculated over the lengths of the reference genome(s), not the reported consensus sequence(s).

4. Status: The overall outcome of the analysis for this virus

   1. Full analysis (consensus, VC) means that the sample analysis completed normally, that a sufficient number of amplicons were detected to ensure reliable variant calling (amplicon experiments only), and that the percentage of callable bases was above the minimum percentage of consensus sequence generated to label as confident (5% by default)

   2. Low confidence means that there is at lease one callable base but the overall percentage of callable bases was below the minimum percentage of consensus sequence generated to label as confident (5% by default)

   3. No callable bases indicates that zero positions in the indicated reference genome were callable and no consensus sequence is therefore provided.

   4. Insufficient titer for VC will only be present for an amplicon experiment and indicates that the number of detected amplicons was below the minimum percentage (default 80%) required for reliable variant calling. See Special considerations for amplicon sequencing with IMAP protocols for more details.

5. Median coverage: The median coverage value (in number of reads overlapping each position) over the entire reference genome (not just the generated consensus sequence).

6. Consensus FASTA: A download link to a FASTA-formatted text file containing all the consensus sequences generated for this virus.

Metrics by sequence

This table summarizes the results for each sequence generated for the sample. For multi-segment viruses such as Influenza, there will may be multiple sequences detected for a given virus. For single-segment viruses there will typically be only one sequence per virus. It contains buttons to download the contents of the table as a CSV, JSON or PDF file. The table itself contains rows for every sequence. It contains the following columns:

1. Virus: The name of the virus. For custom references, this will be the part of the FASTA header before the first whitespace character for the corresponding reference sequence if no custom genome definition file is provided. If a custom genome definition file is provided, this will be the value of the genomeName column that corresponds to the selected reference (matched by the value in the accession column of the genome definition file and the part of the FASTA header before the first whitespace character).

2. Segment: The name of the genome segment to which the sequence belongs. For viruses with a single segment, the name of the segment will typically be "Full".

3. Accession: The accession number or other short unique identifier for the sequence. If using a custom genome definition BED, this value is taken from the first column (chrom) in the definition file. If using a custom reference without a genome definition file, the value is taken from the part of the FASTA header before the first whitespace character.

4. % callable bases: The percentage of the selected reference sequence whose bases are considered "callable." Callable bases are those for which reliable variant calling can be performed and therefore for which the software can output a base call. Callable bases are defined as genomic positions with read coverage above the minimum read coverage depth for consensus sequence generation (10x by default). Note that genomic positions below the confidence threshold are hard-masked with "N" characters to avoid reference bias (inclusion of a reference base when the actual base cannot be accurately determined). Note that this percentage is calculated over the lengths of the reference sequence, not the reported consensus sequence.

5. Median coverage: The median coverage value (in number of reads overlapping each position) over the entire reference sequence (not just the generated consensus sequence).

6. Consensus sequence length: The length of this consensus sequence. The reported length is the length of the hard-masked sequence after trimming any leading and trailing masked regions (if trimming is active).

7. # callable bases: The number of positions in the reference sequence above the minimum read coverage depth for consensus sequence generation (default 10x). In other words, the number of positions not masked. This may not be equal to the number of unmasked positions in the final consensus sequence since insertions and deletions are applied after masking.

8. Consensus FASTA: A download link to a FASTA-formatted text file containing this consensus sequence.

Pre-processing metrics

This stacked bar plot contains information about the outcome of the pre-processing steps (read QC, trimming, de-hosting) as well as the alignment step. It contains counts of reads that fall into the following categories:

• Removed in QC: Reads that failed to meet the minimum quality thresholds and were excluded from further processing.

• Removed in trimming: Reads that were removed in the initial sequence-based primer trimming step and were excluded from further processing.

• Removed in de-hosting: Reads that were removed in the de-hosting step and excluded from further processing. De-hosting is the process of removing reads that may originate from the host organism. Currently only human hosts are supported. De-hosting reads improves the quality of downstream analysis and helps ensure that human sequences are not included in the output BAM files.

• Unmapped: Reads that were not aligned to any reference genomes.

• Mapped. Reads that were mapped to at least one reference genome.

Alignment metrics

A column plot displaying the numbers and percentages of all reads that aligned to each reference sequence with at least one mapped read. The columns are labeled by both virus and segment name (if available) on the x-axis, and the y-axis is the read count for each sequence.

Coverage

Displays a trace of the read coverage over each reference sequence. The drop-down menu in the upper left allows the user to switch between viruses. If multiple segment sequences are generated for a single virus, their corresponding coverage plots will be displayed in a vertically stacked fashion. The black trace represents the read coverage, with the coverage depth in number of reads on the left y-axis and the position in the reference sequence on the x-axis.

The minimum read coverage depth for consensus sequence generation (default 10x) is plotted as a dashed orange line across the plot, to easily visualize locations where coverage drops below the threshold (which will be masked in the consensus sequence) and where the coverage is above the threshold (which will be reported in the consensus sequence).

The median coverage is plotted as a dashed teal line across the plot.

By default, sequence variants representing differences between the consensus sequence and the reference sequence are also plotted, with allele frequency on the right y-axis. The colors and symbols represent different sequence variant types. See the figure legend for details.

The "Show log-scale" toggle switch allows the user to switch between logarithmic and linear scales for the coverage (left) y-axis.

The "Show Median" toggle switch allows the user to turn the median coverage line on and off.

The "Show Sequence Variants" toggle switch allows the user to turn the plotting of sequence variants on and off.

Pangolin Report (optional)

This table contains the results of the Pangolin analysis performed on the generated consensus sequences. Pangolin is run if the "Enable Pangolin" box is checked on the input form and one of the following is true:

• 'Enrichment Panel' is set to a non-custom panel (e.g. VSP) and a consensus sequence was generated using SARS-CoV-2 as reference

• 'Amplicon Primer Set' is set to a non-custom set with SARS-CoV-2 as reference (e.g. SARS-CoV-2, ARTIC v5.3.2 primers) and a valid consensus sequence was generated

• Either 'Enrichment Panel' or 'Amplicon Primer Set' is set to 'Custom'. In this case, Pangolin is applied to every consensus sequence generated for the sample since the software assumes all of them to be potentially SARS-CoV-2 sequences.

The Pangolin report contains a "Download CSV" button which allows the user to download the contents of the report as a text CSV file.

The table in the Pangolin report is derived from the output of the Pangolin software. Please see the Pangolin documentation for more details: https://cov-lineages.org/resources/pangolin/output.html. Sequences with a bad Pangolin QC status are highlighted in yellow.

NextClade Report (optional)

This table contains the results of the NextClade analysis performed on the generated consensus sequences. NextClade is run if the "Enable NextClade" box is checked on the input form and one of the following is true:

• 'Enrichment Panel' is set to a non-custom panel (e.g. VSP) and a consensus sequence was generated using a reference with NextClade dataset available.

• 'Amplicon Primer Set' is set to a non-custom set with a reference with NextClade dataset available (e.g. SARS-CoV-2, ARTIC v5.3.2 primers) and a valid consensus sequence was generated.

• Either 'Enrichment Panel' or 'Amplicon Primer Set' is set to 'Custom' and one or more NextClade datasets are selected under 'Custom Reference'. In this case, each of the selected NextClade datasets is applied to each consensus sequence generated for the sample. This may result in multiple NextClade results for each consensus sequence, some of which may not be meaningful (e.g. "flu_h1n1pdm_ha" dataset applied to a NA segment of an Influenza genome).

The NextClade Report contains a button labeled "Group table by" with a drop-down menu allowing the user to group the results by various fields, including "None". The default is "Dataset" which means that all of the results for each NextClade dataset will be grouped together. For example, if a user is only interested in phylogenetic analysis performed on the HA segment of Influenza A H1N1, these results for each sample can be viewed together in the "flu_h1n1pdm_ha" collapsible group.

The NextClade report also contains a "Download CSV" button which allows the user to download the contents of the report as a text CSV file.

The table in the NextClade report is derived from the output of the NextClade software. Please see the NextClade documentation for more details: https://docs.nextstrain.org/projects/nextclade/en/stable/user/output-files/04-results-tsv.html. Sequences with a bad NextClade QC status are highlighted in yellow.

Flowchart

Pipeline Steps

Possible outcomes

The app produces a summary report as well as result reports for each of the samples analyzed. See the links below for a description of each.