plastree 0.1.0__tar.gz

plastree-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BioSys_BUT
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

plastree-0.1.0/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: plastree
+Version: 0.1.0
+Summary: Build plasmid phylogenetic trees from dotplot, pangenome presence/absence, and k-mer methods, with cluster detection.
+Author: Helena Vitkova, Matej Bezdicek, Ema Holubova, Martina Lengerova
+Author-email: Marketa Jakubickova <jakubickova@vut.cz>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/BioSys-BUT/PlasTree
+Project-URL: Repository, https://github.com/BioSys-BUT/PlasTree
+Project-URL: Issues, https://github.com/BioSys-BUT/PlasTree/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: biopython==1.87
+Requires-Dist: numpy==2.4.6
+Requires-Dist: pandas==2.3.3
+Requires-Dist: scipy==1.17.1
+Requires-Dist: matplotlib==3.10.9
+Dynamic: license-file
+
+# 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.
+
+![PlasTree overview](plastree_overview.png "PlasTree pipeline and an example consensus tree with color-coded clusters")
+
+## 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](#key-features)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Parameters](#parameters)
+  - [Example](#example)
+  - [Output](#output)
+- [Generating pangenome input (Bakta + Roary/Panaroo)](#generating-pangenome-input-bakta--roarypanaroo)
+- [License](#license)
+- [Citation](#citation)
+- [Contact](#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**
+```bash
+python3 -m venv plastree
+source plastree/bin/activate
+pip install --upgrade pip
+```
+
+**Option B: conda / miniforge**
+```bash
+conda create -n plastree python=3.12
+conda activate plastree
+```
+
+With the environment active, install PlasTree directly from GitHub:
+```bash
+pip install git+https://github.com/BioSys-BUT/PlasTree.git
+```
+
+Or, if you want a local copy of the source:
+```bash
+git clone https://github.com/BioSys-BUT/PlasTree.git
+cd PlasTree
+pip install .
+```
+
+Verify the install:
+```bash
+plastree --help
+```
+
+## Usage
+
+```bash
+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
+
+```bash
+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/`](examples)):
+```bash
+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](https://github.com/oschwengers/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](https://sanger-pathogens.github.io/Roary/) and/or [Panaroo](https://github.com/gtonkinhill/panaroo) on the collected GFF3 files:
+```bash
+roary *.gff3 -f roary_out
+```
+```bash
+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](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:
+
+```bibtex
+@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 [jakubickova@vut.cz](mailto:jakubickova@vut.cz).

plastree-0.1.0/README.md

@@ -0,0 +1,172 @@
+# 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.
+
+![PlasTree overview](plastree_overview.png "PlasTree pipeline and an example consensus tree with color-coded clusters")
+
+## 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](#key-features)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Parameters](#parameters)
+  - [Example](#example)
+  - [Output](#output)
+- [Generating pangenome input (Bakta + Roary/Panaroo)](#generating-pangenome-input-bakta--roarypanaroo)
+- [License](#license)
+- [Citation](#citation)
+- [Contact](#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**
+```bash
+python3 -m venv plastree
+source plastree/bin/activate
+pip install --upgrade pip
+```
+
+**Option B: conda / miniforge**
+```bash
+conda create -n plastree python=3.12
+conda activate plastree
+```
+
+With the environment active, install PlasTree directly from GitHub:
+```bash
+pip install git+https://github.com/BioSys-BUT/PlasTree.git
+```
+
+Or, if you want a local copy of the source:
+```bash
+git clone https://github.com/BioSys-BUT/PlasTree.git
+cd PlasTree
+pip install .
+```
+
+Verify the install:
+```bash
+plastree --help
+```
+
+## Usage
+
+```bash
+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
+
+```bash
+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/`](examples)):
+```bash
+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](https://github.com/oschwengers/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](https://sanger-pathogens.github.io/Roary/) and/or [Panaroo](https://github.com/gtonkinhill/panaroo) on the collected GFF3 files:
+```bash
+roary *.gff3 -f roary_out
+```
+```bash
+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](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:
+
+```bibtex
+@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 [jakubickova@vut.cz](mailto:jakubickova@vut.cz).

plastree-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "plastree"
+version = "0.1.0"
+description = "Build plasmid phylogenetic trees from dotplot, pangenome presence/absence, and k-mer methods, with cluster detection."
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "Helena Vitkova" },
+    { name = "Marketa Jakubickova", email = "jakubickova@vut.cz" },
+    { name = "Matej Bezdicek" },
+    { name = "Ema Holubova" },
+    { name = "Martina Lengerova" },
+]
+requires-python = ">=3.10"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+]
+dependencies = [
+    "biopython==1.87",
+    "numpy==2.4.6",
+    "pandas==2.3.3",
+    "scipy==1.17.1",
+    "matplotlib==3.10.9",
+]
+
+[project.urls]
+Homepage = "https://github.com/BioSys-BUT/PlasTree"
+Repository = "https://github.com/BioSys-BUT/PlasTree"
+Issues = "https://github.com/BioSys-BUT/PlasTree/issues"
+
+[project.scripts]
+plastree = "plastree.plasmid_tree_tool:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]

plastree-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

plastree-0.1.0/src/plastree/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"