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

rapidtide/__init__.py

@@ -2,11 +2,3 @@
 from . import _version
 
 __version__ = _version.get_versions()["version"]
-
-from . import _version
-
-__version__ = _version.get_versions()["version"]
-
-from . import _version
-
-__version__ = _version.get_versions()["version"]

rapidtide/_version.py

@@ -1,5 +1,5 @@
 
-# This file was generated by 'versioneer.py' (0.28) from
+# This file was generated by 'versioneer.py' (0.29) from
 # revision-control system data, or from the parent directory name of an
 # unpacked source archive. Distribution tarballs contain a pre-generated copy
 # of this file.
@@ -8,11 +8,11 @@ import json
 
 version_json = '''
 {
- "date": "2024-09-05T20:58:41-0400",
+ "date": "2026-01-21T11:49:41-0500",
  "dirty": false,
  "error": null,
- "full-revisionid": "3a4b12ec4332b98aa4adfd39414bc67924abbf78",
- "version": "2.9.6"
+ "full-revisionid": "63ac9a63f9549380f07bf90d8c5f0d80db38bb53",
+ "version": "3.1.3"
 }
 '''  # END VERSION_JSON
 

rapidtide/calccoherence.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.
@@ -19,19 +19,79 @@
 import gc
 import logging
 import warnings
+from typing import Any
 
 import numpy as np
-from tqdm import tqdm
+from numpy.typing import NDArray
 
-import rapidtide.multiproc as tide_multiproc
+import rapidtide.genericmultiproc as tide_genericmultiproc
 
 warnings.simplefilter(action="ignore", category=FutureWarning)
 LGR = logging.getLogger("GENERAL")
 
 
 def _procOneVoxelCoherence(
-    vox, theCoherer, fmritc, alt=False, rt_floatset=np.float64, rt_floattype="float64"
-):
+    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,
+    }
+    options.update(kwargs)
+    alt = options["alt"]
+    debug = options["debug"]
+    (theCoherer, fmritc) = voxelargs
+    if debug:
+        print(f"{alt=}")
     if alt:
         (
             thecoherence_y,
@@ -53,109 +113,194 @@ def _procOneVoxelCoherence(
     )
 
 
+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: 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,
-    rt_floatset=np.float64,
-    rt_floattype="float64",
-):
+    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 : NDArray
+        Input fMRI data array with shape (time, voxels).
+    theCoherer : Any
+        Object or function used to perform coherence calculations.
+    coherencefunc : NDArray
+        Array to store coherence function results for each voxel.
+    coherencepeakval : NDArray
+        Array to store peak coherence values for each voxel.
+    coherencepeakfreq : 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)
-    volumetotal = 0
-    if nprocs > 1 or alwaysmultiproc:
-        # define the consumer function here so it inherits most of the arguments
-        def coherence_consumer(inQ, outQ):
-            while True:
-                try:
-                    # get a new message
-                    val = inQ.get()
-
-                    # this is the 'TERM' signal
-                    if val is None:
-                        break
-
-                    # process and send the data
-                    outQ.put(
-                        _procOneVoxelCoherence(
-                            val,
-                            theCoherer,
-                            fmridata[val, :],
-                            alt=alt,
-                            rt_floatset=rt_floatset,
-                            rt_floattype=rt_floattype,
-                        )
-                    )
-
-                except Exception as e:
-                    print("error!", e)
-                    break
-
-        data_out = tide_multiproc.run_multiproc(
-            coherence_consumer,
-            inputshape,
-            None,
-            nprocs=nprocs,
-            showprogressbar=showprogressbar,
-            chunksize=chunksize,
-        )
-
-        # unpack the data
-        volumetotal = 0
-        for voxel in data_out:
-            coherencefunc[voxel[0], :] = voxel[2] + 0.0
-            coherencepeakval[voxel[0]] = voxel[3] + 0.0
-            coherencepeakfreq[voxel[0]] = voxel[4] + 0.0
-            volumetotal += 1
-        del data_out
-    else:
-        for vox in tqdm(
-            range(0, inputshape[0]),
-            desc="Voxel",
-            unit="voxels",
-            disable=(not showprogressbar),
-        ):
-            (
-                dummy,
-                dummy,
-                coherencefunc[vox],
-                coherencepeakval[vox],
-                coherencepeakfreq[vox],
-            ) = _procOneVoxelCoherence(
-                vox,
-                theCoherer,
-                fmridata[vox, :],
-                alt=alt,
-                rt_floatset=rt_floatset,
-                rt_floattype=rt_floattype,
-            )
-            volumetotal += 1
+    voxelargs = [theCoherer, fmridata]
+    voxelfunc = _procOneVoxelCoherence
+    packfunc = _packvoxeldata
+    unpackfunc = _unpackvoxeldata
+    voxeltargets = [coherencefunc, coherencepeakval, coherencepeakfreq]
+    voxelmask = np.ones_like(fmridata[:, 0])
+
+    volumetotal = tide_genericmultiproc.run_multiproc(
+        voxelfunc,
+        packfunc,
+        unpackfunc,
+        voxelargs,
+        voxeltargets,
+        inputshape,
+        voxelmask,
+        LGR,
+        nprocs,
+        alwaysmultiproc,
+        showprogressbar,
+        chunksize,
+        alt=alt,
+        debug=debug,
+    )
     LGR.info(f"\nCoherence performed on {volumetotal} voxels")
 
     # garbage collect