plastree 0.1.0

Build plasmid phylogenetic trees from dotplot, pangenome presence/absence, and k-mer methods, with cluster detection.

PlasTree

A tree-based pipeline for clustering complete bacterial plasmids from long-read assemblies, combining structural, k-mer, and gene-content similarity into a single weighted consensus tree.

Overview

PlasTree integrates three complementary similarity methods, DotPloTree (pairwise dotplot-based structural similarity), KmerTree (ranked k-mer frequency similarity), and PanGTree (pangenome presence/absence similarity), and combines them into a single weighted consensus tree. Plasmids are then automatically grouped into clusters based on branch length and cluster size thresholds. PlasTree is intended for complete plasmid assemblies from long-read sequencing (e.g. Oxford Nanopore Technologies), where rearrangements, recombination, and accessory gene turnover can obscure relationships found by a single similarity measure.

Content

• Key Features
• Requirements
• Installation
• Usage
  • Parameters
  • Example
  • Output
• Generating pangenome input (Bakta + Roary/Panaroo)
• License
• Citation
• Contact

Key Features

• Three independent tree-building methods: DotPloTree (structural), KmerTree (nucleotide composition), and PanGTree (gene content, Roary or Panaroo format)
• Weighted consensus tree (3:2:1 DotPloTree:PanGTree:KmerTree) when two or more methods are combined
• Automatic clustering of plasmids by branch length, with support for multiple thresholds computed in a single run
• Installable as a standard Python package, exposing a single plastree command
• Optional PNG rendering of pairwise dotplots and the final cluster-colored consensus tree

Requirements

• Python 3.10+
• All other dependencies (Biopython, NumPy, Pandas, SciPy, Matplotlib) are installed automatically with the package.

Installation

First create an isolated environment named plastree (pick one option below), then install PlasTree into it.

Option A: venv

python3 -m venv plastree
source plastree/bin/activate
pip install --upgrade pip

Option B: conda / miniforge

conda create -n plastree python=3.12
conda activate plastree

With the environment active, install PlasTree directly from GitHub:

pip install git+https://github.com/BioSys-BUT/PlasTree.git

Or, if you want a local copy of the source:

git clone https://github.com/BioSys-BUT/PlasTree.git
cd PlasTree
pip install .

Verify the install:

plastree --help

Usage

plastree --fasta <fasta_path> [--pang_format {roary,panaroo}] [--pang_csv <csv_path>] [--methods dotplot kmer pang] [--outdir <out_dir>] [--max_cluster_size <int>] [--max_branch_length <float> [<float> ...]] [--dotplot_window {19,22}] [--dotplot_threads <int>] [--dotplot_png] [--result_tree_png]

Parameters

• --fasta: Path to a single FASTA file containing all plasmid sequences (one record per plasmid). Required.
• --pang_format {roary,panaroo}: Format of the pangenome CSV. Required when using --methods pang.
• --pang_csv: Path to the pangenome presence/absence CSV file. Required when using --methods pang.
• --methods [dotplot pang kmer ...]: Tree construction methods to apply. Default: dotplot only.
• --outdir: Directory to store output files. Default: output.
• --max_cluster_size: Maximum OTUs (plasmids) per cluster. Default: half the number of input sequences.
• --max_branch_length: Maximum allowed branch length within a cluster (0-1). Accepts one or more values (e.g. 0.1 0.2 0.05); one cluster-assignment table is produced per value. Default: 0.2.
• --dotplot_window {19,22}: Sliding window size for dotplot comparison. Default: 22.
• --dotplot_threads: Number of parallel worker processes for dotplot pairwise distance computation. Default: 1.
• --dotplot_png: Save pairwise dotplots as PNGs. Only for <=20 sequences. Default: off.
• --result_tree_png: Save the consensus tree as a PNG with node support and cluster coloring. Default: off.

Example

plastree \
  --fasta sequences.fasta \
  --methods dotplot kmer pang \
  --pang_format panaroo \
  --pang_csv gene_presence_absence.csv \
  --dotplot_window 22 \
  --dotplot_threads 8 \
  --max_cluster_size 30 \
  --max_branch_length 0.05 0.1 0.2 0.4 \
  --result_tree_png \
  --outdir output

with example data (8 small real plasmids from Enterococcus faecium, included in examples/):

plastree \
  --fasta examples/plasmids.fasta \
  --methods dotplot kmer pang \
  --pang_format panaroo \
  --pang_csv examples/gene_presence_absence.csv \
  --result_tree_png \
  --outdir examples/output

Output

All output files are written to --outdir.

File	Description
dotplot_tree.newick	DotPloTree structural similarity tree (--methods dotplot)
dotplot_distmat.tsv	DotPloTree distance matrix
kmer_tree.newick	KmerTree nucleotide composition tree (--methods kmer)
kmer_distmat.tsv	KmerTree distance matrix
pang_tree.newick	PanGTree gene content tree (--methods pang)
pang_distmat.tsv	PanGTree distance matrix
consensus_tree.newick	weighted consensus tree (only when 2+ methods are used)
plasmid_clusters.tsv	cluster assignment per plasmid (cluster 0 = outlier)
cluster_tree.png	consensus tree rendered with clusters color-coded (only with --result_tree_png)

If multiple --max_branch_length values are given, plasmid_clusters.tsv and cluster_tree.png are produced once per threshold, suffixed with the value (dots replaced by underscores), e.g. plasmid_clusters_bl0_2.tsv and cluster_tree_0_2.png for threshold 0.2.

Generating pangenome input (Bakta + Roary/Panaroo)

The --pang_csv file used by --methods pang is not produced by PlasTree itself. It comes from annotating the same plasmid FASTA files and clustering the predicted genes into orthologous groups, using external tools:

1. Annotate each plasmid with Bakta (or another tool that outputs GFF3 annotations), producing one GFF3 file per plasmid.
2. Collect all resulting GFF3 files into one directory.
3. Run Roary and/or Panaroo on the collected GFF3 files:

roary *.gff3 -f roary_out

panaroo -i *.gff3 -o panaroo_out

Both produce a gene_presence_absence.csv. Pass this file as --pang_csv, together with the matching --pang_format roary or --pang_format panaroo. See each tool's own documentation for annotation database setup, threading, and other options. Bakta, Roary, and Panaroo have their own, sometimes conflicting, dependencies, so it is common to install them into separate environments (e.g. separate conda environments).

License

See LICENSE for details (MIT).

Citation

The manuscript describing PlasTree is currently in submission. Until it is published, if you use PlasTree in your research, please cite this repository:

@software{plastree2026,
  title={PlasTree},
  author={Vitkova, Helena and Jakubickova, Marketa and Bezdicek, Matej and Holubova, Ema and Lengerova, Martina},
  year={2026},
  url={https://github.com/BioSys-BUT/PlasTree}
}

Contact

For questions and feedback, please open an issue on GitHub or contact us via email at [e-mail].