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

rapidtide/workflows/rapidtide.py

@@ -23,8 +23,10 @@ import platform
 import sys
 import warnings
 from pathlib import Path
+from typing import Any, Tuple
 
 import numpy as np
+from numpy.typing import NDArray
 from scipy.stats import rankdata
 
 import rapidtide.calccoherence as tide_calccoherence
@@ -66,7 +68,36 @@ ErrorLGR = logging.getLogger("ERROR")
 TimingLGR = logging.getLogger("TIMING")
 
 
-def checkforzeromean(thedataset):
+def checkforzeromean(thedataset: Any) -> bool:
+    """
+    Check if the mean of dataset is zero.
+
+    Parameters
+    ----------
+    thedataset : array-like
+        Input dataset to check for zero mean. Should be array-like structure
+        that can be processed by numpy mean and std functions.
+
+    Returns
+    -------
+    bool
+        True if the mean of standard deviations is greater than the mean of means,
+        False otherwise.
+
+    Notes
+    -----
+    This function calculates the mean and standard deviation along axis 1,
+    then compares the means of these two arrays. The function name suggests
+    checking for zero mean, but the implementation actually compares means
+    and standard deviations rather than directly checking if mean equals zero.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> data = np.array([[1, 2, 3], [4, 5, 6]])
+    >>> checkforzeromean(data)
+    False
+    """
     themean = np.mean(thedataset, axis=1)
     thestd = np.std(thedataset, axis=1)
     if np.mean(thestd) > np.mean(themean):
@@ -75,7 +106,59 @@ def checkforzeromean(thedataset):
         return False
 
 
-def echocancel(thetimecourse, echooffset, thetimestep, outputname, padtimepoints):
+def echocancel(
+    thetimecourse: Any, echooffset: Any, thetimestep: Any, outputname: Any, padtimepoints: Any
+) -> Tuple[NDArray, NDArray, float]:
+    """
+    Perform echo cancellation on a timecourse using linear regression.
+
+    This function applies echo cancellation to a given timecourse by modeling the echo signal
+    and subtracting its contribution from the original signal. The echo is shifted in time
+    according to `echooffset` and then fitted using maximum likelihood regression. The
+    resulting filtered timecourse is saved along with the original and echo components.
+
+    Parameters
+    ----------
+    thetimecourse : array-like
+        The input timecourse data to be processed.
+    echooffset : float
+        The time offset (in seconds) of the echo signal relative to the input timecourse.
+    thetimestep : float
+        The time step (in seconds) of the input timecourse.
+    outputname : str
+        Base name for output files; used to construct filenames for saved results.
+    padtimepoints : int
+        Number of timepoints to pad during resampling of the echo signal.
+
+    Returns
+    -------
+    tuple
+        A tuple containing:
+        - `outputtimecourse`: The timecourse after echo cancellation.
+        - `echofit`: The regression coefficients from fitting the echo signal.
+        - `echoR2`: The R-squared value of the echo fit.
+
+    Notes
+    -----
+    - The function writes three separate TSV files:
+        1. Original timecourse.
+        2. Echo signal.
+        3. Filtered (echo-cancelled) timecourse.
+    - The echo signal is shifted in time using `tide_resample.timeshift`.
+    - The echo is zeroed out at the beginning up to the computed shift.
+    - The function uses `tide_fit.mlregress` for linear regression fitting.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> timecourse = np.random.rand(100)
+    >>> echo_offset = 2.0
+    >>> time_step = 1.0
+    >>> output_name = "test_output"
+    >>> pad_points = 10
+    >>> result = echocancel(timecourse, echo_offset, time_step, output_name, pad_points)
+    >>> filtered_tc, fit_coeffs, r2 = result
+    """
     tide_io.writebidstsv(
         f"{outputname}_desc-echocancellation_timeseries",
         thetimecourse,
@@ -114,12 +197,84 @@ def echocancel(thetimecourse, echooffset, thetimestep, outputname, padtimepoints
     )
     return outputtimecourse, echofit, echoR2
 
-def setpassoptions(passdict, optiondict):
+
+def setpassoptions(passdict: Any, optiondict: Any) -> None:
+    """
+    Copy key-value pairs from passdict to optiondict.
+
+    This function updates the optiondict with key-value pairs from passdict,
+    effectively passing options from one dictionary to another.
+
+    Parameters
+    ----------
+    passdict : Any
+        Dictionary containing options to be passed
+    optiondict : Any
+        Dictionary that will receive the options from passdict
+
+    Returns
+    -------
+    None
+        This function modifies optiondict in-place and returns None
+
+    Notes
+    -----
+    This function performs an in-place update of optiondict. Any existing keys
+    in optiondict that are also present in passdict will be overwritten with
+    the values from passdict.
+
+    Examples
+    --------
+    >>> options = {'verbose': True, 'timeout': 30}
+    >>> new_options = {'debug': False}
+    >>> setpassoptions(options, new_options)
+    >>> print(new_options)
+    {'debug': False, 'verbose': True, 'timeout': 30}
+    """
     for key, value in passdict.items():
         optiondict[key] = value
 
 
-def rapidtide_main(argparsingfunc):
+def rapidtide_main(argparsingfunc: Any) -> None:
+    """
+    Process fMRI data to perform spatially localized signal-to-noise ratio (sLFO) analysis.
+
+    This function performs a comprehensive analysis of fMRI data including correlation
+    analysis, signal filtering, and various statistical computations to identify and
+    remove spatially localized noise components.
+
+    Parameters
+    ----------
+    None
+
+    Returns
+    -------
+    None
+        The function performs in-place processing and saves results to files.
+
+    Notes
+    -----
+    This function is designed to be called as part of a larger pipeline for fMRI
+    preprocessing and analysis. It handles multiple stages including:
+
+    1. Data initialization and validation
+    2. Correlation analysis across spatial locations
+    3. Signal filtering and noise removal
+    4. Statistical computations and result saving
+    5. Timing and logging management
+
+    Examples
+    --------
+    >>> process_fmri_data()
+    # Processes fMRI data and saves results to output files
+
+    See Also
+    --------
+    tide_regressfrommaps : Performs regression analysis on fMRI data
+    tide_io : Handles input/output operations for fMRI data
+    tide_util : Utility functions for processing fMRI data
+
+    """
     optiondict, theprefilter = argparsingfunc
     optiondict["threaddebug"] = False
 
@@ -179,7 +334,7 @@ def rapidtide_main(argparsingfunc):
         logger_filename=f"{outputname}_log.txt",
         timing_filename=f"{outputname}_runtimings.tsv",
         memory_filename=f"{outputname}_memusage.tsv",
-        verbose=optiondict["verbose"],
+        isverbose=optiondict["verbose"],
         debug=optiondict["debug"],
     )
     TimingLGR.info("Start")
@@ -306,6 +461,7 @@ def rapidtide_main(argparsingfunc):
     if optiondict["oversampfactor"] < 0:
         optiondict["oversampfactor"] = int(np.max([np.ceil(fmritr / 0.5), 1]))
         LGR.debug(f"oversample factor set to {optiondict['oversampfactor']}")
+    # optiondict["prewhitenlags"] *= optiondict["oversampfactor"]
 
     oversamptr = fmritr / optiondict["oversampfactor"]
     LGR.verbose(f"fmri data: {timepoints} timepoints, tr = {fmritr}, oversamptr = {oversamptr}")
@@ -350,6 +506,13 @@ def rapidtide_main(argparsingfunc):
     optiondict["osvalidsimcalcend"] = osvalidsimcalcend
     optiondict["simcalcoffset"] = -validsimcalcstart * fmritr
 
+    ####################################################
+    # Calculate initial stats
+    ####################################################
+    init_min, init_max, init_mean, init_std, init_median, init_MAD, init_skew, init_kurtosis = (
+        tide_stats.fmristats(theinputdata.byvoxel())
+    )
+
     ####################################################
     #  Prepare data
     ####################################################
@@ -372,7 +535,7 @@ def rapidtide_main(argparsingfunc):
                     valslist=optiondict[thisanatomic[1]],
                     maskname=thisanatomic[2],
                     tolerance=optiondict["spatialtolerance"],
-                    debug=optiondict["focaldebug"],
+                    debug=optiondict["debug"],
                 )
             )
             anatomicmasks[-1] = np.uint16(np.where(anatomicmasks[-1] > 0.1, 1, 0))
@@ -443,7 +606,7 @@ def rapidtide_main(argparsingfunc):
             numspatiallocs,
             istext=(theinputdata.filetype == "text"),
             tolerance=optiondict["spatialtolerance"],
-            debug=optiondict["focaldebug"],
+            debug=optiondict["debug"],
         )
     )
     if internalinvbrainmask is not None:
@@ -462,7 +625,7 @@ def rapidtide_main(argparsingfunc):
         numspatiallocs,
         istext=(theinputdata.filetype == "text"),
         tolerance=optiondict["spatialtolerance"],
-        debug=optiondict["focaldebug"],
+        debug=optiondict["debug"],
     )
     if internalinvbrainmask is not None:
         if internalrefineexcludemask is not None:
@@ -480,7 +643,7 @@ def rapidtide_main(argparsingfunc):
         numspatiallocs,
         istext=(theinputdata.filetype == "text"),
         tolerance=optiondict["spatialtolerance"],
-        debug=optiondict["focaldebug"],
+        debug=optiondict["debug"],
     )
     if internalinvbrainmask is not None:
         if internaloffsetexcludemask is not None:
@@ -502,7 +665,7 @@ def rapidtide_main(argparsingfunc):
             valslist=optiondict["corrmaskincludevals"],
             maskname="correlation",
             tolerance=optiondict["spatialtolerance"],
-            debug=optiondict["focaldebug"],
+            debug=optiondict["debug"],
         )
 
         corrmask = np.uint16(np.where(thecorrmask > 0, 1, 0).reshape(numspatiallocs))
@@ -1260,7 +1423,7 @@ def rapidtide_main(argparsingfunc):
         corrpadding=optiondict["corrpadding"],
         debug=optiondict["debug"],
     )
-    if optiondict["focaldebug"]:
+    if optiondict["debug"]:
         print(
             f"calling setreftc during initialization with length {optiondict['oversampfactor'] * validtimepoints}"
         )
@@ -1613,7 +1776,9 @@ def rapidtide_main(argparsingfunc):
             tmask_y=tmask_y,
             tmaskos_y=tmaskos_y,
             fastresamplerpadtime=optiondict["fastresamplerpadtime"],
-            debug=optiondict["debug"],
+            prewhitenregressor=False,
+            prewhitenlags=optiondict["prewhitenlags"],
+            debug=optiondict["focaldebug"],
         )
 
     # cycle over all voxels
@@ -1713,6 +1878,32 @@ def rapidtide_main(argparsingfunc):
                 "message3": "voxels",
             },
         )
+        tide_io.writebidstsv(
+            f"{outputname}_desc-oversampledmovingregressor_timeseries",
+            tide_math.stdnormalize(resampref_y),
+            oversampfreq,
+            columns=["pass1_echocancel"],
+            extraheaderinfo={
+                "Description": "The probe regressor used in each pass, at the time resolution used for calculating the similarity function"
+            },
+            append=True,
+        )
+
+    # Preprocessing - prewhitening
+    if optiondict["prewhitenregressor"]:
+        resampref_y = tide_fit.prewhiten(
+            resampref_y, optiondict["prewhitenlags"], debug=optiondict["focaldebug"]
+        )
+        tide_io.writebidstsv(
+            f"{outputname}_desc-oversampledmovingregressor_timeseries",
+            tide_math.stdnormalize(resampref_y),
+            oversampfreq,
+            columns=["pass1_prewhiten"],
+            extraheaderinfo={
+                "Description": "The probe regressor used in each pass, at the time resolution used for calculating the similarity function"
+            },
+            append=True,
+        )
 
     # --------------------- Main pass loop ---------------------
     # loop over all passes
@@ -1803,7 +1994,7 @@ def rapidtide_main(argparsingfunc):
             rt_floattype=rt_floattype,
             rt_floatset=rt_floatset,
         )
-        if optiondict["focaldebug"]:
+        if optiondict["debug"]:
             print(
                 f"after cleanregressor: {len(referencetc)=}, {len(cleaned_referencetc)=}, {osvalidsimcalcstart=}, {osvalidsimcalcend=}, {lagmininpts=}, {lagmaxinpts=}"
             )
@@ -1827,7 +2018,7 @@ def rapidtide_main(argparsingfunc):
                     f"{outputname}_options_pregetnull_pass" + str(thepass) + ".json",
                 )
             theCorrelator.setlimits(lagmininpts, lagmaxinpts)
-            if optiondict["focaldebug"]:
+            if optiondict["debug"]:
                 print(
                     f"calling setreftc prior to significance estimation with length {len(cleaned_resampref_y)}"
                 )
@@ -2002,7 +2193,7 @@ def rapidtide_main(argparsingfunc):
             rt_floatset=rt_floatset,
             rt_floattype=rt_floattype,
             threaddebug=optiondict["threaddebug"],
-            debug=optiondict["focaldebug"],
+            debug=optiondict["debug"],
         )
         if optiondict["similaritymetric"] == "riptide":
             optiondict["despeckle_passes"] = 0
@@ -2669,6 +2860,12 @@ def rapidtide_main(argparsingfunc):
             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,
+            )
+
             LGR.info("End filtering operation")
             TimingLGR.info(
                 "sLFO filtering end",
@@ -2978,6 +3175,13 @@ def rapidtide_main(argparsingfunc):
                     "percent",
                     "Change in inband variance after filtering, in percent",
                 ),
+                # (
+                #    lfofilteredmeanvalue,
+                #    "lfofilterMean",
+                #    "map",
+                #    None,
+                #    "Voxelwise mean of the sLFO filtered data",
+                # ),
             ]
             if optiondict["saveminimumsLFOfiltfiles"]:
                 maplist += [
@@ -3039,6 +3243,59 @@ def rapidtide_main(argparsingfunc):
                             "Normalized fit coefficient",
                         ),
                     ]
+                init_std_valid = init_std[validvoxels] + 0.0
+                init_skew_valid = init_skew[validvoxels] + 0.0
+                init_kurtosis_valid = init_kurtosis[validvoxels] + 0.0
+                maplist += [
+                    (init_std_valid, "initialStd", "map", None, "Std of the raw input data"),
+                    (
+                        init_skew_valid,
+                        "initialSkewness",
+                        "map",
+                        None,
+                        "Skewness of the raw input data",
+                    ),
+                    (
+                        init_kurtosis_valid,
+                        "initialKurtosis",
+                        "map",
+                        None,
+                        "Kurtosis of the raw input data",
+                    ),
+                ]
+                (
+                    final_min_valid,
+                    final_max_valid,
+                    final_mean_valid,
+                    final_std_valid,
+                    final_median_valid,
+                    final_MAD_valid,
+                    final_skew_valid,
+                    final_kurtosis_valid,
+                ) = tide_stats.fmristats(filtereddata)
+                maplist += [
+                    (
+                        final_std_valid,
+                        "lfofilterCleanedStd",
+                        "map",
+                        None,
+                        "Std of the sLFO cleaned data",
+                    ),
+                    (
+                        final_skew_valid,
+                        "lfofilterCleanedSkewness",
+                        "map",
+                        None,
+                        "Skewness of the sLFO cleaned data",
+                    ),
+                    (
+                        final_kurtosis_valid,
+                        "lfofilterCleanedKurtosis",
+                        "map",
+                        None,
+                        "Kurtosis of the sLFO cleaned data",
+                    ),
+                ]
         else:
             maplist = [
                 (

rapidtide/workflows/rapidtide2std.py

@@ -20,12 +20,39 @@ import argparse
 import glob
 import os
 import sys
+from argparse import Namespace
+from typing import Any, Callable, Dict, List, Optional, Tuple, Union
 
 import rapidtide.externaltools as tide_exttools
 import rapidtide.io as tide_io
 
 
-def _get_parser():
+def _get_parser() -> Any:
+    """
+    Create and configure an argument parser for the rapidtide2std command-line tool.
+
+    This function sets up an `argparse.ArgumentParser` with specific arguments
+    required for registering rapidtide output maps to standard space. It supports
+    various options for controlling the transformation process, including linear
+    vs. nonlinear registration, file selection, and debugging output.
+
+    Returns
+    -------
+    argparse.ArgumentParser
+        Configured argument parser with all required and optional arguments.
+
+    Notes
+    -----
+    The parser is designed for use with the `rapidtide2std` command-line tool.
+    It expects three mandatory positional arguments: `inputfileroot`, `outputdir`,
+    and `featdirectory`. Additional optional arguments control the behavior of the
+    registration process.
+
+    Examples
+    --------
+    >>> parser = _get_parser()
+    >>> args = parser.parse_args()
+    """
     # get the command line parameters
     parser = argparse.ArgumentParser(
         prog="rapidtide2std",
@@ -111,7 +138,76 @@ def _get_parser():
     return parser
 
 
-def rapidtide2std(args):
+def rapidtide2std(args: Any) -> None:
+    """
+    Transform RapidTide output maps and timecourses to standard (MNI) or high-resolution (T1) space.
+
+    This function performs spatial normalization of RapidTide-derived functional and anatomical
+    maps using FSL's FLIRT and FNIRT tools. It supports both linear and nonlinear transformations
+    depending on the presence of warp files and user-specified options. The function processes
+    all relevant output files from a RapidTide analysis and applies the appropriate transformation
+    to align them with either the standard MNI152 template or the high-resolution T1-weighted image.
+
+    Parameters
+    ----------
+    args : Any
+        An object containing command-line arguments. Expected attributes include:
+        - debug : bool, optional
+            Enable debug output.
+        - featdirectory : str
+            Path to the FEAT directory containing registration files.
+        - aligntohires : bool, optional
+            Align to high-resolution space instead of standard space.
+        - forcelinear : bool, optional
+            Force linear transformation even if warp file is present.
+        - onefilename : str, optional
+            Process a single input file instead of all files in the dataset.
+        - outputdir : str
+            Output directory for transformed files.
+        - inputfileroot : str
+            Root name for input files.
+        - corrout : bool, optional
+            Include corrout_info map in output.
+        - clean : bool, optional
+            Include lfofilterCleaned_bold map in output.
+        - confound : bool, optional
+            Include confoundfilterR2_map in output.
+        - sequential : bool, optional
+            Run commands sequentially instead of in parallel.
+        - preponly : bool, optional
+            Only print commands without executing them.
+
+    Returns
+    -------
+    None
+        This function does not return any value. It performs file I/O and system calls
+        to transform and copy files to the specified output directory.
+
+    Notes
+    -----
+    The function expects the FSL environment variable FSLDIR to be set. It uses the
+    example_func2highres.mat or example_func2standard.mat transformation matrix and
+    the corresponding warp file (if present) to perform the spatial normalization.
+
+    Examples
+    --------
+    >>> import argparse
+    >>> args = argparse.Namespace(
+    ...     debug=False,
+    ...     featdirectory='/path/to/feat',
+    ...     aligntohires=False,
+    ...     forcelinear=False,
+    ...     onefilename=None,
+    ...     outputdir='output',
+    ...     inputfileroot='sub-01_task-rest',
+    ...     corrout=True,
+    ...     clean=False,
+    ...     confound=False,
+    ...     sequential=False,
+    ...     preponly=False
+    ... )
+    >>> rapidtide2std(args)
+    """
     if args.debug:
         print(args)