MicroFactual

Interpretable, sklearn-native counterfactual explanations for microbiome classification.

MicroFactual answers a question most microbiome ML tools can’t: “what minimal change in taxa abundance would flip this sample’s prediction?” It pairs per-sample counterfactual analysis with a clean scikit-learn-compatible surface (Pipeline, GridSearchCV, cross_val_score) over microbiome-aware preprocessing (abundance/prevalence filtering, CLR).

CI

Non-goals: not a replacement for QIIME2’s bioinformatics pipeline, not a feature-engineering toolkit, not a diversity/phylogenetics library.

Pipeline overview

        flowchart LR
    A[Feature table + metadata] -->|MicrobiomeDataset| B(Preprocessing)
    B -->|Abundance / Prevalence / CLR| C[MicrobiomeClassifier]
    C -->|explain_counterfactual| D[Counterfactuals]
    C -->|plots| E[ROC / importance]
    D -->|plausible_range + heatmap| F[Actionable, plausible explanations]

Installation

Install from source (not yet published to PyPI):

# Core install (lean)
pip install -e .

# With the counterfactual explainability stack (DiCE)
pip install -e '.[explainability]'

Quickstart: a counterfactual

import microfactual as mf
from microfactual import AbundanceFilter, PrevalenceFilter, CLRTransform

# 1. Load a real feature table + metadata
ds = mf.MicrobiomeDataset.from_files(
    "abundance.tsv", "metadata.tsv",
    target_column="Group", sample_column="Sample ID",
)

# 2. Preprocess into CLR space (real taxon names are preserved end-to-end)
X = CLRTransform().fit_transform(
    PrevalenceFilter(min_prevalence=0.1).fit_transform(
        AbundanceFilter(min_abundance=1e-5).fit_transform(ds.X)))
y = ds.y

# 3. Fit an sklearn-compatible classifier in that space
model = mf.MicrobiomeClassifier(preprocessing=None).fit(X, y)

# 4. What minimal change flips this sample's prediction?
cf = mf.explain_counterfactual(
    model, X.iloc[[0]], background_data=X, y=y,
    class_names=list(ds.target_names),
)
print(cf.summary())
cf.changes(0)   # taxon, original -> counterfactual, delta, direction

See the Counterfactual Explanations guide for plausibility bounds, cohort-level importance, and the class-reference heatmap, and Preprocessing: choosing filters and transforms for how to choose the filtering and transform defaults.

Contents

Guides

Reference