GENOMICS-CDDBRG/Pan-Genome_Analysis_Tool

Gulumba Metagenomics Tool 1: Sequence Processing

First tool in a two tool metagenomics workflow. Takes raw shotgun metagenomic FASTQ files and optional metadata, and runs quality trimming, optional host removal, Kraken2/Bracken taxonomy, MEGAHIT assembly, genome resolved binning, and optional functional/resistance/mobile element annotation, depending on the selected analysis mode and which databases are configured. It finishes by writing a species abundance matrix that is the direct input to Bulamarwa Metagenomics Tool 2.

Before you deploy, read this

The core read processing and assembly tools (fastp, FastQC, MultiQC, Bowtie2, SAMtools, Kraken2, Bracken, MEGAHIT, QUAST, MetaBAT2, Prodigal, seqkit, dRep) are installed in the Docker image itself and work out of the box, apart from the Kraken2 database (see below).

CheckM2, GTDB-Tk, geNomad, eggNOG-mapper, and AMRFinderPlus are not installed by default, because each needs an external reference database that is tens of gigabytes, sometimes over one hundred gigabytes for GTDB-Tk. A standard Hugging Face Space does not have room for this. Realistic options:

1. 1.Leave these modules switched off. The app detects missing tools and databases automatically and skips the corresponding step, so the rest of the pipeline still runs and the Space stays small.
2. 2.Build with --build-arg INSTALL_OPTIONAL=true to install the extra tools, and use a Hugging Face persistent storage add-on (paid tier) to mount the databases, setting the matching environment variables below.
3. 3.Run this same Dockerfile on your own server or HPC node instead of on Hugging Face, where you can mount institutional database storage directly. The Dockerfile and app code do not change between these options.

Database environment variables

Set these as Space secrets (Settings tab) or container environment variables, pointing at a mounted path. A module is skipped whenever its variable is unset or the path does not exist.

Deploying this Space

1. 1.Create a new Space on Hugging Face, select the Docker SDK.
2. 2.Upload app.py, requirements.txt, environment-core.yml, and Dockerfile from this package (this README.md can go too, since its front matter configures the Space).
3. 3.If you need CheckM2/GTDB-Tk/geNomad/eggNOG-mapper/AMRFinderPlus, add a build argument INSTALL_OPTIONAL=true in the Space's Docker build settings before the first build.
4. 4.Set any database environment variables you have available, as secrets.
5. 5.Hugging Face builds the image and starts the container. The first build with the core tools only typically takes several minutes; with INSTALL_OPTIONAL=true it will take considerably longer and produces a much larger image.

Local test before deploying

docker build -t gulumba-tool1 .
docker run -p 7860:7860 -e KRAKEN2_DB=/databases/kraken2 -v /path/to/databases:/databases gulumba-tool1

Hand off to Tool 2

Download the results ZIP from a completed run, and take 10_Abundance_Matrix/species_relative_abundance.tsv (or species_estimated_reads.tsv) together with samplesheet_resolved.csv as the input files for Tool 2.