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

rapidtide/workflows/showhist.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.
@@ -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

@@ -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,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

@@ -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,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.",
@@ -165,6 +235,13 @@ def _get_parser():
         help="Skip NUM lines at the beginning of each file (to get past header lines).",
         default=0,
     )
+    parser.add_argument(
+        "--fullxrange",
+        dest="fullxrange",
+        action="store_true",
+        help="Set xrange to be the overall range of all files.",
+        default=False,
+    )
     parser.add_argument(
         "--debug",
         dest="debug",
@@ -179,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
@@ -399,11 +562,7 @@ def showtc(args):
                 else:
                     linelabels.append(thisfilename)
             else:
-                linelabels.append(legends[i % len(legends)])
-                """if invecs.shape[0] > 1:
-                    linelabels.append(legends[i % len(legends)] + '_column' + str(j).zfill(2))
-                else:
-                    linelabels.append(legends[i % len(legends)])"""
+                linelabels.append(legends[j % len(legends)])
             samplerates.append(thissamplerate + 0.0)
             if args.debug:
                 print(
@@ -429,7 +588,10 @@ def showtc(args):
     for thevec in xvecs:
         overallxmax = np.max([np.max(thevec), overallxmax])
         overallxmin = np.min([np.min(thevec), overallxmin])
-    xrange = (np.max([overallxmin, args.thestarttime]), np.min([overallxmax, args.theendtime]))
+    if args.fullxrange:
+        xrange = (overallxmin, overallxmax)
+    else:
+        xrange = (np.max([overallxmin, args.thestarttime]), np.min([overallxmax, args.theendtime]))
     ymins = []
     ymaxs = []
     for thevec in yvecs: