/roary-pangenome

name: "roary-pangenome"
description: "Compute the bacterial pan-genome from Prokka/Bakta GFF3 annotations with Roary's CD-HIT + BLAST + MCL clustering pipeline. Builds gene presence/absence matrices, core/soft-core/shell/cloud partitions, multi-FASTA core gene alignments (with `-e`), and a pan-genome reference. Use Panaroo for higher-accuracy pan-genomes from highly fragmented assemblies, PIRATE for paralog-aware clustering, or PPanGGOLiN for graph-based partitioning."
license: "GPL-3.0"

Roary Pan-Genome Pipeline

Overview

Roary is a high-throughput pan-genome pipeline for prokaryotes that takes per-sample GFF3 annotations (typically from Prokka or Bakta) and produces a clustered gene presence/absence matrix across the entire input set. It first reduces redundancy with CD-HIT iterative clustering, then performs an all-vs-all BLASTP within each pre-cluster, and finally applies MCL graph clustering to define orthologous gene families. The output partitions the gene space into core (≥ 99 %), soft-core (95–99 %), shell (15–95 %), and cloud (< 15 %) genes and optionally builds a concatenated core-gene alignment suitable for phylogenetic inference.

When to Use

• Computing a pan-genome from a set of bacterial isolate annotations (10–10,000 genomes)
• Producing a `gene_presence_absence.csv` matrix for downstream GWAS, accessory-gene mining, or core-gene phylogenetics
• Building a concatenated core-gene multi-FASTA alignment for ML/Bayesian phylogenetic trees
• Generating a pan-genome reference FASTA to use as a non-redundant gene catalog
• Comparative genomics across closely related strains where >95 % nucleotide identity is expected
• Use **Panaroo** instead when assemblies are highly fragmented or annotations are noisy (Panaroo aggressively cleans annotation errors)
• Use **PIRATE** instead when paralog-aware clustering with multiple identity thresholds is needed
• Use **PPanGGOLiN** instead when graph-based, statistically grounded gene-family partitioning is preferred over fixed-frequency cutoffs

Prerequisites

• **Software**: Roary ≥ 3.13, Perl 5, BLAST+, CD-HIT, MCL, BEDTools, PRANK or MAFFT (for `-e` core alignment), FastTree (optional)
• **Python packages** (for output parsing): `pandas`, `matplotlib`, `seaborn`, `biopython`, `dendropy`
• **Input**: per-sample GFF3 files with embedded FASTA at the end (Prokka/Bakta default output)
• **Hardware**: ≥ 8 GB RAM for ~50 genomes; 32 GB+ recommended for ~500 genomes
• **Naming**: each GFF3 filename becomes the sample column header in the output matrix; use `sample_id.gff` style

> **Check before installing**: The tool may already be available in the current environment (e.g., inside a `pixi` / `conda` env). Run `command -v roary` first and skip the install commands below if it returns a path. When running inside a pixi project, invoke the tool via `pixi run roary` rather than bare `roary`.

# Install Roary via conda/mamba (recommended)
mamba install -c conda-forge -c bioconda roary

# Verify installation
roary --version
# 3.13.0

# Verify dependent tools
which cd-hit blastp mcl bedtools mafft
# /opt/conda/bin/cd-hit
# /opt/conda/bin/blastp
# /opt/conda/bin/mcl
# /opt/conda/bin/bedtools
# /opt/conda/bin/mafft

# Install Python parsing dependencies
pip install pandas matplotlib seaborn biopython dendropy

Pre-flight Interview

Settle these with the user before writing any analysis code.

decisions:
  - id: D1
    param: inputAnnotations
    kind: derived
    source: upstream
    ask: "Which GFF3 files, and were they all produced by the same annotation tool and version?"
    default: "the annotation stage output"

  - id: D2
    param: identityThreshold
    kind: required
    source: user
    ask: "How similar must two proteins be to count as the same gene? Lower values merge diverged orthologs; higher values split them."
    default: "95%"

  - id: D3
    param: coreDefinition
    kind: required
    source: user
    ask: "In what fraction of isolates must a gene appear before it counts as core?"
    default: "99%"

  - id: D4
    param: paralogSplitting
    kind: required
    source: user
    ask: "Should duplicated genes within a genome be split into separate families, or kept together?"
    default: "split"

  - id: D5
    param: coreAlignment
    kind: required
    source: upstream
    ask: "Is a concatenated core-gene alignment needed for a downstream phylogeny?"
    default: "not produced - it is the slowest stage by a wide margin"

  - id: D6
    param: alignmentSpeed
    kind: optional
    source: user
    depends_on: [D5]
    ask: "Align every gene accurately, or use the fast route sufficient for tree building?"
    default: "fast alignment"
    skip_if: "no core alignment requested"

  - id: D7
    param: clusterInflation
    kind: optional
    source: user
    ask: "How tightly should the clustering step group families?"
    default: 1.5

  - id: D8
    param: maxClusters
    kind: optional_conditional
    source: data
    ask: "Is the expected number of gene families above the default cap?"
    default: 50000

  - id: D9
    param: processes
    kind: never_ask
    source: data
    reason: "Affects runtime only, not the gene families"
    default: "min(8, available_cores)"

D1 is derived and carries a consistency requirement rather than a choice: Roary compares annotations, so GFF3 files from different annotation tools or database versions produce apparent presence/absence differences that are annotation artefacts, not biology. D2 and D3 together decide the size of the core genome, which is usually the headline number of the analysis.

Quick Start

# Run Roary on all GFF3 files in current directory; emit core gene alignment
roary -e --mafft -p 8 -o pangenome -f roary_out/ *.gff

# Inspect summary statistics
cat roary_out/summary_statistics.txt
# Core genes        (99% <= strains <= 100%) 2823
# Soft core genes   (95% <= strains <  99%)   78
# Shell genes       (15% <= strains