Merge branch 'main' into maint/update-nitransforms-pin

Author: oesteban

.github/workflows/test.yml

@@ -115,7 +115,7 @@ jobs:
           # Override libiconv pre-installed from anaconda channel
           # See https://github.com/conda-forge/libitk-feedstock/issues/98
           # Since we're not creating a new environment, we must be explicit
-          conda install -c conda-forge ants=2.5 libiconv
+          conda install -c conda-forge ants=2.4 libitk=5.3 libiconv
       - name: Verify antsRegistration path
         run: |
           export PATH=$ANTSPATH:$PATH

AGENTS.md

@@ -0,0 +1,107 @@
+<!--
+Copyright The NiPreps Developers <[email protected]>
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+We support and encourage derived works from this project, please read
+about our expectations at
+
+    https://www.nipreps.org/community/licensing/
+-->
+
+# AGENTS instructions
+
+The project's source code lives under `src/nifreeze/` and tests under `tests/`.
+
+## Testing
+
+### Pre-requisites
+
+- Bootstrap version metadata (which will create an `src/nifreeze/_version.py` file):
+  ```
+  python -m hatch version
+  ```
+
+- Some software needs to be installed prior to testing, for example ANTs
+  ```
+  conda install -c conda-forge ants=2.4 libitk=5.3 libiconv
+  ```
+- Notebooks generate figures with latex commands inside, therefore:
+  ```
+  sudo apt install texlive texlive-latex-extra texlive-fonts-recommended cm-super dvipng
+  ```
+- A number of tests use pre-existing data (stored in the git-annex-enabled GIN G-Node https://gin.g-node.org/nipreps-data/tests-nifreeze) that need be found at location indicated by the environment variable `TEST_DATA_HOME`:
+  ```
+  uvx datalad-installer --sudo ok git-annex
+  uv tool install --with=datalad-osf --with=datalad-next datalad
+  uv tool install --with=datalad-next datalad-osf
+  datalad wtf  # check datalad is installed
+
+  # Install the dataset
+  if [[ ! -d "${TEST_DATA_HOME}" ]]; then
+      datalad install -rg --source=https://gin.g-node.org/nipreps-data/tests-nifreeze ${TEST_DATA_HOME}
+  else
+      cd ${TEST_DATA_HOME}
+      datalad update --merge -r .
+      datalad get -r -J4 *
+  fi
+  ```
+  Files in GIN's annex can be retrieved using curl by composing the URL like this one for the [`dmri_data/motion_test_data/dwi_motion.h5` file](https://gin.g-node.org/nipreps-data/tests-nifreeze/raw/master/dmri_data/motion_test_data/dwi_motion.h5)
+
+- Some test data comes from DIPY:
+  ```
+  echo "from dipy.data import fetch_stanford_hardi; fetch_stanford_hardi()" > fetch.py
+  uv tool install dipy
+  uv add --script fetch.py dipy
+  uv run fetch.py
+  ```
+
+Details about testing are found in `.github/workflows/test.yml`
+
+### Unit tests
+
+- Unit tests can be executed with pytest: `pytest tests/`.
+- The project includes doctests, which can be run with `pytest --doctest-module src/nifreeze`
+
+### Integration tests and benchmarks
+
+- The full battery of tests can be run through tox (`tox -v`)
+- Install tox using `uv tool install --with=tox-uv --with=tox-gh-actions tox`
+
+## Documentation building
+
+Documentation can be built as described in `.github/workflows/docs-build-pr.yml`.
+
+## Linting
+
+Before accepting new PRs, we use the latest version of Ruff to lint the code, as in `.github/workflows/contrib.yml`:
+
+- Check correctness:
+  ```
+  pipx run ruff check --fix <files>
+  ```
+- Reformat:
+  ```
+  pipx run ruff format <files>
+  ```
+
+## Codex instructions
+
+- Always plan first
+- Think harder in the planning phase
+- When proposing tasks, highlight potential critical points that could lead to side effects.
+
+## Commits and PRs
+
+- Commit messages should follow the semantic commit conventions, and at least, contain one line with the following format: `<type-code>: <message>` where `<type-code>` indicates the type of comment. Type of comments can be fixes and bugfixes (`fix:`), enhancements and new features (`enh:`), style (`sty:`), documentation (`doc:`), maintenance (`mnt:`), etc.
+- PR titles should also be semantic, and use the same Type codes but in all caps (e.g., `FIX:`, `ENH:`, `STY:`, `DOC:`, `STY:`, `MNT:`)

docs/notebooks/data_structures.ipynb

@@ -93,7 +93,7 @@
     }
    ],
    "source": [
-    "plot_gradients(dwi.gradients.T);"
+    "plot_gradients(dwi.gradients);"
    ]
   },
   {
@@ -192,7 +192,7 @@
     }
    ],
    "source": [
-    "plot_gradients(dwi.gradients.T);"
+    "plot_gradients(dwi.gradients);"
    ]
   },
   {
@@ -213,7 +213,7 @@
    ],
    "source": [
     "# Select a b-value\n",
-    "b2000_gradientmask = dwi.gradients[-1, ...] == 2000\n",
+    "b2000_gradientmask = dwi.gradients[:, -1] == 2000\n",
     "\n",
     "# Select b=2000\n",
     "data, _, grad = dwi[b2000_gradientmask]\n",

docs/notebooks/pet_motion_estimation.ipynb

@@ -2428,10 +2428,11 @@
    ]
   },
   {
-   "metadata": {},
    "cell_type": "code",
-   "outputs": [],
    "execution_count": null,
+   "id": "d3627d44376b27f4",
+   "metadata": {},
+   "outputs": [],
    "source": [
     "import numpy as np\n",
     "import pandas as pd\n",
@@ -2441,20 +2442,20 @@
     "# Assume `affines` is the list of affine matrices computed earlier\n",
     "motion_parameters = []\n",
     "\n",
-    "for idx, affine in enumerate(affines):\n",
+    "for _idx, affine in enumerate(affines):\n",
     "    tx, ty, tz, rx, ry, rz = extract_motion_parameters(affine)\n",
     "    motion_parameters.append([tx, ty, tz, rx, ry, rz])\n",
     "\n",
     "motion_parameters = np.array(motion_parameters)\n",
     "estimated_fd = compute_fd_from_motion(motion_parameters)"
-   ],
-   "id": "d3627d44376b27f4"
+   ]
   },
   {
-   "metadata": {},
    "cell_type": "code",
-   "outputs": [],
    "execution_count": null,
+   "id": "4f141ebdb1643673",
+   "metadata": {},
+   "outputs": [],
    "source": [
     "# Set up the matplotlib figure\n",
     "import matplotlib.pyplot as plt\n",
@@ -2466,20 +2467,20 @@
     "plot_volumewise_motion(np.arange(len(estimated_fd)), motion_parameters)\n",
     "\n",
     "plt.show()"
-   ],
-   "id": "4f141ebdb1643673"
+   ]
   },
   {
-   "metadata": {},
    "cell_type": "markdown",
-   "source": "For the dataset used in this example, we have access to the ground truth motion parameters that were used to corrupt the motion-free dataset. Let's now plot the ground truth motion to enable a visual comparison with the estimated motion.",
-   "id": "e3f45164598d16f0"
+   "id": "e3f45164598d16f0",
+   "metadata": {},
+   "source": "For the dataset used in this example, we have access to the ground truth motion parameters that were used to corrupt the motion-free dataset. Let's now plot the ground truth motion to enable a visual comparison with the estimated motion."
   },
   {
-   "metadata": {},
    "cell_type": "code",
-   "outputs": [],
    "execution_count": null,
+   "id": "1009ea77e1bdd0ee",
+   "metadata": {},
+   "outputs": [],
    "source": [
     "from nifreeze.viz.motion_viz import plot_volumewise_motion\n",
     "\n",
@@ -2505,14 +2506,13 @@
     "\n",
     "plt.tight_layout()\n",
     "plt.show()"
-   ],
-   "id": "1009ea77e1bdd0ee"
+   ]
   },
   {
-   "metadata": {},
    "cell_type": "markdown",
-   "source": "Let's plot the estimated and the ground truth framewise displacement.",
-   "id": "113b4b4d1361b5ec"
+   "id": "113b4b4d1361b5ec",
+   "metadata": {},
+   "source": "Let's plot the estimated and the ground truth framewise displacement."
   },
   {
    "cell_type": "code",

docs/usage.rst

@@ -34,10 +34,11 @@ To utilize *NiFreeze* functionalities within your Python module or script, follo
    Use the appropriate parameters for the particular imaging modality (e.g.
    dMRI, fMRI, or PET) that you are using.
 
-   For example, for dMRI data, ensure the gradient table is provided. It
-   should have one column per diffusion-weighted image. The first three rows
-   represent the gradient directions, and the last row indicates the timing
-   and strength of the gradients in units of s/mm² ``[ R A S+ b ]``.
+   For example, for dMRI data, ensure the gradient table is provided. NiFreeze
+   expects the table to have one row per diffusion-weighted image, with the
+   first three columns storing the gradient direction components and the last
+   column indicating the timing and strength of the gradients in units of
+   s/mm² ``[ R A S+ b ]``.
 
    .. code-block:: python
 

src/nifreeze/data/base.py

@@ -101,7 +101,7 @@ def __len__(self) -> int:
 
     def _getextra(self, idx: int | slice | tuple | np.ndarray) -> tuple[Unpack[Ts]]:
         """
-        Extracts extra fields synchronized with the indexed access of the corresponding data object.
+        Extract extra fields for a given index of the corresponding data object.
 
         Parameters
         ----------