NeuroRuler 1.0.0

A program that calculates head circumference from MRI data (.nii, .nii.gz, .nrrd).

NeuroRuler

NeuroRuler is a program that calculates head circumference from MRI data (.nii, .nii.gz, .nrrd).

Full demo

Cite this tool

If you want 😉 format is 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.

pip install NeuroRuler

If pip doesn't work, try pip3.

If contributing to this repo, clone/fork and run pip install -r requirements.txt to install additional development dependencies (for code formatting, documentation, etc.). After installing additional dependencies, run pre-commit install to enable pre-commit actions.

Run GUI

Run these commands in a Python terminal:

from NeuroRuler.GUI import gui
gui()

Note: If you make changes to the repo, use the gui.py script to run the GUI. Changes you make will not be reflected in the pip package until uploaded to PyPI.

Import/Export

In "circumference mode" (after clicking Apply), click Export to export JSON files containing the circumferences of all loaded images, along with the settings applied to each image.

You can then use File > Import MRI Settings to import a JSON file of this kind to load the same image with the same settings.

Configure settings

After cloning the repo, edit the JSON configuration files gui_config.json and cli_config.json.

You can also supply CLI arguments to the gui.py or cli.py scripts, which will override settings in the JSON configuration files.

Apply the -h command-line option when running those scripts to see the list of options. You can see some examples of CLI options in test_cli.py.

Run tests

To test locally, run pytest.

Our algorithm tests assert that our GUI calculations have at least a 0.98 R² value with ground truth data from the old Head Circumference Tool. Additionally, we test that our CLI and GUI produce the same results. Lastly, we verified that our circumference result is correct for images with non-(1.0, 1.0, 1.0) pixel spacing.

Our tests run on GitHub Actions on push and PR via tox (tests.yml). If the image below says "passing," then the tests are passing.

Documentation

https://NeuroRuler.readthedocs.io

See .readthedocs.yaml and docs/ to contribute.

Team website

Pre-commit actions

Run pre-commit install to enable pre-commit actions.

Before each commit, the actions in .pre-commit-config.yaml will be run. Specifically, code will be reformatted with black.

Note: Some file names are excluded, so don't name any source code files those names.

Release

To test the package locally before releasing, use scripts/testdist. If using macOS, run with . scripts/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, edit the version number in setup.py. Then push to a branch called release-pypi (create it if it doesn't exist). This will trigger pypi.yml, which will run tests and publish to PyPI if the tests pass.

To publish to Test PyPI, do the same as above, but push to a branch called release-testpypi.