antspymm 1.5.2__py3-none-any.whl → 1.5.4__py3-none-any.whl

antspymm/__init__.py

@@ -135,5 +135,6 @@ from .mm import fix_LR_RL_stuff
 from .mm import segment_timeseries_by_bvalue
 from .mm import shorten_pymm_names
 from .mm import pet3d_summary
+from .mm import deformation_gradient_optimized
 
 

antspymm/mm.py

@@ -2195,62 +2195,206 @@ def dti_numpy_to_image( reference_image, tensorarray, upper_triangular=True):
     ants.copy_image_info( reference_image, dtiAnts )
     return dtiAnts
 
-def transform_and_reorient_dti( fixed, moving_dti, composite_transform, py_based=True, verbose=False, **kwargs):
+
+def deformation_gradient_optimized(warp_image, to_rotation=False, to_inverse_rotation=False):
     """
-    apply a transform to DTI in the style of ants.apply_transforms. this function
-        expects a pre-computed composite transform which it will use to reorient 
-        the DTI using preservation of principle directions.
-    
-    fixed : antsImage reference space
+    Compute the deformation gradient tensor from a displacement (warp) field image.
 
-    moving_dti : antsImage DTI in upper triangular format
+    This function computes the **deformation gradient** `F = ∂φ/∂x` where `φ(x) = x + u(x)` is the mapping
+    induced by the displacement field `u(x)` stored in `warp_image`.
 
-    composite_transform : should be a composition of all transforms to be applied stored on disk ( a filename ) ... might change this in the future.
+    The returned tensor field has shape `(x, y, z, dim, dim)` (for 3D), where each matrix represents 
+    the **Jacobian** of the transformation at that voxel. The gradient is computed in the physical space 
+    of the image using spacing and direction metadata.
 
-    py_based : boolean
+    Optionally, the deformation gradient can be projected onto the space of pure rotations using the polar
+    decomposition (via SVD). This is useful for applications like reorientation of tensors (e.g., DTI).
 
-    verbose : boolean
+    Parameters
+    ----------
+    warp_image : ants.ANTsImage
+        A vector-valued ANTsImage encoding the warp/displacement field. It must have `dim` components
+        (e.g., shape `(x, y, z, 3)` for 3D) representing the displacements in each spatial direction.
+        
+    to_rotation : bool, optional
+        If True, the deformation gradient will be replaced with its **nearest rotation matrix**
+        using the polar decomposition (`F → R`, where `F = R U`).
+        
+    to_inverse_rotation : bool, optional
+        If True, the deformation gradient will be replaced with the **inverse of the rotation**
+        (`F → R.T`), which is often needed for transforming tensors **back** to their original frame.
+
+    Returns
+    -------
+    F : np.ndarray
+        A NumPy array of shape `(x, y, z, dim, dim)` (or `(dim1, dim2, ..., dim, dim)` in general),
+        representing the deformation gradient tensor field at each voxel.
+
+    Raises
+    ------
+    RuntimeError
+        If `warp_image` is not an `ants.ANTsImage`.
+
+    Notes
+    -----
+    - The function computes gradients in physical space using the spacing of the image and applies 
+      the image direction matrix (`tdir`) to properly orient gradients.
+    - The gradient is added to the identity matrix to yield the deformation gradient `F = I + ∂u/∂x`.
+    - The polar decomposition ensures `F` is replaced with the closest rotation matrix (orthogonal, det=1).
+    - This is a **vectorized pure NumPy implementation**, intended for performance and simplicity.
+
+    Examples
+    --------
+    >>> warp = ants.create_warp_image(reference_image, displacement_field)
+    >>> F = deformation_gradient_optimized(warp)
+    >>> R = deformation_gradient_optimized(warp, to_rotation=True)
+    >>> Rinv = deformation_gradient_optimized(warp, to_inverse_rotation=True)
+    """
+    if not ants.is_image(warp_image):
+        raise RuntimeError("antsimage is required")
+    dim = warp_image.dimension
+    tshp = warp_image.shape
+    tdir = warp_image.direction
+    spc = warp_image.spacing
+    warpnp = warp_image.numpy()
+    gradient_list = [np.gradient(warpnp[..., k], *spc, axis=range(dim)) for k in range(dim)]
+    # This correctly calculates J.T, where dg[..., i, j] = d(u_j)/d(x_i)
+    dg = np.stack([np.stack(grad_k, axis=-1) for grad_k in gradient_list], axis=-1)
+    dg = (tdir @ dg).swapaxes(-1, -2)
+    dg += np.eye(dim)
+    if to_rotation or to_inverse_rotation:
+        U, s, Vh = np.linalg.svd(dg)
+        Z = U @ Vh
+        dets = np.linalg.det(Z)
+        reflection_mask = dets < 0
+        Vh[reflection_mask, -1, :] *= -1
+        Z[reflection_mask] = U[reflection_mask] @ Vh[reflection_mask]
+        dg = Z
+        if to_inverse_rotation:
+            dg = np.transpose(dg, axes=(*range(dg.ndim - 2), dg.ndim - 1, dg.ndim - 2))
+    new_shape = tshp + (dim,dim)
+    return np.reshape(dg, new_shape)
+
+
+def transform_and_reorient_dti( fixed, moving_dti, composite_transform, verbose=False, **kwargs):
+    """
+    Applies a transformation to a DTI image using an ANTs composite transform,
+    including local tensor reorientation via the Finite Strain method.
+
+    This function expects:
+    - Input `moving_dti` to be a 6-component ANTsImage (upper triangular format).
+    - `composite_transform` to point to an ANTs-readable transform file,
+      which maps points from `fixed` space to `moving` space.
 
-    **kwargs : passed to ants.apply_transforms
+    Args:
+        fixed (ants.ANTsImage): The reference space image (defines the output grid).
+        moving_dti (ants.ANTsImage): The input DTI (6-component), to be transformed.
+        composite_transform (str): File path to an ANTs transform
+                                   (e.g., from `ants.read_transform` or a written composite transform).
+        verbose (bool): Whether to print verbose output during execution.
+        **kwargs: Additional keyword arguments passed to `ants.apply_transforms`.
 
+    Returns:
+        ants.ANTsImage: The transformed and reoriented DTI image in the `fixed` space,
+                        in 6-component upper triangular format.
     """
     if moving_dti.dimension != 3:
-        raise ValueError('moving image should have 3 dimensions')
+        raise ValueError('moving_dti must be 3-dimensional.')
     if moving_dti.components != 6:
-        raise ValueError('moving image should have 6 components')
-    # now apply the transform to the template
-    # 1. transform the tensor components
+        raise ValueError('moving_dti must have 6 components (upper triangular format).')
+
+    if verbose:
+        print("1. Spatially transforming DTI scalar components from moving to fixed space...")
+
+    # ants.apply_transforms resamples the *values* of each DTI component from 'moving_dti'
+    # onto the grid of 'fixed'.
+    # The output 'dtiw' will have the same spatial metadata (spacing, origin, direction) as 'fixed'.
+    # However, the tensor values contained within it are still oriented as they were in
+    # 'moving_dti's original image space, not 'fixed' image space, and certainly not yet reoriented
+    # by the local deformation.
     dtsplit = moving_dti.split_channels()
-    dtiw = []
+    dtiw_channels = []
     for k in range(len(dtsplit)):
-        dtiw.append( ants.apply_transforms( fixed, dtsplit[k], composite_transform ) )
-    dtiw=ants.merge_channels(dtiw)
+        dtiw_channels.append( ants.apply_transforms( fixed, dtsplit[k], composite_transform, **kwargs ) )
+    dtiw = ants.merge_channels(dtiw_channels)
+    
     if verbose:
-        print("reorient tensors locally: compose and get reo image")
-    locrot = ants.deformation_gradient( ants.image_read(composite_transform), 
-        to_rotation = True, py_based=py_based ).numpy()
-    rebaser = np.dot( np.transpose( fixed.direction  ), moving_dti.direction )
+        print(f"   DTI scalar components resampled to fixed grid. Result shape: {dtiw.shape}")
+        print("2. Computing local rotation field from composite transform...")
+    
+    # Read the composite transform as an image (assumed to be a displacement field).
+    # The 'deformation_gradient_optimized' function is assumed to be 100% correct,
+    # meaning it returns the appropriate local rotation matrix field (R_moving_to_fixed)
+    # in (spatial_dims..., 3, 3 ) format when called with these flags.
+    wtx = ants.image_read(composite_transform)
+    R_moving_to_fixed_forward = deformation_gradient_optimized(
+        wtx,
+        to_rotation=False,      # This means the *deformation gradient* F=I+J is computed first.
+        to_inverse_rotation=True # This requests the inverse of the rotation part of F.
+    )
+
     if verbose:
-        print("convert UT to full tensor")
-    dtiw2tensor = triangular_to_tensor( dtiw )
+        print(f"   Local reorientation matrices (R_moving_to_fixed_forward) computed. Shape: {R_moving_to_fixed_forward.shape}")
+        print("3. Converting 6-component DTI to full 3x3 tensors for vectorized reorientation...")
+    
+    # Convert `dtiw` (resampled, but still in moving-image-space orientation)
+    # from 6-components to full 3x3 tensor representation.
+    # dtiw2tensor_np will have shape (spatial_dims..., 3, 3).
+    dtiw2tensor_np = triangular_to_tensor(dtiw)
+    
     if verbose:
-        print("rebase tensors to new space via iterator")
-    it = np.ndindex( fixed.shape )
-    for i in it:
-        # direction * dt * direction.transpose();
-        mmm = dtiw2tensor[i]
-        # transform rebase
-        locrotx = np.reshape( locrot[i], [3,3] )
-        mmm = np.dot( mmm, np.transpose( locrotx ) )
-        mmm = np.dot( locrotx, mmm )
-        # physical space rebase
-        mmm = np.dot( mmm, np.transpose( rebaser ) )
-        mmm = np.dot( rebaser, mmm )
-        dtiw2tensor[i] = mmm
+        print("4. Applying vectorized tensor reorientation (Finite Strain Method)...")
+    
+    # --- Vectorized Tensor Reorientation ---
+    # This replaces the entire `for i in it:` loop and its contents with efficient NumPy operations.
+
+    # Step 4.1: Rebase tensors from `moving_dti.direction` coordinate system to World Coordinates.
+    # D_world_moving_orient = moving_dti.direction @ D_moving_image_frame @ moving_dti.direction.T
+    # This transforms the tensor's components from being relative to `moving_dti`'s image axes
+    # (where they are currently defined) into absolute World (physical) coordinates.
+    D_world_moving_orient = np.einsum(
+        'ab, ...bc, cd -> ...ad',
+        moving_dti.direction,            # 3x3 matrix (moving_image_axes -> world_axes)
+        dtiw2tensor_np,                  # (spatial_dims..., 3, 3)
+        moving_dti.direction.T           # 3x3 matrix (world_axes -> moving_image_axes) - inverse of moving_dti.direction
+    )
+
+    # Step 4.2: Apply local rotation in World Coordinates (Finite Strain Reorientation).
+    # D_reoriented_world = R_moving_to_fixed_forward @ D_world_moving_orient @ (R_moving_to_fixed_forward).T
+    # This is the core reorientation step, transforming the tensor's orientation from
+    # the original `moving` space to the new `fixed` space, all within world coordinates.
+    D_world_fixed_orient = np.einsum(
+        '...ab, ...bc, ...cd -> ...ad',
+        R_moving_to_fixed_forward,      # (spatial_dims..., 3, 3) - local rotation
+        D_world_moving_orient,          # (spatial_dims..., 3, 3) - tensor in world space, moving_orient
+        np.swapaxes(R_moving_to_fixed_forward, -1, -2) # (spatial_dims..., 3, 3) - transpose of local rotation
+    )
+
+    # Step 4.3: Rebase reoriented tensors from World Coordinates to `fixed.direction` coordinate system.
+    # D_final_fixed_image_frame = (fixed.direction).T @ D_world_fixed_orient @ fixed.direction
+    # This transforms the tensor's components from absolute World (physical) coordinates
+    # back into `fixed.direction`'s image coordinate system.
+    final_dti_tensors_numpy = np.einsum(
+        'ba, ...bc, cd -> ...ad',
+        fixed.direction,                # Using `fixed.direction` here, but 'ba' indices specify to use its transpose.
+        D_world_fixed_orient,           # (spatial_dims..., 3, 3)
+        fixed.direction                 # 3x3 matrix (world_axes -> fixed_image_axes)
+    )
+
     if verbose:
-        print("done with rebasing")
-    return dti_numpy_to_image( fixed, dtiw2tensor )
+        print("   Vectorized tensor reorientation complete.")
 
+    if verbose:
+        print("5. Converting reoriented full tensors back to 6-component ANTsImage...")
+    
+    # Convert the final (spatial_dims..., 3, 3) NumPy array of tensors back into a
+    # 6-component ANTsImage with the correct spatial metadata from `fixed`.
+    final_dti_image = dti_numpy_to_image(fixed, final_dti_tensors_numpy)
+    
+    if verbose:
+        print(f"Done. Final reoriented DTI image in fixed space generated. Shape: {final_dti_image.shape}")
+
+    return final_dti_image
 
 def dti_reg(
     image,
@@ -2769,7 +2913,7 @@ def template_figure_with_overlay(scalar_label_df, prefix, outputfilename=None, t
     toviz = temp['overlay']
     return { "underlay": seggm, 'overlay': toviz, 'seg': tcrop  }
 
-def get_data( name=None, force_download=False, version=25, target_extension='.csv' ):
+def get_data( name=None, force_download=False, version=26, target_extension='.csv' ):
     """
     Get ANTsPyMM data filename
 
@@ -6510,7 +6654,37 @@ def bold_perfusion_minimal(
   return convert_np_in_dict( outdict )
 
 
-def bold_perfusion( fmri, t1head, t1, t1segmentation, t1dktcit,
+
+def warn_if_small_mask( mask: ants.ANTsImage, threshold_fraction: float = 0.05, label: str = ' ' ):
+    """
+    Warn the user if the number of non-zero voxels in the mask
+    is less than a given fraction of the total number of voxels in the mask.
+
+    Parameters
+    ----------
+    mask : ants.ANTsImage
+        The binary mask to evaluate.
+    threshold_fraction : float, optional
+        Fraction threshold below which a warning is triggered (default is 0.05).
+    
+    Returns
+    -------
+    None
+    """
+    import warnings
+    image_size = np.prod(mask.shape)
+    mask_size = np.count_nonzero(mask.numpy())
+    if mask_size / image_size < threshold_fraction:
+        percentage = 100.0 * mask_size / image_size
+        warnings.warn(
+            f"[ants] Warning: {label} contains only {mask_size} voxels "
+            f"({percentage:.2f}% of image volume). "
+            f"This is below the threshold of {threshold_fraction * 100:.2f}% and may lead to unreliable results.",
+            UserWarning
+        )
+
+def bold_perfusion( 
+    fmri, t1head, t1, t1segmentation, t1dktcit,
                    FD_threshold=0.5,
                    spa = (0., 0., 0., 0.),
                    nc = 3,
@@ -6711,11 +6885,18 @@ def bold_perfusion( fmri, t1head, t1, t1segmentation, t1dktcit,
       newspc = [minspc,minspc,minspc]
       fmri_template = ants.resample_image( fmri_template, newspc, interp_type=0 )
 
+  if verbose:
+      print( 'fmri_template')
+      print( fmri_template )
+
   rig = ants.registration( fmri_template, t1head, 'BOLDRigid' )
   bmask = ants.apply_transforms( fmri_template, 
     ants.threshold_image(t1segmentation,1,6), 
     rig['fwdtransforms'][0], 
     interpolator='genericLabel' )
+
+  warn_if_small_mask( bmask, label='bold_perfusion:bmask')
+
   corrmo = timeseries_reg(
         fmri, fmri_template,
         type_of_transform=type_of_transform,
@@ -6739,6 +6920,7 @@ def bold_perfusion( fmri, t1head, t1, t1segmentation, t1dktcit,
   mytsnrThresh = np.quantile( mytsnr.numpy(), 0.995 )
   tsnrmask = ants.threshold_image( mytsnr, 0, mytsnrThresh ).morphology("close",3)
   bmask = bmask * ants.iMath( tsnrmask, "FillHoles" )
+  warn_if_small_mask( bmask, label='bold_perfusion:bmask*tsnrmask')
   fmrimotcorr=corrmo['motion_corrected']
   und = fmri_template * bmask
   t1reg = ants.registration( und, t1, "SyNBold" )
@@ -6751,13 +6933,16 @@ def bold_perfusion( fmri, t1head, t1, t1segmentation, t1dktcit,
   csfseg = ants.threshold_image( t1segmentation, 1, 1 )
   wmseg = ants.threshold_image( t1segmentation, 3, 3 )
   csfAndWM = ( csfseg + wmseg ).morphology("erode",1)
+  compcorquantile=0.50
   csfAndWM = ants.apply_transforms( und, csfAndWM,
     t1reg['fwdtransforms'], interpolator = 'nearestNeighbor' )  * bmask
   csfseg = ants.apply_transforms( und, csfseg,
     t1reg['fwdtransforms'], interpolator = 'nearestNeighbor' )  * bmask
   wmseg = ants.apply_transforms( und, wmseg,
     t1reg['fwdtransforms'], interpolator = 'nearestNeighbor' )  * bmask
-  compcorquantile=0.50
+  warn_if_small_mask( wmseg, label='bold_perfusion:wmseg')
+  # warn_if_small_mask( csfseg, threshold_fraction=0.01, label='bold_perfusion:csfseg')
+  warn_if_small_mask( csfAndWM, label='bold_perfusion:csfAndWM')
   mycompcor = ants.compcor( fmrimotcorr,
     ncompcor=nc, quantile=compcorquantile, mask = csfAndWM,
     filter_type='polynomial', degree=2 )
@@ -7606,7 +7791,7 @@ def mm(
                 if srmodel is not None:
                     tspc=[1.,1.,1.]
                 group_template2mm = ants.resample_image( group_template, tspc  )
-                normalization_dict['DTI_norm'] = transform_and_reorient_dti( group_template2mm, mydti['dti'], comptx, py_based=True, verbose=True )
+                normalization_dict['DTI_norm'] = transform_and_reorient_dti( group_template2mm, mydti['dti'], comptx, verbose=False )
             import shutil
             shutil.rmtree(output_directory, ignore_errors=True )
         if output_dict['rsf'] is not None:

{antspymm-1.5.2.dist-info → antspymm-1.5.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: antspymm
-Version: 1.5.2
+Version: 1.5.4
 Summary: multi-channel/time-series medical image processing with antspyx
 Author-email: "Avants, Gosselin, Tustison, Reardon" <stnava@gmail.com>
 License: Apache-2.0
@@ -197,6 +197,8 @@ NOTE: an example process for BIDS data on a cluster is [here](https://github.com
 
 # example processing
 
+see discussion [here](https://github.com/ANTsX/ANTsPyMM/issues/26) for the organization of tests and examples.
+
 see the latest help but this snippet gives an idea of how one might use the package:
 
 ```python

antspymm-1.5.4.dist-info/RECORD

@@ -0,0 +1,7 @@
+antspymm/__init__.py,sha256=hynrdvZDlPQ0Wam8tU6mBtbEk0Worwz_bLZk9N7N1CM,4684
+antspymm/mm.py,sha256=e4BTBarPnlk3RlqMAPOp6wcGZxv5ufSA1GxuKi3oiJw,536471
+antspymm-1.5.4.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+antspymm-1.5.4.dist-info/METADATA,sha256=2NNkAHHTSMIhla6KURkKU39w9CqxWrDshuHzOI2kMdc,26051
+antspymm-1.5.4.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+antspymm-1.5.4.dist-info/top_level.txt,sha256=iyD1sRhCKzfwKRJLq5ZUeV9xsv1cGQl8Ejp6QwXM1Zg,9
+antspymm-1.5.4.dist-info/RECORD,,

antspymm-1.5.2.dist-info/RECORD

@@ -1,7 +0,0 @@
-antspymm/__init__.py,sha256=DnkidUfEu3Dl0tuWNTA-9VOUkBtH_cROKiPGNNXNagU,4637
-antspymm/mm.py,sha256=NbT1IBiuEMtMoanr_8yO3kLNpSSfV0j1_155gykGOM0,526972
-antspymm-1.5.2.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-antspymm-1.5.2.dist-info/METADATA,sha256=3Ttc-cPytZsiNct2MRz4PZwe5JmdZzaEsEgu7hxKxvA,25939
-antspymm-1.5.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-antspymm-1.5.2.dist-info/top_level.txt,sha256=iyD1sRhCKzfwKRJLq5ZUeV9xsv1cGQl8Ejp6QwXM1Zg,9
-antspymm-1.5.2.dist-info/RECORD,,