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

rapidtide/workflows/showarbcorr.py

@@ -18,8 +18,11 @@
 #
 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
@@ -29,9 +32,34 @@ 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

rapidtide/workflows/showhist.py

@@ -17,15 +17,44 @@
 #
 #
 import argparse
+from argparse import Namespace
+from typing import Any, Callable, Dict, List, Optional, Tuple, Union
 
 import numpy as np
 from matplotlib.pyplot import bar, legend, plot, savefig, show, title, xlabel, ylabel
+from numpy.typing import NDArray
 
 import rapidtide.io as tide_io
 import rapidtide.stats as tide_stats
 
 
-def _get_parser():
+def _get_parser() -> Any:
+    """
+    Create and configure an argument parser for the showhist command-line tool.
+
+    This function sets up an `argparse.ArgumentParser` with specific arguments
+    to control the behavior of the histogram plotting script. It defines
+    required and optional parameters for input file, axis labels, title,
+    output file, plot style, and debugging options.
+
+    Returns
+    -------
+    argparse.ArgumentParser
+        Configured argument parser object with defined arguments for
+        controlling histogram plotting behavior.
+
+    Notes
+    -----
+    The parser is configured with `allow_abbrev=False` to prevent
+    abbreviated argument names from being accepted.
+
+    Examples
+    --------
+    >>> parser = _get_parser()
+    >>> args = parser.parse_args(['data.txt'])
+    >>> print(args.infilename)
+    'data.txt'
+    """
     # get the command line parameters
     parser = argparse.ArgumentParser(
         prog="showhist",
@@ -90,7 +119,62 @@ def _get_parser():
     return parser
 
 
-def showhist(args):
+def showhist(args: Any) -> None:
+    """
+    Display or save a histogram or line plot based on input data and arguments.
+
+    This function reads data from a specified input file, computes a histogram if
+    requested, and visualizes the results using matplotlib. The plot can be displayed
+    on screen or saved to a file depending on the provided arguments.
+
+    Parameters
+    ----------
+    args : Any
+        An object containing the following attributes:
+        - infilename : str
+            Path to the input file containing data to be plotted.
+        - debug : bool
+            If True, prints the args object for debugging purposes.
+        - calcdist : bool
+            If True, computes a histogram from the input data.
+        - dobars : bool
+            If True, displays the histogram as bars; otherwise, as a line plot.
+        - thetitle : str, optional
+            Title for the plot.
+        - thexlabel : str, optional
+            Label for the x-axis.
+        - theylabel : str, optional
+            Label for the y-axis.
+        - outputfile : str, optional
+            Path to save the plot. If None, the plot is displayed on screen.
+
+    Returns
+    -------
+    None
+        This function does not return any value. It either displays the plot
+        or saves it to a file.
+
+    Notes
+    -----
+    - The function uses `tide_io.readvecs` to read input data.
+    - If `calcdist` is True, `tide_stats.makehistogram` is used to compute the histogram.
+    - The histogram is displayed as either bars or a line, depending on the `dobars` flag.
+    - If `outputfile` is provided, the plot is saved using `savefig`; otherwise, `show()` is called.
+
+    Examples
+    --------
+    >>> args = type('Args', (), {
+    ...     'infilename': 'data.txt',
+    ...     'debug': False,
+    ...     'calcdist': True,
+    ...     'dobars': True,
+    ...     'thetitle': 'Sample Histogram',
+    ...     'thexlabel': 'Values',
+    ...     'theylabel': 'Frequency',
+    ...     'outputfile': 'output.png'
+    ... })()
+    >>> showhist(args)
+    """
     if args.debug:
         print(args)
     if args.calcdist:

rapidtide/workflows/showstxcorr.py

@@ -18,11 +18,14 @@
 #
 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
 import pandas as pd
 from numpy.polynomial import Polynomial
+from numpy.typing import NDArray
 
 import rapidtide.correlate as tide_corr
 import rapidtide.fit as tide_fit
@@ -32,7 +35,36 @@ import rapidtide.resample as tide_resamp
 import rapidtide.workflows.parser_funcs as pf
 
 
-def _get_parser():
+def _get_parser() -> Any:
+    """
+    Create and configure an argument parser for the showstxcorr tool.
+
+    This function sets up an `argparse.ArgumentParser` with various required and
+    optional arguments to control the behavior of the cross-correlation plotting
+    tool. It includes options for input files, sampling parameters, correlation
+    settings, display control, and preprocessing steps.
+
+    Returns
+    -------
+    argparse.ArgumentParser
+        Configured argument parser object with all necessary arguments added.
+
+    Notes
+    -----
+    The parser is configured with:
+    - Two required input text files (`infilename1`, `infilename2`)
+    - Output filename root
+    - Sampling rate or time step options (mutually exclusive)
+    - Correlation threshold and window parameters
+    - Time range and display options
+    - Preprocessing options like detrending and correlation weighting
+    - Filtering and windowing options
+
+    Examples
+    --------
+    >>> parser = _get_parser()
+    >>> args = parser.parse_args()
+    """
     parser = argparse.ArgumentParser(
         prog="showstxcorr",
         description="Plots the data in text files.",
@@ -187,13 +219,138 @@ def _get_parser():
     return parser
 
 
-def printthresholds(pcts, thepercentiles, labeltext):
+def printthresholds(pcts: Any, thepercentiles: Any, labeltext: Any) -> None:
+    """
+    Print thresholds with corresponding percentile values.
+
+    This function prints a formatted list of thresholds where each threshold
+    corresponds to a specific percentile. The output shows the probability
+    threshold for which the percentile is less than the given value.
+
+    Parameters
+    ----------
+    pcts : Any
+        Array-like object containing the percentile values to be printed.
+    thepercentiles : Any
+        Array-like object containing the corresponding percentile thresholds.
+    labeltext : Any
+        Text label to be printed before the threshold values.
+
+    Returns
+    -------
+    None
+        This function prints to stdout and does not return any value.
+
+    Notes
+    -----
+    The function assumes that both `pcts` and `thepercentiles` have the same length
+    and that the percentiles are ordered in ascending order.
+
+    Examples
+    --------
+    >>> pcts = [0.05, 0.01, 0.001]
+    >>> thepercentiles = [0.95, 0.99, 0.999]
+    >>> labeltext = "Significance thresholds:"
+    >>> printthresholds(pcts, thepercentiles, labeltext)
+    Significance thresholds:
+            p < 0.05 :  0.05
+            p < 0.01 :  0.01
+            p < 0.001 :  0.001
+    """
     print(labeltext)
     for i in range(0, len(pcts)):
         print("\tp <", 1.0 - thepercentiles[i], ": ", pcts[i])
 
 
-def showstxcorr(args):
+def showstxcorr(args: Any) -> None:
+    """
+    Compute and display short-term cross-correlations between two time series.
+
+    This function performs short-term cross-correlation analysis on two input time series,
+    applying optional filtering, detrending, and time-warping. It supports both single
+    correlation output and matrix output modes, and can generate plots and save results
+    to files.
+
+    Parameters
+    ----------
+    args : argparse.Namespace
+        Command-line arguments containing the following attributes:
+        - infilename1 : str
+            Path to the first input file.
+        - infilename2 : str
+            Path to the second input file.
+        - samplerate : float or str
+            Sampling rate of the data. Must be set if 'auto'.
+        - starttime : float
+            Start time for data trimming.
+        - duration : float
+            Duration of the data to process.
+        - stepsize : float
+            Step size for correlation computation.
+        - windowwidth : float
+            Width of the analysis window in seconds.
+        - lagmin : float
+            Minimum lag for correlation search.
+        - lagmax : float
+            Maximum lag for correlation search.
+        - corrweighting : str
+            Type of weighting for correlation.
+        - windowfunc : str
+            Window function to apply.
+        - detrendorder : int
+            Order of detrending to apply.
+        - invert : bool
+            Whether to invert the second signal.
+        - display : bool
+            Whether to display plots.
+        - debug : bool
+            Whether to enable debug output.
+        - outfilename : str
+            Base name for output files.
+        - corrthresh : float
+            Threshold for correlation significance.
+        - filter : dict
+            Filter parameters.
+
+    Returns
+    -------
+    None
+        This function does not return a value but saves output files and displays plots
+        if requested.
+
+    Notes
+    -----
+    The function applies a prefilter to the data and trims the input time series to
+    the specified duration. It supports both single correlation and matrix correlation
+    modes. In matrix mode, all components are correlated against each other and
+    results are saved to NIfTI files and CSV tables. In single mode, correlations are
+    computed between two time series and results are saved to text files.
+
+    Examples
+    --------
+    >>> import argparse
+    >>> args = argparse.Namespace(
+    ...     infilename1='data1.txt',
+    ...     infilename2='data2.txt',
+    ...     samplerate=100,
+    ...     starttime=0,
+    ...     duration=1000,
+    ...     stepsize=10,
+    ...     windowwidth=20,
+    ...     lagmin=-5,
+    ...     lagmax=5,
+    ...     corrweighting='uniform',
+    ...     windowfunc='hanning',
+    ...     detrendorder=1,
+    ...     invert=False,
+    ...     display=False,
+    ...     debug=False,
+    ...     outfilename='output',
+    ...     corrthresh=0.3,
+    ...     filter={}
+    ... )
+    >>> showstxcorr(args)
+    """
     # get the command line parameters
     verbose = True
     matrixoutput = False

rapidtide/workflows/showtc.py

@@ -21,10 +21,12 @@ import warnings
 warnings.simplefilter(action="ignore", category=FutureWarning)
 import argparse
 import sys
+from argparse import Namespace
 
 import matplotlib.cm as cm
 import numpy as np
 from matplotlib.pyplot import figure, savefig, setp, show
+from numpy.typing import NDArray
 
 import rapidtide.filter as tide_filt
 import rapidtide.fit as tide_fit
@@ -41,11 +43,79 @@ except ImportError:
     haveseaborn = False
 
 
-def phase(mcv):
+def phase(mcv: NDArray[np.complex128]) -> NDArray[np.float64]:
+    """
+    Compute the phase angle of complex numbers.
+
+    This function calculates the phase angle (also known as the argument) of complex numbers
+    using the arctan2 function, which correctly handles all quadrants and avoids division
+    by zero errors that could occur with the standard arctan function.
+
+    Parameters
+    ----------
+    mcv : ndarray of complex128
+        Input array of complex numbers for which to compute the phase angles.
+
+    Returns
+    -------
+    ndarray of float64
+        Array of phase angles in radians, with values in the range [-π, π].
+        The phase angle is computed as atan2(imaginary_part, real_part).
+
+    Notes
+    -----
+    The phase angle is computed using `np.arctan2(mcv.imag, mcv.real)` which correctly
+    handles the quadrant determination and avoids ambiguity that would occur with
+    `np.arctan(mcv.imag / mcv.real)`.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> z = np.array([1+0j, 0+1j, -1+0j, 0-1j])
+    >>> phase(z)
+    array([ 0.        ,  1.57079633,  3.14159265, -1.57079633])
+
+    >>> z = np.array([1+1j, -1+1j, -1-1j, 1-1j])
+    >>> phase(z)
+    array([ 0.78539816,  2.35619449, -2.35619449, -0.78539816])
+    """
     return np.arctan2(mcv.imag, mcv.real)
 
 
-def _get_parser():
+def _get_parser() -> argparse.ArgumentParser:
+    """
+    Create and configure an argument parser for the showtc command-line tool.
+
+    This function constructs an `argparse.ArgumentParser` object with a set of
+    predefined arguments for plotting data from text files. It supports various
+    display modes, sampling options, and plotting configurations.
+
+    Returns
+    -------
+    argparse.ArgumentParser
+        Configured argument parser for the showtc tool.
+
+    Notes
+    -----
+    The parser includes support for:
+
+    - Input file specification with optional column selections
+    - Sampling rate or sample time configuration
+    - Display mode options: time series, power spectrum, or phase spectrum
+    - Plot format options: overlaid, separate, or separately linked
+    - Waterfall plotting for multiple timecourses
+    - Data normalization and transposition
+    - Plot appearance customization via `pf.addplotopts`
+    - Time range selection and header skipping
+    - Debugging and version information
+
+    Examples
+    --------
+    >>> parser = _get_parser()
+    >>> args = parser.parse_args(['file1.txt', 'file2.txt'])
+    >>> print(args.textfilenames)
+    ['file1.txt', 'file2.txt']
+    """
     parser = argparse.ArgumentParser(
         prog="showtc",
         description="Plots the data in text files.",
@@ -186,7 +256,93 @@ def _get_parser():
     return parser
 
 
-def showtc(args):
+def showtc(args: Namespace) -> None:
+    """
+    Display time series or spectral data from text files with customizable plotting options.
+
+    This function reads time series data from one or more text files and plots it
+    in either time domain or frequency domain (power or phase). It supports various
+    display modes, plot formatting options, and customization of colors, legends,
+    and axis labels.
+
+    Parameters
+    ----------
+    args : argparse.Namespace
+        A namespace object containing the following attributes:
+        - samplerate : float or str
+            Sampling rate of the data. If "auto", defaults to 1.0.
+        - displaymode : str
+            Display mode: "time", "power", or "phase".
+        - plotformat : str
+            Plot formatting: "overlaid", "separate", or "separatelinked".
+        - colors : str, optional
+            Comma-separated list of color names for the lines.
+        - legends : str, optional
+            Comma-separated list of legend labels.
+        - dolegend : bool
+            Whether to display legends.
+        - linewidths : str, optional
+            Comma-separated list of line widths.
+        - legendloc : int
+            Legend location (0-10).
+        - thestarttime : float, optional
+            Start time for data selection.
+        - theendtime : float, optional
+            End time for data selection.
+        - textfilenames : list of str
+            List of text file names to read data from.
+        - dotranspose : bool
+            Whether to transpose the input data.
+        - normall : bool
+            Whether to normalize all data.
+        - fullxrange : bool
+            Whether to use full x-axis range.
+        - voffset : float
+            Vertical offset for overlaid plots.
+        - dowaterfall : bool
+            Whether to create a waterfall plot.
+        - fontscalefac : float
+            Font scaling factor.
+        - thetitle : str, optional
+            Title for the plot.
+        - xlabel : str, optional
+            X-axis label.
+        - ylabel : str, optional
+            Y-axis label.
+        - showxax : bool
+            Whether to show x-axis labels.
+        - showyax : bool
+            Whether to show y-axis labels.
+        - outputfile : str, optional
+            Output file name for saving the plot.
+        - saveres : int
+            Resolution for saved plots.
+        - debug : bool
+            Whether to print debug information.
+
+    Returns
+    -------
+    None
+        This function does not return a value but displays or saves the plot.
+
+    Notes
+    -----
+    - The function handles multiple input files and concatenates data.
+    - Spectral data is computed using Hamming windowing by default.
+    - Time series data is plotted with time on x-axis and values on y-axis.
+    - Spectral data is plotted with frequency on x-axis and either power or phase on y-axis.
+    - The function supports automatic detection of file types and column specifications.
+
+    Examples
+    --------
+    >>> import argparse
+    >>> args = argparse.Namespace()
+    >>> args.samplerate = 1.0
+    >>> args.displaymode = "time"
+    >>> args.plotformat = "separate"
+    >>> args.textfilenames = ["data1.txt", "data2.txt"]
+    >>> showtc(args)
+    """
     # set the sample rate
     if args.samplerate == "auto":
         samplerate = 1.0