Raccoon Pipeline

Rigorous Alignment Curation: Cleanup Of Outliers and Noise

FASTA file(s)
Metadata file(s)
FASTA file(s)

One or more sequence files in FASTA format

FASTA format consists of a header line starting with ">" followed by the sequence data.

A file can contain multiple sequences, each with its own header.

Metadata file(s)

CSV or TSV files with sequence metadata (optional).

Each file should contain a header row with column names and subsequent rows with metadata for each sequence.

Metadata files should have a column that can be used to match the provided sequence IDs (default: "sample").

Ideally, the metadata file(s) should also contain location and date information for each sequence.

raccoon seq-qc
Sequence QC
combined.fasta
seq-qc_report.html
Issues files
combined.fasta

Combined sequence file with N content and length filter, with harmonized headers populated from metadata.

By default raccoon will attempt to match sequence IDs with metadata and produce headers in the format ">sample|location|YYYY-MM-DD".

seq-qc_report.html

Interactive report with filtering summary

Contains a summary of input files, sequence length distribution, metadata description, filtered sequences, final IDs, and report metadata.

Issues files

metadata_issues.csv: Missing metadata CSV flagging sequences with missing location or date metadata

filter_failures.csv: CSV file of sequences that did not pass filters, and so are not included in the combined FASTA

MAFFT
Multiple Sequence Alignment
alignment.fasta
alignment.fasta

Multiple sequence alignment in FASTA format

or
Reference Mapping
Alignment vs Reference
alignment.fasta
alignment.fasta

Multiple sequence alignment against reference in FASTA format

raccoon aln-qc
Alignment QC
mask_sites.csv
aln-qc_report.html
alignment_flags.tsv
mask_sites.csv

Flagged sites (clustered SNPs, N-adjacent, gap-adjacent, frame breaks)

aln-qc_report.html

Interactive alignment quality report with visualizations

alignment_flags.tsv

Detailed per-sequence flag information

raccoon mask (optional)
Apply Mask
alignment.masked.fasta
alignment.masked.fasta

Alignment with flagged sites masked

Optional Inputs
Outgroup IDs
Outgroup IDs

Comma-separated sequence IDs to use as outgroup for rooting

IQ-TREE
Maximum Likelihood Tree Estimation
output.treefile
output.state
output.treefile

Phylogenetic tree in Newick format

output.state

Ancestral state reconstruction (optional)

raccoon tree-qc
Phylogenetic QC
tree_qc_report.html
flagged_sequences.txt
Additional reports
tree_qc_report.html

Interactive tree visualization with QC findings

flagged_sequences.txt

Sequences flagged for removal with details

Additional reports

Convergent mutations, APOBEC/ADAR signals, root-to-tip regression

Legend

Sequence Data
Metadata/Reports
Phylogenetic Tree
Optional Step

raccoon seq-qc

Purpose

Combine and harmonize sequence headers across one or more input files. Creates structured, consistent sequence headers using metadata, and filters sequences by length and N-content.

Basic Usage

raccoon seq-qc -f file1.fasta file2.fasta -o combined.fasta

With Metadata

raccoon seq-qc -f *.fasta -m metadata.csv \
--metadata-id-field sample_id \
--header-fields "{sample}|{admin1}|{admin2}|{date}" \
-o combined.fasta

Key Options

  • -f, --fasta: Input FASTA file(s) (required)
  • -m, --metadata: Metadata CSV/TSV files (optional)
  • --header-fields: Sequence header template
    (default: {sample}|{location}|{date})
  • --min-length: Minimum sequence length filter
  • --max-n-content: Maximum N-content proportion (0-1)
  • --require-date: Require a valid date in the metadata or sequence header
  • -o, --outfile: Name of combined output FASTA file
    (default: `combined.fasta`)

Customisation

  • --metadata-id-field: Field in metadata to use as unique identifier
    (default: `sample`)
  • --metadata-location-field: Field in metadata to use for location information
    (default: `location`)
  • --metadata-date-field: Field in metadata to use for date information
    (default: `date`)
  • --seq-id-field-index: Which field in the FASTA header to match against metadata
    (default: whole header)
  • --seq-id-delimiter: Delimiter used to split FASTA header fields
    (default: `|`)
  • --require-date: Require a valid date in the metadata or sequence header

Outputs

  • Combined FASTA file with harmonized headers
  • HTML report with seq-qc summary
  • Missing metadata CSV flagging sequences with missing location or date metadata
  • CSV file of sequences that did not pass filters, and so are not included in the combined FASTA
→ View full documentation

raccoon aln-qc

Purpose

Assess alignment quality and flag problematic sites. Detects clustered SNPs, SNPs adjacent to gaps or Ns, and frame-breaking indels. Generates a mask file for downstream masking.

Basic Usage

raccoon aln-qc alignment.fasta -d outdir

With GenBank Reference

raccoon aln-qc alignment.fasta -d outdir \
--genbank reference.gb \
--reference-id ref_seq_id

Key Options

  • alignment: Input alignment FASTA (positional, required)
  • -t, --sequence-type: nt or aa (default: nt)
  • --cluster-window: Window size for clustered SNP detection (bp)
  • --cluster-count: Min SNPs in window to flag as clustered
  • --max-n-content: N-content threshold for flagging
  • --no-flag-*: Skip specific flag types (clustered, n-adjacent, gap-adjacent, frame-break)

Outputs

  • mask_sites.csv - Flagged sites with flag types
  • aln-qc_report.html - Interactive alignment report
  • alignment_flags.tsv - Per-sequence flag details
  • alignment_summary.txt - Summary statistics
→ View full documentation

raccoon mask

Purpose

Apply an alignment QC mask file to exclude flagged sites from downstream phylogenetic inference. Replaces flagged sites with a mask character (default: ?).

Usage

raccoon mask alignment.fasta \
--mask-file mask_sites.csv \
-d outdir \
-o alignment.masked.fasta

Key Options

  • alignment: Input alignment (positional, required)
  • --mask-file: Mask CSV from aln-qc (required)
  • --mask-character: Character for masking (default: ?)
  • -t, --sequence-type: nt or aa (default: nt)

Note

This step is optional. You can proceed directly to tree building if you prefer to retain all sites.

→ View full documentation

raccoon tree-qc

Purpose

Assess phylogenetic tree quality and identify problematic sequences. Detects long branches, convergent mutations, APOBEC3-mediated and ADAR-induced mutations, and evaluates temporal signal.

Basic Usage

raccoon tree-qc --tree alignment.treefile -d outdir

With ASR and Bias Detection

raccoon tree-qc --tree alignment.treefile \
--alignment alignment.fasta \
--asr-state alignment.state \
-d outdir \
--run-adar --run-apobec

Key Options

  • -t, --tree: Tree file (required)
  • --outgroup-ids: Comma-separated outgroup sequence IDs (optional)
  • --alignment: Alignment FASTA (needed for some analyses)
  • --asr-state: ASR file from IQ-TREE
  • --long-branch-sd: SD threshold for long-branch flagging (default: 3.0)
  • --run-adar: Run ADAR mutation detection
  • --adar-window: Window size for ADAR clustering (default: 300 bp)
  • --run-apobec: Run APOBEC3 mutation detection
  • --midpoint-root: Midpoint-root tree for visualization

Outputs

  • tree_qc_report.html - Interactive tree visualization
  • flagged_sequences.txt - Outlier sequences for removal
  • convergent_mutations.csv - Detected convergent mutations
  • tree_summary.txt - Summary statistics
→ View full documentation

MAFFT - Multiple Sequence Alignment

Purpose

MAFFT is an external multiple sequence alignment software. It aligns the combined sequences into a format suitable for phylogenetic inference.

Installation

conda install -c bioconda mafft

Basic Usage

mafft --auto input.fasta > alignment.fasta

Common Options

  • --auto: Automatic method selection based on input size
  • --thread: Number of threads for parallelization
  • --maxiterate: Number of refinement iterations

Note

External tool: Not part of raccoon, but essential for the pipeline. Install separately using Conda or your package manager.

Citation

Katoh K, Standley DM. MAFFT multiple sequence alignment software version 7: improvements in performance and usability. Mol Biol Evol. 2013 Apr;30(4):772-80. doi: 10.1093/molbev/mst010. Epub 2013 Jan 16. PMID: 23329690; PMCID: PMC3603318.

→ MAFFT Documentation

Reference Mapping - Alignment vs Reference

Purpose

Alternative to multiple sequence alignment. Maps all sequences against a reference genome using minimap2 and converts the SAM alignment to FASTA format using gofasta. This approach is a useful speed-up for large datasets or for analyses where you want to maintain consistent coordinates with a known reference.

Installation

conda install -c bioconda minimap2 gofasta

Workflow

Step 1 - Sequence Mapping with minimap2:

minimap2 -a -x asm20 -rmq=no --junc-bonus=0 --for-only --sam-hit-only --secondary=no --score-N=0 -t {threads} {reference} - -o {output.sam}

Step 2 - Convert to Multiple Alignment with gofasta:

gofasta sam toMultiAlign \
-s {input.sam} \
-t {threads} \
--reference {reference} \
--trimstart {trim_start} \
--trimend {trim_end} \
--trim \
--pad -o {output.fasta}

Key Parameters

  • -x asm20: Preset for mapping asm5/asm10/asm20 genomes to themselves
  • -rmq=no: Don't use the minigraph chaining algorithm
  • --for-only: Only consider forward strand
  • --sam-hit-only: Output queries with hits only
  • --secondary=no: Do not output secondary alignments
  • --score-N=0: Score a mismatch involving ambiguous bases as 0
  • -t: Number of threads
  • --trimstart/--trimend: Positions to trim reference at start/end
  • --trim: Soft mask bases outside trim boundaries
  • --pad: Pad with end of alignment with Ns if query doesn't cover reference region

When to Use

  • For a huge speed up on large datasets with high similarity to the reference (e.g. heavily sampled outbreak)
  • To maintain consistent coordinate systems across analyses

Note

External tools: Not part of raccoon. Install minimap2 and gofasta separately using Conda or your package manager.

→ minimap2 Documentation

IQ-TREE - Phylogenetic Inference

Purpose

IQ-TREE is an external software for maximum likelihood phylogenetic tree estimation. It can also generate ancestral state reconstructions for use with tree-qc.

Installation

conda install -c bioconda iqtree

Basic Usage

iqtree -s alignment.fasta -m GTR+G -bb 1000

Common Options

  • -s: Input alignment file
  • -m: Evolution model (e.g., GTR+G, HKY+F)
  • -bb: Number of bootstrap replicates
  • -asr: Compute ancestral state reconstruction
  • -T: Number of threads

Citation

Minh, B.Q., Schmidt, H.A., et al. IQ-TREE 2: New Models and Efficient Methods for Phylogenetic Inference in the Genomic Era. Molecular Biology and Evolution, Volume 37, Issue 5, May 2020, Pages 1530–1534, https://doi.org/10.1093/molbev/msaa015

For Raccoon Integration

To generate ASR files for tree-qc analysis, use flag -asr in IQ-TREE. This will create a .state file needed for advanced tree-qc analyses.

→ IQ-TREE Documentation