# Python Tools for NIfTI-MRS
[](https://doi.org/10.5281/zenodo.7517423)
This package contains python-based tools for representing, validating, and manipulating the [NIfTI-MRS format](https://github.com/wtclarke/mrs_nifti_standard/blob/master/specification.MD). [NIfTI-MRS](https://github.com/wtclarke/mrs_nifti_standard) is a standardised format for storing Magnetic Resonance Spectroscopy data.
These tools are used extensively in the [spec2nii](https://github.com/wtclarke/spec2nii) format conversion program and the [FSL-MRS](fsl-mrs.com) analysis software. However, this library can also be used as a stand-alone set of tools.
If you use these tools please cite:
_Clarke, WT, Bell, TK, Emir, UE, et al. NIfTI-MRS: A standard data format for magnetic resonance spectroscopy. Magn Reson Med. 2022; 88: 2358- 2370. doi:[10.1002/mrm.29418](https://doi.org/10.1002/mrm.29418)_
## Installation
Installation is via [conda(-forge)]() or [Pypi](https://pypi.org/project/nifti-mrs/).
```conda install -c conda-forge nifti-mrs```
or
```pip install nifti-mrs```
Note this package is a requirement of _spec2nii_ (>v0.4.9) and _FSL-MRS_ (>v2.0.9) and will automatically be installed with them.
## Using the package
### Command-line tool - _mrs_tools_
MRS data stored in NIfTI-MRS format can contain multiple higher dimensions. For example it might contain dimensions encoding multiple receive coils, multiple temporal averages, or even a spectral editing dimension.
Data might need to be manipulated within the NIfTI-MRS storage framework before, after, or during preprocessing. For this, FLS-MRS provides the `mrs_tools` command line script. `mrs_tools` has the ability to merge and split NIfTI-MRS files along the higher encoding dimensions. It can also reorder the higher dimensions, or create a new singleton dimension for further manipulation.
`mrs_tools split` takes a single file and splits it along a specified dimension e.g. `--dim DIM_DYN`, at a single point (`--index 8`) or extracting multiple elements into a second file (`--indices 8 9 10`).
`mrs_tools merge` takes two or more files and merges them along a specified dimension e.g. `--dim DIM_EDIT`. Use `--newaxis` if that dimension doesn't exist in the files already.
`mrs_tools reorder` permutes the dimensions of an existing NIfTI-MRS file. For example, the 5th through 7th dimensions can be changed from `DIM_COIL, DIM_DYN, DIM_EDIT` to `DIM_DYN, DIM_EDIT, DIM_COIL` using `--dim_order DIM_DYN DIM_EDIT DIM_COIL`. Reorder can be used to add a tag to a singleton dimension.
`mrs_tools reshape` allows Numpy-style reshaping of the higher dimensions. For example if two editing conditions are interleaved you can reshape a file from (32, 128) to (32, 64, 2), and by specifying `-d6 DIM_DYN -d7 DIM_EDIT` you can tag the new dimensions appropriately.
`mrs_tools` also contains the `mrs_tools vis` and `mrs_tools info` options to provide quick visualisation and information on the command line. See the [FSL-MRS Visualisation documentation](https://open.win.ox.ac.uk/pages/fsl/fsl_mrs/visualisation.html#quick-glance) for more information on `mrs_tools vis/info`.
__Note: visualisation of NIfTI-MRS data using `mrs_tools` requires the installation of the [FSL-MRS package](fsl-mrs.com)__
### As a code library
The command-line tools presents an interface to the underlying code library. The library can be used directly in interactive or scripted python. For example:
```
from nifti_mrs.nifti_mrs import NIFTI_MRS
from nifti_mrs import tools
obj = NIFTI_MRS('path/to/data.nii.gz')
# Split the object at index 16 (1-16, 17-N) along the dynamics dimension
part_1, part_2 = tools.split(obj, 'DIM_DYN', 15)
# Save the first part
part_1.save('output/location/part_1.nii.gz')
```
See the [API documentation](https://wtclarke.github.io/nifti_mrs_tools/index.html) for details.
## Contributing and tests
Contributions to improve or extend these tools via pull requests are extremely welcome. Contributors, please take time to develop tests to continually validate new features or changes.
## Acknowledgements
### Contributors
William Clarke, University of Oxford
### Funding acknowledgments
This work was funded by the Wellcome Trust [225924/Z/22/Z, 203139/Z/16/Z and 203139/A/16/Z].
Raw data
{
"_id": null,
"home_page": "https://github.com/wtclarke/nifti_mrs_tools",
"name": "nifti-mrs",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "MRS",
"author": "William Clarke",
"author_email": "william.clarke@ndcn.ox.ac.uk",
"download_url": "https://files.pythonhosted.org/packages/f6/52/6d54b178d483a43565b7e60e90e8668568f55f48fb2225e65d759b4930b7/nifti_mrs-1.2.1.tar.gz",
"platform": null,
"description": "# Python Tools for NIfTI-MRS\n\n\n\n[](https://doi.org/10.5281/zenodo.7517423)\n\n\nThis package contains python-based tools for representing, validating, and manipulating the [NIfTI-MRS format](https://github.com/wtclarke/mrs_nifti_standard/blob/master/specification.MD). [NIfTI-MRS](https://github.com/wtclarke/mrs_nifti_standard) is a standardised format for storing Magnetic Resonance Spectroscopy data. \n\nThese tools are used extensively in the [spec2nii](https://github.com/wtclarke/spec2nii) format conversion program and the [FSL-MRS](fsl-mrs.com) analysis software. However, this library can also be used as a stand-alone set of tools.\n\nIf you use these tools please cite:\n_Clarke, WT, Bell, TK, Emir, UE, et al. NIfTI-MRS: A standard data format for magnetic resonance spectroscopy. Magn Reson Med. 2022; 88: 2358- 2370. doi:[10.1002/mrm.29418](https://doi.org/10.1002/mrm.29418)_\n\n## Installation\nInstallation is via [conda(-forge)]() or [Pypi](https://pypi.org/project/nifti-mrs/).\n\n```conda install -c conda-forge nifti-mrs```\n\nor\n\n```pip install nifti-mrs```\n\nNote this package is a requirement of _spec2nii_ (>v0.4.9) and _FSL-MRS_ (>v2.0.9) and will automatically be installed with them.\n\n## Using the package\n### Command-line tool - _mrs_tools_\n\nMRS data stored in NIfTI-MRS format can contain multiple higher dimensions. For example it might contain dimensions encoding multiple receive coils, multiple temporal averages, or even a spectral editing dimension.\n\nData might need to be manipulated within the NIfTI-MRS storage framework before, after, or during preprocessing. For this, FLS-MRS provides the `mrs_tools` command line script. `mrs_tools` has the ability to merge and split NIfTI-MRS files along the higher encoding dimensions. It can also reorder the higher dimensions, or create a new singleton dimension for further manipulation.\n\n`mrs_tools split` takes a single file and splits it along a specified dimension e.g. `--dim DIM_DYN`, at a single point (`--index 8`) or extracting multiple elements into a second file (`--indices 8 9 10`).\n\n`mrs_tools merge` takes two or more files and merges them along a specified dimension e.g. `--dim DIM_EDIT`. Use `--newaxis` if that dimension doesn't exist in the files already.\n\n`mrs_tools reorder` permutes the dimensions of an existing NIfTI-MRS file. For example, the 5th through 7th dimensions can be changed from `DIM_COIL, DIM_DYN, DIM_EDIT` to `DIM_DYN, DIM_EDIT, DIM_COIL` using `--dim_order DIM_DYN DIM_EDIT DIM_COIL`. Reorder can be used to add a tag to a singleton dimension.\n\n`mrs_tools reshape` allows Numpy-style reshaping of the higher dimensions. For example if two editing conditions are interleaved you can reshape a file from (32, 128) to (32, 64, 2), and by specifying `-d6 DIM_DYN -d7 DIM_EDIT` you can tag the new dimensions appropriately.\n\n`mrs_tools` also contains the `mrs_tools vis` and `mrs_tools info` options to provide quick visualisation and information on the command line. See the [FSL-MRS Visualisation documentation](https://open.win.ox.ac.uk/pages/fsl/fsl_mrs/visualisation.html#quick-glance) for more information on `mrs_tools vis/info`.\n\n__Note: visualisation of NIfTI-MRS data using `mrs_tools` requires the installation of the [FSL-MRS package](fsl-mrs.com)__\n\n### As a code library\nThe command-line tools presents an interface to the underlying code library. The library can be used directly in interactive or scripted python. For example:\n\n```\nfrom nifti_mrs.nifti_mrs import NIFTI_MRS\nfrom nifti_mrs import tools\n\nobj = NIFTI_MRS('path/to/data.nii.gz')\n\n# Split the object at index 16 (1-16, 17-N) along the dynamics dimension\npart_1, part_2 = tools.split(obj, 'DIM_DYN', 15)\n\n# Save the first part\npart_1.save('output/location/part_1.nii.gz')\n\n```\n\nSee the [API documentation](https://wtclarke.github.io/nifti_mrs_tools/index.html) for details.\n\n## Contributing and tests\nContributions to improve or extend these tools via pull requests are extremely welcome. Contributors, please take time to develop tests to continually validate new features or changes.\n\n## Acknowledgements\n### Contributors\nWilliam Clarke, University of Oxford \n\n### Funding acknowledgments\nThis work was funded by the Wellcome Trust [225924/Z/22/Z, 203139/Z/16/Z and 203139/A/16/Z].\n",
"bugtrack_url": null,
"license": "BSD 3-Clause License",
"summary": "Software tools for the NIfTI-MRS data format",
"version": "1.2.1",
"project_urls": {
"Homepage": "https://github.com/wtclarke/nifti_mrs_tools"
},
"split_keywords": [
"mrs"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b1d941a6efde20a1a0ad366c11a25f0705998b95653e904201945061ea6bda2a",
"md5": "d669acdbe2ae58c503ec520ffd82cc28",
"sha256": "4e05db881e2bb2b8d8c641be2b884a1fb5ecf2688c554d8cc20d3c4cd872a92b"
},
"downloads": -1,
"filename": "nifti_mrs-1.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d669acdbe2ae58c503ec520ffd82cc28",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 35095,
"upload_time": "2024-04-04T10:21:22",
"upload_time_iso_8601": "2024-04-04T10:21:22.428938Z",
"url": "https://files.pythonhosted.org/packages/b1/d9/41a6efde20a1a0ad366c11a25f0705998b95653e904201945061ea6bda2a/nifti_mrs-1.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f6526d54b178d483a43565b7e60e90e8668568f55f48fb2225e65d759b4930b7",
"md5": "5da2667fb3048725aa51f1542e1dc03a",
"sha256": "b1d2c56615313f499e714aa3f4b6b2b43be1e1940057fa22234b3fed429abdcb"
},
"downloads": -1,
"filename": "nifti_mrs-1.2.1.tar.gz",
"has_sig": false,
"md5_digest": "5da2667fb3048725aa51f1542e1dc03a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 41733,
"upload_time": "2024-04-04T10:21:24",
"upload_time_iso_8601": "2024-04-04T10:21:24.256407Z",
"url": "https://files.pythonhosted.org/packages/f6/52/6d54b178d483a43565b7e60e90e8668568f55f48fb2225e65d759b4930b7/nifti_mrs-1.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-04 10:21:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "wtclarke",
"github_project": "nifti_mrs_tools",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "nifti-mrs"
}
JSON
