A modular, open-source Nextflow toolkit for long-read microbiome analysis.
Somatem supports Oxford Nanopore and PacBio 16S, metagenomic, isolate, and longitudinal datasets. It provides preprocessing, taxonomic profiling, assembly and MAG recovery, isolate characterization, pathogen screening, and genome-dynamics workflows with reproducible Conda environments and HTML summaries.
Somatem supports Linux and macOS and requires Nextflow 26.04.6 or newer. Install the Bioconda package with conda, mamba, or micromamba:
micromamba create -n somatem -c bioconda somatem
micromamba activate somatem
somatem helpDownload the example datasets and sample sheets before trying a workflow without --input:
somatem examples --outdir /path/to/somatem-examples
somatem 16S --outdir resultsThe downloaded location is remembered automatically; set SOMATEM_EXAMPLE_DIR to override it.
The defaults work for local installations, but shared systems and HPC users may want to relocate databases and caches:
SOMATEM_DB_DIR: downloaded databases (default:~/somatem_databases)NXF_CONDA_CACHEDIR: generated Nextflow Conda environmentsMAMBA_ROOT_PREFIX: downloaded and extracted micromamba packagesSOMATEM_UNIFIED_DB_DIR: unified databases used for ensemble species detection (defaults toSOMATEM_DB_DIR)
Set overrides in your shell or source assets/scripts/somatem_env.sh from your shell profile:
export SOMATEM_DB_DIR=/path/to/databases
echo "source /path/to/somatem_env.sh" >> ~/.bashrc| Command | Purpose |
|---|---|
somatem pre_processing |
NanoPlot QC, Chopper filtering, and Deacon host depletion |
somatem 16S |
Emu 16S profiling and Taxburst visualization |
somatem taxonomic_profiling |
Metagenomic profiling with Sylph (default), Lemur + MAGnet, Kraken2, or SingleM |
somatem assembly_mags |
Flye assembly, AGB graph reports, read mapping, Pigeon/SemiBin2 binning, CheckM2 assessment, SingleM appraisal, and Bakta annotation |
somatem isolate_analysis |
Autocycler consensus from Flye, Myloasm, metaMDBG, Canu, and Hifiasm, optional Polypolish/Pypolca hybrid polishing, Kraken2, CheckM2, MOB-suite, Bakta, and BTyper3 |
somatem seqscreen |
Modular SeqScreen pathogen and functional screening with TSV and portable HTML reports |
somatem genome_dynamics |
Rhea structural-variation and horizontal-gene-transfer analysis with Bandage output |
somatem pre_download_databases |
Pre-fetch databases for the selected configuration |
Each subworkflow will have a dedicated page in the Somatem wiki covering inputs, options, databases, and examples. Common options are --input, --outdir, --threads, --data_type, and -params-file; run somatem help for the current CLI reference.
If Autocycler fails or its consensus is too small, the isolate workflow passes along a candidate assembly that meets --autocycler_min_genome_fraction (default 0.8) of that sample's supplied or estimated genome size. It selects the qualifying candidate closest to the expected size, breaking ties by filename. If no candidate qualifies, the sample is reported without an assembly and other samples continue. The size threshold is unchanged; fallback selection does not establish biological completeness.
Each completed selection writes isolate_analysis/<sample>/autocycler/<sample>.autocycler.selection.tsv, recording consensus, fallback, or no_assembly, the source, and the reason. The summary report shows recovery status; the length audit and Autocycler log remain alongside it. A fallback FASTA has no Autocycler consensus graph. Samples with all expected candidate assemblies proceed immediately; partial groups wait until the remaining assembler tasks finish.
Sample task failures are isolated to that sample and stage. Resource-related exits receive one retry, then the failed task is skipped; other sample task failures are skipped immediately. Check the summary and pipeline_info/execution_trace_*.txt for missing outputs and failed tasks, since a completed batch can contain failed samples. MOB-suite database readiness is checked once per run before parallel sample jobs start, reusing an initialized database. Shared database setup failures, invalid workflow settings, and aggregate report failures still fail the run.
For local isolate runs, --threads and --max_memory_gb budget the total resources requested by concurrent tasks as well as limiting individual tasks. With no explicit memory budget, the workflow reserves --local_memory_reserve_gb (default 4) from detected RAM. These are scheduler budgets; tools must still respect their requested resources. For cluster runs, configure the executor and queue limits for your scheduler. Retain the Nextflow work directory and use -resume when rerunning a batch to reuse successful tasks.
Reference databases can require 100 GB or more; Bakta alone is approximately 60 GB. The first applicable run downloads missing databases for reuse.
export SOMATEM_HOME=/path/to/somatem-data
export SOMATEM_DB_DIR=/path/to/databases
export SOMATEM_CONDA_CACHE=/path/to/nextflow-conda-envs
export MAMBA_ROOT_PREFIX=/path/to/micromamba-cache
export SOMATEM_UNIFIED_DB_DIR=/path/to/unified-databasesExplicit variables override SOMATEM_HOME. The installed launcher otherwise keeps Nextflow environments and micromamba packages under $CONDA_PREFIX/share/somatem. Direct nextflow run launches use the active $CONDA_PREFIX, or .somatem/conda_cache when no Conda environment is active. On a cluster, cache directories must be accessible from every compute node.
The assembly_mags workflow is compute- and storage-intensive. Plan for large temporary files and substantially longer runtimes than preprocessing or profiling workflows.
Developer notes are in docs/dev_notes.md, and software citations are collected in CITATIONS.md. If Somatem supports your research, please cite Somatem and the tools used by your selected workflow.
Contributions are welcome. Somatem is licensed under the GNU GPLv3.