- Overview
- Features
- Architecture
- Quick Start
- Installation
- Usage Guide
- API Reference
- Deployment
- Processing Large Datasets
- Citation
- Contributing
- License
- Contact
StaphScope Web is a user-friendly web interface for the StaphScope command-line tool, a comprehensive bioinformatics pipeline for Staphylococcus aureus genomic analysis. It allows researchers and clinicians to upload bacterial genomes and receive detailed typing results without any command-line expertise.
The tool integrates six essential genotyping methods into a single, cohesive workflow, making MRSA/MSSA surveillance accessible to all.
| Module | Purpose | Outputs |
|---|---|---|
| FASTA QC | Quality control and statistics | HTML/TSV/JSON reports |
| MLST Typing | Multi-locus sequence typing | Sequence type, clonal complex |
| spa Typing | Protein A gene analysis | spa type, repeat patterns |
| SCCmec Typing | Methicillin resistance cassette | Cassette type (I-XIII) |
| AMR Profiling | Antimicrobial resistance genes | 5,000+ genes, risk categories |
| ABRicate Screening | 9 databases (CARD, VFDB, PlasmidFinder, etc.) | Resistance, virulence, plasmids |
| Lineage Database | Global epidemiological context | 44 major lineages |
| Visualization | Interactive dashboards | PNG/SVG/PDF outputs |
- ✅ Drag-and-drop file upload (single, multiple, or ZIP)
- ✅ Module selection – choose which analyses to run
- ✅ Real-time progress monitoring with live logs
- ✅ Beautiful HTML reports with interactive visualizations
- ✅ Download all results as a single ZIP
- ✅ Responsive design – works on desktop and tablet
- ✅ 10-file limit for fair resource usage
- Automated MRSA/MSSA classification
- Clinical gene flagging (PVL, enterotoxins, van genes)
- Risk categorization: 'Critical Risk', 'High Risk'
- Cross-genome pattern discovery
staphscope-web/
├── app.py # Flask application with routes
├── tasks.py # Celery worker tasks
├── config.py # Configuration settings
├── requirements.txt # Python dependencies
├── jobs/ # Job directories (created at runtime)
├── static/ # Static files (CSS, JS)
│ ├── css/
│ └── js/
└── templates/ # HTML templates
├── base.html
├── index.html
├── progress.html
└── results.html
- Backend: Flask (Python web framework)
- Task Queue: Celery with Redis broker
- Bioinformatics Engine: StaphScope (conda environment)
- Frontend: Bootstrap 5, JavaScript
- Deployment: Gunicorn + Nginx + systemd
- Python 3.8+
- Redis server
- Conda (for StaphScope environment)
git clone https://github.com/bbeckley-hub/staphscope-web.git
cd staphscope-webpython3 -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
pip install -r requirements.txt- Ubuntu/Debian:
sudo apt install redis-server && sudo systemctl start redis - macOS:
brew install redis && brew services start redis - Windows: Use WSL2 or download from redis.io
Edit config.py to point to your StaphScope installation:
CONDA_PYTHON = "/path/to/your/miniconda3/envs/staphscope/bin/python"
STAPHSCOPE_SCRIPT = "/path/to/your/miniconda3/envs/staphscope/bin/staphscope"celery -A tasks.celery worker --loglevel=infopython app.pyVisit http://127.0.0.1:5000 and start analyzing!
- Navigate to the home page
- Click "Choose Files" and select one or more FASTA files (
.fasta,.fna,.fa) - Alternatively, upload a ZIP archive containing multiple FASTA files
- Select which modules to run (uncheck to skip)
- Click "Submit" and wait for analysis to complete
Results are organized into tabs:
- Comprehensive: Unified report of all analyses
- MLST: Sequence typing results
- spa: spa typing with repeat patterns
- SCCmec: Methicillin resistance cassette typing
- AMR: Antimicrobial resistance genes
- ABRicate: Multi-database screening
- Lineage: Phylogenetic lineage information
- FASTA QC: Quality control metrics
- Visualization: Interactive plots and dashboards
Each tab provides:
- HTML reports for interactive viewing
- TSV/JSON downloads for further analysis
- Individual sample-level reports
Click the "Download All Results (ZIP)" button to get a complete archive of all analysis outputs.
The web app provides a simple REST API:
| Endpoint | Method | Description |
|---|---|---|
/ |
GET | Home page with upload form |
/submit |
POST | Submit files for analysis |
/status/<job_id> |
GET | Check job status (PENDING, RUNNING, COMPLETED, FAILED) |
/progress/<job_id> |
GET | Progress page with live logs |
/results/<job_id> |
GET | Results page |
/results/<job_id>/<path:filename> |
GET | Download specific result file |
/results/<job_id>/download |
GET | Download all results as ZIP |
- Ubuntu 20.04/22.04 (or similar Linux)
- 4+ CPU cores, 8+ GB RAM
- 50+ GB storage
- Domain name (optional but recommended)
- Set up the server (see full deployment guide)
- Install dependencies: Conda, Redis, Nginx
- Clone the repository:
git clone https://github.com/bbeckley-hub/staphscope-web.git /var/www/staphscope-web - Set up virtual environment:
python3 -m venv venv && source venv/bin/activate && pip install -r requirements.txt - Configure services: Create systemd units for Gunicorn and Celery
- Set up Nginx as reverse proxy
- Enable SSL with Let's Encrypt
Gunicorn (/etc/systemd/system/staphscope-web.service):
[Unit]
Description=Gunicorn instance for StaphScope Web
After=network.target
[Service]
User=staphscope
Group=staphscope
WorkingDirectory=/var/www/staphscope-web
Environment="PATH=/var/www/staphscope-web/venv/bin"
ExecStart=/var/www/staphscope-web/venv/bin/gunicorn --workers 3 --bind unix:/var/www/staphscope-web/staphscope.sock app:app
[Install]
WantedBy=multi-user.targetCelery (/etc/systemd/system/staphscope-celery.service):
[Unit]
Description=Celery worker for StaphScope Web
After=network.target redis.service
[Service]
User=staphscope
Group=staphscope
WorkingDirectory=/var/www/staphscope-web
Environment="PATH=/var/www/staphscope-web/venv/bin"
ExecStart=/var/www/staphscope-web/venv/bin/celery -A tasks.celery worker --loglevel=info
[Install]
WantedBy=multi-user.targetThe web version limits uploads to 10 files per job to ensure fair resource usage. For larger datasets, use the command-line version:
# 1. Install Miniconda (if not already)
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
bash Miniconda3-latest-Linux-x86_64.sh
source ~/.bashrc
# 2. Create StaphScope environment
conda create -n staphscope -c conda-forge -c bioconda -c bbeckley-hub staphscope -y
conda activate staphscope
# 3. Update databases
abricate --setupdb
# 4. Navigate to your FASTA files
cd /path/to/your/fasta/files
# 5. Run StaphScope (adjust pattern to match your files)
staphscope -i "*.fna" -o Staphscope_resultsNo need to specify threads – StaphScope automatically allocates optimal resources based on your CPU. ☕ Relax and enjoy your coffee while it runs!
If you use StaphScope in your research, please cite:
Beckley, B., Amarh, V. (2026). StaphScope: a species‑optimized computational pipeline for rapid and accessible Staphylococcus aureus genotyping and surveillance. BMC Genomics, 27:123.
DOI: 10.1186/s12864-026-12609-x
PMID: 41645058
Contributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (
git checkout -b feature/AmazingFeature) - Commit your changes (
git commit -m 'Add some AmazingFeature') - Push to the branch (
git push origin feature/AmazingFeature) - Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
Author: Brown Beckley
Affiliation: University of Ghana Medical School – Department of Medical Biochemistry
Email: brownbeckley94@gmail.com
GitHub: @bbeckley-hub
Project Link: https://github.com/bbeckley-hub/staphscope-web
-
StaphScope development team
-
University of Ghana Medical School
-
All contributors and beta testers
⭐ If you find this tool useful, please star the repository on GitHub! ⭐