# NeuroRuler <span><img width="20" src="https://i.imgur.com/pYlhHqu.png"></span>
NeuroRuler is a program that calculates head circumference from MRI data (`.nii`, `.nii.gz`, `.nrrd`).
<p align="center">
<img src="https://i.imgur.com/nqwqHq8.gif" alt="GUI demo"/>
</p>
<p align="center">
<a href="https://www.youtube.com/watch?v=ZhSg5xwzbmo"><img src="https://img.youtube.com/vi/ZhSg5xwzbmo/0.jpg" alt="full demo video"></a>
</p>
<p align="center">
<a href="https://www.youtube.com/watch?v=ZhSg5xwzbmo">Full demo</a>
</p>
## Cite this tool
If you want 😉 format is bibtex.
```bibtex
@misc{neuroruler,
title={NeuroRuler},
author={Wei, Jesse and Lester, Madison and He, Peifeng and Schneider, Eric and Styner, Martin},
howpublished={\url{https://github.com/NIRALUser/NeuroRuler}},
year={2023}
}
```
## Install
Your Python version needs to be 3.8+. Check with `python --version`. Install with pip.
```sh
pip install NeuroRuler
```
If `python` or `pip` don't work, try `python3` and `pip3`.
## Usage
Download the latest [release](https://github.com/NIRALUser/NeuroRuler/releases).
The [gui.py](https://github.com/NIRALUser/NeuroRuler/blob/main/gui.py) and [cli.py](https://github.com/NIRALUser/NeuroRuler/blob/main/cli.py) scripts, further described below, are entry points for NeuroRuler's GUI and CLI.
[gui_config.json](https://github.com/NIRALUser/NeuroRuler/blob/main/gui_config.json) and [cli_config.json](https://github.com/NIRALUser/NeuroRuler/blob/main/cli_config.json) set default settings for the GUI and CLI. `gui.py` and `cli.py` will create `gui_config.json` and `cli_config.json` if they don't exist. For more information, see [Configure default settings](#configure-default-settings).
## For developers
Developers contributing to the repository should clone the repository. `gui.py` and `cli.py` will then import from the local repository and reflect changes made to the codebase.
Developers should also run `pip install -r requirements.txt` to install additional development dependencies and `pre-commit install` to install pre-commit git hooks.
## Run GUI
```sh
python gui.py
```
Run `python gui.py -h` to see command-line options.
The GUI can also be run from any directory from a Python terminal. After opening a Python terminal, run these commands:
```py
from NeuroRuler.GUI import gui
gui()
```
<p align="center">Same as the code in <code>gui.py</code></p>
## Run CLI
```text
python cli.py <file>
```
See [test_cli.py](https://github.com/NIRALUser/NeuroRuler/blob/main/tests/test_cli.py) for example usages.
```text
usage: cli.py [-h] [-d] [-r] [-x X] [-y Y] [-z Z] [-s SLICE] [-c CONDUCTANCE] [-i ITERATIONS] [-t STEP] [-f FILTER] [-l LOWER]
[-u UPPER]
file
A program that calculates head circumference from MRI data (``.nii``, ``.nii.gz``, ``.nrrd``).
positional arguments:
file file to compute circumference from, file format must be *.nii.gz, *.nii, or *.nrrd
options:
-h, --help show this help message and exit
-d, --debug print debug info
-r, --raw print just the "raw" circumference
-x X, --x X x rotation (in degrees)
-y Y, --y Y y rotation (in degrees)
-z Z, --z Z z rotation (in degrees)
-s SLICE, --slice SLICE
slice (Z slice, 0-indexed)
-c CONDUCTANCE, --conductance CONDUCTANCE
conductance smoothing parameter
-i ITERATIONS, --iterations ITERATIONS
smoothing iterations
-t STEP, --step STEP time step (smoothing parameter)
-f FILTER, --filter FILTER
which filter to use (Otsu or binary), default is Otsu
-l LOWER, --lower LOWER
lower threshold for binary threshold
-u UPPER, --upper UPPER
upper threshold for binary threshold
```
<p align="center">Output of <code>python cli.py -h</code> (could be outdated)</p>
## Import/export image settings JSON
In the GUI's "circumference mode" (after clicking Apply), click the large Export button under the image to export image settings JSON file(s) containing the circumferences of all loaded images and the settings applied to each image.
You can then use File > Import Image Settings to import an image settings JSON to load the same image with the same settings.
Here is an example:
```py
{
"input_image_path": "/Users/jesse/Documents/GitHub/COMP523/NeuroRuler/data/MicroBiome_1month_T1w.nii.gz",
"output_contoured_slice_path": "/Users/jesse/Documents/GitHub/COMP523/NeuroRuler/output/MicroBiome_1month_T1w/MicroBiome_1month_T1w_contoured.png",
"circumference": 285.04478394448125,
"x_rotation": -17,
"y_rotation": -18,
"z_rotation": 24,
"slice": 131,
"smoothing_conductance": 4.0,
"smoothing_iterations": 10,
"smoothing_time_step": 0.08,
"threshold_filter": "Otsu"
}
```
When multiple images are exported, the output directory structure looks like this:
```text
output
├── 150649_V06_t1w
│ ├── 150649_V06_t1w_contoured.png
│ └── 150649_V06_t1w_settings.json
└── MicroBiome_1month_T1w
├── MicroBiome_1month_T1w_contoured.png
└── MicroBiome_1month_T1w_settings.json
```
## Configure default settings
Edit the JSON configuration files [gui_config.json](https://github.com/NIRALUser/NeuroRuler/blob/main/gui_config.json) and [cli_config.json](https://github.com/NIRALUser/NeuroRuler/blob/main/cli_config.json). `gui.py` and `cli.py` will create these files if they don't exist.
Command-line arguments supplied to the [gui.py](https://github.com/NIRALUser/NeuroRuler/blob/main/gui.py) or [cli.py](https://github.com/NIRALUser/NeuroRuler/blob/main/cli.py) scripts override settings in the JSON configuration files. JSON settings are default values for the GUI and CLI: If a setting in the JSON file is not overriden by a CLI argument, the JSON file setting will be used.
## Run tests
To test locally, run `pytest`.
Our algorithm tests assert that our GUI calculations have at least a 0.98 R<sup>2</sup> value with ground truth data from the old Head Circumference Tool. We use a similar R<sup>2</sup> test to verify that our circumference result is correct for images with non-(1.0, 1.0, 1.0) pixel spacing. We verified manually (no unit test) that the GUI computes similar circumferences for (a, b, c) pixel spacing images generated from (1.0, 1.0, 1.0) pixel spacing images.
To test CLI, we test that our CLI produces the same results as the GUI.
Our tests run on GitHub Actions on push and PR via `tox` ([tests.yml](https://github.com/NIRALUser/NeuroRuler/blob/main/.github/workflows/tests.yml)). If the image below says "passing," then the tests are passing.
<p align="center">
<img src="https://github.com/NIRALUser/NeuroRuler/actions/workflows/tests.yml/badge.svg" alt="GitHub actions tests.yml badge"/>
</p>
## Documentation
[https://NeuroRuler.readthedocs.io](https://NeuroRuler.readthedocs.io)
See [.readthedocs.yaml](https://github.com/NIRALUser/NeuroRuler/blob/main/.readthedocs.yaml) and [docs/](https://github.com/NIRALUser/NeuroRuler/tree/main/docs) to contribute.
[Team website](https://tarheels.live/comp523teamd/)
## Release
To test the package locally before releasing on PyPI, use the [testdist](https://github.com/NIRALUser/NeuroRuler/blob/main/testdist) script. If using macOS, run with `. ./testdist`. If using Windows, you may need to modify the script slightly.
You must test from a directory that isn't `NeuroRuler/`. If your directory is `NeuroRuler/`, then imports will import from the source code, not the package.
To publish to [PyPI](https://pypi.org/project/NeuroRuler/), edit the version number in [setup.py](https://github.com/NIRALUser/NeuroRuler/blob/main/setup.py). Then push to a branch called `release-pypi` (create it if it doesn't exist). This will trigger [pypi.yml](https://github.com/NIRALUser/NeuroRuler/blob/main/.github/workflows/pypi.yml), which will run tests and publish to PyPI if the tests pass.
To publish to [Test PyPI](https://test.pypi.org/project/NeuroRuler/), do the same as above, but push to a branch called `release-testpypi`.
If any of these files changes, they should be re-released on our GitHub release page: `gui.py`, `cli.py`, `gui_config.json`, `cli_config.json`.
Raw data
{
"_id": null,
"home_page": "https://github.com/NIRALUser/NeuroRuler",
"name": "NeuroRuler",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "MRI,NIfTI,NRRD,brain,circumference,PyQt6",
"author": "COMP523 Team D",
"author_email": "Peifeng He <hankhe@ad.unc.edu>, Madison Lester <madiali@email.unc.edu>, Eric Schneider <eric@cs.unc.edu>, Jesse Wei <jesse@cs.unc.edu>",
"download_url": "https://files.pythonhosted.org/packages/cb/4f/d68842970c791e062e8d6e51e995334913361db591f1d047e3b972186f7a/NeuroRuler-1.0.1.tar.gz",
"platform": null,
"description": "# NeuroRuler <span><img width=\"20\" src=\"https://i.imgur.com/pYlhHqu.png\"></span>\n\n\n\n\n\n\nNeuroRuler is a program that calculates head circumference from MRI data (`.nii`, `.nii.gz`, `.nrrd`).\n\n<p align=\"center\">\n <img src=\"https://i.imgur.com/nqwqHq8.gif\" alt=\"GUI demo\"/>\n</p>\n\n<p align=\"center\">\n <a href=\"https://www.youtube.com/watch?v=ZhSg5xwzbmo\"><img src=\"https://img.youtube.com/vi/ZhSg5xwzbmo/0.jpg\" alt=\"full demo video\"></a>\n</p>\n\n<p align=\"center\">\n <a href=\"https://www.youtube.com/watch?v=ZhSg5xwzbmo\">Full demo</a>\n</p>\n\n## Cite this tool\n\nIf you want \ud83d\ude09 format is bibtex.\n\n```bibtex\n@misc{neuroruler,\n title={NeuroRuler},\n author={Wei, Jesse and Lester, Madison and He, Peifeng and Schneider, Eric and Styner, Martin},\n howpublished={\\url{https://github.com/NIRALUser/NeuroRuler}},\n year={2023}\n}\n```\n\n## Install\n\nYour Python version needs to be 3.8+. Check with `python --version`. Install with pip.\n\n```sh\npip install NeuroRuler\n```\n\nIf `python` or `pip` don't work, try `python3` and `pip3`.\n\n## Usage\n\nDownload the latest [release](https://github.com/NIRALUser/NeuroRuler/releases).\n\nThe [gui.py](https://github.com/NIRALUser/NeuroRuler/blob/main/gui.py) and [cli.py](https://github.com/NIRALUser/NeuroRuler/blob/main/cli.py) scripts, further described below, are entry points for NeuroRuler's GUI and CLI.\n\n[gui_config.json](https://github.com/NIRALUser/NeuroRuler/blob/main/gui_config.json) and [cli_config.json](https://github.com/NIRALUser/NeuroRuler/blob/main/cli_config.json) set default settings for the GUI and CLI. `gui.py` and `cli.py` will create `gui_config.json` and `cli_config.json` if they don't exist. For more information, see [Configure default settings](#configure-default-settings).\n\n## For developers\n\nDevelopers contributing to the repository should clone the repository. `gui.py` and `cli.py` will then import from the local repository and reflect changes made to the codebase.\n\nDevelopers should also run `pip install -r requirements.txt` to install additional development dependencies and `pre-commit install` to install pre-commit git hooks.\n\n## Run GUI\n\n```sh\npython gui.py\n```\n\nRun `python gui.py -h` to see command-line options.\n\nThe GUI can also be run from any directory from a Python terminal. After opening a Python terminal, run these commands:\n\n```py\nfrom NeuroRuler.GUI import gui\ngui()\n```\n\n<p align=\"center\">Same as the code in <code>gui.py</code></p>\n\n## Run CLI\n\n```text\npython cli.py <file>\n```\n\nSee [test_cli.py](https://github.com/NIRALUser/NeuroRuler/blob/main/tests/test_cli.py) for example usages.\n\n```text\nusage: cli.py [-h] [-d] [-r] [-x X] [-y Y] [-z Z] [-s SLICE] [-c CONDUCTANCE] [-i ITERATIONS] [-t STEP] [-f FILTER] [-l LOWER]\n [-u UPPER]\n file\n\nA program that calculates head circumference from MRI data (``.nii``, ``.nii.gz``, ``.nrrd``).\n\npositional arguments:\n file file to compute circumference from, file format must be *.nii.gz, *.nii, or *.nrrd\n\noptions:\n -h, --help show this help message and exit\n -d, --debug print debug info\n -r, --raw print just the \"raw\" circumference\n -x X, --x X x rotation (in degrees)\n -y Y, --y Y y rotation (in degrees)\n -z Z, --z Z z rotation (in degrees)\n -s SLICE, --slice SLICE\n slice (Z slice, 0-indexed)\n -c CONDUCTANCE, --conductance CONDUCTANCE\n conductance smoothing parameter\n -i ITERATIONS, --iterations ITERATIONS\n smoothing iterations\n -t STEP, --step STEP time step (smoothing parameter)\n -f FILTER, --filter FILTER\n which filter to use (Otsu or binary), default is Otsu\n -l LOWER, --lower LOWER\n lower threshold for binary threshold\n -u UPPER, --upper UPPER\n upper threshold for binary threshold\n```\n\n<p align=\"center\">Output of <code>python cli.py -h</code> (could be outdated)</p>\n\n## Import/export image settings JSON\n\nIn the GUI's \"circumference mode\" (after clicking Apply), click the large Export button under the image to export image settings JSON file(s) containing the circumferences of all loaded images and the settings applied to each image.\n\nYou can then use File > Import Image Settings to import an image settings JSON to load the same image with the same settings.\n\nHere is an example:\n\n```py\n{\n \"input_image_path\": \"/Users/jesse/Documents/GitHub/COMP523/NeuroRuler/data/MicroBiome_1month_T1w.nii.gz\",\n \"output_contoured_slice_path\": \"/Users/jesse/Documents/GitHub/COMP523/NeuroRuler/output/MicroBiome_1month_T1w/MicroBiome_1month_T1w_contoured.png\",\n \"circumference\": 285.04478394448125,\n \"x_rotation\": -17,\n \"y_rotation\": -18,\n \"z_rotation\": 24,\n \"slice\": 131,\n \"smoothing_conductance\": 4.0,\n \"smoothing_iterations\": 10,\n \"smoothing_time_step\": 0.08,\n \"threshold_filter\": \"Otsu\"\n}\n```\n\nWhen multiple images are exported, the output directory structure looks like this:\n\n```text\noutput\n\u251c\u2500\u2500 150649_V06_t1w\n\u2502 \u251c\u2500\u2500 150649_V06_t1w_contoured.png\n\u2502 \u2514\u2500\u2500 150649_V06_t1w_settings.json\n\u2514\u2500\u2500 MicroBiome_1month_T1w\n \u251c\u2500\u2500 MicroBiome_1month_T1w_contoured.png\n \u2514\u2500\u2500 MicroBiome_1month_T1w_settings.json\n```\n\n## Configure default settings\n\nEdit the JSON configuration files [gui_config.json](https://github.com/NIRALUser/NeuroRuler/blob/main/gui_config.json) and [cli_config.json](https://github.com/NIRALUser/NeuroRuler/blob/main/cli_config.json). `gui.py` and `cli.py` will create these files if they don't exist.\n\nCommand-line arguments supplied to the [gui.py](https://github.com/NIRALUser/NeuroRuler/blob/main/gui.py) or [cli.py](https://github.com/NIRALUser/NeuroRuler/blob/main/cli.py) scripts override settings in the JSON configuration files. JSON settings are default values for the GUI and CLI: If a setting in the JSON file is not overriden by a CLI argument, the JSON file setting will be used.\n\n## Run tests\n\nTo test locally, run `pytest`.\n\nOur algorithm tests assert that our GUI calculations have at least a 0.98 R<sup>2</sup> value with ground truth data from the old Head Circumference Tool. We use a similar R<sup>2</sup> test to verify that our circumference result is correct for images with non-(1.0, 1.0, 1.0) pixel spacing. We verified manually (no unit test) that the GUI computes similar circumferences for (a, b, c) pixel spacing images generated from (1.0, 1.0, 1.0) pixel spacing images.\n\nTo test CLI, we test that our CLI produces the same results as the GUI.\n\nOur tests run on GitHub Actions on push and PR via `tox` ([tests.yml](https://github.com/NIRALUser/NeuroRuler/blob/main/.github/workflows/tests.yml)). If the image below says \"passing,\" then the tests are passing.\n\n<p align=\"center\">\n <img src=\"https://github.com/NIRALUser/NeuroRuler/actions/workflows/tests.yml/badge.svg\" alt=\"GitHub actions tests.yml badge\"/>\n</p>\n\n## Documentation\n\n[https://NeuroRuler.readthedocs.io](https://NeuroRuler.readthedocs.io)\n\nSee [.readthedocs.yaml](https://github.com/NIRALUser/NeuroRuler/blob/main/.readthedocs.yaml) and [docs/](https://github.com/NIRALUser/NeuroRuler/tree/main/docs) to contribute.\n\n[Team website](https://tarheels.live/comp523teamd/)\n\n## Release\n\nTo test the package locally before releasing on PyPI, use the [testdist](https://github.com/NIRALUser/NeuroRuler/blob/main/testdist) script. If using macOS, run with `. ./testdist`. If using Windows, you may need to modify the script slightly.\n\nYou must test from a directory that isn't `NeuroRuler/`. If your directory is `NeuroRuler/`, then imports will import from the source code, not the package.\n\nTo publish to [PyPI](https://pypi.org/project/NeuroRuler/), edit the version number in [setup.py](https://github.com/NIRALUser/NeuroRuler/blob/main/setup.py). Then push to a branch called `release-pypi` (create it if it doesn't exist). This will trigger [pypi.yml](https://github.com/NIRALUser/NeuroRuler/blob/main/.github/workflows/pypi.yml), which will run tests and publish to PyPI if the tests pass.\n\nTo publish to [Test PyPI](https://test.pypi.org/project/NeuroRuler/), do the same as above, but push to a branch called `release-testpypi`.\n\nIf any of these files changes, they should be re-released on our GitHub release page: `gui.py`, `cli.py`, `gui_config.json`, `cli_config.json`.\n",
"bugtrack_url": null,
"license": "",
"summary": "A program that calculates head circumference from MRI data (.nii, .nii.gz, .nrrd).",
"version": "1.0.1",
"project_urls": {
"Bug Tracker": "https://github.com/NIRALUser/NeuroRuler/issues",
"Download": "https://github.com/NIRALUser/NeuroRuler/releases",
"Homepage": "https://github.com/NIRALUser/NeuroRuler"
},
"split_keywords": [
"mri",
"nifti",
"nrrd",
"brain",
"circumference",
"pyqt6"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "96a7887e7a806c72cc655fc6d1d609e044daf3dd4e331a3113974235d7bff102",
"md5": "eb8646bcadfdb102b1a2f56abb9fabaa",
"sha256": "03ba4d6667ddcbc8ba71c867ae1dff45f24db7c2fd9e393b061133eebcb96b05"
},
"downloads": -1,
"filename": "NeuroRuler-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "eb8646bcadfdb102b1a2f56abb9fabaa",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 570814,
"upload_time": "2023-05-07T19:19:02",
"upload_time_iso_8601": "2023-05-07T19:19:02.029923Z",
"url": "https://files.pythonhosted.org/packages/96/a7/887e7a806c72cc655fc6d1d609e044daf3dd4e331a3113974235d7bff102/NeuroRuler-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "cb4fd68842970c791e062e8d6e51e995334913361db591f1d047e3b972186f7a",
"md5": "6cdbf521f99082eb94957c9ee89237b7",
"sha256": "a06d3c46abc7c6eb4165f744e36f61209e184352670eac5b6b2851b00c8e44e5"
},
"downloads": -1,
"filename": "NeuroRuler-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "6cdbf521f99082eb94957c9ee89237b7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 531589,
"upload_time": "2023-05-07T19:19:03",
"upload_time_iso_8601": "2023-05-07T19:19:03.650481Z",
"url": "https://files.pythonhosted.org/packages/cb/4f/d68842970c791e062e8d6e51e995334913361db591f1d047e3b972186f7a/NeuroRuler-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-07 19:19:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "NIRALUser",
"github_project": "NeuroRuler",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"tox": true,
"lcname": "neuroruler"
}
JSON
