Quickstart

The recommended way to run the bundled examples is to clone the repository, create a uv virtual environment, install the package in editable mode, and run one of the example sweep configurations. The repository includes lightweight data under examples/data/, so the examples are ready to run after installation.

1. Clone the repository

git clone https://github.com/CMG-GUTS/mllabiome.git
cd mllabiome

2. Create and activate a uv environment

uv venv
source .venv/bin/activate

On Windows PowerShell:

uv venv
.venv\Scripts\Activate.ps1

3. Install the package in editable mode

uv pip install -e .

Editable installation keeps the command-line interface and Python package linked to the checked-out repository, which is convenient when adapting example configurations.

4. Run a bundled example

mllabiome examples/configs_sweep.py

The example uses data from examples/data/ and writes results under examples/runs/.

5. Adapt the sweep

Sweep configurations are ordinary Python files. To adjust an example for another analysis, edit the active entries in:

_RESOLUTION_SETS
_build_count_transformations()
_build_models()

Add, remove, comment, or uncomment entries to define the representations, transformations, and learners to evaluate. Update DATA, EXPERIMENT_DIR, and EVALUATION for the dataset and validation design.

Resume and rerun stages

Runs are resumable. Re-running the same configuration preserves completed results and evaluates newly enabled or missing MPMA/split pairs.

mllabiome examples/configs_sweep.py --stage evaluate
mllabiome examples/configs_sweep.py --stage ensemble
mllabiome examples/configs_sweep.py --stage explain
mllabiome examples/configs_sweep.py --stage report

Use the stage commands when adding new learners or transformations, regenerating explanations, or refreshing the report.

PyPI installation after release

After the package is published on PyPI, users who do not need the repository examples can install the released package directly:

pip install mllabiome

Until then, use the repository-based editable installation above. The editable installation is also the recommended path when running or modifying the bundled examples.

Minimal mental model

The package evaluates MPMA candidates, searches ensembles, explains selected targets out-of-fold, and writes tables, figures, and reports under the configured experiment directory.