nf-core/ampliseq

Use this to specify the location of your input paired-end FastQ files.

For example:

--input 'path/to/data'  

Example for input data organization from one sequencing run with two samples:

data  
  |-sample1_1_L001_R1_001.fastq.gz  
  |-sample1_1_L001_R2_001.fastq.gz  
  |-sample2_1_L001_R1_001.fastq.gz  
  |-sample2_1_L001_R2_001.fastq.gz  

Please note the following requirements:

1. The path must be enclosed in quotes
2. The folder must contain gzip compressed paired-end demultiplexed fastq files. If the file names do not follow the default ("/*_R{1,2}_001.fastq.gz"), please check --extension.
3. If your data is scattered, a directory with symlinks to your actual data might be a solution.
4. All sequencing data should originate from one sequencing run, because processing relies on run-specific error models that are unreliable when data from several sequencing runs are mixed. Sequencing data originating from multiple sequencing runs requires additionally the parameter --multipleSequencingRuns and a specific folder structure.

In amplicon sequencing methods, PCR with specific primers produces the amplicon of interest. These primer sequences need to be trimmed from the reads before further processing and are also required for producing an appropriate classifier.

For example:

--FW_primer GTGYCAGCMGCCGCGGTAA --RV_primer GGACTACNVGGGTWTCTAAT  

In amplicon sequencing methods, PCR with specific primers produces the amplicon of interest. These primer sequences need to be trimmed from the reads before further processing and are also required for producing an appropriate classifier.

For example:

--FW_primer GTGYCAGCMGCCGCGGTAA --RV_primer GGACTACNVGGGTWTCTAAT  

This is optional, but for performing downstream analysis such as barplots, diversity indices or differential abundance testing, a metadata file is essential.

For example:

--metadata "path/to/metadata.tsv"  

Please note the following requirements:

1. The path must be enclosed in quotes
2. The metadata file has to follow the QIIME2 specifications (https://docs.qiime2.org/2019.10/tutorials/metadata/)
3. In case of multiple sequencing runs, specific naming of samples are required, see --multipleSequencingRuns

The first column in the metadata file is the identifier (ID) column and defines the sample or feature IDs associated with your study. Metadata files are not required to have additional metadata columns, so a file containing only an ID column is a valid QIIME 2 metadata file. Additional columns defining metadata associated with each sample or feature ID are optional.
NB: without additional columns there might be no groupings for the downstream analyses.

Identifiers should be 36 characters long or less, and also contain only ASCII alphanumeric characters (i.e. in the range of [a-z], [A-Z], or [0-9]), the period (.) character, or the dash (-) character. By default all numeric columns, blanks or NA are removed, and only columns with multiple different values but not all unique are selected.

The columns which are to be assessed can be specified by --metadata_category. If --metadata_category isn't specified than all columns that fit the specification are automatically chosen.

Expects one subfolder per sequencing run in the folder specified by --input containing sequencing data of the specific run.

To prevent overlapping sample names from multiple sequencing runs, sample names obtained from the sequencing files will be renamed automatically by adding the folder name as prefix separated by a string specified by --split. Accordingly, the sample name column in the metadata file --metadata require values following subfolder-samplename.

Example for input data organization:

data  
  |-run1  
  |  |-sample1_1_L001_R{1,2}_001.fastq.gz  
  |  |-sample2_1_L001_R{1,2}_001.fastq.gz  
  |  
  |-run2  
     |-sample3_1_L001_R{1,2}_001.fastq.gz  
     |-sample4_1_L001_R{1,2}_001.fastq.gz  

In this example the first column in the metadata file requires the values run1-sample1 ... run2-sample4 (instead of sample1, ..., sample4).

Example command to analyze this data in one pipeline run:

nextflow run nf-core/ampliseq \  
    -profile singularity \  
    --input "data" \  
    --FW_primer GTGYCAGCMGCCGCGGTAA \  
    --RV_primer GGACTACNVGGGTWTCTAAT \  
    --metadata "data/Metadata.tsv" \  
    --multipleSequencingRuns  

Visually choosing sequencing read truncation cutoffs

While --untilQ2import with --multipleSequencingRuns is currently supported, --Q2imported is not. The pipeline can be first run with --untilQ2import, than --trunclenf and --trunclenr are visually chosen, and then the pipeline can be continued without --untilQ2import but with --trunlenf, --trunlenr, and -resume.

For example:

(1) To produce quality plots and choose truncation values:

nextflow run nf-core/ampliseq \  
    -profile singularity \  
    --input "data" \  
    --FW_primer GTGYCAGCMGCCGCGGTAA \  
    --RV_primer GGACTACNVGGGTWTCTAAT \  
    --metadata "data/Metadata.tsv" \  
    --multipleSequencingRuns \  
    --untilQ2import  

(2) To finish analysis:

nextflow run nf-core/ampliseq \  
    -profile singularity \  
    --input "data" \  
    --FW_primer GTGYCAGCMGCCGCGGTAA \  
    --RV_primer GGACTACNVGGGTWTCTAAT \  
    --metadata "data/Metadata.tsv" \  
    --multipleSequencingRuns \  
    --trunclenf 200 \  
    --trunclenr 180 \  
    -resume  

You can submit a manifest file as an alternative way to provide input reads. No submission of read files with --input is required this way.

A manifest must be a tab-separated file that must have the following labels in this exact order: sampleID, forwardReads, reverseReads. In case of single-end reads, such as PacBio data, the labels should be: sampleID, Reads. The sample identifiers must be listed under sampleID. Paths to forward and reverse reads must be reported under forwardReads and reverseReads, respectively. Path to single-end must be reported under Reads.

Multiple sequencing runs not supported by --manifest at this stage.

After truncation, reads with higher than ‘maxEE’ "expected errors" will be discarded. In case of very long reads, you might want to increase this value. We recommend (to start with) a value corresponding to approximately 1 expected error per 100-200 bp (default: 2)

Remove reads with length greater than maxLen after trimming and truncation.

Remove reads with length less than minLen after trimming and truncation.

When read sequences are trimmed, untrimmed read pairs are discarded routinely. Use this option to retain untrimmed read pairs. This is usually not recommended and is only of advantage for specific protocols that prevent sequencing PCR primers.

For example:

--retain_untrimmed  

Cutdapt will be run twice, first to remove reads without primers (default), then a second time to remove reads that erroneously contain a second set of primers, not to be used with --retain_untrimmed

Read denoising by DADA2 creates an error profile specific to a sequencing run and uses this to correct sequencing errors. This method requires all reads to have the same length and as high quality as possible while maintaining at least 20 bp overlap for merging. One cutoff for the forward read --trunclenf and one for the reverse read --trunclenr truncate all longer reads at that position and drop all shorter reads.
These cutoffs are usually chosen visually using --untilQ2import, inspecting the quality plots in "results/demux", and resuming analysis with --Q2imported. If not set, these cutoffs will be determined automatically for the position before the mean quality score drops below --trunc_qmin.

For example:

--trunclenf 180 --trunclenr 120  

Please note:

1. Overly aggressive truncation might lead to insufficient overlap for read merging
2. Too little truncation might reduce denoised reads
3. The code choosing these values automatically cannot take the points above into account, therefore setting --trunclenf and --trunclenr is recommended

Read denoising by DADA2 creates an error profile specific to a sequencing run and uses this to correct sequencing errors. This method requires all reads to have the same length and as high quality as possible while maintaining at least 20 bp overlap for merging. One cutoff for the forward read --trunclenf and one for the reverse read --trunclenr truncate all longer reads at that position and drop all shorter reads.
These cutoffs are usually chosen visually using --untilQ2import, inspecting the quality plots in "results/demux", and resuming analysis with --Q2imported. If not set, these cutoffs will be determined automatically for the position before the mean quality score drops below --trunc_qmin.

For example:

--trunclenf 180 --trunclenr 120  

Please note:

1. Overly aggressive truncation might lead to insufficient overlap for read merging
2. Too little truncation might reduce denoised reads
3. The code choosing these values automatically cannot take the points above into account, therefore setting --trunclenf and --trunclenr is recommended

Automatically determine --trunclenf and --trunclenr before the median quality score drops below --trunc_qmin (default: 25). The fraction of reads retained is defined by --trunc_rmin, which might override the quality cutoff.

For example:

--trunc_qmin 35  

Please note:

1. The code choosing --trunclenf and --trunclenr using --trunc_qmin automatically cannot take amplicon length or overlap requirements for merging into account, therefore use with caution.
2. The default value of 25 is recommended. However, high quality data with a large paired sequence overlap might justify a higher value (e.g. 35). Also, very low quality data might require a lower value.
3. If the quality cutoff is too low to include a certain fraction of reads that is specified by --trunc_rmin (default: 0.75, meaning at least 75% percent of reads are retained), a lower cutoff according to --trunc_rmin superseeds the quality cutoff.

Value can range from 0 to 1. 0 means no reads need to be retained and 1 means all reads need to be retained. The minimum lengths of --trunc_qmin and --trunc_rmin are chosen as DADA2 cutoffs.

By default, the workflow downloads SILVA (https://www.arb-silva.de/) v132 (https://www.arb-silva.de/documentation/release-132/) and extracts reference sequences and taxonomy clustered at 99% similarity and trains a Naive Bayes classifier to assign taxonomy to features.

By default, uses SILVA for taxonomic assignment, but can also use UNITE. If so, specify the UNITE fasta file with --reference_database.

If you have trained a compatible classifier before, from sources such as SILVA (https://www.arb-silva.de/), Greengenes (http://greengenes.secondgenome.com/downloads) or RDP (https://rdp.cme.msu.edu/).

For example:

--classifier "FW_primer-RV_primer-classifier.qza"  

Please note the following requirements:

1. The path must be enclosed in quotes
2. The classifier is a Naive Bayes classifier produced by "qiime feature-classifier fit-classifier-naive-bayes" (e.g. by this pipeline or from (https://docs.qiime2.org/2019.10/data-resources/))
3. The primer pair for the amplicon PCR and the computing of the classifier are exactly the same (or fulllength, potentially lower performance)
4. The classifier has to be trained by the same version of scikit-learn as this version of the pipeline uses (0.21.2)

Depending on the primers used, PCR might amplify unwanted or off-target DNA. By default sequences originating from mitochondria or chloroplasts are removed. The taxa specified are excluded from further analysis.
For example to exclude any taxa that contain mitochondria, chloroplast, or archaea:

--exclude_taxa "mitochondria,chloroplast,archaea"  

If you prefer not filtering the data, specify:

--exclude_taxa "none"  

Please note the following requirements:

1. Comma separated list enclosed in quotes
2. May not contain whitespace characters
3. Features that contain one or several of these terms in their taxonomical classification are excluded from further analysis
4. The taxonomy level is not taken into consideration

Remove entries from the feature table below an absolute abundance threshold (default: 1, meaning filter is disabled). Singletons are often regarded as artifacts, choosing a value of 2 removes sequences with less than 2 total counts from the feature table.

For example to remove singletons choose:

--min_frequency 2  

Filtering low prevalent features from the feature table, e.g. keeping only features that are present in at least two samples can be achived by choosing a value of 2 (default: 1, meaning filter is disabled). Typically only used when having replicates for all samples.

For example to retain features that are present in at least two sample:

--min_samples 2  

Please note this is independent of abundance.

Here columns in the metadata sheet can be chosen with groupings that are used for diversity indices and differential abundance analysis. By default, all suitable columns in the metadata sheet will be used if this option is not specified. Suitable are columns which are categorical (not numerical) and have multiple different values which are not all unique. For example:

--metadata_category "treatment1,treatment2"  

Please note the following requirements:

1. Comma separated list enclosed in quotes
2. May not contain whitespace characters
3. Each comma separated term has to match exactly one column name in the metadata sheet

A string that will be used between the prepended run/folder name and the sample name. Only used with --multipleSequencingRuns (default: "-").

For example using the string link:

--split "link"  

Please note:

1. Run/folder names may not contain the string specified by --split
2. No underscore(s) allowed
3. Must be enclosed in quotes
4. The metadata sheet has to be adjusted, instead of using run-sample in the first column, in this example runlinksample is required

Indicates the naming of sequencing files (default: "/*_R{1,2}_001.fastq.gz").

Please note:

1. The prepended slash (/) is required
2. The star (*) is the required wildcard for sample names
3. The curly brackets ({}) enclose the orientation for paired end reads, seperated by a comma (,).
4. The pattern must be enclosed in quotes

For example for one sample (name: 1) with forward (file: 1_a.fastq.gz) and reverse (file: 1_b.fastq.gz) reads in folder data:

--input "data" --extension "/*_{a,b}.fastq.gz"  

Set this parameter to your e-mail address to get a summary e-mail with details of the run sent to you when the workflow exits. If set in your user config file (~/.nextflow/config) then you don't need to specify this on the command line for every run.

If a timezone error occurs, this parameter needs to be specified (default: 'Europe/Berlin'). Find your appropriate timezone with e.g. tzselect.
Note, this affects the timezone of the entire software environment.

Analysis starting with a QIIME2 artefact with trimmed reads, typically produced before with --untilQ2import. This is only supported for data from a single sequencing run.

For data from multiple sequencing runs with --multipleSequencingRuns the pipeline can be first run with --untilQ2import and next run without --untilQ2import but with -resume.