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

rapidtide/linfitfiltpass.py

@@ -16,7 +16,10 @@
 #   limitations under the License.
 #
 #
+from typing import Any, Callable
+
 import numpy as np
+from numpy.typing import NDArray
 from scipy.special import factorial
 from tqdm import tqdm
 
@@ -27,8 +30,63 @@ 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_floatset: type = np.float64,
+    rt_floattype: str = "float64",
+) -> tuple[int, Any, Any, Any, Any, 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 : numpy.ndarray
+        Experimental design matrix. If 2D, dimension 0 is number of points,
+        dimension 1 is number of evs.
+    thedata : numpy.ndarray
+        Dependent variable data corresponding to the evs.
+    rt_floatset : type, optional
+        Data type for floating-point results, default is ``np.float64``.
+    rt_floattype : str, optional
+        String representation of the floating-point type, default is ``"float64"``.
+
+    Returns
+    -------
+    tuple[int, Any, Any, Any, Any, Any, numpy.ndarray, numpy.ndarray]
+        A tuple containing:
+        - voxel index (`int`)
+        - intercept term (`Any`)
+        - signed square root of R-squared (`Any`)
+        - R-squared value (`Any`)
+        - fit coefficients (`Any` or `numpy.ndarray`)
+        - normalized fit coefficients (`Any`)
+        - data removed by fitting (`numpy.ndarray`)
+        - residuals (`numpy.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
+    >>> from tide_fit import mlregress
+    >>> 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:
@@ -78,36 +136,132 @@ def _procOneRegressionFitItem(
 
 
 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,
+    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_floatset: type = np.float64,
+    rt_floattype: str = "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_floatset : type, default: np.float64
+        Data type for internal floating-point calculations.
+    rt_floattype : str, default: "float64"
+        String representation of the floating-point data type.
+    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,7 +297,7 @@ def linfitfiltpass(
 
                     # process and send the data
                     if procbyvoxel:
-                        if confoundregress or (not voxelspecific):
+                        if confoundregress or constantevs:
                             outQ.put(
                                 _procOneRegressionFitItem(
                                     val,
@@ -164,7 +318,7 @@ def linfitfiltpass(
                                 )
                             )
                     else:
-                        if confoundregress or (not voxelspecific):
+                        if confoundregress or constantevs:
                             outQ.put(
                                 _procOneRegressionFitItem(
                                     val,
@@ -214,7 +368,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 +380,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 +400,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 +412,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 +424,7 @@ def linfitfiltpass(
 
         del data_out
     else:
+        # this is the single proc path
         itemstotal = 0
         if procbyvoxel:
             for vox in tqdm(
@@ -298,7 +453,7 @@ def linfitfiltpass(
                             rt_floattype=rt_floattype,
                         )
                     elif coefficientsonly:
-                        if voxelspecific:
+                        if not constantevs:
                             (
                                 dummy,
                                 meanvalue[vox],
@@ -377,22 +532,40 @@ def linfitfiltpass(
                             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_floatset=rt_floatset,
+                                rt_floattype=rt_floattype,
+                            )
+                        else:
+                            (
+                                dummy,
+                                meanvalue[timepoint],
+                                rvalue[timepoint],
+                                r2value[timepoint],
+                                fitcoeff[timepoint],
+                                fitNorm[timepoint],
+                                dummy,
+                                dummy,
+                            ) = _procOneRegressionFitItem(
+                                timepoint,
+                                theevs,
+                                thedata,
+                                rt_floatset=rt_floatset,
+                                rt_floattype=rt_floattype,
+                            )
                     else:
                         (
                             dummy,
@@ -410,30 +583,56 @@ def linfitfiltpass(
                             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 +658,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: