Harmonization of diffusion MRI datasets with adaptive dictionary learning
For details on the algorithm, you can check out the published version
St-Jean S, Viergever MA, Leemans A. Harmonization of diffusion MRI data sets with adaptive dictionary learning. Hum Brain Mapp. 2020; 41: 4478–4499. https://doi.org/10.1002/hbm.25117
The manuscript detailing the original harmonization challenge which lead to this algorithm is also available from the publisher here.
Tax, C. M. W., Grussu, F., Kaden, E., Ning, L., Rudrapatna, U., John Evans, C., St-Jean, S., Leemans, A., Koppers, S., Merhof, D., Ghosh, A., Tanno, R., Alexander, D. C., Zappalà, S., Charron, C., Kusmia, S., Linden, D. EJ., Jones, D. K., & Veraart, J. (2019). Cross-scanner and cross-protocol diffusion MRI data harmonisation: A benchmark database and evaluation of algorithms. NeuroImage, 195, 285–299. https://doi.org/10.1016/j.neuroimage.2019.01.077
How to install
To install a precompiled version, simply run pip install dmri-harmonization.
Normally everything is available pre-compiled, but feel free to redo it from source on your computer cluster for example.
There is a basic documentation available at https://samuelstjean.github.io/harmonization
A step by step example
There are two main scripts to use, one to build the database and one to harmonize the datasets afterwards.
You will most likely want you data to be organized sensibly and have the same filename for every diffusion dataset under various subjects folders, just like in the example that can be found under the tests folder.
This looks like this and is the format used by the BIDS standard and the HCP datasets. You do not need to follow this exactly, you just need to ensure that the filenames are somewhat consistent since everything is found internally by pattern matching and substitutions.
datasets/
├── subj1
│ ├── dwi_brain_mask.nii.gz
│ ├── dwi.bvals
│ ├── dwi.bvecs
│ └── dwi.nii.gz
├── subj2
│ ├── dwi_brain_mask.nii.gz
│ ├── dwi.bvals
│ ├── dwi.bvecs
│ └── dwi.nii.gz
datasets_bids/
├── subj1-bids
│ └── dwi
│ ├── subj1-dwi_brain_mask.nii.gz
│ ├── subj1-dwi.bvals
│ ├── subj1-dwi.bvecs
│ └── subj1-dwi.nii.gz
└── subj2-bids
└── dwi
├── subj2-dwi_brain_mask.nii.gz
├── subj2-dwi.bvals
├── subj2-dwi.bvecs
└── subj2-dwi.nii.gz
Step 1
First write a config file like this
harmonization_get_global_D write myconfig.yaml
Open up this myconfig.yaml file and change a couple of options, namely the paths at the top to point to your datasets folder.
You can look up the example I mentioned above for a working example, but this should get you going. There are a couple more options to play with, but the default should be sane. I'd recommend looking at the numbers of cores option at the end however if you share a compute server with other people.
Step 2
Once you have your config file set up, run the command (note how there is no write keyword anymore)
harmonization_get_global_D myconfig.yaml
Everything will be read from myconfig.yaml, including the input and output folder.
You'll see that all your datasets will be loaded in before processing, so you can double check the paths were set up correctly (particularly the glob option if you use BIDS with different filenames).
Step 3
After running step 2, you now have an output dictionary file. Now run the command
harmonization_harmonize_my_data myconfig.yaml
Sit back and relax, and you should have your harmonized datasets in the folder you specified. Remember you can also specify the same input and output folder to have the data side by side.
There are a few safeguards to not shoot yourself in the foot, like not overwriting datasets by default.
On subsequent runs, be sure to change the output dictionary filename as it sets the logic for the output filenames or set the overwrite option to True in the config file if desired.
1 maintainer
Metadata
1 maintainer
Release files for dmri-harmonization 0.2.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| dmri_harmonization-0.2.1.tar.gz | 724.7 kB | Details |
Built distributions (wheels)
Total release size: 30.1 MB
Release files / dmri_harmonization-0.2.1.tar.gz
| Download URL | dmri_harmonization-0.2.1.tar.gz |
|---|---|
| Size | 724.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
643eca04d564c1b753e62a0ae9d6c93fd3043d7b0b2d44d165d43d43af258cd8
|
|
BLAKE2b-256 checksum How to use checksums |
6649d1a5462df98d805e4c13c5661361b505a30229e54fdc028983161fd383e4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 17, 2026.
Transparency logRelease files / dmri_harmonization-0.2.1-cp315-cp315-win_amd64.whl
| Download URL | dmri_harmonization-0.2.1-cp315-cp315-win_amd64.whl |
|---|---|
| Size | 2.3 MB |
| Tags | CPython 3.15 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
c99c7def4491bef5cc376797e2b4d6d2cd11cfa951399157c023dfe4626eada5
|
|
BLAKE2b-256 checksum How to use checksums |
7232a0f66eaba97e0fca9b09a430b35e0beafefc8a9ffc1f1349e2adcc2a216d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 17, 2026.
Transparency logRelease files / dmri_harmonization-0.2.1-cp315-cp315-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
| Download URL | dmri_harmonization-0.2.1-cp315-cp315-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 1.9 MB |
| Tags | CPython 3.15 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
70e3b49ee9b000ef40d6e7abcf3b2ad0e2f2ae6a6caf7294b3db3f9578d19e6e
|
|
BLAKE2b-256 checksum How to use checksums |
51e059eb64dc804626d72f3bfc9d18d3c838463c61177864f847b453e827402d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 17, 2026.
Transparency logRelease files / dmri_harmonization-0.2.1-cp315-cp315-macosx_15_0_arm64.whl
| Download URL | dmri_harmonization-0.2.1-cp315-cp315-macosx_15_0_arm64.whl |
|---|---|
| Size | 1.7 MB |
| Tags | CPython 3.15 macOS 15.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
e5222faf95dd7aa61812e9cfae41db321f2579517f0be455d30b11f670683980
|
|
BLAKE2b-256 checksum How to use checksums |
a368d3750a45f89cb4ee392177f1168aaa2918c9307f36eb15eb84dfc8164897
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 17, 2026.
Transparency logRelease files / dmri_harmonization-0.2.1-cp314-cp314-win_amd64.whl
| Download URL | dmri_harmonization-0.2.1-cp314-cp314-win_amd64.whl |
|---|---|
| Size | 2.3 MB |
| Tags | CPython 3.14 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
a27ea907f1fbf6f3335c8ee25cfd6ed9316b6c8309ce6654e64336f857be8ad9
|
|
BLAKE2b-256 checksum How to use checksums |
ebe336eb2a1c7ecf413db17534f2257a9e2d2161107305676bd886cc7e7cc2dc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 17, 2026.
Transparency logRelease files / dmri_harmonization-0.2.1-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
| Download URL | dmri_harmonization-0.2.1-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 1.9 MB |
| Tags | CPython 3.14 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
1e7aa2e482f3f6fdad7f9ffc9643b1e6bd157ee84d053277e66296867b9ab238
|
|
BLAKE2b-256 checksum How to use checksums |
76db60f9c6995150d05f72d45f4301f623450e91092d05c13284b927afe8894c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 17, 2026.
Transparency logRelease files / dmri_harmonization-0.2.1-cp314-cp314-macosx_15_0_arm64.whl
| Download URL | dmri_harmonization-0.2.1-cp314-cp314-macosx_15_0_arm64.whl |
|---|---|
| Size | 1.7 MB |
| Tags | CPython 3.14 macOS 15.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
1728709c0394da031ae082e3c6ea92e4e4360f1cba92546dee8c26f575e8659e
|
|
BLAKE2b-256 checksum How to use checksums |
132ad769dd6ad3c30cd0e4d088bfecc472b07b3a57cdb84f39b57b207beda983
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 17, 2026.
Transparency logRelease files / dmri_harmonization-0.2.1-cp313-cp313-win_amd64.whl
| Download URL | dmri_harmonization-0.2.1-cp313-cp313-win_amd64.whl |
|---|---|
| Size | 2.3 MB |
| Tags | CPython 3.13 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
29869bc6a5745d9a134634bfa44ef915a113d7622acfcafa5e68f8340aa95434
|
|
BLAKE2b-256 checksum How to use checksums |
76229752ae01ec6cf5bd7e429dcd7406c300223bef6b1d82772145aa570b079e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 17, 2026.
Transparency logRelease files / dmri_harmonization-0.2.1-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
| Download URL | dmri_harmonization-0.2.1-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 1.9 MB |
| Tags | CPython 3.13 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
f0d6bad0e2c90a68609ad8bcdb49c660f28d324e97668c7a9e0d7f6c74fb2ba2
|
|
BLAKE2b-256 checksum How to use checksums |
d000ffb442f89d1ed3e84d31cdcf2920a3bdee40ac8477befff371c035af2776
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 17, 2026.
Transparency logRelease files / dmri_harmonization-0.2.1-cp313-cp313-macosx_15_0_arm64.whl
| Download URL | dmri_harmonization-0.2.1-cp313-cp313-macosx_15_0_arm64.whl |
|---|---|
| Size | 1.7 MB |
| Tags | CPython 3.13 macOS 15.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
77bdf5d43307439090c478657a97dc2c0b71a87922feb6a69ba9df2af31b2643
|
|
BLAKE2b-256 checksum How to use checksums |
c300944bad88aeb38f3efe4addffa6766454bff4283e6bad7779b52e2b3d27ac
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 17, 2026.
Transparency logRelease files / dmri_harmonization-0.2.1-cp312-cp312-win_amd64.whl
| Download URL | dmri_harmonization-0.2.1-cp312-cp312-win_amd64.whl |
|---|---|
| Size | 2.3 MB |
| Tags | CPython 3.12 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
06792f4354f905d11ff2c61df047a212b12434fd6ac6018725a9d0797a7ef67c
|
|
BLAKE2b-256 checksum How to use checksums |
98b4142d6add99cbcd5d2263934aa1e409187d5c2a728d185b455f97fcf56c03
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 17, 2026.
Transparency logRelease files / dmri_harmonization-0.2.1-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
| Download URL | dmri_harmonization-0.2.1-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 1.9 MB |
| Tags | CPython 3.12 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
0686c681de92184466d292e7faac8dcde992cb88de71e626da53485de4f36f02
|
|
BLAKE2b-256 checksum How to use checksums |
6fac2ec7571d4fe960f522596422663e7e416ae43ddc7982cc797e288fae3950
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 17, 2026.
Transparency logRelease files / dmri_harmonization-0.2.1-cp312-cp312-macosx_15_0_arm64.whl
| Download URL | dmri_harmonization-0.2.1-cp312-cp312-macosx_15_0_arm64.whl |
|---|---|
| Size | 1.7 MB |
| Tags | CPython 3.12 macOS 15.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
e22c4fec9d7eba8c2c1dd173515caed5d209f67bf4875a2e6e7d23b6fb62d5d9
|
|
BLAKE2b-256 checksum How to use checksums |
cd6fdf28aae4bed9304b8adf4868303d674099835ce62c0c258a62c20ca334d4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 17, 2026.
Transparency logRelease files / dmri_harmonization-0.2.1-cp311-cp311-win_amd64.whl
| Download URL | dmri_harmonization-0.2.1-cp311-cp311-win_amd64.whl |
|---|---|
| Size | 2.3 MB |
| Tags | CPython 3.11 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
5afd9ed043db10b504267d6f1a8b6d7233d4ca418e3488c7ddf82c22e78ecb25
|
|
BLAKE2b-256 checksum How to use checksums |
a0bd7630b4a9c8efa3b05ceb0c7800fd818223a7f7e346eb5de92d20e8bc8232
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 17, 2026.
Transparency logRelease files / dmri_harmonization-0.2.1-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
| Download URL | dmri_harmonization-0.2.1-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 1.9 MB |
| Tags | CPython 3.11 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
6c174c5741933dc318062a48300975053ddfb858c36c3a709775ed21d3e32d4a
|
|
BLAKE2b-256 checksum How to use checksums |
65cc514b0c3dcdaa64668e4f09d8a799562517ad93ae6e865449a89f919b77e3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 17, 2026.
Transparency logRelease files / dmri_harmonization-0.2.1-cp311-cp311-macosx_15_0_arm64.whl
| Download URL | dmri_harmonization-0.2.1-cp311-cp311-macosx_15_0_arm64.whl |
|---|---|
| Size | 1.7 MB |
| Tags | CPython 3.11 macOS 15.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
1836562d374744b5e4fb98c55edd57227e702d66e14245c842030d940fc9bc64
|
|
BLAKE2b-256 checksum How to use checksums |
56986863d1109dcb47d7bab7807833d4ea0115b2d6075edab889e3640256a83a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 17, 2026.
Transparency log
