# MRI Phase Unwrapping
[](https://zenodo.org/badge/latestdoi/551228762)
A simple, laplacian-based unwrapping pipeline for MRI phase images.
If you use this code in your work, please cite:
```
Blake E. Dewey. (2022). Laplacian-based Phase Unwrapping in Python. Zenodo. [https://doi.org/10.5281/zenodo.7198990](https://doi.org/10.5281/zenodo.7198991)
```
## Install with pip
```bash
pip install phase_unwrap
```
## Basic Usage
```bash
unwrap-phase /path/to/phase_image.nii.gz
```
This will produce an unwrapped phase image in the same directory as the input image with `_unwrapped` appended to the filename.
**NOTE:** Some have reported the best results when the phase image is reoriented to the axial plane before unwrapping.
This can be done with the `--orientation` option:
```bash
unwrap-phase /path/to/phase_image.nii.gz --orientation RAI
```
If you would like the unwrapped image returned in the original orientation, use the `--undo-reorient` option.
### CLI Options
| Option | Description | Default |
|-------------------|-------------------------------------------------------------|----------|
| | Path to phase image | Required |
| `-o`/`--output` | Output path | Optional |
| `--orientation` | Reorient to this before unwrapping (`RAI`, `RSA`, or `ASR`) | Optional |
| `--undo-reorient` | Return image to orientation after unwrapping | `False` |
Using the `--output` option will save the unwrapped image to that path.
If not provided, the unwrapped image will be saved to the same directory as the input image with `_unwrapped` appended to the filename (before the `.nii.gz`).
`--orientation` can be used to reorient the image before unwrapping.
This script uses 2D functions for unwrapping and will slice the data according to the slice direction of the volume (last dimension).
If the slice direction is not the desired orientation, use this option to reorient the image before unwrapping.
`RAI` will give you an axial image. `RSA` will give you a coronal image. `ASR` will give you a sagittal image.
If you would like the unwrapped image returned in the original orientation, use the `--undo-reorient` option.
## Docker Usage
The docker file in this package is used to build a container with the necessary dependencies to run the unwrapping script.
You can pull it directly from Docker Hub with:
```bash
docker pull blakedewey/phase_unwrap:v2.0.0
```
After pulling the image, you can run the unwrapping script with:
```bash
docker run -it --rm -v /path/to/data:/data blakedewey/phase_unwrap:v2.0.0 /data/phase_image.nii.gz
```
All of the same CLI options will work with the Docker container as well.
Remember to mount the directory containing the data to a place in the container (`/data` in the example).
You will also have to specify the path to the image relative to the mounted directory.
## Upgrading from v1.0.0
The CLI options have changed slightly from v1.0.0 to v2.0.0:
- The `-p`/`--phase-image` option has been replaced with a positional argument for the path to the phase image.
- In v1.0.0, image paths were assumed to be in `/data` for use in Docker. This is no longer the case. You must specify the full path to the image or output, even in the Docker container.
- In v1.0.0, the default for `--orientation` was `RAI`. This has been removed. If you want to reorient the image, you must specify the orientation. Use `--orientation RAI` to get the same behavior as v1.0.0.
- The `--undo-reorient` option has been added to return the image to the original orientation after unwrapping.
## Works Using This Code
This processing has been used in a number of published manuscripts detailing phase-rim lesions in multiple sclerosis.
1. Absinta et al. "Persistent 7-tesla phase rim predicts poor outcome in new multiple sclerosis patient lesions" *Journal of Clinical Investigation* (doi: [10.1172/JCI86198](https://doi.org/10.1172%2FJCI86198))
Raw data
{
"_id": null,
"home_page": "https://github.com/blakedewey/phase_unwrap",
"name": "phase-unwrap",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "mri phase unwrapping",
"author": "Blake Dewey",
"author_email": "blake.dewey@jhu.edu",
"download_url": "https://files.pythonhosted.org/packages/c8/e6/9c508075fbe2af5ea066bdbe503b6fa8b7b7157487335bc98e70a1d776c9/phase_unwrap-2.0.0.tar.gz",
"platform": null,
"description": "# MRI Phase Unwrapping\n\n[](https://zenodo.org/badge/latestdoi/551228762)\n\nA simple, laplacian-based unwrapping pipeline for MRI phase images.\n\nIf you use this code in your work, please cite:\n```\nBlake E. Dewey. (2022). Laplacian-based Phase Unwrapping in Python. Zenodo. [https://doi.org/10.5281/zenodo.7198990](https://doi.org/10.5281/zenodo.7198991)\n```\n\n## Install with pip\n```bash\npip install phase_unwrap\n```\n\n## Basic Usage\n```bash\nunwrap-phase /path/to/phase_image.nii.gz\n```\nThis will produce an unwrapped phase image in the same directory as the input image with `_unwrapped` appended to the filename.\n\n**NOTE:** Some have reported the best results when the phase image is reoriented to the axial plane before unwrapping.\nThis can be done with the `--orientation` option:\n```bash\nunwrap-phase /path/to/phase_image.nii.gz --orientation RAI\n```\nIf you would like the unwrapped image returned in the original orientation, use the `--undo-reorient` option.\n\n### CLI Options\n| Option | Description | Default |\n|-------------------|-------------------------------------------------------------|----------|\n| | Path to phase image | Required |\n| `-o`/`--output` | Output path | Optional |\n| `--orientation` | Reorient to this before unwrapping (`RAI`, `RSA`, or `ASR`) | Optional |\n| `--undo-reorient` | Return image to orientation after unwrapping | `False` |\n\nUsing the `--output` option will save the unwrapped image to that path. \nIf not provided, the unwrapped image will be saved to the same directory as the input image with `_unwrapped` appended to the filename (before the `.nii.gz`).\n\n`--orientation` can be used to reorient the image before unwrapping.\nThis script uses 2D functions for unwrapping and will slice the data according to the slice direction of the volume (last dimension).\nIf the slice direction is not the desired orientation, use this option to reorient the image before unwrapping.\n`RAI` will give you an axial image. `RSA` will give you a coronal image. `ASR` will give you a sagittal image.\nIf you would like the unwrapped image returned in the original orientation, use the `--undo-reorient` option.\n\n## Docker Usage\nThe docker file in this package is used to build a container with the necessary dependencies to run the unwrapping script.\nYou can pull it directly from Docker Hub with:\n```bash\ndocker pull blakedewey/phase_unwrap:v2.0.0\n```\n\nAfter pulling the image, you can run the unwrapping script with:\n```bash\ndocker run -it --rm -v /path/to/data:/data blakedewey/phase_unwrap:v2.0.0 /data/phase_image.nii.gz\n```\n\nAll of the same CLI options will work with the Docker container as well.\nRemember to mount the directory containing the data to a place in the container (`/data` in the example).\nYou will also have to specify the path to the image relative to the mounted directory.\n\n## Upgrading from v1.0.0\nThe CLI options have changed slightly from v1.0.0 to v2.0.0:\n - The `-p`/`--phase-image` option has been replaced with a positional argument for the path to the phase image.\n - In v1.0.0, image paths were assumed to be in `/data` for use in Docker. This is no longer the case. You must specify the full path to the image or output, even in the Docker container.\n - In v1.0.0, the default for `--orientation` was `RAI`. This has been removed. If you want to reorient the image, you must specify the orientation. Use `--orientation RAI` to get the same behavior as v1.0.0.\n - The `--undo-reorient` option has been added to return the image to the original orientation after unwrapping.\n\n## Works Using This Code\nThis processing has been used in a number of published manuscripts detailing phase-rim lesions in multiple sclerosis.\n\n1. Absinta et al. \"Persistent 7-tesla phase rim predicts poor outcome in new multiple sclerosis patient lesions\" *Journal of Clinical Investigation* (doi: [10.1172/JCI86198](https://doi.org/10.1172%2FJCI86198))\n",
"bugtrack_url": null,
"license": "GPL-3.0",
"summary": "A simple, laplacian-based unwrapping pipeline for MRI phase images in Python.",
"version": "2.0.0",
"project_urls": {
"Homepage": "https://github.com/blakedewey/phase_unwrap"
},
"split_keywords": [
"mri",
"phase",
"unwrapping"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "bbb64b76586a8e4eab80a037acc4c13aab2d61fcbe05aa8e34222e791d5cde4a",
"md5": "2805e7ddd9ece07d6f533721ba5b6674",
"sha256": "763499392d4ee71d57fadb59502e00e8b3b9494a9e54a8c39ba43331dc4ab716"
},
"downloads": -1,
"filename": "phase_unwrap-2.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2805e7ddd9ece07d6f533721ba5b6674",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 20382,
"upload_time": "2024-06-24T23:53:00",
"upload_time_iso_8601": "2024-06-24T23:53:00.853097Z",
"url": "https://files.pythonhosted.org/packages/bb/b6/4b76586a8e4eab80a037acc4c13aab2d61fcbe05aa8e34222e791d5cde4a/phase_unwrap-2.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c8e69c508075fbe2af5ea066bdbe503b6fa8b7b7157487335bc98e70a1d776c9",
"md5": "8fedd8c2f3b911a2799bdb54e1b6d2fa",
"sha256": "d92f922c6e6056ccb1f5daf384d29ae9dacde45c310ef8ee41a34a7f9b056c5a"
},
"downloads": -1,
"filename": "phase_unwrap-2.0.0.tar.gz",
"has_sig": false,
"md5_digest": "8fedd8c2f3b911a2799bdb54e1b6d2fa",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 19962,
"upload_time": "2024-06-24T23:53:02",
"upload_time_iso_8601": "2024-06-24T23:53:02.286039Z",
"url": "https://files.pythonhosted.org/packages/c8/e6/9c508075fbe2af5ea066bdbe503b6fa8b7b7157487335bc98e70a1d776c9/phase_unwrap-2.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-24 23:53:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "blakedewey",
"github_project": "phase_unwrap",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "nibabel",
"specs": []
},
{
"name": "numpy",
"specs": []
}
],
"lcname": "phase-unwrap"
}
JSON
