Running the Pipeline¶

This page explains how to run the MAD4HATTER pipeline, including which parameters are required, what workflows are available, and how to customize your run.

Understanding Parameters¶

Parameters with two hyphens (--) are pipeline-specific parameters defined by MAD4HATTER. Parameters with one hyphen (-) are Nextflow-defined parameters. For example, --readDIR is a pipeline parameter (two hyphens) and -profile is a Nextflow parameter (one hyphen).

Available Workflows¶

The MAD4HATTER pipeline offers three different workflows. Most users will run only the complete (default) workflow, however, in some cases you may choose one of the other two workflows.

1. Complete Workflow (Default) :¶

The primary and most commonly used workflow

What it does: Runs the full end-to-end workflow, from raw FASTQs through microhaplotype calling and drug-resistance profiling.

When to use: This is the standard workflow for processing your sequencing data end-to-end.

2. QC Only Workflow¶

What it does: Only the steps required to generate basic QC metrics.

When to use: Use this if you want to quickly check your data quality and coverage before running the full pipeline.

3. Postprocessing Only Workflow¶

What it does: Re-runs post-processing (alignment, filtering, masking, allele calling) on previously denoised data.

When to use: Use this if you want to re-analyze your DADA2 output with different parameters (e.g., different masking settings or alignment thresholds).

¶

Required Parameters¶

The parameters you need depend on which workflow you're running. To control which workflow you are running use --workflow_name. By default this is set to complete, so is only necessary when running qc or postprocessing

For Complete and QC Workflows¶

These parameters are required:

For Postprocessing Workflow¶

These parameters are required:

Runtime Profile (Required for all workflows)¶

You must specify a runtime profile using -profile:

• docker - For local computers
• apptainer or conda - For HPC clusters
• See Quick Start for details on choosing a profile

Pre-Configured Pools¶

The pipeline includes several pre-configured pools that are ready to use. These pools can be used individually or combined depending on your data.

Using Pre-Configured Pools¶

To use one or more pre-configured pools, simply specify them in the --pools parameter:

# Use a single pool
--pools D1.1

# Combine multiple pools
--pools D1.1,R1.2,R2.1

# Use shorthand names
--pools D1,R1,R2

The pipeline will automatically locate the configuration files for these pools. No additional setup is required.

Optional Parameters¶

These parameters can be customized but have defaults:

Workflow Examples¶

Complete Workflow (Default)¶

This is the most common workflow - it processes your data from start to finish.

nextflow run main.nf \
  --readDIR /path/to/your/data \
  --outDIR /path/to/results \
  --pools D1,R1,R2 \
  -profile docker

What happens:

1. Reads are demultiplexed and adapters removed
2. Sequences are inferred using DADA2
3. Sequences are aligned, filtered, masked, and converted to allele tables including microhaplotypes and pseudo_cigars.
4. Quality control metrics are calculated
5. Resistance markers are extracted

Outputs: All pipeline outputs including allele_data.txt, coverage files, and quality reports. For more information, see Pipeline Outputs.

QC Only Workflow¶

Use this to quickly assess your data quality before running the full pipeline.

nextflow run main.nf \
  --readDIR /path/to/your/data \
  --outDIR /path/to/results \
  --pools D1,R1,R2 \
  --workflow_name qc \
  -profile docker

What happens:

1. Reads are demultiplexed and adapters removed
2. Quality control metrics are calculated

Outputs: - amplicon_coverage.txt - Coverage per amplicon - sample_coverage.txt - Coverage per sample

Postprocessing Only Workflow¶

Use this to re-analyze DADA2 output with different parameters.

nextflow run main.nf \
  --denoised_asvs /path/to/previous/run/dada2.clusters.txt \
  --outDIR /path/to/new/results \
  --pools D1,R1,R2 \
  --workflow_name postprocessing \
  -profile docker

What happens:

1. Takes DADA2 output from a previous run as input
2. Re-runs alignment, filtering, masking, and allele calling
3. Generates new allele tables

Outputs: - allele_data.txt - Final allele table with updated parameters

Parameter Reference Quick Guide¶

Minimum Command (Complete Workflow)¶

nextflow run main.nf \
  --readDIR /path/to/data \
  --pools D1,R1,R2 \
  -profile docker

With Custom Output Directory¶

nextflow run main.nf \
  --readDIR /path/to/data \
  --outDIR /custom/output/path \
  --pools D1,R1,R2 \
  -profile docker

With Custom Targeted Reference¶

nextflow run main.nf \
  --readDIR /path/to/data \
  --pools D1,R1,R2 \
  --refseq_fasta /path/to/reference.fasta \
  -profile docker

With Whole Genome Reference¶

nextflow run main.nf \
  --readDIR /path/to/data \
  --pools D1,R1,R2 \
  --genome /path/to/whole_genome_reference.fasta \
  -profile docker

Getting Help¶

To see all available parameters and their descriptions:

nextflow run main.nf --help

This displays the complete help message with all pipeline parameters.

Next Steps¶

• Review outputs: See Pipeline Outputs for details on what files are generated
• Customize parameters: See Advanced Pipeline Parameters for all parameter options
• Configure resources: See Pipeline Resources for computational resource settings
• Use custom pools: See Custom Pools for setting up bespoke amplicon panels
• Understand modules: See Core Pipeline Modules for details on each processing step