Quickstart

Python 3.10–3.13 is supported.

Install

For a released package:


uv venv
source .venv/bin/activate
uv pip install mllabiome

For a checked-out repository:


git clone https://github.com/CMG-GUTS/mllabiome.git
cd mllabiome
uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"

On Windows PowerShell, activate the environment with:


.venv\Scripts\Activate.ps1

Optional integrations

From a repository checkout, use uv sync --extra foundation for foundation-model dependencies or uv sync --extra tabpfn for TabPFN. Models and checkpoints may require separate access; see Foundation models.

Run an example

Browse the current example configurations . From a repository checkout, run a configuration with:


mllabiome path/to/config.py --stage evaluate

Run one stage


mllabiome path/to/config.py --stage explore
mllabiome path/to/config.py --stage evaluate
mllabiome path/to/config.py --stage ensemble
mllabiome path/to/config.py --stage inference
mllabiome path/to/config.py --stage federated-evaluate
mllabiome path/to/config.py --stage explain
mllabiome path/to/config.py --stage robustness
mllabiome path/to/config.py --stage report

The federated stage is a separate optional simulation; it is not part of --stage all. The default command runs the standard workflow:


mllabiome path/to/config.py --stage all

Minimal configuration


from pathlib import Path
from sklearn.ensemble import RandomForestClassifier
from mllabiome import mll
 
DATA = mll.Data(
    abundance_path=Path("profiles.tsv"),
    metadata=mll.Metadata(metadata_path=Path("metadata.tsv")),
    format="metaphlan_tsv",
    sample_id_col="sample_id",
    target_col="label",
    task="classification",
    class_labels=("control", "case"),
    positive_class="case",
)
 
SWEEP = mll.Sweep(
    data=DATA,
    experiment_dir=Path("runs/example"),
    resolutions=(("genus", ("genus",)),),
    count_transformations=(
        mll.Transformation("identity"),
        mll.Transformation("relative_abundance", composition_scope="joint"),
    ),
    learners=(
        ("RF", RandomForestClassifier(n_estimators=500, random_state=42, n_jobs=1)),
    ),
    evaluation=mll.Evaluation(
        protocol="repeated_nested_cv",
        outer_folds=5,
        inner_folds=3,
        repeats=2,
        optimize_metric="log_loss",
        random_state=42,
    ),
)

Run it with:


mllabiome config.py

For real studies, explicitly configure grouping, transformations, candidate learners, ensemble search, and explainability rather than relying on a minimal example.