combatlearn 0.1.0

Batch-effect harmonisation for machine learning frameworks.

combatlearn

combatlearn makes the popular ComBat (and CovBat) batch-effect correction algorithm available for use into machine learning frameworks. It lets you harmonise high-dimensional data inside a scikit-learn Pipeline, so that cross-validation and grid-search automatically take batch structure into account, without data leakage.

Three methods:

• method="johnson" - classic ComBat (Johnson et al., 2007)
• method="fortin" - covariate-aware ComBat (Fortin et al., 2018)
• method="chen" - CovBat (Chen et al., 2022)

Installation

pip install combatlearn

Quick start

import pandas as pd
from sklearn.pipeline import Pipeline
from sklearn.preprocessing import StandardScaler
from sklearn.linear_model import LogisticRegression
from combatlearn import ComBat

df = pd.read_csv("data.csv", index_col=0)
X, y = df.drop(columns="y"), df["y"]

batch = pd.read_csv("batch.csv", index_col=0, squeeze=True)
diag = pd.read_csv("diagnosis.csv", index_col=0) # categorical
age = pd.read_csv("age.csv", index_col=0) # continuous

pipe = Pipeline([
    ("combat", ComBat(
        batch=batch,
        discrete_covariates=diag,
        continuous_covariates=age,
        method="fortin", # or "johnson" or "chen"
        parametric=True
    )),
    ("scaler", StandardScaler()),
    ("clf", LogisticRegression())
])

param_grid = {
    "combat__mean_only": [True, False],
    "clf__C": [0.01, 0.1, 1, 10],
}

grid = GridSearchCV(
    estimator=pipe,
    param_grid=param_grid,
    cv=5,
    scoring="roc_auc",
)

grid.fit(X, y)

print("Best parameters:", grid.best_params_)
print(f"Best CV AUROC: {grid.best_score_:.3f}")

For a full example of how to use combatlearn see the notebook demo

Contributing

Pull requests, bug reports, and feature ideas are welcome: feel free to open a PR!

Acknowledgements

This project builds on the excellent work of the ComBat family of harmonisation methods. We gratefully acknowledge:

• ComBat
• neuroCombat
• CovBat

Citation

If combatlearn is useful in your research, please cite the original papers:

• Johnson WE, Li C, Rabinovic A. Adjusting batch effects in microarray expression data using empirical Bayes methods. Biostatistics. 2007 Jan;8(1):118-27. doi: 10.1093/biostatistics/kxj037

• Fortin JP, Cullen N, Sheline YI, Taylor WD, Aselcioglu I, Cook PA, Adams P, Cooper C, Fava M, McGrath PJ, McInnis M, Phillips ML, Trivedi MH, Weissman MM, Shinohara RT. Harmonization of cortical thickness measurements across scanners and sites. Neuroimage. 2018 Feb 15;167:104-120. doi: 10.1016/j.neuroimage.2017.11.024

• Chen AA, Beer JC, Tustison NJ, Cook PA, Shinohara RT, Shou H; Alzheimer's Disease Neuroimaging Initiative. Mitigating site effects in covariance for machine learning in neuroimaging data. Hum Brain Mapp. 2022 Mar;43(4):1179-1195. doi: 10.1002/hbm.25688