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

rapidtide/workflows/regressfrommaps.py

@@ -17,7 +17,10 @@
 #
 #
 
+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.linfitfiltpass as tide_linfitfiltpass
@@ -25,37 +28,158 @@ import rapidtide.makelaggedtcs as tide_makelagged
 
 
 def regressfrommaps(
-    fmri_data_valid,
-    validvoxels,
-    initial_fmri_x,
-    lagtimes,
-    fitmask,
-    genlagtc,
-    mode,
-    outputname,
-    oversamptr,
-    sLFOfitmean,
-    rvalue,
-    r2value,
-    fitNorm,
-    fitcoeff,
-    movingsignal,
-    lagtc,
-    filtereddata,
-    LGR,
-    TimingLGR,
-    regressfiltthreshval,
-    saveminimumsLFOfiltfiles,
-    nprocs_makelaggedtcs=1,
-    nprocs_regressionfilt=1,
-    regressderivs=0,
-    chunksize=50000,
-    showprogressbar=True,
-    alwaysmultiproc=False,
-    saveEVsandquit=False,
-    coefficientsonly=False,
-    debug=False,
-):
+    fmri_data_valid: Any,
+    validvoxels: Any,
+    initial_fmri_x: Any,
+    lagtimes: Any,
+    fitmask: Any,
+    genlagtc: Any,
+    mode: Any,
+    outputname: Any,
+    oversamptr: Any,
+    sLFOfitmean: Any,
+    rvalue: Any,
+    r2value: Any,
+    fitNorm: Any,
+    fitcoeff: Any,
+    movingsignal: Any,
+    lagtc: Any,
+    filtereddata: Any,
+    LGR: Any,
+    TimingLGR: Any,
+    regressfiltthreshval: Any,
+    saveminimumsLFOfiltfiles: Any,
+    nprocs_makelaggedtcs: int = 1,
+    nprocs_regressionfilt: int = 1,
+    regressderivs: int = 0,
+    chunksize: int = 50000,
+    showprogressbar: bool = True,
+    alwaysmultiproc: bool = False,
+    saveEVsandquit: bool = False,
+    coefficientsonly: bool = False,
+    timemask: Optional[NDArray] = None,
+    debug: bool = False,
+) -> None:
+    """
+    Perform regression analysis on fMRI data using lagged timecourses.
+
+    This function generates voxel-specific regressors from lagged timecourses,
+    applies filtering, and performs regression to estimate model coefficients.
+    It supports various modes including cross-validation regression (cvrmap),
+    and can optionally save intermediate results or quit early.
+
+    Parameters
+    ----------
+    fmri_data_valid : array-like
+        Valid fMRI data to be processed.
+    validvoxels : array-like
+        Indices or mask of valid voxels.
+    initial_fmri_x : array-like
+        Initial fMRI timecourse (e.g., stimulus timing).
+    lagtimes : array-like
+        Time lags to be used for generating lagged regressors.
+    fitmask : array-like
+        Mask for selecting voxels to fit.
+    genlagtc : object
+        Generator for lagged timecourses.
+    mode : str
+        Processing mode (e.g., 'cvrmap').
+    outputname : str
+        Base name for output files.
+    oversamptr : float
+        Oversampling rate for timecourse generation.
+    sLFOfitmean : array-like
+        Mean of sLFO fit values.
+    rvalue : array-like
+        R-values from regression.
+    r2value : array-like
+        R-squared values from regression.
+    fitNorm : array-like
+        Normalization values for fit.
+    fitcoeff : array-like
+        Coefficients from the fit.
+    movingsignal : array-like
+        Moving signal components.
+    lagtc : array-like
+        Lagged timecourses.
+    filtereddata : array-like
+        Filtered fMRI data.
+    LGR : object, optional
+        Logger for general logging.
+    TimingLGR : object, optional
+        Logger for timing information.
+    regressfiltthreshval : float
+        Threshold for regression filtering.
+    saveminimumsLFOfiltfiles : bool
+        Whether to save noise removed timeseries.
+    nprocs_makelaggedtcs : int, optional
+        Number of processes for making lagged timecourses (default is 1).
+    nprocs_regressionfilt : int, optional
+        Number of processes for regression filtering (default is 1).
+    regressderivs : int, optional
+        Order of derivatives to include in regressors (default is 0).
+    chunksize : int, optional
+        Size of chunks for processing (default is 50000).
+    showprogressbar : bool, optional
+        Whether to show progress bar (default is True).
+    alwaysmultiproc : bool, optional
+        Force multiprocessing even for small tasks (default is False).
+    saveEVsandquit : bool, optional
+        Save EVs and quit early (default is False).
+    coefficientsonly : bool, optional
+        Return only coefficients (default is False).
+    timemask : NDArray, optional
+       Mask of timepoints to include in regression filtering.
+    debug : bool, optional
+        Enable debug output (default is False).
+
+    Returns
+    -------
+    tuple
+        If `saveEVsandquit` is True, returns (0, regressorset, evset).
+        Otherwise, returns (voxelsprocessed_regressionfilt, regressorset, evset).
+
+    Notes
+    -----
+    - The function modifies `fitcoeff` in-place when `mode == "cvrmap"` by multiplying by 100.
+    - The function uses multiprocessing if `alwaysmultiproc` is True or if `nprocs > 1`.
+    - Filtering is performed using `tide_linfitfiltpass.linfitfiltpass`.
+
+    Examples
+    --------
+    >>> regressfrommaps(
+    ...     fmri_data_valid=data,
+    ...     validvoxels=voxels,
+    ...     initial_fmri_x=stimulus,
+    ...     lagtimes=lags,
+    ...     fitmask=mask,
+    ...     genlagtc=gen,
+    ...     mode="cvrmap",
+    ...     outputname="output",
+    ...     oversamptr=2.0,
+    ...     sLFOfitmean=mean,
+    ...     rvalue=r_vals,
+    ...     r2value=r2_vals,
+    ...     fitNorm=norm,
+    ...     fitcoeff=coeffs,
+    ...     movingsignal=moving,
+    ...     lagtc=lagged_tc,
+    ...     filtereddata=filtered,
+    ...     LGR=logger,
+    ...     TimingLGR=timing_logger,
+    ...     regressfiltthreshval=0.5,
+    ...     saveminimumsLFOfiltfiles=True,
+    ...     nprocs_makelaggedtcs=4,
+    ...     nprocs_regressionfilt=2,
+    ...     regressderivs=2,
+    ...     chunksize=10000,
+    ...     showprogressbar=True,
+    ...     alwaysmultiproc=False,
+    ...     saveEVsandquit=False,
+    ...     coefficientsonly=False,
+    ...     debug=False,
+    ... )
+    """
     if debug:
         print("regressfrommaps: Starting")
         print(f"\t{nprocs_makelaggedtcs=}")
@@ -68,8 +192,7 @@ def regressfrommaps(
         print(f"\t{outputname=}")
         print(f"\t{oversamptr=}")
         print(f"\t{regressfiltthreshval=}")
-    rt_floatset = np.float64
-    rt_floattype = "float64"
+    rt_floattype = np.float64
     numvalidspatiallocs = np.shape(validvoxels)[0]
 
     # generate the voxel specific regressors
@@ -89,10 +212,12 @@ def regressfrommaps(
         alwaysmultiproc=alwaysmultiproc,
         showprogressbar=showprogressbar,
         chunksize=chunksize,
-        rt_floatset=rt_floatset,
         rt_floattype=rt_floattype,
         debug=debug,
     )
+    if timemask is not None:
+        lagtc = lagtc * timemask[None, :]
+
     if debug:
         print(f"\t{lagtimes.shape=}")
         threshmask = np.where(fitmask > 0, 1, 0)
@@ -113,7 +238,7 @@ def regressfrommaps(
         if debug:
             print(f"adding derivatives up to order {regressderivs} prior to regression")
         regressorset = tide_linfitfiltpass.makevoxelspecificderivs(lagtc, regressderivs)
-        baseev = rt_floatset(genlagtc.yfromx(initial_fmri_x))
+        baseev = (genlagtc.yfromx(initial_fmri_x)).astype(rt_floattype)
         evset = tide_linfitfiltpass.makevoxelspecificderivs(
             baseev.reshape((1, -1)), regressderivs
         ).reshape((-1, 2))
@@ -121,7 +246,7 @@ def regressfrommaps(
         if debug:
             print(f"using raw lagged regressors for regression")
         regressorset = lagtc
-        evset = rt_floatset(genlagtc.yfromx(initial_fmri_x))
+        evset = (genlagtc.yfromx(initial_fmri_x)).astype(rt_floattype)
     if debug:
         print(f"{regressorset.shape=}")
 
@@ -152,7 +277,6 @@ def regressfrommaps(
         showprogressbar=showprogressbar,
         verbose=(LGR is not None),
         chunksize=chunksize,
-        rt_floatset=rt_floatset,
         rt_floattype=rt_floattype,
         debug=debug,
     )

rapidtide/workflows/resamplenifti.py

@@ -30,6 +30,10 @@ with warnings.catch_warnings():
     else:
         pyfftwpresent = True
 
+from argparse import Namespace
+from typing import Any, Callable, Dict, List, Optional, Tuple, Union
+
+from numpy.typing import NDArray
 from scipy import fftpack
 
 import rapidtide.io as tide_io
@@ -40,9 +44,37 @@ if pyfftwpresent:
     pyfftw.interfaces.cache.enable()
 
 
-def _get_parser():
+def _get_parser() -> Any:
     """
-    Argument parser for resamplenifti
+    Argument parser for resamplenifti.
+
+    Creates and configures an argument parser for the resamplenifti command-line tool
+    that resamples NIfTI files to a different temporal resolution (TR).
+
+    Returns
+    -------
+    argparse.ArgumentParser
+        Configured argument parser object with all required and optional arguments
+        for the resamplenifti tool.
+
+    Notes
+    -----
+    The returned parser includes the following positional arguments:
+    - inputfile: Path to the input NIfTI file
+    - outputfile: Path to the output NIfTI file
+    - outputtr: Target temporal resolution in seconds
+
+    And the following optional arguments:
+    - --noantialias: Disable antialiasing filter (enabled by default)
+    - --normalize: Normalize data and save as UINT16 (disabled by default)
+    - --debug: Print debugging information (disabled by default)
+
+    Examples
+    --------
+    >>> parser = _get_parser()
+    >>> args = parser.parse_args(['input.nii', 'output.nii', '2.0'])
+    >>> print(args.inputfile)
+    'input.nii'
     """
     parser = argparse.ArgumentParser(
         prog="resamplenifti",
@@ -78,7 +110,57 @@ def _get_parser():
     return parser
 
 
-def resamplenifti(args):
+def resamplenifti(args: Any) -> None:
+    """
+    Resample a 4D NIfTI file to a specified temporal resolution.
+
+    This function reads a 4D NIfTI file, resamples its time series data to a
+    new temporal resolution specified by `args.outputtr`, and saves the
+    resampled data to a new NIfTI file. The resampling is performed using
+    spline interpolation, and optional antialiasing is applied based on the
+    input and output temporal resolutions.
+
+    Parameters
+    ----------
+    args : argparse.Namespace
+        An object containing the following attributes:
+        - inputfile : str
+            Path to the input NIfTI file.
+        - outputfile : str
+            Path to the output NIfTI file.
+        - outputtr : float
+            Desired output temporal resolution (TR) in seconds.
+        - antialias : bool, optional
+            Whether to apply antialiasing during resampling. Default is True.
+        - debug : bool, optional
+            If True, print debugging information. Default is False.
+
+    Returns
+    -------
+    None
+        This function does not return a value but saves the resampled NIfTI
+        file to the specified output path.
+
+    Notes
+    -----
+    - If the input TR is greater than the output TR (i.e., upsampling), antialiasing
+      is automatically disabled.
+    - The function processes each voxel individually, which may be time-consuming
+      for large datasets.
+    - The output NIfTI header is updated to reflect the new temporal resolution.
+
+    Examples
+    --------
+    >>> import argparse
+    >>> args = argparse.Namespace(
+    ...     inputfile='input.nii.gz',
+    ...     outputfile='output.nii.gz',
+    ...     outputtr=1.0,
+    ...     antialias=True,
+    ...     debug=False
+    ... )
+    >>> resamplenifti(args)
+    """
     # get the input TR
     inputtr, numinputtrs = tide_io.fmritimeinfo(args.inputfile)
     if args.debug:

rapidtide/workflows/resampletc.py

@@ -17,18 +17,49 @@
 #
 #
 import argparse
+from argparse import Namespace
+from typing import Any, Callable, Dict, List, Optional, Tuple, Union
 
 import matplotlib.pyplot as plt
 import numpy as np
+from numpy.typing import NDArray
 
 import rapidtide.io as tide_io
 import rapidtide.resample as tide_resample
 import rapidtide.workflows.parser_funcs as pf
 
 
-def _get_parser():
+def _get_parser() -> Any:
     """
-    Argument parser for resamp1tc
+    Argument parser for resamp1tc.
+
+    This function constructs and returns an `argparse.ArgumentParser` object configured
+    for parsing command-line arguments for the `resamp1tc` utility. It defines required
+    and optional arguments needed to resample a timeseries file.
+
+    Returns
+    -------
+    argparse.ArgumentParser
+        Configured argument parser for the resamp1tc utility.
+
+    Notes
+    -----
+    The parser includes the following required arguments:
+
+    - ``inputfile``: Path to the input timeseries file.
+    - ``insamplerate``: Input sample rate in Hz.
+    - ``outputfile``: Path to the output resampled file.
+    - ``outsamplerate``: Output sample rate in Hz.
+
+    Optional arguments include:
+
+    - ``--nodisplay``: Do not display data.
+    - ``--noantialias``: Disable antialiasing.
+
+    Examples
+    --------
+    >>> parser = _get_parser()
+    >>> args = parser.parse_args()
     """
     parser = argparse.ArgumentParser(
         prog="resampletc",
@@ -91,7 +122,64 @@ def _get_parser():
     return parser
 
 
-def resampletc(args):
+def resampletc(args: Any) -> None:
+    """
+    Resample a time series signal from an input file to a specified output sampling rate.
+
+    This function reads a time series from a text file, resamples it to a new sampling rate,
+    and writes the resampled data to an output file. Optionally, it displays the original
+    and resampled signals for visual comparison.
+
+    Parameters
+    ----------
+    args : Any
+        An object containing the following attributes:
+        - `inputfile` : str
+            Path to the input text file containing the time series data.
+        - `outputfile` : str
+            Path to the output text file where resampled data will be written.
+        - `insamplerate` : float
+            Input sampling rate (Hz) of the data in the input file.
+        - `outsamplerate` : float
+            Desired output sampling rate (Hz) for the resampled data.
+        - `antialias` : bool
+            Whether to apply anti-aliasing during resampling.
+        - `display` : bool
+            If True, plots the original and resampled signals.
+        - `starttime` : float, optional
+            Start time for the output signal. If None, uses the start time from input.
+        - `endtime` : float, optional
+            End time for the output signal. If None, uses the end time from input.
+
+    Returns
+    -------
+    None
+        This function does not return a value. It writes the resampled data to a file
+        and optionally displays a plot.
+
+    Notes
+    -----
+    - The input file is expected to contain a single column of time series data.
+    - If the sampling rate specified in the input file does not match `args.insamplerate`,
+      a warning is printed.
+    - The function uses `tide_resample.arbresample` for resampling with configurable
+      anti-aliasing.
+    - If `args.display` is True, the original and resampled signals are plotted
+      with the original in black and the resampled in red.
+
+    Examples
+    --------
+    >>> import argparse
+    >>> args = argparse.Namespace(
+    ...     inputfile='input.txt',
+    ...     outputfile='output.txt',
+    ...     insamplerate=10.0,
+    ...     outsamplerate=5.0,
+    ...     antialias=True,
+    ...     display=False
+    ... )
+    >>> resampletc(args)
+    """
     intimestep = 1.0 / args.insamplerate
     outtimestep = 1.0 / args.outsamplerate
     (

rapidtide/workflows/retrolagtcs.py

@@ -21,8 +21,11 @@ import copy
 import logging
 import os
 import sys
+from argparse import Namespace
+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.linfitfiltpass as tide_linfitfiltpass
@@ -39,9 +42,32 @@ TimingLGR = logging.getLogger("TIMING")
 DEFAULT_REGRESSIONFILTDERIVS = 0
 
 
-def _get_parser():
+def _get_parser() -> Any:
     """
-    Argument parser for retrolagtcs
+    Argument parser for retrolagtcs.
+
+    This function constructs and returns an `argparse.ArgumentParser` object configured
+    for the `retrolagtcs` command-line tool. It defines all required and optional
+    arguments needed to generate voxel-specific lagged timecourses from rapidtide
+    analysis maps.
+
+    Returns
+    -------
+    argparse.ArgumentParser
+        Configured argument parser for retrolagtcs.
+
+    Notes
+    -----
+    The parser expects several input files and parameters to define the processing
+    pipeline. The function uses `pf.is_valid_file` to validate the existence of
+    the input 4D NIfTI file.
+
+    Examples
+    --------
+    >>> parser = _get_parser()
+    >>> args = parser.parse_args()
+    >>> print(args.fmrifile)
+    'sub-01_task-rest_bold.nii.gz'
     """
     parser = argparse.ArgumentParser(
         prog="retrolagtcs",
@@ -126,11 +152,71 @@ def _get_parser():
     return parser
 
 
-def retrolagtcs(args):
-    rt_floatset = np.float64
-    rt_floattype = "float64"
-    rt_outfloatset = np.float64
-    rt_outfloattype = "float64"
+def retrolagtcs(args: Any) -> None:
+    """
+    Generate lagged time series regressors from fMRI data using a lag-time map and a generator file.
+
+    This function reads fMRI data, a mask, and a lag-time map to compute lagged time series
+    regressors for each voxel in the mask. It supports both single-process and multi-process
+    execution using shared memory. The computed regressors are saved as NIfTI files.
+
+    Parameters
+    ----------
+    args : Any
+        An object containing the following attributes:
+        - fmrifile : str
+            Path to the input fMRI NIfTI file.
+        - maskfile : str
+            Path to the processing mask NIfTI file.
+        - lagtimesfile : str
+            Path to the lag times NIfTI file.
+        - lagtcgeneratorfile : str
+            Path to the lagtc generator file (used for resampling).
+        - outputroot : str
+            Root path for output files.
+        - nprocs : int
+            Number of processes to use for parallel execution. If less than 1, defaults to max CPU count.
+        - numskip : int
+            Number of initial time points to skip.
+        - regressderivs : int
+            Number of time derivatives to include in the regressor set.
+        - showprogressbar : bool
+            Whether to display a progress bar during processing.
+        - debug : bool
+            Whether to enable debug mode for additional logging.
+
+    Returns
+    -------
+    None
+        This function does not return a value but writes output files to disk.
+
+    Notes
+    -----
+    - The function requires the input files to have matching spatial dimensions.
+    - Shared memory is used for multi-process execution to improve performance.
+    - Output files include:
+        - Regressor time series (4D NIfTI)
+        - Optional mask and lag time maps (3D NIfTI)
+
+    Examples
+    --------
+    >>> import argparse
+    >>> args = argparse.Namespace(
+    ...     fmrifile='fmri.nii.gz',
+    ...     maskfile='mask.nii.gz',
+    ...     lagtimesfile='lagtimes.nii.gz',
+    ...     lagtcgeneratorfile='generator.txt',
+    ...     outputroot='output',
+    ...     nprocs=4,
+    ...     numskip=5,
+    ...     regressderivs=2,
+    ...     showprogressbar=True,
+    ...     debug=False
+    ... )
+    >>> retrolagtcs(args)
+    """
+    rt_floattype = np.float64
+    rt_outfloattype = np.float64
 
     # get the pid of the parent process
     args.pid = os.getpid()
@@ -229,11 +315,15 @@ def retrolagtcs(args):
     else:
         if args.debug:
             print("allocating memory")
-    fitNorm, fitNorm_shm = tide_util.allocarray(internalvalidspaceshapederivs, 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
     )
-    lagtc, lagtc_shm = tide_util.allocarray(internalvalidfmrishape, rt_floattype, shared=usesharedmem)
+    lagtc, lagtc_shm = tide_util.allocarray(
+        internalvalidfmrishape, rt_floattype, shared=usesharedmem
+    )
 
     outputpath = os.path.dirname(args.outputroot)
     rawsources = [