ENH: Add transform analysis utils #286

jhlegarreta · 2025-11-01T14:58:45Z

Add transform analysis utils.

Transfer contents from the NiFreeze projects so that hey can be reused across projects requiring transform analysis:
https://github.com/nipreps/nifreeze/blob/d27ba7552bbd9095c3c13b46443d87a4b5504c4c/src/nifreeze/analysis/motion.py https://github.com/nipreps/nifreeze/blob/d27ba7552bbd9095c3c13b46443d87a4b5504c4c/src/nifreeze/data/utils.py

Add a fixture to be able to reuse a random number generator across tests.

Fixes #239.

jhlegarreta · 2025-11-01T15:00:41Z

I did not dare to create a data module the utils.py module at the root folder, as I do not know well the philosophy in this project, but let me know if it does belong to a data module.

I think the plotting should go to nireports.

codecov · 2025-11-01T18:31:48Z

Codecov Report

❌ Patch coverage is 0% with 86 lines in your changes missing coverage. Please review.
✅ Project coverage is 0.00%. Comparing base (9486757) to head (dab55cf).

Files with missing lines	Patch %	Lines
nitransforms/analysis/utils.py	0.00%	86 Missing ⚠️

❗ There is a different number of reports uploaded between BASE (9486757) and HEAD (dab55cf). Click for more details.

HEAD has 49 uploads less than BASE

Flag BASE (9486757) HEAD (dab55cf)

49 1

unittests 1 0

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #286       +/-   ##
==========================================
- Coverage   96.74%   0.00%   -96.75%     
==========================================
  Files          16      17        +1     
  Lines        1994    2079       +85     
  Branches      267       0      -267     
==========================================
- Hits         1929       0     -1929     
- Misses         41    2079     +2038     
+ Partials       24       0       -24

Flag	Coverage Δ
unittests	`?`

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

jhlegarreta · 2025-11-19T12:32:48Z

Pinging @oesteban.

nitransforms/utils.py

nitransforms/tests/test_utils.py

jhlegarreta · 2025-11-20T02:34:06Z

Then should we remove these files from NiFreeze?
https://github.com/nipreps/nifreeze/blob/6723229312850a73cbe9e4f31144ade3502535da/src/nifreeze/data/utils.py
https://github.com/nipreps/nifreeze/blob/6723229312850a73cbe9e4f31144ade3502535da/test/test_data_utils.py
and use nitransforms.resampling.apply in
https://github.com/nipreps/nifreeze/blob/6723229312850a73cbe9e4f31144ade3502535da/src/nifreeze/registration/utils.py#L74
and
https://github.com/nipreps/nifreeze/blob/6723229312850a73cbe9e4f31144ade3502535da/src/nifreeze/registration/utils.py#L113

oesteban · 2025-11-20T06:37:19Z

Then should we remove these files from NiFreeze?
https://github.com/nipreps/nifreeze/blob/6723229312850a73cbe9e4f31144ade3502535da/src/nifreeze/data/utils.py
https://github.com/nipreps/nifreeze/blob/6723229312850a73cbe9e4f31144ade3502535da/test/test_data_utils.py

Yes

and use nitransforms.resampling.apply in
https://github.com/nipreps/nifreeze/blob/6723229312850a73cbe9e4f31144ade3502535da/src/nifreeze/registration/utils.py#L74
and
https://github.com/nipreps/nifreeze/blob/6723229312850a73cbe9e4f31144ade3502535da/src/nifreeze/registration/utils.py#L113

No, if you look at it closer, you'll see this is using apply_affine from nibabel.affines, which is not the same (that applies affines to points, our apply in nitransforms and the apply_affines (notice the 's' at the end) in nifreeze apply affines to images (internally to points, but that's not relevant here).

oesteban

Thanks for the update. I just realized of a little inconsistency. Other than that, I think this is almost ready.

nitransforms/analysis/utils.py

jhlegarreta · 2025-11-20T12:49:25Z

Had a closer look at the apply_affines function: it calls nt.resampling.apply so ultimately its a wrapper around it to write transformed images to a NIfTI file. So, maybe it is useful if we rename/relocate it? Else, are there other nitransforms utils that do that job?

oesteban · 2025-11-20T13:04:31Z

Else, are there other nitransforms utils that do that job?

Yes, nitransforms.resampling.apply does the job. We created the apply_transforms wrapper in nifreeze because the multiple-volume resampling was not very well supported in nitransforms, but that changed.

jhlegarreta · 2025-12-27T22:29:07Z

This is ready to go. Merging this would allow NiFreeze to drop code that is general, and probably have better support as these functions may get better testing. We will need to set/bump a new min version for NiTransforms when a new version with these changes is released.

oesteban

We had a pretty hefty bug in the original implementation of nifreeze!

nitransforms/analysis/utils.py

nitransforms/tests/test_analysis.py

nitransforms/analysis/utils.py

Add transform analysis utils. Transfer contents from the `NiFreeze` projects so that hey can be reused across projects requiring transform analysis: https://github.com/nipreps/nifreeze/blob/d27ba7552bbd9095c3c13b46443d87a4b5504c4c/src/nifreeze/analysis/motion.py https://github.com/nipreps/nifreeze/blob/d27ba7552bbd9095c3c13b46443d87a4b5504c4c/src/nifreeze/data/utils.py Add a fixture to be able to reuse a random number generator across tests. Co-authored-by: Oscar Esteban <code@oscaresteban.es>

Co-authored-by: Oscar Esteban <code@oscaresteban.es>

Cite Power et al. in FD computation function docstring.

Fix style errors.

oesteban · 2026-01-04T18:51:07Z

@jhlegarreta please have one more look - I realized that the FD from transform matrices was also badly computed as it did not accept the previous transform. IMHO, we should also provide a "vectorized" version of FD such that you pass the list of transforms and gives you timeseries. Could be left for a future PR though.

@effigies added you to have an extra pair of eyes on this.

oesteban · 2026-01-04T18:52:51Z

nitransforms/analysis/utils.py

+    xfm: TransformBase,
+    xfm_prev: TransformBase | None = None,
+    radius: float = DEFAULT_FD_RADIUS,
+    n_vertices: int = 8,


It would be interesting to make the output match compute_fd_from_motion for n_vertices = 1.

jhlegarreta

IMHO, we should also provide a "vectorized" version of FD such that you pass the list of transforms and gives you timeseries. Could be left for a future PR though.

Better for a future PR. This is already better than what we have in NiFreeze (thanks for reviewing and the subsequent work), allows us to have a common, single authoritative location, and frees NiFreeze from hosting this.

Some inline comments about documentation and syntax highlighting.

nitransforms/analysis/utils.py

effigies · 2026-01-07T16:20:07Z

Out of curiosity, why are we standardizing on degrees? Apart from AFNI, everybody reports angles in radians. It seems to add unnecessary complication. Nipype also normalizes to SPM style (https://github.com/nipy/nipype/blob/8234ec318489930fa17487cf15d210420214b00a/nipype/utils/misc.py#L246-L271) so consistency within the nipy world seems desirable.

effigies · 2026-01-07T17:20:52Z

Another conceptual question: Do we want to continue the tradition of accepting an unlabeled Nx6 matrix, or would it be a good opportunity to require the caller to consider the it useful to have a function that accepts an Nx6 matrix, or would it make more sense to accept 2 Nx3 matrices and a radius? The reason I ask is that it would be very tempting to load an Nx6 matrix out of some transform file and pass it directly without carefully considering which are the translations and which are the rotations. I might think of the API as follows:

def framewise_displacement(
    translations: np.ndarray,
    rotations: np.ndarray,
    radius: float = DEFAULT_RADIUS
) -> np.ndarray:
    """Calculate framewise displacement of motion parameters. ..."""

def extract_parameters(motion_parameters: np.ndarray, fmt: str | None=None) -> tuple[np.ndarray, np.ndarray]:
    """Extract translation and rotation parameters from a parameter array.

    This function normalizes rotation parameters to radians, if the input format is known to use degrees.

    The parameters are returned in the order expected by the `framewise_displacement` function.
    """

# I know what my matrix is:
fd = framewise_displacement(motion_parameters[:, :3], motion_parameters[:, 3:])
# I know I got it from AFNI:
afni_fd = framewise_displacement(*extract_parameters(motion_parameters, fmt='afni'))

We could even force people to use labels instead and say:

@dataclass(kw_only=True)
class MotionParameters:
    rotations: np.ndarray
    translations: np.ndarray

def extract_parameters(motion_parameters: np.ndarray, fmt: str | None=None) -> MotionParameters: ...
def framewise_displacement(motion_parameters: MotionParameters, radius: float = DEFAULT_RADIUS) -> np.ndarray: ...

This would even suggest a straightforward translation between affines and motion parameters:

def affineToMotionParams(aff: Affine) -> MotionParameters: ...
def motionParamstoAffine(motion_parameters: MotionParameters) -> LinearTransformsMapping: ...

Just a couple thoughts. Will review the PR on the assumption that you'll stick with degrees and a big matrix.

nitransforms/analysis/utils.py

effigies · 2026-01-07T17:57:21Z

nitransforms/analysis/utils.py

+def extract_motion_parameters(affine: np.ndarray) -> Tuple[np.ndarray, np.ndarray]:
+    """Extract translation (mm) and rotation (degrees) parameters from an affine matrix.
+
+    Parameters
+    ----------
+    affine : :obj:`~numpy.ndarray`
+        The affine transformation matrix.
+
+    Returns
+    -------
+    :obj:`tuple`
+        Extracted translation and rotation parameters.
+    """
+
+    translation = affine[:3, 3]
+    rotation_rad = np.arctan2(
+        [affine[2, 1], affine[0, 2], affine[1, 0]],
+        [affine[2, 2], affine[0, 0], affine[1, 1]],
+    )
+    rotation_deg = np.rad2deg(rotation_rad)
+    return *translation, *rotation_deg


This isn't obviously correct to me. There are many ways of extracting angles from a rotation matrix, but I'm surprised that you seem able to get them using only 6 entries of a 3x3 matrix.

At the least, this function needs a citation, but I would be inclined to rely on scipy.spatial.transforms or transforms3d for this functionality.

Thanks, will investigate.

effigies · 2026-01-07T18:00:24Z

nitransforms/analysis/utils.py

+    numpy.ndarray
+        An array of shape ``(n_points, 3)`` whose rows have unit norm.
+
+    Examples


Would it be too much to ask for these docs to have plots to show the points on the unit sphere?

Sounds good, I'll see if it doesn't involve much or defer to a future PR.

effigies · 2026-01-07T18:20:41Z

nitransforms/analysis/utils.py

+    Identifies high-motion frames as timepoint exceeding a given threshold value
+    based on z-score normalized framewise displacement (FD) values.


Is there a citation for this one? This seems dubious to me, as z-scoring will amplify low-motion subjects' FD and suppress high-motion subjects' FD. For the purposes of censoring, absolute thresholds are often used based on voxel size.

I'm inclined to drop this function altogether. The purpose is not censoring, but rather identifying the higher trees in the forest.

nitransforms/analysis/utils.py

Co-authored-by: Chris Markiewicz <effigies@gmail.com>

jhlegarreta force-pushed the enh/add-transform-analysis-utils branch 3 times, most recently from 7fae796 to 73b27ba Compare November 1, 2025 18:19

jhlegarreta force-pushed the enh/add-transform-analysis-utils branch from 73b27ba to 86fa6af Compare November 19, 2025 12:32

oesteban reviewed Nov 19, 2025

View reviewed changes

nitransforms/utils.py Outdated Show resolved Hide resolved

nitransforms/tests/test_utils.py Outdated Show resolved Hide resolved

jhlegarreta force-pushed the enh/add-transform-analysis-utils branch from 86fa6af to 711146a Compare November 20, 2025 02:31

oesteban reviewed Nov 20, 2025

View reviewed changes

nitransforms/analysis/utils.py Outdated Show resolved Hide resolved

jhlegarreta force-pushed the enh/add-transform-analysis-utils branch from 04b0f77 to 8039887 Compare November 20, 2025 12:55

jhlegarreta force-pushed the enh/add-transform-analysis-utils branch 3 times, most recently from b71eac7 to f3236b7 Compare November 20, 2025 13:24

jhlegarreta force-pushed the enh/add-transform-analysis-utils branch 2 times, most recently from 66875cb to 8164b14 Compare December 8, 2025 23:55

jhlegarreta force-pushed the enh/add-transform-analysis-utils branch from 8164b14 to 98ec243 Compare December 27, 2025 22:25

oesteban reviewed Jan 3, 2026

View reviewed changes

jhlegarreta commented Jan 3, 2026

View reviewed changes

nitransforms/analysis/utils.py Outdated Show resolved Hide resolved

nitransforms/tests/test_analysis.py Outdated Show resolved Hide resolved

nitransforms/tests/test_analysis.py Outdated Show resolved Hide resolved

jhlegarreta commented Jan 3, 2026

View reviewed changes

nitransforms/analysis/utils.py Outdated Show resolved Hide resolved

oesteban force-pushed the enh/add-transform-analysis-utils branch 4 times, most recently from 079e6bc to 358dcec Compare January 4, 2026 16:25

jhlegarreta and others added 9 commits January 4, 2026 17:25

Apply suggestions from code review

fe68162

Co-authored-by: Oscar Esteban <code@oscaresteban.es>

DOC: Cite Power et al. in FD computation function docstring

7016e0b

Cite Power et al. in FD computation function docstring.

Update nitransforms/analysis/utils.py

9c48c5f

STY: Fix style errors

43cafbc

Fix style errors.

fix: generalize sampling on unit sphere computation

ee16315

fix: defensive increase of tolerance in FD test

e8b5783

doc: add missing modules to apidoc

f9744b9

tst: exercise all branches

c437e38

fix: address bug in compute_fd_from_transform

bacdc83

oesteban force-pushed the enh/add-transform-analysis-utils branch from 358dcec to bacdc83 Compare January 4, 2026 16:25

oesteban requested a review from effigies January 4, 2026 18:48

oesteban approved these changes Jan 4, 2026

View reviewed changes

jhlegarreta commented Jan 4, 2026

View reviewed changes

nitransforms/analysis/utils.py Outdated Show resolved Hide resolved

jhlegarreta added 2 commits January 4, 2026 15:50

Apply suggestions from code review

6799c9b

Apply suggestions from code review

bbf7bf9

effigies reviewed Jan 7, 2026

View reviewed changes

oesteban reviewed Jan 8, 2026

View reviewed changes

nitransforms/analysis/utils.py Outdated Show resolved Hide resolved

Apply suggestions from code review

dab55cf

Co-authored-by: Chris Markiewicz <effigies@gmail.com>

		Identifies high-motion frames as timepoint exceeding a given threshold value
		based on z-score normalized framewise displacement (FD) values.

ENH: Add transform analysis utils #286

Are you sure you want to change the base?

ENH: Add transform analysis utils #286

Uh oh!

Conversation

jhlegarreta commented Nov 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jhlegarreta commented Nov 1, 2025

Uh oh!

codecov bot commented Nov 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

jhlegarreta commented Nov 19, 2025

Uh oh!

Uh oh!

Uh oh!

jhlegarreta commented Nov 20, 2025

Uh oh!

oesteban commented Nov 20, 2025

Uh oh!

oesteban left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jhlegarreta commented Nov 20, 2025

Uh oh!

oesteban commented Nov 20, 2025

Uh oh!

jhlegarreta commented Dec 27, 2025

Uh oh!

oesteban left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

oesteban commented Jan 4, 2026

Uh oh!

oesteban Jan 4, 2026

Choose a reason for hiding this comment

Uh oh!

jhlegarreta left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

effigies commented Jan 7, 2026

Uh oh!

effigies commented Jan 7, 2026

Uh oh!

Uh oh!

Uh oh!

effigies Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

oesteban Jan 8, 2026

Choose a reason for hiding this comment

Uh oh!

effigies Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

oesteban Jan 8, 2026

Choose a reason for hiding this comment

Uh oh!

effigies Jan 7, 2026

jhlegarreta commented Nov 1, 2025 •

edited

Loading

codecov bot commented Nov 1, 2025 •

edited

Loading