- 🎯 Overview
- ✨ Key Features
- ⚡ Quick Start
- 🔧 Installation
- 🐳 Docker & Singularity (HPC Ready)
- 🚀 Usage Guide
- 📁 Output Structure
- 🔍 Core Analytical Modules
- 📈 Ultimate Reporter & Visualisation
- 🖥️ Sample Report
- ⚙️ Mandatory First‑Run Steps
- ❓ Not Happy? Try These Alternatives
- 🌐 Part of the ESKAPE Web Tools Suite
- 🔮 Future Development
- 🙏 Acknowledgements
- 💰 Sponsor This Project
- 📚 Citation
- 👥 Authors & Contact
- 📄 License
PseudoScope is an automated, locally‑executable computational pipeline designed specifically for comprehensive Pseudomonas aeruginosa genomic surveillance. It integrates seven essential analysis modules into a single, cohesive workflow:
- FASTA QC – Assembly quality metrics (N50, GC%, contig stats)
- MLST (Oxford scheme) – Multi‑locus sequence typing via 7 housekeeping genes
- PAST serotyping – O‑antigen typing (pasty / camlhmp‑blast‑regions)
- AMRfinderPlus – Comprehensive antimicrobial resistance gene detection
- ABRicate – Multi‑database screening (resistance, virulence, plasmids, biocides)
- Ultimate Reporter – Gene‑centric integration with interactive HTML
- Visualisation Dashboard – Publication‑ready interactive plots (PCA, networks, boxplots)
PseudoScope runs entirely locally (or on HPC clusters), protects your data privacy, and produces beautiful interactive reports in minutes.
- Automated critical gene flagging – Carbapenemases (KPC, NDM, VIM, IMP, OXA), colistin (mcr‑1 to mcr‑10), ESBLs (PER, VEB, BEL), 16S rRNA methyltransferases (armA, rmt)
- MLST (Oxford scheme) – Uses
acsA, aroE, guaA, mutL, nuoD, ppsA, trpE - PAST serotyping – Up‑to‑date O‑antigen reference database (Robert Petit / camlhmp)
- Cross‑genome pattern discovery – ST‑O combination table, gene co‑occurrence, PCA
- Gene‑centric views – Each gene table shows all genomes that carry it (no truncation)
- Sample‑centric interactive report – Each isolate is presented in its own box with typing badges (ST, O‑type) and detailed, horizontally scrollable tables for AMR, virulence, plasmids, Bacmet, and mutations. This shift enables rapid individual isolate assessment for clinical outbreaks.
- Dynamic grouping by typing – Group genomes by MLST, O‑serotype, or ST‑O combinations directly within AMR, Virulence, Plasmid, Bacmet, and Mutation tables. Instantly see which clones carry specific resistance/virulence genes – transforming gene lists into epidemiological intelligence.
- Mutation tracking – Point mutations in gyrA, parC, rpoB, 23S rRNA, mprF are displayed both per‑isolate and gene‑centrically, capturing resistance mechanisms not detectable by gene databases.
- Signal handlers & automatic clean‑up – Gracefully handles
SIGINTandSIGTERM, removing temporary directories on interruptions, making the pipeline HPC‑friendly. - Structured data ingestion – Leverages structured TSV summaries for faster processing while preserving compatibility with HTML outputs; all reports remain self‑contained and shareable.
- Refined citations – Correctly credits PAST, pasty, and camlhmp tools; citations updated to current literature.
- Complete analysis in 10‑15 minutes for 5 genomes (16 cores)
- Linear scaling – 100 genomes in ~2 hours
- Low memory footprint – Runs on 4GB RAM, scales to HPC
- Parallel execution – QC, MLST, and PAST run concurrently; ABRicate and AMR sequentially
See complete interactive reports generated by PseudoScope:
Each isolate as an interactive box with full gene profile |
Each gene with all genomes that carry it – groupable by typing |
Interactive plots, networks & PCA |
Note: Reports may take a few seconds to load. For the best experience, download the HTML files and open them locally.
| Feature | Sample‑Centric | Gene‑Centric | Visual Dashboard |
|---|---|---|---|
| MLST (Sequence Typing) | ✅ Per‑isolate | ✅ Groupable | ✅ Distribution plots |
| O Serotyping | ✅ Per‑isolate | ✅ Groupable | ✅ Distribution plots |
| AMR Genes | ✅ Per‑isolate table | ✅ Gene‑centric table | ✅ Top genes + Stacked bars |
| Virulence Genes | ✅ Per‑isolate table | ✅ Gene‑centric table | ✅ Top genes + Stacked bars |
| Biocides & Heavy Metals | ✅ Per‑isolate table | ✅ Gene‑centric table | ❌ |
| Plasmid Replicons | ✅ Per‑isolate table | ✅ Gene‑centric table | ❌ |
| Point Mutations | ✅ Per‑isolate table | ✅ Gene‑centric table | ❌ |
| Dynamic Grouping | ❌ | ✅ By ST, O serotype, Combinations | ❌ |
| Filter by Database | ✅ | ❌ | ❌ |
| Search by Sample | ✅ | ✅ | ❌ |
| Export to CSV | ✅ | ✅ | ✅ |
| Co‑occurrence Analysis | ❌ | ✅ Top 500 gene pairs | ✅ Network visualization |
| Principal Component Analysis (PCA) | ❌ | ❌ | ✅ Gene presence/absence PCA |
| Stacked Bar Charts | ❌ | ❌ | ✅ ST‑Serotype, AMR‑Virulence |
- Dynamic grouping – reorganise gene lists by MLST, O serotype, or combinations (e.g.,
ST‑O). - Horizontally scrollable tables – no data truncation.
- Filter by database – in sample‑centric mode, show only AMR, virulence, plasmids, biocides, or heavy metals.
- Search – find specific samples or genes instantly.
- Export to CSV – download any table for downstream analysis.
- Print‑friendly – print any section with the built‑in button.
- Network visualization – gene co‑occurrence network with hover details and degree‑based node sizing.
- PCA clustering – 2D projection of gene presence/absence profiles, coloured by ST.
| Question | Which Report |
|---|---|
| "What is the complete resistance profile of isolate X?" | Sample‑Centric |
| "Which STs carry blaVIM?" | Gene‑Centric (group by ST) |
| "Are there any O11 isolates with ExoU?" | Sample‑Centric + search |
| "Which serotypes are associated with ST235?" | Visual Dashboard (stacked bar) |
| "Do any isolates have colistin resistance mutations?" | Both (mutations tab) |
| "What is the most common plasmid replicon in ST111?" | Gene‑Centric (group by ST) |
| "Is there a correlation between serotype and virulence gene carriage?" | Gene‑Centric (group by serotype) |
| "Which genes co‑occur most frequently?" | Gene‑Centric (co‑occurrence) or Visual Dashboard (network) |
All reports are self‑contained HTML files – no internet connection needed after loading. You can share them with collaborators, attach them to publications, or upload them to AI tools (ChatGPT, Claude, Gemini) for interactive analysis.
# 1. Install PseudoScope
conda create -n pseudoscope -c conda-forge -c bioconda pseudoscope -y
conda activate pseudoscope
# 2. Mandatory first‑time database setup
abricate --setupdb
pseudoscope --update-amr-db
# 3. Run analysis on all .fna files
pseudoscope -i "*.fna" -o results --threads 4
# 4. Open the interactive ultimate report
firefox results/GENIUS_PSEUDOMONAS_ULTIMATE_REPORTS/genius_pseudomonas_ultimate_report.html| Resource | Minimum | Recommended |
|---|---|---|
| CPU cores | 2 | 8+ |
| RAM | 4 GB | 8 GB |
| Storage | 10 GB | 20 GB |
| OS | Linux, macOS, WSL2 | Ubuntu 22.04+ |
conda config --add channels conda-forge
conda config --add channels bioconda
conda create -n pseudoscope python=3.9 pseudoscope -y
conda activate pseudoscope
pseudoscope --helpmamba create -n pseudoscope -c conda-forge -c bioconda pseudoscope -y
mamba activate pseudoscopedocker pull bbeckleyhub/pseudoscope:latest
# Run as your own user ID – files will be owned by you, no sudo chown needed
docker run --rm \
-u $(id -u):$(id -g) \
-v $(pwd):/data \
-w /data \
bbeckleyhub/pseudoscope:latest \
-i "*.fna" -o results --threads 4Why
-u $(id -u):$(id -g)?
By default, Docker runs asrootinside the container, so output files are owned by root. Adding-u $(id -u):$(id -g)runs the container with your host user ID, meaning all output files are created with your ownership – you never needsudo chownto access them.
Option A – Build directly from Docker Hub:
singularity pull pseudoscope.sif docker://bbeckleyhub/pseudoscope:latestOption B – Convert a local Docker image (if network issues on HPC):
On a machine with Docker:
docker pull bbeckleyhub/pseudoscope:latest
docker save bbeckleyhub/pseudoscope:latest -o pseudoscope.tar
singularity build pseudoscope.sif docker-archive://pseudoscope.tar
scp pseudoscope.sif user@hpc.cluster:~Run on HPC (Singularity already runs as your user, so no -u flag needed):
singularity run --writable-tmpfs -B $(pwd):/data pseudoscope.sif \
-i "/data/*.fna" -o /data/output --threads 8All output files will be owned by your HPC user – no sudo chown needed.
# Single genome
pseudoscope -i genome.fna -o results/
# Batch processing with glob pattern
pseudoscope -i "*.fna" -o batch_results --threads 16
# Skip specific modules
pseudoscope -i "*.fasta" -o results --skip-qc --skip-viz
# Update AMR database only
pseudoscope --update-amr-db
# Show version
pseudoscope --version| Flag | Description |
|---|---|
-i, --input |
Input FASTA file(s) – supports glob patterns (e.g., "*.fna") |
-o, --output |
Output directory for all results |
-t, --threads |
Number of CPU threads (default: 2) |
--quiet |
Suppress all non‑error output |
--verbose |
Show full command output from modules |
--version |
Show version and exit |
--update-amr-db |
Update AMRfinderPlus database and exit |
--skip-qc |
Skip FASTA QC |
--skip-mlst |
Skip MLST |
--skip-past |
Skip PAST serotyping |
--skip-abricate |
Skip ABRicate |
--skip-amr |
Skip AMRfinderPlus |
--skip-summary |
Skip ultimate reporter |
--skip-sample-centric |
Skip sample‑centric interactive report (v1.2.0) |
--skip-viz |
Skip visualisation dashboard |
Supported FASTA formats: .fna, .fasta, .fa, .fn
results/
├── fasta_qc_results/ # FASTA QC per sample + summary
├── mlst_results/ # MLST per sample + mlst_summary.html/csv/json
├── past_results/ # PAST serotyping per sample + past_summary.html/csv/json
├── pseudo_abricate_results/ # ABRicate per database summary reports
├── pseudo_amrfinder_results/ # AMRfinder per sample + summary reports
├── GENIUS_PSEUDOMONAS_ULTIMATE_GENE_CENTRIC_REPORTS/
│ ├── genius_pseudomonas_ultimate_report.html ← Main gene‑centric interactive report
│ ├── genius_pseudomonas_ultimate_report.json
│ ├── sample_overview.csv
│ ├── amr_genes.csv
│ ├── virulence_genes.csv
│ └── gene_cooccurrence.csv
├── GENIUS_PSEUDOMONAS_SAMPLE_CENTRIC_REPORTS/ ← NEW in v1.2.0
│ ├── genius_pseudomonas_sample_centric_report.html ← Isolate‑centric interactive report
│ ├── genius_pseudomonas_sample_centric_report.json
│ ├── sample_overview.csv
│ ├── amr_genes.csv
│ ├── virulence_genes.csv
│ ├── plasmid_replicons.csv
│ ├── bacmet_genes.csv
│ ├── mutations.csv
│ └── gene_cooccurrence.csv
└── GENIUS_PSEUDOMONAS_VISUAL_DASHBOARD/
└── genius_pseudomonas_visual_dashboard.html ← Interactive visualisation dashboard
| Module | Purpose | Key Databases / Methods | Outputs |
|---|---|---|---|
| FASTA QC | Assembly quality control | Biopython | N50, GC%, contigs, length, HTML/TSV/JSON |
| MLST | Oxford scheme ST assignment | PubMLST (Jolley et al.) | ST, 7‑gene profile, summary table |
| PAST | O‑serotyping | pasty / camlhmp (Petit & Read) | O‑type (O1–O20), coverage, hits |
| AMRfinderPlus | AMR gene detection | NCBI curated database | Risk categories (Critical, High), per‑gene prevalence |
| ABRicate | Multi‑database screening | NCBI, CARD, ResFinder, VFDB, ARG‑ANNOT, PlasmidFinder, MEGARes, EcoH, BacMet2, Ecoli_VF | Per‑database summaries, master JSON |
| Ultimate Reporter (Gene‑centric) | Gene‑centric integration | All above HTML summaries | Interactive HTML (search/sort/filter), CSV exports |
| Sample‑centric Reporter (NEW) | Isolate‑centric integration | All above TSV/HTML summaries | Interactive isolate boxes with typing badges, full gene tables |
| Visualisation Dashboard | Interactive plots | Plotly, PCA, networkx, sklearn | Box plots, PCA, network, heatmap, stacked bars |
- Gene‑centric tables – Every AMR or virulence gene is shown with the complete list of genomes that carry it (no truncation).
- Sortable & searchable – Click column headers to sort; type in the search box to filter.
- Filter buttons – One‑click filters for:
- Carbapenemases (KPC, NDM, VIM, IMP, OXA‑48‑like)
- Colistin resistance (mcr‑1 … mcr‑10)
- ESBLs (GES, PER, VEB)
- 16S rRNA methyltransferases (armA, rmt)
- Efflux pumps, aminoglycoside modifying enzymes, etc.
- ST‑O combination table – Shows each ST and O‑type pair with the list of samples.
- FASTA QC integration – N50, GC%, total length displayed alongside typing results.
- CSV export – Every table can be exported with one click.
- AI‑assisted guide – Suggests questions for ChatGPT / Claude / Gemini.
- Each isolate is displayed in its own box with typing badges (ST, O‑type).
- Horizontally scrollable tables for AMR, virulence, plasmids, Bacmet, and mutations – no data loss.
- Filter by sample name and by database (e.g., show only AMRfinder genes).
- Mutation boxes – point mutations shown per isolate with full details (gene, mutation, class, subclass, contig, start/stop, coverage, identity).
- Dynamic grouping – within gene‑centric tables, group genome lists by ST, O‑type, or ST‑O to reveal clone‑specific patterns.
- ST and O‑type bar charts – Counts per type.
- Top 20‑50 AMR & virulence genes – Stacked bar charts by database (adjustable).
- Gene co‑occurrence network – Top 100 edges, interactive (hover, drag, zoom).
- FASTA QC box plots – GC%, AT%, N50, total length with all points (jitter) and outliers.
- PCA of gene presence/absence – Colored by ST, explained variance labels.
- Co‑occurrence heatmap – Pairwise counts of top 30 AMR genes.
All plots are generated with Plotly – fully interactive, downloadable as PNG/SVG, and embedded in a single scrolling HTML file.
# 1. Set up ABRicate databases (required for resistance/virulence screening)
abricate --setupdb
# 2. Download AMRfinderPlus database (required for AMR analysis)
pseudoscope --update-amr-dbThese steps are required only once; the databases will be reused for all future runs.
PseudoScope is optimised for P. aeruginosa and integrates many databases out of the box. However, if you need a different workflow, consider these excellent tools:
- Bactopia – A flexible, multi‑species pipeline for bacterial genomes (supports raw reads, uses Nextflow).
- Nullarbor – A read‑to‑report pipeline for public health microbiology (great for outbreak surveillance).
- Pathogenwatch – A web‑based platform for genomics surveillance (requires upload, but very user‑friendly).
Each has its own strengths; PseudoScope focuses on speed, local execution, and P. aeruginosa‑specific features.
PseudoScope is one of a growing collection of species‑optimised pipelines for the ESKAPE pathogens + E. coli (Enterococcus faecium, Staphylococcus aureus, Klebsiella pneumoniae, Acinetobacter baumannii, Pseudomonas aeruginosa, and Enterobacter species). Other tools in development:
- StaphScope – S. aureus (MLST, spa, SCCmec)
- Kleboscope – K. pneumoniae (MLST, K/O typing, AMR)
- Enteroscope – Enterobacter (van typing, MLST)
- AcinetoScope – A. baumannii (MLST, OCL typing)
- EnteroMark - Enterococcus (van typing, MLST)
- EcoliTyper - E. coli (serotyping typing, MLST)
A unified web interface is planned that will allow users to upload FASTA and run any of these pipelines without installing anything locally. Stay tuned!
Planned features (2026–2027):
- Raw read support – Direct analysis of FASTQ files using
shovill(spades) assembly on the fly. - Machine learning module – Predict virulence, outbreak potential, and clinical risk from gene profiles.
- Real‑time database sync – Automatic updates of MLST, PAST, and AMR databases without re‑installation.
- Web interface – Single‑page application to run PseudoScope online (file upload, progress monitoring, report download).
- Plugin system – Allow community‑contributed gene sets and analysis modules.
Call for collaborators – If you are interested in contributing to any of these features, please open an issue or contact the authors.
PseudoScope builds upon the incredible work of many open‑source developers and database curators. Special thanks to:
- Torsten Seemann (MLST, ABRicate, and foundational bioinformatics tools)
- Robert Petit & Tim Read (pasty / camlhmp‑blast‑regions for P. aeruginosa serotyping)
- NCBI AMR team (AMRFinderPlus)
- PubMLST (K. Jolley & M. Maiden)
- CGE (ResFinder, PlasmidFinder – their database structures inspired ABRicate integration)
- All database maintainers of CARD, VFDB, ARG-ANNOT, MEGARes, BacMet2, EcoH, Ecoli_VF
- Early adopters and beta testers at the University of Ghana Medical School
PseudoScope is developed and maintained in our spare time. If you find it useful for your research or clinical work, please consider sponsoring:
- GitHub Sponsors: https://github.com/sponsors/bbeckley-hub
- Support allows us to:
- Add raw read support faster
- Host a free public web interface
- Provide dedicated user support
- Keep databases updated
Every contribution, no matter how small, helps keep the project alive. Thank you!
If you use PseudoScope in your research, please cite:
@software{beckley2026pseudoscope,
author = {Brown Beckley and Vincent Amarh},
title = {PseudoScope: A species‑specific bioinformatics suite for rapid and accessible Pseudomonas aeruginosa genomic analysis},
year = {2026},
publisher = {GitHub},
url = {https://github.com/bbeckley-hub/pseudoscope},
version = {1.2.0}
}Integrated tools – please also cite the original authors of MLST, ABRicate, pasty, AMRFinderPlus, PubMLST, CARD, ResFinder, VFDB, and others (full citation list in the repository).
PseudoScope integrates several essential third-party tools and databases. If you use PseudoScope in your research, please also cite the following:
@software{seemann_mlst_2018,
author = {Seemann, T.},
title = {MLST: Scan contig files against traditional PubMLST typing schemes},
year = {2018},
publisher = {GitHub},
url = {https://github.com/tseemann/mlst}
}@article{jolley_pubmlst_2018,
author = {Jolley, K. A. and Bray, J. E. and Maiden, M. C. J.},
title = {Open-access bacterial population genomics: {BIGSdb} software, the {PubMLST.org} website and their applications},
journal = {Wellcome Open Research},
volume = {3},
pages = {124},
year = {2018},
doi = {10.12688/wellcomeopenres.14826.1}
}@software{seemann_abricate_2018,
author = {Seemann, T.},
title = {ABRicate: Mass screening of contigs for antimicrobial resistance and virulence genes},
year = {2018},
publisher = {GitHub},
url = {https://github.com/tseemann/abricate}
}@article{feldgarden_amrfinderplus_2021,
author = {Feldgarden, M. et al.},
title = {AMRFinderPlus and the Reference Gene Catalog facilitate examination of the genomic links among antimicrobial resistance, stress response, and virulence},
journal = {Scientific Reports},
volume = {11},
pages = {12728},
year = {2021},
doi = {10.1038/s41598-021-91456-0}
}@software{petit_pasty_2021,
author = {Petit, R. A.},
title = {PASTY: A tool easily taken advantage of for in silico serogrouping of Pseudomonas aeruginosa isolates},
year = {2024},
publisher = {GitHub},
url = {https://github.com/rpetit3/pasty},
note = {PAST and PASTY (for Pseudomonas aeruginosa)}
}@software{petit_camlhmp_2021,
author = {Petit, R. A.},
title = {camlhmp: Classification through yAML Heuristic Mapping Protocol},
year = {2024},
publisher = {GitHub},
url = {https://github.com/rpetit3/camlhmp}
}@article{alcock_card_2023,
author = {Alcock, B. P. et al.},
title = {CARD 2023: expanded curation, support for machine learning, and resistome prediction at the Comprehensive Antibiotic Resistance Database},
journal = {Nucleic Acids Research},
volume = {51},
number = {D1},
pages = {D690-D699},
year = {2023},
doi = {10.1093/nar/gkac920}
}@article{bortolaia_resfinder_2020,
author = {Bortolaia, V. et al.},
title = {ResFinder 4.0 for predictions of phenotypes from genotypes},
journal = {Journal of Antimicrobial Chemotherapy},
volume = {75},
number = {12},
pages = {3491-3500},
year = {2020},
doi = {10.1093/jac/dkaa345}
}@article{chen_vfdb_2016,
author = {Chen, L. et al.},
title = {VFDB 2016: hierarchical and refined dataset for big data analysis—10 years on},
journal = {Nucleic Acids Research},
volume = {44},
number = {D1},
pages = {D694-D697},
year = {2016},
doi = {10.1093/nar/gkv1239}
}@article{carattoli_plasmidfinder_2014,
author = {Carattoli, A. et al.},
title = {In silico detection and typing of plasmids using PlasmidFinder and plasmid multilocus sequence typing},
journal = {Antimicrobial Agents and Chemotherapy},
volume = {58},
number = {7},
pages = {3895-3903},
year = {2014},
doi = {10.1128/AAC.02412-14}
}@article{Pal_bacmet_2014,
author = {Pal, C. et al.},
title = {BacMet: antibacterial biocide and metal resistance genes database},
journal = {Nucleic Acids Research},
volume = {42},
pages = {D737-D743},
year = {2014},
doi = {10.1093/nar/gkt1252}
}@article{biopython_2009,
author = {Cock, P. J. A. et al.},
title = {Biopython: freely available Python tools for computational molecular biology and bioinformatics},
journal = {Bioinformatics},
volume = {25},
number = {11},
pages = {1422-1423},
year = {2009},
doi = {10.1093/bioinformatics/btp163}
}@article{doster_megares_2020,
author = {Doster, E. et al.},
title = {MEGARes 2.0: a database for classification of antimicrobial drug, biocide and metal resistance determinants in metagenomic sequence data},
journal = {Nucleic Acids Research},
volume = {48},
pages = {D561-D569},
year = {2020},
doi = {10.1093/nar/gkz1010}
}Brown Beckley (Primary Developer)
University of Ghana Medical School – Department of Medical Biochemistry
📧 brownbeckley94@gmail.com
🐙 GitHub: bbeckley-hub
📞 +233 508820617
Vincent Amarh (Co‑author, Advisor)
University of Ghana Medical School – Department of Medical Biochemistry
For bug reports, feature requests, or collaborations, please use the GitHub issue tracker.
The PseudoScope pipeline code (workflow engine, report generation, HTML templates, visualisation, and ultimate reporter) is licensed under the MIT License – see the LICENSE file for details.
Third‑party tools and databases are used under their respective licenses (GPL, Apache, Public Domain, etc.). By using PseudoScope, you agree to comply with those licenses.
