| Name | plasmidhub JSON |
| Version |
1.0.0
JSON |
| download |
| home_page | https://github.com/YOUR_USERNAME/Plasmidhub |
| Summary | A command-line tool for plasmid clustering, analysis, and visualization. |
| upload_time | 2025-07-24 14:51:19 |
| maintainer | None |
| docs_url | None |
| author | Dr. Balint Timmer |
| requires_python | >=3.8 |
| license | MIT License
Copyright (c) 2025 Dr. Balint Timmer
Institute of Metagenomics, University of Debrecen, Debrecen, Hungary
Institute of Medical Microbiology, Faculty of Medicine, University of Pecs, Pecs, Hungary
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 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. |
| keywords |
plasmid
bioinformatics
network
clustering
amr
virulence
plasmid network
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<img src="https://img.shields.io/github/license/BALINTESBL/plasmidhub" alt="License"> <img src="https://img.shields.io/pypi/v/plasmidhub" alt="PyPI"> 
# Plasmidhub
Plasmidhub is a free and open-source command-line tool for comprehensive plasmid network analysis based on nucleotide sequence similarity. It enables researchers to cluster plasmids and identify genetically related groups using a dynamic, database-independent approach. Plasmidhub's approach:
* Is applicable to any plasmid
* Provides an unambiguous classification
* Considers the whole sequence of the plasmids
Network visualizations, stats and data are provided for further analysis.
## Download and Installation
PlasmidHub can be installed easily via PyPI, Bioconda, or directly from GitHub.
### Pip
```
pip install plasmidhub
```
**Note:** It's highly recommended to use a virtual environment or conda environment.
Recommended environment setup:
```
conda create -n plasmidhub python=3.8
conda activate plasmidhub
```
### Bioconda
If you use Conda for environment management:
```
conda install -c bioconda plasmidhub
```
Make sure you have the bioconda channel configured. If not, configure them with:
```
conda config --add channels defaults
conda config --add channels bioconda
conda config --add channels conda-forge
```
### GitHub
To get the latest version:
```
git clone https://github.com/BALINTESBL/plasmidhub.git
cd plasmidhub
pip install .
```
### Dependencies
This tool requires the following external software to be installed:
- [FastANI](https://github.com/ParBLiSS/FastANI)
- [ABRicate](https://github.com/tseemann/abricate)
## Inputs
Plasmidhub requires plasmid FASTA files (.fna or .fa or .fasta). Your FASTA files need to be placed in one directory. Ideally, there are no other files in the directory.
## Usage
Perform plasmid network analysis with default settings by defining only the directory path of your plasmid FASTA files! Or, you can also adjust parameters.
Example usage:
```
% plasmidhub path/to/my/plasmid/FASTA/files --fragLen 1000 --kmer 14 --coverage_threshold 0.5 --ani_threshold 95 --min_cluster_size 4 --plot_k 2.0 3.0 -t 32
```
This command will:
* Compute pairwise ANI using FastANI
* Build a plasmid similarity network
* Save network metrics and statistics (results/statistics)
* Cluster plasmids
* Annotate resistance and virulence genes with ABRicate (results/abricate_results)
* Generate network visualizations (results/plots)
### Key Options
| Category | Flag | Description | Default |
| -------------- | ---------------------- | --------------------------------------- | ------------------------- |
| **Input** | ` | Path to folder with plasmid FASTA files | – |
| **FastANI** | `--fragLen` | Fragment length | `1000` |
| | `--kmer` | K-mer size | `14` |
| | `--coverage_threshold` | Minimum proportion of the plasmid lenghts| `0.5` |
| | | covered by the matching fragments | |
| | `--ani_threshold` | Minimum ANI score (after applying | `95.0` |
| | | coverage threshold) | |
| **Clustering** | `--cluster_off` | Disable clustering | – |
| | `--min_cluster_size` | Minimum cluster size (plasmids) | `3` |
| **ABRicate** | `--skip_abricate` | Skip annotation step | – |
| | `--abricate_dbs` | Databases to use e.g.: | `plasmidfinder card vfdb` |
| | | --abricate_dbs ncbi ecoli_vf | |
| **Plotting** | `--plot_k` | Range of k values |`3` `3` |
| | `--plot_skip` | Skips plotting | |
| **Threads** | `-t` or `--threads` | Number of threads | `4` |
### Plot-only mode
In plot-only mode, network visualizations can be generated from existing networks directly, by using --plot_only flag and defining the directory path. In this mode, several parameters can be adjusted.
Example usage:
```
% plasmidhub --plot_only path/to/my/results --plot_k 3 5 --plot_node_color blue --plot_node_size 500 --plot_node_shape s --plot_figsize 20 20 -t 32
```
| **Plotting** | Flag | Description | Default |
| -------------- | ---------------------- | --------------------------------------- | ------------------------- |
| | `--plot_node_size` | Size of nodes | `900` |
| | `--plot_node_shape` | Shape of nodes (`o`, `s`, `^`, etc.) | `o` (circle) |
| | `--plot_edge_width` | Min/max edge width | `0.2 2.0` |
| | `--plot_figsize` | Figure size in inches | `25 25` |
| | `--plot_iterations` | Spring layout iterations | `100` |
Node shapes:
| Marker | Description |
| ------ | -------------------------- |
| `'o'` | Circle |
| `'s'` | Square |
| `'^'` | Upward-pointing triangle |
| `'v'` | Downward-pointing triangle |
| `'>'` | Right-pointing triangle |
| `'<'` | Left-pointing triangle |
| `'D'` | Diamond |
| `'d'` | Thin diamond |
| `'p'` | Pentagon |
| `'h'` | Hexagon 1 |
| `'H'` | Hexagon 2 |
| `'*'` | Star |
| `'+'` | Plus |
| `'x'` | Cross |
| `'X'` | Filled X |
Plots generated with Plasmidhub:
<img width="1668" height="1668" alt="image" src="https://github.com/user-attachments/assets/afed18b8-6dbe-44b8-b539-23aa47b4bfb0" />
## Overview
Plasmidhub performs an all-vs-all comparison of input plasmid sequences using FastANI. FastANI results ("raw results") are filtered by the coverage (what proportion of the full plasmid sequences are covered by the matching fragments). The remaining pairs are filtered by the minimum ANI score. ANI scores are further weighted by the proportion of matching fragments, and data are sorted into a similarity matrix. The network is build from the similarity matrix, where:
- **Nodes** represent plasmids
- **Edges** represent genetic relatedness (weighted ANI)
Within the network, communities are detected via Louvain method (subclusters). Plasmid clusters are complete subgraphs (cliques) detected within the whole network. Clusters comprising highly similar or identical plasmids. If relevant and scientifically appropriate, plasmids of the same cluster may be considered as equivalent. This approach is alignment-free, reference-free, database-independent, and uses relative similarity-based system to overcome the limitations of database dependency (untypeable plasmids, multireplicon/multi-MOB plasmids, mosaic, hybrid plasmids ect.)
Network and node statistics are saved to a distinct directory for downstream analyses (connectance, modularity, nestedness, community partition, degree centrality, node degrees, betweenness, closeness ect.)
Resistance and virulence genes can be annotated via [ABRicate](https://github.com/tseemann/abricate). The abricate files are saved to a distinct subdirectory. By default, plasmidfinder, vfdb and card databases are used, but optionally other databases can be specified from the databases available with ABRicate.
To generate custom visualizations, feel free to use and modify the *plot.py*.
## Troubleshooting
Users are welcome to report any issue or feedback related to Plasmidhub by posting a [Github issue](https://github.com/BALINTESBL/plasmidhub/issues).
---
Developed by **Dr. Bálint Timmer**
*Institute of Metagenomics, University of Debrecen, Debrecen, Hungary*
*Department of Medical Microbiology, University of Pécs Medical School, Pécs, Hungary*
<img width="33" height="33" alt="image" src="https://github.com/user-attachments/assets/bd9f17e9-e9ce-4edb-8319-ef0091c45f00" /> <img width="99" height="32.054" alt="image" src="https://github.com/user-attachments/assets/5f3d5b6b-cef6-478a-af66-614b2e2860b2" />
Contact: [timmer.balint@med.unideb.hu](mailto:timmer.balint@med.unideb.hu) , [timmer.balint@pte.hu](mailto:timmer.balint@pte.hu)
Raw data
{
"_id": null,
"home_page": "https://github.com/YOUR_USERNAME/Plasmidhub",
"name": "plasmidhub",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "plasmid, bioinformatics, network, clustering, AMR, virulence, plasmid network",
"author": "Dr. Balint Timmer",
"author_email": "\"Dr. Balint Timmer\" <timmer.balint@med.unideb.hu>",
"download_url": "https://files.pythonhosted.org/packages/3b/58/758f7e220ffa3d2fc8690b194534768fb950497218e57a71d12ddd49b312/plasmidhub-1.0.0.tar.gz",
"platform": null,
"description": " <img src=\"https://img.shields.io/github/license/BALINTESBL/plasmidhub\" alt=\"License\"> <img src=\"https://img.shields.io/pypi/v/plasmidhub\" alt=\"PyPI\"> \n \n# Plasmidhub\nPlasmidhub is a free and open-source command-line tool for comprehensive plasmid network analysis based on nucleotide sequence similarity. It enables researchers to cluster plasmids and identify genetically related groups using a dynamic, database-independent approach. Plasmidhub's approach: \n* Is applicable to any plasmid\n* Provides an unambiguous classification\n* Considers the whole sequence of the plasmids\n\nNetwork visualizations, stats and data are provided for further analysis.\n\n## Download and Installation\nPlasmidHub can be installed easily via PyPI, Bioconda, or directly from GitHub.\n\n### Pip\n```\npip install plasmidhub\n```\n**Note:** It's highly recommended to use a virtual environment or conda environment.\nRecommended environment setup:\n```\nconda create -n plasmidhub python=3.8\nconda activate plasmidhub\n```\n### Bioconda\n\nIf you use Conda for environment management:\n```\nconda install -c bioconda plasmidhub\n```\nMake sure you have the bioconda channel configured. If not, configure them with:\n```\nconda config --add channels defaults\nconda config --add channels bioconda\nconda config --add channels conda-forge\n```\n### GitHub\nTo get the latest version:\n```\ngit clone https://github.com/BALINTESBL/plasmidhub.git\ncd plasmidhub\npip install .\n```\n### Dependencies\nThis tool requires the following external software to be installed:\n- [FastANI](https://github.com/ParBLiSS/FastANI)\n- [ABRicate](https://github.com/tseemann/abricate)\n\n## Inputs\nPlasmidhub requires plasmid FASTA files (.fna or .fa or .fasta). Your FASTA files need to be placed in one directory. Ideally, there are no other files in the directory.\n\n## Usage\nPerform plasmid network analysis with default settings by defining only the directory path of your plasmid FASTA files! Or, you can also adjust parameters.\nExample usage:\n```\n% plasmidhub path/to/my/plasmid/FASTA/files --fragLen 1000 --kmer 14 --coverage_threshold 0.5 --ani_threshold 95 --min_cluster_size 4 --plot_k 2.0 3.0 -t 32\n\n```\nThis command will:\n* Compute pairwise ANI using FastANI\n* Build a plasmid similarity network\n* Save network metrics and statistics (results/statistics)\n* Cluster plasmids\n* Annotate resistance and virulence genes with ABRicate (results/abricate_results)\n* Generate network visualizations (results/plots)\n### Key Options\n\n| Category | Flag | Description | Default |\n| -------------- | ---------------------- | --------------------------------------- | ------------------------- |\n| **Input** | ` | Path to folder with plasmid FASTA files | \u2013 |\n| **FastANI** | `--fragLen` | Fragment length | `1000` |\n| | `--kmer` | K-mer size | `14` |\n| | `--coverage_threshold` | Minimum proportion of the plasmid lenghts| `0.5` |\n| | | covered by the matching fragments | |\n| | `--ani_threshold` | Minimum ANI score (after applying | `95.0` |\n| | | coverage threshold) | | \n| **Clustering** | `--cluster_off` | Disable clustering | \u2013 |\n| | `--min_cluster_size` | Minimum cluster size (plasmids) | `3` |\n| **ABRicate** | `--skip_abricate` | Skip annotation step | \u2013 |\n| | `--abricate_dbs` | Databases to use e.g.: | `plasmidfinder card vfdb` |\n| | | --abricate_dbs ncbi ecoli_vf | |\n| **Plotting** | `--plot_k` | Range of k values |`3` `3` |\n| | `--plot_skip` | Skips plotting | |\n| **Threads** | `-t` or `--threads` | Number of threads | `4` |\n### Plot-only mode \nIn plot-only mode, network visualizations can be generated from existing networks directly, by using --plot_only flag and defining the directory path. In this mode, several parameters can be adjusted.\nExample usage:\n```\n% plasmidhub --plot_only path/to/my/results --plot_k 3 5 --plot_node_color blue --plot_node_size 500 --plot_node_shape s --plot_figsize 20 20 -t 32\n\n```\n| **Plotting** | Flag | Description | Default |\n| -------------- | ---------------------- | --------------------------------------- | ------------------------- | \n| | `--plot_node_size` | Size of nodes | `900` |\n| | `--plot_node_shape` | Shape of nodes (`o`, `s`, `^`, etc.) | `o` (circle) |\n| | `--plot_edge_width` | Min/max edge width | `0.2 2.0` |\n| | `--plot_figsize` | Figure size in inches | `25 25` |\n| | `--plot_iterations` | Spring layout iterations | `100` |\n\nNode shapes: \n| Marker | Description |\n| ------ | -------------------------- |\n| `'o'` | Circle |\n| `'s'` | Square |\n| `'^'` | Upward-pointing triangle | \n| `'v'` | Downward-pointing triangle | \n| `'>'` | Right-pointing triangle | \n| `'<'` | Left-pointing triangle | \n| `'D'` | Diamond | \n| `'d'` | Thin diamond | \n| `'p'` | Pentagon | \n| `'h'` | Hexagon 1 | \n| `'H'` | Hexagon 2 |\n| `'*'` | Star |\n| `'+'` | Plus |\n| `'x'` | Cross |\n| `'X'` | Filled X |\n\nPlots generated with Plasmidhub:\n<img width=\"1668\" height=\"1668\" alt=\"image\" src=\"https://github.com/user-attachments/assets/afed18b8-6dbe-44b8-b539-23aa47b4bfb0\" />\n\n## Overview\n\nPlasmidhub performs an all-vs-all comparison of input plasmid sequences using FastANI. FastANI results (\"raw results\") are filtered by the coverage (what proportion of the full plasmid sequences are covered by the matching fragments). The remaining pairs are filtered by the minimum ANI score. ANI scores are further weighted by the proportion of matching fragments, and data are sorted into a similarity matrix. The network is build from the similarity matrix, where:\n- **Nodes** represent plasmids\n- **Edges** represent genetic relatedness (weighted ANI)\n\nWithin the network, communities are detected via Louvain method (subclusters). Plasmid clusters are complete subgraphs (cliques) detected within the whole network. Clusters comprising highly similar or identical plasmids. If relevant and scientifically appropriate, plasmids of the same cluster may be considered as equivalent. This approach is alignment-free, reference-free, database-independent, and uses relative similarity-based system to overcome the limitations of database dependency (untypeable plasmids, multireplicon/multi-MOB plasmids, mosaic, hybrid plasmids ect.)\nNetwork and node statistics are saved to a distinct directory for downstream analyses (connectance, modularity, nestedness, community partition, degree centrality, node degrees, betweenness, closeness ect.)\n\nResistance and virulence genes can be annotated via [ABRicate](https://github.com/tseemann/abricate). The abricate files are saved to a distinct subdirectory. By default, plasmidfinder, vfdb and card databases are used, but optionally other databases can be specified from the databases available with ABRicate. \n\nTo generate custom visualizations, feel free to use and modify the *plot.py*.\n\n## Troubleshooting\nUsers are welcome to report any issue or feedback related to Plasmidhub by posting a [Github issue](https://github.com/BALINTESBL/plasmidhub/issues).\n\n---\n\nDeveloped by **Dr. B\u00e1lint Timmer** \n*Institute of Metagenomics, University of Debrecen, Debrecen, Hungary* \n*Department of Medical Microbiology, University of P\u00e9cs Medical School, P\u00e9cs, Hungary* \n\n <img width=\"33\" height=\"33\" alt=\"image\" src=\"https://github.com/user-attachments/assets/bd9f17e9-e9ce-4edb-8319-ef0091c45f00\" /> <img width=\"99\" height=\"32.054\" alt=\"image\" src=\"https://github.com/user-attachments/assets/5f3d5b6b-cef6-478a-af66-614b2e2860b2\" />\n \nContact: [timmer.balint@med.unideb.hu](mailto:timmer.balint@med.unideb.hu) , [timmer.balint@pte.hu](mailto:timmer.balint@pte.hu)\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2025 Dr. Balint Timmer\n \n Institute of Metagenomics, University of Debrecen, Debrecen, Hungary\n Institute of Medical Microbiology, Faculty of Medicine, University of Pecs, Pecs, Hungary\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense,\n and to permit persons to whom the Software is \n furnished to do so, subject to the following conditions: \n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software. \n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR \n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, \n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE \n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER \n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, \n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE \n SOFTWARE.",
"summary": "A command-line tool for plasmid clustering, analysis, and visualization.",
"version": "1.0.0",
"project_urls": {
"Homepage": "https://github.com/YOUR_USERNAME/Plasmidhub"
},
"split_keywords": [
"plasmid",
" bioinformatics",
" network",
" clustering",
" amr",
" virulence",
" plasmid network"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "b807dde6baa7abeeb563c1f1cabf467c13696a48fdcfaf4c1ace134846b79995",
"md5": "ef28e9b081974bb0b68a6a146e299580",
"sha256": "23fe5badc4f48b5311252c311474e4443b33987833358997a9abcc58d3ded9ec"
},
"downloads": -1,
"filename": "plasmidhub-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ef28e9b081974bb0b68a6a146e299580",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 24187,
"upload_time": "2025-07-24T14:51:17",
"upload_time_iso_8601": "2025-07-24T14:51:17.972592Z",
"url": "https://files.pythonhosted.org/packages/b8/07/dde6baa7abeeb563c1f1cabf467c13696a48fdcfaf4c1ace134846b79995/plasmidhub-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "3b58758f7e220ffa3d2fc8690b194534768fb950497218e57a71d12ddd49b312",
"md5": "894df2b048cfca62a59cef08327da9b1",
"sha256": "21653bdf811bcf09d5cfd7382720d09cfeee16dda0db18a04895a712dd44df49"
},
"downloads": -1,
"filename": "plasmidhub-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "894df2b048cfca62a59cef08327da9b1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 23172,
"upload_time": "2025-07-24T14:51:19",
"upload_time_iso_8601": "2025-07-24T14:51:19.227159Z",
"url": "https://files.pythonhosted.org/packages/3b/58/758f7e220ffa3d2fc8690b194534768fb950497218e57a71d12ddd49b312/plasmidhub-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-24 14:51:19",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "YOUR_USERNAME",
"github_project": "Plasmidhub",
"github_not_found": true,
"lcname": "plasmidhub"
}
