Modules Dependencies¶
Description¶
Geomosaic is organized as a collection of independent analytical modules connected through a graph-based dependency structure. Each module performs a specific analytical task and can be combined with others to generate workflows ranging from simple read-based analyses to complete genome-resolved metagenomic analyses.
Current metagenomic workflows can exploit three complementary analytical streams: read-based, assembly-based, and genome-resolved analyses. Rather than representing different levels of analytical quality, these streams provide complementary biological information at different levels of resolution and genomic context.
Read-based analyses preserve the broadest representation of the sequenced microbial community and are well suited for taxonomic and functional profiling across complete metagenomes. Assembly-based analyses reconstruct longer genomic fragments, enabling gene prediction, functional annotation, and gene neighbourhood analyses while retaining only the fraction of the community that can be successfully assembled. Genome-resolved analyses further associate genes and functions with reconstructed microbial populations through metagenome-assembled genomes (MAGs), providing organism-level genomic context while introducing the additional filtering inherent to assembly, binning, and genome-quality assessment.
Geomosaic was developed to integrate these three analytical representations within a single modular workflow. Users may execute the complete workflow or select only the analytical modules required for their specific scientific question. This modular design maximizes flexibility while maintaining reproducibility and simplifying workflow construction.
At first look, each module may represents a type of analysis that can be performed during the metagenomics workflows. However, this description is useful but not complete as the following
Highlight
A module is a type of metagenomics analysis that can be performed taking into consideration the dependencies to which it is linked. Therefore, a module will have specific dependencies if the package that implements that type of analysis will take in input the output of the linked modules.
Unlike traditional pipelines with fixed execution paths, Geomosaic allows users to execute only the modules required to answer their scientific question.
Geomosaic Graph Structure¶
The Geomosaic workflow is built around a Directed Acyclic Graph (DAG), where each node represents an analytical module and edges define dependencies among modules. These dependencies ensure that only valid workflows can be generated while allowing users to customize the analysis by selecting the modules they wish to execute.
The graph is organized around three main analytical streams:
Stream |
Module |
Depends on |
|---|---|---|
|
Pre-processing |
- |
|
Assembly |
Pre-processing |
|
Binning |
Pre-processing, Assembly |
During workflow generation, Geomosaic automatically evaluates these dependencies. For example, if the Assembly module is omitted, all downstream modules requiring assembled contigs are automatically excluded from the workflow. This dependency-based approach guarantees workflow consistency while preserving maximum analytical flexibility.
The complete dependency graph for the current release is shown below.
Input/output dependencies between modules¶
The definition of dependencies among Geomosaic modules is primarily determined by the type of input required and the type of output produced by the corresponding packages.
For instance, the assembly_readmapping module has the goal of mapping sequencing reads against the obtained assembly. Its dependencies are therefore the pre_processing and assembly modules, because the analysis requires both the processed reads and the assembled contigs as input. All packages integrated within this module must accept the same type of input and generate the same type of output, in this case SAM/BAM files.
Note
It is important that packages integrated within the same module provide compatible output formats. Otherwise, downstream modules may not work consistently across the different software choices available to the user.
In this example, any read-mapping package can in principle be integrated into the module as long as it accepts processed reads and the assembly as input and produces the expected outputs. Geomosaic standardizes these outputs as read_mapping_sorted.bam and read_mapping_sorted.bam.bai.
Another simple example is the assembly module, which represents one of the central steps in many metagenomic workflows. At the time of writing, Geomosaic integrates two packages for this task:
MEGAHIT
metaSPAdes
Both require the processed reads as input and generate assembled contigs as output. Geomosaic standardizes the final assembly output as geomosaic_contigs.fasta, obtained after filtering the original assembler output to remove contigs shorter than 1,000 bp. Since both packages use the same input type, the assembly module depends on pre_processing.
What if two packages perform the same type of analysis but require different inputs?¶
This situation occurred during integration example 3, where KOfam Scan was added for functional annotation of MAGs.
Before this integration, DRAM was the only package performing a related type of analysis. However, the two tools require different inputs. DRAM typically takes as input a directory containing MAG FASTA files, whereas KOfam Scan operates on predicted protein sequences and therefore requires a preceding ORF-prediction step.
Because these input requirements imply different upstream dependencies, the two packages cannot belong to the same Geomosaic module.
For this integration, DRAM was therefore assigned to the mags_metabolic_function module, which depends directly on mags_retrieval, whereas KOfam Scan was integrated into the mags_functional_annotation module, which depends on mags_orf_prediction.
Module names are descriptive labels indicating the general analytical task performed by the packages. The key property defining a module is not its name, but the compatibility of its input requirements, output structure, and dependencies with the rest of the Geomosaic graph.
Integrated modules¶
The current Geomosaic release integrates software covering all major stages of metagenomic analysis, from quality control and taxonomic profiling to genome reconstruction and downstream annotation. Modules are organized according to the three complementary analytical streams and can be combined to build workflows adapted to different datasets and research questions.
| Stream-level | Modules | Packages |
|---|---|---|
| Read-based | Pre Processing | fastp |
| trimgalore | ||
| trimmomatic | ||
| Reads Quality Check | fastqc + reads count | |
| Functional Annotation | ARGs-OAP with Custom DB | |
| mi-faser | ||
| Taxonomic Annotation | Kaiju | |
| metaPhlAn | ||
| Assembly Based | Assembly | metaSPAdes |
| Megahit | ||
| Assembly Quality Check | Quast | |
| Meta-Quast | ||
| Read Mapping | Bowtie2 | |
| Bowtie2 - Output without unmapped reads | ||
| BBMap | ||
| BBMap - Output without unmapped reads | ||
| Read Coverage | CoverM (contigs) | |
| Taxonomic Annotation | Kraken2 | |
| ORF Prediction | Prodigal | |
| Domain Annoation | reCOGnizer | |
| HMM Annotation | HMMSearch | |
| ORF Annotation | eggNOG-mapper | |
| KOfam Scan | ||
| Functional Annotation | Bakta | |
| Binning Based | Binning | Multi-Binners (Metabat2 + MaxBin2 + SemiBin2) |
| Binning De-replication | DAS Tool | |
| Binning Quality Assessment | CheckM | |
| MAGs Retrieval | MAGs Retrieval | |
| MAGs Functional Annotation | DRAM | |
| Bakta | ||
| MAGs Taxonomic Annotation | GTDBtk | |
| MAGs ORF Prediction | Prodigal | |
| MAGS Domain Annotation | reCOGnizer | |
| MAGs ORF Annotation | KOfam Scan | |
| MAGs Coverage | CoverM (Genome) | |
| MAGs HMM Annotation | HMMSearch |
Future module integration¶
Geomosaic has been designed as an extensible platform, allowing the straightforward integration of new analytical modules and software packages as they become available.
The following modules are currently under evaluation for future integration.
Read-based
Functional annotation
mi-faser (custom database implementation)
Assembly-based
Functional annotation
Prokka
Taxonomic annotation
CAT/BAT
Additional tools can be proposed through the GitHub issue tracker. At present, Geomosaic supports the integration of software that can be installed through Conda environments.