# Geomosaic Cookbook

The **Geomosaic Cookbook** is a companion repository containing reproducible downstream analysis and visualization workflows for outputs generated by Geomosaic.

While Geomosaic focuses on the execution and integration of metagenomic analyses, the Cookbook provides examples of how the resulting data can be imported, explored, statistically analysed, and visualized using R, Python, and Jupyter notebooks.

The Cookbook is available at:

[https://github.com/giovannellilab/geomosaic_cookbook](https://github.com/giovannellilab/geomosaic_cookbook)

## Why use the Cookbook?

Geomosaic generates standardized outputs that can be integrated across samples using the `gather` command. These gathered tables provide a convenient starting point for downstream ecological, functional, and comparative analyses.

The Cookbook provides ready-to-use examples showing how these outputs can be transformed into:

- taxonomic composition plots;
- ordination analyses;
- functional profiles;
- heatmaps;
- comparisons among samples or environments;
- genome-resolved visualizations;
- analyses of custom HMM annotations;
- Redox Metabolic Index (RMI) and Metal Plasticity Index (MPI) comparisons;
- publication-ready figures.

The notebooks are designed both as reproducible examples and as templates that can be adapted to individual datasets.

## Current analyses

The current Cookbook includes notebooks for several Geomosaic outputs, including:

- **Kaiju** — downstream analysis and visualization of read-based taxonomic profiles;
- **fmh-funprofiler** — exploration of read-based functional annotations;
- **KOfam Scan** — downstream analysis of assembly-based KO annotations;
- **MAG HMM Annotation** — visualization and comparison of custom HMM annotations across reconstructed genomes;
- **GTDB-Tk** — downstream processing of genome-resolved taxonomic classifications;
- **RMI and MPI** — visualization and comparison of the Redox Metabolic Index and Metal Plasticity Index across samples.

Additional notebooks and scripts will be added as new Geomosaic modules and downstream analyses are developed.

## Relationship with `geomosaic gather`

For supported modules, the Geomosaic `gather` command integrates results generated independently for multiple samples into unified tables.

A typical workflow is therefore:

```text
Geomosaic analysis
        ↓
geomosaic gather
        ↓
standardized multi-sample tables
        ↓
Geomosaic Cookbook
        ↓
statistics, exploration and visualization
```

This separation keeps the core Geomosaic workflow focused on reproducible bioinformatic processing while allowing downstream analyses to remain flexible and easily customizable.

## Installation

Clone the Cookbook repository:

```bash
git clone https://github.com/giovannellilab/geomosaic_cookbook.git

cd geomosaic_cookbook
```

Create the dedicated analysis environment using the environment file provided in the repository:

```bash
mamba env create -f environment.yaml
```

Activate the environment:

```bash
conda activate geomosaic_analysis
```

```{note}
The Cookbook uses a separate environment from the main Geomosaic installation because downstream statistical analysis and visualization require a different set of R and Python packages.
```

If using RStudio, launch it from a terminal after activating the Cookbook environment so that RStudio uses the correct Conda environment.

## Repository structure

The Cookbook repository contains:

- `notebooks/` — documented Jupyter notebooks for specific Geomosaic outputs;
- `scripts/` — reusable R and Python functions;
- `tables/` — auxiliary tables used in downstream analyses;
- `environment.yaml` — the Conda environment required for the main Cookbook analyses;
- additional environment files for analyses requiring specialized dependencies.

The notebooks can be executed directly or used as templates for custom downstream workflows.

## From Geomosaic output to figures

A typical analysis consists of:

1. running the desired Geomosaic modules;
2. using `geomosaic gather` where available to combine results across samples;
3. opening the corresponding Cookbook notebook;
4. importing the gathered tables;
5. adding sample metadata or environmental variables;
6. adapting the statistical analysis and visualization to the research question.

Because the input tables generated by `gather` are standardized, the same downstream workflow can be reused across projects with relatively minor modifications.

## Reproducibility

The Cookbook is intended to make the transition from bioinformatic processing to biological interpretation transparent and reproducible.

The notebooks provide the complete code used for data import, transformation, statistical analysis, and figure generation. Users can therefore reproduce the examples directly, inspect every analytical step, and modify them for their own datasets.

```{tip}
The Cookbook is not required to use Geomosaic. Geomosaic outputs can be analysed using any statistical or visualization environment. The Cookbook provides tested examples and reusable templates to accelerate downstream analyses.
```