| Name | gradiator JSON |
| Version |
0.0.1.dev14
JSON |
| download |
| home_page | |
| Summary | turn covariance matrices into brain gradients |
| upload_time | 2023-02-05 15:27:03 |
| maintainer | |
| docs_url | None |
| author | Leonard Sasse |
| requires_python | >=3.7 |
| license | |
| keywords |
neuroimaging
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# gradiator
Command line tool turn covariance matrices in tsv or csv files into gradients.
gradiator is heavily based on the fantastic brainspace toolbox, so make sure to
check out its [documentation](https://brainspace.readthedocs.io/en/latest/index.html)
and the [related paper](https://www.nature.com/articles/s42003-020-0794-7).
The idea of gradiator is to provide a quick and easy-to-use command line interface for the
computation of gradients using some symmetric covariance matrix in a csv or tsv file. gradiator
assumes that the first row of this matrix contains the column names, and like-wise it assumes
that the first column represents the index of the matrix.
The output gradients will be mapped to a NIfTI image in the same space as the volumetric atlas
you provide to gradiator.
# Set up
You may or may not want to set up a virtual environment.
```sh
python3 -m venv .examplevenv
source .examplevenv/bin/activate
pip install -U pip
```
You can simply install `gradiator` via PyPI:
```
pip install gradiator
```
Alternatively, you can install from GitHub.
Clone the repository to where you would like to install it and:
```
git clone https://github.com/LeSasse/gradiator.git
cd gradiator
pip install -e .
```
# How to use
Run `gradiator --help`:
```
usage: gradiator [-h] [--reference REFERENCE] [--n_components N_COMPONENTS]
[--sparsity [SPARSITY ...]] [--kernel [KERNEL ...]]
[--approach [APPROACH ...]] [--background BACKGROUND]
matrix nii_atlas out_folder
Derive GradientMaps from symmetric ROIxROI covariance matrices saved in .tsv or
.csv files. For some arguments more than one values can be passed i.e. kernel. In
this case output will be generated for all possible combinations of parameters.
positional arguments:
matrix Path to the .csv or .tsv file containing the covariance
matrix. gradiator assumes that the first row is the column names,
and the first column is the index of the matrix.
nii_atlas Path to the nifti file that was used as a parcellation to
derive the ROI's of the covariance matrix and is used to
map gradients to nifti files.
out_folder Path to the directory in which output should be stored.
optional arguments:
-h, --help show this help message and exit
--reference REFERENCE, -r REFERENCE
Path to a covariance matrix which should be used to create
reference gradients for alignment.
--n_components N_COMPONENTS, -n N_COMPONENTS
Number of components to extract. (Int: default 5)
--sparsity [SPARSITY ...], -s [SPARSITY ...]
One or more sparsity thresholds to be applied to covariance
matrix (float: default 0 and 0.9).
--kernel [KERNEL ...], -k [KERNEL ...]
One or more kernels used to construct affinity matrix.
Available options are: pearson, spearman, normalized_angle,
cosine, gaussian or None.
--approach [APPROACH ...], -a [APPROACH ...]
One or more approaches for the dimensionality reduction.
Available options are: pca, dm, le.
--background BACKGROUND, -b BACKGROUND
Set the value of background voxels (i.e. voxels that are
labelled 0 in the Parcellation.). The absolute value of the
number handed over as 'background' will be subtracted from
the minimum gradient value to determine the value of
background voxels. If 'NaN' or 'nan' are provided, this
means that background values will be set to nan floating
points.In any case, 'NaN' values in the image are treated
exactly the same as background voxels.
```
# Example commands:
By default, gradiator will yield output for all possible combinations of gradient parameters:
```
gradiator my_covariance_matrix.tsv my_atlas.nii.gz path/to/my_desired_output_location
```
To specify only a few specific parameters, you could use the provided optional arguments as follows:
```sh
gradiator \
my_covariance_matrix.tsv \
my_atlas.nii.gz \
path/to/my_desired_output_location \
-n 5 \
-s 0.9 \
-a dm \ # diffusion map embedding
-k normalized_angle
```
You can also set the value of the background voxels. For example by providing the strings
'nan' or 'NaN' with the `--background` option, the background will be set to 'NaN':
```
gradiator my_covariance_matrix.tsv my_atlas.nii.gz path/to/my_desired_output_location -b nan
```
However, typically it makes sense to set the background below the "cal_min" property of
the image header, which indicates the minimum display intensity of a NIfTI image.
From the [official NIfTI file specifications](https://nifti.nimh.nih.gov/pub/dist/src/niftilib/nifti1.h):
> float cal_min; /*!< Min display intensity */ /* float cal_min; */
By handing over a numeric value to the `--background` option, the background will be set to
`header['cal_min'] - abs(<your_provided_value>)`. This is useful, as the background can then
be easily distuingished from negative values on your gradient. the `cal_min` value of your resultant
gradient image is set to the lowest value on the gradient (which can often be negative).
So an example command for this can be:
```
gradiator my_covariance_matrix.tsv my_atlas.nii.gz path/to/my_desired_output_location -b 1000
```
Which will set the background voxels to the cal_min - 1000.
Now, it is also important to note, that any 'NaN' values in the gradient image are handled in the
same way as background voxels. That is, if a brain area has 'NaN' values in the covariance matrix,
then this area will be excluded from gradient computation, and the area will be 'NaN' in the image.
If you have other ideas on how 'NaN' values can be handled, feel free to make an issue.
Raw data
{
"_id": null,
"home_page": "",
"name": "gradiator",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "neuroimaging",
"author": "Leonard Sasse",
"author_email": "l.sasse@fz-juelich.de",
"download_url": "https://files.pythonhosted.org/packages/06/f6/a8edd0884da97893eb0014b68f012bbde4fcf63f7adb6a6dba663f7f48e8/gradiator-0.0.1.dev14.tar.gz",
"platform": null,
"description": "# gradiator\nCommand line tool turn covariance matrices in tsv or csv files into gradients.\n\n\ngradiator is heavily based on the fantastic brainspace toolbox, so make sure to\ncheck out its [documentation](https://brainspace.readthedocs.io/en/latest/index.html)\nand the [related paper](https://www.nature.com/articles/s42003-020-0794-7).\n\nThe idea of gradiator is to provide a quick and easy-to-use command line interface for the\ncomputation of gradients using some symmetric covariance matrix in a csv or tsv file. gradiator\nassumes that the first row of this matrix contains the column names, and like-wise it assumes\nthat the first column represents the index of the matrix.\n\nThe output gradients will be mapped to a NIfTI image in the same space as the volumetric atlas\nyou provide to gradiator.\n\n# Set up\n\nYou may or may not want to set up a virtual environment.\n\n```sh\npython3 -m venv .examplevenv\nsource .examplevenv/bin/activate\npip install -U pip\n```\n\nYou can simply install `gradiator` via PyPI:\n\n```\npip install gradiator\n```\n\nAlternatively, you can install from GitHub.\nClone the repository to where you would like to install it and:\n```\ngit clone https://github.com/LeSasse/gradiator.git\ncd gradiator\npip install -e .\n```\n\n# How to use\n\nRun `gradiator --help`:\n\n```\nusage: gradiator [-h] [--reference REFERENCE] [--n_components N_COMPONENTS]\n [--sparsity [SPARSITY ...]] [--kernel [KERNEL ...]]\n [--approach [APPROACH ...]] [--background BACKGROUND]\n matrix nii_atlas out_folder\n\nDerive GradientMaps from symmetric ROIxROI covariance matrices saved in .tsv or\n.csv files. For some arguments more than one values can be passed i.e. kernel. In\nthis case output will be generated for all possible combinations of parameters.\n\npositional arguments:\n matrix Path to the .csv or .tsv file containing the covariance\n matrix. gradiator assumes that the first row is the column names,\n and the first column is the index of the matrix.\n nii_atlas Path to the nifti file that was used as a parcellation to\n derive the ROI's of the covariance matrix and is used to\n map gradients to nifti files.\n out_folder Path to the directory in which output should be stored.\n\noptional arguments:\n -h, --help show this help message and exit\n --reference REFERENCE, -r REFERENCE\n Path to a covariance matrix which should be used to create\n reference gradients for alignment.\n --n_components N_COMPONENTS, -n N_COMPONENTS\n Number of components to extract. (Int: default 5)\n --sparsity [SPARSITY ...], -s [SPARSITY ...]\n One or more sparsity thresholds to be applied to covariance\n matrix (float: default 0 and 0.9).\n --kernel [KERNEL ...], -k [KERNEL ...]\n One or more kernels used to construct affinity matrix.\n Available options are: pearson, spearman, normalized_angle,\n cosine, gaussian or None.\n --approach [APPROACH ...], -a [APPROACH ...]\n One or more approaches for the dimensionality reduction.\n Available options are: pca, dm, le.\n --background BACKGROUND, -b BACKGROUND\n Set the value of background voxels (i.e. voxels that are\n labelled 0 in the Parcellation.). The absolute value of the\n number handed over as 'background' will be subtracted from\n the minimum gradient value to determine the value of\n background voxels. If 'NaN' or 'nan' are provided, this\n means that background values will be set to nan floating\n points.In any case, 'NaN' values in the image are treated\n exactly the same as background voxels.\n\n```\n\n# Example commands:\n\nBy default, gradiator will yield output for all possible combinations of gradient parameters:\n\n```\ngradiator my_covariance_matrix.tsv my_atlas.nii.gz path/to/my_desired_output_location\n```\n\nTo specify only a few specific parameters, you could use the provided optional arguments as follows:\n\n```sh\ngradiator \\\n my_covariance_matrix.tsv \\\n my_atlas.nii.gz \\\n path/to/my_desired_output_location \\\n -n 5 \\\n -s 0.9 \\\n -a dm \\ # diffusion map embedding\n -k normalized_angle\n```\n\nYou can also set the value of the background voxels. For example by providing the strings\n'nan' or 'NaN' with the `--background` option, the background will be set to 'NaN':\n\n```\ngradiator my_covariance_matrix.tsv my_atlas.nii.gz path/to/my_desired_output_location -b nan\n```\n\n\nHowever, typically it makes sense to set the background below the \"cal_min\" property of\nthe image header, which indicates the minimum display intensity of a NIfTI image.\nFrom the [official NIfTI file specifications](https://nifti.nimh.nih.gov/pub/dist/src/niftilib/nifti1.h):\n\n> float cal_min; /*!< Min display intensity */ /* float cal_min; */\n\nBy handing over a numeric value to the `--background` option, the background will be set to \n`header['cal_min'] - abs(<your_provided_value>)`. This is useful, as the background can then\nbe easily distuingished from negative values on your gradient. the `cal_min` value of your resultant\ngradient image is set to the lowest value on the gradient (which can often be negative).\n\nSo an example command for this can be:\n\n```\ngradiator my_covariance_matrix.tsv my_atlas.nii.gz path/to/my_desired_output_location -b 1000\n```\n\nWhich will set the background voxels to the cal_min - 1000.\n\nNow, it is also important to note, that any 'NaN' values in the gradient image are handled in the\nsame way as background voxels. That is, if a brain area has 'NaN' values in the covariance matrix,\nthen this area will be excluded from gradient computation, and the area will be 'NaN' in the image.\nIf you have other ideas on how 'NaN' values can be handled, feel free to make an issue.\n",
"bugtrack_url": null,
"license": "",
"summary": "turn covariance matrices into brain gradients",
"version": "0.0.1.dev14",
"split_keywords": [
"neuroimaging"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "119909f2799a25e078bbccbeaae884c79d048b4411ffbad49ea7e36e7028532a",
"md5": "8f595360ed3f0f77bfb8082dc51a3b82",
"sha256": "888d203a8e50acfcdb014d5038bd34efb712ea20f13e008bcbae2ddbac619a77"
},
"downloads": -1,
"filename": "gradiator-0.0.1.dev14-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8f595360ed3f0f77bfb8082dc51a3b82",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 20333,
"upload_time": "2023-02-05T15:27:01",
"upload_time_iso_8601": "2023-02-05T15:27:01.603388Z",
"url": "https://files.pythonhosted.org/packages/11/99/09f2799a25e078bbccbeaae884c79d048b4411ffbad49ea7e36e7028532a/gradiator-0.0.1.dev14-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "06f6a8edd0884da97893eb0014b68f012bbde4fcf63f7adb6a6dba663f7f48e8",
"md5": "18ba5db488f03a4e075e7c8b5ccaa71e",
"sha256": "ccc2030de0dd645f0e5195d9593a12728dabb924cad4b7f584d69f9e44884862"
},
"downloads": -1,
"filename": "gradiator-0.0.1.dev14.tar.gz",
"has_sig": false,
"md5_digest": "18ba5db488f03a4e075e7c8b5ccaa71e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 21113,
"upload_time": "2023-02-05T15:27:03",
"upload_time_iso_8601": "2023-02-05T15:27:03.907638Z",
"url": "https://files.pythonhosted.org/packages/06/f6/a8edd0884da97893eb0014b68f012bbde4fcf63f7adb6a6dba663f7f48e8/gradiator-0.0.1.dev14.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-02-05 15:27:03",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "gradiator"
}
