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

rapidtide/workflows/ccorrica.py

@@ -21,9 +21,12 @@ import warnings
 warnings.simplefilter(action="ignore", category=FutureWarning)
 import argparse
 import sys
+from argparse import Namespace
+from typing import Any, Callable, Dict, List, Optional, Tuple, Union
 
 import nibabel as nib
 import numpy as np
+from numpy.typing import NDArray
 from scipy.stats import pearsonr
 
 import rapidtide.correlate as tide_corr
@@ -38,9 +41,29 @@ DEFAULT_DETREND_ORDER = 3
 DEFAULT_CORRWEIGHTING = "phat"
 
 
-def _get_parser():
+def _get_parser() -> Any:
     """
-    Argument parser for ccorrica
+    Argument parser for ccorrica.
+
+    This function constructs and returns an `argparse.ArgumentParser` object configured
+    with all required and optional arguments for the `ccorrica` tool, which computes
+    temporal cross-correlations between timecourses.
+
+    Returns
+    -------
+    argparse.ArgumentParser
+        Configured argument parser for the ccorrica tool.
+
+    Notes
+    -----
+    The parser includes support for specifying sample rate or timestep, windowing options,
+    search range parameters, filtering, correlation weighting methods, detrending, and
+    oversampling factors. It also supports debugging output.
+
+    Examples
+    --------
+    >>> parser = _get_parser()
+    >>> args = parser.parse_args(['--timecoursefile', 'data.txt', '--outputroot', 'out'])
     """
     parser = argparse.ArgumentParser(
         prog="ccorrica",
@@ -134,7 +157,77 @@ def _get_parser():
     return parser
 
 
-def ccorrica(args):
+def ccorrica(args: Any) -> None:
+    """
+    Compute cross-correlations between time series components and save results in NIfTI and text formats.
+
+    This function reads time course data from a text file, applies preprocessing including
+    filtering, resampling, detrending, and windowing, then computes cross-correlations
+    between all pairs of components. The results are saved as NIfTI files and text vectors
+    for further analysis.
+
+    Parameters
+    ----------
+    args : argparse.Namespace
+        Command-line arguments containing configuration options such as:
+        - timecoursefile : str
+            Path to the input time course file.
+        - samplerate : float or str
+            Sampling rate of the data. If "auto", it must be specified in the file header.
+        - oversampfactor : int
+            Oversampling factor for upsampling the data. If less than 0, it is auto-computed.
+        - detrendorder : int
+            Order of detrending to apply.
+        - windowfunc : str
+            Windowing function to apply.
+        - corrweighting : str
+            Type of weighting to use in correlation computation.
+        - debug : bool
+            If True, display plots during correlation computation.
+        - outputroot : str
+            Root name for output files.
+
+    Returns
+    -------
+    None
+        This function does not return a value but saves multiple output files:
+        - `_filtereddata.txt`: Filtered time series.
+        - `_xcorr.nii.gz`: Cross-correlation data as 4D NIfTI.
+        - `_pxcorr.nii.gz`: Pearson correlation coefficients.
+        - `_corrmax.nii.gz`: Maximum correlation values.
+        - `_corrlag.nii.gz`: Lag at maximum correlation.
+        - `_corrwidth.nii.gz`: Width of the correlation peak.
+        - `_corrmask.nii.gz`: Mask indicating correlation significance.
+        - `_reformdata.txt`: Final reformatted and normalized data.
+
+    Notes
+    -----
+    The function performs the following steps:
+    1. Reads input data from a text file.
+    2. Applies post-processing filter options.
+    3. Resamples data if necessary.
+    4. Filters data using a specified prefilter.
+    5. Normalizes data using standard and correlation normalization.
+    6. Computes cross-correlations using fast FFT-based methods.
+    7. Fits Gaussian peaks to find maximum correlation lag and width.
+    8. Saves symmetric matrices for correlation maxima, lags, widths, and masks.
+    9. Outputs results in both NIfTI and text formats.
+
+    Examples
+    --------
+    >>> import argparse
+    >>> args = argparse.Namespace(
+    ...     timecoursefile='data.txt',
+    ...     samplerate=2.0,
+    ...     oversampfactor=1,
+    ...     detrendorder=1,
+    ...     windowfunc='hanning',
+    ...     corrweighting='none',
+    ...     debug=False,
+    ...     outputroot='output'
+    ... )
+    >>> ccorrica(args)
+    """
     args, theprefilter = pf.postprocessfilteropts(args)
 
     # read in data
@@ -172,7 +265,7 @@ def ccorrica(args):
     if args.oversampfactor == 1:
         print("data array shape is ", reformdata.shape)
     else:
-        resampdata = np.zeros((numcomponents, tclen * args.oversampfactor), dtype=np.float)
+        resampdata = np.zeros((numcomponents, tclen * args.oversampfactor), dtype=float)
         for component in range(0, numcomponents):
             resampdata[component, :] = tide_resample.upsample(
                 reformdata[component, :], Fs, Fs * args.oversampfactor, intfac=True

rapidtide/workflows/cleanregressor.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.correlate as tide_corr
 import rapidtide.filter as tide_filt
@@ -27,35 +30,171 @@ import rapidtide.simfuncfit as tide_simfuncfit
 
 
 def cleanregressor(
-    outputname,
-    thepass,
-    referencetc,
-    resampref_y,
-    resampnonosref_y,
-    fmrifreq,
-    oversampfreq,
-    osvalidsimcalcstart,
-    osvalidsimcalcend,
-    lagmininpts,
-    lagmaxinpts,
-    theFitter,
-    theCorrelator,
-    lagmin,
-    lagmax,
-    LGR=None,
-    check_autocorrelation=True,
-    fix_autocorrelation=True,
-    despeckle_thresh=5.0,
-    lthreshval=0.0,
-    fixdelay=False,
-    detrendorder=3,
-    windowfunc="hamming",
-    respdelete=False,
-    displayplots=False,
-    debug=False,
-    rt_floattype="float64",
-    rt_floatset=np.float64,
-):
+    outputname: Any,
+    thepass: Any,
+    referencetc: Any,
+    resampref_y: Any,
+    resampnonosref_y: Any,
+    fmrifreq: Any,
+    oversampfreq: Any,
+    osvalidsimcalcstart: Any,
+    osvalidsimcalcend: Any,
+    lagmininpts: Any,
+    lagmaxinpts: Any,
+    theFitter: Any,
+    theCorrelator: Any,
+    lagmin: Any,
+    lagmax: Any,
+    LGR: Optional[Any] = None,
+    check_autocorrelation: bool = True,
+    fix_autocorrelation: bool = True,
+    despeckle_thresh: float = 5.0,
+    lthreshval: float = 0.0,
+    fixdelay: bool = False,
+    detrendorder: int = 3,
+    windowfunc: str = "hamming",
+    respdelete: bool = False,
+    displayplots: bool = False,
+    debug: bool = False,
+    rt_floattype: str = "float64",
+    rt_floatset: Any = np.float64,
+) -> Tuple[
+    NDArray,
+    NDArray,
+    NDArray,
+    float,
+    float | None,
+    float | None,
+    float,
+    float | None,
+    float | None,
+]:
+    """
+    Clean and preprocess a regressor signal by checking and correcting autocorrelation properties.
+
+    This function performs several operations on the input regressor signal, including:
+    detrending, normalization, optional filtering to remove periodic components, and
+    autocorrelation analysis to detect and correct sidelobes. It returns cleaned versions
+    of the regressor and associated metadata for further use in time series analysis.
+
+    Parameters
+    ----------
+    outputname : Any
+        Base name for output files.
+    thepass : Any
+        Pass identifier, used for labeling output files.
+    referencetc : Any
+        Reference time course data (normalized).
+    resampref_y : Any
+        Resampled reference signal.
+    resampnonosref_y : Any
+        Non-oversampled reference signal.
+    fmrifreq : Any
+        fMRI sampling frequency.
+    oversampfreq : Any
+        Oversampled frequency.
+    osvalidsimcalcstart : Any
+        Start index for valid data in oversampled signal.
+    osvalidsimcalcend : Any
+        End index for valid data in oversampled signal.
+    lagmininpts : Any
+        Minimum lag in samples for autocorrelation calculation.
+    lagmaxinpts : Any
+        Maximum lag in samples for autocorrelation calculation.
+    theFitter : Any
+        Fitter object for fitting autocorrelation data.
+    theCorrelator : Any
+        Correlator object for computing cross-correlations.
+    lagmin : Any
+        Minimum lag in seconds.
+    lagmax : Any
+        Maximum lag in seconds.
+    LGR : Optional[Any], optional
+        Logger object for logging messages. Default is None.
+    check_autocorrelation : bool, optional
+        If True, perform autocorrelation checks. Default is True.
+    fix_autocorrelation : bool, optional
+        If True, attempt to fix detected autocorrelation issues. Default is True.
+    despeckle_thresh : float, optional
+        Threshold for despeckling autocorrelation data. Default is 5.0.
+    lthreshval : float, optional
+        Low threshold value for fitting. Default is 0.0.
+    fixdelay : bool, optional
+        If True, fix delay in fitting. Default is False.
+    detrendorder : int, optional
+        Order of detrending polynomial. Default is 3.
+    windowfunc : str, optional
+        Window function to use for normalization. Default is "hamming".
+    respdelete : bool, optional
+        If True, remove periodic components from the reference signal. Default is False.
+    displayplots : bool, optional
+        If True, display plots during processing. Default is False.
+    debug : bool, optional
+        If True, print debugging information. Default is False.
+    rt_floattype : str, optional
+        Data type for real-time processing. Default is "float64".
+    rt_floatset : Any, optional
+        Float type setting for real-time processing. Default is np.float64.
+
+    Returns
+    -------
+    tuple
+        A tuple containing:
+        - cleaned_resampref_y : np.ndarray
+            Cleaned resampled reference signal.
+        - cleaned_referencetc : np.ndarray
+            Cleaned reference time course.
+        - cleaned_nonosreferencetc : np.ndarray
+            Cleaned non-oversampled reference signal.
+        - despeckle_thresh : float
+            Updated despeckle threshold.
+        - sidelobeamp : float or None
+            Amplitude of detected sidelobe, or None if not found.
+        - sidelobetime : float or None
+            Time of detected sidelobe in seconds, or None if not found.
+        - lagmod : float
+            Lag modulus value used for correction.
+        - acwidth : float or None
+            Width of autocorrelation function, or None if not computed.
+        - absmaxsigma : float or None
+            Absolute maximum sigma value, or None if not computed.
+
+    Notes
+    -----
+    - If `respdelete` is True, the function applies frequency tracking and filtering to remove
+      periodic components from the reference signal.
+    - Autocorrelation analysis is performed using `tide_corr.check_autocorrelation` to detect
+      sidelobes that may affect the regressor quality.
+    - If `fix_autocorrelation` is True, detected sidelobes are corrected by applying a notch filter
+      and adjusting the lag modulus.
+
+    Examples
+    --------
+    >>> cleanregressor(
+    ...     outputname="test_output",
+    ...     thepass=1,
+    ...     referencetc=ref_tc,
+    ...     resampref_y=resamp_ref,
+    ...     resampnonosref_y=resamp_nonos_ref,
+    ...     fmrifreq=2.0,
+    ...     oversampfreq=10.0,
+    ...     osvalidsimcalcstart=0,
+    ...     osvalidsimcalcend=100,
+    ...     lagmininpts=5,
+    ...     lagmaxinpts=20,
+    ...     theFitter=fitter,
+    ...     theCorrelator=correlator,
+    ...     lagmin=-10,
+    ...     lagmax=10,
+    ...     check_autocorrelation=True,
+    ...     fix_autocorrelation=True,
+    ...     detrendorder=3,
+    ...     windowfunc="hamming",
+    ...     respdelete=False,
+    ...     displayplots=False,
+    ...     debug=False,
+    ... )
+    """
     # print debugging info
     if debug:
         print("cleanregressor:")

rapidtide/workflows/delayvar.py

@@ -22,9 +22,12 @@ import logging
 import os
 import sys
 import time
+from argparse import Namespace
 from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional, Tuple, Union
 
 import numpy as np
+from numpy.typing import NDArray
 from scipy.stats import pearsonr
 from sklearn.decomposition import PCA
 from tf_keras.src.dtensor.integration_test_utils import train_step
@@ -63,14 +66,34 @@ DEFAULT_DELAYOFFSETSPATIALFILT = -1
 DEFAULT_WINDOWSIZE = 30.0
 DEFAULT_SYSTEMICFITTYPE = "pca"
 DEFAULT_PCACOMPONENTS = 1
-DEFAULT_LAGMIN = 0.0
-DEFAULT_LAGMAX = 0.0
+DEFAULT_LAGMIN = -999
+DEFAULT_LAGMAX = -999
 DEFAULT_TRAINSTEP = 0.5
 
 
-def _get_parser():
+def _get_parser() -> Any:
     """
-    Argument parser for glmfilt
+    Argument parser for glmfilt.
+
+    This function constructs and returns an `argparse.ArgumentParser` object configured
+    for parsing command-line arguments used by the `glmfilt` tool. It defines required
+    and optional arguments for processing fMRI data, including file paths, filtering
+    options, output settings, and experimental parameters.
+
+    Returns
+    -------
+    argparse.ArgumentParser
+        Configured argument parser for the glmfilt tool.
+
+    Notes
+    -----
+    The parser includes both standard and experimental options. Experimental options
+    are marked as such and may not be fully tested or stable.
+
+    Examples
+    --------
+    >>> parser = _get_parser()
+    >>> args = parser.parse_args()
     """
     parser = argparse.ArgumentParser(
         prog="delayvar",
@@ -265,7 +288,102 @@ def _get_parser():
     return parser
 
 
-def delayvar(args):
+def delayvar(args: Any) -> None:
+    """
+    Perform windowed delay variance analysis on fMRI data.
+
+    This function conducts a comprehensive delay variance analysis on fMRI data,
+    computing delay offsets for each voxel across temporal windows. It supports
+    various filtering options, PCA-based systemic component removal, and outputs
+    detailed timing information and processed maps.
+
+    Parameters
+    ----------
+    args : Any
+        Namespace object containing all required arguments for the analysis.
+        Expected attributes include:
+        - fmrifile : str
+            Path to the input fMRI NIfTI file.
+        - datafileroot : str
+            Root name for output files.
+        - lag_extrema : tuple of int
+            Minimum and maximum lag values for analysis.
+        - alternateoutput : str, optional
+            Alternate output name.
+        - debug : bool
+            Enable debug mode.
+        - outputlevel : str
+            Level of output files to save ('min', 'less', 'normal', 'more', 'max').
+        - nprocs : int
+            Number of processes to use.
+        - hpf : bool
+            Apply highpass filtering.
+        - windowsize : float
+            Size of temporal windows in seconds.
+        - windelayoffsetgausssigma : float
+            Sigma for Gaussian smoothing of delay offsets.
+        - delaypatchthresh : float
+            Threshold for patch-based delay correction.
+        - systemicfittype : str
+            Type of systemic component removal ('pca' or 'mean').
+        - pcacomponents : float
+            Number of PCA components to use.
+        - trainstep : float
+            Step size for training the delay model.
+        - numskip : int
+            Number of initial timepoints to skip.
+        - focaldebug : bool
+            Enable focal debugging mode.
+        - verbose : bool
+            Enable verbose output.
+        - showprogressbar : bool
+            Show progress bar during processing.
+
+    Returns
+    -------
+    None
+        This function does not return a value but writes multiple output files
+        including:
+        - Delay offset maps in temporal windows
+        - Systemic component timeseries
+        - PCA component information
+        - Timing and runoptions files
+        - Histograms of delay offsets
+        - Various intermediate processing results
+
+    Notes
+    -----
+    The function performs the following key steps:
+    1. Windowed processing of fMRI data
+    2. Derivative ratio calculation and filtering
+    3. Delay offset training and calculation
+    4. Systemic component removal (PCA or mean)
+    5. Output generation and cleanup
+
+    Examples
+    --------
+    >>> import argparse
+    >>> args = argparse.Namespace(
+    ...     fmrifile='data.nii.gz',
+    ...     datafileroot='output',
+    ...     lag_extrema=(0, 10),
+    ...     debug=False,
+    ...     outputlevel='normal',
+    ...     nprocs=4,
+    ...     hpf=True,
+    ...     windowsize=30.0,
+    ...     windelayoffsetgausssigma=2.0,
+    ...     delaypatchthresh=0.5,
+    ...     systemicfittype='pca',
+    ...     pcacomponents=0.8,
+    ...     trainstep=0.1,
+    ...     numskip=5,
+    ...     focaldebug=False,
+    ...     verbose=True,
+    ...     showprogressbar=True
+    ... )
+    >>> delayvar(args)
+    """
     # get the pid of the parent process
     args.pid = os.getpid()
 
@@ -289,7 +407,7 @@ def delayvar(args):
         logger_filename=f"{outputname}_retrolog.txt",
         timing_filename=f"{outputname}_retroruntimings.tsv",
         error_filename=f"{outputname}_retroerrorlog.txt",
-        verbose=False,
+        isverbose=False,
         debug=args.debug,
     )
     TimingLGR.info("Start")
@@ -618,8 +736,12 @@ def delayvar(args):
     winsLFOfitmean, winsLFOfitmean_shm = tide_util.allocarray(
         internalwinspaceshape, rt_outfloattype, shared=usesharedmem
     )
-    winrvalue, winrvalue_shm = tide_util.allocarray(internalwinspaceshape, rt_outfloattype, shared=usesharedmem)
-    winr2value, winr2value_shm = tide_util.allocarray(internalwinspaceshape, rt_outfloattype, shared=usesharedmem)
+    winrvalue, winrvalue_shm = tide_util.allocarray(
+        internalwinspaceshape, rt_outfloattype, shared=usesharedmem
+    )
+    winr2value, winr2value_shm = tide_util.allocarray(
+        internalwinspaceshape, rt_outfloattype, shared=usesharedmem
+    )
     winfitNorm, winfitNorm_shm = tide_util.allocarray(
         internalwinspaceshapederivs, rt_outfloattype, shared=usesharedmem
     )
@@ -629,7 +751,9 @@ def delayvar(args):
     winmovingsignal, winmovingsignal_shm = tide_util.allocarray(
         internalwinfmrishape, rt_outfloattype, shared=usesharedmem
     )
-    winlagtc, winlagtc_shm = tide_util.allocarray(internalwinfmrishape, rt_floattype, shared=usesharedmem)
+    winlagtc, winlagtc_shm = tide_util.allocarray(
+        internalwinfmrishape, rt_floattype, shared=usesharedmem
+    )
     winfiltereddata, winfiltereddata_shm = tide_util.allocarray(
         internalwinfmrishape, rt_outfloattype, shared=usesharedmem
     )
@@ -1112,9 +1236,38 @@ def delayvar(args):
     Path(f"{outputname}_DELAYVARDONE.txt").touch()
 
 
-def process_args(inputargs=None):
+def process_args(inputargs: Optional[Any] = None) -> None:
     """
     Compile arguments for delayvar workflow.
+
+    This function processes input arguments for the delayvar workflow by parsing
+    command line arguments or provided input arguments using a predefined parser.
+
+    Parameters
+    ----------
+    inputargs : Any, optional
+        Input arguments to be processed. Can be None (default) to use command line
+        arguments, or a list of arguments to parse. Default is None.
+
+    Returns
+    -------
+    dict
+        Parsed arguments as a dictionary. The exact structure depends on the
+        argument parser (_get_parser) used internally.
+
+    Notes
+    -----
+    This function internally calls `pf.setargs` with the `_get_parser` function
+    and the provided input arguments. The returned arguments are typically used
+    to configure the delayvar workflow parameters.
+
+    Examples
+    --------
+    >>> # Using default command line arguments
+    >>> args = process_args()
+
+    >>> # Using custom arguments
+    >>> args = process_args(['--input', 'data.txt', '--output', 'result.txt'])
     """
     args, argstowrite = pf.setargs(_get_parser, inputargs=inputargs)
     return args

rapidtide/workflows/diffrois.py

@@ -18,18 +18,46 @@
 #
 import argparse
 import copy
+from argparse import Namespace
+from typing import Any, Callable, Dict, List, Optional, Tuple, Union
 
 import nibabel as nib
 import numpy as np
 import pandas as pd
+from numpy.typing import NDArray
 
 import rapidtide.io as tide_io
 import rapidtide.workflows.parser_funcs as pf
 
 
-def _get_parser():
+def _get_parser() -> Any:
     """
-    Argument parser for diffrois
+    Argument parser for diffrois.
+
+    This function creates and configures an argument parser for the diffrois command-line tool.
+    It defines required and optional arguments needed to process ROI (Region of Interest) data
+    from a CSV file and generate difference matrices.
+
+    Returns
+    -------
+    argparse.ArgumentParser
+        Configured argument parser object with defined arguments for diffrois.
+
+    Notes
+    -----
+    The parser is configured with:
+    - A required datafile argument (CSV input)
+    - A required outputroot argument (root name for output files)
+    - Optional keyfile argument to specify region label order
+    - Optional maxlines argument to limit processing to first N lines
+    - Optional debug flag for verbose output
+
+    Examples
+    --------
+    >>> parser = _get_parser()
+    >>> args = parser.parse_args(['data.csv', 'output_root'])
+    >>> print(args.datafile)
+    'data.csv'
     """
     parser = argparse.ArgumentParser(
         prog="diffrois",
@@ -77,7 +105,57 @@ def _get_parser():
     return parser
 
 
-def diffrois(args):
+def diffrois(args: Any) -> None:
+    """
+    Compute pairwise differences between regions in a CSV file and save results as NIfTI images.
+
+    This function reads region data from a CSV file, computes pairwise differences between
+    regions, and saves the results as NIfTI images. It also computes mean and standard
+    deviation maps of the differences and saves those as well. The function supports
+    optional masking of invalid (NaN) values and can limit the number of input lines
+    processed.
+
+    Parameters
+    ----------
+    args : argparse.Namespace
+        An object containing the following attributes:
+        - datafile : str
+            Path to the input CSV file containing region data.
+        - keyfile : str, optional
+            Path to a file listing column keys in the CSV to use for processing.
+        - outputroot : str
+            Root name for output NIfTI files.
+        - maxlines : int, optional
+            Maximum number of lines to process from the input CSV.
+        - debug : bool
+            If True, print debug information during execution.
+
+    Returns
+    -------
+    None
+        This function does not return any value but saves multiple NIfTI files to disk.
+
+    Notes
+    -----
+    The function saves the following NIfTI files:
+    - `{outputroot}_diffs.nii.gz`: Pairwise differences between regions.
+    - `{outputroot}_mask.nii.gz`: Binary mask indicating valid (non-NaN) values.
+    - `{outputroot}_meandiffs.nii.gz`: Mean of differences for each region pair.
+    - `{outputroot}_stddiffs.nii.gz`: Standard deviation of differences for each region pair.
+    - `{outputroot}_demeaneddiffs.nii.gz`: Demeaned differences (difference minus mean).
+
+    Examples
+    --------
+    >>> import argparse
+    >>> args = argparse.Namespace(
+    ...     datafile='data.csv',
+    ...     keyfile='keys.txt',
+    ...     outputroot='output',
+    ...     maxlines=100,
+    ...     debug=False
+    ... )
+    >>> diffrois(args)
+    """
     df = pd.read_csv(args.datafile)
 
     theregions = np.array(df.columns[1:].values)