rapidtide 3.0.11__py3-none-any.whl → 3.1.1__py3-none-any.whl

rapidtide/linfitfiltpass.py

@@ -16,7 +16,10 @@
 #   limitations under the License.
 #
 #
+from typing import Any
+
 import numpy as np
+from numpy.typing import NDArray
 from scipy.special import factorial
 from tqdm import tqdm
 
@@ -27,38 +30,89 @@ import rapidtide.multiproc as tide_multiproc
 
 
 def _procOneRegressionFitItem(
-    vox, theevs, thedata, rt_floatset=np.float64, rt_floattype="float64"
-):
+    vox: int,
+    theevs: NDArray,
+    thedata: NDArray,
+    rt_floattype: np.dtype = np.float64,
+) -> tuple[int, float, float, float, float | NDArray, Any, NDArray, NDArray]:
+    """
+    Perform single regression fit on voxel data and return fit results.
+
+    This function fits a linear regression model to the provided evs and data,
+    handling both univariate and multivariate cases. It computes fit coefficients,
+    R-squared value, and residual data.
+
+    Parameters
+    ----------
+    vox : int
+        Voxel index.
+    theevs : NDArray
+        Experimental design matrix. If 2D, dimension 0 is number of points,
+        dimension 1 is number of evs.
+    thedata : NDArray
+        Dependent variable data corresponding to the evs.
+    rt_floattype : str, optional
+        String representation of the floating-point type, default is ``np.float64``.
+
+    Returns
+    -------
+    tuple[int, float, float, float, float, Any, NDArray, NDArray]
+        A tuple containing:
+        - voxel index (`int`)
+        - intercept term (`float`)
+        - signed square root of R-squared (`float`)
+        - R-squared value (`float`)
+        - fit coefficients (`float` or `NDArray`)
+        - normalized fit coefficients (`Any`)
+        - data removed by fitting (`NDArray`)
+        - residuals (`NDArray`)
+
+    Notes
+    -----
+    For multivariate regressions (2D `theevs`), the function computes the fit
+    using `tide_fit.mlregress`. If the fit fails, a zero matrix is returned.
+    For univariate regressions (1D `theevs`), the function directly computes
+    the fit and handles edge cases such as zero coefficients.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> theevs = np.array([[1, 2], [3, 4], [5, 6]], dtype=np.float64)
+    >>> thedata = np.array([1, 2, 3], dtype=np.float64)
+    >>> result = _procOneRegressionFitItem(0, theevs, thedata)
+    >>> print(result[0])  # voxel index
+    0
+    """
     # NOTE: if theevs is 2D, dimension 0 is number of points, dimension 1 is number of evs
     thefit, R2 = tide_fit.mlregress(theevs, thedata)
     if theevs.ndim > 1:
         if thefit is None:
             thefit = np.matrix(np.zeros((1, theevs.shape[1] + 1), dtype=rt_floattype))
-        fitcoeffs = rt_floatset(thefit[0, 1:])
+        fitcoeffs = (thefit[0, 1:]).astype(rt_floattype)
         if fitcoeffs[0, 0] < 0.0:
             coeffsign = -1.0
         else:
             coeffsign = 1.0
         datatoremove = theevs[:, 0] * 0.0
         for j in range(theevs.shape[1]):
-            datatoremove += rt_floatset(rt_floatset(thefit[0, 1 + j]) * theevs[:, j])
+            datatoremove += (thefit[0, 1 + j] * theevs[:, j]).astype(rt_floattype)
         if np.any(fitcoeffs) != 0.0:
             pass
         else:
             R2 = 0.0
         return (
             vox,
-            rt_floatset(thefit[0, 0]),
-            rt_floatset(coeffsign * np.sqrt(R2)),
-            rt_floatset(R2),
+            thefit[0, 0],
+            coeffsign * np.sqrt(R2),
+            R2,
             fitcoeffs,
-            rt_floatset(thefit[0, 1:] / thefit[0, 0]),
+            (thefit[0, 1:] / thefit[0, 0]).astype(rt_floattype),
             datatoremove,
-            rt_floatset(thedata - datatoremove),
+            (thedata - datatoremove).astype(rt_floattype),
         )
     else:
-        fitcoeff = rt_floatset(thefit[0, 1])
-        datatoremove = rt_floatset(fitcoeff * theevs)
+        fitcoeff = (thefit[0, 1]).astype(rt_floattype)
+        datatoremove = (fitcoeff * theevs).astype(rt_floattype)
         if fitcoeff < 0.0:
             coeffsign = -1.0
         else:
@@ -67,47 +121,140 @@ def _procOneRegressionFitItem(
             R2 = 0.0
         return (
             vox,
-            rt_floatset(thefit[0, 0]),
-            rt_floatset(coeffsign * np.sqrt(R2)),
-            rt_floatset(R2),
+            thefit[0, 0],
+            coeffsign * np.sqrt(R2),
+            R2,
             fitcoeff,
-            rt_floatset(thefit[0, 1] / thefit[0, 0]),
+            (thefit[0, 1] / thefit[0, 0]).astype(rt_floattype),
             datatoremove,
-            rt_floatset(thedata - datatoremove),
+            (thedata - datatoremove).astype(rt_floattype),
         )
 
 
 def linfitfiltpass(
-    numprocitems,
-    fmri_data,
-    threshval,
-    theevs,
-    meanvalue,
-    rvalue,
-    r2value,
-    fitcoeff,
-    fitNorm,
-    datatoremove,
-    filtereddata,
-    nprocs=1,
-    alwaysmultiproc=False,
-    voxelspecific=True,
-    confoundregress=False,
-    coefficientsonly=False,
-    procbyvoxel=True,
-    showprogressbar=True,
-    chunksize=1000,
-    rt_floatset=np.float64,
-    rt_floattype="float64",
-    verbose=True,
-    debug=False,
-):
+    numprocitems: int,
+    fmri_data: NDArray,
+    threshval: float | None,
+    theevs: NDArray,
+    meanvalue: NDArray | None,
+    rvalue: NDArray | None,
+    r2value: NDArray,
+    fitcoeff: NDArray | None,
+    fitNorm: NDArray | None,
+    datatoremove: NDArray | None,
+    filtereddata: NDArray | None,
+    nprocs: int = 1,
+    alwaysmultiproc: bool = False,
+    constantevs: bool = False,
+    confoundregress: bool = False,
+    coefficientsonly: bool = False,
+    procbyvoxel: bool = True,
+    showprogressbar: bool = True,
+    chunksize: int = 1000,
+    rt_floattype: np.dtype = np.float64,
+    verbose: bool = True,
+    debug: bool = False,
+) -> int:
+    """
+    Perform linear regression fitting and filtering on fMRI data.
+
+    This function fits a linear model to fMRI data using specified experimental variables
+    and applies filtering to remove noise. It supports both voxel-wise and timepoint-wise
+    processing, with optional multiprocessing for performance.
+
+    Parameters
+    ----------
+    numprocitems : int
+        Number of items to process (voxels or timepoints depending on ``procbyvoxel``).
+    fmri_data : ndarray
+        Input fMRI data array with shape ``(n_voxels, n_timepoints)`` or ``(n_timepoints, n_voxels)``.
+    threshval : float, optional
+        Threshold value for masking. If ``None``, no masking is applied.
+    theevs : ndarray
+        Experimental variables (design matrix) with shape ``(n_voxels, n_timepoints)`` or ``(n_timepoints, n_voxels)``.
+    meanvalue : ndarray, optional
+        Array to store mean values of the data. Shape depends on ``procbyvoxel``.
+    rvalue : ndarray, optional
+        Array to store correlation coefficients. Shape depends on ``procbyvoxel``.
+    r2value : ndarray
+        Array to store R-squared values. Shape depends on ``procbyvoxel``.
+    fitcoeff : ndarray, optional
+        Array to store fit coefficients. Shape depends on ``procbyvoxel`` and ``constantevs``.
+    fitNorm : ndarray, optional
+        Array to store normalized fit coefficients. Shape depends on ``procbyvoxel``.
+    datatoremove : ndarray, optional
+        Array to store data to be removed after fitting. Shape depends on ``procbyvoxel``.
+    filtereddata : ndarray
+        Array to store filtered data after regression. Shape depends on ``procbyvoxel``.
+    nprocs : int, default: 1
+        Number of processes to use for multiprocessing. If 1 and ``alwaysmultiproc`` is False, uses single-threaded processing.
+    alwaysmultiproc : bool, default: False
+        If True, always use multiprocessing even if ``nprocs`` is 1.
+    constantevs : bool, default: False
+        If True, treat experimental variables as constant across voxels/timepoints.
+    confoundregress : bool, default: False
+        If True, perform confound regression only (no output of coefficients or residuals).
+    coefficientsonly : bool, default: False
+        If True, store only regression coefficients and R-squared values.
+    procbyvoxel : bool, default: True
+        If True, process data voxel-wise; otherwise, process by timepoint.
+    showprogressbar : bool, default: True
+        If True, display a progress bar during processing.
+    chunksize : int, default: 1000
+        Size of chunks for multiprocessing.
+    rt_floattype : str, default: np.float64
+        Data type for internal floating-point calculations.
+    verbose : bool, default: True
+        If True, print verbose output.
+    debug : bool, default: False
+        If True, enable debug printing.
+
+    Returns
+    -------
+    int
+        Total number of items processed.
+
+    Notes
+    -----
+    - The function modifies the output arrays in-place.
+    - For ``confoundregress=True``, only ``r2value`` and ``filtereddata`` are populated.
+    - When ``coefficientsonly=True``, only ``meanvalue``, ``rvalue``, ``r2value``, ``fitcoeff``, and ``fitNorm`` are populated.
+    - If ``threshval`` is provided, a mask is generated based on mean or standard deviation of the data.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from typing import NDArray
+    >>> fmri_data = np.random.rand(100, 200)
+    >>> theevs = np.random.rand(100, 200)
+    >>> r2value = np.zeros(100)
+    >>> filtereddata = np.zeros_like(fmri_data)
+    >>> numprocitems = 100
+    >>> items_processed = linfitfiltpass(
+    ...     numprocitems=numprocitems,
+    ...     fmri_data=fmri_data,
+    ...     threshval=None,
+    ...     theevs=theevs,
+    ...     meanvalue=None,
+    ...     rvalue=None,
+    ...     r2value=r2value,
+    ...     fitcoeff=None,
+    ...     fitNorm=None,
+    ...     datatoremove=None,
+    ...     filtereddata=filtereddata,
+    ...     nprocs=4,
+    ...     procbyvoxel=True,
+    ...     showprogressbar=True
+    ... )
+    >>> print(f"Processed {items_processed} items.")
+    """
     inputshape = np.shape(fmri_data)
     if debug:
         print(f"{numprocitems=}")
         print(f"{fmri_data.shape=}")
         print(f"{threshval=}")
-        print(f"{theevs.shape=}")
+        print(f"{theevs.shape=}, {np.min(theevs)=}, {np.max(theevs)=}")
+        print(f"{theevs=}")
     if procbyvoxel:
         indexaxis = 0
         procunit = "voxels"
@@ -143,13 +290,12 @@ def linfitfiltpass(
 
                     # process and send the data
                     if procbyvoxel:
-                        if confoundregress or (not voxelspecific):
+                        if confoundregress or constantevs:
                             outQ.put(
                                 _procOneRegressionFitItem(
                                     val,
                                     theevs,
                                     fmri_data[val, :],
-                                    rt_floatset=rt_floatset,
                                     rt_floattype=rt_floattype,
                                 )
                             )
@@ -159,18 +305,16 @@ def linfitfiltpass(
                                     val,
                                     theevs[val, :],
                                     fmri_data[val, :],
-                                    rt_floatset=rt_floatset,
                                     rt_floattype=rt_floattype,
                                 )
                             )
                     else:
-                        if confoundregress or (not voxelspecific):
+                        if confoundregress or constantevs:
                             outQ.put(
                                 _procOneRegressionFitItem(
                                     val,
                                     theevs,
                                     fmri_data[:, val],
-                                    rt_floatset=rt_floatset,
                                     rt_floattype=rt_floattype,
                                 )
                             )
@@ -180,7 +324,6 @@ def linfitfiltpass(
                                     val,
                                     theevs[:, val],
                                     fmri_data[:, val],
-                                    rt_floatset=rt_floatset,
                                     rt_floattype=rt_floattype,
                                 )
                             )
@@ -214,7 +357,7 @@ def linfitfiltpass(
                     meanvalue[voxel[0]] = voxel[1]
                     rvalue[voxel[0]] = voxel[2]
                     r2value[voxel[0]] = voxel[3]
-                    if theevs.ndim > 1:
+                    if fitcoeff.ndim > 1:
                         fitcoeff[voxel[0], :] = voxel[4]
                         fitNorm[voxel[0], :] = voxel[5]
                     else:
@@ -226,7 +369,7 @@ def linfitfiltpass(
                     meanvalue[voxel[0]] = voxel[1]
                     rvalue[voxel[0]] = voxel[2]
                     r2value[voxel[0]] = voxel[3]
-                    if theevs.ndim > 1:
+                    if fitcoeff.ndim > 1:
                         fitcoeff[voxel[0], :] = voxel[4]
                         fitNorm[voxel[0], :] = voxel[5]
                     else:
@@ -246,7 +389,7 @@ def linfitfiltpass(
                     meanvalue[timepoint[0]] = timepoint[1]
                     rvalue[timepoint[0]] = timepoint[2]
                     r2value[timepoint[0]] = timepoint[3]
-                    if theevs.ndim > 1:
+                    if fitcoeff.ndim > 1:
                         fitcoeff[:, timepoint[0]] = timepoint[4]
                         fitNorm[:, timepoint[0]] = timepoint[5]
                     else:
@@ -258,7 +401,7 @@ def linfitfiltpass(
                     meanvalue[timepoint[0]] = timepoint[1]
                     rvalue[timepoint[0]] = timepoint[2]
                     r2value[timepoint[0]] = timepoint[3]
-                    if theevs.ndim > 1:
+                    if fitcoeff.ndim > 1:
                         fitcoeff[:, timepoint[0]] = timepoint[4]
                         fitNorm[:, timepoint[0]] = timepoint[5]
                     else:
@@ -270,6 +413,7 @@ def linfitfiltpass(
 
         del data_out
     else:
+        # this is the single proc path
         itemstotal = 0
         if procbyvoxel:
             for vox in tqdm(
@@ -294,11 +438,10 @@ def linfitfiltpass(
                             vox,
                             theevs,
                             thedata,
-                            rt_floatset=rt_floatset,
                             rt_floattype=rt_floattype,
                         )
                     elif coefficientsonly:
-                        if voxelspecific:
+                        if not constantevs:
                             (
                                 dummy,
                                 meanvalue[vox],
@@ -312,7 +455,6 @@ def linfitfiltpass(
                                 vox,
                                 theevs[vox, :],
                                 thedata,
-                                rt_floatset=rt_floatset,
                                 rt_floattype=rt_floattype,
                             )
                         else:
@@ -329,7 +471,6 @@ def linfitfiltpass(
                                 vox,
                                 theevs,
                                 thedata,
-                                rt_floatset=rt_floatset,
                                 rt_floattype=rt_floattype,
                             )
                     else:
@@ -346,7 +487,6 @@ def linfitfiltpass(
                             vox,
                             theevs[vox, :],
                             thedata,
-                            rt_floatset=rt_floatset,
                             rt_floattype=rt_floattype,
                         )
                     itemstotal += 1
@@ -373,26 +513,41 @@ def linfitfiltpass(
                             timepoint,
                             theevs,
                             thedata,
-                            rt_floatset=rt_floatset,
                             rt_floattype=rt_floattype,
                         )
                     elif coefficientsonly:
-                        (
-                            dummy,
-                            meanvalue[timepoint],
-                            rvalue[timepoint],
-                            r2value[timepoint],
-                            fitcoeff[timepoint],
-                            fitNorm[timepoint],
-                            dummy,
-                            dummy,
-                        ) = _procOneRegressionFitItem(
-                            timepoint,
-                            theevs[:, timepoint],
-                            thedata,
-                            rt_floatset=rt_floatset,
-                            rt_floattype=rt_floattype,
-                        )
+                        if not constantevs:
+                            (
+                                dummy,
+                                meanvalue[timepoint],
+                                rvalue[timepoint],
+                                r2value[timepoint],
+                                fitcoeff[timepoint],
+                                fitNorm[timepoint],
+                                dummy,
+                                dummy,
+                            ) = _procOneRegressionFitItem(
+                                timepoint,
+                                theevs[:, timepoint],
+                                thedata,
+                                rt_floattype=rt_floattype,
+                            )
+                        else:
+                            (
+                                dummy,
+                                meanvalue[timepoint],
+                                rvalue[timepoint],
+                                r2value[timepoint],
+                                fitcoeff[timepoint],
+                                fitNorm[timepoint],
+                                dummy,
+                                dummy,
+                            ) = _procOneRegressionFitItem(
+                                timepoint,
+                                theevs,
+                                thedata,
+                                rt_floattype=rt_floattype,
+                            )
                     else:
                         (
                             dummy,
@@ -407,33 +562,58 @@ def linfitfiltpass(
                             timepoint,
                             theevs[:, timepoint],
                             thedata,
-                            rt_floatset=rt_floatset,
                             rt_floattype=rt_floattype,
                         )
+
                     itemstotal += 1
         if showprogressbar:
             print()
     return itemstotal
 
 
-def makevoxelspecificderivs(theevs, nderivs=1, debug=False):
-    r"""Perform multicomponent expansion on theevs (each ev replaced by itself,
-    its square, its cube, etc.).
+def makevoxelspecificderivs(theevs: NDArray, nderivs: int = 1, debug: bool = False) -> NDArray:
+    """
+    Perform multicomponent expansion on voxel-specific explanatory variables by computing
+    derivatives up to a specified order.
+
+    This function takes an array of voxel-specific timecourses and expands each one
+    into a set of components representing the original signal and its derivatives.
+    Each component corresponds to a higher-order derivative of the signal, scaled by
+    the inverse factorial of the derivative order (Taylor series coefficients).
 
     Parameters
     ----------
     theevs : 2D numpy array
-        NxP array of voxel specific explanatory variables (one timecourse per voxel)
-        :param theevs:
+        NxP array of voxel-specific explanatory variables, where N is the number of voxels
+        and P is the number of timepoints.
+    nderivs : int, optional
+        Number of derivative components to compute for each voxel. Default is 1.
+        If 0, the original `theevs` are returned without modification.
+    debug : bool, optional
+        If True, print debugging information including input and output shapes.
+        Default is False.
 
-    nderivs : integer
-        Number of components to use for each ev.  Each successive component is a
-        higher power of the initial ev (initial, square, cube, etc.)
-        :param nderivs:
+    Returns
+    -------
+    3D numpy array
+        Array of shape (N, P, nderivs + 1) containing the original signal and its
+        derivatives up to order `nderivs` for each voxel. The first component is the
+        original signal, followed by the first, second, ..., up to `nderivs`-th derivative.
 
-    debug: bool
-        Flag to toggle debugging output
-        :param debug:
+    Notes
+    -----
+    - The function uses `numpy.gradient` to compute numerical derivatives.
+    - Each derivative component is scaled by the inverse factorial of the derivative order
+      to align with Taylor series expansion coefficients.
+    - If `nderivs=0`, the function returns a copy of the input `theevs`.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> theevs = np.array([[1, 2, 3, 4], [5, 6, 7, 8]])
+    >>> result = makevoxelspecificderivs(theevs, nderivs=2)
+    >>> print(result.shape)
+    (2, 4, 3)
     """
     if debug:
         print(f"{theevs.shape=}")
@@ -459,19 +639,86 @@ def makevoxelspecificderivs(theevs, nderivs=1, debug=False):
 
 
 def confoundregress(
-    theregressors,
-    theregressorlabels,
-    thedataarray,
-    tr,
-    nprocs=1,
-    orthogonalize=True,
-    tcstart=0,
-    tcend=-1,
-    tchp=None,
-    tclp=None,
-    showprogressbar=True,
-    debug=False,
-):
+    theregressors: NDArray,
+    theregressorlabels: list[str],
+    thedataarray: NDArray,
+    tr: float,
+    nprocs: int = 1,
+    orthogonalize: bool = True,
+    tcstart: int = 0,
+    tcend: int = -1,
+    tchp: float | None = None,
+    tclp: float | None = None,
+    showprogressbar: bool = True,
+    debug: bool = False,
+) -> tuple[NDArray, list[str], NDArray, NDArray]:
+    """
+    Perform confound regression on fMRI data using linear regression.
+
+    This function applies confound regression to remove noise from fMRI time series
+    by regressing out specified confounding variables (e.g., motion parameters,
+    physiological signals). It supports optional filtering, orthogonalization of
+    regressors, and parallel processing for performance.
+
+    Parameters
+    ----------
+    theregressors : ndarray
+        Array of confounding variables with shape (n_regressors, n_timepoints).
+    theregressorlabels : list of str
+        List of labels corresponding to each regressor.
+    thedataarray : ndarray
+        3D or 4D array of fMRI data with shape (n_voxels, n_timepoints) or
+        (n_voxels, n_timepoints, n_volumes).
+    tr : float
+        Repetition time (TR) in seconds.
+    nprocs : int, optional
+        Number of processes to use for parallel processing. Default is 1.
+    orthogonalize : bool, optional
+        If True, orthogonalize the regressors to reduce multicollinearity.
+        Default is True.
+    tcstart : int, optional
+        Start timepoint index for regressor data. Default is 0.
+    tcend : int, optional
+        End timepoint index for regressor data. If -1, use all timepoints
+        from `tcstart`. Default is -1.
+    tchp : float, optional
+        High-pass cutoff frequency for filtering. If None, no high-pass filtering
+        is applied.
+    tclp : float, optional
+        Low-pass cutoff frequency for filtering. If None, no low-pass filtering
+        is applied.
+    showprogressbar : bool, optional
+        If True, display a progress bar during processing. Default is True.
+    debug : bool, optional
+        If True, enable debug output. Default is False.
+
+    Returns
+    -------
+    tuple of (NDArray, list of str, NDArray, NDArray)
+        - `theregressors`: Processed regressors (possibly orthogonalized).
+        - `theregressorlabels`: Updated labels for the regressors.
+        - `filtereddata`: Data with confounds removed.
+        - `r2value`: R-squared values for each voxel (or None if not computed).
+
+    Notes
+    -----
+    - The function applies standard deviation normalization to regressors for
+      numerical stability.
+    - If `orthogonalize` is True, Gram-Schmidt orthogonalization is applied to
+      the regressors.
+    - Filtering is applied using a trapezoidal filter if `tchp` or `tclp` are provided.
+    - The function uses `linfitfiltpass` internally for the actual regression.
+
+    Examples
+    --------
+    >>> regressors = np.random.rand(3, 100)
+    >>> labels = ['motion_x', 'motion_y', 'motion_z']
+    >>> data = np.random.rand(50, 100)
+    >>> tr = 2.0
+    >>> processed_regressors, labels, filtered_data, r2 = confoundregress(
+    ...     regressors, labels, data, tr, nprocs=4
+    ... )
+    """
     if tcend == -1:
         theregressors = theregressors[:, tcstart:]
     else: