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

rapidtide/workflows/filttc.py

@@ -18,17 +18,42 @@
 #
 import argparse
 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.miscmath as tide_math
 import rapidtide.workflows.parser_funcs as pf
 
 
-def _get_parser():
+def _get_parser() -> Any:
     """
-    Argument parser for filttc
+    Argument parser for filttc.
+
+    This function constructs and returns an `argparse.ArgumentParser` object configured
+    for parsing command-line arguments for the `filttc` tool, which filters timecourse
+    data in text files. It includes support for specifying sampling rate or timestep,
+    filter options, normalization methods, and miscellaneous flags.
+
+    Returns
+    -------
+    argparse.ArgumentParser
+        Configured argument parser for the filttc tool.
+
+    Notes
+    -----
+    The `--samplerate` and `--sampletstep` arguments are mutually exclusive and define
+    the sampling frequency of the input timecourses. The sampling frequency can be
+    specified either as a frequency (Hz) or as a timestep (seconds), with the latter
+    being the inverse of the former.
+
+    Examples
+    --------
+    >>> parser = _get_parser()
+    >>> args = parser.parse_args(['--inputfile', 'input.txt', '--outputfile', 'output.txt'])
     """
     parser = argparse.ArgumentParser(
         prog="filttc",
@@ -104,7 +129,53 @@ def _get_parser():
     return parser
 
 
-def filttc(args):
+def filttc(args: Any) -> None:
+    """
+    Apply a filter to timecourse data read from a text file and write the filtered output.
+
+    This function reads timecourse data from a specified input file, applies a filter
+    to each timecourse, and writes the filtered data to an output file. It supports
+    normalization, demeaning, and automatic sampling rate detection from the input file
+    or command-line arguments.
+
+    Parameters
+    ----------
+    args : Any
+        An object containing command-line arguments. Expected attributes include:
+        - `inputfile`: Path to the input text file containing timecourse data.
+        - `outputfile`: Path to the output text file where filtered data will be written.
+        - `samplerate`: Sampling rate of the data, or 'auto' to detect from file.
+        - `normfirst`: Boolean indicating whether to normalize before filtering.
+        - `normmethod`: Normalization method to use (e.g., 'zscore', 'minmax').
+        - `demean`: Boolean indicating whether to remove the mean from the filtered data.
+
+    Returns
+    -------
+    None
+        This function does not return a value. It writes the filtered timecourse data
+        to the specified output file.
+
+    Notes
+    -----
+    - The input file must contain a header specifying the sampling rate, or the
+      sampling rate must be provided via command-line arguments.
+    - The filtering and normalization are applied independently to each timecourse.
+    - If `normfirst` is True, normalization is applied before filtering; otherwise,
+      filtering is applied before normalization.
+
+    Examples
+    --------
+    >>> import argparse
+    >>> args = argparse.Namespace(
+    ...     inputfile='input.txt',
+    ...     outputfile='output.txt',
+    ...     samplerate='auto',
+    ...     normfirst=False,
+    ...     normmethod='zscore',
+    ...     demean=True
+    ... )
+    >>> filttc(args)
+    """
     args, thefilter = pf.postprocessfilteropts(args)
 
     # read in data

rapidtide/workflows/fitSimFuncMap.py

@@ -16,7 +16,10 @@
 #   limitations under the License.
 #
 #
+from typing import Any, Callable, Dict, List, Optional, Tuple, Union
+
 import numpy as np
+from numpy.typing import NDArray
 from scipy import ndimage
 
 import rapidtide.io as tide_io
@@ -28,48 +31,193 @@ import rapidtide.util as tide_util
 
 
 def fitSimFunc(
-    fmri_data_valid,
-    validsimcalcstart,
-    validsimcalcend,
-    osvalidsimcalcstart,
-    osvalidsimcalcend,
-    initial_fmri_x,
-    os_fmri_x,
-    theMutualInformationator,
-    cleaned_referencetc,
-    corrout,
-    outputname,
-    validvoxels,
-    nativespaceshape,
-    bidsbasedict,
-    numspatiallocs,
-    gaussout,
-    theinitialdelay,
-    windowout,
-    R2,
-    thesizes,
-    internalspaceshape,
-    numvalidspatiallocs,
-    theinputdata,
-    theheader,
-    theFitter,
-    fitmask,
-    lagtimes,
-    lagstrengths,
-    lagsigma,
-    failreason,
-    outmaparray,
-    trimmedcorrscale,
-    similaritytype,
-    thepass,
-    optiondict,
-    LGR,
-    TimingLGR,
-    simplefit=False,
-    upsampfac=8,
-    rt_floatset=np.float64,
-    rt_floattype="float64",
-):
+    fmri_data_valid: NDArray[np.floating[Any]],
+    validsimcalcstart: int,
+    validsimcalcend: int,
+    osvalidsimcalcstart: int,
+    osvalidsimcalcend: int,
+    initial_fmri_x: NDArray[np.floating[Any]],
+    os_fmri_x: NDArray[np.floating[Any]],
+    theMutualInformationator: Any,
+    cleaned_referencetc: Any,
+    corrout: NDArray[np.floating[Any]],
+    outputname: str,
+    validvoxels: Any,
+    nativespaceshape: Any,
+    bidsbasedict: Any,
+    numspatiallocs: Any,
+    gaussout: Any,
+    theinitialdelay: Any,
+    windowout: Any,
+    R2: Any,
+    thesizes: Any,
+    internalspaceshape: Any,
+    numvalidspatiallocs: Any,
+    theinputdata: Any,
+    theheader: Any,
+    theFitter: Any,
+    fitmask: Any,
+    lagtimes: Any,
+    lagstrengths: Any,
+    lagsigma: Any,
+    failreason: Any,
+    outmaparray: Any,
+    trimmedcorrscale: Any,
+    similaritytype: Any,
+    thepass: Any,
+    optiondict: Any,
+    LGR: Any,
+    TimingLGR: Any,
+    simplefit: bool = False,
+    upsampfac: int = 8,
+    rt_floattype: np.dtype = np.float64,
+) -> NDArray | None:
+    """
+    Perform similarity function fitting and time lag estimation for fMRI data.
+
+    This function conducts either a simple or full fitting process for estimating time lags
+    between fMRI signals and a reference time course. It supports hybrid similarity metrics
+    and includes optional despeckling and patch shifting steps.
+
+    Parameters
+    ----------
+    fmri_data_valid : NDArray[np.floating[Any]]
+        Valid fMRI data for processing.
+    validsimcalcstart : int
+        Start index for valid similarity calculation.
+    validsimcalcend : int
+        End index for valid similarity calculation.
+    osvalidsimcalcstart : int
+        Start index for oversampled valid similarity calculation.
+    osvalidsimcalcend : int
+        End index for oversampled valid similarity calculation.
+    initial_fmri_x : NDArray[np.floating[Any]]
+        Initial fMRI x values.
+    os_fmri_x : NDArray[np.floating[Any]]
+        Oversampled fMRI x values.
+    theMutualInformationator : object
+        Mutual information calculator.
+    cleaned_referencetc : array_like
+        Cleaned reference time course.
+    corrout : NDArray[np.floating[Any]]
+        Correlation output array.
+    outputname : str
+        Output filename prefix.
+    validvoxels : array_like
+        Indices of valid voxels.
+    nativespaceshape : tuple
+        Native space shape of the data.
+    bidsbasedict : dict
+        BIDS-based dictionary for output metadata.
+    numspatiallocs : int
+        Number of spatial locations.
+    gaussout : array_like
+        Gaussian output array.
+    theinitialdelay : float
+        Initial delay value.
+    windowout : array_like
+        Window output array.
+    R2 : array_like
+        R-squared values.
+    thesizes : array_like
+        Sizes for processing.
+    internalspaceshape : tuple
+        Internal space shape.
+    numvalidspatiallocs : int
+        Number of valid spatial locations.
+    theinputdata : object
+        Input data object.
+    theheader : dict
+        Header information.
+    theFitter : object
+        Fitter object for similarity function fitting.
+    fitmask : array_like
+        Mask for fitting.
+    lagtimes : array_like
+        Array to store estimated lag times.
+    lagstrengths : array_like
+        Array to store lag strengths.
+    lagsigma : array_like
+        Array to store sigma values for lags.
+    failreason : array_like
+        Array to store failure reasons.
+    outmaparray : array_like
+        Output map array.
+    trimmedcorrscale : array_like
+        Trimmed correlation scale.
+    similaritytype : str
+        Type of similarity metric used.
+    thepass : int
+        Current pass number.
+    optiondict : dict
+        Dictionary of options for processing.
+    LGR : object
+        Logger for general messages.
+    TimingLGR : object
+        Logger for timing information.
+    simplefit : bool, optional
+        If True, perform simple fitting using upsampling. Default is False.
+    upsampfac : int, optional
+        Upsampling factor for simple fitting. Default is 8.
+    rt_floattype : np.dtype, optional
+        Real-time floating-point data type. Default is np.float64.
+
+    Returns
+    -------
+    internaldespeckleincludemask : NDArray[np.floating[Any]] or None
+        Mask indicating which voxels were included in despeckling, or None if no despeckling was performed.
+
+    Notes
+    -----
+    - This function supports both simple and hybrid similarity metrics.
+    - Despeckling and patch shifting steps are optional and controlled by `optiondict`.
+    - The function modifies `lagtimes`, `lagstrengths`, `lagsigma`, and `fitmask` in-place.
+
+    Examples
+    --------
+    >>> fitSimFunc(
+    ...     fmri_data_valid,
+    ...     validsimcalcstart,
+    ...     validsimcalcend,
+    ...     osvalidsimcalcstart,
+    ...     osvalidsimcalcend,
+    ...     initial_fmri_x,
+    ...     os_fmri_x,
+    ...     theMutualInformationator,
+    ...     cleaned_referencetc,
+    ...     corrout,
+    ...     outputname,
+    ...     validvoxels,
+    ...     nativespaceshape,
+    ...     bidsbasedict,
+    ...     numspatiallocs,
+    ...     gaussout,
+    ...     theinitialdelay,
+    ...     windowout,
+    ...     R2,
+    ...     thesizes,
+    ...     internalspaceshape,
+    ...     numvalidspatiallocs,
+    ...     theinputdata,
+    ...     theheader,
+    ...     theFitter,
+    ...     fitmask,
+    ...     lagtimes,
+    ...     lagstrengths,
+    ...     lagsigma,
+    ...     failreason,
+    ...     outmaparray,
+    ...     trimmedcorrscale,
+    ...     similaritytype,
+    ...     thepass,
+    ...     optiondict,
+    ...     LGR,
+    ...     TimingLGR,
+    ...     simplefit=False,
+    ...     upsampfac=8,
+    ...     rt_floattype="float64",
+    ... )
+    """
     # Do a peak prefit if doing hybrid
     if optiondict["similaritymetric"] == "hybrid":
         LGR.info(f"\n\nPeak prefit calculation, pass {thepass}")
@@ -91,7 +239,6 @@ def fitSimFunc(
             interptype=optiondict["interptype"],
             showprogressbar=optiondict["showprogressbar"],
             chunksize=optiondict["mp_chunksize"],
-            rt_floatset=rt_floatset,
             rt_floattype=rt_floattype,
         )
         tide_util.enablemkl(optiondict["mklthreads"], debug=optiondict["threaddebug"])
@@ -115,7 +262,9 @@ def fitSimFunc(
         delaystep = (trimmedcorrscale[1] - trimmedcorrscale[0]) / upsampfac
         for thevox in range(numvalidspatiallocs):
             fitmask[thevox] = 1
-            upsampcorrout = tide_resample.upsample(corrout[thevox,:],1, upsampfac, intfac=True, dofilt=False)
+            upsampcorrout = tide_resample.upsample(
+                corrout[thevox, :], 1, upsampfac, intfac=True, dofilt=False
+            )
             if optiondict["bipolar"]:
                 thismax = np.argmax(np.fabs(upsampcorrout))
             else:
@@ -164,7 +313,6 @@ def fitSimFunc(
             chunksize=optiondict["mp_chunksize"],
             despeckle_thresh=optiondict["despeckle_thresh"],
             initiallags=initlags,
-            rt_floatset=rt_floatset,
             rt_floattype=rt_floattype,
         )
         tide_util.enablemkl(optiondict["mklthreads"], debug=optiondict["threaddebug"])
@@ -193,9 +341,9 @@ def fitSimFunc(
                 outmaparray[validvoxels] = eval("lagtimes")[:]
 
                 # find voxels to despeckle
-                medianlags = ndimage.median_filter(outmaparray.reshape(nativespaceshape), 3).reshape(
-                    numspatiallocs
-                )
+                medianlags = ndimage.median_filter(
+                    outmaparray.reshape(nativespaceshape), 3
+                ).reshape(numspatiallocs)
                 # voxels that we're happy with have initlags set to -1000000.0
                 initlags = np.where(
                     np.abs(outmaparray - medianlags) > optiondict["despeckle_thresh"],
@@ -232,10 +380,11 @@ def fitSimFunc(
                             chunksize=optiondict["mp_chunksize"],
                             despeckle_thresh=optiondict["despeckle_thresh"],
                             initiallags=initlags,
-                            rt_floatset=rt_floatset,
                             rt_floattype=rt_floattype,
                         )
-                        tide_util.enablemkl(optiondict["mklthreads"], debug=optiondict["threaddebug"])
+                        tide_util.enablemkl(
+                            optiondict["mklthreads"], debug=optiondict["threaddebug"]
+                        )
 
                         voxelsprocessed_fc_ds += voxelsprocessed_thispass
                         optiondict[
@@ -258,7 +407,9 @@ def fitSimFunc(
                 0.0,
             )
             if optiondict["savedespecklemasks"] and (optiondict["despeckle_passes"] > 0):
-                despecklesavemask = np.where(internaldespeckleincludemask[validvoxels] == 0.0, 0, 1)
+                despecklesavemask = np.where(
+                    internaldespeckleincludemask[validvoxels] == 0.0, 0, 1
+                )
                 if thepass == optiondict["passes"]:
                     if theinputdata.filetype != "text":
                         if theinputdata.filetype == "cifti":

rapidtide/workflows/fixtr.py

@@ -17,13 +17,39 @@
 #
 #
 import argparse
+from argparse import Namespace
+from typing import Any, Callable, Dict, List, Optional, Tuple, Union
 
 import rapidtide.io as tide_io
 
 
-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 changes the TR (repetition time) in a NIFTI header.
+
+    Returns
+    -------
+    argparse.ArgumentParser
+        Configured argument parser object with all required and optional arguments
+        for the resamplenifti tool.
+
+    Notes
+    -----
+    The parser is configured with:
+    - Required positional arguments: inputfile, outputfile, and outputtr
+    - Optional debug flag for additional output
+    - Program name set to "fixtr"
+    - Description explaining the purpose of changing TR in NIFTI headers
+
+    Examples
+    --------
+    >>> parser = _get_parser()
+    >>> args = parser.parse_args(['input.nii', 'output', '2.0'])
+    >>> print(args.inputfile)
+    'input.nii'
     """
     parser = argparse.ArgumentParser(
         prog="fixtr",
@@ -45,7 +71,51 @@ def _get_parser():
     return parser
 
 
-def fixtr(args):
+def fixtr(args: Any) -> None:
+    """
+    Fix the temporal resolution (TR) of a NIfTI file.
+
+    This function reads a NIfTI file and modifies its header to change the
+    temporal resolution (TR) while preserving the original data. The output
+    file is saved with the new TR value in the header.
+
+    Parameters
+    ----------
+    args : Any
+        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 in seconds
+        - debug : bool, optional
+            If True, print debug information including input timepoints and TR
+
+    Returns
+    -------
+    None
+        This function does not return a value but saves the modified NIfTI file
+        to the specified output path.
+
+    Notes
+    -----
+    The function preserves the original data type and spatial dimensions of the
+    input file. The temporal dimension (t) in the output header is updated based
+    on the units specified in the input header. If the input header specifies
+    millisecond units, the output TR is converted from seconds to milliseconds.
+
+    Examples
+    --------
+    >>> class Args:
+    ...     def __init__(self):
+    ...         self.inputfile = "input.nii"
+    ...         self.outputfile = "output.nii"
+    ...         self.outputtr = 2.0
+    ...         self.debug = False
+    >>> args = Args()
+    >>> fixtr(args)
+    """
     # get the input TR
     inputtr, numinputtrs = tide_io.fmritimeinfo(args.inputfile)
     if args.debug:

rapidtide/workflows/gmscalc.py

@@ -20,8 +20,11 @@ import argparse
 import platform
 import sys
 import time
+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.filter as tide_filt
 import rapidtide.io as tide_io
@@ -30,7 +33,33 @@ import rapidtide.util as tide_util
 import rapidtide.workflows.parser_funcs as pf
 
 
-def _get_parser():
+def _get_parser() -> Any:
+    """
+    Construct and return an argument parser for the gmscalc tool.
+
+    This function sets up an `argparse.ArgumentParser` with required and optional
+    arguments needed to run the global mean signal calculation and filtering
+    pipeline. It includes support for specifying input data, output root, data mask,
+    normalization options, smoothing, and debugging.
+
+    Returns
+    -------
+    argparse.ArgumentParser
+        Configured argument parser with all required and optional arguments
+        for the gmscalc tool.
+
+    Notes
+    -----
+    The parser is configured with `allow_abbrev=False` to enforce full argument
+    names and avoid ambiguity.
+
+    Examples
+    --------
+    >>> parser = _get_parser()
+    >>> args = parser.parse_args(['data.nii', 'output_root'])
+    >>> print(args.datafile)
+    'data.nii'
+    """
     parser = argparse.ArgumentParser(
         prog="gmscalc",
         description="Calculate the global mean signal, and filtered versions",
@@ -86,7 +115,54 @@ def _get_parser():
     return parser
 
 
-def makecommandlinelist(arglist, starttime, endtime, extra=None):
+def makecommandlinelist(
+    arglist: Any, starttime: Any, endtime: Any, extra: Optional[Any] = None
+) -> None:
+    """
+    Create a list of command line information for logging purposes.
+
+    This function generates a list of descriptive strings containing processing
+    information including date, duration, version details, and the actual command
+    that was executed.
+
+    Parameters
+    ----------
+    arglist : Any
+        List of command line arguments to be joined into a command string.
+    starttime : Any
+        Start time of the process, typically a timestamp.
+    endtime : Any
+        End time of the process, typically a timestamp.
+    extra : Any, optional
+        Additional descriptive text to include in the output list. Default is None.
+
+    Returns
+    -------
+    list of str
+        List containing the following elements in order:
+        - Processing date and time
+        - Processing duration
+        - Node and version information
+        - Extra information (if provided)
+        - The actual command line string
+
+    Notes
+    -----
+    The function uses `time.strftime` to format the start time and `tide_util.version()`
+    to retrieve version information. The command line is constructed by joining
+    the `arglist` elements with spaces.
+
+    Examples
+    --------
+    >>> import time
+    >>> args = ['python', 'script.py', '--input', 'data.txt']
+    >>> start = time.time()
+    >>> # ... some processing ...
+    >>> end = time.time()
+    >>> info = makecommandlinelist(args, start, end)
+    >>> print(info[0])
+    '# Processed on Mon, 01 Jan 2024 12:00:00 UTC.'
+    """
     # get the processing date
     dateline = (
         "# Processed on "
@@ -123,7 +199,41 @@ def makecommandlinelist(arglist, starttime, endtime, extra=None):
         return [dateline, timeline, nodeline, commandline]
 
 
-def gmscalc_main():
+def gmscalc_main() -> None:
+    """
+    Main function to calculate global mean signal (GMS) from fMRI data.
+
+    This function reads NIfTI-formatted fMRI data, applies optional smoothing,
+    masks the data if a mask is provided, and computes the global mean signal
+    across valid voxels. It then applies low-frequency (LFO) and high-frequency
+    (HF) filtering to the global signal and writes the results to text files.
+
+    The function uses the `tide_io` module for reading and writing data, and
+    `tide_filt` and `tide_math` for filtering and normalization.
+
+    Notes
+    -----
+    The function expects a command-line interface to be set up with `_get_parser()`
+    and uses `sys.argv` to parse arguments. It prints diagnostic information
+    during execution.
+
+    Examples
+    --------
+    Assuming the script is called as `gmscalc_main.py` and properly configured:
+
+    >>> gmscalc_main()
+
+    This will read the input data, perform processing, and write output files
+    with names based on the `outputroot` argument.
+
+    See Also
+    --------
+    tide_io.readfromnifti : Reads NIfTI files.
+    tide_io.writevec : Writes vectors to text files.
+    tide_filt.ssmooth : Applies spatial smoothing.
+    tide_filt.NoncausalFilter : Applies non-causal filtering.
+    tide_math.normalize : Normalizes a signal.
+    """
     try:
         args = _get_parser().parse_args()
     except SystemExit: