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

rapidtide/workflows/calcSimFuncMap.py

@@ -16,7 +16,10 @@
 #   limitations under the License.
 #
 #
+from typing import Any, Callable, Dict, List, Optional, Tuple, Union
+
 import numpy as np
+from numpy.typing import NDArray
 
 import rapidtide.calcsimfunc as tide_calcsimfunc
 import rapidtide.io as tide_io
@@ -27,21 +30,86 @@ import rapidtide.util as tide_util
 
 
 def makeRIPTiDeRegressors(
-    initial_fmri_x,
-    lagmin,
-    lagmax,
-    lagtcgenerator,
-    LGR,
-    nprocs=1,
-    alwaysmultiproc=False,
-    showprogressbar=True,
-    chunksize=1000,
-    targetstep=2.5,
-    edgepad=0,
-    rt_floatset=np.float64,
-    rt_floattype="float64",
-    debug=False,
-):
+    initial_fmri_x: Any,
+    lagmin: Any,
+    lagmax: Any,
+    lagtcgenerator: Any,
+    LGR: Any,
+    nprocs: int = 1,
+    alwaysmultiproc: bool = False,
+    showprogressbar: bool = True,
+    chunksize: int = 1000,
+    targetstep: float = 2.5,
+    edgepad: int = 0,
+    rt_floattype: np.dtype = np.float64,
+    debug: bool = False,
+) -> Tuple[NDArray, NDArray]:
+    """
+    Generate regressors for RIPTiDe (Regressors for Inverse Temporal Deconvolution).
+
+    This function creates a set of lagged temporal regressors based on the provided
+    parameters, which are used in the context of fMRI data analysis for temporal
+    deconvolution. It leverages the `tide_makelagged.makelaggedtcs` function to
+    compute the actual regressor matrix.
+
+    Parameters
+    ----------
+    initial_fmri_x : array_like
+        The initial fMRI time series data used to generate the regressors.
+    lagmin : float
+        The minimum lag (in seconds) to consider for regressor generation.
+    lagmax : float
+        The maximum lag (in seconds) to consider for regressor generation.
+    lagtcgenerator : callable
+        A function or callable object that generates lagged time courses.
+    LGR : object
+        An object containing parameters for the lagged time course generation.
+    nprocs : int, optional
+        Number of processes to use for parallel computation (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 processing in multiprocessing (default is 1000).
+    targetstep : float, optional
+        Target step size (in seconds) between lags (default is 2.5).
+    edgepad : int, optional
+        Number of padding steps at the beginning and end of the lag range (default is 0).
+    rt_floattype : np.dtype, optional
+        Data type for the regressor matrix (default is np.float64).
+    debug : bool, optional
+        If True, print debug information during execution (default is False).
+
+    Returns
+    -------
+    tuple of (NDArray, NDArray)
+        A tuple containing:
+        - regressorset : NDArray
+            The computed regressor matrix of shape (num_lags, num_timepoints).
+        - delaystouse : NDArray
+            The array of delay values used for regressor generation.
+
+    Notes
+    -----
+    This function is intended for use in fMRI data analysis workflows where
+    temporal deconvolution is required. The regressors generated can be used
+    in subsequent steps such as GLM fitting or temporal filtering.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> fmri_data = np.random.rand(100, 50)
+    >>> regressors, delays = makeRIPTiDeRegressors(
+    ...     initial_fmri_x=fmri_data,
+    ...     lagmin=0.0,
+    ...     lagmax=10.0,
+    ...     lagtcgenerator=my_lag_generator,
+    ...     LGR=my_lgr_object,
+    ...     nprocs=4,
+    ...     debug=True
+    ... )
+    """
     # make the RIPTiDe evs
     numdelays = int(np.round((lagmax - lagmin) / targetstep, 0))
     numregressors = numdelays + 2 * edgepad
@@ -62,7 +130,7 @@ def makeRIPTiDeRegressors(
         print(f"{delaystouse=}, {len(delaystouse)}")
         print(f"{len(initial_fmri_x)}")
 
-    regressorset = np.zeros((len(delaystouse), len(initial_fmri_x)), dtype=rt_floatset)
+    regressorset = np.zeros((len(delaystouse), len(initial_fmri_x)), dtype=rt_floattype)
 
     dummy = tide_makelagged.makelaggedtcs(
         lagtcgenerator,
@@ -75,7 +143,6 @@ def makeRIPTiDeRegressors(
         alwaysmultiproc=alwaysmultiproc,
         showprogressbar=showprogressbar,
         chunksize=chunksize,
-        rt_floatset=rt_floatset,
         rt_floattype=rt_floattype,
         debug=debug,
     )
@@ -87,54 +154,209 @@ def makeRIPTiDeRegressors(
 
 
 def calcSimFunc(
-    numvalidspatiallocs,
-    fmri_data_valid,
-    validsimcalcstart,
-    validsimcalcend,
-    osvalidsimcalcstart,
-    osvalidsimcalcend,
-    initial_fmri_x,
-    os_fmri_x,
-    theCorrelator,
-    theMutualInformationator,
-    cleaned_referencetc,
-    corrout,
-    regressorset,
-    delayvals,
-    sLFOfitmean,
-    r2value,
-    fitcoeff,
-    fitNorm,
-    meanval,
-    corrscale,
-    outputname,
-    outcorrarray,
-    validvoxels,
-    nativecorrshape,
-    theinputdata,
-    theheader,
-    lagmininpts,
-    lagmaxinpts,
-    thepass,
-    optiondict,
-    LGR,
-    TimingLGR,
-    similaritymetric="correlation",
-    simcalcoffset=0,
-    echocancel=False,
-    checkpoint=False,
-    nprocs=1,
-    alwaysmultiproc=False,
-    oversampfactor=2,
-    interptype="univariate",
-    showprogressbar=True,
-    chunksize=1000,
-    rt_floatset=np.float64,
-    rt_floattype="float64",
-    mklthreads=1,
-    threaddebug=False,
-    debug=False,
-):
+    numvalidspatiallocs: Any,
+    fmri_data_valid: Any,
+    validsimcalcstart: Any,
+    validsimcalcend: Any,
+    osvalidsimcalcstart: Any,
+    osvalidsimcalcend: Any,
+    initial_fmri_x: Any,
+    os_fmri_x: Any,
+    theCorrelator: Any,
+    theMutualInformationator: Any,
+    cleaned_referencetc: Any,
+    corrout: Any,
+    regressorset: Any,
+    delayvals: Any,
+    sLFOfitmean: Any,
+    r2value: Any,
+    fitcoeff: Any,
+    fitNorm: Any,
+    meanval: Any,
+    corrscale: Any,
+    outputname: Any,
+    outcorrarray: Any,
+    validvoxels: Any,
+    nativecorrshape: Any,
+    theinputdata: Any,
+    theheader: Any,
+    lagmininpts: Any,
+    lagmaxinpts: Any,
+    thepass: Any,
+    optiondict: Any,
+    LGR: Any,
+    TimingLGR: Any,
+    similaritymetric: str = "correlation",
+    simcalcoffset: int = 0,
+    echocancel: bool = False,
+    checkpoint: bool = False,
+    nprocs: int = 1,
+    alwaysmultiproc: bool = False,
+    oversampfactor: int = 2,
+    interptype: str = "univariate",
+    showprogressbar: bool = True,
+    chunksize: int = 1000,
+    rt_floattype: np.dtype = np.float64,
+    mklthreads: int = 1,
+    threaddebug: bool = False,
+    debug: bool = False,
+) -> str:
+    """
+    Compute similarity metrics (correlation, mutual information, or RIPtiDe) between fMRI data and a reference time series.
+
+    This function performs similarity calculations across voxels using either correlation, mutual information,
+    or a hybrid method, depending on the specified `similaritymetric`. It supports multi-processing and can
+    optionally save intermediate results.
+
+    Parameters
+    ----------
+    numvalidspatiallocs : Any
+        Number of valid spatial locations in the fMRI data.
+    fmri_data_valid : Any
+        Valid fMRI data array, typically of shape (n_voxels, n_timepoints).
+    validsimcalcstart : Any
+        Start index for valid timepoints to use in similarity calculation.
+    validsimcalcend : Any
+        End index for valid timepoints to use in similarity calculation.
+    osvalidsimcalcstart : Any
+        Start index for oversampled valid timepoints.
+    osvalidsimcalcend : Any
+        End index for oversampled valid timepoints.
+    initial_fmri_x : Any
+        Initial fMRI timepoints (e.g., for correlation).
+    os_fmri_x : Any
+        Oversampled fMRI timepoints.
+    theCorrelator : Any
+        Correlator object used for computing correlations.
+    theMutualInformationator : Any
+        Mutual information calculator object.
+    cleaned_referencetc : Any
+        Cleaned reference time series.
+    corrout : Any
+        Output array for storing correlation results.
+    regressorset : Any
+        Set of regressors for fitting.
+    delayvals : Any
+        Array of delay values for RIPtiDe calculation.
+    sLFOfitmean : Any
+        Mean value for fitting.
+    r2value : Any
+        R² values for model fit.
+    fitcoeff : Any
+        Fitting coefficients.
+    fitNorm : Any
+        Normalization values for fitting.
+    meanval : Any
+        Mean value used in normalization.
+    corrscale : Any
+        Correlation scale for lag calculation.
+    outputname : Any
+        Base name for output files.
+    outcorrarray : Any
+        Array to store correlation output for checkpointing.
+    validvoxels : Any
+        Indices of valid voxels.
+    nativecorrshape : Any
+        Shape of the native correlation array.
+    theinputdata : Any
+        Input data object.
+    theheader : Any
+        Header information for NIfTI output.
+    lagmininpts : Any
+        Minimum lag in timepoints.
+    lagmaxinpts : Any
+        Maximum lag in timepoints.
+    thepass : Any
+        Pass number for tracking multiple iterations.
+    optiondict : Any
+        Dictionary of options for saving results.
+    LGR : Any
+        Logger for general messages.
+    TimingLGR : Any
+        Logger for timing information.
+    similaritymetric : str, optional
+        Type of similarity metric to compute. Options are:
+        'correlation', 'mutualinfo', 'riptide', or 'hybrid'. Default is 'correlation'.
+    simcalcoffset : int, optional
+        Offset to subtract from computed lags. Default is 0.
+    echocancel : bool, optional
+        Whether to cancel echo effects. Default is False.
+    checkpoint : bool, optional
+        Whether to save intermediate results. Default is False.
+    nprocs : int, optional
+        Number of processes for multiprocessing. Default is 1.
+    alwaysmultiproc : bool, optional
+        Force multiprocessing even for single-core cases. Default is False.
+    oversampfactor : int, optional
+        Oversampling factor for interpolation. Default is 2.
+    interptype : str, optional
+        Interpolation type. Default is 'univariate'.
+    showprogressbar : bool, optional
+        Whether to show a progress bar. Default is True.
+    chunksize : int, optional
+        Size of chunks for processing. Default is 1000.
+    rt_floattype : np.dtype, optional
+        Rapidtide floating-point data type. Default is np.float64.
+    mklthreads : int, optional
+        Number of threads for Intel MKL. Default is 1.
+    threaddebug : bool, optional
+        Enable thread debugging. Default is False.
+    debug : bool, optional
+        Enable debug mode. Default is False.
+
+    Returns
+    -------
+    str
+        The type of similarity metric used in the calculation.
+
+    Notes
+    -----
+    - For 'riptide', the function fits linear models to delayed regressors.
+    - The function logs timing and processing information using `TimingLGR` and `LGR`.
+    - If `checkpoint` is True, intermediate correlation results are saved to disk.
+    - This function modifies `corrout` and `outcorrarray` in-place.
+
+    Examples
+    --------
+    >>> calcSimFunc(
+    ...     numvalidspatiallocs=100,
+    ...     fmri_data_valid=np.random.rand(100, 100),
+    ...     validsimcalcstart=0,
+    ...     validsimcalcend=99,
+    ...     osvalidsimcalcstart=0,
+    ...     osvalidsimcalcend=99,
+    ...     initial_fmri_x=np.linspace(0, 1, 100),
+    ...     os_fmri_x=np.linspace(0, 1, 100),
+    ...     theCorrelator=correlator_obj,
+    ...     theMutualInformationator=mi_obj,
+    ...     cleaned_referencetc=np.random.rand(100),
+    ...     corrout=np.zeros((100, 100)),
+    ...     regressorset=np.random.rand(10, 100),
+    ...     delayvals=np.array([0, 1, 2]),
+    ...     sLFOfitmean=np.mean(np.random.rand(100)),
+    ...     r2value=np.zeros(100),
+    ...     fitcoeff=np.zeros((100, 1)),
+    ...     fitNorm=np.ones(100),
+    ...     meanval=np.mean(np.random.rand(100)),
+    ...     corrscale=np.arange(100),
+    ...     outputname="test_output",
+    ...     outcorrarray=np.zeros((100, 100)),
+    ...     validvoxels=np.arange(100),
+    ...     nativecorrshape=(100, 100),
+    ...     theinputdata=input_data_obj,
+    ...     theheader=header,
+    ...     lagmininpts=-5,
+    ...     lagmaxinpts=5,
+    ...     thepass=1,
+    ...     optiondict={},
+    ...     LGR=logging.getLogger(),
+    ...     TimingLGR=logging.getLogger(),
+    ...     similaritymetric="correlation",
+    ...     nprocs=2,
+    ...     checkpoint=True,
+    ... )
+    'Correlation'
+    """
     # Step 1 - Correlation step
     if similaritymetric == "mutualinfo":
         similaritytype = "Mutual information"
@@ -170,7 +392,6 @@ def calcSimFunc(
             interptype=interptype,
             showprogressbar=showprogressbar,
             chunksize=chunksize,
-            rt_floatset=rt_floatset,
             rt_floattype=rt_floattype,
             debug=debug,
         )
@@ -195,7 +416,6 @@ def calcSimFunc(
             interptype=interptype,
             showprogressbar=showprogressbar,
             chunksize=chunksize,
-            rt_floatset=rt_floatset,
             rt_floattype=rt_floattype,
             debug=debug,
         )
@@ -216,13 +436,12 @@ def calcSimFunc(
                 None,
                 None,
                 coefficientsonly=True,
-                voxelspecific=False,
+                constantevs=True,
                 nprocs=nprocs,
                 alwaysmultiproc=alwaysmultiproc,
                 showprogressbar=showprogressbar,
                 verbose=(LGR is not None),
                 chunksize=chunksize,
-                rt_floatset=rt_floatset,
                 rt_floattype=rt_floattype,
                 debug=debug,
             )

rapidtide/workflows/calctexticc.py

@@ -20,8 +20,11 @@ import argparse
 import platform
 import sys
 import time
+from argparse import Namespace
+from typing import Any, Callable, Dict, List, Optional, Tuple, Union
 
 import numpy as np
+from numpy.typing import NDArray
 from scipy.linalg import pinv
 
 import rapidtide.io as tide_io
@@ -30,7 +33,42 @@ import rapidtide.util as tide_util
 from rapidtide.workflows.parser_funcs import is_valid_file
 
 
-def _get_parser():
+def _get_parser() -> Any:
+    """
+    Create and configure an argument parser for the calcicc command-line tool.
+
+    This function sets up an `argparse.ArgumentParser` with required and optional
+    arguments needed to run the ICC(3,1) calculation on text-based data files.
+
+    Returns
+    -------
+    argparse.ArgumentParser
+        Configured argument parser object with all required and optional arguments
+        for the calcicc tool.
+
+    Notes
+    -----
+    The parser is configured with:
+    - A program name "calcicc"
+    - A description explaining the purpose of the tool
+    - Three required positional arguments:
+        1. `datafile`: comma-separated list of 2D text files
+        2. `measurementlist`: multicolumn file specifying how to group measurements
+        3. `outputroot`: root name for output text files
+    - Several optional flags for controlling behavior:
+        - `--demedian`: subtract median from each map before ICC calculation
+        - `--demean`: subtract mean from each map before ICC calculation
+        - `--nocache`: disable caching for ICC calculation (not recommended)
+        - `--debug`: enable basic debugging output
+        - `--deepdebug`: enable verbose debugging output
+
+    Examples
+    --------
+    >>> parser = _get_parser()
+    >>> args = parser.parse_args(['file1.txt', 'measurements.txt', 'output_root'])
+    >>> print(args.datafile)
+    'file1.txt'
+    """
     parser = argparse.ArgumentParser(
         prog="calcicc",
         description="Calculate per-column ICC(3,1) on a set of text files.",
@@ -105,7 +143,55 @@ def _get_parser():
     return parser
 
 
-def parsetextmeasurementlist(measlist, numfiles, debug=False):
+def parsetextmeasurementlist(
+    measlist: Any, numfiles: Any, debug: bool = False
+) -> Tuple[NDArray, NDArray]:
+    """
+    Parse a measurement list from text format into file and volume indices.
+
+    This function processes a 2D array of strings representing measurement entries,
+    where each entry is expected to contain either one or two comma-separated values.
+    The first value represents the file index, and the second represents the volume index.
+    If only one value is present, the file index is assumed to be 0.
+
+    Parameters
+    ----------
+    measlist : array-like
+        A 2D array of strings where each string contains either one or two
+        comma-separated integers representing file and volume indices.
+    numfiles : int
+        The total number of available files, used to validate file indices.
+    debug : bool, optional
+        If True, prints debug information for each parsed element. Default is False.
+
+    Returns
+    -------
+    tuple of ndarray
+        A tuple containing two 2D arrays:
+        - `filesel`: File indices for each measurement.
+        - `volumesel`: Volume indices for each measurement.
+
+    Notes
+    -----
+    - Each entry in `measlist` should be a string of the form "file,volume" or "volume".
+    - File indices are validated to ensure they do not exceed `numfiles - 1`.
+    - The function will exit with an error if:
+        1. An entry contains more than one comma.
+        2. A file index is out of bounds.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> measlist = np.array([["0,1", "1,2"], ["0", "2,3"]])
+    >>> numfiles = 3
+    >>> filesel, volumesel = parsetextmeasurementlist(measlist, numfiles)
+    >>> print(filesel)
+    [[0 1]
+     [0 2]]
+    >>> print(volumesel)
+    [[1 2]
+     [0 3]]
+    """
     # how do we get the number of subjects?
     nummeas, numsubjs = measlist.shape[0], measlist.shape[1]
     filesel = np.zeros((nummeas, numsubjs), dtype=int)
@@ -134,7 +220,54 @@ def parsetextmeasurementlist(measlist, numfiles, debug=False):
     return filesel, volumesel
 
 
-def makdcommandlinelist(arglist, starttime, endtime, extra=None):
+def makdcommandlinelist(
+    arglist: Any, starttime: Any, endtime: Any, extra: Optional[Any] = None
+) -> Tuple[str, str, str, str, str] | Tuple[str, str, str, str]:
+    """
+    Create a list of command line information for processing metadata.
+
+    This function generates a list of descriptive strings containing processing
+    information including timestamps, version details, and the command line
+    that was executed.
+
+    Parameters
+    ----------
+    arglist : Any
+        List of command line arguments that were used to invoke the process
+    starttime : Any
+        Start time of the process, typically a timestamp or time object
+    endtime : Any
+        End time of the process, typically a timestamp or time object
+    extra : Any, optional
+        Additional descriptive text to include in the output list, by default None
+
+    Returns
+    -------
+    list of str
+        List containing metadata strings with processing information:
+        - Processing date and time
+        - Processing duration
+        - Version and system information
+        - Extra information (if provided)
+        - The original command line
+
+    Notes
+    -----
+    The function uses `time.strftime` to format the start time and calculates
+    the processing duration by subtracting starttime from endtime. It also
+    retrieves version information using `tide_util.version()` and system
+    information using `platform.node()`.
+
+    Examples
+    --------
+    >>> import time
+    >>> args = ['python', 'script.py', '--input', 'data.txt']
+    >>> start = time.time() - 10
+    >>> end = time.time()
+    >>> result = makdcommandlinelist(args, start, end)
+    >>> print(result[0])
+    '# Processed on Mon, 01 Jan 2024 12:00:00 UTC.'
+    """
     # get the processing date
     dateline = (
         "# Processed on "
@@ -166,12 +299,71 @@ def makdcommandlinelist(arglist, starttime, endtime, extra=None):
     commandline = " ".join(arglist)
 
     if extra is not None:
-        return [dateline, timeline, nodeline, "# " + extra, commandline]
+        return dateline, timeline, nodeline, f"# {extra}", commandline
     else:
-        return [dateline, timeline, nodeline, commandline]
-
-
-def calctexticc(args):
+        return dateline, timeline, nodeline, commandline
+
+
+def calctexticc(args: Any) -> None:
+    """
+    Calculate intraclass correlation coefficients (ICC) for text-based measurement data across subjects.
+
+    This function reads measurement lists and corresponding data files, processes the data to
+    compute ICC(3,1) values for each voxel, and writes out the results along with variance components
+    and session effect F-values.
+
+    Parameters
+    ----------
+    args : Any
+        An object containing command-line arguments. Expected attributes include:
+        - datafile : str
+            Comma-separated list of input data file paths.
+        - measurementlist : str
+            Path to the measurement list file.
+        - outputroot : str
+            Root name for output files.
+        - debug : bool, optional
+            Enable debug printing.
+        - deepdebug : bool, optional
+            Enable deep debug printing.
+        - demedian : bool, optional
+            Remove median from each subject's measurements.
+        - demean : bool, optional
+            Remove mean from each subject's measurements.
+        - nocache : bool, optional
+            Disable caching during ICC calculation.
+
+    Returns
+    -------
+    None
+        The function does not return a value but writes multiple output files:
+        - `{outputroot}_ICC.txt`
+        - `{outputroot}_r_var.txt`
+        - `{outputroot}_e_var.txt`
+        - `{outputroot}_session_effect_F.txt`
+        - `{outputroot}_commandline.txt`
+
+    Notes
+    -----
+    The function reshapes data into a voxel-by-subject-by-measurement format and computes ICC(3,1)
+    using a repeated measures ANOVA approach. It supports optional mean/median removal for each
+    subject and measurement.
+
+    Examples
+    --------
+    >>> import argparse
+    >>> args = argparse.Namespace(
+    ...     datafile="data1.txt,data2.txt",
+    ...     measurementlist="meas_list.txt",
+    ...     outputroot="output",
+    ...     debug=False,
+    ...     deepdebug=False,
+    ...     demedian=False,
+    ...     demean=False,
+    ...     nocache=False
+    ... )
+    >>> calctexticc(args)
+    """
     runstarttime = time.time()
 
     datafiles = (args.datafile).split(",")
@@ -297,4 +489,4 @@ def calctexticc(args):
 
     runendtime = time.time()
     thecommandfilelines = makdcommandlinelist(sys.argv, runstarttime, runendtime, extra=extraline)
-    tide_io.writevec(thecommandfilelines, args.outputroot + "_commandline.txt")
+    tide_io.writevec(np.asarray(thecommandfilelines), args.outputroot + "_commandline.txt")