README.md

Anatomical Fiducials (AFIDs) Utility Tools

The afids-utils package provides common utilities for projects involving anatomical fiducials (AFIDs). For a comprehensive list of available utilities refer to the documentation page.

Installation

afids-utils can be installed using pip:

pip install afids-utils

To also include plotting functionality (this will install matplotlib, plotly, and nilearn):

pip install afids-utils[plotting]

Contributing

afids-utils is an open-source project and contributions are welcome! If you have any bug reports, feature requests, or improvement suggestions, please submit them to the issues page.

To contribute, first click the "fork" button to create your own copy of the repository and then clone the project to your local machine:

git clone https://github.com/your-username/afids-utils.git

Navigate to the location where the directory was cloned and add the upstream repository:

cd afids-utils

git remote add upstream https://github.com/afids/afids-utils.git

Now, git remote -v will show two remote repositories:

• upstream, referring to the afids repository
• origin, your personal fork

To the pull the latest changes from the code:

git checkout main
git pull upstream main

To develop and push your contribution to your copy of the repository:

git checkout -b contribution-name
git push origin contribution-name

Once pushed, a pull request can be opened, at which point the contribution will be reviewed by a maintainer of the afids-utils repository.

Poetry

afids-utils depedencies are managed with Poetry - please refer to the Poetry website for installation instructions. Following the installation of Poetry, the development environment can be set up from the local repository location by running the following commands:

poetry install --with dev --all-extras

Poetry uses poethepoet as a task runner. You can see what commands are available by running:

poetry run poe

Tests are performed with pytest and can be run via:

poetry run poe test

Additionally, afids-utils makes use of a number of libraries to lint and format code, which can be invoked by running the following:

poetry run poe setup

This sets up a pre-commit hook, which runs the necessary checks every time a commit is performed. Alternatively, if you don't wish to use the pre-commit hook, you can run the following manually, which performs the same checks:

poetry run poe quality

Please ensure these all pass before making a pull request.