rapidtide 2.9.5__py3-none-any.whl → 3.1.3__py3-none-any.whl

rapidtide/workflows/calctexticc.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
 #
-#   Copyright 2016-2024 Blaise Frederick
+#   Copyright 2016-2025 Blaise Frederick
 #
 #   Licensed under the Apache License, Version 2.0 (the "License");
 #   you may not use this file except in compliance with the License.
@@ -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
 from scipy.linalg import pinv
 
 import rapidtide.io as tide_io
@@ -30,7 +33,42 @@ import rapidtide.util as tide_util
 from rapidtide.workflows.parser_funcs import is_valid_file
 
 
-def _get_parser():
+def _get_parser() -> Any:
+    """
+    Create and configure an argument parser for the calcicc command-line tool.
+
+    This function sets up an `argparse.ArgumentParser` with required and optional
+    arguments needed to run the ICC(3,1) calculation on text-based data files.
+
+    Returns
+    -------
+    argparse.ArgumentParser
+        Configured argument parser object with all required and optional arguments
+        for the calcicc tool.
+
+    Notes
+    -----
+    The parser is configured with:
+    - A program name "calcicc"
+    - A description explaining the purpose of the tool
+    - Three required positional arguments:
+        1. `datafile`: comma-separated list of 2D text files
+        2. `measurementlist`: multicolumn file specifying how to group measurements
+        3. `outputroot`: root name for output text files
+    - Several optional flags for controlling behavior:
+        - `--demedian`: subtract median from each map before ICC calculation
+        - `--demean`: subtract mean from each map before ICC calculation
+        - `--nocache`: disable caching for ICC calculation (not recommended)
+        - `--debug`: enable basic debugging output
+        - `--deepdebug`: enable verbose debugging output
+
+    Examples
+    --------
+    >>> parser = _get_parser()
+    >>> args = parser.parse_args(['file1.txt', 'measurements.txt', 'output_root'])
+    >>> print(args.datafile)
+    'file1.txt'
+    """
     parser = argparse.ArgumentParser(
         prog="calcicc",
         description="Calculate per-column ICC(3,1) on a set of text files.",
@@ -105,7 +143,55 @@ def _get_parser():
     return parser
 
 
-def parsetextmeasurementlist(measlist, numfiles, debug=False):
+def parsetextmeasurementlist(
+    measlist: Any, numfiles: Any, debug: bool = False
+) -> Tuple[NDArray, NDArray]:
+    """
+    Parse a measurement list from text format into file and volume indices.
+
+    This function processes a 2D array of strings representing measurement entries,
+    where each entry is expected to contain either one or two comma-separated values.
+    The first value represents the file index, and the second represents the volume index.
+    If only one value is present, the file index is assumed to be 0.
+
+    Parameters
+    ----------
+    measlist : array-like
+        A 2D array of strings where each string contains either one or two
+        comma-separated integers representing file and volume indices.
+    numfiles : int
+        The total number of available files, used to validate file indices.
+    debug : bool, optional
+        If True, prints debug information for each parsed element. Default is False.
+
+    Returns
+    -------
+    tuple of ndarray
+        A tuple containing two 2D arrays:
+        - `filesel`: File indices for each measurement.
+        - `volumesel`: Volume indices for each measurement.
+
+    Notes
+    -----
+    - Each entry in `measlist` should be a string of the form "file,volume" or "volume".
+    - File indices are validated to ensure they do not exceed `numfiles - 1`.
+    - The function will exit with an error if:
+        1. An entry contains more than one comma.
+        2. A file index is out of bounds.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> measlist = np.array([["0,1", "1,2"], ["0", "2,3"]])
+    >>> numfiles = 3
+    >>> filesel, volumesel = parsetextmeasurementlist(measlist, numfiles)
+    >>> print(filesel)
+    [[0 1]
+     [0 2]]
+    >>> print(volumesel)
+    [[1 2]
+     [0 3]]
+    """
     # how do we get the number of subjects?
     nummeas, numsubjs = measlist.shape[0], measlist.shape[1]
     filesel = np.zeros((nummeas, numsubjs), dtype=int)
@@ -134,7 +220,54 @@ def parsetextmeasurementlist(measlist, numfiles, debug=False):
     return filesel, volumesel
 
 
-def makdcommandlinelist(arglist, starttime, endtime, extra=None):
+def makdcommandlinelist(
+    arglist: Any, starttime: Any, endtime: Any, extra: Optional[Any] = None
+) -> Tuple[str, str, str, str, str] | Tuple[str, str, str, str]:
+    """
+    Create a list of command line information for processing metadata.
+
+    This function generates a list of descriptive strings containing processing
+    information including timestamps, version details, and the command line
+    that was executed.
+
+    Parameters
+    ----------
+    arglist : Any
+        List of command line arguments that were used to invoke the process
+    starttime : Any
+        Start time of the process, typically a timestamp or time object
+    endtime : Any
+        End time of the process, typically a timestamp or time object
+    extra : Any, optional
+        Additional descriptive text to include in the output list, by default None
+
+    Returns
+    -------
+    list of str
+        List containing metadata strings with processing information:
+        - Processing date and time
+        - Processing duration
+        - Version and system information
+        - Extra information (if provided)
+        - The original command line
+
+    Notes
+    -----
+    The function uses `time.strftime` to format the start time and calculates
+    the processing duration by subtracting starttime from endtime. It also
+    retrieves version information using `tide_util.version()` and system
+    information using `platform.node()`.
+
+    Examples
+    --------
+    >>> import time
+    >>> args = ['python', 'script.py', '--input', 'data.txt']
+    >>> start = time.time() - 10
+    >>> end = time.time()
+    >>> result = makdcommandlinelist(args, start, end)
+    >>> print(result[0])
+    '# Processed on Mon, 01 Jan 2024 12:00:00 UTC.'
+    """
     # get the processing date
     dateline = (
         "# Processed on "
@@ -166,12 +299,71 @@ def makdcommandlinelist(arglist, starttime, endtime, extra=None):
     commandline = " ".join(arglist)
 
     if extra is not None:
-        return [dateline, timeline, nodeline, "# " + extra, commandline]
+        return dateline, timeline, nodeline, f"# {extra}", commandline
     else:
-        return [dateline, timeline, nodeline, commandline]
-
-
-def calctexticc(args):
+        return dateline, timeline, nodeline, commandline
+
+
+def calctexticc(args: Any) -> None:
+    """
+    Calculate intraclass correlation coefficients (ICC) for text-based measurement data across subjects.
+
+    This function reads measurement lists and corresponding data files, processes the data to
+    compute ICC(3,1) values for each voxel, and writes out the results along with variance components
+    and session effect F-values.
+
+    Parameters
+    ----------
+    args : Any
+        An object containing command-line arguments. Expected attributes include:
+        - datafile : str
+            Comma-separated list of input data file paths.
+        - measurementlist : str
+            Path to the measurement list file.
+        - outputroot : str
+            Root name for output files.
+        - debug : bool, optional
+            Enable debug printing.
+        - deepdebug : bool, optional
+            Enable deep debug printing.
+        - demedian : bool, optional
+            Remove median from each subject's measurements.
+        - demean : bool, optional
+            Remove mean from each subject's measurements.
+        - nocache : bool, optional
+            Disable caching during ICC calculation.
+
+    Returns
+    -------
+    None
+        The function does not return a value but writes multiple output files:
+        - `{outputroot}_ICC.txt`
+        - `{outputroot}_r_var.txt`
+        - `{outputroot}_e_var.txt`
+        - `{outputroot}_session_effect_F.txt`
+        - `{outputroot}_commandline.txt`
+
+    Notes
+    -----
+    The function reshapes data into a voxel-by-subject-by-measurement format and computes ICC(3,1)
+    using a repeated measures ANOVA approach. It supports optional mean/median removal for each
+    subject and measurement.
+
+    Examples
+    --------
+    >>> import argparse
+    >>> args = argparse.Namespace(
+    ...     datafile="data1.txt,data2.txt",
+    ...     measurementlist="meas_list.txt",
+    ...     outputroot="output",
+    ...     debug=False,
+    ...     deepdebug=False,
+    ...     demedian=False,
+    ...     demean=False,
+    ...     nocache=False
+    ... )
+    >>> calctexticc(args)
+    """
     runstarttime = time.time()
 
     datafiles = (args.datafile).split(",")
@@ -297,4 +489,4 @@ def calctexticc(args):
 
     runendtime = time.time()
     thecommandfilelines = makdcommandlinelist(sys.argv, runstarttime, runendtime, extra=extraline)
-    tide_io.writevec(thecommandfilelines, args.outputroot + "_commandline.txt")
+    tide_io.writevec(np.asarray(thecommandfilelines), args.outputroot + "_commandline.txt")

rapidtide/workflows/ccorrica.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
 #
-#   Copyright 2016-2024 Blaise Frederick
+#   Copyright 2016-2025 Blaise Frederick
 #
 #   Licensed under the Apache License, Version 2.0 (the "License");
 #   you may not use this file except in compliance with the License.
@@ -21,9 +21,12 @@ import warnings
 warnings.simplefilter(action="ignore", category=FutureWarning)
 import argparse
 import sys
+from argparse import Namespace
+from typing import Any, Callable, Dict, List, Optional, Tuple, Union
 
 import nibabel as nib
 import numpy as np
+from numpy.typing import NDArray
 from scipy.stats import pearsonr
 
 import rapidtide.correlate as tide_corr
@@ -34,10 +37,33 @@ import rapidtide.resample as tide_resample
 import rapidtide.stats as tide_stats
 import rapidtide.workflows.parser_funcs as pf
 
+DEFAULT_DETREND_ORDER = 3
+DEFAULT_CORRWEIGHTING = "phat"
 
-def _get_parser():
+
+def _get_parser() -> Any:
     """
-    Argument parser for ccorrica
+    Argument parser for ccorrica.
+
+    This function constructs and returns an `argparse.ArgumentParser` object configured
+    with all required and optional arguments for the `ccorrica` tool, which computes
+    temporal cross-correlations between timecourses.
+
+    Returns
+    -------
+    argparse.ArgumentParser
+        Configured argument parser for the ccorrica tool.
+
+    Notes
+    -----
+    The parser includes support for specifying sample rate or timestep, windowing options,
+    search range parameters, filtering, correlation weighting methods, detrending, and
+    oversampling factors. It also supports debugging output.
+
+    Examples
+    --------
+    >>> parser = _get_parser()
+    >>> args = parser.parse_args(['--timecoursefile', 'data.txt', '--outputroot', 'out'])
     """
     parser = argparse.ArgumentParser(
         prog="ccorrica",
@@ -95,15 +121,17 @@ def _get_parser():
         action="store",
         type=str,
         choices=["None", "phat", "liang", "eckart"],
-        help=("Method to use for cross-correlation " "weighting. Default is  None. "),
-        default="None",
+        help=(
+            f"Method to use for cross-correlation weighting. Default is {DEFAULT_CORRWEIGHTING}. "
+        ),
+        default=DEFAULT_CORRWEIGHTING,
     )
     parser.add_argument(
         "--detrendorder",
         dest="detrendorder",
         type=int,
-        help=("Detrending order (default is 1 - linear).  Set to 0 to disable"),
-        default=1,
+        help=(f"Detrending order (default is {DEFAULT_DETREND_ORDER}).  Set to 0 to disable"),
+        default=DEFAULT_DETREND_ORDER,
     )
 
     parser.add_argument(
@@ -116,7 +144,6 @@ def _get_parser():
         ),
         default=1,
     )
-
     parser.add_argument(
         "--debug",
         dest="debug",
@@ -130,7 +157,77 @@ def _get_parser():
     return parser
 
 
-def ccorrica(args):
+def ccorrica(args: Any) -> None:
+    """
+    Compute cross-correlations between time series components and save results in NIfTI and text formats.
+
+    This function reads time course data from a text file, applies preprocessing including
+    filtering, resampling, detrending, and windowing, then computes cross-correlations
+    between all pairs of components. The results are saved as NIfTI files and text vectors
+    for further analysis.
+
+    Parameters
+    ----------
+    args : argparse.Namespace
+        Command-line arguments containing configuration options such as:
+        - timecoursefile : str
+            Path to the input time course file.
+        - samplerate : float or str
+            Sampling rate of the data. If "auto", it must be specified in the file header.
+        - oversampfactor : int
+            Oversampling factor for upsampling the data. If less than 0, it is auto-computed.
+        - detrendorder : int
+            Order of detrending to apply.
+        - windowfunc : str
+            Windowing function to apply.
+        - corrweighting : str
+            Type of weighting to use in correlation computation.
+        - debug : bool
+            If True, display plots during correlation computation.
+        - outputroot : str
+            Root name for output files.
+
+    Returns
+    -------
+    None
+        This function does not return a value but saves multiple output files:
+        - `_filtereddata.txt`: Filtered time series.
+        - `_xcorr.nii.gz`: Cross-correlation data as 4D NIfTI.
+        - `_pxcorr.nii.gz`: Pearson correlation coefficients.
+        - `_corrmax.nii.gz`: Maximum correlation values.
+        - `_corrlag.nii.gz`: Lag at maximum correlation.
+        - `_corrwidth.nii.gz`: Width of the correlation peak.
+        - `_corrmask.nii.gz`: Mask indicating correlation significance.
+        - `_reformdata.txt`: Final reformatted and normalized data.
+
+    Notes
+    -----
+    The function performs the following steps:
+    1. Reads input data from a text file.
+    2. Applies post-processing filter options.
+    3. Resamples data if necessary.
+    4. Filters data using a specified prefilter.
+    5. Normalizes data using standard and correlation normalization.
+    6. Computes cross-correlations using fast FFT-based methods.
+    7. Fits Gaussian peaks to find maximum correlation lag and width.
+    8. Saves symmetric matrices for correlation maxima, lags, widths, and masks.
+    9. Outputs results in both NIfTI and text formats.
+
+    Examples
+    --------
+    >>> import argparse
+    >>> args = argparse.Namespace(
+    ...     timecoursefile='data.txt',
+    ...     samplerate=2.0,
+    ...     oversampfactor=1,
+    ...     detrendorder=1,
+    ...     windowfunc='hanning',
+    ...     corrweighting='none',
+    ...     debug=False,
+    ...     outputroot='output'
+    ... )
+    >>> ccorrica(args)
+    """
     args, theprefilter = pf.postprocessfilteropts(args)
 
     # read in data
@@ -152,8 +249,7 @@ def ccorrica(args):
         else:
             Fs = args.samplerate
     else:
-        if args.samplerate != "auto":
-            Fs = args.samplerate
+        Fs = samplerate
 
     sampletime = 1.0 / Fs
     thedims = tcdata.shape
@@ -169,7 +265,7 @@ def ccorrica(args):
     if args.oversampfactor == 1:
         print("data array shape is ", reformdata.shape)
     else:
-        resampdata = np.zeros((numcomponents, tclen * args.oversampfactor), dtype=np.float)
+        resampdata = np.zeros((numcomponents, tclen * args.oversampfactor), dtype=float)
         for component in range(0, numcomponents):
             resampdata[component, :] = tide_resample.upsample(
                 reformdata[component, :], Fs, Fs * args.oversampfactor, intfac=True
@@ -178,9 +274,19 @@ def ccorrica(args):
         Fs *= args.oversampfactor
         tclen *= args.oversampfactor
 
+    # filter the data
+    for component in range(0, numcomponents):
+        reformdata[component, :] = tide_math.stdnormalize(
+            theprefilter.apply(Fs, reformdata[component, :])
+        )
+
+    # save the filtered timecourses
+    tide_io.writenpvecs(reformdata, args.outputroot + "_filtereddata.txt")
+
+    # now detrend, window, and normalize the data
     for component in range(0, numcomponents):
         reformdata[component, :] = tide_math.corrnormalize(
-            theprefilter.apply(Fs, reformdata[component, :]),
+            reformdata[component, :],
             detrendorder=args.detrendorder,
             windowfunc=args.windowfunc,
         )
@@ -214,9 +320,11 @@ def ccorrica(args):
                 zeropadding=0,
                 displayplots=args.debug,
             )
-            thepxcorr = pearsonr(reformdata[component1, :] / tclen, reformdata[component2, :])
+            thepxcorr = pearsonr(
+                reformdata[component1, :] / tclen, reformdata[component2, :]
+            ).statistic
             outputdata[component1, component2, 0, :] = thexcorr
-            outputpdata[component1, component2, 0, :] = thepxcorr[0]
+            outputpdata[component1, component2, 0, :] = thepxcorr
             (
                 maxindex,
                 maxlag,