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

rapidtide/_version.py

@@ -8,11 +8,11 @@ import json
 
 version_json = '''
 {
- "date": "2025-08-27T10:21:33-0400",
+ "date": "2025-11-08T09:22:00-0500",
  "dirty": false,
  "error": null,
- "full-revisionid": "078ea587f66134f5bb1f53817240da52156cf7f1",
- "version": "3.0.11"
+ "full-revisionid": "d57dfd2f1902964ec2bdc7a760f361eea22f22aa",
+ "version": "3.1"
 }
 '''  # END VERSION_JSON
 

rapidtide/calccoherence.py

@@ -19,8 +19,10 @@
 import gc
 import logging
 import warnings
+from typing import Any
 
 import numpy as np
+from numpy.typing import NDArray
 
 import rapidtide.genericmultiproc as tide_genericmultiproc
 
@@ -29,10 +31,57 @@ LGR = logging.getLogger("GENERAL")
 
 
 def _procOneVoxelCoherence(
-    vox,
-    voxelargs,
-    **kwargs,
-):
+    vox: int,
+    voxelargs: list,
+    **kwargs: Any,
+) -> tuple[int, NDArray, NDArray, float, float]:
+    """
+    Process coherence for a single voxel.
+
+    This function computes coherence values for a given voxel using the provided
+    coherence calculator and fMRI time course data. It returns the voxel index
+    along with coherence values and the location of the maximum coherence.
+
+    Parameters
+    ----------
+    vox : int
+        The voxel index being processed.
+    voxelargs : list
+        A list containing two elements: the coherence calculator object and
+        the fMRI time course data (fmritc).
+    **kwargs : Any
+        Additional keyword arguments that can override default options:
+        - alt : bool, optional (default: False)
+            Flag to indicate alternative computation mode.
+        - debug : bool, optional (default: False)
+            Flag to enable debug printing.
+
+    Returns
+    -------
+    tuple[int, NDArray, NDArray, float, float]
+        A tuple containing:
+        - vox : int
+            The input voxel index
+        - thecoherence_x : NDArray
+            X-axis coherence values
+        - thecoherence_y : NDArray
+            Y-axis coherence values
+        - thecoherence_y[maxindex] : float
+            Maximum coherence value
+        - thecoherence_x[maxindex] : float
+            X-coordinate corresponding to maximum coherence
+
+    Notes
+    -----
+    The function uses the `theCoherer.run()` method to compute coherence values.
+    When `alt=True`, the function returns additional dummy values from the
+    coherence calculation. The maximum coherence is determined using `np.argmax()`.
+
+    Examples
+    --------
+    >>> result = _procOneVoxelCoherence(10, [coherer_obj, fmri_data], alt=True)
+    >>> voxel_idx, x_vals, y_vals, max_coherence, max_x = result
+    """
     options = {
         "alt": False,
         "debug": False,
@@ -64,51 +113,169 @@ def _procOneVoxelCoherence(
     )
 
 
-def _packvoxeldata(voxnum, voxelargs):
+def _packvoxeldata(voxnum: int, voxelargs: list) -> list:
+    """
+    Pack voxel data for processing.
+
+    Parameters
+    ----------
+    voxnum : int
+        The voxel number to extract from the second element of voxelargs.
+    voxelargs : list
+        A list containing voxel arguments where:
+        - voxelargs[0] is the first voxel argument (returned as-is)
+        - voxelargs[1] is a 2D array from which row voxnum is extracted
+
+    Returns
+    -------
+    list
+        A list containing:
+        - voxelargs[0] (unchanged)
+        - The voxnum-th row of voxelargs[1] as a 1D array
+
+    Notes
+    -----
+    This function is typically used in voxel-based data processing workflows
+    where data needs to be extracted and reorganized for further analysis.
+
+    Examples
+    --------
+    >>> voxelargs = [10, [[1, 2, 3], [4, 5, 6], [7, 8, 9]]]
+    >>> _packvoxeldata(1, voxelargs)
+    [10, [4, 5, 6]]
+    """
     return [
         voxelargs[0],
         (voxelargs[1])[voxnum, :],
     ]
 
 
-def _unpackvoxeldata(retvals, voxelproducts):
+def _unpackvoxeldata(retvals: tuple, voxelproducts: list) -> None:
+    """
+    Unpack voxel data from retvals tuple into corresponding voxel product lists.
+
+    This function takes a tuple of voxel data and distributes the values into
+    three separate voxel product lists based on the index specified in the first
+    element of the retvals tuple.
+
+    Parameters
+    ----------
+    retvals : tuple
+        A tuple containing voxel data where:
+        - retvals[0] : int, index for insertion
+        - retvals[1] : unused
+        - retvals[2] : value to insert into voxelproducts[0]
+        - retvals[3] : value to insert into voxelproducts[1]
+        - retvals[4] : value to insert into voxelproducts[2]
+    voxelproducts : list
+        A list of three voxel product arrays/lists where:
+        - voxelproducts[0] : first voxel product array
+        - voxelproducts[1] : second voxel product array
+        - voxelproducts[2] : third voxel product array
+
+    Returns
+    -------
+    None
+        This function modifies the voxelproducts lists in-place and does not return anything.
+
+    Notes
+    -----
+    The function assumes that retvals contains exactly 5 elements and that
+    voxelproducts contains exactly 3 elements. The first element of retvals
+    is used as an index to determine the position where values should be inserted
+    into each of the three voxel product arrays.
+
+    Examples
+    --------
+    >>> voxel1 = [0, 0, 0]
+    >>> voxel2 = [0, 0, 0]
+    >>> voxel3 = [0, 0, 0]
+    >>> retvals = (1, None, 10, 20, 30)
+    >>> voxelproducts = [voxel1, voxel2, voxel3]
+    >>> _unpackvoxeldata(retvals, voxelproducts)
+    >>> print(voxel1[1])
+    10
+    >>> print(voxel2[1])
+    20
+    >>> print(voxel3[1])
+    30
+    """
     (voxelproducts[0])[retvals[0]] = retvals[2]
     (voxelproducts[1])[retvals[0]] = retvals[3]
     (voxelproducts[2])[retvals[0]] = retvals[4]
 
 
 def coherencepass(
-    fmridata,
-    theCoherer,
-    coherencefunc,
-    coherencepeakval,
-    coherencepeakfreq,
-    alt=False,
-    chunksize=1000,
-    nprocs=1,
-    alwaysmultiproc=False,
-    showprogressbar=True,
-    debug=False,
-):
+    fmridata: NDArray,
+    theCoherer: Any,
+    coherencefunc: NDArray,
+    coherencepeakval: NDArray,
+    coherencepeakfreq: NDArray,
+    alt: bool = False,
+    chunksize: int = 1000,
+    nprocs: int = 1,
+    alwaysmultiproc: bool = False,
+    showprogressbar: bool = True,
+    debug: bool = False,
+) -> int:
     """
+    Perform coherence analysis on fMRI data across voxels using multiprocessing.
+
+    This function applies coherence analysis to each voxel in the input fMRI data,
+    storing results in the provided output arrays. It supports parallel processing
+    for improved performance and includes optional debugging and progress tracking.
 
     Parameters
     ----------
-    fmridata
-    theCoherer
-    coherencefunc
-    coherencepeakval
-    coherencepeakfreq
-    chunksize
-    nprocs
-    alwaysmultiproc
-    showprogressbar
-    rt_floatset
-    rt_floattype
+    fmridata : numpy.ndarray
+        Input fMRI data array with shape (time, voxels).
+    theCoherer : Any
+        Object or function used to perform coherence calculations.
+    coherencefunc : numpy.ndarray
+        Array to store coherence function results for each voxel.
+    coherencepeakval : numpy.ndarray
+        Array to store peak coherence values for each voxel.
+    coherencepeakfreq : numpy.ndarray
+        Array to store peak coherence frequencies for each voxel.
+    alt : bool, optional
+        If True, use alternative coherence calculation method. Default is False.
+    chunksize : int, optional
+        Number of voxels to process in each chunk during multiprocessing.
+        Default is 1000.
+    nprocs : int, optional
+        Number of processes to use for multiprocessing. Default is 1.
+    alwaysmultiproc : bool, optional
+        If True, always use multiprocessing even for small datasets.
+        Default is False.
+    showprogressbar : bool, optional
+        If True, display a progress bar during processing. Default is True.
+    debug : bool, optional
+        If True, enable debug logging. Default is False.
 
     Returns
     -------
+    int
+        Total number of voxels processed.
+
+    Notes
+    -----
+    This function uses `tide_genericmultiproc.run_multiproc` to distribute
+    voxel-wise coherence computations across multiple processes. The results
+    are stored directly into the provided output arrays (`coherencefunc`,
+    `coherencepeakval`, `coherencepeakfreq`).
 
+    Examples
+    --------
+    >>> import numpy as np
+    >>> fmri_data = np.random.rand(100, 50)
+    >>> coherer = SomeCohererClass()
+    >>> coherence_func = np.zeros((100, 50))
+    >>> peak_val = np.zeros((1, 50))
+    >>> peak_freq = np.zeros((1, 50))
+    >>> n_voxels = coherencepass(
+    ...     fmri_data, coherer, coherence_func, peak_val, peak_freq
+    ... )
+    >>> print(f"Processed {n_voxels} voxels")
     """
     inputshape = np.shape(fmridata)
     voxelargs = [theCoherer, fmridata]

rapidtide/calcnullsimfunc.py

@@ -16,9 +16,12 @@
 #   limitations under the License.
 #
 #
+import logging
 import sys
+from typing import Any
 
 import numpy as np
+from numpy.typing import NDArray
 
 import rapidtide.filter as tide_filt
 import rapidtide.genericmultiproc as tide_genericmultiproc
@@ -27,10 +30,63 @@ import rapidtide.miscmath as tide_math
 
 # note: rawtimecourse has been filtered, but NOT windowed
 def _procOneNullCorrelationx(
-    vox,
-    voxelargs,
-    **kwargs,
-):
+    vox: int,
+    voxelargs: list,
+    **kwargs: Any,
+) -> tuple[int, float]:
+    """
+    Process a single voxel to compute the maximum correlation value from a null correlation test.
+
+    This function performs a permutation-based null correlation test for a given voxel. It shuffles
+    the reference time course according to the specified method and computes the cross-correlation
+    with the original time course. The maximum correlation value is returned along with the voxel index.
+
+    Parameters
+    ----------
+    vox : int
+        The voxel index to process.
+    voxelargs : list
+        A list containing the following elements in order:
+        - `normalizedreftc`: Normalized reference time course.
+        - `rawtcfft_r`: Raw FFT magnitude of the reference time course.
+        - `rawtcfft_ang`: Raw FFT phase of the reference time course.
+        - `theCorrelator`: Correlator object used for cross-correlation.
+        - `thefitter`: Fitter object used for fitting the correlation peak.
+    **kwargs : Any
+        Additional keyword arguments that can override default options:
+        - permutationmethod : str, optional
+            The method used for shuffling the reference time course.
+            Options are 'shuffle' (default) or 'phaserandom'.
+        - debug : bool, optional
+            If True, prints debug information including the permutation method used.
+
+    Returns
+    -------
+    tuple[int, float]
+        A tuple containing:
+        - vox : int
+            The voxel index passed as input.
+        - maxval : float
+            The maximum correlation value obtained from the fitted correlation.
+
+    Notes
+    -----
+    This function supports two permutation methods:
+    - 'shuffle': Randomly shuffles the reference time course.
+    - 'phaserandom': Shuffles the phase of the FFT of the reference time course while preserving
+      the magnitude.
+
+    Examples
+    --------
+    >>> result = _procOneNullCorrelationx(
+    ...     vox=10,
+    ...     voxelargs=[ref_tc, fft_r, fft_ang, correlator, fitter],
+    ...     permutationmethod='shuffle',
+    ...     debug=True
+    ... )
+    >>> print(result)
+    (10, 0.85)
+    """
 
     options = {
         "permutationmethod": "shuffle",
@@ -79,56 +135,151 @@ def _procOneNullCorrelationx(
     return vox, maxval
 
 
-def _packvoxeldata(voxnum, voxelargs):
-    return [voxelargs[0], voxelargs[1], voxelargs[2], voxelargs[3], voxelargs[4]]
+def _packvoxeldata(voxnum: int, voxelargs: list) -> list:
+    """
+    Pack voxel data into a list format.
 
+    Parameters
+    ----------
+    voxnum : int
+        The voxel number identifier.
+    voxelargs : list
+        List containing voxel arguments to be packed. Expected to contain at least 5 elements.
 
-def _unpackvoxeldata(retvals, voxelproducts):
-    (voxelproducts[0])[retvals[0]] = retvals[1]
+    Returns
+    -------
+    list
+        A list containing the first 5 elements from voxelargs in order:
+        [voxelargs[0], voxelargs[1], voxelargs[2], voxelargs[3], voxelargs[4]]
 
+    Notes
+    -----
+    This function currently returns a fixed subset of the input list. For proper functionality,
+    the voxnum parameter is not utilized in the current implementation.
 
-def getNullDistributionData(
-    Fs,
-    theCorrelator,
-    thefitter,
-    LGR,
-    numestreps=0,
-    nprocs=1,
-    alwaysmultiproc=False,
-    showprogressbar=True,
-    chunksize=1000,
-    permutationmethod="shuffle",
-    rt_floatset=np.float64,
-    rt_floattype="float64",
-    debug=False,
-):
-    r"""Calculate a set of null correlations to determine the distribution of correlation values.  This can
-    be used to find the spurious correlation threshold
+    Examples
+    --------
+    >>> _packvoxeldata(1, [10, 20, 30, 40, 50, 60])
+    [10, 20, 30, 40, 50]
+    """
+    return [voxelargs[0], voxelargs[1], voxelargs[2], voxelargs[3], voxelargs[4]]
+
+
+def _unpackvoxeldata(retvals: tuple, voxelproducts: list) -> None:
+    """
+    Unpack voxel data by assigning values to specified indices.
+
+    This function takes return values and assigns them to a specific location
+    within a voxel product structure based on the provided indices.
 
     Parameters
     ----------
-    Fs: float
-        The sample frequency of rawtimecourse, in Hz
+    retvals : tuple
+        A tuple containing two elements: the first element is the index
+        used to access the voxel product, and the second element is the
+        value to be assigned.
+    voxelproducts : list
+        A list of voxel product structures where the assignment will occur.
+        The function modifies the first element of this list in-place.
 
-    rawtimecourse : 1D numpy array
-        The test regressor.  This should be filtered to the desired bandwidth, but NOT windowed.
-        :param rawtimecourse:
+    Returns
+    -------
+    None
+        This function modifies the voxelproducts list in-place and does not
+        return any value.
 
-    corrscale: 1D numpy array
-        The time axis of the cross correlation function.
+    Notes
+    -----
+    The function assumes that voxelproducts[0] is a mutable structure (like
+    a list or array) that supports item assignment. The first element of
+    retvals is used as an index to access voxelproducts[0], and the second
+    element of retvals is assigned to that location.
 
-    filterfunc: function
-        This is a preconfigured NoncausalFilter function which is used to filter data to the desired bandwidth
+    Examples
+    --------
+    >>> voxel_data = [[0, 0, 0]]
+    >>> _unpackvoxeldata((1, 42), voxel_data)
+    >>> voxel_data
+    [[0, 42, 0]]
+    """
+    (voxelproducts[0])[retvals[0]] = retvals[1]
 
-    corrorigin: int
-        The bin number in the correlation timescale corresponding to 0.0 seconds delay
 
-    negbins: int
-        The lower edge of the search range for correlation peaks, in number of bins below corrorigin
+def getNullDistributionData(
+    Fs: float,
+    theCorrelator: Any,
+    thefitter: Any,
+    LGR: logging.Logger,
+    numestreps: int = 0,
+    nprocs: int = 1,
+    alwaysmultiproc: bool = False,
+    showprogressbar: bool = True,
+    chunksize: int = 1000,
+    permutationmethod: str = "shuffle",
+    rt_floatset: type = np.float64,
+    rt_floattype: str = "float64",
+    debug: bool = False,
+) -> NDArray:
+    """
+    Calculate a set of null correlations to determine the distribution of correlation values.
+
+    This function generates a distribution of correlation values by performing permutations
+    on the reference time course. The resulting distribution can be used to identify
+    spurious correlation thresholds.
+
+    Parameters
+    ----------
+    Fs : float
+        The sample frequency of the raw time course, in Hz.
+    theCorrelator : Any
+        An object containing the reference time course and related filtering parameters.
+    thefitter : Any
+        An object used for fitting the correlation data.
+    LGR : logging.Logger
+        Logger instance for logging messages during execution.
+    numestreps : int, optional
+        Number of null correlation estimates to compute. Default is 0.
+    nprocs : int, optional
+        Number of processes to use for multiprocessing. Default is 1.
+    alwaysmultiproc : bool, optional
+        If True, always use multiprocessing even for small datasets. Default is False.
+    showprogressbar : bool, optional
+        If True, display a progress bar during computation. Default is True.
+    chunksize : int, optional
+        Size of chunks for multiprocessing. Default is 1000.
+    permutationmethod : str, optional
+        Permutation method to use ('shuffle' or other supported methods). Default is 'shuffle'.
+    rt_floatset : type, optional
+        The floating-point type to use for internal calculations. Default is np.float64.
+    rt_floattype : str, optional
+        String representation of the floating-point type. Default is 'float64'.
+    debug : bool, optional
+        If True, enable debug output. Default is False.
+
+    Returns
+    -------
+    NDArray
+        Array of correlation values representing the null distribution.
 
-    posbins: int
-        The upper edge of the search range for correlation peaks, in number of bins above corrorigin
+    Notes
+    -----
+    This function applies normalization and filtering to the reference time course before
+    computing correlations. It supports parallel processing via multiprocessing for
+    improved performance when `numestreps` is large.
 
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from some_module import getNullDistributionData
+    >>> result = getNullDistributionData(
+    ...     Fs=100.0,
+    ...     theCorrelator=correlator_obj,
+    ...     thefitter=fitter_obj,
+    ...     LGR=logging.getLogger(__name__),
+    ...     numestreps=1000,
+    ...     nprocs=4
+    ... )
+    >>> print(f"Null correlation distribution shape: {result.shape}")
     """
     inputshape = np.asarray([numestreps])
     normalizedreftc = theCorrelator.ncprefilter.apply(