| Name | nisupply JSON |
| Version |
1.1.0
JSON |
| download |
| home_page | None |
| Summary | A python module for dealing with unstructured or semi-structured neuroimaging datasets which do not conform to the BIDS data structure |
| upload_time | 2024-04-19 10:10:01 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | None |
| license | MIT |
| keywords |
files
utility
neuroscience
neuroimaging
file-management
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# nisupply
A python module for dealing with unstructured or semi-structured neuroimaging datasets which do not conform to the [Brain Imaging Data Structure (BIDS)](https://bids.neuroimaging.io/). Although this packages was originall developed for neuroimaging datasets it can work on any file type!
## Installation
Install via pip with: `pip install nisupply`
## Aims
Though more and more datasets become available in the standardized BIDS-format, researchers will still often find themelves in situations, where:
1. The dataset is not BIDS-formatted at all (this is often the case with old 'in-house' datasets that were aquired during a time were BIDS didn't exist yet).
2. The dataset is wrongly BIDS-formatted because it sticks to an outdated BIDS version or because the maintainers made errors (as a consequence, verification tools like the [BIDS-validator](https://bids-standard.github.io/bids-validator/) will throw errors)
3. It is not possible to convert the datasets to BIDS, because you
1. don't have access to the original DICOM-files
2. don't have time and ressources to do so
3. don't have all the information, but the contact to the original maintainer got lost
As a consequence, one cannot use tools from the [BIDS Apps universe](https://bids-apps.neuroimaging.io/apps/) which by default require the files to be BIDS-conform in order to work. The idea behind the nisupply module is to provide helper functions that facilitate the often tedious data-wrangling work that can happen with unstructured data sets.
## Documentation
The nisupply package provides three main modules:
1. `nisupply.io`: for input-output-operations (finding files, copying them over to a different directory)
2. `nisupply.structure`: helper functions to bring the dataset into a new format
3. `nisupply.utils`: helper functions that work on the files themselves (e.g. uncompressing `.nii.gz` to `.nii` as needed for SPM12)
Consider this semistructured dataset as an example:
```
src
├── fmri_nback_subject_3_session_2.nii.gz
├── subject_1
│ ├── fmri_gambling.nii.gz
│ ├── fmri_nback.nii.gz
│ └── session_2
│ └── fmri_nback.nii.gz
├── subject_2_fmri_nback.nii.gz
└── subject_4.txt
```
We can run `nisupply.io.get_filepath_df` on this directory to find all the files that we need and gather the filepaths in a pandas dataframe (that is, search the directory `./src` for files that end with `.nii.gz` and start with `fmri_nback`. Add two new columns `subject_id`
and `task` to it that extract these entities using regular expressions).
```
df = get_filepath_df(src_dir='./src',
regex_dict={'subject_id':'subject_(\d)',
'task': 'fmri_(nback|gambling)'},
file_suffix='.nii.gz',
file_prefix='fmri_nback')
```
This gives you a pandas dataframe that looks like this:
```
filepath subject_id task
0 src/fmri_nback_subject_3_session_2.nii.gz 3 nback
1 src/subject_1/fmri_nback.nii.gz 1 nback
2 src/subject_1/session_2/fmri_nback.nii.gz 1 nback
```
We can now use `nisupply.structure.get_file_extension` and `nisupply.structure.get_new_filepath` to create a new filepath
for each file:
```
df = get_file_extension(df)
df['dst'] = './dst'
df = get_new_filepath(df,template="{dst}/sub-{subject_id}/sub-{subject_id}_task-{task}{file_extension}")
```
Which outputs:
```
filepath ... filepath_new
0 src/fmri_nback_subject_3_session_2.nii.gz ... ./dst/sub-3/sub-3_task-nback.nii.gz
1 src/subject_1/fmri_nback.nii.gz ... ./dst/sub-1/sub-1_task-nback.nii.gz
2 src/subject_1/session_2/fmri_nback.nii.gz ... ./dst/sub-1/sub-1_task-nback.nii.gz
```
Finally, we can copy over the files using `nisupply.io.copy_files(df,src_col='filepath',tgt_col='filepath_new')` to a new location to obtain a new
tidy dataset:
```
dst/
├── sub-1
│ └── sub-1_task-nback.nii.gz
└── sub-3
└── sub-3_task-nback.nii.gz
```
## Note
The nisupply module does **not** provide any functions to convert DICOM files to NIFTI files. If you are looking for tools to do that, check out tools like [heudiconv](https://heudiconv.readthedocs.io/en/latest/) or [bidscoin](https://bidscoin.readthedocs.io/en/latest/) that can do that for you.
## Similar Projects
There are similar projects out there following the same idea:
1. Have a look at Stephen Larroque's [pathmatcher](https://github.com/lrq3000/pathmatcher) package which works primarily with regex.
2. The [interfaces.io](https://nipype.readthedocs.io/en/latest/api/generated/nipype.interfaces.io.html) module from `nipype` (especially the [DataFinder](https://nipype.readthedocs.io/en/latest/api/generated/nipype.interfaces.io.html#datafinder) class)
The focus of nisupply is to avoid quite unreadable regex-matches as much as possible. It therefore is best suited for semi-structured datsets that are neither completely unordered but also neither 100% standardized.
Raw data
{
"_id": null,
"home_page": null,
"name": "nisupply",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "files, utility, neuroscience, neuroimaging, file-management",
"author": null,
"author_email": "Johannes Wiesner <joh.wiesner@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/5e/30/2bcde1fa0d21cbbdf8c7f7841bbc1e195ff313b809fe752acdf1fa883327/nisupply-1.1.0.tar.gz",
"platform": null,
"description": "# nisupply\nA python module for dealing with unstructured or semi-structured neuroimaging datasets which do not conform to the [Brain Imaging Data Structure (BIDS)](https://bids.neuroimaging.io/). Although this packages was originall developed for neuroimaging datasets it can work on any file type!\n\n## Installation\nInstall via pip with: `pip install nisupply`\n\n## Aims\nThough more and more datasets become available in the standardized BIDS-format, researchers will still often find themelves in situations, where:\n\n1. The dataset is not BIDS-formatted at all (this is often the case with old 'in-house' datasets that were aquired during a time were BIDS didn't exist yet).\n\n2. The dataset is wrongly BIDS-formatted because it sticks to an outdated BIDS version or because the maintainers made errors (as a consequence, verification tools like the [BIDS-validator](https://bids-standard.github.io/bids-validator/) will throw errors)\n\n3. It is not possible to convert the datasets to BIDS, because you\n 1. don't have access to the original DICOM-files\n 2. don't have time and ressources to do so\n 3. don't have all the information, but the contact to the original maintainer got lost\n\nAs a consequence, one cannot use tools from the [BIDS Apps universe](https://bids-apps.neuroimaging.io/apps/) which by default require the files to be BIDS-conform in order to work. The idea behind the nisupply module is to provide helper functions that facilitate the often tedious data-wrangling work that can happen with unstructured data sets.\n\n## Documentation\nThe nisupply package provides three main modules:\n\n1. `nisupply.io`: for input-output-operations (finding files, copying them over to a different directory)\n2. `nisupply.structure`: helper functions to bring the dataset into a new format\n3. `nisupply.utils`: helper functions that work on the files themselves (e.g. uncompressing `.nii.gz` to `.nii` as needed for SPM12)\n\nConsider this semistructured dataset as an example:\n\n```\nsrc\n\u251c\u2500\u2500 fmri_nback_subject_3_session_2.nii.gz\n\u251c\u2500\u2500 subject_1\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 fmri_gambling.nii.gz\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 fmri_nback.nii.gz\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 session_2\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 fmri_nback.nii.gz\n\u251c\u2500\u2500 subject_2_fmri_nback.nii.gz\n\u2514\u2500\u2500 subject_4.txt\n```\n\nWe can run `nisupply.io.get_filepath_df` on this directory to find all the files that we need and gather the filepaths in a pandas dataframe (that is, search the directory `./src` for files that end with `.nii.gz` and start with `fmri_nback`. Add two new columns `subject_id`\nand `task` to it that extract these entities using regular expressions).\n\n```\ndf = get_filepath_df(src_dir='./src',\n regex_dict={'subject_id':'subject_(\\d)',\n 'task': 'fmri_(nback|gambling)'},\n file_suffix='.nii.gz',\n file_prefix='fmri_nback')\n```\nThis gives you a pandas dataframe that looks like this:\n\n```\n filepath subject_id task\n0 src/fmri_nback_subject_3_session_2.nii.gz 3 nback\n1 src/subject_1/fmri_nback.nii.gz 1 nback\n2 src/subject_1/session_2/fmri_nback.nii.gz 1 nback\n```\n\nWe can now use `nisupply.structure.get_file_extension` and `nisupply.structure.get_new_filepath` to create a new filepath\nfor each file:\n\n```\ndf = get_file_extension(df)\ndf['dst'] = './dst'\ndf = get_new_filepath(df,template=\"{dst}/sub-{subject_id}/sub-{subject_id}_task-{task}{file_extension}\")\n```\n\nWhich outputs:\n\n```\n filepath ... filepath_new\n0 src/fmri_nback_subject_3_session_2.nii.gz ... ./dst/sub-3/sub-3_task-nback.nii.gz\n1 src/subject_1/fmri_nback.nii.gz ... ./dst/sub-1/sub-1_task-nback.nii.gz\n2 src/subject_1/session_2/fmri_nback.nii.gz ... ./dst/sub-1/sub-1_task-nback.nii.gz\n```\n\nFinally, we can copy over the files using `nisupply.io.copy_files(df,src_col='filepath',tgt_col='filepath_new')` to a new location to obtain a new\ntidy dataset:\n\n```\ndst/\n\u251c\u2500\u2500 sub-1\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 sub-1_task-nback.nii.gz\n\u2514\u2500\u2500 sub-3\n \u2514\u2500\u2500 sub-3_task-nback.nii.gz\n```\n\n## Note\nThe nisupply module does **not** provide any functions to convert DICOM files to NIFTI files. If you are looking for tools to do that, check out tools like [heudiconv](https://heudiconv.readthedocs.io/en/latest/) or [bidscoin](https://bidscoin.readthedocs.io/en/latest/) that can do that for you.\n\n## Similar Projects\nThere are similar projects out there following the same idea:\n1. Have a look at Stephen Larroque's [pathmatcher](https://github.com/lrq3000/pathmatcher) package which works primarily with regex.\n2. The [interfaces.io](https://nipype.readthedocs.io/en/latest/api/generated/nipype.interfaces.io.html) module from `nipype` (especially the [DataFinder](https://nipype.readthedocs.io/en/latest/api/generated/nipype.interfaces.io.html#datafinder) class)\n\nThe focus of nisupply is to avoid quite unreadable regex-matches as much as possible. It therefore is best suited for semi-structured datsets that are neither completely unordered but also neither 100% standardized.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A python module for dealing with unstructured or semi-structured neuroimaging datasets which do not conform to the BIDS data structure",
"version": "1.1.0",
"project_urls": {
"Homepage": "https://github.com/JohannesWiesner/nisupply"
},
"split_keywords": [
"files",
" utility",
" neuroscience",
" neuroimaging",
" file-management"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7341b658932190e36a8b849cda243ecf9f9936088e0d52dd9eed0913c02c840b",
"md5": "689f205cd32171ca8b9465b1d1cf7772",
"sha256": "57e8d2f821de6598e57ab210985c7e48f1c562ba1af5dd32f774bc016152c0d0"
},
"downloads": -1,
"filename": "nisupply-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "689f205cd32171ca8b9465b1d1cf7772",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 8811,
"upload_time": "2024-04-19T10:09:58",
"upload_time_iso_8601": "2024-04-19T10:09:58.989858Z",
"url": "https://files.pythonhosted.org/packages/73/41/b658932190e36a8b849cda243ecf9f9936088e0d52dd9eed0913c02c840b/nisupply-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5e302bcde1fa0d21cbbdf8c7f7841bbc1e195ff313b809fe752acdf1fa883327",
"md5": "d1dd5c7e396692ad0b9a1322de8a1a93",
"sha256": "b3fc6784788e3abd949ed66b59ca3b4160e5d78e4d1b6b1d5060306f99056c9e"
},
"downloads": -1,
"filename": "nisupply-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "d1dd5c7e396692ad0b9a1322de8a1a93",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 11436,
"upload_time": "2024-04-19T10:10:01",
"upload_time_iso_8601": "2024-04-19T10:10:01.327804Z",
"url": "https://files.pythonhosted.org/packages/5e/30/2bcde1fa0d21cbbdf8c7f7841bbc1e195ff313b809fe752acdf1fa883327/nisupply-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-19 10:10:01",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "JohannesWiesner",
"github_project": "nisupply",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "nisupply"
}
