Panaroo Documentation

Panaroo offers different cleaning modes via the --clean-mode flag to balance sensitivity and specificity:

• strict: The default and most conservative mode. It removes potential sources of contamination and error while retaining most genes of interest.
• sensitive: Use this mode if you need to retain rare plasmids, acknowledging that it may increase the risk of including contamination.

panaroo -i *.gff -o results --clean-mode sensitive

When running panaroo-filter-pa, the program generates new versions of the following files in the specified output directory:

• gene_presence_absence.csv
• gene_presence_absence.Rtab

These new files will include an additional suffix to indicate which specific filtering types (e.g., pseudo, length, or frag) were applied.

The --clean-mode parameter is the primary way to adjust Panaroo's stringency. It changes default behaviors for filtering contaminants and handling refound genes.

• strict: Requires strong evidence (present in $\ge 5%$ of genomes) to keep likely contaminant genes. Removes genes that are refound more often than originally called.
• moderate: Requires moderate evidence (present in $\ge 1%$ of genomes) to keep likely contaminant genes. Keeps genes that are refound more often than originally called.
• sensitive: Does not delete any genes; only performs merge and refinding operations. Useful for studying rare plasmids, but will likely include more spurious annotations.

panaroo -i *.gff -o ./results/ --clean-mode strict

Panaroo offers different cleaning modes via the --clean-mode flag to balance between contamination removal and sensitivity:

• strict: The default and most conservative mode. It is recommended for most use cases as it removes potential sources of contamination and error while retaining most genes of interest.
• sensitive: Use this mode if you need to retain rare plasmids. Note that this mode may increase the risk of including contamination.

# Run in sensitive mode to retain rare plasmids
panaroo -i *.gff -o results --clean-mode sensitive

The panaroo-qc tool generates several types of plots to help identify sample issues:

• Contamination: Uses the Mash algorithm to produce plots indicating possible sources of contamination.
• Multi-Dimensional Scaling (MDS): Generates an MDS plot based on a pairwise distance matrix created by Mash. Samples appearing as outliers in this plot should be investigated for contamination, poor assembly, or other technical issues.
• Outliers (Gene/Contig counts): Produces plots (such as boxplots) highlighting samples with an unusual number of contigs or genes, which may indicate sample-specific problems.

Before running Panaroo, you can perform rudimentary quality checks on your input data using the panaroo-qc script. This requires a mash database.

Example usage:

panaroo-qc -t 3 --graph_type all -i *.gff --ref_db refseq.genomes.k21s1000.msh -o results

To focus on specific subsets of the pangenome (e.g., genes present in only 1-3 genomes), use the selection and filtering tools in Cytoscape.

Selection Methods:

1. Manual: Select nodes directly using the mouse.
2. Rule-based: Use the 'select' tab to define rules (e.g., selecting nodes where a specific attribute falls within a range).

Post-Selection Actions: Once nodes are selected, you can use the filtering buttons to:

• Create a subgraph: Convert the selection into a new, separate graph for isolated analysis.
• Filter out: Remove the selected nodes from the current main graph view.

Panaroo provides consolidated FASTA files containing both annotated and refound sequences:

• combined_DNA_CDS.fasta: Nucleotide sequences.
• combined_protein_CDS.fasta: Protein sequences.

Note on Gene Names: These files use Panaroo's internal gene names. To map these internal names back to your original gene names/annotations, use the gene_data.csv file.

Panaroo generates two types of alignments for core genes (genes present in at least the fraction of genomes specified by --core_threshold, default=0.95):

1. core_gene_alignment.aln: The standard alignment. If a gene is fragmented, only the longer fragment is included.
2. core_gene_alignment_filtered.aln: Recommended for phylogeny building. This is a filtered version where genes exceeding the Block Mapping and Gathering with Entropy (BMGE) filter are removed.

Configuration: The filtering is controlled by the --core_entropy_filter parameter. By default, it uses Tukey's outlier test to automatically identify and remove outlying genes.

After running Panaroo, you can generate simplified GFF files for each isolate. These files remove filtered annotations and include refound gene annotations generated by Panaroo. Note that only CDS sequences considered by Panaroo are included in these simplified files.

To generate these files, use the panaroo-generate-gffs command. You must provide the input GFF files used during the original Panaroo run and specify the Panaroo output directory as the output directory.

panaroo-generate-gffs -i *.gff -o panaroo_out

Panaroo includes a refinding step to identify genes missed by annotation software by searching the sequence surrounding a neighbor gene.

• --search_radius SEARCH_RADIUS: The distance in nucleotides surrounding the neighbor of an accessory gene in which to search (default is 5000).
• --refind_prop_match REFIND_PROP_MATCH: The proportion of an accessory gene that must be found to consider it a match.
• --refind-mode {default,strict,off}:
  • default: Allows for premature stop codons and incorrect lengths to account for misassemblies.
  • strict: Prevents fragmented, misassembled, or potential pseudogene sequences from being re-found.
  • off: Turns off all re-finding steps.

panaroo -i *.gff -o ./results/ --clean-mode strict --refind_prop_match 0.5 --search_radius 1000