bbeckleyhub/acinetoscope repository overview

⁠🐳 AcinetoScope Docker Image

Run the complete Acinetobacter baumannii typing pipeline with zero installation – just Docker.

⁠🧬 What is AcinetoScope?

AcinetoScope is a comprehensive bioinformatics pipeline for complete genomic characterization of Acinetobacter baumannii. It integrates multiple core analyses into a single automated workflow:

• Quality Control (FASTA QC) – Sequence validation and statistics
• MLST – Multi‑Locus Sequence Typing (Oxford & Pasteur schemes)
• K/O Locus Typing (Kaptive) – Capsule and lipooligosaccharide typing
• AMR Profiling – Resistance gene detection (AMRFinderPlus)
• ABRicate – Multi‑database screening (CARD, ResFinder, VFDB, NCBI, MEGARes, BacMet, etc.)
• Critical Genes Flagging – Priority markers for infection control
• Interactive HTML Reports – Gene‑centric integrated analysis
• Cross‑genome pattern discovery

📖 Full documentation, examples, and Conda installation instructions are available on the GitHub repository:
👉 https://github.com/bbeckley-hub/acinetoscope⁠

⁠📦 What’s inside this Docker image

• Full AcinetoScope pipeline (all modules)
• All dependencies pre‑installed (Conda environment, Perl, BLAST, ABRicate, Kaptive, etc.)
• ABRicate databases pre‑configured (abricate --setupdb already run)
• jq installed for reliable JSON parsing
• No need for Conda, no manual setup, no “read‑only filesystem” errors

⁠🚀 Quick Start

⁠Pull the image

docker pull bbeckleyhub/acinetoscope:latest

⁠Run on a single FASTA file

docker run --rm -v $(pwd):/data bbeckleyhub/acinetoscope:latest -i "/data/genome.fna" -o /data/output

After the run, output files are owned by root on your host. To reclaim ownership:

sudo chown -R $USER:$USER ./output

⁠Run on all FASTA files in the current directory

docker run --rm -v $(pwd):/data bbeckleyhub/acinetoscope:latest -i "/data/*.fna" -o /data/output

⁠📖 Detailed Usage

⁠Basic syntax

docker run --rm -v $(pwd):/data bbeckleyhub/acinetoscope:latest [OPTIONS]

• --rm : remove container after exit
• -v $(pwd):/data : mount current directory to /data inside container
• Input files must be under /data (e.g., /data/*.fna)
• Output directory must also be under /data (e.g., /data/output)

⁠All AcinetoScope options work

docker run --rm -v $(pwd):/data bbeckleyhub/acinetoscope:latest \
  -i "/data/*.fna" -o /data/output \
  --threads 8 --skip-qc --skip-amr

See docker run --rm bbeckleyhub/acinetoscope:latest -h for all options.

⁠Using custom threads

docker run --rm -v $(pwd):/data bbeckleyhub/acinetoscope:latest \
  -i "/data/*.fna" -o /data/output -t 16

⁠🔧 Handling File Permissions (The “Padlock” Issue)

By default, Docker runs as root inside the container. Any files written to your mounted directory will be owned by root:root.
You have three options:

⁠1. Change ownership after the run (easiest)

sudo chown -R $USER:$USER ./output

⁠2. Run with your host user ID (requires a small code fix – coming soon)

Currently not fully supported because AcinetoScope needs to write to its own installation directory. A future update will fix this.

⁠3. Use Singularity (recommended for HPC, no sudo needed)

See the Singularity section⁠ below.

⁠🧪 Testing Your Docker Setup

⁠Check help message

docker run --rm bbeckleyhub/acinetoscope:latest -h

⁠Verify ABRicate databases are installed

docker run --rm --entrypoint /bin/bash bbeckleyhub/acinetoscope:latest -c "abricate --list | head -5"

Expected output: list of databases (ncbi, card, vfdb, etc.)

⁠Verify jq is installed (important for correct summaries)

docker run --rm --entrypoint /bin/bash bbeckleyhub/acinetoscope:latest -c "jq --version"

Should output jq-1.6 or similar.

⁠🖥️ Singularity for HPC (no sudo, correct ownership)

On HPC clusters that support Singularity/Apptainer⁠, you can run AcinetoScope without sudo and output files will be owned by your user automatically.

⁠Option A: Direct pull (if network allows)

singularity pull acinetoscope.sif docker://bbeckleyhub/acinetoscope:latest
singularity run --writable-tmpfs -B $(pwd):/data acinetoscope.sif -i "/data/*.fna" -o /data/output

⁠Option B: Convert from a local Docker image (when singularity pull fails)

If you encounter TLS timeouts or other network errors (common on some HPCs), convert an existing Docker image to a Singularity SIF file on a machine with Docker, then transfer the .sif file to the HPC.

Step 1 – on a machine with Docker (e.g., your laptop):

docker pull bbeckleyhub/acinetoscope:latest
docker save bbeckleyhub/acinetoscope:latest -o acinetoscope.tar
singularity build acinetoscope.sif docker-archive://acinetoscope.tar

Now copy acinetoscope.sif to your HPC home or project directory (e.g., using scp).

Step 2 – on the HPC (no sudo needed):

singularity run --writable-tmpfs -B $(pwd):/data acinetoscope.sif -i "/data/*.fna" -o /data/output

⁠Explanation of flags

⁠Additional options

You can use any AcinetoScope flag, e.g.:

singularity run --writable-tmpfs -B $(pwd):/data acinetoscope.sif \
    -i "/data/*.fna" -o /data/output --threads 8 --skip-qc

⁠Verify it works

After a successful run, you will see output like:

✓ QC analysis completed!
✓ MLST Pasteur completed
...
✓ 🎉 All analyses completed successfully!

All result files in ./output will be owned by your HPC user – no sudo chown needed.

⁠📁 Output Structure

After a successful run, your output directory will contain:

output/
├── fasta_qc_results/
├── mlst_results/
├── k_o_results/          # Kaptive (K/O locus)
├── abricate_results/     # Multi-database screening
├── amr_results/          # AMRFinderPlus
└── GENIUS_ULTIMATE_results/      # Ultimate HTML reports

The main interactive report is summary_results/ACINETOSCOPE_ULTIMATE_REPORTS/genius_acinetobacter_report.html.

⁠❓ Frequently Asked Questions

⁠Why are output files owned by root?

Docker containers run as root by default. Use sudo chown or Singularity to fix ownership.

⁠Can I use --user $(id -u):$(id -g)?

Not yet – AcinetoScope currently needs to write into its own installation directory. A future update will remove this limitation.

⁠How large is the image?

Approximately 1–2 GB (includes Conda, all dependencies, ABRicate databases, and Kaptive).

⁠Can I run this on Windows / macOS?

Yes, with Docker Desktop. Mount paths must be absolute (e.g., -v /c/Users/name/data:/data on Windows Git Bash).

⁠Does it work on ARM (Apple Silicon)?

The image is built for linux/amd64. On Apple Silicon, Docker will use emulation (may be slower).

⁠📜 License & Citation

AcinetoScope Docker image bundles the same tools as the Conda package. See the main README⁠ for third‑party licenses.

If you use AcinetoScope in research, please cite the associated paper (when available) or the software:

@software{beckley2026acinetoscope,
  title = {AcinetoScope: Comprehensive genomic typing and surveillance platform for Acinetobacter baumannii},
  author = {Beckley, B. et a.l},
  year = {2026},
  url = {https://github.com/bbeckley-hub/acinetoscope}
}

⁠🔗 Links

• GitHub repository (full documentation, Conda install, examples):
  https://github.com/bbeckley-hub/acinetoscope⁠
• Docker Hub (image registry):
  https://hub.docker.com/r/bbeckleyhub/acinetoscope⁠
• Report issues:
  https://github.com/bbeckley-hub/acinetoscope/issues⁠