GENOMICS-CDDBRG/Genome_Comparative_Analysis

WOLOJI Comprehensive Bacterial Genomics Suite v2.1.0

WOLOJI is a Docker-based Streamlit platform for bacterial isolate whole-genome analysis. It starts from raw Illumina reads, Oxford Nanopore reads or finished assemblies, runs established command-line tools in a fixed order, and returns one ZIP package with results, logs and provenance records. It also provides standalone sequence utilities for primer design, local BLAST, phylogenetic trees and output concordance checks.

This Space is built from four files only:

Analysis modules

Every run also writes input SHA256 checksums, a command manifest, a run manifest with software versions and database paths, an assembly summary table, N50 and GC figures (600 dpi) and a short methods note.

Sequence utilities tab

• —Primer design with Primer3 (primer3-py).
• —GeneClean-BLAST: local blastn of a query FASTA against a subject FASTA.
• —PhyloForge: MAFFT alignment and IQ-TREE 2 tree with ModelFinder and 1000 ultrafast bootstraps (at least four sequences).
• —Output concordance: compares a WOLOJI table with a table from a direct run of the same tool and reports key precision, recall, F1 and value disagreements.

Out of scope in this build

Genome annotation (Bakta, Prokka), codon usage and composition, AMR detection, virulence screening, secondary metabolites, eggNOG-mapper and Panaroo are handled by separate dedicated tools.

Deploying on Hugging Face

1. 1.Create a new Space and choose Docker as the SDK.
2. 2.Upload the four files to the root of the Space.
3. 3.Choose the toolset by editing the ARG WOLOJI_TOOLSET= line in the Dockerfile:

1. 1.Use CPU hardware with enough RAM for bacterial assembly. The free CPU Space is suitable for interface testing, utilities and small data sets. SPAdes on a typical 5 Mb genome at 100x coverage needs about 8 to 16 GB RAM, and GTDB-Tk needs far more.
2. 2.Attach persistent storage and place the reference databases under /data.
3. 3.Add the database locations as Space variables, for example:

GTDBTK_DATA_PATH=/data/gtdbtk
CHECKM2DB=/data/checkm2/uniref100.KO.1.dmnd
GENOMAD_DB=/data/genomad_db
MOB_SUITE_DB=/data/mob_suite

1. 1.Restart the Space, open Tools & databases, and confirm that the expected tools and databases are detected.
2. 2.Run one small, well characterised isolate before analysing study data.

The build does not download the large biological databases. Modules that depend on them stay visible and are recorded as skipped until the paths are configured. Initialise MOB-suite and download the GTDB-Tk release that matches the installed GTDB-Tk version before deployment, not during an analysis.

Running locally

With Docker:

docker build -t woloji .                                   # standard toolset
docker build --build-arg WOLOJI_TOOLSET=full -t woloji .   # full toolset
docker run -p 7860:7860 -v /path/to/databases:/data \
  -e GTDBTK_DATA_PATH=/data/gtdbtk -e CHECKM2DB=/data/checkm2/uniref100.KO.1.dmnd \
  -e GENOMAD_DB=/data/genomad_db -e MOB_SUITE_DB=/data/mob_suite woloji

Then open http://localhost:7860.

Without Docker (Python 3.11 or newer):

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
streamlit run app.py

Without the command-line tools installed, use Dry run in the sidebar. It records every intended command in the result package without running it, which is useful for checking inputs and settings.

Input

Upload FASTQ, FASTQ.GZ, FASTA, FASTA.GZ or one ZIP that contains them.

Without a metadata table, WOLOJI pairs reads by file name: Sample01_R1.fastq.gz / Sample01_R2.fastq.gz, Sample01_1.fq / Sample01_2.fq and lane suffixes such as _R1_001 are recognised. A FASTQ without a pair is treated as long reads, and a FASTA file is treated as a finished assembly. If two files claim the same role for one sample, the run stops and asks for a metadata table instead of guessing.

A metadata CSV or TSV gives full control. Sample_ID is required and every file it names must be uploaded:

Sample_ID,Read_1,Read_2,Long_Reads,Assembly,Genus,Species
ISO01,ISO01_R1.fastq.gz,ISO01_R2.fastq.gz,,,Escherichia,coli
ISO02,,,ISO02_nanopore.fastq.gz,,Klebsiella,pneumoniae
ISO03,,,,ISO03.fasta,Staphylococcus,aureus

Other inputs: a reference genome (FASTA or GenBank) for core SNP analysis, and a chewBBACA schema as a ZIP for cgMLST or wgMLST. Use the same schema and training file for every isolate you compare.

Method notes

• —Assembly strategy. In Auto mode, isolates with both short and long reads are assembled with Unicycler, long reads alone with Flye (--nano-hq) and then Polypolish when short reads are present, and short reads alone with SPAdes --isolate. Set the expected genome size for Flye in the sidebar.
• —GTDB-Tk. classify_wf runs with --skip_ani_screen, which is required from GTDB-Tk 2.2 onwards when no Mash database is supplied. Do not mix GTDB-Tk software and reference data releases.
• —Core SNP tree. Snippy uses reads when available and assemblies otherwise. After Gubbins removes recombinant regions, the tree is inferred from polymorphic sites only, so WOLOJI adds ascertainment bias correction (+ASC) to the IQ-TREE model. Without it, branch lengths are overestimated.
• —fastp --n_base_limit is an absolute count of N bases per read, not a percentage.

Result package

00_input/                  uploaded files and schema
01_read_qc/                fastp, FastQC and MultiQC reports
02_assembly/               SPAdes, Flye or Unicycler output
03_polishing/              Polypolish output
04_assembly_qc/            QUAST and CheckM2
05_taxonomy/               GTDB-Tk, Mash and skani
12_mobileome/              MOB-suite, geNomad, IntegronFinder, MinCED
13_typing/                 mlst and chewBBACA
16_phylogenomics/          Snippy, snippy-core, Gubbins, IQ-TREE
17_population/             PopPUNK
20_publication_report/     tables, figures, methods_note.txt, run_summary.json
logs/                      stdout and stderr of every command
input_manifest.tsv         SHA256 checksum of every input file
command_manifest.json      every executed or skipped command with exit code, times and reason
run_manifest.json          parameters, modules, database paths and software versions

Validation before publication

Passing a dry run or a successful deployment does not establish biological validity. Before a manuscript, compare WOLOJI output with direct command-line runs of the same tools on public or curated data sets, using the same software and database releases:

1. 1.Read QC and assembly: retained reads, assembly size, contigs, N50, genome fraction and misassemblies.
2. 2.Taxonomy: species calls, ANI and aligned fraction against curated reference genomes.
3. 3.Mobile elements: curated positive and negative genomes, with database versions.
4. 4.MLST and cgMLST: exact concordance with independently generated profiles.
5. 5.SNP phylogenomics: core SNP counts, pairwise SNP distances and tree topology.
6. 6.Reproducibility: rerun identical inputs with the same image and databases and compare checksums where outputs are deterministic.
7. 7.Performance: wall-clock time, peak RAM, disk use and failure rate as the number of isolates grows.

The Output concordance tab performs the table comparison. The same function is available from the command line:

python app.py compare woloji_mlst.tsv direct_mlst.tsv --keys Sample_ID --json-out mlst_concordance.json

It matches rows on the key columns, reports key precision, recall and F1, and lists up to 100 value disagreements. Numeric columns are compared with --numeric-tolerance (default 1e-8).

Use at least one established bacterial WGS workflow as an external comparator, and report biological concordance, computational performance and usability as separate outcomes. Do not claim better accuracy only because more modules are available through a graphical interface.

Citation and licence

WOLOJI coordinates other programs. Publications should cite WOLOJI and every underlying program that was executed in the chosen workflow, together with the database release dates and versions. The command manifest and run manifest list what was run.

The WOLOJI application code is released under the MIT License. Each external tool and reference database keeps its own licence and terms; check them before redistribution or commercial use.

Changelog

2.1.0

• —Consolidated the repository into four files: app.py, Dockerfile, requirements.txt and README.md.
• —Merged the output comparison script into app.py, as an interface tab and as python app.py compare.
• —Merged the full and lite Dockerfiles into one file with a WOLOJI_TOOLSET switch (lite, standard, full). Removed Prokka and cd-hit, which this build no longer uses, and added the pipeline tools it does use.
• —Moved the app to port 7860 and a non-root user, as required by Hugging Face Spaces.
• —Added the missing requirements.txt with tested, pinned versions.
• —Dry run now records every intended command even when tools are not installed.
• —Automatic sample pairing now stops on ambiguous file names instead of overwriting them; metadata that names a missing file now raises an error.
• —Empty metadata cells no longer become the text "nan".
• —Results and download buttons now persist after a download click (PhyloForge previously lost the tree after the first download).
• —PhyloForge checks for duplicate sequence IDs and at least four sequences before running IQ-TREE.
• —Core SNP tree uses +ASC on the SNP-only alignment; GTDB-Tk runs with --skip_ani_screen.
• —Command timeouts are recorded instead of stopping the whole run; schema ZIPs are extracted safely.
• —The methods note now lists only the modules that were selected, and the version number comes from one place.

2.0.1

• —Timezone-aware run names, explicit check=False on subprocess calls, and removal of unused dependencies.

2.0.0

• —First unified bacterial WGS workflow from raw reads or assemblies, with SHA256 provenance, command manifests and publication outputs.