diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md new file mode 100644 index 0000000..a7df7ae --- /dev/null +++ b/.github/ISSUE_TEMPLATE.md @@ -0,0 +1,8 @@ +## The problem + +Briefly describe the issue you are experiencing (or feature you want to see added). Tell us what you were trying to do and what happened instead. If you have any helpful screenshots or a file you tried to upload, please include them! Please also select an appropriate label (to the right). + +## Environment + +- Operating System +- Autoafids version diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..dfc4577 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,26 @@ +## Proposed changes + +Describe the changes implemented in this pull request. If the changes fix a bug or resolves a feature request, be sure to link the issue. Please explain the issue and how the changes address the issue. + +## Types of changes + +What types of changes does your code introduce? Put an `x` in the boxes that apply + +- [ ] Bugfix (non-breaking change which fixes an issue) +- [ ] New feature (non-breaking change which adds functionalitiy) +- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected) +- [ ] Other (if none of the other choices apply) + +## Checklist + +Put an `x` in the boxes that apply. You can also fill these out after creating the PR. If you are unsure about any of the choices, don't hesitate to ask! + +- [ ] Changes have been tested to ensure that fix is effective or that a feature works. +- [ ] Changes pass the unit tests +- [ ] Changes pass the wet run tests +- [ ] Code has been run through the `poe quality` task +- [ ] I have included necessary documentation or comments (as necessary) +- [ ] Any dependent changes have been merged and published + +## Notes +All PRs will undergo unit and wet run testing before being reviewed. You may be requested to explain or make additional changes before the PR is accepted. diff --git a/README.md b/README.md index 72ee87e..2208b16 100644 --- a/README.md +++ b/README.md @@ -1,36 +1,123 @@ # Automatic Anatomical Fiducials (AutoAFIDs) + [![Documentation Status](https://readthedocs.org/projects/autoafids/badge/?version=latest)](https://autoafids.readthedocs.io/en/stable/?badge=stable) ![Version](https://img.shields.io/github/v/tag/afids/autoafids?label=version) ![Python3](https://img.shields.io/badge/python-_3.9_|_3.10_|_3.11_|_3.12-blue.svg) [![Tests](https://github.com/afids/autoafids/actions/workflows/lint-and-dryrun-testing.yml/badge.svg?branch=main)](https://github.com/afids/autoafids/actions/workflows/lint-and-dryrun-testing.yml?query=branch%3Amain) -![Docker Pulls](https://img.shields.io/docker/pulls/dhananjhay/autoafids) +![Docker Pulls](https://img.shields.io/docker/pulls/jclauneurolab/autoafids) + +Developed by the AIMS Lab at the Robarts Research Institute +*2023–2025* + +> ⚠️ This package is under active development. While stable and reproducible, users are encouraged to report any bugs or unexpected behavior to the development team. + +--- + +## πŸ“‘ Table of Contents + +- [🧠 What is AutoAFIDs?](#what-is-autoafids) +- [βš™οΈ Workflow Overview](#workflow-overview) +- [πŸ” Known Issues](#known-issues) +- [πŸ“– Full Documentation](#full-documentation) +- [πŸ’¬ Questions, Issues, and Feedback](#questions-issues-and-feedback) +- [πŸ“š Relevant Papers](#relevant-papers) + +--- +## What is AutoAFIDs? + +**AutoAFIDs** is a BIDS App for automatic detection of anatomical fiducials (AFIDs) on MRI scans. We make use of these AFIDs in various neuroimaging applications such as image registration, quality control, and neurosurgical targeting. + +AutoAFIDs leverages: -AIMS Lab Research Team at the Robarts Research Institute - 2023-2025 +- A 3D [U-Net architecture](https://arxiv.org/abs/1505.04597) for landmark localization +- The [Snakemake](https://snakemake.readthedocs.io/) and [SnakeBIDS](https://snakebids.readthedocs.io/en/stable/) workflow frameworks for reproducible processing +- The AFIDs protocol developed by the [AFIDs community](https://github.com/afids) -*This package is under active development. It should be stable and reproducible, but please let any of the active contributing members know if there are any bugs or unusual behaviour.* +The software is modality-aware, but best supports T1-weighted MRI scans. It also includes QC visualizations for quality assurance. -This Python package is a standard 3D [U-Net](https://arxiv.org/abs/1505.04597) (Ronneberger et al. 2015) machine learning model based on Snakemake and SnakeBIDS workflow management tools that leverages the recent release of the anatomical fiducial framework to solve the landmark regression problem on 3D MRI images. It is currently in development phase and contains tunable parameters that are not normally exposed in most other machine learning models; the user is highly advised to get familiar with the above mentioned workflow managaments tools and read docstrings and relevant documentation before using this software. Please see the [changelog](CHANGELOG.md) for more details. +--- -## Workflow +## Workflow Overview -A brief summary of the workflow can be found below along with its Directed Acyclic Graph (DAG) (see documentation for a detailed summary): +Below is a high-level summary of the AutoAFIDs processing pipeline: ![Pipeline Overview](https://raw.githubusercontent.com//afids/autoafids/master/docs/images/dag.png) -1. Preprocess input NIfTI files based on image modality -2. Download and apply the fiducial model +1. Preprocess BIDS input files based on image modality (T1w, T2w) +2. Load trained fiducial models (32 AFID points) +3. Run patch-based U-Net inference per AFID +4. Generate predictions -## Processing landmark data (AFIDs) -1. Extract fiducial points from the landmark files (.fcsv is supported) -2. Generate a landmark Euclidean distance/probability map with each voxel communicating distance to an AFID of interest +--- ## Known Issues -- Factorize apply workflow to run per landmark of interest -### **Full documentation:** [here](https://autoafids.readthedocs.io/en/) +- `gen_fcsv` rule is currently sequential and may benefit from AFID-level parallelization +- T1w-like scan synthesis is available (via SynthSR [Iglesias et al., 2023](https://www-science-org.proxy1.lib.uwo.ca/doi/10.1126/sciadv.add3607)) but requires millimetric validation and may not work for all operating systems + +--- + +## Full Documentation + +πŸ‘‰ [autoafids.readthedocs.io](https://autoafids.readthedocs.io/en/) + +Includes installation instructions, usage examples, and advanced configuration. + +--- + +## Questions, Issues, and Feedback + +- Open an issue on the [GitHub issues page](https://github.com/afids/autoafids/issues) +- Start a conversation on the [Discussions board](https://github.com/afids/autoafids/discussions) +- Contact: [ataha24@uwo.ca](mailto:ataha24@uwo.ca) or [dbansal7@uwo.ca](mailto:dbansal7@uwo.ca) + +We welcome feedback, contributions, and collaboration! + + +## Relevant Papers + +AutoAFIDs builds upon a series of foundational works that introduce, validate, and apply the anatomical fiducials (AFIDs) framework for neuroimaging quality control, registration evaluation, and surgical planning. + +--- + +### Methodological Foundations + +- **Lau et al., 2019** + *A framework for evaluating correspondence between brain images using anatomical fiducials.* + *Human Brain Mapping*, 40(14), 4163–4179. + [DOI: 10.1002/hbm.24695](https://doi.org/10.1002/hbm.24695) + +--- + +### Clinical Applications + +- **Abbass et al., 2022** + *Application of the anatomical fiducials framework to a clinical dataset of patients with Parkinson’s disease.* + *Brain Structure & Function*, 227(1), 393–405. + [DOI: 10.1007/s00429-021-02408-3](https://doi-org.proxy1.lib.uwo.ca/10.1007/s00429-021-02408-3) + +- **Taha et al., 2022** + *An indirect deep brain stimulation targeting tool using salient anatomical fiducials.* + *Neuromodulation: Journal of the International Neuromodulation Society*, 25(8), S6–S7. + +--- + +### Dataset & Resource Publication + +- **Taha et al., 2023** + *Magnetic resonance imaging datasets with anatomical fiducials for quality control and registration.* + *Scientific Data*, 10(1), 449. + [DOI: 10.1038/s41597-023-02330-9](https://doi.org/10.1038/s41597-023-02330-9) + +--- + +### Registration and Localization Accuracy + +- **Abbass et al., 2025** + *The impact of localization and registration accuracy on estimates of deep brain stimulation electrode position in stereotactic space.* + *Imaging Neuroscience.* + [DOI: 10.1162/imag_a_00579](https://doi.org/10.1162/imag_a_00579) -## Revalent Papers: -* Link relavent papers to autoafids here +--- -## Questions, Issues, Suggestions, and Other Feedback -Please reach out if you have any questions, suggestions, or other feedback related to this softwareβ€”either through email (dbansal7@uwo.ca) or the discussions page. Larger issues or feature requests can be posted and tracked via the issues page. Finally, you can also reach out to Alaa Taha, the Science Lead. +> πŸ“Œ If you use AutoAFIDs or AFIDs data in your research, please cite the relevant papers above. \ No newline at end of file diff --git a/docs/contributing/contributing.md b/docs/contributing/contributing.md index 64831c0..e2f3580 100644 --- a/docs/contributing/contributing.md +++ b/docs/contributing/contributing.md @@ -1,79 +1,90 @@ -# Contributing to Autoafids +# Contributing to AutoAFIDs -Autoafids python package uses Poetry pacakge manager to manage its dependencies. You’ll need it installed on your machine before contributing to the software. Installation instructions can be found on the -[Poetry website](https://python-poetry.org/docs/master/#installation). +AutoAFIDs is a Python-based BIDS App for automatic anatomical fiducial detection. Development is managed using **Conda** for dependency and environment management. -Autoafids primarily caters to T1w modality images, in which case it doesn't need to depend on pacakges outside of python but for other modalities it has a single dependency outside of python, i.e., `synthsr`. +> πŸ› οΈ These instructions are intended for contributors making code changes to the AutoAFIDs codebase or using advanced features such as Snakemake cluster execution profiles. -Note: These instructions are only recommended if you are making changes to the Autoafids codebase and committing these back to the repository or if you are using Snakemake’s cluster execution profiles. +--- -## Setup the development environment +## πŸ“¦ Prerequisites -Once Poetry is available, clone this repository and install all dependencies (including `dev`): +Ensure **Conda** is installed on your system. You can install Miniconda or Anaconda by following the official guide: +πŸ‘‰ [https://docs.conda.io/projects/conda/en/latest/user-guide/install/index.html](https://docs.conda.io/projects/conda/en/latest/user-guide/install/index.html) -``` +Note: AutoAFIDs primarily supports T1-weighted images. For additional modalities (e.g., T2w), SynthSR will be triggered, though compatibility varies by operating system. + +## πŸ§ͺ Setting Up the Development Environment + +1. Clone the repository: + +```bash git clone https://github.com/afids/autoafids.git cd autoafids -poetry install --with dev ``` -Poetry will automatically create a virtual environment. To customize where -these virtual environments are stored, see the poetry docs -[here](https://python-poetry.org/docs/configuration/). - -Then, you can run autoafids: +2. Create and activate the development environment: -``` -autoafids -h +```bash +mamba env create -f autoafids-dev.yml +eval "$(mamba shell hook --shell zsh)" +mamba activate autoafids-dev ``` -or you can activate a virtual environment shell and run autoafids directly: +3. Run AutoAFIDs with development dependencies: -``` -poetry shell -autoafids +```bash +./autoafids/run.py -h ``` -You can exit the poetry shell with `exit` +--- -## Running and fixing code format quality -Autoafids uses [poethepoet](https://github.com/nat-n/poethepoet) as a task runner. -You can see what commands are available by running: +## 🧹 Code Quality and Formatting -``` -poetry run poe +AutoAFIDs uses several tools to ensure clean and consistent code: + +- [`ruff`](https://github.com/charliermarsh/ruff) – for linting and formatting +- [`snakefmt`](https://github.com/snakemake/snakefmt) – for formatting Snakemake files +- [`yamlfix`](https://github.com/lyz-code/yamlfix) – for YAML cleanup + +### Check formatting: + +```bash +ruff check . +snakefmt --check Snakefile +yamlfix --check config/ ``` -We use a few tools, including `ruff`, `snakefmt`, and `yamlfix` to ensure -formatting and style of our codebase is consistent. There are two task runners -you can use to check and fix your code, which can be invoked with: +### Auto-fix formatting: +```bash +ruff check . --fix +snakefmt Snakefile +yamlfix config/ ``` -poetry run poe quality-check -poetry run poe quality + +--- + +## πŸ§ͺ Dry Run / Workflow Testing + +To test the Snakemake workflow without running any jobs, use the built-in **dry-run** feature: + +```bash +./autoafids/run.py tests/data tests/output participant -n ``` -_Note: If you are in a poetry shell, you do not need to prepend `poetry run` to -the command._ +The `tests/data` directory contains a lightweight fake BIDS dataset (with zero-byte files) useful for testing the pipeline logic. -## Dry-run / testing your workflow +You can simulate more complex scenarios by modifying the `tests/` configuration and rerunning dry-runs with `--modality` and other options. -Using Snakemake\'s dry-run option (`--dry-run`/`-n`) is an easy way to verify -any changes made to the workflow are working direcctly. The `tests/data` folder -contains a _fake_ BIDS dataset (i.e. dataset with zero-sized files) that is -useful for verifying different aspects of the workflow. These dry-run tests are -part of the automated Github actions that are run for every commit. +--- -You can invoke the pre-configured task via -[poethepoet](https://github.com/nat-n/poethepoet) to perform a dry-run: +## πŸ™‹ Questions, Issues, and Feedback -``` -poetry run poe test_base -``` +We welcome all forms of feedback and contributions. -This performs a number of tests, involving different scenarios in which a user -may use autoafids. +- πŸ’¬ For questions or suggestions, use the [Discussions](https://github.com/afids/autoafids/discussions) page. +- πŸ› For bugs or feature requests, open an issue on the [Issues](https://github.com/afids/autoafids/issues) page. +- πŸ“§ You may also contact [dbansal7@uwo.ca](mailto:dbansal7@uwo.ca) or reach out to **Alaa Taha**, the Science Lead. -## Questions, Issues, Suggestions, and Other Feedback -Please reach out if you have any questions, suggestions, or other feedback related to this softwareβ€”either through email (dbansal7@uwo.ca) or the discussions page. Larger issues or feature requests can be posted and tracked via the issues page. Finally, you can also reach out to Alaa Taha, the Science Lead. \ No newline at end of file +Thanks for helping improve AutoAFIDs! \ No newline at end of file diff --git a/docs/getting_started/apptainer.md b/docs/getting_started/apptainer.md index 44d55b4..6bc6a4d 100644 --- a/docs/getting_started/apptainer.md +++ b/docs/getting_started/apptainer.md @@ -1,53 +1,82 @@ # Running AutoAFIDs with Apptainer (Singularity) -## Pre-requisities: - 1. Apptainer (or Singularity) is installed on your system. For more info, see the detailed [apptainer install instructions](https://apptainer.org/docs/admin/main/installation.html#install-from-pre-built-packages). - 2. The following command-line tools are installed: - - wget - - tar - 3. Sufficient disk-space - - in your `/tmp` folder (>15GB) to build the container - - in your working folder to store the container (~15GB) - - for AutoAFIDs outputs (~1GB per subject) - 4. Sufficient CPU and memory - the more you have, the faster it will run, but we recommend at least 4 CPU cores and 16GB memory. +## Prerequisites +Before running AutoAFIDs with Apptainer (formerly Singularity), ensure the following requirements are met: -## First time setup +1. **Apptainer is installed.** + See the official [Apptainer installation guide](https://apptainer.org/docs/admin/main/installation.html#install-from-pre-built-packages) for instructions. -Pull the container: +2. **Required command-line tools are installed:** + - `wget` + - `tar` - apptainer pull jclauneurolab_autoafids_1.1.0.sif docker://dhananjhay/autoafids:1.1.0 +3. **Sufficient disk space is available:** + - At least **15 GB** free in `/tmp` to build the container + - At least **15 GB** in your working directory to store the `.sif` container + - Approximately **1 GB per subject** for AutoAFIDs output +4. **Adequate CPU and memory:** + - Minimum: 4 CPU cores and 16 GB RAM + - More resources will improve performance -Run AutoAFIDs without any arguments to print the short help: - apptainer run -e jclauneurolab_autoafids_1.1.0.sif +## First-Time Setup -Use the `-h` option to get a detailed help listing: +### πŸ”„ Pull the container - apptainer run -e jclauneurolab_autoafids_1.1.0.sif -h +```bash +apptainer pull autoafids.sif docker://jclauneurolab/autoafids +``` + +### πŸš€ Run AutoAFIDs + +Run without arguments to see a short help message: + +```bash +apptainer run -e jclauneurolab_autoafids_1.1.0.sif +``` + +Get detailed help with the `-h` flag: + +```bash +apptainer run -e jclauneurolab_autoafids_1.1.0.sif -h +``` + +List available Snakemake-specific options using: + +```bash +apptainer run -e jclauneurolab_autoafids_1.1.0.sif --help-snakemake +``` + +--- + +### ⚠️ Troubleshooting: Pull Errors + +If you encounter errors while pulling the container, it may be due to insufficient disk space in your Apptainer cache directories. -Note that all the Snakemake command-line options are also available in -AutoAFIDs, and can be listed with `--help-snakemake`: +You can redirect the cache location by setting the following environment variable: - apptainer run -e jclauneurolab_autoafids_1.1.0.sif --help-snakemake +```bash +export APPTAINER_CACHEDIR=/your/custom/path/.cache/apptainer +``` + +> πŸ’‘ **Tip:** Avoid using network file systems (e.g., NFS) for the cache directory, as this may lead to performance issues or errors during image creation. -Note: If you encounter any errors pulling the container from dockerhub, it may be because you are running -out of disk space in your cache folders. Note, you can change these locations -by setting environment variables, however, using a network file system for the folders may result in poor performance and/or errors e.g.: - - export APPTAINER_CACHEDIR=/YOURDIR/.cache/apptainer -## Running an example +## Running an Example -Download and extract a single-subject BIDS dataset for this test: +### πŸ“₯ Download a Sample Dataset - wget "https://www.dropbox.com/scl/fi/phmmofiy4q6o1k01rs6c4/ds003653.tar?rlkey=bpa8fxfl0lyrdc38fs6aowta7&st=zvhpqsga&dl=1" -O ds003653.tar - tar -xvf ds003653.tar +Download and extract a single-subject BIDS dataset: + +```bash +wget "https://www.dropbox.com/scl/fi/phmmofiy4q6o1k01rs6c4/ds003653.tar?rlkey=bpa8fxfl0lyrdc38fs6aowta7&st=zvhpqsga&dl=1" -O ds003653.tar +tar -xvf ds003653.tar +``` -This will create a `ds003653/` folder with a single subject, that has a -both T1w and T2w images: +This will create a `ds003653/` folder containing a single subject with both T1w and T2w images: ``` ds003653/ @@ -62,61 +91,74 @@ ds003653/ β”‚Β Β  └── sub-718211_ses-01_T2w.nii.gz β”œβ”€β”€ sub-718211_ses-01_scans.json └── sub-718211_ses-01_scans.tsv +``` + +--- + +### πŸš€ Run AutoAFIDs -3 directories, 8 files +Run the following command to perform a dry-run with the T1w image: + +```bash +apptainer run -e jclauneurolab_autoafids_1.1.0.sif ds003653 ds003653_autoafids participant -n --modality T1 ``` -Now let's run AutoAFIDs. +#### πŸ” Explanation - apptainer run -e jclauneurolab_autoafids_1.1.0.sif ds003653 ds003653_autoafids participant -n --modality T1 -Explanation: +Everything **before** the container name is passed to Apptainer. Everything **after** is passed to AutoAFIDs: -Everything prior to the container (`jclauneurolab_autoafids_1.1.0.sif`) are arguments to apptainer, and after are to AutoAFIDs itself. The first three arguments to AutoAFIDs (as with any BIDS App) are the input -folder (`ds003653`), the output folder (`ds003653_autoafids`), and then the analysis level (`participant`). The `participant` analysis -level is used in AutoAFIDs for performing any -participant-level processing. Here -we used the T1w image. We also used the `--dry-run/-n` option to -just print out what would run, without actually running anything. +- `ds003653`: input folder +- `ds003653_autoafids`: output folder +- `participant`: analysis level +- `--modality T1`: use T1w image +- `-n`: dry-run mode (no processing, just show steps) +To inspect the rule graph more interactively: -When you run the above command, a long listing will print out, describing all the rules that -will be run. This is a long listing, and you can better appreciate it with the `less` tool. We can -also have the shell command used for each rule printed to screen using the `-p` Snakemake option: +```bash +apptainer run -e jclauneurolab_autoafids_1.1.0.sif ds003653 ds003653_autoafids participant -np | less +``` - apptainer run -e jclauneurolab_autoafids_1.1.0.sif ds003653 ds003653_autoafids participant -np | less +To actually run the pipeline, remove `-n` and specify the number of cores: +```bash +apptainer run -e jclauneurolab_autoafids_1.1.0.sif ds003653 ds003653_autoafids participant -p --cores all +``` -Now, to actually run the workflow, we need to specify how many cores to use and leave out -the dry-run option. The Snakemake `--cores` option tells AutoAFIDs how many cores to use. - Using `--cores 8` means that AutoAFIDs will only make use of 8 cores at most. Generally speaking -you should use `--cores all`, so it can make maximal use of all the CPU cores it has access to on your system. This is especially -useful if you are running multiple subjects. +> πŸ’‘ We recommend `--cores all` to utilize all available CPU cores. This speeds up processing, especially for multi-subject datasets. -Running the following command (autoafids on a single subject) may take ~6 minutes if you have 8 cores, shorter if you have more -cores, but could be much longer (several hours) if you only have a single core. +--- +### βš™οΈ Apptainer Bind Paths - apptainer run -e jclauneurolab_autoafids_1.1.0.sif ds003653 ds003653_autoafids participant -p --cores all +Make sure input/output folders are accessible inside the container. You can bind host paths using: +```bash +export APPTAINER_BINDPATH=/data:/data +``` -Note that you may need to adjust your [Singularity options](https://sylabs.io/guides/3.1/user-guide/cli/apptainer_run.html) to ensure the container can read and write to yout input and output directories, respectively. You can bind paths easily by setting an -environment variable, e.g. if you have a `/project` folder that contains your data, you can add it to the `APPTAINER_BINDPATH` so it is available when you are running a container: +Adjust paths as needed for your system. - export APPTAINER_BINDPATH=/data:/data +--- +### πŸ“‚ After Completion +Upon completion, the `ds003653_autoafids/` folder will contain output files for the processed subject. -After this completes, you should have a `ds003653_autoafids` folder with outputs for the one subject. +--- -## Exploring different options +## Exploring Different Options + +To run AutoAFIDs using the T2w image (or CT and FLAIR) instead: + +```bash +apptainer run -e jclauneurolab_autoafids_1.1.0.sif ds003653 ds003653_autoafids_t2w participant --modality T2w -p --cores all +``` -If you alternatively want to run AutoAFIDs using a different modality, e.g. the high-resolution T2w image -in the BIDS test dataset, you can use the `--modality T2w` option. The T2w image would be then first pre-processesed into T1w using SynthSR and then used as an input image for predicting AFIDs. +> ⚠️ Use a **separate output folder** when running with a different modality, as outputs may be overwritten. - apptainer run -e jclauneurolab_autoafids_1.1.0.sif ds003653 ds003653_autoafids_t2w participant --modality T2w -p --cores all +When using `--modality T2w`, the T2w image will first be synthesized into a T1-like image using **SynthSR**, then used for fiducial prediction. -Note that if you run with a different modality, you should use a separate output folder, since some of the files -would be overwritten if not. diff --git a/docs/getting_started/conda.md b/docs/getting_started/conda.md index 4e727e4..3328a38 100644 --- a/docs/getting_started/conda.md +++ b/docs/getting_started/conda.md @@ -1,18 +1,19 @@ -# Running AutoAFIDS with Conda +# Running AutoAFIDs with Conda AutoAFIDs can be installed and run using Conda on **Linux and macOS** systems. -**Note:** Conda installation is **not supported on Windows** at this time. If you are on Windows, please refer to the [Docker instructions](docker.md) instead. +> **Note:** Conda installation is **not supported on Windows and M1 chip** at this time. +> If you are on Windows or M1 chip on Mac, please refer to the [Docker instructions](docker.md) instead. --- ## For Users: Installing AutoAFIDs via Conda -These steps are intended for **end users** who simply want to run AutoAFIDs and get their AFIDs. +These steps are intended for **end users** who simply want to run AutoAFIDs and get their AFIDs (+ other derivative apps). ### 1. Install Conda (if not already installed) -Follow the instructions at the official Conda documentation: +Follow the instructions at the official Conda documentation: [https://docs.conda.io/projects/conda/en/latest/user-guide/install/index.html](https://docs.conda.io/projects/conda/en/latest/user-guide/install/index.html) --- @@ -39,7 +40,9 @@ autoafids -h You should see a help message listing all available command-line options. If this runs successfully, you’re ready to start processing data with AutoAFIDs! -## Running an example +--- + +## Running an Example You can try AutoAFIDs on a sample dataset to make sure everything works as expected. @@ -65,33 +68,37 @@ ds003653/ β”‚Β Β  └── sub-718211_ses-01_T2w.nii.gz β”œβ”€β”€ sub-718211_ses-01_scans.json └── sub-718211_ses-01_scans.tsv - -3 directories, 8 files ``` -### Run the full AutoAFIDs BIDS pipeline +--- + +### Run the Full AutoAFIDs BIDS Pipeline -By default (Linux or Intel-based macOS), you can run: +By default (Linux or Intel-based macOS), run: ```bash autoafids ds003653 ds003653_autoafids participant --cores all ``` -This should run the full pipeline and place results in a new `ds003653_autoafids/` folder. +This will run the full pipeline and place results in a new `ds003653_autoafids/` folder. -If you’re on an M-chip mac, prefix with CONDA_SUBDIR=osx-64 to ensure compatibility: +#### For M2 (Apple Silicon) Macs + +Prefix with `CONDA_SUBDIR=osx-64` to force compatibility: ```bash CONDA_SUBDIR=osx-64 autoafids ds003653 ds003653_autoafids participant --cores all ``` -Note: AutoAFIDs on M-chip mac currently only supports the T1w modality. Other modalities (e.g., T2w, FLAIR) are not yet processed by this pipeline. + +> ⚠️ **Note:** AutoAFIDs on Apple Silicon currently only supports the T1w modality. +> Other modalities (e.g., T2w, FLAIR) are not yet supported on this platform. ## Cache Directory -When running, AutoAFIDs automatically downloads and caches necessary SynthSR repo and CNN model to speed up subsequent runs. +When running, AutoAFIDs automatically downloads and caches the necessary CNN model to speed up subsequent runs. -By default, these are stored in the following directory: +By default, it's stored in the following directory: ```bash ~/.cache/autoafids/ @@ -161,4 +168,3 @@ If you encounter issues while setting up AutoAFIDs via Conda: --- -Happy AFIDs placing! diff --git a/docs/getting_started/docker.md b/docs/getting_started/docker.md index dacb44f..70d6fea 100644 --- a/docs/getting_started/docker.md +++ b/docs/getting_started/docker.md @@ -1,8 +1,13 @@ # Running AutoAFIDs with Docker on Windows -Note: These instructions assume you have Docker installed already on a Windows system. Docker can also run on Linux or MacOS with similar commands, but here we will assume the default Windows CLI is being used. +> 🐳 These instructions assume Docker is already installed on your Windows system. +> Docker also works on Linux and macOS with similar commands, but this guide assumes usage via the Windows Command Prompt (CMD). -## First time setup +--- + +## πŸ› οΈ First-Time Setup + +### 1. Open the Command Prompt and Pull Container Open your Windows Command Prompt by clicking the bottom left `Windows` button and type `cmd` followed by `Enter`. This is where you will enter your AutoAFIDs commands. Feel free to make a new directory with `mkdir` or move to a directory you would like to work out of with `cd`, and for this example we will work from: @@ -10,22 +15,22 @@ Open your Windows Command Prompt by clicking the bottom left `Windows` button an Pull the container (this will take some time and storage space, but like an installation it only needs to be done once and can then be run on many datasets): - docker pull dhananjhay/autoafids:1.1.0 + docker pull jclauneurolab/autoafids Run AutoAFIDs without any arguments to print the short help: - docker run -it --rm dhananjhay/autoafids:1.1.0 + docker run -it --rm jclauneurolab/autoafids Use the `-h` option to get a detailed help listing: - docker run -it --rm dhananjhay/autoafids:1.1.0 -h + docker run -it --rm jclauneurolab/autoafids -h Note that all the Snakemake command-line options are also available in AutoAFIDs, and can be listed with `--help-snakemake`: - docker run -it --rm dhananjhay/autoafids:1.1.0 --help-snakemake + docker run -it --rm jclauneurolab/autoafids --help-snakemake -## Running an example +### 2. Example Download and extract a single-subject BIDS dataset for this test from [ds003653.tar](https://www.dropbox.com/scl/fi/phmmofiy4q6o1k01rs6c4/ds003653.tar?rlkey=bpa8fxfl0lyrdc38fs6aowta7&st=zvhpqsga&dl=1"). Here we will also assume you chose to save and extract to the directory `c:\Users\dhananjhay\Downloads\`. @@ -50,13 +55,13 @@ ds003653/ Now let's run AutoAFIDs on the test dataset. Docker will need read/write access to the input and output directories, respectively. This is achieved with the `-v` flag. This 'binds' or 'mounts' a directory to a new directory inside the container. - docker run -it --rm -v c:\Users\dhananjhay\Downloads\ds003653:/bids -v c:\Users\dhananjhay\Downloads\ds003653_autoafids:/output dhananjhay/autoafids:1.1.0 /bids /output participant -n + docker run -it --rm -v c:\Users\dhananjhay\Downloads\ds003653:/bids -v c:\Users\dhananjhay\Downloads\ds003653_autoafids:/output jclauneurolab/autoafids /bids /output participant -n Explanation: `-v c:\Users\dhananjhay\Downloads\ds003653:/bids` tells Docker to mount the directory `c:\Users\dhananjhay\Downloads\ds003653` into a new directory inside the container named `/bids`. We then do the same things for our output directory named `ds003653_autoafids`, which we mount to `/output` inside the container. These arguments are not specific to AutoAFIDs but rather are general ways to use Docker. You may want to familiarize yourself with [Docker options](https://docs.docker.com/engine/reference/run/). -Everything after we specified the container (`dhananjhay/autoafids:1.1.0`) are arguments to AutoAFIDs itself. The first of these arguments (as with any BIDS App) are the input directory (`/bids`), the output directory (`/output`), and then the analysis level (`participant`). The `participant` analysis +Everything after we specified the container (`jclauneurolab/autoafids`) are arguments to AutoAFIDs itself. The first of these arguments (as with any BIDS App) are the input directory (`/bids`), the output directory (`/output`), and then the analysis level (`participant`). The `participant` analysis level is used in AutoAFIDs for performing any participant-level processing. We also used the `--dry-run/-n` option to just print out what would run, without actually running anything. When you run the above command, a long listing will print out, describing all the rules that @@ -69,7 +74,7 @@ useful if you are running multiple subjects. Running the following command (autoafids on a single subject) may take ~6 minutes if you have 8 cores, shorter if you have more cores, but could be much longer (several hours) if you only have a single core. - docker run -it --rm -v c:\Users\dhananjhay\Downloads\ds003653:/bids -v c:\Users\dhananjhay\Downloads\ds003653_autoafids:/output dhananjhay/autoafids:1.1.0 /bids /output participant -p --cores all + docker run -it --rm -v c:\Users\dhananjhay\Downloads\ds003653:/bids -v c:\Users\dhananjhay\Downloads\ds003653_autoafids:/output jclauneurolab/autoafids /bids /output participant -p --cores all After this completes, you should have a `ds003653_autoafids` directory with outputs for the one subject. @@ -78,7 +83,7 @@ After this completes, you should have a `ds003653_autoafids` directory with outp If you alternatively want to run AutoAFIDs using a different modality, e.g. the high-resolution T2w image in the BIDS test dataset, you can use the `--modality T2w` option. The T2w image would be then first pre-processesed into T1w using SynthSR and then used as an input image for predicting AFIDs. - docker run -it --rm -v c:\Users\dhananjhay\Downloads\ds003653:/bids -v c:\Users\dhananjhay\Downloads\ds003653_autoafids_t2w:/output dhananjhay/autoafids:1.1.0 /bids /output participant --modality T2w -p --cores all + docker run -it --rm -v c:\Users\dhananjhay\Downloads\ds003653:/bids -v c:\Users\dhananjhay\Downloads\ds003653_autoafids_t2w:/output jclauneurolab/autoafids /bids /output participant --modality T2w -p --cores all Note that if you run with a different modality, you should use a separate output directory, since some of the files would be overwritten if not. diff --git a/docs/getting_started/installation.md b/docs/getting_started/installation.md index f393ee7..50198a1 100644 --- a/docs/getting_started/installation.md +++ b/docs/getting_started/installation.md @@ -1,63 +1,82 @@ # Installation -## BIDS App for Automatic Anatomical Fiducials (AutoAFIDs) +## AutoAFIDs: A BIDS App for Automatic Landmark Localization -### Requirements +***AutoAFIDs*** is a BIDS App that automatically detects anatomical landmarks in the human brain. It is trained to predict the coordinates of a standardized set of well-validated anatomical landmarks (e.g., the anterior and posterior commissures). -AutoAFIDs can be run either with Conda, or with containers -- Conda (Linux/Mac only, no containers needed) -- **--OR--** Docker (Intel Mac/Windows/Linux) or Apptainer (formerly known as Singularity) (Linux) -- For those wishing to contribute or modify the code, see [Contributing to AutoAFIDs](https://autoafids.readthedocs.io/en/latest/contributing/contributing.html). -- GPU not required -- ⚠️ Warning: Local installation on Apple M1 is currently not supported. You can still run the pipeline by building a docker container, but it'll be an emulated amd64 container and fairly slow. +--- -### Notes -- Inputs to AutoAFIDs should be a BIDS-formatted dataset. -- The output includes fiducial markers that are automatically positioned at standardized anatomical landmarks. +## 🧰 System Requirements -## Comparison of methods for running AutoAFIDs +we support three modes for installing ***AutoAFIDs***: -There are several different ways of running AutoAFIDs: +| Method | OS Support | Container Needed | Editable | Cluster Profiles | Notes | +|-----------------------|-----------------------------|------------------|----------|------------------|---------------------------------------| +| **Conda** | Linux, macOS (Intel & M2 only) | ❌ No | βœ… Yes | βœ… Yes | Recommended for most local setups | +| **Docker** | Windows, macOS (Intel/Silicon) | βœ… Yes | ❌ No | ❌ No | Works cross-platform (slow on M1) | +| **Singularity/Apptainer** | Linux only | βœ… Yes | ❌ No | ❌ No | Good for HPC or shared environments | -1. Conda Environment (Linux/macOS) -2. Apptainer/Singularity Container on Linux -3. Docker Container on Windows/Mac (Intel)/Linux +> πŸ’‘ **Note:** GPU is *not* required. +> ⚠️ **Apple Silicon (M1):** Native Conda support is not available. You can use Docker with emulated `amd64`, but performance will be slow. -## Conda +If you're interested in contributing to development, see the [Contributing Guide](https://autoafids.readthedocs.io/en/latest/contributing/contributing.html). -AutoAFIDs is available via [Conda](https://docs.conda.io/), offering a container-free way to run the tool on Linux and macOS systems. +--- -### Pros: -- No need for any containers -- Easy to install via `conda` -- Compatible with Snakemake execution profiles -- Good option for users who prefer Python virtual environments +## πŸ“‚ Inputs and Outputs -### Cons: -- Not compatible with Windows -- Requires installation of Conda or Miniconda +- **Input:** BIDS-formatted dataset containing structural MRI images (best on T1-weighted modalities). +- **Output:** Automatically placed anatomical fiducials (AFIDs) saved as structured coordinate files and visualizations (if using `--fidqc` flag). -## Docker on Windows/macOS/Linux +--- -The AutoAFIDs BIDS App is available as a Docker container. Instructions can be found in the [Docker](https://autoafids.readthedocs.io/en/latest/getting_started/docker.html) documentation page. +## πŸš€ Installation Methods -### Pros -- Compatible with non-Linux systems, including Apple Silicon (M1, M2) -- All dependencies are contained within a single container +### πŸ”§ 1. Conda Environment (Linux/macOS) -### Cons -- Typically not possible on shared machines -- Cannot use Snakemake cluster execution profiles -- Cannot edit code within the container +AutoAFIDs can be installed via [Conda](https://docs.conda.io/) for container-free execution on Linux and Intel macOS systems. -## Singularity Container +πŸ“˜ [Conda Installtion Instructions](https://autoafids.readthedocs.io/en/latest/getting_started/conda.html) -The same Docker container can also be used with Singularity (now Apptainer). Instructions can be found in the [Singularity](https://autoafids.readthedocs.io/en/latest/getting_started/singularity.html) documentation page. -### Pros -- All dependencies are packaged within a single `.sif` file -- Compatible with shared systems where Singularity is installed +**βœ… Pros:** +- Easy to install and run +- Fully editable code +- Works with Snakemake profiles -### Cons -- Cannot use Snakemake cluster execution profiles -- Cannot edit code within the container \ No newline at end of file +**⚠️ Cons:** +- Not supported on Windows or Apple Silicon (M1) system +- Requires Conda or Miniconda + +--- + +### 🐳 2. Docker Container (Windows/Linux/macOS Intel) + +A pre-built Docker container is available with all dependencies bundled. + +πŸ“˜ [Docker Setup Instructions](https://autoafids.readthedocs.io/en/latest/getting_started/docker.html) + +**βœ… Pros:** +- Cross-platform support, including limited M1 compatibility via emulation +- All dependencies packaged in a single file + +**⚠️ Cons:** +- Cannot edit code inside the container +- Not compatible with Snakemake cluster execution +- May not be usable on shared systems (e.g., university clusters) + +--- + +### πŸ§ͺ 3. Singularity / Apptainer (Linux) + +Use [Singularity](https://apptainer.org/) (now Apptainer) to convert the Docker image into a `.sif` file for HPC or institutional clusters. + +πŸ“˜ [Singularity Setup Instructions](https://autoafids.readthedocs.io/en/latest/getting_started/singularity.html) + +**βœ… Pros:** +- Ideal for shared Linux systems +- All dependencies packaged in a single file + +**⚠️ Cons:** +- Cannot edit code inside the container +- Not compatible with Snakemake cluster execution