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

rapidtide/workflows/retroregress.py

@@ -23,9 +23,12 @@ import os
 import platform
 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
 
 import rapidtide.filter as tide_filt
 import rapidtide.io as tide_io
@@ -63,9 +66,30 @@ DEFAULT_REFINEDELAYNUMPOINTS = 501
 DEFAULT_DELAYOFFSETSPATIALFILT = -1
 
 
-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 the `glmfilt` command-line tool, which performs sLFO (spatially localized
+    filter) filtering using maps generated from a previous rapidtide analysis.
+
+    Returns
+    -------
+    argparse.ArgumentParser
+        Configured argument parser for the glmfilt command-line interface.
+
+    Notes
+    -----
+    The parser includes both standard and experimental options. Experimental options
+    are not fully tested and may not work as expected.
+
+    Examples
+    --------
+    >>> parser = _get_parser()
+    >>> args = parser.parse_args(['fmri.nii', 'dataset_root'])
+    >>> print(args.fmrifile)
+    'fmri.nii'
     """
     parser = argparse.ArgumentParser(
         prog="retroregress",
@@ -232,7 +256,90 @@ def _get_parser():
     return parser
 
 
-def retroregress(args):
+def retroregress(args: Any) -> None:
+    """
+    Perform retrospective regression analysis on fMRI data to filter out slow
+    physiological noise (sLFO).
+
+    This function applies a retrospective regression approach to remove slow
+    physiological noise from fMRI data. It uses a delayed sLFO regressor to
+    model and remove the noise, optionally refining the delay using temporal
+    derivatives of the regressor.
+
+    Parameters
+    ----------
+    args : argparse.Namespace
+        Command-line arguments parsed by argparse. Expected attributes include:
+        - data_root : str
+            Root path for input data files
+        - output_prefix : str
+            Prefix for output files
+        - filter_type : str
+            Type of filtering to apply (e.g., 'bandpass')
+        - filter_low : float
+            Low cutoff frequency for filtering
+        - filter_high : float
+            High cutoff frequency for filtering
+        - regress_derivs : int
+            Number of temporal derivatives to include in the regressor
+        - refinedelay : bool
+            Whether to refine the delay using temporal derivatives
+        - refinecorr : bool
+            Whether to compute correlation refinement
+        - savemovingsignal : bool
+            Whether to save the filtered signal
+        - savenormalsLFOfiltfiles : bool
+            Whether to save standard output files
+        - saveminimumsLFOfiltfiles : bool
+            Whether to save minimum output files
+        - saveallsLFOfiltfiles : bool
+            Whether to save all output files
+        - makepseudofile : bool
+            Whether to create a pseudo-file
+        - nprocs : int
+            Number of processes to use
+        - debug : bool
+            Enable debug mode
+        - focaldebug : bool
+            Enable focal debug mode
+
+    Returns
+    -------
+    None
+        This function does not return a value but writes output files to disk.
+
+    Notes
+    -----
+    The function performs the following steps:
+    1. Reads input data files including mean image, correlation mask, and processed mask
+    2. Applies temporal filtering to the input data
+    3. Performs GLM regression using delayed sLFO regressors
+    4. Refines delay if requested using temporal derivatives
+    5. Saves output files including filtered data, regressors, and timing information
+
+    Examples
+    --------
+    >>> import argparse
+    >>> args = argparse.Namespace(
+    ...     data_root='path/to/data',
+    ...     output_prefix='output',
+    ...     filter_type='bandpass',
+    ...     filter_low=0.01,
+    ...     filter_high=0.1,
+    ...     regress_derivs=2,
+    ...     refinedelay=True,
+    ...     refinecorr=False,
+    ...     savemovingsignal=True,
+    ...     savenormalsLFOfiltfiles=True,
+    ...     saveminimumsLFOfiltfiles=True,
+    ...     saveallsLFOfiltfiles=False,
+    ...     makepseudofile=False,
+    ...     nprocs=4,
+    ...     debug=False,
+    ...     focaldebug=False
+    ... )
+    >>> retroregress(args)
+    """
     # get the pid of the parent process
     args.pid = os.getpid()
 
@@ -253,7 +360,7 @@ def retroregress(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")
@@ -307,7 +414,7 @@ def retroregress(args):
     # save the raw and formatted command lines
     argstowrite = sys.argv
     thecommandline = " ".join(sys.argv[1:])
-    tide_io.writevec([thecommandline], f"{outputname}_retrocommandline.txt")
+    tide_io.writevec(np.asarray([thecommandline]), f"{outputname}_retrocommandline.txt")
     formattedcommandline = []
     for thetoken in argstowrite[0:3]:
         formattedcommandline.append(thetoken)
@@ -326,7 +433,9 @@ def retroregress(args):
         else:
             suffix = ""
         formattedcommandline[i] = prefix + formattedcommandline[i] + suffix
-    tide_io.writevec(formattedcommandline, f"{outputname}_retroformattedcommandline.txt")
+    tide_io.writevec(
+        np.asarray(formattedcommandline), f"{outputname}_retroformattedcommandline.txt"
+    )
 
     if args.nprocs < 1:
         args.nprocs = tide_multiproc.maxcpus()
@@ -362,19 +471,15 @@ def retroregress(args):
         sys.exit()
 
     if therunoptions["internalprecision"] == "double":
-        rt_floattype = "float64"
-        rt_floatset = np.float64
+        rt_floattype = np.float64
     else:
-        rt_floattype = "float32"
-        rt_floatset = np.float32
+        rt_floattype = np.float32
 
     # set the output precision
     if therunoptions["outputprecision"] == "double":
-        rt_outfloattype = "float64"
-        rt_outfloatset = np.float64
+        rt_outfloattype = np.float64
     else:
-        rt_outfloattype = "float32"
-        rt_outfloatset = np.float32
+        rt_outfloattype = np.float32
     therunoptions["saveminimumsLFOfiltfiles"] = args.saveminimumsLFOfiltfiles
 
     # read the fmri input files
@@ -519,16 +624,24 @@ def retroregress(args):
     sLFOfitmean, sLFOfitmean_shm = tide_util.allocarray(
         internalvalidspaceshape, rt_outfloattype, shared=usesharedmem
     )
-    rvalue, rvalue_shm = tide_util.allocarray(internalvalidspaceshape, rt_outfloattype, shared=usesharedmem)
-    r2value, r2value_shm = tide_util.allocarray(internalvalidspaceshape, rt_outfloattype, shared=usesharedmem)
-    fitNorm, fitNorm_shm = tide_util.allocarray(internalvalidspaceshapederivs, rt_outfloattype, shared=usesharedmem)
+    rvalue, rvalue_shm = tide_util.allocarray(
+        internalvalidspaceshape, rt_outfloattype, shared=usesharedmem
+    )
+    r2value, r2value_shm = tide_util.allocarray(
+        internalvalidspaceshape, rt_outfloattype, shared=usesharedmem
+    )
+    fitNorm, fitNorm_shm = tide_util.allocarray(
+        internalvalidspaceshapederivs, rt_outfloattype, shared=usesharedmem
+    )
     fitcoeff, fitcoeff_shm = tide_util.allocarray(
         internalvalidspaceshapederivs, rt_outfloattype, shared=usesharedmem
     )
     movingsignal, movingsignal_shm = tide_util.allocarray(
         internalvalidfmrishape, rt_outfloattype, shared=usesharedmem
     )
-    lagtc, lagtc_shm = tide_util.allocarray(internalvalidfmrishape, rt_floattype, shared=usesharedmem)
+    lagtc, lagtc_shm = tide_util.allocarray(
+        internalvalidfmrishape, rt_floattype, shared=usesharedmem
+    )
     filtereddata, filtereddata_shm = tide_util.allocarray(
         internalvalidfmrishape, rt_outfloattype, shared=usesharedmem
     )
@@ -658,7 +771,6 @@ def retroregress(args):
                 maxdelay=args.maxdelay,
                 numpoints=args.numpoints,
                 histlen=therunoptions["histlen"],
-                rt_floatset=rt_floatset,
                 rt_floattype=rt_floattype,
                 debug=args.debug,
             )
@@ -731,6 +843,12 @@ def retroregress(args):
         varchange = initialvariance * 0.0
         varchange[divlocs] = 100.0 * (finalvariance[divlocs] / initialvariance[divlocs] - 1.0)
 
+        # calculate the voxelwise mean of the filtered data
+        lfofilteredmeanvalue = np.mean(
+            filtereddata,
+            axis=1,
+        )
+
         # save regional timecourses if masks are defined
         # read in the anatomic masks
         anatomiclist = [
@@ -889,6 +1007,13 @@ def retroregress(args):
                     "Change in inband variance after filtering, in percent",
                 ),
                 # (
+                #    lfofilteredmeanvalue,
+                #    "lfofilterMean",
+                #    "map",
+                #    None,
+                #    "Voxelwise mean of the sLFO filtered data",
+                # )
+                # (
                 #   initialrawvariance,
                 #    "lfofilterTotalVarianceBefore",
                 #    "map",
@@ -930,13 +1055,10 @@ def retroregress(args):
                 (initialvariance, "lfofilterInbandVarianceBefore", "map", None),
                 (finalvariance, "lfofilterInbandVarianceAfter", "map", None),
                 (varchange, "CVRVariance", "map", None),
+                (rvalue, "CVRR", "map", None),
+                (r2value, "CVRR2", "map", None),
+                (fitcoeff[:, 0], "CVR", "map", "percent"),
             ]
-            if args.savenormalsLFOfiltfiles:
-                maplist += [
-                    (rvalue, "CVRR", "map", None),
-                    (r2value, "CVRR2", "map", None),
-                    (fitcoeff, "CVR", "map", "percent"),
-                ]
         bidsdict = bidsbasedict.copy()
 
         if args.debug or args.focaldebug:
@@ -1343,9 +1465,37 @@ def retroregress(args):
     Path(f"{outputname}_RETRODONE.txt").touch()
 
 
-def process_args(inputargs=None):
+def process_args(inputargs: Optional[Any] = None) -> None:
     """
     Compile arguments for retroregress workflow.
+
+    This function processes input arguments for the retroregress 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), a list of strings,
+        or other argument formats supported by the underlying parser. Default is None.
+
+    Returns
+    -------
+    argparse.Namespace
+        Parsed arguments namespace containing all processed arguments for the workflow.
+
+    Notes
+    -----
+    The function relies on `pf.setargs` and `_get_parser` which should be defined
+    in the module's scope. The returned arguments can be used directly in the
+    retroregress workflow pipeline.
+
+    Examples
+    --------
+    >>> # Using default arguments
+    >>> args = process_args()
+
+    >>> # Using custom input arguments
+    >>> args = process_args(['--input', 'data.csv', '--output', 'results.txt'])
     """
     args, argstowrite = pf.setargs(_get_parser, inputargs=inputargs)
     return args

rapidtide/workflows/roisummarize.py

@@ -18,17 +18,42 @@
 #
 import argparse
 import sys
+from typing import Any, Callable, Dict, List, Optional, Tuple, Union
 
 import numpy as np
+from numpy.typing import NDArray
 
 import rapidtide.io as tide_io
 import rapidtide.miscmath as tide_math
 import rapidtide.workflows.parser_funcs as pf
 
 
-def _get_parser():
+def _get_parser() -> Any:
     """
-    Argument parser for roisummarize
+    Argument parser for roisummarize.
+
+    This function constructs and returns an `argparse.ArgumentParser` object configured
+    for parsing command-line arguments used by the `roisummarize` tool. It defines
+    required inputs, optional arguments for sampling frequency, filtering, normalization,
+    and debugging options.
+
+    Returns
+    -------
+    argparse.ArgumentParser
+        Configured argument parser for the roisummarize tool.
+
+    Notes
+    -----
+    The parser supports two mutually exclusive ways to specify sampling frequency:
+    either via `--samplerate` or `--sampletstep`. These are equivalent and both
+    set the same internal `samplerate` parameter.
+
+    Examples
+    --------
+    >>> parser = _get_parser()
+    >>> args = parser.parse_args(['--inputfilename', 'input.txt',
+    ...                           '--templatefile', 'template.nii',
+    ...                           '--outputfile', 'output.txt'])
     """
     parser = argparse.ArgumentParser(
         prog="filttc",
@@ -101,7 +126,50 @@ def _get_parser():
     return parser
 
 
-def summarize4Dbylabel(inputvoxels, templatevoxels, normmethod="z", debug=False):
+def summarize4Dbylabel(
+    inputvoxels: NDArray, templatevoxels: NDArray, normmethod: str = "z", debug: bool = False
+) -> NDArray:
+    """
+    Summarize 4D voxel data by region labels from a template.
+
+    This function extracts time series data for each region defined in a template
+    and computes normalized mean time courses for each region across time points.
+
+    Parameters
+    ----------
+    inputvoxels : NDArray
+        4D array containing voxel data with shape (n_voxels, n_timepoints, n_other_dims)
+    templatevoxels : NDArray
+        3D array containing region labels with shape (n_voxels, 1, 1)
+    normmethod : str, optional
+        Normalization method to apply to time courses, default is "z"
+        Supported methods depend on tide_math.normalize function
+    debug : bool, optional
+        If True, print debugging information including voxel counts and shapes,
+        default is False
+
+    Returns
+    -------
+    timecourses : NDArray
+        2D array of shape (n_regions, n_timepoints) containing normalized mean
+        time courses for each region
+
+    Notes
+    -----
+    - Regions are assumed to be labeled starting from 1
+    - Zero-valued voxels in template are ignored
+    - NaN values are converted to zeros before computing means
+    - The function uses tide_math.normalize for normalization
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> input_data = np.random.rand(100, 50, 1)
+    >>> template = np.random.randint(1, 4, (100, 1, 1))
+    >>> result = summarize4Dbylabel(input_data, template, normmethod="z")
+    >>> print(result.shape)
+    (3, 50)
+    """
     numregions = np.max(templatevoxels)
     numtimepoints = inputvoxels.shape[1]
     timecourses = np.zeros((numregions, numtimepoints), dtype="float")
@@ -118,7 +186,51 @@ def summarize4Dbylabel(inputvoxels, templatevoxels, normmethod="z", debug=False)
     return timecourses
 
 
-def summarize3Dbylabel(inputvoxels, templatevoxels, debug=False):
+def summarize3Dbylabel(
+    inputvoxels: NDArray, templatevoxels: NDArray, debug: bool = False
+) -> Tuple[NDArray, list]:
+    """
+    Summarize 3D voxel data by label using mean, standard deviation, and median statistics.
+
+    This function processes 3D voxel data by grouping voxels according to labels in a template
+    and computes summary statistics for each labeled region. The input voxels are replaced
+    with the mean value of each region, and statistics are returned for further analysis.
+
+    Parameters
+    ----------
+    inputvoxels : NDArray
+        3D array containing the voxel values to be summarized
+    templatevoxels : NDArray
+        3D array containing integer labels defining regions of interest
+    debug : bool, optional
+        Flag to enable debug output (default is False)
+
+    Returns
+    -------
+    tuple
+        A tuple containing:
+        - outputvoxels : NDArray
+          3D array with each labeled region replaced by its mean value
+        - regionstats : list
+          List of lists containing [mean, std, median] statistics for each region
+
+    Notes
+    -----
+    - Regions are labeled starting from 1 to max(templatevoxels)
+    - NaN values are converted to 0 during statistics calculation
+    - The function modifies the input arrays in-place during processing
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> input_data = np.random.rand(10, 10, 10)
+    >>> template = np.zeros((10, 10, 10), dtype=int)
+    >>> template[2:5, 2:5, 2:5] = 1
+    >>> template[6:8, 6:8, 6:8] = 2
+    >>> result, stats = summarize3Dbylabel(input_data, template)
+    >>> print(f"Region 1 mean: {stats[0][0]:.3f}")
+    >>> print(f"Region 2 mean: {stats[1][0]:.3f}")
+    """
     numregions = np.max(templatevoxels)
     outputvoxels = 0.0 * inputvoxels
     regionstats = []
@@ -132,7 +244,64 @@ def summarize3Dbylabel(inputvoxels, templatevoxels, debug=False):
     return outputvoxels, regionstats
 
 
-def roisummarize(args):
+def roisummarize(args: Any) -> None:
+    """
+    Summarize fMRI data by regions of interest (ROIs) using a template image.
+
+    This function reads input fMRI and template NIfTI files, checks spatial
+    compatibility, and computes either 3D or 4D summaries depending on the
+    number of timepoints in the input data. For 4D data, it applies a filter
+    and summarizes timecourses by ROI. For 3D data, it computes mean values and
+    region statistics.
+
+    Parameters
+    ----------
+    args : Any
+        Command-line arguments parsed by `_get_parser()`. Expected attributes include:
+        - `inputfilename` : str
+            Path to the input fMRI NIfTI file.
+        - `templatefile` : str
+            Path to the template NIfTI file defining ROIs.
+        - `samplerate` : str or float
+            Sampling rate for filtering. If "auto", defaults to 1.0.
+        - `numskip` : int
+            Number of initial timepoints to skip when summarizing 4D data.
+        - `normmethod` : str
+            Normalization method for 4D summarization.
+        - `debug` : bool
+            Enable debug mode for additional output.
+        - `outputfile` : str
+            Base name for output files.
+
+    Returns
+    -------
+    None
+        The function writes output files to disk:
+        - `<outputfile>_timecourses`: Timecourses for each ROI (4D case).
+        - `<outputfile>_meanvals`: Mean values per ROI (3D case).
+        - `<outputfile>_regionstats.txt`: Statistics for each ROI (3D case).
+
+    Notes
+    -----
+    - The function assumes that the template file defines ROIs with integer labels.
+    - For 4D data, the input is filtered using `pf.postprocessfilteropts`.
+    - If the spatial dimensions of the input and template files do not match,
+      the function exits with an error message.
+
+    Examples
+    --------
+    >>> import argparse
+    >>> args = argparse.Namespace(
+    ...     inputfilename='fmri.nii',
+    ...     templatefile='roi_template.nii',
+    ...     samplerate='auto',
+    ...     numskip=5,
+    ...     normmethod='zscore',
+    ...     debug=False,
+    ...     outputfile='output'
+    ... )
+    >>> roisummarize(args)
+    """
     # grab the command line arguments then pass them off.
     try:
         args = _get_parser().parse_args()

rapidtide/workflows/runqualitycheck.py

@@ -17,14 +17,41 @@
 #
 #
 import argparse
+from argparse import Namespace
+from typing import Any, Callable, Dict, List, Optional, Tuple, Union
 
 import rapidtide.io as tide_io
 import rapidtide.qualitycheck as tide_quality
 
 
-def _get_parser():
+def _get_parser() -> Any:
     """
-    Argument parser for runqualitycheck
+    Argument parser for runqualitycheck.
+
+    This function creates and configures an argument parser for the runqualitycheck
+    command-line tool. The parser handles both required and optional arguments needed
+    to perform quality checks on rapidtide datasets.
+
+    Returns
+    -------
+    argparse.ArgumentParser
+        Configured argument parser object with all required and optional arguments
+        for the runqualitycheck tool.
+
+    Notes
+    -----
+    The argument parser is configured with:
+    - Required input file root name
+    - Optional gray matter mask specification
+    - Optional white matter mask specification
+    - Debug flag for additional output
+
+    Examples
+    --------
+    >>> parser = _get_parser()
+    >>> args = parser.parse_args(['dataset_root'])
+    >>> print(args.inputfileroot)
+    'dataset_root'
     """
     parser = argparse.ArgumentParser(
         prog="runqualitycheck",
@@ -66,7 +93,48 @@ def _get_parser():
     return parser
 
 
-def runqualitycheck(args):
+def runqualitycheck(args: Any) -> None:
+    """
+    Run quality check on input data and write results to JSON file.
+
+    This function performs a quality check on the input data using the tide_quality
+    module and writes the results to a JSON file with a standardized naming convention.
+
+    Parameters
+    ----------
+    args : Any
+        An object containing input arguments with the following attributes:
+        - inputfileroot : str
+            Root name of the input file(s)
+        - graymaskspec : str, optional
+            Specification for gray matter masking
+        - whitemaskspec : str, optional
+            Specification for white matter masking
+        - debug : bool, optional
+            Flag to enable debug mode
+
+    Returns
+    -------
+    None
+        This function does not return any value but writes results to a JSON file.
+
+    Notes
+    -----
+    The output JSON file will be named as '{inputfileroot}_desc-qualitymetrics_info.json'
+    where inputfileroot is the root name provided in the args object.
+
+    Examples
+    --------
+    >>> class Args:
+    ...     def __init__(self):
+    ...         self.inputfileroot = "sub-01_task-rest"
+    ...         self.graymaskspec = "gray_mask.nii.gz"
+    ...         self.whitemaskspec = "white_mask.nii.gz"
+    ...         self.debug = False
+    ...
+    >>> args = Args()
+    >>> runqualitycheck(args)
+    """
     resultsdict = tide_quality.qualitycheck(
         args.inputfileroot,
         graymaskspec=args.graymaskspec,