harmonization-tool

Run the harmonize.py CLI with your features .npy and meta.csv, setting --method combat and --batch site. The script validates the IO schema, quantifies site R² before and after, and writes harmonized features plus a manifest.json to the output directory.

Use ComBat-GAM when the cohort age range exceeds 20 years so age effects are modeled non-linearly, plain ComBat otherwise. Choose CovBat for connectome or FC features where covariance structure matters, and site-covariate regression as a quick first pass or LOSO-safe fallback.

Fitting harmonization on the full dataset before splitting leaks site-level information into the test set. The adapters enforce separate fit and transform entry points so harmonization is fit on the training split only, then applied to validation and test data.

ComBat-GAM and CovBat cannot harmonize a site unseen during fit, so leave-site-out produces NaNs with them. Use site-stratified 80/10/10 splits for ComBat-GAM, or the site-covariate method for strict leave-site-out evaluation.

The metadata table must include subject_id, dataset, and site columns, with at least two unique site values. Protected covariates such as age, sex, and dx must also be present if listed in --protected, and the diagnosis column must be protected when it is the prediction target.

Skip harmonization for single-site, single-scanner studies where no batch variable exists. Also avoid it when site and diagnosis are fully confounded, since removing site variance will also remove the diagnosis signal that lives in the site channel.