Diagnose Harmonisation (DHARM): An open-source tool for the harmonisation and analysis of batch effects in MRI-derived measures.

Abstract

Technical differences between scanners, acquisition protocols, machine hardware and processing pipelines can introduce systematic variation into MRI-derived measures. Numerous harmonisation methods have been developed to reduce these effects. However, validation of these methods is often performed using different criteria depending on the method itself, the datasets used and the study design. Consequently, determining whether harmonisation is required, selecting an appropriate method and establishing whether or not technical variation has been sufficiently removed without compromising biological signal remain challenging. In this manuscript, we introduce Diagnose Harmonisation (DHARM), an open-source Python toolbox for diagnosing batch effects, applying harmonisation and evaluating harmonisation performance in cross-sectional and repeated-measures settings. DHARM is user-friendly, comes with GUI-based and command-line interfaces, and has graphical reporting. It provides standardised reporting workflows combining complementary measures of batch-associated differences in feature location, scale, empirical distributions, covariance and multivariate structure, together with measures assessing preservation of biological covariate effects and repeated-measures consistency. The framework includes several established harmonisation approaches, but its evaluation workflow is method-agnostic: users can also supply data harmonised using external or newly developed methods and benchmark their outputs using the same common set of diagnostics. We demonstrate DHARM using multisite cross-sectional MRI measures from UK Biobank, Cam-CAN and OxBAC as well as travelling-heads data from the ON-Harmony dataset. Across the cross-sectional datasets, harmonisation substantially reduced additive batch effects, while residual differences in variance and empirical distributions varied between methods. Multivariate diagnostics further demonstrated that reduction of batch-associated structure can coexist with preservation or increased detectability of biologically relevant variation. In the repeated-measures example, harmonisation reduced batch-associated and within-subject variability, while broadly preserving subject-level and biological relationships. DHARM provides a reproducible framework for diagnosing batch effects, applying different harmonisation methods and evaluating harmonisation as a multi-criteria problem rather than relying on a single measure of success. By jointly characterising technical variation and preservation of biologically meaningful information, DHARM can support dataset- and objective-specific selection, benchmarking and validation of harmonisation strategies.