Sweep configuration

A current mllabiome sweep is a normal Python file. It should define the objects and builder functions below.


from pathlib import Path
from sklearn.ensemble import RandomForestClassifier
from mllabiome import mll
 
TITLE = "example mllabiome sweep"
EXPERIMENT_DIR = Path("examples/runs/EXAMPLE")
 
DATA = mll.Data(
    abundance_path=Path("examples/data/example_profiles.tsv"),
    metadata_path=Path("examples/data/example_metadata.tsv"),
    format="metaphlan_tsv",
    sample_id_col="sample_id",
    target_col="label",
    # Optional: additionally stratify repeated nested-CV by a metadata column.
    # The splitter uses target + this column as the composite stratum.
    # stratify_col="batch",
    label_map={"control": 0, "case": 1},
    class_labels=("control", "case"),
    positive_class=1,
)
 
_RESOLUTION_SETS = [
    ("genus", ("genus",)),
    # ("species", ("species",)),
    # ("family-genus", ("family", "genus")),
]
 
def _build_count_transformations():
    T = mll.Transformation
    return [
        T("none"),
        T("arcsin_sqrt"),
        # T("scikit-bio_clr"),
        # T("rank_col"),
    ]
 
def _build_models():
    return [
        ("RF_1000_msl5", RandomForestClassifier(
            n_estimators=1000,
            min_samples_leaf=5,
            n_jobs=1,
            random_state=42,
        )),
        # ("FLAML_600s", mll.FLAMLClassifier(
        #     time_budget=600, metric="roc_auc", n_jobs=1, random_state=42,
        # )),
    ]
 
EVALUATION = mll.Evaluation(
    protocol="repeated_nested_cv",
    outer_folds=5,
    inner_folds=3,
    repeats=2,
    optimize_metric="nMCC",
    random_state=42,
    n_jobs=1,
)
 
GATE = mll.QualificationGate(enabled=False, metric="nMCC", threshold=0.51)
ENSEMBLE = mll.Ensemble(sizes=(3,), optimize_metric="nMCC")
EXPLAINABILITY = mll.Explainability(targets="auto", top_k=30)

Editing the sweep space

The sweep space is controlled by ordinary Python lists. Add or remove configurations by editing, commenting, or uncommenting entries in _RESOLUTION_SETS, _build_count_transformations(), and _build_models(). The run is resumable: completed MPMA/split pairs are preserved, and reruns evaluate newly enabled or missing pairs.

Learners are defined in _build_models() and transformations are defined in _build_count_transformations(). See learners and transformations for scikit-learn models, custom estimators, sample-wise transformations, and fold-fitted transformations.

Data formats

mll.Data(format=...) supports:

Format	Use
`metaphlan_tsv`	Feature/clade rows, sample columns, separate metadata file
`wide_csv`	One row per sample with metadata columns and numeric feature columns in one CSV
`auto`	Selects `metaphlan_tsv` when profile and metadata files are supplied, otherwise `wide_csv`

Compatibility aliases such as matrix_tsv, profile_tsv, and csv are accepted, but new examples should prefer the clearer names above.

Evaluation protocols

Use protocol="repeated_nested_cv" for within-dataset evaluation and protocol="lodo" when DATA defines a group_col for leave-one-dataset-out or leave-one-group-out evaluation.

Repeated nested-CV is stratified by the target label by default. To additionally stratify by metadata, set stratify_col in mll.Data. The splitter uses the composite of target label and the requested metadata column so target balance is preserved while also balancing that metadata stratum when sample counts allow it.


DATA = mll.Data(
    abundance_path=Path("examples/data/example_profiles.tsv"),
    metadata_path=Path("examples/data/example_metadata.tsv"),
    format="metaphlan_tsv",
    sample_id_col="sample_id",
    target_col="label",
    stratify_col="batch",
    label_map={"control": 0, "case": 1},
    class_labels=("control", "case"),
    positive_class=1,
)

For LODO:


DATA = mll.Data(
    abundance_path=Path("examples/data/IBS/IBS_lodo_mllabiome.csv"),
    metadata_path=None,
    format="wide_csv",
    sample_id_col="sample_id",
    target_col="label",
    group_col="study_id",
    label_map={"non-IBS": 0, "IBS": 1},
    class_labels=("non-IBS", "IBS"),
    positive_class=1,
)
 
EVALUATION = mll.Evaluation(protocol="lodo", inner_folds=3, optimize_metric="nMCC")

Explainability targets

Use targets, not the old subject terminology.


EXPLAINABILITY = mll.Explainability(targets="auto", top_k=30)

targets="auto" runs the standard comparison suite: MPMA-E when available, MPMA-B, and the strict Baseline RF when the required baseline exists.