# Gray Matter Microstructure models estimator for diffusion MRI
[](https://pypi.org/project/graymatter_swissknife)
[](#)
[](#)
[](#)
[](https://pypi.org/project/graymatter_swissknife)
[](https://github.com/psf/black)
-----
<div align="center">
<img src="images/gm_swissknife_square_low_res.png" alt="GM SK logo" width="300" role="img">
</div>
**Table of Contents**
- [Installation](#installation)
- [Usage](#usage)
- [Prerequisites](#prerequisites)
- [Citation](#citation)
- [License](#license)
## Installation
```console
pip install numpy nibabel tqdm joblib scipy xgboost scikit-learn matplotlib
pip install graymatter_swissknife
```
## Usage
### Estimate Gray Matter microstructure model parameters
To estimate any gray matter model parameters with Nonlinear Least Squares using the graymatter_swissknife package, you can use the estimate_model function. This function takes several parameters that you need to provide in order to perform the estimation accurately.
```
from graymatter_swissknife import estimate_model
estimate_model(model_name, dwi_path, bvals_path, delta_path, small_delta, lowb_noisemap_path, out_path)
```
`model_name`: Choose your gray matter model between `'Nexi'` (or `'Nexi_Narrow_Pulses_Approximation'`), `'Smex'` (or `'Nexi_Wide_Pulses'`), `'Sandi'`, `'Sandix'` and `'Gem'`.
`dwi_path`: The path to the diffusion-weighted image (DWI) data in NIfTI format. This data contains the preprocessed diffusion-weighted volumes acquired from your imaging study.
`bvals_path`: The path to the file containing the b-value of each volume in the DWI data, in ms/µm². B-values specify the strength and timing of diffusion sensitization gradients for each volume in the DWI data.
`delta_path`: The path to the file containing the Δ of each volume in the DWI data, in ms. Δ is the time at the beginning of the second gradient pulse in the PGSE sequence.
`small_delta` (float): The value of δ in your protocol, in ms. δ is the duration of a gradient pulse. A future update will allow multiple δ in the protocol.
`lowb_noisemap_path`: The path to the noisemap calculated using only the small b-values (b < 2 ms/µm²) and Marchenko-Pastur principal component analysis (MP-PCA) denoising. This noisemap is used to calculate the signal-to-noise ratio (SNR) of the data. To get your estimates without noise correction, e.g. if you don't have any noisemap, use the function `estimate_model_noiseless` instead (Not recommended).
`out_path`: The folder where the estimated parameters will be saved as output.
**Additional options:**
`mask_path` (**Recommended**): The mask path, if the analysis concerns a specific portion of the DWI images. The mask can be in 3 dimensions, or must be able to be squeezed in only 3 dimensions.
`fixed_parameters` (Optional): Allows to fix some parameters of the model if not set to None. Tuple of fixed parameters for the model. The tuple must have the same length as the number of parameters of the model (with or without noise correction). Example of use: Fix Di to 2.0µm²/ms and De to 1.0µm²/ms in the NEXI model by specifying fixed_parameters=(None, 2.0 , 1.0, None)
`adjust_parameter_limits` (Optional): Allows to redefine some parameter limits of the model if not set to None. Tuple of adjusted parameter limits for the model. The tuple must have the same length as the number of parameters of the model (with or without noise correction). This will have no effect on the fixed parameters (if set in fixed_parameters). Example of use: Fix Di limits to (1.5-2.5)µm²/ms and De to (0.5-1.5)µm²/ms in the NEXI model by specifying fixed_parameters=(None, (1.5, 2.5) , (0.5, 1.5), None)
`n_cores`: Number of cores to use for the parallelization. If -1, all available cores are used. The default is -1.
`debug`: Debug mode. The default is False.
### Fast XGBoost Estimation (Artificial Intelligence)
The Non-Linear Least Squares method is preferred for the most accurate estimates. However, this method takes a long time to fit. For the analysis of extensive cohorts, we propose employing an XGBoost model to learn the microstructure model on the given parameter limits, then applying this trained XGBoost model to the entire cohort. For example, employing this approach enables the execution of a NEXI analysis on an entire cohort within a timeframe of less than **10 minutes**, provided that the scan parameters remain consistent across the cohort. To achieve this, we use the following arguments:
`optimization_method`: To use XGBoost, set this setting to `'xgboost'`. The default is `'nls'`.
`xgboost_model_path`: If the model is not yet trained, this setting indicates where the model and its weights will be saved. It must end with a `'.json'` extension. If the model is already trained, then this setting must indicate where it is saved. The default is None. If `optimization_method` is set to `'xgboost'`, this setting will be required.
`retrain_xgboost` (Optional): Boolean to indicate if you wish to overwrite the model already trained and saved at the address indicated in xgboost_model_path. The default and recommended setting is False. The safest way is to delete the saved file yourself.
`force_cpu` (Optional): Boolean option to be used only if your training has failed for lack of space on your GPU.
### Gray Matter microstructure models description from the Generalized Exchange Model
## Prerequisites
### Data Acquisition
For accurate parameter estimation using the graymatter_swissknife package, acquire PGSE EPI (Pulsed Gradient Spin Echo Echo-Planar Imaging) diffusion MRI data with diverse combinations of b values and diffusion times. Ensure reasonable signal-to-noise ratio (SNR) in the data for accurate parameter estimation.
### Preprocessing
Before proceeding, make sure to preprocess your data with the following steps:
- Marchenko-Pastur principal component analysis (MP-PCA) denoising ([Veraart et al., 2016](https://doi.org/10.1016/j.neuroimage.2016.08.016)). Recommended algorithm : [dwidenoise from mrtrix](https://mrtrix.readthedocs.io/en/dev/reference/commands/dwidenoise.html)
- Gibbs ringing correction ([Kellner et al., 2016](https://doi.org/10.1002/mrm.26054)). Recommended algorithm : [FSL implementation](https://bitbucket.org/reisert/unring/src/master/)
- Distortion correction using FSL topup ([Andersson et al., 2003](https://doi.org/10.1002/mrm.10335), [Andersson et al., 2016](https://doi.org/10.1016/j.neuroimage.2015.10.019)). Recommended algorithm : [FSL topup](https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/topup)
- Eddy current and motion correction ([Andersson and Sotiropoulos, 2016](https://doi.org/10.1016/j.neuroimage.2015.12.037)). Recommended algorithm : [FSL eddy](https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/eddy)
Additionally, you need to compute another noisemap using only the small b-values (b < 2 ms/µm²) and MP-PCA. This noisemap will be used to calculate the signal-to-noise ratio (SNR) of the data.
Furthermore, you can provide a mask of grey matter tissue if available. This mask can be used to restrict the processing to specific regions of interest. If a mask is not provided, the algorithms will be applied to the entire image, voxel by voxel, as long as there are no NaN values present.
To compute a grey matter mask, one common approach involves using a T1 image, [FastSurfer](https://deep-mi.org/research/fastsurfer/), and performing registration to the diffusion (b = 0 ms/µm²) space. However, you can choose any other method to compute a grey matter mask.
## Citation
If you use this package in your research, please consider citing the following papers:
### Development of this package
Quentin Uhl, Tommaso Pavan, Thorsten Feiweier, Gian Franco Piredda, Sune N. Jespersen and Ileana Jelescu, [NEXI for the quantification of human gray matter microstructure on a clinical MRI scanner](https://www.ismrm.org/24m/), Proc. Intl. Soc. Mag. Reson. Med. 2024.
Presented at the Annual Meeting of the ISMRM, Singapore, Singapore, p. 0937.
### Generalized Exchange Model ($GEM$) / Development of this package
Quentin Uhl, Tommaso Pavan, Inès de Riedmatten, Jasmine Nguyen-Duc, and Ileana Jelescu, [GEM: a unifying model for Gray Matter microstructure](https://www.ismrm.org/24m/), Proc. Intl. Soc. Mag. Reson. Med. 2024.
Presented at the Annual Meeting of the ISMRM, Singapore, Singapore, p. 7970.
## Other original gray matter model papers
### Neurite Exchange Imaging ($NEXI$, or $NEXI_{Narrow Pulse Approximation}$)
Ileana O. Jelescu, Alexandre de Skowronski, Françoise Geffroy, Marco Palombo, Dmitry S. Novikov, [Neurite Exchange Imaging (NEXI): A minimal model of diffusion in gray matter with inter-compartment water exchange](https://www.sciencedirect.com/science/article/pii/S1053811922003986), NeuroImage, 2022.
Quentin Uhl, Tommaso Pavan, Malwina Molendowska, Derek K. Jones, Marco Palombo, Ileana Jelescu, [Quantifying human gray matter microstructure using Neurite Exchange Imaging (NEXI) and 300 mT/m gradients](https://direct.mit.edu/imag/article/doi/10.1162/imag_a_00104/119673/Quantifying-human-gray-matter-microstructure-using), Imaging Neuroscience, 2024
### Standard Model with Exchange ($SMEX$, or $NEXI_{Wide Pulses}$)
Jonas L. Olesen, Leif Østergaard, Noam Shemesh, Sune N. Jespersen, [Diffusion time dependence, power-law scaling, and exchange in gray matter](https://doi.org/10.1016/j.neuroimage.2022.118976), NeuroImage, 2022.
### Soma And Neurite Density Imaging ($SANDI$)
Marco Palombo, Andrada Ianus, Michele Guerreri, Daniel Nunes, Daniel C. Alexander, Noam Shemesh, Hui Zhang, [SANDI: A compartment-based model for non-invasive apparent soma and neurite imaging by diffusion MRI](https://doi.org/10.1016/j.neuroimage.2020.116835), NeuroImage, 2020.
### Soma And Neurite Density Imaging with eXchange ($SANDIX$)
Jonas L. Olesen, Leif Østergaard, Noam Shemesh, Sune N. Jespersen, [Diffusion time dependence, power-law scaling, and exchange in gray matter](https://doi.org/10.1016/j.neuroimage.2022.118976), NeuroImage, 2022.
## License
`graymatter_swissknife` is distributed under the terms of the [Apache License 2.0](https://spdx.org/licenses/Apache-2.0.html).
Raw data
{
"_id": null,
"home_page": null,
"name": "graymatter_swissknife",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "diffusion, dmri, grey matter, microstructure, model, mri",
"author": null,
"author_email": "Quentin Uhl <quentin.uhl@gmail.com>, \"Ileana O. Jelescu\" <ileana.jelescu@chuv.ch>",
"download_url": "https://files.pythonhosted.org/packages/00/63/87c0240692c06b74648ed1f0b493debe46f98b4e4e1fe331a3c746dee7da/graymatter_swissknife-1.3.6.tar.gz",
"platform": null,
"description": "# Gray Matter Microstructure models estimator for diffusion MRI\n\n[](https://pypi.org/project/graymatter_swissknife)\n[](#)\n[](#)\n[](#)\n[](https://pypi.org/project/graymatter_swissknife)\n[](https://github.com/psf/black)\n\n-----\n\n<div align=\"center\">\n<img src=\"images/gm_swissknife_square_low_res.png\" alt=\"GM SK logo\" width=\"300\" role=\"img\">\n</div>\n\n\n**Table of Contents**\n\n- [Installation](#installation)\n- [Usage](#usage)\n- [Prerequisites](#prerequisites)\n- [Citation](#citation)\n- [License](#license)\n\n\n## Installation\n\n```console\npip install numpy nibabel tqdm joblib scipy xgboost scikit-learn matplotlib\npip install graymatter_swissknife\n```\n\n## Usage\n\n### Estimate Gray Matter microstructure model parameters\n\nTo estimate any gray matter model parameters with Nonlinear Least Squares using the graymatter_swissknife package, you can use the estimate_model function. This function takes several parameters that you need to provide in order to perform the estimation accurately.\n\n```\nfrom graymatter_swissknife import estimate_model\nestimate_model(model_name, dwi_path, bvals_path, delta_path, small_delta, lowb_noisemap_path, out_path)\n```\n\n`model_name`: Choose your gray matter model between `'Nexi'` (or `'Nexi_Narrow_Pulses_Approximation'`), `'Smex'` (or `'Nexi_Wide_Pulses'`), `'Sandi'`, `'Sandix'` and `'Gem'`.\n\n`dwi_path`: The path to the diffusion-weighted image (DWI) data in NIfTI format. This data contains the preprocessed diffusion-weighted volumes acquired from your imaging study.\n\n`bvals_path`: The path to the file containing the b-value of each volume in the DWI data, in ms/\u00b5m\u00b2. B-values specify the strength and timing of diffusion sensitization gradients for each volume in the DWI data.\n\n`delta_path`: The path to the file containing the \u0394 of each volume in the DWI data, in ms. \u0394 is the time at the beginning of the second gradient pulse in the PGSE sequence.\n\n`small_delta` (float): The value of \u03b4 in your protocol, in ms. \u03b4 is the duration of a gradient pulse. A future update will allow multiple \u03b4 in the protocol.\n\n`lowb_noisemap_path`: The path to the noisemap calculated using only the small b-values (b < 2 ms/\u00b5m\u00b2) and Marchenko-Pastur principal component analysis (MP-PCA) denoising. This noisemap is used to calculate the signal-to-noise ratio (SNR) of the data. To get your estimates without noise correction, e.g. if you don't have any noisemap, use the function `estimate_model_noiseless` instead (Not recommended).\n\n`out_path`: The folder where the estimated parameters will be saved as output.\n\n**Additional options:**\n\n`mask_path` (**Recommended**): The mask path, if the analysis concerns a specific portion of the DWI images. The mask can be in 3 dimensions, or must be able to be squeezed in only 3 dimensions.\n\n`fixed_parameters` (Optional): Allows to fix some parameters of the model if not set to None. Tuple of fixed parameters for the model. The tuple must have the same length as the number of parameters of the model (with or without noise correction). Example of use: Fix Di to 2.0\u00b5m\u00b2/ms and De to 1.0\u00b5m\u00b2/ms in the NEXI model by specifying fixed_parameters=(None, 2.0 , 1.0, None)\n\n`adjust_parameter_limits` (Optional): Allows to redefine some parameter limits of the model if not set to None. Tuple of adjusted parameter limits for the model. The tuple must have the same length as the number of parameters of the model (with or without noise correction). This will have no effect on the fixed parameters (if set in fixed_parameters). Example of use: Fix Di limits to (1.5-2.5)\u00b5m\u00b2/ms and De to (0.5-1.5)\u00b5m\u00b2/ms in the NEXI model by specifying fixed_parameters=(None, (1.5, 2.5) , (0.5, 1.5), None)\n\n`n_cores`: Number of cores to use for the parallelization. If -1, all available cores are used. The default is -1.\n\n`debug`: Debug mode. The default is False.\n\n### Fast XGBoost Estimation (Artificial Intelligence)\n\nThe Non-Linear Least Squares method is preferred for the most accurate estimates. However, this method takes a long time to fit. For the analysis of extensive cohorts, we propose employing an XGBoost model to learn the microstructure model on the given parameter limits, then applying this trained XGBoost model to the entire cohort. For example, employing this approach enables the execution of a NEXI analysis on an entire cohort within a timeframe of less than **10 minutes**, provided that the scan parameters remain consistent across the cohort. To achieve this, we use the following arguments:\n\n`optimization_method`: To use XGBoost, set this setting to `'xgboost'`. The default is `'nls'`.\n\n`xgboost_model_path`: If the model is not yet trained, this setting indicates where the model and its weights will be saved. It must end with a `'.json'` extension. If the model is already trained, then this setting must indicate where it is saved. The default is None. If `optimization_method` is set to `'xgboost'`, this setting will be required.\n\n`retrain_xgboost` (Optional): Boolean to indicate if you wish to overwrite the model already trained and saved at the address indicated in xgboost_model_path. The default and recommended setting is False. The safest way is to delete the saved file yourself.\n\n`force_cpu` (Optional): Boolean option to be used only if your training has failed for lack of space on your GPU.\n\n### Gray Matter microstructure models description from the Generalized Exchange Model\n\n\n\n## Prerequisites\n\n### Data Acquisition\n\nFor accurate parameter estimation using the graymatter_swissknife package, acquire PGSE EPI (Pulsed Gradient Spin Echo Echo-Planar Imaging) diffusion MRI data with diverse combinations of b values and diffusion times. Ensure reasonable signal-to-noise ratio (SNR) in the data for accurate parameter estimation.\n\n### Preprocessing\n\nBefore proceeding, make sure to preprocess your data with the following steps:\n- Marchenko-Pastur principal component analysis (MP-PCA) denoising ([Veraart et al., 2016](https://doi.org/10.1016/j.neuroimage.2016.08.016)). Recommended algorithm : [dwidenoise from mrtrix](https://mrtrix.readthedocs.io/en/dev/reference/commands/dwidenoise.html)\n- Gibbs ringing correction ([Kellner et al., 2016](https://doi.org/10.1002/mrm.26054)). Recommended algorithm : [FSL implementation](https://bitbucket.org/reisert/unring/src/master/)\n- Distortion correction using FSL topup ([Andersson et al., 2003](https://doi.org/10.1002/mrm.10335), [Andersson et al., 2016](https://doi.org/10.1016/j.neuroimage.2015.10.019)). Recommended algorithm : [FSL topup](https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/topup)\n- Eddy current and motion correction ([Andersson and Sotiropoulos, 2016](https://doi.org/10.1016/j.neuroimage.2015.12.037)). Recommended algorithm : [FSL eddy](https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/eddy)\n\nAdditionally, you need to compute another noisemap using only the small b-values (b < 2 ms/\u00b5m\u00b2) and MP-PCA. This noisemap will be used to calculate the signal-to-noise ratio (SNR) of the data.\n\nFurthermore, you can provide a mask of grey matter tissue if available. This mask can be used to restrict the processing to specific regions of interest. If a mask is not provided, the algorithms will be applied to the entire image, voxel by voxel, as long as there are no NaN values present.\n\nTo compute a grey matter mask, one common approach involves using a T1 image, [FastSurfer](https://deep-mi.org/research/fastsurfer/), and performing registration to the diffusion (b = 0 ms/\u00b5m\u00b2) space. However, you can choose any other method to compute a grey matter mask.\n\n## Citation\n\nIf you use this package in your research, please consider citing the following papers:\n\n### Development of this package\nQuentin Uhl, Tommaso Pavan, Thorsten Feiweier, Gian Franco Piredda, Sune N. Jespersen and Ileana Jelescu, [NEXI for the quantification of human gray matter microstructure on a clinical MRI scanner](https://www.ismrm.org/24m/), Proc. Intl. Soc. Mag. Reson. Med. 2024. \nPresented at the Annual Meeting of the ISMRM, Singapore, Singapore, p. 0937.\n\n### Generalized Exchange Model ($GEM$) / Development of this package\nQuentin Uhl, Tommaso Pavan, In\u00e8s de Riedmatten, Jasmine Nguyen-Duc, and Ileana Jelescu, [GEM: a unifying model for Gray Matter microstructure](https://www.ismrm.org/24m/), Proc. Intl. Soc. Mag. Reson. Med. 2024. \nPresented at the Annual Meeting of the ISMRM, Singapore, Singapore, p. 7970.\n\n## Other original gray matter model papers\n\n### Neurite Exchange Imaging ($NEXI$, or $NEXI_{Narrow Pulse Approximation}$)\nIleana O. Jelescu, Alexandre de Skowronski, Fran\u00e7oise Geffroy, Marco Palombo, Dmitry S. Novikov, [Neurite Exchange Imaging (NEXI): A minimal model of diffusion in gray matter with inter-compartment water exchange](https://www.sciencedirect.com/science/article/pii/S1053811922003986), NeuroImage, 2022.\n\nQuentin Uhl, Tommaso Pavan, Malwina Molendowska, Derek K. Jones, Marco Palombo, Ileana Jelescu, [Quantifying human gray matter microstructure using Neurite Exchange Imaging (NEXI) and 300 mT/m gradients](https://direct.mit.edu/imag/article/doi/10.1162/imag_a_00104/119673/Quantifying-human-gray-matter-microstructure-using), Imaging Neuroscience, 2024\n\n### Standard Model with Exchange ($SMEX$, or $NEXI_{Wide Pulses}$)\nJonas L. Olesen, Leif \u00d8stergaard, Noam Shemesh, Sune N. Jespersen, [Diffusion time dependence, power-law scaling, and exchange in gray matter](https://doi.org/10.1016/j.neuroimage.2022.118976), NeuroImage, 2022.\n\n### Soma And Neurite Density Imaging ($SANDI$)\nMarco Palombo, Andrada Ianus, Michele Guerreri, Daniel Nunes, Daniel C. Alexander, Noam Shemesh, Hui Zhang, [SANDI: A compartment-based model for non-invasive apparent soma and neurite imaging by diffusion MRI](https://doi.org/10.1016/j.neuroimage.2020.116835), NeuroImage, 2020.\n\n### Soma And Neurite Density Imaging with eXchange ($SANDIX$)\nJonas L. Olesen, Leif \u00d8stergaard, Noam Shemesh, Sune N. Jespersen, [Diffusion time dependence, power-law scaling, and exchange in gray matter](https://doi.org/10.1016/j.neuroimage.2022.118976), NeuroImage, 2022.\n\n## License\n\n`graymatter_swissknife` is distributed under the terms of the [Apache License 2.0](https://spdx.org/licenses/Apache-2.0.html).\n",
"bugtrack_url": null,
"license": null,
"summary": "Gray Matter Swiss Knife : Generalized Exchange Model estimators for diffusion MRI",
"version": "1.3.6",
"project_urls": {
"Documentation": "https://github.com/QuentinUhl/graymatter_swissknife#readme",
"Issues": "https://github.com/QuentinUhl/graymatter_swissknife/issues",
"Source": "https://github.com/QuentinUhl/graymatter_swissknife"
},
"split_keywords": [
"diffusion",
" dmri",
" grey matter",
" microstructure",
" model",
" mri"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "8a25cd270f6618123e43870c8f3825182a4b3777b755336abf88d01aa1a66e25",
"md5": "54155265ba5465cc4f65ece4578caad7",
"sha256": "843bc2cd990170055b0277ee742953b741f13086f79df39e59d2771143d4973f"
},
"downloads": -1,
"filename": "graymatter_swissknife-1.3.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "54155265ba5465cc4f65ece4578caad7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 80684,
"upload_time": "2024-10-21T18:22:44",
"upload_time_iso_8601": "2024-10-21T18:22:44.701633Z",
"url": "https://files.pythonhosted.org/packages/8a/25/cd270f6618123e43870c8f3825182a4b3777b755336abf88d01aa1a66e25/graymatter_swissknife-1.3.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "006387c0240692c06b74648ed1f0b493debe46f98b4e4e1fe331a3c746dee7da",
"md5": "16f16682d340c694dbb7aba048331063",
"sha256": "f4b1f76491234e760a2f977dfd2ed8137ef50ac43645a9f10596c06dcc50d817"
},
"downloads": -1,
"filename": "graymatter_swissknife-1.3.6.tar.gz",
"has_sig": false,
"md5_digest": "16f16682d340c694dbb7aba048331063",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 720172,
"upload_time": "2024-10-21T18:22:46",
"upload_time_iso_8601": "2024-10-21T18:22:46.726366Z",
"url": "https://files.pythonhosted.org/packages/00/63/87c0240692c06b74648ed1f0b493debe46f98b4e4e1fe331a3c746dee7da/graymatter_swissknife-1.3.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-21 18:22:46",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "QuentinUhl",
"github_project": "graymatter_swissknife#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "graymatter_swissknife"
}
JSON
