rapidtide 2.9.5__py3-none-any.whl → 3.1.3__py3-none-any.whl

rapidtide/workflows/spatialfit.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
 #
-#   Copyright 2016-2024 Blaise Frederick
+#   Copyright 2016-2025 Blaise Frederick
 #
 #   Licensed under the Apache License, Version 2.0 (the "License");
 #   you may not use this file except in compliance with the License.
@@ -17,6 +17,8 @@
 #
 #
 import argparse
+from argparse import Namespace
+from typing import Any, Callable, Dict, List, Optional, Tuple, Union
 
 from matplotlib.pyplot import *
 from tqdm import tqdm
@@ -26,7 +28,32 @@ import rapidtide.io as tide_io
 import rapidtide.workflows.parser_funcs as pf
 
 
-def _get_parser():
+def _get_parser() -> Any:
+    """
+    Create and configure an argument parser for the spatialfit command-line tool.
+
+    This function sets up an `argparse.ArgumentParser` with specific arguments
+    required for fitting a 3D or 4D NIFTI file to a spatial template. It includes
+    validation for file inputs and supports optional masking and fitting parameters.
+
+    Returns
+    -------
+    argparse.ArgumentParser
+        Configured argument parser with defined command-line arguments.
+
+    Notes
+    -----
+    The parser is configured with:
+    - Required positional arguments: `datafile`, `templatefile`, and `outputroot`.
+    - Optional arguments: `--datamask`, `--templatemask`, `--order`, and `--debug`.
+
+    Examples
+    --------
+    >>> parser = _get_parser()
+    >>> args = parser.parse_args(['data.nii', 'template.nii', 'output_root'])
+    >>> print(args.datafile)
+    'data.nii'
+    """
     # get the command line parameters
     parser = argparse.ArgumentParser(
         prog="spatialfit",
@@ -80,7 +107,55 @@ def _get_parser():
     return parser
 
 
-def spatialfit(args):
+def spatialfit(args: Any) -> None:
+    """
+    Perform spatial fitting of fMRI data using a template-based linear regression model.
+
+    This function reads input data and template files, performs masking, and fits a
+    linear model at each spatial location to estimate spatially varying linear coefficients,
+    offsets, and R² values. It outputs time series of these parameters along with fitted,
+    residual, and normalized data volumes.
+
+    Parameters
+    ----------
+    args : Any
+        Parsed command-line arguments. Expected to contain the following attributes:
+        - datafile : str
+            Path to the input NIfTI data file.
+        - templatefile : str
+            Path to the template NIfTI file.
+        - dmask : str, optional
+            Path to the data mask NIfTI file.
+        - tmask : str, optional
+            Path to the template mask NIfTI file.
+        - outputroot : str
+            Root name for output files.
+        - debug : bool, optional
+            Enable debug printing.
+
+    Returns
+    -------
+    None
+        This function does not return a value but writes multiple NIfTI and text files
+        to disk.
+
+    Notes
+    -----
+    The function assumes that the input data and template files have compatible
+    spatial dimensions. It performs a linear regression for each timepoint and
+    stores the resulting coefficients, offsets, and R² values.
+
+    Examples
+    --------
+    >>> import argparse
+    >>> args = argparse.Namespace(
+    ...     datafile='data.nii.gz',
+    ...     templatefile='template.nii.gz',
+    ...     outputroot='output',
+    ...     debug=False
+    ... )
+    >>> spatialfit(args)
+    """
     # get the command line parameters
     try:
         args = _get_parser().parse_args()
@@ -180,7 +255,7 @@ def spatialfit(args):
     newmask = np.zeros((numspatiallocs), dtype="float")
     lincoffs = np.zeros((timepoints), dtype="float")
     offsets = np.zeros((timepoints), dtype="float")
-    rvals = np.zeros((timepoints), dtype="float")
+    r2vals = np.zeros((timepoints), dtype="float")
 
     if args.debug:
         print(fitdata.shape)
@@ -190,7 +265,7 @@ def spatialfit(args):
         print(newmask.shape)
         print(lincoffs.shape)
         print(offsets.shape)
-        print(rvals.shape)
+        print(r2vals.shape)
 
     # mask everything
     print("masking data and template")
@@ -215,10 +290,10 @@ def spatialfit(args):
     ):
         if args.debug:
             print("fitting")
-        thefit, R = tide_fit.mlregress(maskedtemplate[:, 0], maskeddata[:, thetime])
+        thefit, R2 = tide_fit.mlregress(maskedtemplate[:, 0], maskeddata[:, thetime])
         lincoffs[thetime] = thefit[0, 1]
         offsets[thetime] = thefit[0, 0]
-        rvals[thetime] = R
+        r2vals[thetime] = R2
         if args.debug:
             print("generating fit data")
             print(
@@ -241,7 +316,7 @@ def spatialfit(args):
     print("writing time series")
     tide_io.writenpvecs(lincoffs, args.outputroot + "_lincoffs.txt")
     tide_io.writenpvecs(offsets, args.outputroot + "_offsets.txt")
-    tide_io.writenpvecs(rvals, args.outputroot + "_rvals.txt")
+    tide_io.writenpvecs(r2vals, args.outputroot + "_r2vals.txt")
     print("slope mean, std:", np.mean(lincoffs), np.std(lincoffs))
     print("offset mean, std:", np.mean(offsets), np.std(offsets))
 

rapidtide/workflows/spatialmi.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
 #
-#   Copyright 2016-2024 Blaise Frederick
+#   Copyright 2016-2025 Blaise Frederick
 #
 #   Licensed under the Apache License, Version 2.0 (the "License");
 #   you may not use this file except in compliance with the License.
@@ -18,8 +18,11 @@
 #
 import argparse
 import sys
+from argparse import Namespace
+from typing import Any, Callable, Dict, List, Optional, Tuple, Union
 
 import numpy as np
+from numpy.typing import NDArray
 
 import rapidtide.correlate as tide_corr
 import rapidtide.filter as tide_filt
@@ -28,9 +31,32 @@ import rapidtide.io as tide_io
 import rapidtide.miscmath as tide_math
 
 
-def _get_parser():
+def _get_parser() -> Any:
     """
-    Argument parser for pixelcomp
+    Argument parser for spatialmi.
+
+    This function constructs and returns an `argparse.ArgumentParser` object configured
+    to parse command-line arguments for the `spatialmi` tool, which calculates localized
+    spatial mutual information between two NIfTI images.
+
+    Returns
+    -------
+    argparse.ArgumentParser
+        Configured argument parser for the spatial mutual information calculation tool.
+
+    Notes
+    -----
+    The parser requires four mandatory positional arguments: two input NIfTI image filenames,
+    two corresponding mask filenames, and an output root name. Optional arguments allow
+    customization of the calculation, including neighborhood shape, filtering, normalization,
+    and debugging output.
+
+    Examples
+    --------
+    >>> parser = _get_parser()
+    >>> args = parser.parse_args()
+    >>> print(args.inputfilename1)
+    'input1.nii.gz'
     """
     parser = argparse.ArgumentParser(
         prog="spatialmi",
@@ -138,23 +164,77 @@ def _get_parser():
 
 
 def getneighborhood(
-    indata,
-    xloc,
-    yloc,
-    zloc,
-    xsize,
-    ysize,
-    zsize,
-    radius,
-    spherical=False,
-    kernelwidth=1.5,
-    slop=0.01,
-    debug=False,
-):
+    indata: NDArray[np.floating[Any]],
+    xloc: Any,
+    yloc: Any,
+    zloc: Any,
+    xsize: Any,
+    ysize: Any,
+    zsize: Any,
+    radius: Any,
+    spherical: bool = False,
+    kernelwidth: float = 1.5,
+    slop: float = 0.01,
+    debug: bool = False,
+) -> NDArray[np.floating[Any]]:
+    """
+    Extract a neighborhood from a 3D dataset, either as a weighted kernel or a spherical region.
+
+    This function retrieves a local neighborhood around a specified 3D location in a dataset.
+    The neighborhood can be extracted either as a cubic region with a Gaussian-weighted kernel
+    (when `spherical=False`) or as a spherical region (when `spherical=True`).
+
+    Parameters
+    ----------
+    indata : NDArray[np.floating[Any]]
+        Input 3D dataset from which the neighborhood is extracted.
+    xloc, yloc, zloc : float or int
+        The center coordinates of the neighborhood in the dataset.
+    xsize, ysize, zsize : int
+        Dimensions of the input dataset along each axis.
+    radius : float or int
+        The radius of the neighborhood. For `spherical=False`, this defines the cubic
+        kernel size. For `spherical=True`, it defines the spherical radius.
+    spherical : bool, optional
+        If True, extracts a spherical neighborhood. If False, extracts a cubic neighborhood
+        with a Gaussian kernel. Default is False.
+    kernelwidth : float, optional
+        Width parameter for the Gaussian kernel used when `spherical=False`. Default is 1.5.
+    slop : float, optional
+        Tolerance for spherical radius checking. Default is 0.01.
+    debug : bool, optional
+        If True, prints debug information about the index list initialization. Default is False.
+
+    Returns
+    -------
+    NDArray[np.floating[Any]]
+        A flattened array of the neighborhood values. When `spherical=False`, the values
+        are weighted by a Gaussian kernel. When `spherical=True`, the values are unweighted.
+
+    Notes
+    -----
+    - The function uses global variables `kernel`, `usedwidth`, `indexlist`, and `usedradius`
+      to cache computations for performance. These are initialized on first call.
+    - For `spherical=False`, the function returns a flattened array of the kernel-weighted
+      neighborhood.
+    - For `spherical=True`, the function returns a flattened array of values within the
+      spherical neighborhood.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> data = np.random.rand(10, 10, 10)
+    >>> neighborhood = getneighborhood(data, 5, 5, 5, 10, 10, 10, 2, spherical=False)
+    >>> print(neighborhood.shape)
+    (125,)
+    >>> neighborhood = getneighborhood(data, 5, 5, 5, 10, 10, 10, 2, spherical=True)
+    >>> print(neighborhood.shape)
+    (33,)
+    """
     if not spherical:
         global usedwidth, kernel
         try:
-            kernel
+            dummy = kernel
         except NameError:
             usedwidth = kernelwidth
             kernel = None
@@ -230,7 +310,66 @@ def getneighborhood(
         return np.array(outdata)
 
 
-def getMI(x, y, norm=True, bins=-1, init=False, prebin=True, sigma=0.25, debug=False):
+def getMI(
+    x: Any,
+    y: Any,
+    norm: bool = True,
+    bins: int = -1,
+    init: bool = False,
+    prebin: bool = True,
+    sigma: float = 0.25,
+    debug: bool = False,
+) -> None:
+    """
+    Compute the mutual information between two variables using binned estimation.
+
+    This function calculates the mutual information between two input arrays `x` and `y`,
+    using a binned approach. It supports normalization, automatic bin selection, and
+    optional pre-binning for performance optimization.
+
+    Parameters
+    ----------
+    x : array-like
+        First input variable.
+    y : array-like
+        Second input variable.
+    norm : bool, optional
+        If True, normalize the input variables using standard normalization
+        (zero mean, unit variance). Default is True.
+    bins : int, optional
+        Number of bins to use for the 2D histogram. If less than 1, the number
+        of bins is automatically determined as `max(int(sqrt(len(x) / 5)), 3)`.
+        Default is -1.
+    init : bool, optional
+        If True, reinitialize the global binning structure. Default is False.
+    prebin : bool, optional
+        If True, use precomputed bin edges. If False, use the number of bins
+        directly. Default is True.
+    sigma : float, optional
+        Standard deviation for Gaussian smoothing in the mutual information
+        calculation. Default is 0.25.
+    debug : bool, optional
+        If True, print debugging information during execution. Default is False.
+
+    Returns
+    -------
+    None
+        The function returns the result of `tide_corr.mutual_info_2d`, which is
+        not explicitly returned here but is the core output of the function.
+
+    Notes
+    -----
+    The function uses a global variable `thebins` to store binning information.
+    If `init` is True or `thebins` is None, bin edges are computed and stored
+    in `thebins`. The function relies on `tide_math.stdnormalize` for normalization
+    and `tide_corr.mutual_info_2d` for the actual mutual information computation.
+
+    Examples
+    --------
+    >>> x = [1, 2, 3, 4, 5]
+    >>> y = [2, 4, 6, 8, 10]
+    >>> getMI(x, y, norm=True, bins=10, debug=False)
+    """
     global thebins
 
     if norm:
@@ -274,18 +413,102 @@ def getMI(x, y, norm=True, bins=-1, init=False, prebin=True, sigma=0.25, debug=F
             f"normy min, max, mean, std: {np.min(normy)}, {np.max(normy)}, {np.mean(normy)}, {np.std(normy)}"
         )
 
-    return tide_corr.mutual_info_2d(
-        normx,
-        normy,
-        bins=thebins,
-        normalized=norm,
-        fast=fast,
-        sigma=sigma,
-        debug=debug,
-    )
+    if fast:
+        return tide_corr.mutual_info_2d_fast(
+            normx,
+            normy,
+            thebins,
+            normalized=norm,
+            sigma=sigma,
+            debug=debug,
+        )
+    else:
+        return tide_corr.mutual_info_2d(
+            normx,
+            normy,
+            thebins,
+            normalized=norm,
+            sigma=sigma,
+            debug=debug,
+        )
 
 
-def spatialmi(args):
+def spatialmi(args: Any) -> None:
+    """
+    Compute spatial mutual information (MI) between two 3D images over a specified neighborhood.
+
+    This function reads two input NIfTI images and their corresponding masks, computes the
+    mutual information between the images within a local neighborhood for each voxel,
+    and saves the result as a NIfTI file. Optional spatial filtering can be applied
+    before computing the MI.
+
+    Parameters
+    ----------
+    args : Any
+        Parsed command-line arguments containing:
+        - inputfilename1 : str
+            Path to the first input NIfTI image.
+        - inputfilename2 : str
+            Path to the second input NIfTI image.
+        - maskfilename1 : str
+            Path to the mask for the first image.
+        - maskfilename2 : str
+            Path to the mask for the second image.
+        - index1 : int, optional
+            Index of the time point to use from the first image (default is 0).
+        - index2 : int, optional
+            Index of the time point to use from the second image (default is 0).
+        - radius : float
+            Neighborhood radius for computing mutual information.
+        - sigma : float, optional
+            Standard deviation for spatial smoothing (default is None).
+        - spherical : bool
+            Whether to use a spherical neighborhood (default is False).
+        - kernelwidth : float
+            Width of the kernel for neighborhood computation (default is None).
+        - norm : bool
+            Whether to normalize the data before computing MI (default is False).
+        - prebin : bool
+            Whether to pre-bin the data (default is False).
+        - debug : bool
+            Enable debug output (default is False).
+        - outputroot : str
+            Root name for the output NIfTI file.
+
+    Returns
+    -------
+    None
+        The function writes the computed spatial mutual information to a NIfTI file
+        named `<outputroot>_result.nii.gz`.
+
+    Notes
+    -----
+    - The function requires that both input images and their masks have matching spatial dimensions.
+    - If `sigma` is specified, spatial filtering is applied using a Gaussian kernel.
+    - The neighborhood is defined by the `radius` and `spherical` parameters.
+    - The output file contains mutual information values for each voxel in the masked region.
+
+    Examples
+    --------
+    >>> import argparse
+    >>> args = argparse.Namespace(
+    ...     inputfilename1='image1.nii.gz',
+    ...     inputfilename2='image2.nii.gz',
+    ...     maskfilename1='mask1.nii.gz',
+    ...     maskfilename2='mask2.nii.gz',
+    ...     index1=0,
+    ...     index2=0,
+    ...     radius=5.0,
+    ...     sigma=None,
+    ...     spherical=True,
+    ...     kernelwidth=None,
+    ...     norm=False,
+    ...     prebin=False,
+    ...     debug=False,
+    ...     outputroot='output'
+    ... )
+    >>> spatialmi(args)
+    """
     global thebins
     thebins = None
 
@@ -352,7 +575,7 @@ def spatialmi(args):
     totalmask = mask1_data * mask2_data
     print(f"totalmask.shape = {totalmask.shape}")
     xsize, ysize, numslices, timepoints = tide_io.parseniftidims(thedims1)
-    outputdata = image1 * 0
+    outputdata = np.zeros_like(image1)
 
     # spatial filter if desired
     if args.sigma is not None: