3. Preparing Inputs

Overview

EPITOME has several built-in features that help you source and manage your input data. You can also supply data manually with or without these automated features. Keep on scrolling to learn more!

Data Sources & Formatting

Sourcing data from public repositories can be challenging and is often messy and unreliable. EPITOME attempts to automate this process 😅. You can also skip this all together and supply your data manually (can also be combined with the automated process!). In either case, all data is eventually combined per taxon and run through some basic quality control steps before being passed on for reference creation.

Automated Data Sourcing

EPITOME can automatically download complete sequences for a specified taxon from NCBI. This feature is controlled using the --ncbi parameter (default: --ncbi true). When enabled, EPITOME will pull all complete sequences for each taxon name in your samplesheet. This is accomplished using the NCBI datasets virus package.

But wait, there's more...

The sample data that comes from datasets download virus genome taxon is currently lacking. Specifically, we are often missing crucial information such as the segment or taxonomic details, like the species name or reported subtype (e.g., H5N1). This additional info is gathered using the taxonomy package from NCBI datasets, combined with an esearch of the NCBI nucleotide database using the following query: ${taxon}[Organism] AND "complete sequence"[Title]. These datastreams are then combined into a single table.

Note

Taxon names must match the taxId used by NCBI (learn more here).

Supplying Data Manually

Data can also be supplied manually for a taxon via the samplesheet. Sequence data is supplied as a multi-fasta file via the assembly column and sequence sample data is supplied as a CSV file via the metadata column. Below is an example samplesheet and metadata file:

samplesheet.csv:

taxon,assembly,metadata,segmented
Betacoronavirus,betacoronavirus.fa.gz,betacoronavirus.meta.csv,FALSE

betacoronavirus.meta.csv

"accession","species"
"JX993988.1","Severe acute respiratory syndrome-related coronavirus"

Note

The only information required in the sample data file is the accession column and the segment column, if the virus has a segmented genome. Otherwise, you are free to supply as much/little info as you like, using whatever column names you like (there are probably some limitations - let me know when you find them! 😄).

Input QC

EPITOME performs some basic quality control on your input sequences and sample data.

Dealing with Segmented Viruses

EPITOME has several features to help manage segmented viruses. Below is an outline of how this works:

1. You must specify if a taxon is segmented using the segmented column in the samplesheet (options: TRUE or FALSE)
2. You can supply synonyms for each segment using the segmentSynonyms column. Each segment is separated by a semicolon (;) and the segment synonyms are separated by a pipe (|). Segment names will be standardized to the first synonym listed for each segment (e.g., m|medium|middle would be standardized to m).
3. A separate row must be supplied for each segment of a taxon when manually supplying data. Each row should contain all segment synonyms (this is clunky, I know 😞. I will try to make it better in future versions).

samplesheet.csv

taxon,segment,segmentSynonyms,assembly,metadata
Alphainfluenzavirus,1,1;2;3;4;5;6;7;8,fluA-1.fa.gz,fluA-1.meta.csv
Alphainfluenzavirus,2,1;2;3;4;5;6;7;8,fluA-2.fa.gz,fluA-2.meta.csv
Alphainfluenzavirus,3,1;2;3;4;5;6;7;8,fluA-3.fa.gz,fluA-3.meta.csv
Alphainfluenzavirus,4,1;2;3;4;5;6;7;8,fluA-4.fa.gz,fluA-4.meta.csv
Alphainfluenzavirus,5,1;2;3;4;5;6;7;8,fluA-5.fa.gz,fluA-5.meta.csv
Alphainfluenzavirus,6,1;2;3;4;5;6;7;8,fluA-6.fa.gz,fluA-6.meta.csv
Alphainfluenzavirus,7,1;2;3;4;5;6;7;8,fluA-7.fa.gz,fluA-7.meta.csv
Alphainfluenzavirus,8,1;2;3;4;5;6;7;8,fluA-8.fa.gz,fluA-8.meta.csv
Hantavirus,,s|small;m|medium|middle;l|large,,

Important

Sequences with missing segment information or a segment name that is different than the values specified in the segmentSynonyms column will be automatically excluded when segmented is set to TRUE in the samplesheet.

Sequence QC

Below is a simplified overview of how sequence QC is performed:

1. Accessions listed in the CSV file specified in the exclusions column of the samplesheet are removed.
2. Identical sequences are collapsed, and unique sequences are assigned a number.
3. Unique sequences are filtered based on:
   • Presence of illegal bases (legal bases: -ATCGRYSWKMBDHVN)
   • Ambiguous base ratio: no. N characters / total sequence length (controlled using --amb_threshold)
   • Sequence length: length ± len_threshold * mean(length) (controlled using --len_threshold)

Sequences that pass these filters are passed onto to reference creation.

Note

EPITOME keeps track of these QC metrics for each input sequence and summarizes this information at the final steps of the pipeline.