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

rapidtide/workflows/rapidtide_parser.py

@@ -21,9 +21,11 @@ import logging
 import os
 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
 
 import rapidtide.io as tide_io
 import rapidtide.util as tide_util
@@ -108,10 +110,37 @@ DEFAULT_DELAYOFFSETSPATIALFILT = -1
 DEFAULT_PATCHMINSIZE = 10
 DEFAULT_PATCHFWHM = 5
 
+DEFAULT_PREWHITEN_LAGS = -1
 
-def _get_parser():
+
+def _get_parser() -> Any:
     """
-    Argument parser for rapidtide
+    Set up the argument parser for rapidtide command-line interface.
+
+    This function configures all available command-line arguments for the rapidtide
+    tool, organizing them into logical groups for easy reference and use.
+
+    Returns
+    -------
+    argparse.ArgumentParser
+        Configured argument parser with all rapidtide options added
+
+    Notes
+    -----
+    The parser includes several groups of options:
+    - Input/Output options
+    - Processing options
+    - Performance options
+    - Miscellaneous options
+    - Experimental options (not fully tested)
+    - Deprecated options (will be removed in future versions)
+    - Debugging options (for development and troubleshooting)
+
+    Examples
+    --------
+    >>> parser = setup_parser()
+    >>> args = parser.parse_args()
+    >>> print(args.version)
     """
     parser = argparse.ArgumentParser(
         prog="rapidtide",
@@ -1445,7 +1474,7 @@ def _get_parser():
     experimental = parser.add_argument_group(
         "Experimental options (not fully tested, or not tested at all, may not work).  Beware!"
     )
-    output.add_argument(
+    experimental.add_argument(
         "--riptidestep",  # was -h
         dest="riptidestep",
         action="store",
@@ -1572,6 +1601,24 @@ def _get_parser():
         help=("Perform patch shift correction."),
         default=False,
     )
+    experimental.add_argument(
+        "--prewhitenregressor",
+        dest="prewhitenregressor",
+        action="store_true",
+        help=("Prewhiten probe regressor prior to calculating correlations."),
+        default=False,
+    )
+    experimental.add_argument(
+        "--prewhitenlags",
+        dest="prewhitenlags",
+        action="store",
+        type=lambda x: pf.is_int(parser, x, minval=0),
+        metavar="LAGS",
+        help=(
+            f"Set number of TRs to use in prewhitening.  Set to -1 to calculate automatically. Default is {DEFAULT_PREWHITEN_LAGS}."
+        ),
+        default=DEFAULT_PREWHITEN_LAGS,
+    )
 
     # Deprecated options
     deprecated = parser.add_argument_group(
@@ -1731,9 +1778,51 @@ def _get_parser():
     return parser
 
 
-def process_args(inputargs=None):
+def process_args(inputargs: Optional[Any] = None) -> Tuple[Any, object]:
     """
     Compile arguments for rapidtide workflow.
+
+    This function processes command-line arguments and sets up the configuration
+    for the rapidtide workflow. It handles argument parsing, logging setup,
+    command-line saving, and various parameter defaults and overrides based on
+    analysis modes and macros.
+
+    Parameters
+    ----------
+    inputargs : optional
+        Input arguments to be processed. If None, arguments are parsed from
+        sys.argv. Default is None.
+
+    Returns
+    -------
+    tuple
+        A tuple containing:
+        - args : dict
+            Dictionary of processed arguments.
+        - theprefilter : object
+            Preprocessing filter object.
+
+    Notes
+    -----
+    The function performs the following key operations:
+    1. Parses command-line arguments using `_get_parser`
+    2. Sets up logging based on debug flag
+    3. Saves raw and formatted command lines to files
+    4. Applies default values and overrides for various parameters
+    5. Handles analysis modes (delaymapping, denoising, cvrmap, etc.)
+    6. Processes macros (venousrefine, nirs)
+    7. Configures output options based on `outputlevel`
+    8. Sets up pass options and dispersion calculation parameters
+    9. Handles mask specifications and file processing
+    10. Initializes filter options
+
+    Examples
+    --------
+    >>> args, prefilter = process_args()
+    >>> print(args['passes'])
+    1
+    >>> print(args['outputlevel'])
+    'normal'
     """
     inargs, argstowrite = pf.setargs(_get_parser, inputargs=inputargs)
     args = vars(inargs)
@@ -1747,7 +1836,7 @@ def process_args(inputargs=None):
     # save the raw and formatted command lines
     args["commandlineargs"] = argstowrite[1:]
     thecommandline = " ".join(argstowrite)
-    tide_io.writevec([thecommandline], args["outputname"] + "_commandline.txt")
+    tide_io.writevec(np.array([thecommandline]), args["outputname"] + "_commandline.txt")
     formattedcommandline = []
     for thetoken in argstowrite[0:3]:
         formattedcommandline.append(thetoken)
@@ -1766,7 +1855,9 @@ def process_args(inputargs=None):
         else:
             suffix = ""
         formattedcommandline[i] = prefix + formattedcommandline[i] + suffix
-    tide_io.writevec(formattedcommandline, args["outputname"] + "_formattedcommandline.txt")
+    tide_io.writevec(
+        np.array(formattedcommandline), args["outputname"] + "_formattedcommandline.txt"
+    )
 
     LGR.debug("\nbefore postprocessing:\n{}".format(args))
 
@@ -1847,6 +1938,9 @@ def process_args(inputargs=None):
     args["lagmin"] = args["lag_extrema"][0]
     args["lagmax"] = args["lag_extrema"][1]
 
+    if args["prewhitenlags"] == -1:
+        args["prewhitenlags"] = int(np.max([np.fabs(args["lagmin"]), np.fabs(args["lagmax"])]))
+
     # set startpoint and endpoint
     args["startpoint"], args["endpoint"] = pf.parserange(args["timerange"], descriptor="timerange")
 
@@ -2222,9 +2316,15 @@ def process_args(inputargs=None):
 
     # make the pass options dictionary
     args["passoptions"] = [
-        {"similaritymetric": "riptide",},
-        {"similaritymetric": "correlation", },
-        {"similaritymetric": "correlation", },
+        {
+            "similaritymetric": "riptide",
+        },
+        {
+            "similaritymetric": "correlation",
+        },
+        {
+            "similaritymetric": "correlation",
+        },
     ]
 
     # dispersion calculation

rapidtide/workflows/refineDelayMap.py

@@ -16,46 +16,156 @@
 #   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.refinedelay as tide_refinedelay
 import rapidtide.stats as tide_stats
 
 
 def refineDelay(
-    fmri_data_valid,
-    initial_fmri_x,
-    xdim,
-    ydim,
-    slicethickness,
-    sLFOfiltmask,
-    genlagtc,
-    oversamptr,
-    sLFOfitmean,
-    rvalue,
-    r2value,
-    fitNorm,
-    fitcoeff,
-    lagtc,
-    outputname,
-    validvoxels,
-    nativespaceshape,
-    theinputdata,
-    lagtimes,
-    optiondict,
-    LGR,
-    TimingLGR,
-    outputlevel="normal",
-    gausssigma=-1,
-    patchthresh=3.0,
-    mindelay=-5.0,
-    maxdelay=5.0,
-    numpoints=501,
-    histlen=101,
-    rt_floatset=np.float64,
-    rt_floattype="float64",
-    debug=False,
-):
+    fmri_data_valid: Any,
+    initial_fmri_x: Any,
+    xdim: Any,
+    ydim: Any,
+    slicethickness: Any,
+    sLFOfiltmask: Any,
+    genlagtc: Any,
+    oversamptr: Any,
+    sLFOfitmean: Any,
+    rvalue: Any,
+    r2value: Any,
+    fitNorm: Any,
+    fitcoeff: Any,
+    lagtc: Any,
+    outputname: Any,
+    validvoxels: Any,
+    nativespaceshape: Any,
+    theinputdata: Any,
+    lagtimes: Any,
+    optiondict: Any,
+    LGR: Any,
+    TimingLGR: Any,
+    outputlevel: str = "normal",
+    gausssigma: int = -1,
+    patchthresh: float = 3.0,
+    mindelay: float = -5.0,
+    maxdelay: float = 5.0,
+    numpoints: int = 501,
+    histlen: int = 101,
+    rt_floatset: Any = np.float64,
+    rt_floattype: str = "float64",
+    debug: bool = False,
+) -> None:
+    """
+    Refine delay estimates using regression derivative ratios and histogram-based calibration.
+
+    This function performs calibration of delay estimates by computing regression derivative
+    ratios, filtering them, training a mapping from ratios to delays, and finally calculating
+    delay offsets for each voxel. It also generates a histogram of the computed delay offsets.
+
+    Parameters
+    ----------
+    fmri_data_valid : Any
+        Valid fMRI data used for delay refinement.
+    initial_fmri_x : Any
+        Initial fMRI design matrix.
+    xdim : Any
+        X dimension of the data.
+    ydim : Any
+        Y dimension of the data.
+    slicethickness : Any
+        Thickness of the slices in the data.
+    sLFOfiltmask : Any
+        Mask for filtering based on SLOF (slice timing) effects.
+    genlagtc : Any
+        Generated lag time course.
+    oversamptr : Any
+        Oversampling time resolution.
+    sLFOfitmean : Any
+        Mean SLOF fit values.
+    rvalue : Any
+        R-values from regression.
+    r2value : Any
+        R-squared values from regression.
+    fitNorm : Any
+        Normalized fit coefficients.
+    fitcoeff : Any
+        Fit coefficients.
+    lagtc : Any
+        Lag time course.
+    outputname : Any
+        Base name for output files.
+    validvoxels : Any
+        Indices of valid voxels.
+    nativespaceshape : Any
+        Shape of the native space.
+    theinputdata : Any
+        Input data object.
+    lagtimes : Any
+        Time lags used for analysis.
+    optiondict : Any
+        Dictionary of options for processing.
+    LGR : Any
+        Logger for general messages.
+    TimingLGR : Any
+        Logger for timing-related messages.
+    outputlevel : str, optional
+        Level of output verbosity, default is "normal".
+    gausssigma : int, optional
+        Sigma for Gaussian filtering, default is -1 (no filtering).
+    patchthresh : float, optional
+        Threshold for patch-based filtering, default is 3.0.
+    mindelay : float, optional
+        Minimum delay value, default is -5.0.
+    maxdelay : float, optional
+        Maximum delay value, default is 5.0.
+    numpoints : int, optional
+        Number of points for delay interpolation, default is 501.
+    histlen : int, optional
+        Length of histogram bins, default is 101.
+    rt_floatset : Any, optional
+        Data type for real-time float operations, default is np.float64.
+    rt_floattype : str, optional
+        String representation of float type, default is "float64".
+    debug : bool, optional
+        Enable debug mode, default is False.
+
+    Returns
+    -------
+    tuple
+        A tuple containing:
+        - delayoffset : ndarray
+            Calculated delay offsets for each voxel.
+        - regressderivratios : ndarray
+            Raw regression derivative ratios.
+        - medfiltregressderivratios : ndarray
+            Median-filtered regression derivative ratios.
+        - filteredregressderivratios : ndarray
+            Final filtered regression derivative ratios.
+        - delayoffsetMAD : ndarray
+            Median absolute deviation of delay offsets.
+
+    Notes
+    -----
+    The function uses the `tide_refinedelay` module to perform various steps:
+    1. Computes regression derivative ratios using `getderivratios`.
+    2. Filters these ratios using `filterderivratios`.
+    3. Trains a ratio-to-delay mapping using `trainratiotooffset`.
+    4. Converts ratios to delay offsets using `ratiotodelay`.
+    5. Saves a histogram of delay offsets to disk.
+
+    Examples
+    --------
+    >>> delayoffset, regressderivratios, medfiltregressderivratios, filteredregressderivratios, delayoffsetMAD = refineDelay(
+    ...     fmri_data_valid, initial_fmri_x, xdim, ydim, slicethickness,
+    ...     sLFOfiltmask, genlagtc, oversamptr, sLFOfitmean, rvalue, r2value,
+    ...     fitNorm, fitcoeff, lagtc, outputname, validvoxels, nativespaceshape,
+    ...     theinputdata, lagtimes, optiondict, LGR, TimingLGR
+    ... )
+    """
     # do the calibration
     TimingLGR.info("Refinement calibration start")
     regressderivratios, regressrvalues = tide_refinedelay.getderivratios(