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

rapidtide/simFuncClasses.py

@@ -18,11 +18,13 @@
 #
 import sys
 import warnings
+from typing import Any
 
 import matplotlib.pyplot as plt
 import numpy as np
 import scipy as sp
 from numpy.polynomial import Polynomial
+from numpy.typing import NDArray
 from scipy.optimize import curve_fit
 from statsmodels.robust import mad
 
@@ -58,6 +60,50 @@ class SimilarityFunctionator:
         filterinputdata=True,
         debug=False,
     ):
+        """
+        Initialize the similarity function analysis object.
+
+        Parameters
+        ----------
+        Fs : float, optional
+            Sampling frequency in Hz. Default is 0.0.
+        similarityfuncorigin : int, optional
+            Origin point for similarity function calculation. Default is 0.
+        lagmininpts : int, optional
+            Minimum lag in samples. Default is 0.
+        lagmaxinpts : int, optional
+            Maximum lag in samples. Default is 0.
+        ncprefilter : array-like, optional
+            Pre-filter for cross-correlation calculation. Default is None.
+        negativegradient : bool, optional
+            Flag to indicate if negative gradient should be used. Default is False.
+        reftc : array-like, optional
+            Reference time course for cross-correlation. Default is None.
+        reftcstart : float, optional
+            Start time for reference time course. Default is 0.0.
+        detrendorder : int, optional
+            Order of detrending to apply to data. Default is 1.
+        filterinputdata : bool, optional
+            Flag to indicate if input data should be filtered. Default is True.
+        debug : bool, optional
+            Flag to enable debug mode. Default is False.
+
+        Returns
+        -------
+        None
+            This method initializes the object attributes but does not return any value.
+
+        Notes
+        -----
+        The initialization sets up all necessary parameters for cross-correlation analysis.
+        If a reference time course is provided, it is set using the setreftc method.
+        All lag parameters are converted to integers by adding 0 to ensure proper type handling.
+
+        Examples
+        --------
+        >>> obj = CrossCorrelationAnalyzer(Fs=100.0, lagmininpts=-10, lagmaxinpts=10)
+        >>> obj = CrossCorrelationAnalyzer(reftc=reference_data, reftcstart=5.0)
+        """
         self.setFs(Fs)
         self.similarityfuncorigin = similarityfuncorigin
         self.lagmininpts = lagmininpts + 0
@@ -72,10 +118,78 @@ class SimilarityFunctionator:
             self.setreftc(self.reftc)
             self.reftcstart = reftcstart + 0.0
 
-    def setFs(self, Fs):
+    def setFs(self, Fs: float) -> None:
+        """Set the sampling frequency for the system.
+
+        Parameters
+        ----------
+        Fs : float
+            Sampling frequency in Hz. This parameter determines the rate at which
+            samples are taken from the continuous signal.
+
+        Returns
+        -------
+        None
+            This method does not return any value.
+
+        Notes
+        -----
+        The sampling frequency is a critical parameter that affects the
+        resolution and accuracy of digital signal processing operations.
+        It should be set appropriately based on the Nyquist criterion to
+        avoid aliasing.
+
+        Examples
+        --------
+        >>> obj = MyClass()
+        >>> obj.setFs(44100.0)
+        >>> print(obj.Fs)
+        44100.0
+        """
         self.Fs = Fs
 
-    def preptc(self, thetc, isreftc=False):
+    def preptc(self, thetc: NDArray, isreftc: bool = False) -> NDArray:
+        """
+        Prepare timecourse by filtering, normalizing, detrending, and applying a window function.
+
+        This function applies a series of preprocessing steps to the input timecourse, including
+        optional filtering, normalization, detrending, and window function application. The specific
+        processing steps depend on the input parameters and class configuration.
+
+        Parameters
+        ----------
+        thetc : numpy.ndarray
+            Input timecourse data to be prepared
+        isreftc : bool, optional
+            Flag indicating whether the input is a reference timecourse. If True, the timecourse
+            is filtered using the class's prefilter and then normalized. Default is False.
+
+        Returns
+        -------
+        numpy.ndarray
+            Prepared and normalized timecourse data after filtering, normalization, detrending,
+            and window function application
+
+        Notes
+        -----
+        The preprocessing pipeline applies the following steps in order:
+        1. Filtering (if applicable based on isreftc and filterinputdata flags)
+        2. Gradient calculation (when negativegradient is True)
+        3. Normalization with detrending and window function application
+
+        When isreftc is True, the input is filtered using self.ncprefilter.apply() before
+        normalization. When isreftc is False and negativegradient is True, the negative gradient
+        of the filtered timecourse is used. Otherwise, the filtering behavior depends on the
+        filterinputdata flag.
+
+        Examples
+        --------
+        >>> # Prepare a timecourse with default settings
+        >>> prepared_tc = processor.preptc(input_tc)
+        >>>
+        >>> # Prepare a reference timecourse
+        >>> ref_tc = processor.preptc(input_tc, isreftc=True)
+        """
         # prepare timecourse by filtering, normalizing, detrending, and applying a window function
         if isreftc:
             thenormtc = tide_math.corrnormalize(
@@ -106,14 +220,79 @@ class SimilarityFunctionator:
 
         return thenormtc
 
-    def trim(self, vector):
+    def trim(self, vector: NDArray) -> NDArray:
+        """
+        Trim vector based on similarity function origin and lag constraints.
+
+        Parameters
+        ----------
+        vector : NDArray
+            Input vector to be trimmed.
+
+        Returns
+        -------
+        NDArray
+            Trimmed vector containing elements from
+            `self.similarityfuncorigin - self.lagmininpts` to
+            `self.similarityfuncorigin + self.lagmaxinpts`.
+
+        Notes
+        -----
+        This function extracts a subset of the input vector based on the origin point
+        of the similarity function and the minimum/maximum lag constraints. The trimming
+        ensures that only relevant portions of the vector are considered for similarity
+        calculations.
+
+        Examples
+        --------
+        >>> # Assuming self.similarityfuncorigin = 10, self.lagmininpts = 2, self.lagmaxinpts = 3
+        >>> trimmed_vector = trim(vector)
+        >>> # Returns vector[8:13] where 8 = 10 - 2 and 13 = 10 + 3
+        """
         return vector[
             self.similarityfuncorigin
             - self.lagmininpts : self.similarityfuncorigin
             + self.lagmaxinpts
         ]
 
-    def getfunction(self, trim=True):
+    def getfunction(self, trim: bool = True) -> tuple[NDArray | None, NDArray | None, int | None]:
+        """
+        Retrieve simulation function data with optional trimming.
+
+        This method returns the simulation function data and time axis, with optional
+        trimming based on the trim parameter. The method handles different validation
+        states of the data and returns appropriate tuples of (function, time_axis, max_value)
+        or None values depending on the data validity.
+
+        Parameters
+        ----------
+        trim : bool, optional
+            If True, trims the simulation function and time axis using the internal
+            trim method. If False, returns the raw data without trimming. Default is True.
+
+        Returns
+        -------
+        tuple
+            A tuple containing:
+            - NDArray or None: Trimmed or untrimmed simulation function data
+            - NDArray or None: Trimmed or untrimmed time axis data
+            - int or None: Global maximum value, or None if not available
+
+        Notes
+        -----
+        The method checks the validity of data through `self.datavalid` and `self.timeaxisvalid` attributes.
+        If `self.datavalid` is True, returns both function and time axis data.
+        If `self.datavalid` is False but `self.timeaxisvalid` is True, returns only time axis data.
+        If neither is valid, prints an error message and returns (None, None, None).
+
+        Examples
+        --------
+        >>> result = obj.getfunction(trim=True)
+        >>> func_data, time_data, max_val = result
+        >>>
+        >>> result = obj.getfunction(trim=False)
+        >>> func_data, time_data, max_val = result
+        """
         if self.datavalid:
             if trim:
                 return (
@@ -137,15 +316,53 @@ class SimilarityFunctionator:
 class MutualInformationator(SimilarityFunctionator):
     def __init__(
         self,
-        windowfunc="hamming",
-        norm=True,
-        madnorm=False,
-        smoothingtime=-1.0,
-        bins=20,
-        sigma=0.25,
-        *args,
-        **kwargs,
-    ):
+        windowfunc: str = "hamming",
+        norm: bool = True,
+        madnorm: bool = False,
+        smoothingtime: float = -1.0,
+        bins: int = 20,
+        sigma: float = 0.25,
+        *args: Any,
+        **kwargs: Any,
+    ) -> None:
+        """
+        Initialize the MutualInformationator object with specified parameters.
+
+        Parameters
+        ----------
+        windowfunc : str, optional
+            Window function to use for spectral analysis. Default is "hamming".
+        norm : bool, optional
+            Whether to normalize the data. Default is True.
+        madnorm : bool, optional
+            Whether to use median absolute deviation normalization. Default is False.
+        smoothingtime : float, optional
+            Time scale for smoothing filter. If > 0, a noncausal filter is set up.
+            Default is -1.0 (no smoothing).
+        bins : int, optional
+            Number of bins for histogram-based calculations. Default is 20.
+        sigma : float, optional
+            Standard deviation for Gaussian smoothing. Default is 0.25.
+        *args : Any
+            Additional positional arguments passed to parent class.
+        **kwargs : Any
+            Additional keyword arguments passed to parent class.
+
+        Returns
+        -------
+        None
+            This method initializes the object in-place and does not return anything.
+
+        Notes
+        -----
+        When `smoothingtime` is positive, a noncausal filter is initialized with
+        frequency settings based on the specified smoothing time scale.
+
+        Examples
+        --------
+        >>> mi = MutualInformationator(windowfunc="hanning", bins=30, smoothingtime=2.0)
+        >>> mi = MutualInformationator(norm=False, madnorm=True, sigma=0.5)
+        """
         self.windowfunc = windowfunc
         self.norm = norm
         self.madnorm = madnorm
@@ -160,7 +377,37 @@ class MutualInformationator(SimilarityFunctionator):
             )
         super(MutualInformationator, self).__init__(*args, **kwargs)
 
-    def setlimits(self, lagmininpts, lagmaxinpts):
+    def setlimits(self, lagmininpts: int, lagmaxinpts: int) -> None:
+        """
+        Set the minimum and maximum lag limits for the analysis.
+
+        This function configures the lag limits based on the provided parameters and
+        adjusts the smoothing filter padding time if necessary to ensure proper
+        signal processing behavior.
+
+        Parameters
+        ----------
+        lagmininpts : int
+            The minimum lag value in terms of number of points.
+        lagmaxinpts : int
+            The maximum lag value in terms of number of points.
+
+        Returns
+        -------
+        None
+            This function does not return any value.
+
+        Notes
+        -----
+        The function automatically adjusts the smoothing filter padding time to be
+        no larger than the total time span of the data. If the adjustment is made,
+        a message is printed to indicate the new padding time value.
+
+        Examples
+        --------
+        >>> setlimits(10, 100)
+        >>> # Sets minimum lag to 10 points and maximum lag to 100 points
+        """
         self.lagmininpts = lagmininpts
         self.lagmaxinpts = lagmaxinpts
         origpadtime = self.smoothingfilter.getpadtime()
@@ -170,10 +417,70 @@ class MutualInformationator(SimilarityFunctionator):
             print("lowering smoothing filter pad time to", newpadtime)
             self.smoothingfilter.setpadtime(newpadtime)
 
-    def setbins(self, bins):
+    def setbins(self, bins: int) -> None:
+        """
+        Set the number of bins for histogram calculation.
+
+        Parameters
+        ----------
+        bins : int
+            The number of bins to use for histogram calculation.
+
+        Returns
+        -------
+        None
+            This method does not return any value.
+
+        Notes
+        -----
+        This method assigns the specified number of bins to the instance variable
+        `self.bins`. The bins parameter determines the granularity of the histogram
+        distribution.
+
+        Examples
+        --------
+        >>> obj = MyClass()
+        >>> obj.setbins(10)
+        >>> print(obj.bins)
+        10
+        """
         self.bins = bins
 
-    def setreftc(self, reftc, offset=0.0):
+    def setreftc(self, reftc: NDArray, offset: float = 0.0) -> None:
+        """
+        Set reference time course and compute cross-mutual information.
+
+        This method initializes the reference time course and computes the cross-mutual
+        information between the reference time course and itself to determine the
+        optimal time alignment and similarity function.
+
+        Parameters
+        ----------
+        reftc : NDArray
+            Reference time course array to be set and processed.
+        offset : float, optional
+            Time offset to be applied to the time axis (default is 0.0).
+
+        Returns
+        -------
+        None
+            This method modifies the object's attributes in-place and does not return anything.
+
+        Notes
+        -----
+        The method performs the following operations:
+        1. Stores a copy of the reference time course
+        2. Pre-processes the reference time course using preptc method
+        3. Computes cross-mutual information using tide_corr.cross_mutual_info
+        4. Adjusts the time axis by the specified offset
+        5. Sets various internal attributes including similarity function normalization
+
+        Examples
+        --------
+        >>> obj.setreftc(reference_data, offset=0.5)
+        >>> print(obj.timeaxis)
+        >>> print(obj.similarityfunclen)
+        """
         self.reftc = reftc + 0.0
         self.prepreftc = self.preptc(self.reftc, isreftc=True)
 
@@ -197,10 +504,91 @@ class MutualInformationator(SimilarityFunctionator):
             print(f"MutualInformationator setreftc: {self.timeaxis}")
             print(f"MutualInformationator setreftc: {self.mi_norm=}")
 
-    def getnormfac(self):
+    def getnormfac(self) -> float:
+        """
+        Return the normalization factor stored in the instance.
+
+        This method provides access to the normalization factor that has been
+        previously computed and stored in the instance variable `mi_norm`.
+
+        Returns
+        -------
+        float
+            The normalization factor value stored in `self.mi_norm`.
+
+        Notes
+        -----
+        The normalization factor is typically used to scale or normalize
+        data within the class. This value should be set before calling this
+        method to ensure meaningful results.
+
+        Examples
+        --------
+        >>> instance = MyClass()
+        >>> instance.mi_norm = 2.5
+        >>> norm_factor = instance.getnormfac()
+        >>> print(norm_factor)
+        2.5
+        """
         return self.mi_norm
 
-    def run(self, thetc, locs=None, trim=True, gettimeaxis=True):
+    def run(
+        self,
+        thetc: NDArray,
+        locs: NDArray | None = None,
+        trim: bool = True,
+        gettimeaxis: bool = True,
+    ) -> tuple[NDArray, NDArray, int] | NDArray:
+        """
+        Compute cross-mutual information between test and reference timecourses.
+
+        This function calculates the cross-mutual information between a test timecourse
+        and a reference timecourse, optionally applying preprocessing, trimming, and
+        smoothing. It supports both trimmed and untrimmed outputs, and can return
+        time axis information depending on the input parameters.
+
+        Parameters
+        ----------
+        thetc : NDArray
+            Test timecourse array of shape (n_times,).
+        locs : NDArray | None, optional
+            Locations to compute mutual information at; if provided, the function
+            will return only the similarity function values at these locations.
+            Default is None.
+        trim : bool, optional
+            If True, trim the output similarity function and time axis to the
+            valid range defined by `lagmininpts` and `lagmaxinpts`. If False,
+            the full similarity function is returned. Default is True.
+        gettimeaxis : bool, optional
+            If True, return the time axis along with the similarity function.
+            If False, only the similarity function is returned. Default is True.
+
+        Returns
+        -------
+        tuple[NDArray, NDArray, int] | NDArray
+            If `locs` is not None, returns the similarity function values at the
+            specified locations.
+            If `trim` is True and `gettimeaxis` is True, returns a tuple of:
+            - trimmed similarity function (NDArray)
+            - trimmed time axis (NDArray)
+            - index of the global maximum (int)
+            If `trim` is False and `gettimeaxis` is True, returns a tuple of:
+            - full similarity function (NDArray)
+            - full time axis (NDArray)
+            - index of the global maximum (int)
+            If `gettimeaxis` is False, returns only the similarity function (NDArray).
+
+        Notes
+        -----
+        This function uses `tide_corr.cross_mutual_info` for computing cross-mutual
+        information, and applies normalization and optional smoothing based on
+        instance attributes.
+
+        Examples
+        --------
+        >>> result = obj.run(test_tc, locs=None, trim=True, gettimeaxis=True)
+        >>> sim_func, time_axis, max_idx = result
+        """
         if len(thetc) != len(self.reftc):
             print(
                 "MutualInformationator: timecourses are of different sizes:",
@@ -293,24 +681,124 @@ class MutualInformationator(SimilarityFunctionator):
 class Correlator(SimilarityFunctionator):
     def __init__(
         self,
-        windowfunc="hamming",
-        corrweighting="None",
-        corrpadding=0,
-        baselinefilter=None,
-        *args,
-        **kwargs,
-    ):
+        windowfunc: str = "hamming",
+        corrweighting: str = "None",
+        corrpadding: int = 0,
+        baselinefilter: Any | None = None,
+        *args: Any,
+        **kwargs: Any,
+    ) -> None:
+        """
+        Initialize the Correlator with specified parameters.
+
+        Parameters
+        ----------
+        windowfunc : str, default="hamming"
+            Window function to apply during correlation. Common options include
+            'hamming', 'hanning', 'blackman', etc.
+        corrweighting : str, default="None"
+            Correlation weighting method. Can be 'None' or other weighting schemes
+            depending on implementation.
+        corrpadding : int, default=0
+            Padding size to apply during correlation operations.
+        baselinefilter : Any | None, default=None
+            Baseline filtering method or object to apply. Can be None to skip filtering.
+        *args : Any
+            Additional positional arguments passed to parent class.
+        **kwargs : Any
+            Additional keyword arguments passed to parent class.
+
+        Returns
+        -------
+        None
+            This method initializes the instance and does not return any value.
+
+        Notes
+        -----
+        The Correlator class inherits from a parent class, and this initialization
+        method sets up the correlation parameters before calling the parent's
+        initialization method.
+
+        Examples
+        --------
+        >>> correlator = Correlator(windowfunc="hanning", corrpadding=10)
+        >>> correlator = Correlator(baselinefilter=my_filter_object)
+        """
         self.windowfunc = windowfunc
         self.corrweighting = corrweighting
         self.corrpadding = corrpadding
         self.baselinefilter = baselinefilter
         super(Correlator, self).__init__(*args, **kwargs)
 
-    def setlimits(self, lagmininpts, lagmaxinpts):
+    def setlimits(self, lagmininpts: int, lagmaxinpts: int) -> None:
+        """
+        Set the minimum and maximum lag limits for the analysis.
+
+        Parameters
+        ----------
+        lagmininpts : int
+            The minimum lag value in points for the analysis.
+        lagmaxinpts : int
+            The maximum lag value in points for the analysis.
+
+        Returns
+        -------
+        None
+            This method does not return any value.
+
+        Notes
+        -----
+        This method assigns the provided lag limits to instance variables
+        `self.lagmininpts` and `self.lagmaxinpts`. The lag limits define the
+        range of lags to be considered in the subsequent analysis operations.
+
+        Examples
+        --------
+        >>> obj = MyClass()
+        >>> obj.setlimits(5, 20)
+        >>> print(obj.lagmininpts)
+        5
+        >>> print(obj.lagmaxinpts)
+        20
+        """
         self.lagmininpts = lagmininpts
         self.lagmaxinpts = lagmaxinpts
 
-    def setreftc(self, reftc, offset=0.0):
+    def setreftc(self, reftc: NDArray, offset: float = 0.0) -> None:
+        """
+        Set reference time course and initialize related attributes.
+
+        This function sets the reference time course, computes related parameters,
+        and initializes the time axis for similarity function calculations.
+
+        Parameters
+        ----------
+        reftc : NDArray
+            Reference time course array used for similarity calculations.
+        offset : float, optional
+            Time offset to apply to the reference time axis (default is 0.0).
+
+        Returns
+        -------
+        None
+            This function modifies instance attributes in-place and does not return anything.
+
+        Notes
+        -----
+        This function performs the following operations:
+        1. Creates a copy of the reference time course
+        2. Computes preprocessed reference time course using preptc method
+        3. Calculates similarity function length and origin
+        4. Constructs time axis based on sampling frequency and offset
+
+        The time axis is centered around zero with the specified offset applied.
+
+        Examples
+        --------
+        >>> setreftc(reftc_array, offset=0.5)
+        >>> print(self.timeaxis)
+        >>> print(self.similarityfunclen)
+        """
         self.reftc = reftc + 0.0
         self.prepreftc = self.preptc(self.reftc, isreftc=True)
         self.similarityfunclen = len(self.reftc) * 2 - 1
@@ -324,7 +812,40 @@ class Correlator(SimilarityFunctionator):
         self.timeaxisvalid = True
         self.datavalid = False
 
-    def run(self, thetc, trim=True):
+    def run(self, thetc: NDArray, trim: bool = True) -> tuple[NDArray, NDArray, int]:
+        """
+        Compute the correlation between test and reference timecourses.
+
+        This function performs correlation analysis between a test timecourse and a reference
+        timecourse, applying preprocessing and optional filtering. It returns the similarity
+        function, time axis, and the index of the global maximum.
+
+        Parameters
+        ----------
+        thetc : ndarray
+            Test timecourse to be correlated with the reference timecourse.
+        trim : bool, optional
+            If True, trims the similarity function and time axis to remove zero-padding
+            effects. Default is True.
+
+        Returns
+        -------
+        tuple of (ndarray, ndarray, int)
+            A tuple containing:
+                - similarity function (ndarray)
+                - time axis (ndarray)
+                - index of the global maximum (int)
+
+        Notes
+        -----
+        The function exits with status code 1 if the lengths of `thetc` and `self.reftc`
+        do not match.
+
+        Examples
+        --------
+        >>> result = correlator.run(test_timecourse, trim=True)
+        >>> similarity_func, time_axis, max_index = result
+        """
         if len(thetc) != len(self.reftc):
             print(
                 "Correlator: timecourses are of different sizes:",
@@ -428,43 +949,70 @@ class SimilarityFunctionFitter:
         functype="correlation",
         peakfittype="gauss",
     ):
-        r"""
+        """
+        Initialize a correlation peak finder.
+
+        This constructor sets up the parameters for fitting and searching correlation
+        functions to find peak locations, amplitudes, and widths.
 
         Parameters
         ----------
-        corrtimeaxis:  1D float array
-            The time axis of the correlation function
-        lagmin: float
-            The minimum allowed lag time in seconds
-        lagmax: float
-            The maximum allowed lag time in seconds
-        absmaxsigma: float
-            The maximum allowed peak halfwidth in seconds
-        hardlimit
-        bipolar: boolean
-            If true find the correlation peak with the maximum absolute value, regardless of sign
-        lthreshval
-        uthreshval
-        debug
-        zerooutbadfit
-        maxguess
-        useguess
-        searchfrac
-        lagmod
-        enforcethresh
-        displayplots
+        corrtimeaxis : 1D float array, optional
+            The time axis of the correlation function. Default is None.
+        lagmin : float, optional
+            The minimum allowed lag time in seconds. Default is -30.0.
+        lagmax : float, optional
+            The maximum allowed lag time in seconds. Default is 30.0.
+        absmaxsigma : float, optional
+            The maximum allowed peak halfwidth in seconds. Default is 1000.0.
+        absminsigma : float, optional
+            The minimum allowed peak halfwidth in seconds. Default is 0.25.
+        hardlimit : bool, optional
+            If True, enforce hard limits on peak fitting. Default is True.
+        bipolar : bool, optional
+            If True, find the correlation peak with the maximum absolute value,
+            regardless of sign. Default is False.
+        lthreshval : float, optional
+            Lower threshold value for correlation function. Default is 0.0.
+        uthreshval : float, optional
+            Upper threshold value for correlation function. Default is 1.0.
+        debug : bool, optional
+            If True, enable debug output. Default is False.
+        zerooutbadfit : bool, optional
+            If True, set bad fits to zero. Default is True.
+        maxguess : float, optional
+            Maximum guess for peak fitting. Default is 0.0.
+        useguess : bool, optional
+            If True, use initial guess for peak fitting. Default is False.
+        searchfrac : float, optional
+            Fraction of the search range to consider for peak fitting. Default is 0.5.
+        lagmod : float, optional
+            Modulus for lag values. Default is 1000.0.
+        enforcethresh : bool, optional
+            If True, enforce threshold constraints. Default is True.
+        allowhighfitamps : bool, optional
+            If True, allow high amplitude fits. Default is False.
+        displayplots : bool, optional
+            If True, display plots during fitting. Default is False.
+        functype : str, optional
+            Type of function to fit. Either "correlation" or "mutualinfo". Default is "correlation".
+        peakfittype : str, optional
+            Type of peak fit to use. Default is "gauss".
 
         Returns
         -------
-
-
-        Methods
-        -------
-        fit(corrfunc):
-            Fit the correlation function given in corrfunc and return the location of the peak in seconds, the maximum
-            correlation value, the peak width
-        setrange(lagmin, lagmax):
-            Specify the search range for lag peaks, in seconds
+        None
+            This method initializes the object and does not return any value.
+
+        Notes
+        -----
+        The `corrtimeaxis` must be provided before calling `fit()` method.
+        The `functype` parameter determines whether to fit a correlation or mutual information function.
+
+        Examples
+        --------
+        >>> peakfinder = PeakFinder(corrtimeaxis=time_axis, lagmin=-20, lagmax=20)
+        >>> peak_location, peak_value, peak_width = peakfinder.fit(correlation_data)
         """
         self.setcorrtimeaxis(corrtimeaxis)
         self.lagmin = lagmin + 0.0
@@ -491,16 +1039,40 @@ class SimilarityFunctionFitter:
         self.allowhighfitamps = allowhighfitamps
         self.displayplots = displayplots
 
-    def _maxindex_noedge(self, corrfunc):
+    def _maxindex_noedge(self, corrfunc: NDArray) -> tuple[int, float]:
         """
+        Find the index of the maximum value in correlation function, avoiding edge effects.
+
+        This function searches for the maximum value in the correlation function while
+        avoiding the edges of the data. It handles bipolar correlation functions by
+        considering both positive and negative peaks, returning the one with the larger
+        absolute value. The function also accounts for edge effects by adjusting the
+        search boundaries when the maximum is found at the edge.
 
         Parameters
         ----------
-        corrfunc
+        corrfunc : NDArray
+            Correlation function array to search for maximum value
 
         Returns
         -------
-
+        tuple[int, float]
+            Tuple containing:
+            - maxindex: Index of the maximum value in the correlation function
+            - flipfac: Flipping factor (-1.0 if minimum was selected, 1.0 otherwise)
+
+        Notes
+        -----
+        The function adjusts search boundaries to avoid edge effects:
+        - If maximum is at index 0, lowerlim is incremented
+        - If maximum is at upper limit, upperlim is decremented
+        - For bipolar correlation functions, both positive and negative peaks are considered
+        - The search continues until no edge effects are detected
+
+        Examples
+        --------
+        >>> max_index, flip_factor = obj._maxindex_noedge(corrfunc)
+        >>> print(f"Maximum at index {max_index} with flip factor {flip_factor}")
         """
         lowerlim = 0
         upperlim = len(self.corrtimeaxis) - 1
@@ -524,33 +1096,269 @@ class SimilarityFunctionFitter:
                 done = False
         return maxindex, flipfac
 
-    def setfunctype(self, functype):
+    def setfunctype(self, functype: str) -> None:
+        """
+        Set the function type for the object.
+
+        Parameters
+        ----------
+        functype : str
+            The function type to be set. This should be a string identifier
+            that defines the type of function this object represents.
+
+        Returns
+        -------
+        None
+            This method does not return any value.
+
+        Notes
+        -----
+        This method directly assigns the provided function type to the
+        internal `functype` attribute of the object.
+
+        Examples
+        --------
+        >>> obj = MyClass()
+        >>> obj.setfunctype('linear')
+        >>> obj.functype
+        'linear'
+        """
         self.functype = functype
 
-    def setpeakfittype(self, peakfittype):
+    def setpeakfittype(self, peakfittype: str) -> None:
+        """
+        Set the peak fitting type for the analysis.
+
+        Parameters
+        ----------
+        peakfittype : str
+            The type of peak fitting to be used. This parameter determines the
+            mathematical model and fitting algorithm applied to the peak data.
+
+        Returns
+        -------
+        None
+            This method does not return any value.
+
+        Notes
+        -----
+        This method directly assigns the provided peak fitting type to the
+        instance variable `self.peakfittype`. The valid values for peakfittype
+        depend on the specific implementation of the peak fitting algorithms
+        available in the class.
+
+        Examples
+        --------
+        >>> analyzer = PeakAnalyzer()
+        >>> analyzer.setpeakfittype('gaussian')
+        >>> print(analyzer.peakfittype)
+        'gaussian'
+        """
         self.peakfittype = peakfittype
 
-    def setrange(self, lagmin, lagmax):
+    def setrange(self, lagmin: float, lagmax: float) -> None:
+        """
+        Set the range of lags for the analysis.
+
+        Parameters
+        ----------
+        lagmin : float
+            The minimum lag value for the analysis range.
+        lagmax : float
+            The maximum lag value for the analysis range.
+
+        Returns
+        -------
+        None
+            This method does not return any value.
+
+        Notes
+        -----
+        This method updates the internal lag range parameters of the object.
+        The lagmin value should be less than or equal to the lagmax value.
+
+        Examples
+        --------
+        >>> obj = MyClass()
+        >>> obj.setrange(0.0, 10.0)
+        >>> print(obj.lagmin)
+        0.0
+        >>> print(obj.lagmax)
+        10.0
+        """
         self.lagmin = lagmin
         self.lagmax = lagmax
 
-    def setcorrtimeaxis(self, corrtimeaxis):
+    def setcorrtimeaxis(self, corrtimeaxis: NDArray | None) -> None:
+        """
+        Set the correlation time axis for the object.
+
+        This method assigns the provided correlation time axis to the object's
+        `corrtimeaxis` attribute. If the input is not None, a copy of the array is
+        created to avoid modifying the original data.
+
+        Parameters
+        ----------
+        corrtimeaxis : NDArray | None
+            The correlation time axis array to be set. If None, the attribute will
+            be set to None. If an array is provided, a copy will be created to
+            prevent modification of the original array.
+
+        Returns
+        -------
+        None
+            This method does not return any value.
+
+        Notes
+        -----
+        When a numpy array is passed, the method creates a copy using `+ 0.0`
+        to ensure that modifications to the original array do not affect the
+        object's internal state.
+
+        Examples
+        --------
+        >>> obj.setcorrtimeaxis(np.array([1, 2, 3, 4]))
+        >>> obj.setcorrtimeaxis(None)
+        """
         if corrtimeaxis is not None:
             self.corrtimeaxis = corrtimeaxis + 0.0
         else:
             self.corrtimeaxis = corrtimeaxis
 
-    def setguess(self, useguess, maxguess=0.0):
+    def setguess(self, useguess: bool, maxguess: float = 0.0) -> None:
+        """
+        Set the guess parameters for the optimization process.
+
+        This method configures whether to use a guess value and sets the maximum
+        guess value for optimization algorithms.
+
+        Parameters
+        ----------
+        useguess : bool
+            Flag indicating whether to use a guess value in the optimization process.
+            If True, the algorithm will attempt to use the provided guess value.
+            If False, no guess value will be used.
+        maxguess : float, optional
+            Maximum guess value to be used in the optimization process. Default is 0.0.
+            This parameter is only relevant when useguess is True.
+
+        Returns
+        -------
+        None
+            This method does not return any value.
+
+        Notes
+        -----
+        The maxguess parameter is typically used to constrain the search space
+        during optimization. When useguess is False, the maxguess parameter has
+        no effect on the optimization process.
+
+        Examples
+        --------
+        >>> optimizer = Optimizer()
+        >>> optimizer.setguess(True, 10.0)
+        >>> optimizer.setguess(False)
+        """
         self.useguess = useguess
         self.maxguess = maxguess
 
-    def setlthresh(self, lthreshval):
+    def setlthresh(self, lthreshval: float) -> None:
+        """
+        Set the lower threshold value for the object.
+
+        Parameters
+        ----------
+        lthreshval : float
+            The lower threshold value to be set. This value will be assigned to
+            the instance attribute `lthreshval`.
+
+        Returns
+        -------
+        None
+            This method does not return any value.
+
+        Notes
+        -----
+        This method assigns the provided threshold value to the instance attribute
+        `lthreshval`. The threshold value is typically used for filtering or
+        processing operations where values below this threshold are treated
+        differently.
+
+        Examples
+        --------
+        >>> obj = MyClass()
+        >>> obj.setlthresh(0.5)
+        >>> print(obj.lthreshval)
+        0.5
+        """
         self.lthreshval = lthreshval
 
-    def setuthresh(self, uthreshval):
+    def setuthresh(self, uthreshval: float) -> None:
+        """
+        Set the upper threshold value for the object.
+
+        Parameters
+        ----------
+        uthreshval : float
+            The upper threshold value to be set. This value will be assigned to
+            the object's internal `uthreshval` attribute.
+
+        Returns
+        -------
+        None
+            This method does not return any value.
+
+        Notes
+        -----
+        This method directly assigns the provided threshold value to the object's
+        internal attribute. No validation or processing is performed on the input value.
+
+        Examples
+        --------
+        >>> obj = MyClass()
+        >>> obj.setuthresh(0.5)
+        >>> print(obj.uthreshval)
+        0.5
+        """
         self.uthreshval = uthreshval
 
-    def diagnosefail(self, failreason):
+    def diagnosefail(self, failreason: Any) -> str:
+        """
+        Diagnose the cause of a failure based on bitwise flags.
+
+        This function takes a failure reason encoded as a bitwise flag and returns
+        a human-readable string describing the cause(s) of the failure. Each flag
+        corresponds to a specific condition that may have led to the failure.
+
+        Parameters
+        ----------
+        failreason : Any
+            A value representing the failure reason, typically an integer or array
+            of integers. It is cast to `np.uint32` for bitwise operations.
+
+        Returns
+        -------
+        str
+            A comma-separated string listing the reasons for the failure. If no
+            reasons are found, returns "No error".
+
+        Notes
+        -----
+        The function checks the following flags:
+        - ``FML_INITAMPLOW``, ``FML_INITAMPHIGH``, ``FML_INITWIDTHLOW``,
+          ``FML_INITWIDTHHIGH``, ``FML_INITLAGLOW``, ``FML_INITLAGHIGH``:
+          Initial parameter values are out of bounds.
+        - ``FML_FITAMPLOW``, ``FML_FITAMPHIGH``, ``FML_FITWIDTHLOW``,
+          ``FML_FITWIDTHHIGH``, ``FML_FITLAGLOW``, ``FML_FITLAGHIGH``:
+          Fit parameter values are out of bounds.
+        - ``FML_FITALGOFAIL``: Nonlinear fitting algorithm failed.
+
+        Examples
+        --------
+        >>> diagnosis = obj.diagnosefail(0x0001)
+        >>> print(diagnosis)
+        'Initial amplitude too low'
+        """
         # define error values
         reasons = []
         if failreason.astype(np.uint32) & self.FML_INITAMPLOW:
@@ -586,7 +1394,52 @@ class SimilarityFunctionFitter:
         else:
             return "No error"
 
-    def fit(self, incorrfunc):
+    def fit(self, incorrfunc: NDArray) -> tuple[int, float, float, float, int, Any, int, int]:
+        """
+        Fit a correlation function to determine peak parameters including lag, amplitude, and width.
+
+        This function performs a fit on the provided correlation function to extract key parameters
+        such as the peak lag, amplitude, and width. It supports multiple fitting methods and handles
+        various edge cases including invalid inputs, out-of-bounds values, and fitting failures.
+
+        Parameters
+        ----------
+        incorrfunc : ndarray
+            The input correlation function to be fitted. Must match the length of `self.corrtimeaxis`.
+
+        Returns
+        -------
+        tuple[int, float, float, float, int, Any, int, int]
+            A tuple containing:
+
+            - `maxindex` (int): Index of the maximum value in the correlation function.
+            - `maxlag` (float): The lag corresponding to the peak, in seconds.
+            - `maxval` (float): The amplitude of the peak, adjusted for flip factor.
+            - `maxsigma` (float): The width of the peak, in seconds.
+            - `maskval` (int): A flag indicating fit success (1) or failure (0).
+            - `failreason` (Any): A bitmask indicating the reason for fit failure, if any.
+            - `peakstart` (int): Start index of the peak region used in fitting.
+            - `peakend` (int): End index of the peak region used in fitting.
+
+        Notes
+        -----
+        The function performs several checks:
+
+        - Ensures `self.corrtimeaxis` is defined and matches the input length.
+        - Handles bipolar correlation functions and adjusts signs accordingly.
+        - Applies initial parameter estimation based on the input data.
+        - Supports multiple fitting algorithms including Gaussian, quadratic, and center-of-mass.
+        - Applies bounds checking for lag, amplitude, and width to ensure physical validity.
+        - Outputs debugging information if `self.debug` is set to True.
+
+        Examples
+        --------
+        >>> # Assuming `fit_instance` is an instance of the class containing this method
+        >>> corr_func = np.array([0.1, 0.5, 1.0, 0.5, 0.1])
+        >>> result = fit_instance.fit(corr_func)
+        >>> print(result)
+        (2, 1.0, 1.0, 0.5, 1, 0, 1, 3)
+        """
         # check to make sure xcorr_x and xcorr_y match
         if self.corrtimeaxis is None:
             print("Correlation time axis is not defined - exiting")
@@ -694,9 +1547,17 @@ class SimilarityFunctionFitter:
                 while peakpoints[peakstart - 1] == 1:
                     peakstart -= 1
             else:
-                while thegrad[peakend + 1] <= 0.0 and peakpoints[peakend + 1] == 1 and peakend < len(self.corrtimeaxis) - 2:
+                while (
+                    thegrad[peakend + 1] <= 0.0
+                    and peakpoints[peakend + 1] == 1
+                    and peakend < len(self.corrtimeaxis) - 2
+                ):
                     peakend += 1
-                while thegrad[peakstart - 1] >= 0.0 and peakpoints[peakstart - 1] == 1 and peakstart >= 1:
+                while (
+                    thegrad[peakstart - 1] >= 0.0
+                    and peakpoints[peakstart - 1] == 1
+                    and peakstart >= 1
+                ):
                     peakstart -= 1
             if self.debug:
                 print("final peakstart, peakend:", peakstart, peakend)
@@ -887,7 +1748,7 @@ class SimilarityFunctionFitter:
                     if self.debug:
                         print("poly coffs:", a, b, c)
                         print("maxlag, maxval, maxsigma:", maxlag, maxval, maxsigma)
-                except np.lib.polynomial.RankWarning:
+                except np.exceptions.RankWarning:
                     failreason |= self.FML_FITALGOFAIL
                     maxlag = 0.0
                     maxval = 0.0
@@ -1030,7 +1891,45 @@ class FrequencyTracker:
     freqs = None
     times = None
 
-    def __init__(self, lowerlim=0.1, upperlim=0.6, nperseg=32, Q=10.0, debug=False):
+    def __init__(
+        self,
+        lowerlim: float = 0.1,
+        upperlim: float = 0.6,
+        nperseg: int = 32,
+        Q: float = 10.0,
+        debug: bool = False,
+    ) -> None:
+        """
+        Initialize the object with spectral analysis parameters.
+
+        Parameters
+        ----------
+        lowerlim : float, optional
+            Lower frequency limit for spectral analysis, default is 0.1
+        upperlim : float, optional
+            Upper frequency limit for spectral analysis, default is 0.6
+        nperseg : int, optional
+            Number of samples per segment for spectral analysis, default is 32
+        Q : float, optional
+            Quality factor for spectral analysis, default is 10.0
+        debug : bool, optional
+            Debug flag for verbose output, default is False
+
+        Returns
+        -------
+        None
+            This method initializes the object attributes and does not return any value.
+
+        Notes
+        -----
+        The ``nfft`` attribute is set equal to ``nperseg`` during initialization.
+
+        Examples
+        --------
+        >>> obj = MyClass(lowerlim=0.2, upperlim=0.8, nperseg=64)
+        >>> print(obj.lowerlim)
+        0.2
+        """
         self.lowerlim = lowerlim
         self.upperlim = upperlim
         self.nperseg = nperseg
@@ -1038,7 +1937,46 @@ class FrequencyTracker:
         self.debug = debug
         self.nfft = self.nperseg
 
-    def track(self, x, fs):
+    def track(self, x: NDArray, fs: float) -> tuple[NDArray, NDArray]:
+        """
+        Track peak frequencies in a signal using spectrogram analysis and peak fitting.
+
+        This function computes the spectrogram of the input signal, then tracks the
+        dominant frequency component over time by fitting peaks in each time segment.
+        The result is a tuple of time indices and corresponding peak frequencies.
+
+        Parameters
+        ----------
+        x : NDArray
+            Input signal array to be analyzed.
+        fs : float
+            Sampling frequency of the input signal in Hz.
+
+        Returns
+        -------
+        tuple[NDArray, NDArray]
+            A tuple containing:
+            - times : NDArray
+                Time indices corresponding to the tracked peaks (excluding the last time bin).
+            - peakfreqs : NDArray
+                Array of peak frequencies corresponding to each time segment.
+                If no valid peak is found within the specified frequency range,
+                the value is set to -1.0.
+
+        Notes
+        -----
+        - The input signal is padded with zeros at both ends to reduce edge effects.
+        - The spectrogram is computed using a Hamming window and no overlap between segments.
+        - Peak fitting is performed using a fast quadratic method.
+        - Frequencies outside the range defined by `self.lowerlim` and `self.upperlim`
+          are marked as invalid (set to -1.0).
+
+        Examples
+        --------
+        >>> times, peakfreqs = obj.track(signal, fs)
+        >>> print(f"Peak frequencies: {peakfreqs}")
+        >>> print(f"Time indices: {times}")
+        """
         self.freqs, self.times, thespectrogram = sp.signal.spectrogram(
             np.concatenate(
                 [np.zeros(int(self.nperseg // 2)), x, np.zeros(int(self.nperseg // 2))],
@@ -1088,7 +2026,44 @@ class FrequencyTracker:
 
         return self.times[:-1], peakfreqs
 
-    def clean(self, x, fs, times, peakfreqs, numharmonics=2):
+    def clean(
+        self, x: NDArray, fs: float, times: NDArray, peakfreqs: NDArray, numharmonics: int = 2
+    ) -> NDArray:
+        """
+        Apply harmonic cleaning to a signal based on detected peak frequencies and their harmonics.
+
+        This function cleans a signal by applying bandpass filtering to specific time intervals
+        centered at given peak frequencies. It supports filtering of harmonics up to a specified
+        number and handles edge effects through padding.
+
+        Parameters
+        ----------
+        x : ndarray
+            Input signal to be cleaned.
+        fs : float
+            Sampling frequency of the signal in Hz.
+        times : ndarray
+            Array of time indices (in seconds) where cleaning is applied.
+        peakfreqs : ndarray
+            Array of peak frequencies (in Hz) corresponding to each time index.
+        numharmonics : int, optional
+            Maximum number of harmonics to filter (default is 2).
+
+        Returns
+        -------
+        ndarray
+            Cleaned signal with harmonics filtered out.
+
+        Notes
+        -----
+        - The function uses Chebyshev type II filter design for each harmonic.
+        - Harmonics are filtered using `scipy.signal.filtfilt` for zero-phase filtering.
+        - Edge effects are mitigated by padding the input signal with zeros.
+
+        Examples
+        --------
+        >>> cleaned_signal = obj.clean(x, fs=1000.0, times=[0.1, 0.5], peakfreqs=[50.0, 100.0])
+        """
         nyquistfreq = 0.5 * fs
         y = x * 0.0
         halfwidth = int(self.nperseg // 2)