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

rapidtide/resample.py

@@ -31,14 +31,18 @@ with warnings.catch_warnings():
     else:
         pyfftwpresent = True
 
-import pylab as pl
+from typing import Any, Callable, Optional, Tuple, Union
+
+import matplotlib.pyplot as plt
 import scipy as sp
+from numpy.typing import ArrayLike, NDArray
 from scipy import fftpack, signal
 
 import rapidtide.filter as tide_filt
 import rapidtide.fit as tide_fit
 import rapidtide.io as tide_io
 import rapidtide.util as tide_util
+from rapidtide.decorators import conditionaljit, conditionaljit2
 
 if pyfftwpresent:
     fftpack = pyfftw.interfaces.scipy_fftpack
@@ -50,125 +54,77 @@ import warnings
 
 warnings.simplefilter(action="ignore", category=RuntimeWarning)
 
-# ---------------------------------------- Global constants -------------------------------------------
-donotbeaggressive = True
-
-# ----------------------------------------- Conditional imports ---------------------------------------
-try:
-    from numba import jit
-except ImportError:
-    donotusenumba = True
-else:
-    donotusenumba = False
-
-
-def conditionaljit():
-    def resdec(f):
-        if donotusenumba:
-            return f
-        return jit(f, nopython=True)
-
-    return resdec
-
-
-def conditionaljit2():
-    def resdec(f):
-        if donotusenumba or donotbeaggressive:
-            return f
-        return jit(f, nopython=True)
-
-    return resdec
-
-
-def disablenumba():
-    global donotusenumba
-    donotusenumba = True
-
-
 # --------------------------- Resampling and time shifting functions -------------------------------------------
-"""
-class ConvolutionGridder:
-    def __init__(self, timeaxis, width, method='gauss', circular=True, upsampleratio=100, doplot=False, debug=False):
-        self.upsampleratio = upsampleratio
-        self.initstep = timeaxis[1] - timeaxis[0]
-        self.initstart = timeaxis[0]
-        self.initend = timeaxis[-1]
-        self.hiresstep = self.initstep / np.float64(self.upsampleratio)
-        if method == 'gauss':
-            fullwidth = 2.355 * width
-        fullwidthpts = int(np.round(fullwidth / self.hiresstep, 0))
-        fullwidthpts += ((fullwidthpts % 2) - 1)
-        self.hires_x = np.linspace(-fullwidth / 2.0, fullwidth / 2.0, numpts = fullwidthpts, endpoint=True)
-        if method == 'gauss':
-            self.hires_y = tide_fit.gauss_eval(self.hires_x, np.array([1.0, 0.0, width])
-        if debug:
-            print(self.hires_x)
-        if doplot:
-            fig = pl.figure()
-            ax = fig.add_subplot(111)
-            ax.set_title('congrid convolution function')
-            pl.plot(self.hires_x, self.hires_y)
-            pl.legend(('input', 'hires'))
-            pl.show()
-
-    def gridded(xvals, yvals):
-        if len(xvals) != len(yvals):
-            print('x and y vectors do not match - aborting')
-            return None
-        for i in range(len(xvals)):
-        outindices = ((newtimeaxis - self.hiresstart) // self.hiresstep).astype(int)
-"""
-
-congridyvals = {}
+congridyvals: dict = {}
 congridyvals["kernel"] = "kaiser"
 congridyvals["width"] = 3.0
 
 
 def congrid(
-    xaxis,
-    loc,
-    val,
-    width,
-    kernel="kaiser",
-    cache=True,
-    cyclic=True,
-    debug=False,
-    onlykeynotices=True,
-):
+    xaxis: NDArray[np.floating[Any]],
+    loc: float,
+    val: float,
+    width: float,
+    kernel: str = "kaiser",
+    cache: bool = True,
+    cyclic: bool = True,
+    debug: bool = False,
+    onlykeynotices: bool = True,
+) -> Tuple[NDArray[np.floating[Any]], NDArray[np.floating[Any]], NDArray[np.floating[Any]]]:
     """
-    Perform a convolution gridding operation with a Kaiser-Bessel or Gaussian kernel of width 'width'.  Grid
-    parameters are cached for performance.
+    Perform a convolution gridding operation with a Kaiser-Bessel or Gaussian kernel.
+
+    This function convolves a given value with a specified gridding kernel and projects
+    the result onto a target axis. It supports both cyclic and non-cyclic boundary
+    conditions and caches kernel values for performance optimization.
 
     Parameters
     ----------
-    xaxis: array-like
-        The target axis for resampling
-    loc: float
-        The location, in x-axis units, of the sample to be gridded
-    val: float
-        The value to be gridded
-    width: float
-        The width of the gridding kernel in target bins
-    kernel: {'old', 'gauss', 'kaiser'}, optional
-        The type of convolution gridding kernel.  Default is 'kaiser'.
-    cyclic: bool, optional
-        When True, gridding wraps around the endpoints of xaxis.  Default is True.
-    debug: bool, optional
-        When True, output additional information about the gridding process
+    xaxis : NDArray[np.floating[Any]]
+        The target axis for resampling. Should be a 1D array of evenly spaced points.
+    loc : float
+        The location, in x-axis units, of the sample to be gridded.
+    val : float
+        The value to be gridded.
+    width : float
+        The width of the gridding kernel in target bins. Must be a half-integral value
+        between 1.5 and 5.0 inclusive.
+    kernel : {'old', 'gauss', 'kaiser'}, optional
+        The type of convolution gridding kernel. Default is 'kaiser'.
+        - 'old': Uses a Gaussian kernel with fixed width.
+        - 'gauss': Uses a Gaussian kernel with optimized sigma.
+        - 'kaiser': Uses a Kaiser-Bessel kernel with optimized beta.
+    cache : bool, optional
+        If True, caches kernel values for performance. Default is True.
+    cyclic : bool, optional
+        When True, gridding wraps around the endpoints of xaxis. Default is True.
+    debug : bool, optional
+        When True, outputs additional information about the gridding process.
+        Default is False.
+    onlykeynotices : bool, optional
+        When True, suppresses certain debug messages. Default is True.
 
     Returns
     -------
-    vals: array-like
-        The input value, convolved with the gridding kernel, projected on to x axis points
-    weights: array-like
-        The values of convolution kernel, projected on to x axis points (used for normalization)
-    indices: array-like
-        The indices along the x axis where the vals and weights fall.
+    vals : NDArray[np.floating[Any]]
+        The input value, convolved with the gridding kernel, projected onto x-axis points.
+    weights : NDArray[np.floating[Any]]
+        The values of the convolution kernel, projected onto x-axis points (used for normalization).
+    indices : NDArray[int[Any]]
+        The indices along the x-axis where the vals and weights fall.
 
     Notes
     -----
-    See  IEEE TRANSACTIONS ON MEDICAL IMAGING. VOL. IO.NO. 3, SEPTEMBER 1991
-
+    This implementation is based on the method described in:
+    IEEE TRANSACTIONS ON MEDICAL IMAGING. VOL. 10, NO. 3, SEPTEMBER 1991
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> xaxis = np.linspace(0, 10, 100)
+    >>> vals, weights, indices = congrid(xaxis, 5.5, 1.0, 2.0)
+    >>> print(vals.shape)
+    (100,)
     """
     global congridyvals
 
@@ -247,7 +203,7 @@ def congrid(
         offsetinpts = center + offset
         startpt = int(np.ceil(offsetinpts - width / 2.0))
         endpt = int(np.floor(offsetinpts + width / 2.0))
-        indices = np.remainder(range(startpt, endpt + 1), len(xaxis))
+        indices = np.remainder(np.array(list(range(startpt, endpt + 1))), len(xaxis))
         try:
             yvals = congridyvals[offsetkey]
         except KeyError:
@@ -283,6 +239,53 @@ class FastResampler:
         debug=False,
         method="univariate",
     ):
+        """
+        Initialize the FastResampler with given time axis and time course data.
+
+        This constructor prepares high-resolution time series data by resampling the input
+        time course using one of several methods, with optional padding and plotting.
+
+        Parameters
+        ----------
+        timeaxis : array-like
+            The time axis of the input data. Should be a 1D array of time points.
+        timecourse : array-like
+            The time course data corresponding to `timeaxis`. Should be a 1D array of values.
+        padtime : float, optional
+            Padding time in seconds to extend the resampled time axis on both ends.
+            Default is 30.0.
+        upsampleratio : int, optional
+            The upsampling ratio used for resampling. Default is 100.
+        doplot : bool, optional
+            If True, plot the original and high-resolution time courses. Default is False.
+        debug : bool, optional
+            If True, print debug information during initialization. Default is False.
+        method : str, optional
+            Resampling method to use. Options are:
+            - "univariate": Uses custom resampling logic.
+            - "poly": Uses `scipy.signal.resample_poly`.
+            - "fourier": Uses `scipy.signal.resample`.
+            Default is "univariate".
+
+        Returns
+        -------
+        None
+            This method initializes instance attributes and does not return a value.
+
+        Notes
+        -----
+        The resampled time axis (`hires_x`) is generated by extending the original time axis
+        by `padtime` on each side, using a step size that is `1 / upsampleratio` of the
+        original step size. The `hires_y` array contains the resampled time course values.
+
+        Examples
+        --------
+        >>> import numpy as np
+        >>> from scipy import signal
+        >>> timeaxis = np.linspace(0, 10, 100)
+        >>> timecourse = np.sin(timeaxis)
+        >>> resampler = FastResampler(timeaxis, timecourse, padtime=5.0, method="poly")
+        """
         self.timeaxis = timeaxis
         self.timecourse = timecourse
         self.upsampleratio = upsampleratio
@@ -331,17 +334,98 @@ class FastResampler:
         if doplot:
             import matplolib.pyplot as pl
 
-            fig = pl.figure()
+            fig = plt.figure()
             ax = fig.add_subplot(111)
             ax.set_title("FastResampler initial timecourses")
-            pl.plot(timeaxis, timecourse, self.hires_x, self.hires_y)
-            pl.legend(("input", "hires"))
-            pl.show()
+            plt.plot(timeaxis, timecourse, self.hires_x, self.hires_y)
+            plt.legend(("input", "hires"))
+            plt.show()
 
     def getdata(self):
+        """
+        Retrieve time series data and related parameters.
+
+        Returns
+        -------
+        tuple
+            A tuple containing:
+            - timeaxis : array_like
+                Time axis values
+            - timecourse : array_like
+                Time course data values
+            - hires_x : array_like
+                High resolution x-axis data
+            - hires_y : array_like
+                High resolution y-axis data
+            - inverse_initstep : float
+                Reciprocal of the initial step size (1.0 / self.initstep)
+
+        Notes
+        -----
+        This function provides access to all time series data and associated
+        high resolution parameters stored in the object instance. The returned
+        inverse_initstep value is commonly used for normalization or scaling
+        operations in time series analysis.
+
+        Examples
+        --------
+        >>> data = obj.getdata()
+        >>> time_axis, time_course, hires_x, hires_y, inv_step = data
+        >>> print(f"Time course shape: {time_course.shape}")
+        """
         return self.timeaxis, self.timecourse, self.hires_x, self.hires_y, 1.0 / self.initstep
 
     def info(self, prefix=""):
+        """
+        Print information about the object's time and sampling parameters.
+
+        This method displays various time-related attributes and sampling parameters
+        of the object, with optional prefix for better formatting in output.
+
+        Parameters
+        ----------
+        prefix : str, optional
+            String to prepend to each printed line, useful for indentation or
+            grouping related output. Default is empty string.
+
+        Returns
+        -------
+        None
+            This method prints information to stdout and does not return any value.
+
+        Notes
+        -----
+        The method prints the following attributes:
+        - timeaxis: Time axis values
+        - timecourse: Time course data
+        - upsampleratio: Upsampling ratio
+        - padtime: Padding time
+        - initstep: Initial step size
+        - initstart: Initial start time
+        - initend: Initial end time
+        - hiresstep: High-resolution step size
+        - hires_x[0]: First value of high-resolution x-axis
+        - hires_x[-1]: Last value of high-resolution x-axis
+        - hiresstart: High-resolution start time
+        - hiresend: High-resolution end time
+        - method: Interpolation/processing method used
+        - hires_y[0]: First value of high-resolution y-axis
+        - hires_y[-1]: Last value of high-resolution y-axis
+
+        Examples
+        --------
+        >>> obj.info()
+        timeaxis=100
+        timecourse=200
+        upsampleratio=4
+        ...
+
+        >>> obj.info(prefix="  ")
+          timeaxis=100
+          timecourse=200
+          upsampleratio=4
+          ...
+        """
         print(f"{prefix}{self.timeaxis=}")
         print(f"{prefix}{self.timecourse=}")
         print(f"{prefix}{self.upsampleratio=}")
@@ -359,6 +443,35 @@ class FastResampler:
         print(f"{prefix}{self.hires_y[-1]=}")
 
     def save(self, outputname):
+        """
+        Save the timecourse data to a TSV file.
+
+        This method writes the internal timecourse data to a tab-separated values file
+        with additional metadata in the header. The output includes the timecourse data
+        along with timing information derived from the object's initialization parameters.
+
+        Parameters
+        ----------
+        outputname : str
+            The path and filename where the TSV output will be saved.
+
+        Returns
+        -------
+        None
+            This method does not return any value.
+
+        Notes
+        -----
+        The method uses the `tide_io.writebidstsv` function to perform the actual file writing.
+        The time step is calculated as 1.0 divided by `self.initstep`, and the start time
+        is taken from `self.initstart`. The output file includes a header with description
+        metadata indicating this is a lagged timecourse generator.
+
+        Examples
+        --------
+        >>> obj.save("output_timecourse.tsv")
+        >>> # Creates a TSV file with the timecourse data and metadata
+        """
         tide_io.writebidstsv(
             outputname,
             self.timecourse,
@@ -370,6 +483,41 @@ class FastResampler:
         )
 
     def yfromx(self, newtimeaxis, doplot=False, debug=False):
+        """
+        Resample y-values from a high-resolution time axis to a new time axis.
+
+        This method maps values from a high-resolution y-array (`self.hires_y`) to a
+        new time axis (`newtimeaxis`) by linear interpolation based on the step size
+        and start of the high-resolution axis.
+
+        Parameters
+        ----------
+        newtimeaxis : array-like
+            The new time axis to which the y-values will be resampled.
+        doplot : bool, optional
+            If True, plot the original high-resolution y-values and the resampled
+            values for comparison. Default is False.
+        debug : bool, optional
+            If True, print debug information including internal parameters and
+            bounds checking. Default is False.
+
+        Returns
+        -------
+        out_y : ndarray
+            The resampled y-values corresponding to `newtimeaxis`.
+
+        Notes
+        -----
+        This function assumes that `self.hires_y` has been precomputed and that
+        the internal parameters (`self.hiresstart`, `self.hiresstep`) are valid.
+        An IndexError is raised if any index in `outindices` is out of bounds.
+
+        Examples
+        --------
+        >>> resampler = FastResampler()
+        >>> new_times = np.linspace(0, 10, 100)
+        >>> y_vals = resampler.yfromx(new_times, doplot=True)
+        """
         if debug:
             print("FastResampler: yfromx called with following parameters")
             print("    padtime:, ", self.padtime)
@@ -392,16 +540,59 @@ class FastResampler:
             print("    requested axis limits:", newtimeaxis[0], newtimeaxis[-1])
             sys.exit()
         if doplot:
-            fig = pl.figure()
+            fig = plt.figure()
             ax = fig.add_subplot(111)
             ax.set_title("FastResampler timecourses")
-            pl.plot(self.hires_x, self.hires_y, newtimeaxis, out_y)
-            pl.legend(("hires", "output"))
-            pl.show()
+            plt.plot(self.hires_x, self.hires_y, newtimeaxis, out_y)
+            plt.legend(("hires", "output"))
+            plt.show()
         return out_y
 
 
-def FastResamplerFromFile(inputname, colspec=None, debug=False, **kwargs):
+def FastResamplerFromFile(
+    inputname: str, colspec: Optional[str] = None, debug: bool = False, **kwargs
+) -> FastResampler:
+    """
+    Create a FastResampler from a BIDS TSV file.
+
+    This function reads data from a BIDS TSV file and creates a FastResampler object
+    for efficient time series resampling operations. The input file must contain
+    exactly one column of data.
+
+    Parameters
+    ----------
+    inputname : str
+        Path to the input BIDS TSV file containing the time series data
+    colspec : str, optional
+        Column specification for selecting specific columns from the TSV file.
+        If None, all columns are read (default: None)
+    debug : bool, optional
+        Enable debug output printing (default: False)
+    **kwargs
+        Additional keyword arguments passed to the FastResampler constructor
+
+    Returns
+    -------
+    FastResampler
+        A FastResampler object initialized with the time axis and data from the input file
+
+    Raises
+    ------
+    ValueError
+        If the input file contains multiple columns of data
+
+    Notes
+    -----
+    The function internally calls `tide_io.readbidstsv` to read the input file and
+    constructs a time axis using `np.linspace` based on the sampling rate and
+    start time from the input file.
+
+    Examples
+    --------
+    >>> resampler = FastResamplerFromFile('data.tsv')
+    >>> resampler = FastResamplerFromFile('data.tsv', colspec='column1')
+    >>> resampler = FastResamplerFromFile('data.tsv', debug=True)
+    """
     (
         insamplerate,
         instarttime,
@@ -425,29 +616,65 @@ def FastResamplerFromFile(inputname, colspec=None, debug=False, **kwargs):
 
 
 def doresample(
-    orig_x,
-    orig_y,
-    new_x,
-    method="cubic",
-    padlen=0,
-    padtype="reflect",
-    antialias=False,
-    debug=False,
-):
+    orig_x: ArrayLike,
+    orig_y: ArrayLike,
+    new_x: ArrayLike,
+    method: str = "cubic",
+    padlen: int = 0,
+    padtype: str = "reflect",
+    antialias: bool = False,
+    debug: bool = False,
+) -> NDArray:
     """
-    Resample data from one spacing to another.  By default, does not apply any antialiasing filter.
+    Resample data from one spacing to another.
+
+    By default, does not apply any antialiasing filter.
 
     Parameters
     ----------
-    orig_x
-    orig_y
-    new_x
-    method
-    padlen
+    orig_x : array-like
+        Original x-coordinates of the data to be resampled.
+    orig_y : array-like
+        Original y-values corresponding to `orig_x`.
+    new_x : array-like
+        New x-coordinates at which to evaluate the resampled data.
+    method : str, optional
+        Interpolation method to use. Options are:
+        - "cubic": cubic spline interpolation (default)
+        - "quadratic": quadratic spline interpolation
+        - "univariate": univariate spline interpolation using `scipy.interpolate.UnivariateSpline`
+    padlen : int, optional
+        Number of elements to pad the input data at both ends. Default is 0.
+    padtype : str, optional
+        Type of padding to use when `padlen > 0`. Default is "reflect".
+        Passed to `tide_filt.padvec`.
+    antialias : bool, optional
+        If True, apply an antialiasing filter before resampling if the original
+        sampling frequency is higher than the target frequency. Default is False.
+    debug : bool, optional
+        If True, print debug information and display a plot of the original and
+        padded data. Default is False.
 
     Returns
     -------
+    ndarray
+        Resampled y-values at coordinates specified by `new_x`. If an invalid
+        interpolation method is specified, returns None.
 
+    Notes
+    -----
+    - The function uses padding to handle edge effects during interpolation.
+    - When `antialias=True`, a non-causal filter is applied to reduce aliasing
+      artifacts when downsampling.
+    - The `tide_filt` module is used for padding and filtering operations.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> x = np.linspace(0, 10, 100)
+    >>> y = np.sin(x)
+    >>> new_x = np.linspace(0, 10, 200)
+    >>> y_resampled = doresample(x, y, new_x, method="cubic")
     """
     tstep = orig_x[1] - orig_x[0]
     if padlen > 0:
@@ -466,11 +693,11 @@ def doresample(
         print("lens:", len(pad_x), len(pad_y))
         print(pad_x)
         print(pad_y)
-        fig = pl.figure()
+        fig = plt.figure()
         ax = fig.add_subplot(111)
         ax.set_title("Original and padded vector")
-        pl.plot(orig_x, orig_y + 1.0, pad_x, pad_y)
-        pl.show()
+        plt.plot(orig_x, orig_y + 1.0, pad_x, pad_y)
+        plt.show()
 
     # antialias and ringstop filter
     init_freq = len(pad_x) / (pad_x[-1] - pad_x[0])
@@ -501,31 +728,75 @@ def doresample(
 
 
 def arbresample(
-    inputdata,
-    init_freq,
-    final_freq,
-    intermed_freq=0.0,
-    method="univariate",
-    antialias=True,
-    decimate=False,
-    debug=False,
-):
+    inputdata: ArrayLike,
+    init_freq: float,
+    final_freq: float,
+    intermed_freq: float = 0.0,
+    method: str = "univariate",
+    antialias: bool = True,
+    decimate: bool = False,
+    debug: bool = False,
+) -> NDArray:
     """
+    Resample input data from an initial frequency to a final frequency using either
+    direct resampling or a two-step process with intermediate frequency.
+
+    This function supports both upsampling and downsampling, with optional anti-aliasing
+    and decimation. It can operate in debug mode to print intermediate steps and
+    statistics.
 
     Parameters
     ----------
-    inputdata
-    init_freq
-    final_freq
-    intermed_freq
-    method
-    antialias
-    decimate
-    debug
+    inputdata : ArrayLike
+        Input signal or data to be resampled. Should be a 1-D array-like object.
+    init_freq : float
+        Initial sampling frequency of the input data in Hz.
+    final_freq : float
+        Target sampling frequency of the output data in Hz.
+    intermed_freq : float, optional
+        Intermediate sampling frequency used in the two-step resampling process.
+        If not specified (default: 0.0), it is automatically set to the maximum of
+        2 * init_freq and 2 * final_freq.
+    method : str, optional
+        Interpolation method to use for resampling. Default is "univariate".
+        Other options may be supported depending on the underlying implementation.
+    antialias : bool, optional
+        If True (default), apply anti-aliasing filter during downsampling using
+        `scipy.signal.decimate`. If False, use simple interpolation for downsampling.
+    decimate : bool, optional
+        If True, perform upsampling followed by decimation for downsampling.
+        If False, use a two-step resampling approach with `dotwostepresample`.
+        Default is False.
+    debug : bool, optional
+        If True, print debug information including number of points before and after
+        resampling, and intermediate steps. Default is False.
 
     Returns
     -------
+    NDArray
+        Resampled data as a NumPy array with length adjusted according to `final_freq`.
 
+    Notes
+    -----
+    - When `decimate=True`, the function uses integer decimation for efficient downsampling.
+    - For downsampling, if `antialias=False`, the function uses linear interpolation
+      instead of filtering to reduce computational cost.
+    - The `intermed_freq` is automatically calculated when `decimate=True` and
+      `final_freq < init_freq`.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> data = np.random.rand(100)
+    >>> resampled = arbresample(data, init_freq=100, final_freq=50, decimate=True)
+    >>> print(len(resampled))
+    50
+
+    See Also
+    --------
+    upsample : Function used for upsampling when `decimate=True`.
+    dotwostepresample : Function used for two-step resampling when `decimate=False`.
+    scipy.signal.decimate : Anti-aliasing filter used when `antialias=True`.
     """
     if debug:
         print("arbresample - initial points:", len(inputdata))
@@ -597,7 +868,62 @@ def arbresample(
         return resampled
 
 
-def upsample(inputdata, Fs_init, Fs_higher, method="univariate", intfac=False, dofilt=True, debug=False):
+def upsample(
+    inputdata: ArrayLike,
+    Fs_init: float,
+    Fs_higher: float,
+    method: str = "univariate",
+    intfac: bool = False,
+    dofilt: bool = True,
+    debug: bool = False,
+) -> NDArray:
+    """
+    Upsample input data to a higher sampling frequency.
+
+    This function increases the sampling rate of the input data using interpolation
+    and optional filtering. It supports different interpolation methods and allows
+    for control over the resampling factor and filtering behavior.
+
+    Parameters
+    ----------
+    inputdata : ArrayLike
+        Input time series data to be upsampled.
+    Fs_init : float
+        Initial sampling frequency of the input data (Hz).
+    Fs_higher : float
+        Target sampling frequency to upsample to (Hz). Must be greater than `Fs_init`.
+    method : str, optional
+        Interpolation method to use. Default is "univariate". Other options depend
+        on the implementation of `doresample`.
+    intfac : bool, optional
+        If True, use integer resampling factor based on `Fs_higher // Fs_init`.
+        If False, compute resampled points based on time duration. Default is False.
+    dofilt : bool, optional
+        If True, apply a non-causal filter to prevent aliasing. Default is True.
+    debug : bool, optional
+        If True, print timing information. Default is False.
+
+    Returns
+    -------
+    NDArray
+        Upsampled time series data with the new sampling frequency.
+
+    Notes
+    -----
+    - The function uses linear interpolation by default, but the actual method
+      depends on the `doresample` function implementation.
+    - If `dofilt` is True, a trapezoidal non-causal filter is applied with a
+      stop frequency set to the minimum of 1.1 * Fs_init / 2.0 and Fs_higher / 2.0.
+    - The function will terminate if `Fs_higher` is not greater than `Fs_init`.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> data = np.sin(np.linspace(0, 4*np.pi, 100))
+    >>> upsampled = upsample(data, Fs_init=10.0, Fs_higher=20.0)
+    >>> print(len(upsampled))
+    200
+    """
     starttime = time.time()
     if Fs_higher <= Fs_init:
         print("upsample: target frequency must be higher than initial frequency")
@@ -626,29 +952,60 @@ def upsample(inputdata, Fs_init, Fs_higher, method="univariate", intfac=False, d
 
 
 def dotwostepresample(
-    orig_x,
-    orig_y,
-    intermed_freq,
-    final_freq,
-    method="univariate",
-    antialias=True,
-    debug=False,
-):
+    orig_x: ArrayLike,
+    orig_y: ArrayLike,
+    intermed_freq: float,
+    final_freq: float,
+    method: str = "univariate",
+    antialias: bool = True,
+    debug: bool = False,
+) -> NDArray:
     """
+    Resample a signal from original frequency to final frequency using a two-step process:
+    first upsampling to an intermediate frequency, then downsampling to the final frequency.
+
+    This function performs resampling by first interpolating the input signal to an
+    intermediate frequency that is higher than the final desired frequency, followed by
+    downsampling to the target frequency. Optional antialiasing filtering is applied
+    during the upsampling step.
 
     Parameters
     ----------
-    orig_x
-    orig_y
-    intermed_freq
-    final_freq
-    method
-    debug
+    orig_x : array-like
+        Original time axis values (must be monotonically increasing).
+    orig_y : array-like
+        Original signal values corresponding to `orig_x`.
+    intermed_freq : float
+        Intermediate frequency to which the signal is upsampled.
+        Must be greater than `final_freq`.
+    final_freq : float
+        Target frequency to which the signal is downsampled.
+    method : str, optional
+        Interpolation method used for resampling. Default is "univariate".
+        Should be compatible with the `doresample` function.
+    antialias : bool, optional
+        If True, apply an antialiasing filter during upsampling. Default is True.
+    debug : bool, optional
+        If True, print timing and intermediate information. Default is False.
 
     Returns
     -------
-    resampled_y
+    ndarray
+        Resampled signal values at the final frequency.
 
+    Notes
+    -----
+    - The intermediate frequency must be strictly greater than the final frequency.
+    - The function uses `doresample` for interpolation and `tide_filt.NoncausalFilter`
+      for antialiasing if enabled.
+    - Timing information is printed when `debug=True`.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> x = np.linspace(0, 10, 100)
+    >>> y = np.sin(x)
+    >>> resampled = dotwostepresample(x, y, intermed_freq=50.0, final_freq=10.0)
     """
     if intermed_freq <= final_freq:
         print("intermediate frequency must be higher than final frequency")
@@ -698,20 +1055,56 @@ def dotwostepresample(
     return resampled_y
 
 
-def calcsliceoffset(sotype, slicenum, numslices, tr, multiband=1):
+def calcsliceoffset(
+    sotype: int, slicenum: int, numslices: int, tr: float, multiband: int = 1
+) -> float:
     """
+    Calculate slice timing offset for slice timing correction.
+
+    This function computes the timing offset (in seconds) for a given slice
+    based on the slice timing correction method specified by `sotype`. The
+    offset is used to align slice acquisition times for functional MRI data
+    preprocessing.
 
     Parameters
     ----------
-    sotype
-    slicenum
-    numslices
-    tr
-    multiband
+    sotype : int
+        Slice timing correction method:
+        - 0: None
+        - 1: Regular up (0, 1, 2, 3, ...)
+        - 2: Regular down
+        - 3: Use slice order file (not supported)
+        - 4: Use slice timings file (not supported)
+        - 5: Standard interleaved (0, 2, 4, ..., 1, 3, 5, ...)
+        - 6: Siemens interleaved
+        - 7: Siemens multiband interleaved
+    slicenum : int
+        The index of the slice for which to compute the timing offset.
+    numslices : int
+        Total number of slices in the volume.
+    tr : float
+        Repetition time (TR) in seconds.
+    multiband : int, optional
+        Multiband factor (default is 1). Used only for sotype 7 (Siemens
+        multiband interleaved).
 
     Returns
     -------
+    float
+        Slice timing offset in seconds.
 
+    Notes
+    -----
+    For sotypes 3 and 4, the function returns 0.0 as these methods are not
+    implemented.
+
+    Examples
+    --------
+    >>> calcsliceoffset(1, 5, 32, 2.0)
+    0.3125
+
+    >>> calcsliceoffset(5, 3, 16, 1.5)
+    0.28125
     """
     # Slice timing correction
     # 0 : None
@@ -802,19 +1195,61 @@ def calcsliceoffset(sotype, slicenum, numslices, tr, multiband=1):
 
 # NB: a positive value of shifttrs delays the signal, a negative value advances it
 # timeshift using fourier phase multiplication
-def timeshift(inputtc, shifttrs, padtrs, doplot=False, debug=False):
+def timeshift(
+    inputtc: ArrayLike, shifttrs: float, padtrs: int, doplot: bool = False, debug: bool = False
+) -> Tuple[NDArray, NDArray, NDArray, NDArray]:
     """
+    Apply a time shift to a signal using FFT-based modulation and padding.
+
+    This function performs a time shift on an input time course by applying
+    phase modulation in the frequency domain, followed by inverse FFT. It uses
+    padding and reflection to avoid edge discontinuities. The function also
+    returns the corresponding shifted weights and the full padded results.
 
     Parameters
     ----------
-    inputtc
-    shifttrs
-    padtrs
-    doplot
+    inputtc : array-like
+        Input time course to be shifted. Should be a 1D array of real values.
+    shifttrs : float
+        Time shift in units of samples. Positive values shift the signal forward,
+        negative values shift it backward.
+    padtrs : int
+        Number of samples to pad the input signal on each side before shifting.
+        This helps reduce edge effects.
+    doplot : bool, optional
+        If True, plots the original and shifted signals. Default is False.
+    debug : bool, optional
+        If True, prints debug information during execution. Default is False.
 
     Returns
     -------
+    tuple of ndarray
+        A tuple containing:
+        - shifted_y : ndarray
+            The time-shifted signal, cropped to the original length.
+        - shifted_weights : ndarray
+            The corresponding shifted weights, cropped to the original length.
+        - shifted_y_full : ndarray
+            The full time-shifted signal including padding.
+        - shifted_weights_full : ndarray
+            The full shifted weights including padding.
 
+    Notes
+    -----
+    The function uses reflection padding to minimize edge artifacts. The phase
+    modulation is applied in the frequency domain using FFT and inverse FFT.
+    The shift is implemented as a complex exponential modulation.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from scipy import fftpack
+    >>> input_signal = np.sin(np.linspace(0, 4*np.pi, 100))
+    >>> shifted_sig, weights, full_shifted, full_weights = timeshift(
+    ...     input_signal, shifttrs=5.0, padtrs=10, doplot=False
+    ... )
+    >>> print(shifted_sig.shape)
+    (100,)
     """
     # set up useful parameters
     thelen = np.shape(inputtc)[0]
@@ -861,17 +1296,17 @@ def timeshift(inputtc, shifttrs, padtrs, doplot=False, debug=False):
         print("thelen:", thelen)
         print("thepaddedlen:", thepaddedlen)
 
-        fig = pl.figure()
+        fig = plt.figure()
         ax = fig.add_subplot(111)
         ax.set_title("Initial vector")
-        pl.plot(xvec, preshifted_y)
+        plt.plot(xvec, preshifted_y)
 
-        fig = pl.figure()
+        fig = plt.figure()
         ax = fig.add_subplot(111)
         ax.set_title("Initial and shifted vector")
-        pl.plot(xvec, preshifted_y, xvec, shifted_y)
+        plt.plot(xvec, preshifted_y, xvec, shifted_y)
 
-        pl.show()
+        plt.show()
 
     return [
         shifted_y[padtrs : padtrs + thelen],
@@ -881,16 +1316,67 @@ def timeshift(inputtc, shifttrs, padtrs, doplot=False, debug=False):
     ]
 
 
-def timewarp(orig_x, orig_y, timeoffset, demean=True, method="univariate", debug=False):
+def timewarp(
+    orig_x: ArrayLike,
+    orig_y: ArrayLike,
+    timeoffset: ArrayLike,
+    demean: bool = True,
+    method: str = "univariate",
+    debug: bool = False,
+) -> NDArray:
+    """
+    Apply time warping to align time series data based on time offsets.
+
+    This function performs time warping by resampling input data according to
+    provided time offsets. It can optionally remove the mean of the time offsets
+    before resampling to center the data around zero.
+
+    Parameters
+    ----------
+    orig_x : ArrayLike
+        Original time axis values (x-coordinates) for the data to be warped.
+    orig_y : ArrayLike
+        Original signal values (y-coordinates) corresponding to orig_x.
+    timeoffset : ArrayLike
+        Time offsets to be applied to each point in the time axis. Positive values
+        shift data forward in time, negative values shift backward.
+    demean : bool, optional
+        If True, remove the mean of timeoffset before resampling. Default is True.
+    method : str, optional
+        Resampling method to use. Options are 'univariate' or other methods
+        supported by the underlying doresample function. Default is 'univariate'.
+    debug : bool, optional
+        If True, print debugging information about the warping process.
+        Default is False.
+
+    Returns
+    -------
+    NDArray
+        Warped time series data after applying the time offsets and resampling.
+
+    Notes
+    -----
+    The function calculates the maximum deviation in samples and uses half the
+    length of the input data (or 30 seconds worth of samples, whichever is smaller)
+    as padding length for the resampling operation.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> x = np.linspace(0, 10, 100)
+    >>> y = np.sin(x)
+    >>> offsets = np.random.normal(0, 0.1, 100)
+    >>> warped_y = timewarp(x, y, offsets)
+    """
     if demean:
         demeanedoffset = timeoffset - np.mean(timeoffset)
         if debug:
             print("mean delay of ", np.mean(timeoffset), "seconds removed prior to resampling")
     else:
         demeanedoffset = timeoffset
-    sampletime = orig_x[1] - orig_x[0]
-    maxdevs = (np.min(demeanedoffset), np.max(demeanedoffset))
-    maxsamps = maxdevs / sampletime
+    sampletime = float(orig_x[1] - orig_x[0])
+    maxdevs = (float(np.min(demeanedoffset)), float(np.max(demeanedoffset)))
+    maxsamps = (maxdevs[0] / sampletime, maxdevs[1] / sampletime)
     padlen = np.min([int(len(orig_x) // 2), int(30.0 / sampletime)])
     if debug:
         print("maximum deviation in samples:", maxsamps)