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

rapidtide/workflows/roisummarize.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
 #
-#   Copyright 2021-2024 Blaise Frederick
+#   Copyright 2021-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.
@@ -18,17 +18,42 @@
 #
 import argparse
 import sys
+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 roisummarize
+    Argument parser for roisummarize.
+
+    This function constructs and returns an `argparse.ArgumentParser` object configured
+    for parsing command-line arguments used by the `roisummarize` tool. It defines
+    required inputs, optional arguments for sampling frequency, filtering, normalization,
+    and debugging options.
+
+    Returns
+    -------
+    argparse.ArgumentParser
+        Configured argument parser for the roisummarize tool.
+
+    Notes
+    -----
+    The parser supports two mutually exclusive ways to specify sampling frequency:
+    either via `--samplerate` or `--sampletstep`. These are equivalent and both
+    set the same internal `samplerate` parameter.
+
+    Examples
+    --------
+    >>> parser = _get_parser()
+    >>> args = parser.parse_args(['--inputfilename', 'input.txt',
+    ...                           '--templatefile', 'template.nii',
+    ...                           '--outputfile', 'output.txt'])
     """
     parser = argparse.ArgumentParser(
         prog="filttc",
@@ -101,7 +126,50 @@ def _get_parser():
     return parser
 
 
-def summarize4Dbylabel(inputvoxels, templatevoxels, normmethod="z", debug=False):
+def summarize4Dbylabel(
+    inputvoxels: NDArray, templatevoxels: NDArray, normmethod: str = "z", debug: bool = False
+) -> NDArray:
+    """
+    Summarize 4D voxel data by region labels from a template.
+
+    This function extracts time series data for each region defined in a template
+    and computes normalized mean time courses for each region across time points.
+
+    Parameters
+    ----------
+    inputvoxels : NDArray
+        4D array containing voxel data with shape (n_voxels, n_timepoints, n_other_dims)
+    templatevoxels : NDArray
+        3D array containing region labels with shape (n_voxels, 1, 1)
+    normmethod : str, optional
+        Normalization method to apply to time courses, default is "z"
+        Supported methods depend on tide_math.normalize function
+    debug : bool, optional
+        If True, print debugging information including voxel counts and shapes,
+        default is False
+
+    Returns
+    -------
+    timecourses : NDArray
+        2D array of shape (n_regions, n_timepoints) containing normalized mean
+        time courses for each region
+
+    Notes
+    -----
+    - Regions are assumed to be labeled starting from 1
+    - Zero-valued voxels in template are ignored
+    - NaN values are converted to zeros before computing means
+    - The function uses tide_math.normalize for normalization
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> input_data = np.random.rand(100, 50, 1)
+    >>> template = np.random.randint(1, 4, (100, 1, 1))
+    >>> result = summarize4Dbylabel(input_data, template, normmethod="z")
+    >>> print(result.shape)
+    (3, 50)
+    """
     numregions = np.max(templatevoxels)
     numtimepoints = inputvoxels.shape[1]
     timecourses = np.zeros((numregions, numtimepoints), dtype="float")
@@ -111,14 +179,58 @@ def summarize4Dbylabel(inputvoxels, templatevoxels, normmethod="z", debug=False)
         if thevoxels.shape[1] > 0:
             regiontimecourse = np.nan_to_num(np.mean(thevoxels, axis=0))
         else:
-            regiontimecourse = timecourses[0, :] * 0.0
+            regiontimecourse = np.zeros_like(timecourses[0, :])
         if debug:
             print("thevoxels, data shape are:", thevoxels.shape, regiontimecourse.shape)
         timecourses[theregion - 1, :] = tide_math.normalize(regiontimecourse, method=normmethod)
     return timecourses
 
 
-def summarize3Dbylabel(inputvoxels, templatevoxels, debug=False):
+def summarize3Dbylabel(
+    inputvoxels: NDArray, templatevoxels: NDArray, debug: bool = False
+) -> Tuple[NDArray, list]:
+    """
+    Summarize 3D voxel data by label using mean, standard deviation, and median statistics.
+
+    This function processes 3D voxel data by grouping voxels according to labels in a template
+    and computes summary statistics for each labeled region. The input voxels are replaced
+    with the mean value of each region, and statistics are returned for further analysis.
+
+    Parameters
+    ----------
+    inputvoxels : NDArray
+        3D array containing the voxel values to be summarized
+    templatevoxels : NDArray
+        3D array containing integer labels defining regions of interest
+    debug : bool, optional
+        Flag to enable debug output (default is False)
+
+    Returns
+    -------
+    tuple
+        A tuple containing:
+        - outputvoxels : NDArray
+          3D array with each labeled region replaced by its mean value
+        - regionstats : list
+          List of lists containing [mean, std, median] statistics for each region
+
+    Notes
+    -----
+    - Regions are labeled starting from 1 to max(templatevoxels)
+    - NaN values are converted to 0 during statistics calculation
+    - The function modifies the input arrays in-place during processing
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> input_data = np.random.rand(10, 10, 10)
+    >>> template = np.zeros((10, 10, 10), dtype=int)
+    >>> template[2:5, 2:5, 2:5] = 1
+    >>> template[6:8, 6:8, 6:8] = 2
+    >>> result, stats = summarize3Dbylabel(input_data, template)
+    >>> print(f"Region 1 mean: {stats[0][0]:.3f}")
+    >>> print(f"Region 2 mean: {stats[1][0]:.3f}")
+    """
     numregions = np.max(templatevoxels)
     outputvoxels = 0.0 * inputvoxels
     regionstats = []
@@ -132,7 +244,64 @@ def summarize3Dbylabel(inputvoxels, templatevoxels, debug=False):
     return outputvoxels, regionstats
 
 
-def roisummarize(args):
+def roisummarize(args: Any) -> None:
+    """
+    Summarize fMRI data by regions of interest (ROIs) using a template image.
+
+    This function reads input fMRI and template NIfTI files, checks spatial
+    compatibility, and computes either 3D or 4D summaries depending on the
+    number of timepoints in the input data. For 4D data, it applies a filter
+    and summarizes timecourses by ROI. For 3D data, it computes mean values and
+    region statistics.
+
+    Parameters
+    ----------
+    args : Any
+        Command-line arguments parsed by `_get_parser()`. Expected attributes include:
+        - `inputfilename` : str
+            Path to the input fMRI NIfTI file.
+        - `templatefile` : str
+            Path to the template NIfTI file defining ROIs.
+        - `samplerate` : str or float
+            Sampling rate for filtering. If "auto", defaults to 1.0.
+        - `numskip` : int
+            Number of initial timepoints to skip when summarizing 4D data.
+        - `normmethod` : str
+            Normalization method for 4D summarization.
+        - `debug` : bool
+            Enable debug mode for additional output.
+        - `outputfile` : str
+            Base name for output files.
+
+    Returns
+    -------
+    None
+        The function writes output files to disk:
+        - `<outputfile>_timecourses`: Timecourses for each ROI (4D case).
+        - `<outputfile>_meanvals`: Mean values per ROI (3D case).
+        - `<outputfile>_regionstats.txt`: Statistics for each ROI (3D case).
+
+    Notes
+    -----
+    - The function assumes that the template file defines ROIs with integer labels.
+    - For 4D data, the input is filtered using `pf.postprocessfilteropts`.
+    - If the spatial dimensions of the input and template files do not match,
+      the function exits with an error message.
+
+    Examples
+    --------
+    >>> import argparse
+    >>> args = argparse.Namespace(
+    ...     inputfilename='fmri.nii',
+    ...     templatefile='roi_template.nii',
+    ...     samplerate='auto',
+    ...     numskip=5,
+    ...     normmethod='zscore',
+    ...     debug=False,
+    ...     outputfile='output'
+    ... )
+    >>> roisummarize(args)
+    """
     # grab the command line arguments then pass them off.
     try:
         args = _get_parser().parse_args()

rapidtide/workflows/runqualitycheck.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
 #
-#   Copyright 2024-2024 Blaise Frederick
+#   Copyright 2024-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.
@@ -17,17 +17,41 @@
 #
 #
 import argparse
-
-import matplotlib as mpl
-import numpy as np
+from argparse import Namespace
+from typing import Any, Callable, Dict, List, Optional, Tuple, Union
 
 import rapidtide.io as tide_io
 import rapidtide.qualitycheck as tide_quality
 
 
-def _get_parser():
+def _get_parser() -> Any:
     """
-    Argument parser for runqualitycheck
+    Argument parser for runqualitycheck.
+
+    This function creates and configures an argument parser for the runqualitycheck
+    command-line tool. The parser handles both required and optional arguments needed
+    to perform quality checks on rapidtide datasets.
+
+    Returns
+    -------
+    argparse.ArgumentParser
+        Configured argument parser object with all required and optional arguments
+        for the runqualitycheck tool.
+
+    Notes
+    -----
+    The argument parser is configured with:
+    - Required input file root name
+    - Optional gray matter mask specification
+    - Optional white matter mask specification
+    - Debug flag for additional output
+
+    Examples
+    --------
+    >>> parser = _get_parser()
+    >>> args = parser.parse_args(['dataset_root'])
+    >>> print(args.inputfileroot)
+    'dataset_root'
     """
     parser = argparse.ArgumentParser(
         prog="runqualitycheck",
@@ -69,7 +93,48 @@ def _get_parser():
     return parser
 
 
-def runqualitycheck(args):
+def runqualitycheck(args: Any) -> None:
+    """
+    Run quality check on input data and write results to JSON file.
+
+    This function performs a quality check on the input data using the tide_quality
+    module and writes the results to a JSON file with a standardized naming convention.
+
+    Parameters
+    ----------
+    args : Any
+        An object containing input arguments with the following attributes:
+        - inputfileroot : str
+            Root name of the input file(s)
+        - graymaskspec : str, optional
+            Specification for gray matter masking
+        - whitemaskspec : str, optional
+            Specification for white matter masking
+        - debug : bool, optional
+            Flag to enable debug mode
+
+    Returns
+    -------
+    None
+        This function does not return any value but writes results to a JSON file.
+
+    Notes
+    -----
+    The output JSON file will be named as '{inputfileroot}_desc-qualitymetrics_info.json'
+    where inputfileroot is the root name provided in the args object.
+
+    Examples
+    --------
+    >>> class Args:
+    ...     def __init__(self):
+    ...         self.inputfileroot = "sub-01_task-rest"
+    ...         self.graymaskspec = "gray_mask.nii.gz"
+    ...         self.whitemaskspec = "white_mask.nii.gz"
+    ...         self.debug = False
+    ...
+    >>> args = Args()
+    >>> runqualitycheck(args)
+    """
     resultsdict = tide_quality.qualitycheck(
         args.inputfileroot,
         graymaskspec=args.graymaskspec,

rapidtide/workflows/showarbcorr.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.
@@ -18,20 +18,48 @@
 #
 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
 from scipy.stats import pearsonr
 
 import rapidtide.correlate as tide_corr
-import rapidtide.helper_classes as tide_classes
 import rapidtide.io as tide_io
 import rapidtide.miscmath as tide_math
+import rapidtide.simFuncClasses as tide_simFuncClasses
 import rapidtide.workflows.parser_funcs as pf
 
 
-def _get_parser():
+def _get_parser() -> Any:
     """
-    Argument parser for showarbcorr
+    Argument parser for showarbcorr.
+
+    This function constructs and returns an `argparse.ArgumentParser` object configured
+    for the `showarbcorr` command-line tool. It defines required and optional arguments
+    for calculating and displaying crosscorrelation between two time series, supporting
+    variable lengths and sampling frequencies.
+
+    Returns
+    -------
+    argparse.ArgumentParser
+        Configured argument parser for `showarbcorr`.
+
+    Notes
+    -----
+    The parser includes groups for:
+    - Required input files
+    - Optional arguments (e.g., sample rates, display control)
+    - Preprocessing options (e.g., detrending, correlation weighting)
+    - Filtering and windowing options
+    - Output configuration (e.g., files for results, plots)
+    - Miscellaneous settings (e.g., multiprocessing, progress bar)
+
+    Examples
+    --------
+    >>> parser = _get_parser()
+    >>> args = parser.parse_args()
     """
     parser = argparse.ArgumentParser(
         prog="showarbcorr",
@@ -240,13 +268,128 @@ def _get_parser():
     return parser
 
 
-def printthresholds(pcts, thepercentiles, labeltext):
+def printthresholds(pcts: Any, thepercentiles: Any, labeltext: Any) -> None:
+    """
+    Print thresholds with corresponding percentile labels.
+
+    This function prints a formatted list of thresholds along with their
+    corresponding percentile labels for statistical analysis output.
+
+    Parameters
+    ----------
+    pcts : Any
+        Array or list of threshold values to be printed.
+    thepercentiles : Any
+        Array or list of percentile values corresponding to the thresholds.
+    labeltext : Any
+        Text label to be printed before the threshold list.
+
+    Returns
+    -------
+    None
+        This function prints to standard output and does not return any value.
+
+    Notes
+    -----
+    The function formats the percentile values as "1.0 - thepercentiles[i]"
+    to show the alpha level (significance threshold) for each percentile.
+
+    Examples
+    --------
+    >>> pcts = [0.05, 0.01, 0.001]
+    >>> thepercentiles = [0.95, 0.99, 0.999]
+    >>> labeltext = "Critical Values:"
+    >>> printthresholds(pcts, thepercentiles, labeltext)
+    Critical Values:
+        p < 0.050 : 0.05
+        p < 0.010 : 0.01
+        p < 0.001 : 0.001
+    """
     print(labeltext)
     for i in range(0, len(pcts)):
         print("\tp <", "{:.3f}".format(1.0 - thepercentiles[i]), ": ", pcts[i])
 
 
-def showarbcorr(args):
+def showarbcorr(args: Any) -> None:
+    """
+    Compute and display cross-correlation between two time series with optional filtering and plotting.
+
+    This function reads two time series from text files, matches their sampling rates, applies
+    optional filtering, and computes the cross-correlation. It supports various options for
+    data trimming, inversion, and output formatting, including optional visualization and
+    correlation fitting.
+
+    Parameters
+    ----------
+    args : Any
+        An object containing command-line arguments and configuration options. Expected
+        attributes include:
+        - infilename1, infilename2 : str
+            Paths to input text files containing the two time series.
+        - samplerate1, samplerate2 : float, optional
+            Sampling rates for the two time series. If not provided, they are inferred
+            from the input files.
+        - start1, start2 : float, optional
+            Start times for the two time series.
+        - trimdata : bool
+            If True, trim the data to the shorter of the two time series.
+        - invert : bool
+            If True, invert the second time series before correlation.
+        - windowfunc : str, optional
+            Window function to apply during correlation normalization.
+        - detrendorder : int, optional
+            Order of detrending to apply before correlation.
+        - display : bool
+            If True, display the cross-correlation plot.
+        - graphfile : str, optional
+            Output filename for saving the plot.
+        - label : str, optional
+            Label to use in output.
+        - lagmin, lagmax : float
+            Minimum and maximum lags (in seconds) to consider in the correlation.
+        - debug : bool
+            If True, enable debug output.
+        - bipolar : bool
+            If True, fit the peak using bipolar symmetry.
+        - summarymode : bool
+            If True, output results in a tab-separated summary format.
+        - outputfile : str, optional
+            File to write summary output.
+        - corroutputfile : str, optional
+            File to write full cross-correlation data.
+        - verbose : bool
+            If True, print verbose messages.
+
+    Returns
+    -------
+    None
+        This function does not return a value but may produce plots, print outputs,
+        and write files depending on the provided arguments.
+
+    Notes
+    -----
+    - The function uses `tide_io.readvectorsfromtextfile` to read input data.
+    - Filtering is applied via `tide_math.corrnormalize` and `theprefilter.apply`.
+    - Cross-correlation is computed using `tide_corr.arbcorr`.
+    - A peak-fitting procedure is used to refine the maximum correlation lag.
+    - If `summarymode` is True, output is written in tab-separated format to stdout or a file.
+
+    Examples
+    --------
+    >>> import argparse
+    >>> args = argparse.Namespace(
+    ...     infilename1="data1.txt",
+    ...     infilename2="data2.txt",
+    ...     samplerate1=10.0,
+    ...     samplerate2=10.0,
+    ...     display=True,
+    ...     lagmin=-5.0,
+    ...     lagmax=5.0,
+    ...     windowfunc="hanning",
+    ...     debug=False
+    ... )
+    >>> showarbcorr(args)
+    """
     # set some default values
     absmaxsigma = 1000.0
     absminsigma = 0.25
@@ -297,6 +440,8 @@ def showarbcorr(args):
         sys.exit()
     if starttime1 == None:
         starttime1 = 0.0
+    endtime1 = starttime1 + len(inputdata1) / Fs1
+    print(f"inputdata1 goes from {starttime1} to {endtime1}")
 
     if args.samplerate2 is not None:
         Fs2 = args.samplerate2
@@ -305,9 +450,19 @@ def showarbcorr(args):
         sys.exit()
     if starttime2 == None:
         starttime2 = 0.0
+    endtime2 = starttime2 + len(inputdata2) / Fs2
+    print(f"inputdata2 goes from {starttime2} to {endtime2}")
 
-    trimdata1 = inputdata1
-    trimdata2 = inputdata2
+    matchedinput1, matchedinput2, commonFs = tide_corr.matchsamplerates(
+        inputdata1,
+        Fs1,
+        inputdata2,
+        Fs2,
+        method="univariate",
+        debug=args.debug,
+    )
+    trimdata1 = matchedinput1
+    trimdata2 = matchedinput2
 
     if args.trimdata:
         minlen = np.min([len(trimdata1), len(trimdata2)])
@@ -324,12 +479,12 @@ def showarbcorr(args):
         if args.verbose:
             print("filtering to ", theprefilter.gettype(), " band")
     filtereddata1 = tide_math.corrnormalize(
-        theprefilter.apply(Fs1, trimdata1),
+        theprefilter.apply(commonFs, trimdata1),
         detrendorder=args.detrendorder,
         windowfunc=args.windowfunc,
     )
     filtereddata2 = tide_math.corrnormalize(
-        theprefilter.apply(Fs2, trimdata2),
+        theprefilter.apply(commonFs, trimdata2),
         detrendorder=args.detrendorder,
         windowfunc=args.windowfunc,
     )
@@ -341,9 +496,9 @@ def showarbcorr(args):
         print(f"{Fs1=}, {Fs2=}, {starttime1=}, {starttime2=}, {args.windowfunc=}")
     xcorr_x, thexcorr, corrFs, zeroloc = tide_corr.arbcorr(
         filtereddata1,
-        Fs1,
+        commonFs,
         filtereddata2,
-        Fs2,
+        commonFs,
         start1=starttime1,
         start2=starttime2,
         windowfunc=args.windowfunc,
@@ -375,10 +530,11 @@ def showarbcorr(args):
     thexcorr_trim = thexcorr[lowerlim:upperlim]
     print("trimmed Correlator lengths (x, y):", len(xcorr_x_trim), len(thexcorr_trim))
 
-    thepxcorr = pearsonr(filtereddata1, filtereddata2)
+    print(f"{len(filtereddata1)=}, {len(filtereddata2)=}")
+    thepxcorr = pearsonr(filtereddata1, filtereddata2).statistic
 
-    # intitialize the correlation fitter
-    thexsimfuncfitter = tide_classes.SimilarityFunctionFitter(
+    # initialize the correlation fitter
+    thexsimfuncfitter = tide_simFuncClasses.SimilarityFunctionFitter(
         corrtimeaxis=xcorr_x,
         lagmin=args.lagmin,
         lagmax=args.lagmax,
@@ -441,7 +597,7 @@ def showarbcorr(args):
     else:
         # report the pearson correlation
         if showpearson:
-            print("Pearson_R:\t", thepxcorr[0])
+            print("Pearson_R:\t", thepxcorr)
             print("")
         if args.label is not None:
             print(args.label, ":\t", -maxdelay)