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

rapidtide/workflows/simdata.py

@@ -17,8 +17,11 @@
 #
 #
 import argparse
+import sys
+from typing import Any, Optional, Tuple
 
-from matplotlib.pyplot import *
+import numpy as np
+from numpy.typing import NDArray
 
 import rapidtide.filter as tide_filt
 import rapidtide.io as tide_io
@@ -28,9 +31,34 @@ import rapidtide.voxelData as tide_voxelData
 import rapidtide.workflows.parser_funcs as pf
 
 
-def _get_parser():
+def _get_parser() -> Any:
     """
-    Argument parser for simdata
+    Argument parser for simdata.
+
+    This function constructs and returns an `argparse.ArgumentParser` object
+    configured for parsing command-line arguments used by the `simdata` tool.
+    The parser supports both required and optional arguments for generating
+    simulated fMRI data with known correlation parameters.
+
+    Returns
+    -------
+    argparse.ArgumentParser
+        Configured argument parser for simdata command-line interface.
+
+    Notes
+    -----
+    The function sets up argument groups for LFO, respiratory, and cardiac
+    bands, each with mutually exclusive options for specifying signal strength
+    (either as a percentage of mean or as a fraction of inband variance).
+    Each band group also accepts optional files for specifying lag, regressor,
+    sample rate, and start time.
+
+    Examples
+    --------
+    >>> parser = _get_parser()
+    >>> args = parser.parse_args(['--lfo pctfile', 'lfo.nii', 'output'])
+    >>> print(args.lfo_pctfile)
+    'lfo.nii'
     """
     parser = argparse.ArgumentParser(
         prog="simdata",
@@ -177,17 +205,83 @@ def _get_parser():
 
 
 def prepareband(
-    simdatadims,
-    pctfile,
-    sigfracfile,
-    lagfile,
-    regressorfile,
-    samprate,
-    starttime,
-    regressorname,
-    padtime=30.0,
-    debug=False,
-):
+    simdatadims: Any,
+    pctfile: str,
+    sigfracfile: Any,
+    lagfile: Any,
+    regressorfile: Any,
+    samprate: Any,
+    starttime: Any,
+    regressorname: Any,
+    padtime: float = 30.0,
+    debug: bool = False,
+) -> Tuple[NDArray, bool, NDArray, object]:
+    """
+    Prepare band-specific regressor data for time series analysis.
+
+    This function reads in a regressor timecourse from a text file and resamples it
+    to match the dimensions of fMRI data. It also loads percentile and lag data
+    from NIfTI files, performing necessary checks for spatial dimension matching.
+    A FastResampler is initialized for later use in resampling the regressor.
+
+    Parameters
+    ----------
+    simdatadims : Any
+        Spatial dimensions of the fMRI data.
+    pctfile : str
+        Path to the NIfTI file containing percentile data. If None, `sigfracfile` is used.
+    sigfracfile : Any
+        Path to the NIfTI file containing signal fraction data. Used if `pctfile` is None.
+    lagfile : Any
+        Path to the NIfTI file containing lag data.
+    regressorfile : Any
+        Path to the text file containing the regressor timecourse.
+    samprate : Any
+        Sampling rate of the regressor. If None, uses the value from `regressorfile`.
+    starttime : Any
+        Start time of the regressor. If None, uses the value from `regressorfile`.
+    regressorname : Any
+        Name of the regressor, used for logging and debugging.
+    padtime : float, optional
+        Padding time (in seconds) for the resampler. Default is 30.0.
+    debug : bool, optional
+        If True, prints debug information. Default is False.
+
+    Returns
+    -------
+    tuple
+        A tuple containing:
+        - pctdata : ndarray
+            The loaded and possibly scaled percentile or signal fraction data.
+        - pctscale : bool
+            Indicates whether the data was scaled from a percentile file.
+        - lagdata : ndarray
+            The loaded lag data from the NIfTI file.
+        - generator : FastResampler
+            An initialized FastResampler object for resampling the regressor.
+
+    Notes
+    -----
+    - The function checks that the spatial dimensions of the NIfTI files match
+      those of the fMRI data.
+    - If `pctfile` is None, the function uses `sigfracfile` and scales the data by 100.
+    - The regressor is normalized using standard normalization.
+
+    Examples
+    --------
+    >>> prepareband(
+    ...     simdatadims=[64, 64, 32],
+    ...     pctfile='pct.nii.gz',
+    ...     sigfracfile=None,
+    ...     lagfile='lag.nii.gz',
+    ...     regressorfile='regressor.txt',
+    ...     samprate=2.0,
+    ...     starttime=0.0,
+    ...     regressorname='band1',
+    ...     padtime=30.0,
+    ...     debug=False
+    ... )
+    """
     if debug:
         print("simdatadims:", simdatadims)
         print("pctfile:", pctfile)
@@ -261,28 +355,102 @@ def prepareband(
 
 
 def fmrisignal(
-    Fs,
-    times,
-    meanvalue,
-    dolfo=False,
-    lfowave=None,
-    lfomag=None,
-    lfodelay=None,
-    lfonoise=0.0,
-    lfofilter=None,
-    doresp=False,
-    respwave=None,
-    respmag=None,
-    respdelay=None,
-    respnoise=0.0,
-    respfilter=None,
-    docardiac=False,
-    cardiacwave=None,
-    cardiacmag=None,
-    cardiacdelay=None,
-    cardiacnoise=0.0,
-    cardiacfilter=None,
-):
+    Fs: float,
+    times: NDArray,
+    meanvalue: float,
+    dolfo: bool = False,
+    lfowave: Optional[object] = None,
+    lfomag: Optional[NDArray] = None,
+    lfodelay: Optional[Any] = None,
+    lfonoise: float = 0.0,
+    lfofilter: Optional[object] = None,
+    doresp: bool = False,
+    respwave: Optional[object] = None,
+    respmag: Optional[NDArray] = None,
+    respdelay: Optional[NDArray] = None,
+    respnoise: float = 0.0,
+    respfilter: Optional[object] = None,
+    docardiac: bool = False,
+    cardiacwave: Optional[object] = None,
+    cardiacmag: Optional[NDArray] = None,
+    cardiacdelay: Optional[NDArray] = None,
+    cardiacnoise: float = 0.0,
+    cardiacfilter: Optional[object] = None,
+) -> NDArray:
+    """
+    Generate an fMRI signal by combining multiple physiological waveforms.
+
+    This function constructs an fMRI signal by summing a base mean signal with
+    contributions from low-frequency oscillations (LFO), respiratory signals,
+    and cardiac signals, each optionally modulated by amplitude, delay, noise,
+    and filtering.
+
+    Parameters
+    ----------
+    Fs : float
+        Sampling frequency of the signal.
+    times : NDArray
+        Time vector for the signal.
+    meanvalue : float
+        Base mean signal value.
+    dolfo : bool, optional
+        Whether to include low-frequency oscillation (LFO) component. Default is False.
+    lfowave : Optional[object], optional
+        Waveform object for LFO signal. Default is None.
+    lfomag : Optional[Any], optional
+        Magnitude of LFO signal. Default is None.
+    lfodelay : Optional[Any], optional
+        Delay for LFO signal. Default is None.
+    lfonoise : float, optional
+        Noise level for LFO signal. Default is 0.0.
+    lfofilter : Optional[object], optional
+        Filter object for LFO noise. Default is None.
+    doresp : bool, optional
+        Whether to include respiratory signal component. Default is False.
+    respwave : Optional[object], optional
+        Waveform object for respiratory signal. Default is None.
+    respmag : Optional[Any], optional
+        Magnitude of respiratory signal. Default is None.
+    respdelay : Optional[Any], optional
+        Delay for respiratory signal. Default is None.
+    respnoise : float, optional
+        Noise level for respiratory signal. Default is 0.0.
+    respfilter : Optional[object], optional
+        Filter object for respiratory noise. Default is None.
+    docardiac : bool, optional
+        Whether to include cardiac signal component. Default is False.
+    cardiacwave : Optional[object], optional
+        Waveform object for cardiac signal. Default is None.
+    cardiacmag : Optional[Any], optional
+        Magnitude of cardiac signal. Default is None.
+    cardiacdelay : Optional[Any], optional
+        Delay for cardiac signal. Default is None.
+    cardiacnoise : float, optional
+        Noise level for cardiac signal. Default is 0.0.
+    cardiacfilter : Optional[object], optional
+        Filter object for cardiac noise. Default is None.
+
+    Returns
+    -------
+    None
+        The function currently returns None. The actual signal is computed and returned
+        by the function body, but the return statement is not correctly implemented.
+
+    Notes
+    -----
+    The function modifies the signal in-place and returns a signal array that includes
+    contributions from all enabled physiological components. Each component is scaled
+    by `meanvalue` and optionally processed with delay, magnitude, noise, and filtering.
+
+    Examples
+    --------
+    >>> Fs = 100
+    >>> times = np.linspace(0, 10, 1000)
+    >>> meanvalue = 1.0
+    >>> signal = fmrisignal(Fs, times, meanvalue)
+    >>> # With LFO component enabled
+    >>> signal = fmrisignal(Fs, times, meanvalue, dolfo=True, lfowave=wave, lfomag=0.5)
+    """
     thesignal = np.zeros((len(times)), dtype=float)
     if dolfo:
         thesignal += meanvalue * (
@@ -299,10 +467,68 @@ def fmrisignal(
             cardiacmag * cardiacwave.yfromx(times - cardiacdelay)
             + cardiacnoise * cardiacfilter.apply(Fs, np.random.standard_normal(len(times)))
         )
-    return thesignal + meanvalue
+    thesignal += meanvalue
+    return thesignal
 
 
-def simdata(args):
+def simdata(args: Any) -> None:
+    """
+    Generate simulated fMRI data based on physiological signal regressors.
+
+    This function simulates fMRI time series data by incorporating physiological
+    signals such as low-frequency oscillations (LFO), respiratory, and cardiac
+    signals. It reads in regressor files, applies filtering, and generates
+    voxel-wise time series using a signal simulation function.
+
+    Parameters
+    ----------
+    args : Any
+        An object containing command-line arguments specifying input and output
+        parameters. Expected attributes include:
+        - lfopctfile, lfosigfracfile, lfolagfile, lforegressor, lfosamprate,
+          lfostarttime: LFO-related input files and parameters.
+        - resppctfile, respsigfracfile, resplagfile, respregressor, respsamprate,
+          respstarttime: Respiratory-related input files and parameters.
+        - cardiacpctfile, cardiacsigfracfile, cardiaclagfile, cardiacregressor,
+          cardiacsamprate, cardiacstarttime: Cardiac-related input files and parameters.
+        - immeanfilename: Path to the mean image file.
+        - numtrs, numskip, fmritr: fMRI time series parameters.
+        - slicetimefile: Optional path to slice timing file.
+        - outputroot: Root name for output NIfTI files.
+        - globalnoiselevel, voxelnoiselevel: Noise parameters.
+        - debug: Boolean flag for debug output.
+
+    Returns
+    -------
+    None
+        This function does not return a value but saves the simulated fMRI data
+        to NIfTI files.
+
+    Notes
+    -----
+    The function requires at least one of LFO, respiratory, or cardiac signal
+    parameters to be specified. If none are provided, the function will print
+    help and exit.
+
+    Examples
+    --------
+    >>> import argparse
+    >>> args = argparse.Namespace(
+    ...     lfopctfile='lfo_pct.nii.gz',
+    ...     lfolagfile='lfo_lag.nii.gz',
+    ...     lforegressor='lfo_regressor.txt',
+    ...     lfosamprate=10.0,
+    ...     immeanfilename='mean_func.nii.gz',
+    ...     numtrs=200,
+    ...     numskip=10,
+    ...     fmritr=2.0,
+    ...     outputroot='simulated_data',
+    ...     globalnoiselevel=0.1,
+    ...     voxelnoiselevel=0.05,
+    ...     debug=False
+    ... )
+    >>> simdata(args)
+    """
     # set default variable values
     lfopctdata = None
     lfolagdata = None

rapidtide/workflows/spatialfit.py

@@ -17,6 +17,8 @@
 #
 #
 import argparse
+from argparse import Namespace
+from typing import Any, Callable, Dict, List, Optional, Tuple, Union
 
 from matplotlib.pyplot import *
 from tqdm import tqdm
@@ -26,7 +28,32 @@ import rapidtide.io as tide_io
 import rapidtide.workflows.parser_funcs as pf
 
 
-def _get_parser():
+def _get_parser() -> Any:
+    """
+    Create and configure an argument parser for the spatialfit command-line tool.
+
+    This function sets up an `argparse.ArgumentParser` with specific arguments
+    required for fitting a 3D or 4D NIFTI file to a spatial template. It includes
+    validation for file inputs and supports optional masking and fitting parameters.
+
+    Returns
+    -------
+    argparse.ArgumentParser
+        Configured argument parser with defined command-line arguments.
+
+    Notes
+    -----
+    The parser is configured with:
+    - Required positional arguments: `datafile`, `templatefile`, and `outputroot`.
+    - Optional arguments: `--datamask`, `--templatemask`, `--order`, and `--debug`.
+
+    Examples
+    --------
+    >>> parser = _get_parser()
+    >>> args = parser.parse_args(['data.nii', 'template.nii', 'output_root'])
+    >>> print(args.datafile)
+    'data.nii'
+    """
     # get the command line parameters
     parser = argparse.ArgumentParser(
         prog="spatialfit",
@@ -80,7 +107,55 @@ def _get_parser():
     return parser
 
 
-def spatialfit(args):
+def spatialfit(args: Any) -> None:
+    """
+    Perform spatial fitting of fMRI data using a template-based linear regression model.
+
+    This function reads input data and template files, performs masking, and fits a
+    linear model at each spatial location to estimate spatially varying linear coefficients,
+    offsets, and R² values. It outputs time series of these parameters along with fitted,
+    residual, and normalized data volumes.
+
+    Parameters
+    ----------
+    args : Any
+        Parsed command-line arguments. Expected to contain the following attributes:
+        - datafile : str
+            Path to the input NIfTI data file.
+        - templatefile : str
+            Path to the template NIfTI file.
+        - dmask : str, optional
+            Path to the data mask NIfTI file.
+        - tmask : str, optional
+            Path to the template mask NIfTI file.
+        - outputroot : str
+            Root name for output files.
+        - debug : bool, optional
+            Enable debug printing.
+
+    Returns
+    -------
+    None
+        This function does not return a value but writes multiple NIfTI and text files
+        to disk.
+
+    Notes
+    -----
+    The function assumes that the input data and template files have compatible
+    spatial dimensions. It performs a linear regression for each timepoint and
+    stores the resulting coefficients, offsets, and R² values.
+
+    Examples
+    --------
+    >>> import argparse
+    >>> args = argparse.Namespace(
+    ...     datafile='data.nii.gz',
+    ...     templatefile='template.nii.gz',
+    ...     outputroot='output',
+    ...     debug=False
+    ... )
+    >>> spatialfit(args)
+    """
     # get the command line parameters
     try:
         args = _get_parser().parse_args()