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

rapidtide/workflows/physiofreq.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
 #
-#   Copyright 2020-2024 Blaise Frederick
+#   Copyright 2020-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,9 +18,12 @@
 #
 import argparse
 import os
+from argparse import Namespace
+from typing import Any, Callable, Dict, List, Optional, Tuple, Union
 
 import matplotlib.pyplot as plt
 import numpy as np
+from numpy.typing import NDArray
 from scipy.signal import savgol_filter, welch
 
 import rapidtide.filter as tide_filt
@@ -29,7 +32,32 @@ import rapidtide.io as tide_io
 import rapidtide.miscmath as tide_math
 
 
-def _get_parser():
+def _get_parser() -> Any:
+    """
+    Create and configure argument parser for physiofreq command line tool.
+
+    This function initializes an ArgumentParser object with all necessary
+    command line arguments for the physiofreq tool, which is designed to
+    find the dominant frequency in cardiac or respiratory waveforms.
+
+    Returns
+    -------
+    argparse.ArgumentParser
+        Configured argument parser object with all required arguments
+        for the physiofreq tool.
+
+    Notes
+    -----
+    The parser includes arguments for input file specification, display options,
+    sampling rate, frequency range constraints, and smoothing settings.
+
+    Examples
+    --------
+    >>> parser = _get_parser()
+    >>> args = parser.parse_args(['input.txt', '--display', '--samplerate', '2.0'])
+    >>> print(args.textfilename)
+    'input.txt'
+    """
     parser = argparse.ArgumentParser(
         prog="physiofreq",
         description="Finds the dominant frequency in a cardiac or respiratory waveform.",
@@ -75,15 +103,65 @@ def _get_parser():
 
 
 def getwavefreq(
-    thewaveform,
-    thesamplerate,
-    minpermin=40.0,
-    maxpermin=140.0,
-    smooth=True,
-    smoothlen=101,
-    debug=False,
-    displayplots=False,
-):
+    thewaveform: Any,
+    thesamplerate: Any,
+    minpermin: float = 40.0,
+    maxpermin: float = 140.0,
+    smooth: bool = True,
+    smoothlen: int = 101,
+    debug: bool = False,
+    displayplots: bool = False,
+) -> None:
+    """
+    Compute the fundamental frequency of a waveform using Welch's method and spectral analysis.
+
+    This function estimates the fundamental frequency of a given waveform by computing
+    its power spectrum using Welch's method, applying filtering and smoothing, and
+    identifying the peak within a specified frequency range. The result is returned in
+    beats per minute (BPM).
+
+    Parameters
+    ----------
+    thewaveform : array-like
+        Input waveform data to analyze.
+    thesamplerate : float
+        Sampling rate of the waveform in Hz.
+    minpermin : float, optional
+        Minimum allowed frequency in BPM. Default is 40.0.
+    maxpermin : float, optional
+        Maximum allowed frequency in BPM. Default is 140.0.
+    smooth : bool, optional
+        If True, apply Savitzky-Golay smoothing to the spectrum. Default is True.
+    smoothlen : int, optional
+        Length of the smoothing window for Savitzky-Golay filter. Default is 101.
+    debug : bool, optional
+        If True, print debug information during computation. Default is False.
+    displayplots : bool, optional
+        If True, display intermediate plots of the power spectrum. Default is False.
+
+    Returns
+    -------
+    float
+        Estimated fundamental frequency in BPM.
+
+    Notes
+    -----
+    - The function internally uses `scipy.signal.welch` for power spectral density estimation.
+    - A Hamming window and detrending are applied before spectral analysis.
+    - The frequency range is constrained to the interval [minpermin, maxpermin].
+    - If `displayplots` is True, two plots will be shown:
+        1. Initial power spectrum with peak marked.
+        2. Smoothed spectrum with final peak marked.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from scipy.signal import chirp
+    >>> t = np.linspace(0, 5, 1000, endpoint=False)
+    >>> signal = chirp(t, f0=60, f1=120, t1=5, method='linear')
+    >>> freq = getwavefreq(signal, thesamplerate=1000, debug=True)
+    >>> print(f"Estimated frequency: {freq} BPM")
+    """
     if len(thewaveform) % 2 == 1:
         thewaveform = thewaveform[:-1]
     if len(thewaveform) > 1024:
@@ -141,7 +219,55 @@ def getwavefreq(
     return peakfreq
 
 
-def physiofreq(args):
+def physiofreq(args: Any) -> None:
+    """
+    Calculate and display the dominant frequency of physiological data.
+
+    This function reads physiological time series data from a file and determines
+    the peak frequency using wavelet analysis. It supports both JSON and standard
+    text file formats, and displays the results in Hz, BPM, and period in seconds.
+
+    Parameters
+    ----------
+    args : Any
+        An object containing command line arguments with the following attributes:
+        - textfilename : str
+            Path to the input file containing physiological data
+        - samplerate : float, optional
+            Sampling rate of the data (used when file is not in JSON format)
+        - lowestbpm : float, optional
+            Minimum allowed heart rate in beats per minute (default: 30)
+        - highestbpm : float, optional
+            Maximum allowed heart rate in beats per minute (default: 200)
+        - nosmooth : bool, optional
+            If True, disables smoothing of the frequency spectrum
+        - displayplots : bool, optional
+            If True, displays frequency plots
+
+    Returns
+    -------
+    None
+        This function prints the frequency analysis results to stdout and does not return a value.
+
+    Notes
+    -----
+    The function automatically detects the file format based on the extension:
+    - JSON files are processed using `tide_io.readbidstsv()`
+    - Other formats are processed using `tide_io.readvecs()`
+
+    Examples
+    --------
+    >>> args = type('Args', (), {
+    ...     'textfilename': 'data.txt',
+    ...     'samplerate': 100.0,
+    ...     'lowestbpm': 40,
+    ...     'highestbpm': 180,
+    ...     'nosmooth': False,
+    ...     'displayplots': False
+    ... })()
+    >>> physiofreq(args)
+    data.txt:	0.83 Hz, 49.80 per minute, period is 1.20 seconds
+    """
     textfileinfo, textfilecolspec = tide_io.parsefilespec(args.textfilename)
     filebase, extension = os.path.splitext(textfileinfo[0])
     if extension == ".json":
@@ -152,6 +278,7 @@ def physiofreq(args):
             invec,
             compressed,
             fakecolumns,
+            extrainfo,
         ) = tide_io.readbidstsv(textfileinfo[0])
     else:
         invec = tide_io.readvecs(textfileinfo[0])[0]

rapidtide/workflows/pixelcomp.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.
@@ -25,12 +25,61 @@ from numpy.polynomial import Polynomial
 import rapidtide.io as tide_io
 
 mpl.use("Agg")
+from typing import Any, Callable, Dict, List, Optional, Tuple, Union
+
 import matplotlib.pyplot as plt
+from numpy.typing import NDArray
 
 
-def _get_parser():
+def _get_parser() -> Any:
     """
-    Argument parser for pixelcomp
+    Argument parser for pixelcomp.
+
+    This function creates and configures an argument parser for the pixelcomp tool,
+    which is used to compare two NIfTI files voxel by voxel and generate either
+    a contour plot or a scatter plot of the differences.
+
+    Returns
+    -------
+    argparse.ArgumentParser
+        Configured argument parser object with all required and optional arguments
+        for the pixelcomp tool.
+
+    Notes
+    -----
+    The parser supports the following positional arguments:
+
+    - ``inputfilename1`` : str
+        The name of the first input image NIfTI file.
+    - ``maskfilename1`` : str
+        The name of the first input mask NIfTI file.
+    - ``inputfilename2`` : str
+        The name of the second input image NIfTI file.
+    - ``maskfilename2`` : str
+        The name of the second input mask NIfTI file.
+    - ``outputroot`` : str
+        The root name of the output files.
+
+    And the following optional arguments:
+
+    - ``--scatter`` : bool, optional
+        Do a scatter plot instead of a contour plot. Default is False.
+    - ``--fitonly`` : bool, optional
+        Perform fit only - do not generate graph. Default is False.
+    - ``--nodisplay`` : bool, optional
+        Save graphs to file only - do not display. Default is True.
+    - ``--fitorder`` : int, optional
+        Order of line fit - default is 1 (linear). Default is 1.
+    - ``--usex`` : bool, optional
+        Use x instead of (y + x)/2 in Bland-Altman plot. Default is False.
+    - ``--histbins`` : int, optional
+        Number of bins per dimension for the contour plot - default is 51.
+        Default is 51.
+
+    Examples
+    --------
+    >>> parser = _get_parser()
+    >>> args = parser.parse_args()
     """
     parser = argparse.ArgumentParser(
         prog="pixelcomp",
@@ -57,7 +106,7 @@ def _get_parser():
     parser.add_argument(
         "--scatter",
         action="store_true",
-        help=("Do a scatter plot intstead of a contour plot."),
+        help=("Do a scatter plot instead of a contour plot."),
         default=False,
     )
     parser.add_argument(
@@ -99,7 +148,58 @@ def _get_parser():
     return parser
 
 
-def bland_altman_plot(data1, data2, usex=False, *args, **kwargs):
+def bland_altman_plot(
+    data1: Any, data2: Any, usex: bool = False, *args: Any, **kwargs: Any
+) -> None:
+    """
+    Create a Bland-Altman plot for comparing two sets of measurements.
+
+    This function generates a scatter plot showing the difference between two
+    measurements against their mean. The plot includes horizontal lines indicating
+    the mean difference and ±2 standard deviations, which are commonly used to
+    assess agreement between two measurement methods.
+
+    Parameters
+    ----------
+    data1 : array-like
+        First set of measurements (X values in the plot).
+    data2 : array-like
+        Second set of measurements (Y values in the plot).
+    usex : bool, optional
+        If True, use data1 as the x-values for the plot. If False (default),
+        use the mean of data1 and data2 as x-values.
+    *args : tuple
+        Additional arguments to pass to matplotlib's scatter function.
+    **kwargs : dict
+        Additional keyword arguments to pass to matplotlib's scatter function.
+
+    Returns
+    -------
+    None
+        This function displays the plot but does not return any value.
+
+    Notes
+    -----
+    The Bland-Altman plot is used to assess the agreement between two different
+    measurement methods. The mean difference (MD) is plotted on the y-axis, and
+    the mean of the two measurements is plotted on the x-axis. The horizontal
+    lines represent:
+    - Mean difference (MD)
+    - Mean difference ± 2 standard deviations (±2SD)
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> import matplotlib.pyplot as plt
+    >>> 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)
+    >>> plt.show()
+
+    >>> # Using custom scatter plot properties
+    >>> bland_altman_plot(data1, data2, c='red', alpha=0.7)
+    >>> plt.show()
+    """
     # data1 is X, data2 is Y
     data1 = np.asarray(data1)
     data2 = np.asarray(data2)
@@ -117,7 +217,47 @@ def bland_altman_plot(data1, data2, usex=False, *args, **kwargs):
     plt.axhline(md - 2 * sd, color="gray", linestyle="--")
 
 
-def pairdata(input1_data, input2_data, totalmask):
+def pairdata(input1_data: Any, input2_data: Any, totalmask: Any) -> NDArray:
+    """
+    Pair corresponding elements from two 3D arrays based on a mask.
+
+    This function extracts elements from two 3D input arrays where the mask
+    has non-zero values, creating pairs of corresponding elements.
+
+    Parameters
+    ----------
+    input1_data : array-like
+        First 3D array from which elements will be extracted.
+    input2_data : array-like
+        Second 3D array from which elements will be extracted.
+    totalmask : array-like
+        3D mask array where non-zero values indicate positions to pair.
+
+    Returns
+    -------
+    NDArray
+        2D array where each row contains a pair of corresponding elements
+        from input1_data and input2_data at positions where totalmask > 0.
+
+    Notes
+    -----
+    - The function assumes all input arrays have the same shape
+    - Only positions where totalmask > 0 are considered
+    - The returned array has shape (n_pairs, 2) where n_pairs is the number
+      of non-zero mask positions
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> input1 = np.array([[[1, 2], [3, 4]], [[5, 6], [7, 8]]])
+    >>> input2 = np.array([[[9, 10], [11, 12]], [[13, 14], [15, 16]]])
+    >>> mask = np.array([[[1, 0], [0, 1]], [[1, 1], [0, 0]]])
+    >>> pairdata(input1, input2, mask)
+    array([[ 1,  9],
+           [ 4, 12],
+           [ 5, 13],
+           [ 6, 14]])
+    """
     nonzeropoints = np.where(totalmask > 0)
     pairlist = []
     for i in range(0, len(nonzeropoints[0])):
@@ -131,7 +271,69 @@ def pairdata(input1_data, input2_data, totalmask):
     return np.asarray(pairlist)
 
 
-def pixelcomp(args):
+def pixelcomp(args: Any) -> None:
+    """
+    Compare pixel values from two input images using masks and generate statistical plots.
+
+    This function reads two NIfTI images and their corresponding masks, performs a pixel-wise
+    comparison, and generates either a scatter plot or a 2D histogram of the paired data.
+    It also fits a polynomial to the data and optionally produces a Bland-Altman plot.
+
+    Parameters
+    ----------
+    args : Any
+        An object containing the following attributes:
+        - inputfilename1 : str
+            Path to the first input NIfTI image file.
+        - maskfilename1 : str
+            Path to the first mask NIfTI file.
+        - inputfilename2 : str
+            Path to the second input NIfTI image file.
+        - maskfilename2 : str
+            Path to the second mask NIfTI file.
+        - outputroot : str
+            Root name for output files.
+        - histbins : int
+            Number of bins for the 2D histogram.
+        - fitorder : int
+            Order of the polynomial to fit.
+        - display : bool
+            If True, display plots; otherwise, save them to files.
+        - scatter : bool
+            If True, generate a scatter plot; otherwise, generate a contour plot.
+        - fitonly : bool
+            If True, only perform the polynomial fit and save coefficients.
+
+    Returns
+    -------
+    None
+        This function does not return any value. It saves plots and data to files.
+
+    Notes
+    -----
+    - The function requires both input images and masks to have matching spatial dimensions.
+    - The output includes:
+        * A scatter or contour plot saved as PNG.
+        * A file with polynomial coefficients.
+        * Optionally, a Bland-Altman plot saved as PNG.
+    - If a RankWarning occurs during polynomial fitting, the coefficients are set to [0.0, 0.0].
+
+    Examples
+    --------
+    >>> class Args:
+    ...     inputfilename1 = "image1.nii.gz"
+    ...     maskfilename1 = "mask1.nii.gz"
+    ...     inputfilename2 = "image2.nii.gz"
+    ...     maskfilename2 = "mask2.nii.gz"
+    ...     outputroot = "output"
+    ...     histbins = 50
+    ...     fitorder = 1
+    ...     display = False
+    ...     scatter = False
+    ...     fitonly = False
+    >>> args = Args()
+    >>> pixelcomp(args)
+    """
     if args.display:
         mpl.use("TkAgg")
 
@@ -194,8 +396,8 @@ def pixelcomp(args):
         thecoffs = (
             Polynomial.fit(thearray[:, 0], thearray[:, 1], args.fitorder).convert().coef[::-1]
         )
-    except np.RankWarning:
-        thecoffs = [0.0, 0.0]
+    except np.exceptions.RankWarning:
+        thecoffs = np.asarray([0.0, 0.0])
     print("thecoffs=", thecoffs)
     with open(f"{args.outputroot}_order_{args.fitorder}_fit", "w") as file:
         file.writelines(str(thecoffs))

rapidtide/workflows/plethquality.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,17 +18,39 @@
 #
 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 skew
 
 import rapidtide.io as tide_io
 import rapidtide.workflows.parser_funcs as pf
 
 
-def _get_parser():
+def _get_parser() -> Any:
     """
-    Argument parser for plethquality
+    Argument parser for plethquality.
+
+    This function creates and configures an argument parser for the plethquality
+    command-line tool that calculates quality metrics from cardiac text files.
+
+    Returns
+    -------
+    argparse.ArgumentParser
+        Configured argument parser object with all required and optional
+        arguments for plethquality functionality.
+
+    Notes
+    -----
+    The parser includes both required and optional arguments for processing
+    cardiac text files and generating quality metrics.
+
+    Examples
+    --------
+    >>> parser = _get_parser()
+    >>> args = parser.parse_args(['input.txt', 'output.txt'])
     """
     parser = argparse.ArgumentParser(
         prog="plethquality",
@@ -57,37 +79,55 @@ def _get_parser():
     return parser
 
 
-def plethquality(waveform, Fs, S_windowsecs=5.0, debug=False):
+def plethquality(waveform: Any, Fs: Any, S_windowsecs: float = 5.0, debug: bool = False) -> None:
     """
+    Calculate the windowed skewness quality metrics for a photoplethysmogram (PPG) signal.
+
+    This function computes the signal quality index based on the skewness of the PPG waveform
+    over a sliding window, as described in Elgendi, M. "Optimal Signal Quality Index for
+    Photoplethysmogram Signals". Bioengineering 2016, Vol. 3, Page 21 (2016).
 
     Parameters
     ----------
-    waveform: array-like
-        The cardiac waveform to be assessed
-    Fs: float
-        The sample rate of the data
-    S_windowsecs: float
-        Window duration in seconds.  Defaults to 2.0 (optimal according to Elgendi
-    debug: boolean
-        Turn on extended output
+    waveform : array-like
+        The cardiac waveform to be assessed.
+    Fs : float
+        The sample rate of the data in Hz.
+    S_windowsecs : float, optional
+        Window duration in seconds. Defaults to 5.0.
+    debug : bool, optional
+        Turn on extended output for debugging purposes. Defaults to False.
 
     Returns
     -------
-    S_sqi_mean: float
-        The mean value of the quality index over all time
-    S_std_mean: float
-        The standard deviation of the quality index over all time
-    S_waveform: array
-        The quality metric over all timepoints
-
+    S_sqi_mean : float
+        The mean value of the quality index over all time.
+    S_sqi_std : float
+        The standard deviation of the quality index over all time.
+    S_waveform : array
+        The quality metric computed over all timepoints.
+
+    Notes
+    -----
+    The window size is rounded to the nearest odd number of samples to ensure symmetric
+    sliding windows around each point. The skewness is calculated using `scipy.stats.skew`
+    with `nan_policy="omit"` to ignore NaN values.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from scipy.stats import skew
+    >>> waveform = np.random.randn(1000)
+    >>> Fs = 100.0
+    >>> mean_sqi, std_sqi, sqi_waveform = plethquality(waveform, Fs)
+    >>> print(f"Mean SQI: {mean_sqi:.3f}")
+    Mean SQI: 0.000
 
-    Calculates the windowed skewness quality metrics described in Elgendi, M. "Optimal Signal Quality Index for
-    Photoplethysmogram Signals". Bioengineering 2016, Vol. 3, Page 21 3, 21 (2016).
     """
     # calculate S_sqi over a sliding window.  Window size should be an odd number of points.
     S_windowpts = int(np.round(S_windowsecs * Fs, 0))
     S_windowpts += 1 - S_windowpts % 2
-    S_waveform = waveform * 0.0
+    S_waveform = np.zeros_like(waveform)
     if debug:
         print("S_windowsecs, S_windowpts:", S_windowsecs, S_windowpts)
     for i in range(0, len(waveform)):
@@ -103,7 +143,49 @@ def plethquality(waveform, Fs, S_windowsecs=5.0, debug=False):
     return S_sqi_mean, S_sqi_std, S_waveform
 
 
-def plethquality(args):
+def plethquality(args: Any) -> None:
+    """
+    Calculate plethysmography quality score and optionally display results.
+
+    This function reads plethysmography data from a text file, calculates a quality
+    score based on the signal characteristics, and writes the quality scores to an
+    output file. Optionally displays the quality score plot.
+
+    Parameters
+    ----------
+    args : Any
+        An object containing command line arguments with the following attributes:
+        - infilename : str
+            Input filename containing plethysmography data
+        - outfilename : str
+            Output filename for quality scores
+        - samplerate : float, optional
+            Sampling rate of the data (if not specified, will be read from file)
+        - display : bool
+            Whether to display the quality score plot
+
+    Returns
+    -------
+    None
+        This function does not return a value but writes results to files and
+        optionally displays plots.
+
+    Notes
+    -----
+    The function uses `tide_io.readvectorsfromtextfile` to read data and
+    `tide_io.writevec` to write quality scores. Quality scores are calculated
+    using an internal `plethquality` function that analyzes signal characteristics.
+
+    Examples
+    --------
+    >>> args = argparse.Namespace(
+    ...     infilename='pleth_data.txt',
+    ...     outfilename='quality_scores.txt',
+    ...     samplerate=100.0,
+    ...     display=True
+    ... )
+    >>> plethquality(args)
+    """
     if args.display:
         import matplotlib as mpl