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

rapidtide/workflows/showxcorrx.py

@@ -18,10 +18,13 @@
 #
 import argparse
 import sys
+from argparse import Namespace
+from typing import Any, Callable, Dict, List, Optional, Tuple, Union
 
 import matplotlib.cm as cm
 import numpy as np
 import scipy as sp
+from numpy.typing import NDArray
 from scipy.signal import correlate
 from scipy.stats import pearsonr
 
@@ -40,9 +43,31 @@ DEFAULT_SIGMAMAX = 1000.0
 DEFAULT_SIGMAMIN = 0.25
 
 
-def _get_parser():
+def _get_parser() -> Any:
     """
-    Argument parser for showxcorrx
+    Argument parser for showxcorrx.
+
+    This function constructs and returns an `argparse.ArgumentParser` object configured
+    to handle command-line arguments for the `showxcorrx` utility. It supports a wide
+    range of options for loading time series data, preprocessing, cross-correlation
+    computation, and output formatting.
+
+    Returns
+    -------
+    argparse.ArgumentParser
+        Configured argument parser for `showxcorrx`.
+
+    Notes
+    -----
+    The parser includes groups for general options, preprocessing, similarity function
+    options, output settings, and debugging. It supports optional arguments such as
+    sample rate specification, data filtering, detrending, correlation weighting,
+    and plotting controls.
+
+    Examples
+    --------
+    >>> parser = _get_parser()
+    >>> args = parser.parse_args()
     """
     parser = argparse.ArgumentParser(
         prog="showxcorrx",
@@ -317,13 +342,168 @@ def _get_parser():
     return parser
 
 
-def printthresholds(pcts, thepercentiles, labeltext):
+def printthresholds(pcts: Any, thepercentiles: Any, labeltext: Any) -> None:
+    """
+    Print thresholds with corresponding percentiles.
+
+    This function prints a formatted list of thresholds along with their
+    corresponding percentile values for statistical analysis reporting.
+
+    Parameters
+    ----------
+    pcts : Any
+        Array or list of percentile values to be printed
+    thepercentiles : Any
+        Array or list of percentile thresholds (typically between 0 and 1)
+    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 formats the output to show "p < threshold: value" format
+    where the threshold is calculated as 1.0 - thepercentiles[i].
+
+    Examples
+    --------
+    >>> printthresholds([0.05, 0.01], [0.95, 0.99], "Significance Levels:")
+    Significance Levels:
+        p < 0.050 : 0.05
+        p < 0.010 : 0.01
+    """
     print(labeltext)
     for i in range(0, len(pcts)):
         print("\tp <", "{:.3f}".format(1.0 - thepercentiles[i]), ": ", pcts[i])
 
 
-def showxcorrx(args):
+def showxcorrx(args: Any) -> None:
+    """
+    Compute and display cross-correlation or mutual information between two time series.
+
+    This function performs cross-correlation or mutual information analysis between two
+    time series, with optional filtering, normalization, and statistical significance
+    testing. It supports various similarity metrics and can output results to files or
+    display plots.
+
+    Parameters
+    ----------
+    args : argparse.Namespace
+        Command-line arguments containing parameters for the analysis. Expected attributes include:
+        - infilename1, infilename2 : str
+            File names for the two time series.
+        - display : bool
+            Whether to display plots.
+        - samplerate : float or str
+            Sampling rate of the time series. If "auto", defaults to 1.0 Hz.
+        - startpoint, endpoint : float
+            Time range to analyze.
+        - trimdata : bool
+            Whether to trim data to the shortest length.
+        - invert : bool
+            Whether to invert the second time series.
+        - theprefilter : object
+            Filter object for preprocessing data.
+        - detrendorder : int
+            Order of detrending for correlation normalization.
+        - windowfunc : str
+            Window function for correlation normalization.
+        - corrweighting : str
+            Weighting method for correlation.
+        - zeropadding : int
+            Zero padding for correlation.
+        - smoothingtime : float
+            Smoothing time for mutual information calculation.
+        - minorm : bool
+            Whether to normalize mutual information.
+        - similaritymetric : str
+            Similarity metric to use ("correlation", "mutualinfo", "hybrid").
+        - lagmin, lagmax : float
+            Minimum and maximum lag for analysis.
+        - absmaxsigma, absminsigma : float
+            Sigma thresholds for peak fitting.
+        - cepstral : bool
+            Whether to compute cepstral delay.
+        - calccoherence : bool
+            Whether to compute coherence.
+        - calccsd : bool
+            Whether to compute cross-spectral density.
+        - numestreps : int
+            Number of bootstrap replicates for significance testing.
+        - showprogressbar : bool
+            Whether to show progress bar during bootstrap.
+        - permutationmethod : str
+            Permutation method for bootstrap.
+        - nprocs : int
+            Number of processes for parallel computation.
+        - summarymode : bool
+            Whether to output in summary format.
+        - resoutputfile : str
+            Output file for results.
+        - label : str
+            Label for output.
+        - labelline : bool
+            Whether to include label in output.
+        - colors : str
+            Comma-separated list of colors for plots.
+        - linewidths : str
+            Comma-separated list of line widths for plots.
+        - legendloc : int
+            Legend location for plots.
+        - legends : str
+            Legend labels for plots.
+        - dolegend : bool
+            Whether to display legend.
+        - thetitle : str
+            Title for plots.
+        - showxax, showyax : bool
+            Whether to show x and y axes.
+        - xlabel, ylabel : str
+            Axis labels.
+        - outputfile : str
+            Output file for plot.
+        - saveres : int
+            Resolution for saved plots.
+        - corroutputfile : str
+            Output file for correlation data.
+        - debug : bool
+            Whether to print debug information.
+        - verbose : bool
+            Whether to print verbose output.
+        - fontscalefac : float
+            Font scaling factor for plots.
+
+    Returns
+    -------
+    None
+        This function does not return a value but may display plots or write output files.
+
+    Notes
+    -----
+    The function supports multiple similarity metrics:
+    - "correlation": Pearson correlation coefficient
+    - "mutualinfo": Mutual information
+    - "hybrid": Combination of both metrics
+
+    Examples
+    --------
+    >>> import argparse
+    >>> args = argparse.Namespace(
+    ...     infilename1='data1.txt',
+    ...     infilename2='data2.txt',
+    ...     display=True,
+    ...     samplerate=1.0,
+    ...     startpoint=0,
+    ...     endpoint=100,
+    ...     similaritymetric='correlation',
+    ...     lagmin=-10,
+    ...     lagmax=10
+    ... )
+    >>> showxcorrx(args)
+    """
     # set some default values
     zerooutbadfit = False
     peakfittype = "gauss"

rapidtide/workflows/showxy.py

@@ -18,6 +18,8 @@
 #
 import argparse
 import sys
+from argparse import Namespace
+from typing import Any, Callable, Dict, List, Optional, Tuple, Union
 
 import matplotlib.cm as cm
 import numpy as np
@@ -36,12 +38,38 @@ from matplotlib.pyplot import (
     ylabel,
     ylim,
 )
+from numpy.typing import NDArray
 from scipy.stats import linregress
 
 import rapidtide.io as tide_io
 
 
-def _get_parser():
+def _get_parser() -> Any:
+    """
+    Create and configure an argument parser for plotting xy data from text files.
+
+    This function sets up an `argparse.ArgumentParser` with a variety of options to
+    control how xy data is read from text files and plotted. It supports features such as
+    axis labels, range limits, title, output file saving, font scaling, legend handling,
+    color specification, and special plot types like Bland-Altman.
+
+    Returns
+    -------
+    argparse.ArgumentParser
+        Configured argument parser object ready to parse command-line arguments.
+
+    Notes
+    -----
+    The parser expects one or more text file names as positional arguments. Each file
+    should contain whitespace-separated x and y data, one point per line.
+
+    Examples
+    --------
+    >>> parser = _get_parser()
+    >>> args = parser.parse_args(['data.txt'])
+    >>> print(args.textfilenames)
+    ['data.txt']
+    """
     # get the command line parameters
     parser = argparse.ArgumentParser(
         prog="showxy",
@@ -202,18 +230,71 @@ def _get_parser():
 
 
 def bland_altman_plot(
-    data1,
-    data2,
-    usex=False,
-    identifier=None,
-    fontscalefac=1.0,
-    xrange=None,
-    yrange=None,
-    doannotate=True,
-    debug=False,
-    *args,
-    **kwargs,
-):
+    data1: Any,
+    data2: Any,
+    usex: bool = False,
+    identifier: Optional[Any] = None,
+    fontscalefac: float = 1.0,
+    xrange: Optional[Any] = None,
+    yrange: Optional[Any] = None,
+    doannotate: bool = True,
+    debug: bool = False,
+    *args: Any,
+    **kwargs: Any,
+) -> None:
+    """
+    Create a Bland-Altman plot to compare two measurement methods.
+
+    This function generates a Bland-Altman plot, which is used to compare two
+    measurement methods by plotting the difference between the measurements
+    against their mean. It also computes and displays key statistics such as
+    mean difference, standard deviation of differences, and regression slopes.
+
+    Parameters
+    ----------
+    data1 : array-like
+        First set of measurements (X-axis data if `usex=True`).
+    data2 : array-like
+        Second set of measurements (Y-axis data).
+    usex : bool, optional
+        If True, use `data1` as the X-axis values; otherwise, use the mean of
+        `data1` and `data2` as the X-axis values. Default is False.
+    identifier : optional
+        Identifier for the dataset, printed for reference. Default is None.
+    fontscalefac : float, optional
+        Scaling factor for font size in annotations. Default is 1.0.
+    xrange : array-like, optional
+        X-axis limits for the plot. Default is None.
+    yrange : array-like, optional
+        Y-axis limits for the plot. Default is None.
+    doannotate : bool, optional
+        If True, annotate the plot with mean difference and standard deviation.
+        Default is True.
+    debug : bool, optional
+        If True, print debug information. Default is False.
+    *args : tuple
+        Additional arguments passed to the scatter plot.
+    **kwargs : dict
+        Additional keyword arguments passed to the scatter plot.
+
+    Returns
+    -------
+    None
+        This function does not return a value but displays a plot.
+
+    Notes
+    -----
+    The Bland-Altman plot is useful for assessing the agreement between two
+    measurement methods. The plot includes horizontal lines indicating the mean
+    difference and ±2 standard deviations from the mean.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> data1 = np.array([1, 2, 3, 4, 5])
+    >>> data2 = np.array([1.1, 2.2, 2.8, 4.1, 4.9])
+    >>> bland_altman_plot(data1, data2)
+    """
     # data1 is X, data2 is Y
     data1 = np.asarray(data1)
     data2 = np.asarray(data2)
@@ -268,7 +349,35 @@ def bland_altman_plot(
         ylim(yrange)
 
 
-def stringtorange(thestring):
+def stringtorange(thestring: Any) -> None:
+    """
+    Convert a comma-separated string to a tuple of floats representing a range.
+
+    Parameters
+    ----------
+    thestring : Any
+        A string containing two comma-separated float values representing
+        the minimum and maximum values of a range.
+
+    Returns
+    -------
+    tuple of float
+        A tuple containing (min_value, max_value) as floats.
+
+    Notes
+    -----
+    This function expects exactly two comma-separated float values. If the
+    input string does not contain exactly two values or if the values cannot
+    be converted to floats, the program will exit with an error message.
+
+    Examples
+    --------
+    >>> stringtorange("1.5,10.0")
+    (1.5, 10.0)
+
+    >>> stringtorange("0,-5.5")
+    (0.0, -5.5)
+    """
     thelist = thestring.split(",")
     if len(thelist) != 2:
         print("range setting requires two comma separated floats - exiting")
@@ -286,7 +395,68 @@ def stringtorange(thestring):
     return (themin, themax)
 
 
-def showxy(args):
+def showxy(args: Any) -> None:
+    """
+    Display or save xy data plots based on command-line arguments.
+
+    This function reads data from text files and plots the corresponding x and y vectors.
+    It supports multiple plot types including line plots, bar plots, and Bland-Altman plots.
+    The function also handles legend, title, axis labels, and output file saving.
+
+    Parameters
+    ----------
+    args : Any
+        An object containing various arguments for plotting, including:
+        - `textfilenames`: List of text files containing data vectors.
+        - `colors`: Comma-separated string of color names for plotting.
+        - `legends`: Comma-separated string of legend labels.
+        - `legendloc`: Location of the legend.
+        - `dobars`: Boolean indicating whether to plot bar charts.
+        - `blandaltman`: Boolean indicating whether to use Bland-Altman plot.
+        - `usex`: Used in Bland-Altman plot.
+        - `fontscalefac`: Scaling factor for font sizes.
+        - `xrange`: X-axis range.
+        - `yrange`: Y-axis range.
+        - `doannotate`: Boolean indicating whether to annotate points.
+        - `debug`: Boolean for debugging output.
+        - `usepoints`: Boolean for plotting points instead of lines.
+        - `thetitle`: Title of the plot.
+        - `thexlabel`: X-axis label.
+        - `theylabel`: Y-axis label.
+        - `outputfile`: Output file name for saving the plot.
+        - `saveres`: Resolution for saved figure.
+
+    Returns
+    -------
+    None
+        This function does not return any value. It either displays the plot or saves it to a file.
+
+    Notes
+    -----
+    - If `dobars` is True, bar plots are displayed using light gray bars.
+    - If `blandaltman` is True, a Bland-Altman plot is generated.
+    - If neither `dobars` nor `blandaltman` is True, line plots are displayed.
+    - If `colors` is not provided, colors are selected from the `nipy_spectral` colormap.
+    - If `outputfile` is None, the plot is displayed using `matplotlib.pyplot.show()`.
+
+    Examples
+    --------
+    >>> args = argparse.Namespace(
+    ...     textfilenames=['data1.txt', 'data2.txt'],
+    ...     colors='red,blue',
+    ...     legends='Dataset1, Dataset2',
+    ...     legendloc='upper right',
+    ...     dobars=False,
+    ...     blandaltman=False,
+    ...     usepoints=False,
+    ...     thetitle='My Plot',
+    ...     thexlabel='X-axis',
+    ...     theylabel='Y-axis',
+    ...     outputfile='output.png',
+    ...     saveres=300
+    ... )
+    >>> showxy(args)
+    """
     # process the file list
     textfilename = []
     for thefile in args.textfilenames: