# erwin — a qMRI toolbox
*erwin* is a Python-based toolbox dedicated to the computation of quantitative maps from MRI data. Accessible through either its Python API or its command-line interface, *erwin* provides a unified interface to well-known methods and toolboxes.
- Field mapping: relative B0 and relative B1
- Cerebral blood flow: ASL-based models (pulsed ASL, pseudo-continuous ASL)
- Diffusion: DTI and spherical harmonics, NODDI
- Motion correction
- Magnetization transfer: MTR and single-point qMT
- Magnetic susceptibility: QSM and R2*
- T1 and T2 mapping: VFA, bSSFP, pSSFP
Since quantitative MRI requires accessing acquisition parameters, often stored in vendor-specific meta-data, *erwin* includes tools to access meta-data in a vendor-neutral way. Using [doit][] and [Spire][], *erwin* allows the definition of complex pipelines with automatic dependency handling.
The complete documentation is available [online](https://erwin.readthedocs.io/).
## Installation
*erwin* requires Python ≥ 3.7 The easiest way to install *erwin* and its dependencies is through [PyPi][] and [pip][]:
```
python3 -m pip install erwin
```
If this fails, you may need to
- adjust the `python3` executable to match your local installation
- upgrade `pip` (`python3 -m pip install --upgrade pip`, especially on Debian ≤ 10 and Ubuntu ≤ 18.04)
- install [Cython][]
- install BLAS and LAPACK
Using the following methods requires additional dependencies:
- Diffusion tensor and spherical harmonics: [MRtrix][]; conversion from Bruker or Siemens DICOM also requires [Dicomifier][]
- Motion correction: [ANTs][]
- QSM: [MEDI][]
## Command-line usage
On the command-line, the main executable is called `erwin`; a list of all methods can be obtained by
```shell
erwin --list
```
The documentation of each individual method is accessed by appending `--help` to its name, e.g.
```shell
erwin b0_map.double_echo --help
```
Due to the large number of parameters -- input and output paths, flip angles, echo times, imaging frequencies, etc. -- each command line argument is named. Parameters corresponding to physical quantities are expressed in SI units in order to avoid discrepancies between standards: DICOM uses "usual" units, e.g. milliseconds for TR or degrees for flip angles, while BIDS uses seconds for TR, but keeps degrees for flip angles.
```shell
erwin b0_map --magnitude /path/to/m1.nii.gz /path/to/m2.nii.gz --phase /path/to/p1.nii.gz /path/to/p2.nii.gz --echo-times 0.01 0.02 --target B0_map.nii.gz
```
*erwin* includes a generic meta-data reader to facilitate the conversion to SI: from either a DICOM or a JSON file, meta-data can be queried using specific units. A flip angle can be read and converted to radians using one of the two following examples, from a DICOM file or from a BIDS sidecar file:
```shell
ALPHA=$(erwin meta_data.get -p /path/to/some_file -q FlipAngle -u deg)
```
The same tool can be used for array-like meta-data (`erwin meta_data.get -p /path/to/file.dcm -q ImageType.0`) or for nested structures, including vendor-specific elements. For example, Siemens-specific meta-data from the sequence card can be queried by
```shell
erwin meta_data.get -p /path/to/some_file -q 00291020.MrPhoenixProtocol.0.sWiPMemBlock.adFree.0
```
## Usage in a Python program
Seen from a Python program, all methods defined in *erwin* are task objects and not function. This enables to easily connect steps in a pipeline: in the following example, the T1 mapping requires the output of the B1 mapping. Note that the path to the B1 map is only defined once, and that the maps will only be computed when calling `erwin.run`.
```python
import erwin
B1_map = erwin.b1_map.AFI(
["afi1.nii.gz", "afi2.nii.gz"], afi_flip_angle, afi_tr_ratio, "B1.nii.gz")
T1_map = erwin.t1_map.VFA(
["vfa1.nii.gz", "vfa2.nii.gz"], vfa_flip_angles, vfa_tr, B1_map.target)
erwin.run([B1_map, T1_map])
```
Even for such a small pipeline, it is beneficial to automate the ordering of tasks, and to keep track of which ones have already been executed. This is handled by [doit][] and [Spire][] -- both requirements of *erwin*, so they should be already installed. By dropping the last instruction (`erwin.run([B1_map, T1_map])`) and storing the following file in e.g. *pipeline.py*, the pipeline can be run by calling `doit -f pipeline.py`.
```python
import erwin
B1_map = erwin.b1_map.AFI(
"afi.nii.gz", afi_flip_angle, afi_tr_ratio, "B1.nii.gz")
T1_map = erwin.t1_map.VFA(
["vfa1.nii.gz", "vfa2.nii.gz"], vfa_flip_angles, vfa_te, vfa_tr,
B1_map.target, "T1_map.nii.gz")
```
Note that re-running doit will not re-run the tasks: since neither the original images nor the code have been modified, everything is up-to-date. Refer to the [doit][] documentation for more details about running tasks.
The complete API is available in the [main documentation](https://erwin.readthedocs.io/en/latest/methods/index.html).
[ANTs]: https://github.com/ANTsX/ANTs
[Cython]: https://cython.org/
[Dicomifier]: https://dicomifier.readthedocs.io/
[doit]: https://pydoit.org/
[MEDI]: http://pre.weill.cornell.edu/mri/pages/qsm.html
[MRtrix]: https://www.mrtrix.org/
[pip]: https://pip.pypa.io/en/stable/
[PyPi]: https://pypi.org/
[Spire]: https://github.com/lamyj/spire
Raw data
{
"_id": null,
"home_page": "https://github.com/lamyj/erwin",
"name": "erwin",
"maintainer": "Julien Lamy",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "lamy@unistra.fr",
"keywords": "MRI,quantitative,field mapping,B0,B1,CBF,cerebral blood flow,ASL,arterial spin labeling,pASL,diffusion,DTI,diffusion tensor,spherical harmonics,MT,magnetization transfer,relaxometry,T1,VFA,T2,bSSFP",
"author": "J. Lamy, M. Mondino, P. Loureiro de Sousa",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/a7/f3/39babf06d8108aba826ef1086c35cb61cf38d03604486f4ac01f1a35b93f/erwin-1.2.0.tar.gz",
"platform": null,
"description": "# erwin — a qMRI toolbox\n\n*erwin* is a Python-based toolbox dedicated to the computation of quantitative maps from MRI data. Accessible through either its Python API or its command-line interface, *erwin* provides a unified interface to well-known methods and toolboxes.\n\n- Field mapping: relative B0 and relative B1 \n- Cerebral blood flow: ASL-based models (pulsed ASL, pseudo-continuous ASL)\n- Diffusion: DTI and spherical harmonics, NODDI\n- Motion correction\n- Magnetization transfer: MTR and single-point qMT\n- Magnetic susceptibility: QSM and R2*\n- T1 and T2 mapping: VFA, bSSFP, pSSFP\n\nSince quantitative MRI requires accessing acquisition parameters, often stored in vendor-specific meta-data, *erwin* includes tools to access meta-data in a vendor-neutral way. Using [doit][] and [Spire][], *erwin* allows the definition of complex pipelines with automatic dependency handling.\n\nThe complete documentation is available [online](https://erwin.readthedocs.io/).\n\n## Installation\n\n*erwin* requires Python \u2265 3.7 The easiest way to install *erwin* and its dependencies is through [PyPi][] and [pip][]:\n```\npython3 -m pip install erwin\n```\n\nIf this fails, you may need to\n- adjust the `python3` executable to match your local installation\n- upgrade `pip` (`python3 -m pip install --upgrade pip`, especially on Debian \u2264 10 and Ubuntu \u2264 18.04)\n- install [Cython][]\n- install BLAS and LAPACK \n\nUsing the following methods requires additional dependencies:\n- Diffusion tensor and spherical harmonics: [MRtrix][]; conversion from Bruker or Siemens DICOM also requires [Dicomifier][]\n- Motion correction: [ANTs][]\n- QSM: [MEDI][]\n\n## Command-line usage\n\nOn the command-line, the main executable is called `erwin`; a list of all methods can be obtained by \n```shell\nerwin --list\n```\n\nThe documentation of each individual method is accessed by appending `--help` to its name, e.g. \n```shell\nerwin b0_map.double_echo --help\n```\n\nDue to the large number of parameters -- input and output paths, flip angles, echo times, imaging frequencies, etc. -- each command line argument is named. Parameters corresponding to physical quantities are expressed in SI units in order to avoid discrepancies between standards: DICOM uses \"usual\" units, e.g. milliseconds for TR or degrees for flip angles, while BIDS uses seconds for TR, but keeps degrees for flip angles. \n\n```shell\nerwin b0_map --magnitude /path/to/m1.nii.gz /path/to/m2.nii.gz --phase /path/to/p1.nii.gz /path/to/p2.nii.gz --echo-times 0.01 0.02 --target B0_map.nii.gz\n```\n\n*erwin* includes a generic meta-data reader to facilitate the conversion to SI: from either a DICOM or a JSON file, meta-data can be queried using specific units. A flip angle can be read and converted to radians using one of the two following examples, from a DICOM file or from a BIDS sidecar file:\n\n```shell\nALPHA=$(erwin meta_data.get -p /path/to/some_file -q FlipAngle -u deg)\n```\n\nThe same tool can be used for array-like meta-data (`erwin meta_data.get -p /path/to/file.dcm -q ImageType.0`) or for nested structures, including vendor-specific elements. For example, Siemens-specific meta-data from the sequence card can be queried by\n\n```shell\nerwin meta_data.get -p /path/to/some_file -q 00291020.MrPhoenixProtocol.0.sWiPMemBlock.adFree.0\n```\n\n## Usage in a Python program\n\nSeen from a Python program, all methods defined in *erwin* are task objects and not function. This enables to easily connect steps in a pipeline: in the following example, the T1 mapping requires the output of the B1 mapping. Note that the path to the B1 map is only defined once, and that the maps will only be computed when calling `erwin.run`.\n\n```python\nimport erwin\n\nB1_map = erwin.b1_map.AFI(\n [\"afi1.nii.gz\", \"afi2.nii.gz\"], afi_flip_angle, afi_tr_ratio, \"B1.nii.gz\")\nT1_map = erwin.t1_map.VFA(\n [\"vfa1.nii.gz\", \"vfa2.nii.gz\"], vfa_flip_angles, vfa_tr, B1_map.target)\nerwin.run([B1_map, T1_map])\n```\n\nEven for such a small pipeline, it is beneficial to automate the ordering of tasks, and to keep track of which ones have already been executed. This is handled by [doit][] and [Spire][] -- both requirements of *erwin*, so they should be already installed. By dropping the last instruction (`erwin.run([B1_map, T1_map])`) and storing the following file in e.g. *pipeline.py*, the pipeline can be run by calling `doit -f pipeline.py`.\n```python\nimport erwin\n\nB1_map = erwin.b1_map.AFI(\n \"afi.nii.gz\", afi_flip_angle, afi_tr_ratio, \"B1.nii.gz\")\nT1_map = erwin.t1_map.VFA(\n [\"vfa1.nii.gz\", \"vfa2.nii.gz\"], vfa_flip_angles, vfa_te, vfa_tr, \n B1_map.target, \"T1_map.nii.gz\")\n```\n\nNote that re-running doit will not re-run the tasks: since neither the original images nor the code have been modified, everything is up-to-date. Refer to the [doit][] documentation for more details about running tasks.\n\nThe complete API is available in the [main documentation](https://erwin.readthedocs.io/en/latest/methods/index.html).\n\n[ANTs]: https://github.com/ANTsX/ANTs\n[Cython]: https://cython.org/\n[Dicomifier]: https://dicomifier.readthedocs.io/\n[doit]: https://pydoit.org/\n[MEDI]: http://pre.weill.cornell.edu/mri/pages/qsm.html\n[MRtrix]: https://www.mrtrix.org/\n[pip]: https://pip.pypa.io/en/stable/\n[PyPi]: https://pypi.org/\n[Spire]: https://github.com/lamyj/spire\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Toolbox to generate quantitative maps from MRI images",
"version": "1.2.0",
"project_urls": {
"Homepage": "https://github.com/lamyj/erwin"
},
"split_keywords": [
"mri",
"quantitative",
"field mapping",
"b0",
"b1",
"cbf",
"cerebral blood flow",
"asl",
"arterial spin labeling",
"pasl",
"diffusion",
"dti",
"diffusion tensor",
"spherical harmonics",
"mt",
"magnetization transfer",
"relaxometry",
"t1",
"vfa",
"t2",
"bssfp"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "db206a2467b8754346eee22a3a4231334250332b67a38379e5f49f64569cebd5",
"md5": "4066bb4c9cb57270f0d40e8ff138153f",
"sha256": "9a63d69f48aa34f440233e55f1ee3570f36d1972595336d11e953c865f9d9fbb"
},
"downloads": -1,
"filename": "erwin-1.2.0-cp311-cp311-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_12_x86_64.manylinux2010_x86_64.whl",
"has_sig": false,
"md5_digest": "4066bb4c9cb57270f0d40e8ff138153f",
"packagetype": "bdist_wheel",
"python_version": "cp311",
"requires_python": ">=3.7",
"size": 103472,
"upload_time": "2023-08-09T15:17:02",
"upload_time_iso_8601": "2023-08-09T15:17:02.512111Z",
"url": "https://files.pythonhosted.org/packages/db/20/6a2467b8754346eee22a3a4231334250332b67a38379e5f49f64569cebd5/erwin-1.2.0-cp311-cp311-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_12_x86_64.manylinux2010_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a7f339babf06d8108aba826ef1086c35cb61cf38d03604486f4ac01f1a35b93f",
"md5": "47df6312b3ad022d0413c99b7881be13",
"sha256": "1e348647d8b289bd638a60fb95e9b7ba4f06a14e21b7576261d4d2b55bef0de5"
},
"downloads": -1,
"filename": "erwin-1.2.0.tar.gz",
"has_sig": false,
"md5_digest": "47df6312b3ad022d0413c99b7881be13",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 76242,
"upload_time": "2023-08-09T15:17:04",
"upload_time_iso_8601": "2023-08-09T15:17:04.578889Z",
"url": "https://files.pythonhosted.org/packages/a7/f3/39babf06d8108aba826ef1086c35cb61cf38d03604486f4ac01f1a35b93f/erwin-1.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-09 15:17:04",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "lamyj",
"github_project": "erwin",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "erwin"
}
JSON
