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

rapidtide/wiener.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
 #
-#   Copyright 2016-2024 Blaise Frederick
+#   Copyright 2016-2025 Blaise Frederick
 #
 #   Licensed under the Apache License, Version 2.0 (the "License");
 #   you may not use this file except in compliance with the License.
@@ -17,41 +17,156 @@
 #
 #
 import numpy as np
+from numpy.typing import NDArray
 from tqdm import tqdm
 
 import rapidtide.fit as tide_fit
 import rapidtide.multiproc as tide_multiproc
 
 
-def _procOneVoxelWiener(vox, lagtc, inittc, rt_floatset=np.float64, rt_floattype="float64"):
-    thefit, R = tide_fit.mlregress(lagtc, inittc)
-    fitcoff = rt_floatset(thefit[0, 1])
-    datatoremove = rt_floatset(fitcoff * lagtc)
+def _procOneVoxelWiener(
+    vox: int,
+    lagtc: NDArray,
+    inittc: NDArray,
+    rt_floattype: np.dtype = np.float64,
+) -> tuple[int, float, float, float, float, NDArray, NDArray, NDArray]:
+    """
+    Perform Wiener filter processing on a single voxel time series.
+
+    This function applies a Wiener filter to remove the lagged component from
+    the initial time course, returning both the filtered and unfiltered results
+    along with fitting statistics.
+
+    Parameters
+    ----------
+    vox : int
+        Voxel index identifier
+    lagtc : NDArray
+        Lagged time course data (input signal)
+    inittc : NDArray
+        Initial time course data (target signal)
+    rt_floattype : np.dtype, optional
+        Rapidtide float type for output arrays, default is np.float64
+
+    Returns
+    -------
+    tuple[int, NDArray, NDArray, NDArray, NDArray, NDArray, NDArray, NDArray]
+        A tuple containing:
+        - vox (int): Input voxel index
+        - intercept (NDArray): Regression intercept term
+        - sqrt_R2 (NDArray): Square root of coefficient of determination
+        - R2 (NDArray): Coefficient of determination
+        - fitcoff (NDArray): Fitting coefficient
+        - ratio (NDArray): Ratio of slope to intercept
+        - datatoremove (NDArray): Data to be removed (filtered signal)
+        - residual (NDArray): Residual signal (unfiltered data)
+
+    Notes
+    -----
+    This function uses maximum likelihood regression to estimate the relationship
+    between lagged and initial time courses, then applies the Wiener filter
+    to remove the lagged component from the initial signal.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> lagtc = np.array([1.0, 2.0, 3.0, 4.0])
+    >>> inittc = np.array([2.0, 4.0, 6.0, 8.0])
+    >>> result = _procOneVoxelWiener(0, lagtc, inittc)
+    >>> print(result[0])  # voxel index
+    0
+    >>> print(result[4])  # fitting coefficient
+    2.0
+    """
+    thefit, R2 = tide_fit.mlregress(lagtc, inittc)
+    fitcoff = thefit[0, 1]
+    datatoremove = (fitcoff * lagtc).astype(rt_floattype)
     return (
         vox,
-        rt_floatset(thefit[0, 0]),
-        rt_floatset(R),
-        rt_floatset(R * R),
+        thefit[0, 0],
+        np.sqrt(R2),
+        R2,
         fitcoff,
-        rt_floatset(thefit[0, 1] / thefit[0, 0]),
+        thefit[0, 1] / thefit[0, 0],
         datatoremove,
-        rt_floatset(inittc - datatoremove),
+        (inittc - datatoremove).astype(rt_floattype),
     )
 
 
 def wienerpass(
-    numspatiallocs,
-    fmri_data,
-    threshval,
-    lagtc,
-    optiondict,
-    wienerdeconv,
-    wpeak,
-    resampref_y,
-    rt_floatset=np.float64,
-    rt_floattype="float64",
-):
-    rt_floatset = (rt_floatset,)
+    numspatiallocs: int,
+    fmri_data: NDArray,
+    threshval: float,
+    lagtc: NDArray,
+    optiondict: dict,
+    wienerdeconv: NDArray,
+    wpeak: NDArray,
+    resampref_y: NDArray,
+    rt_floattype: np.dtype = np.float64,
+) -> int:
+    """
+    Perform Wiener deconvolution on fMRI data voxels.
+
+    This function applies Wiener deconvolution to each voxel in the fMRI data
+    based on the provided lagged time course and threshold. It supports both
+    single-threaded and multi-threaded processing depending on the configuration
+    in `optiondict`.
+
+    Parameters
+    ----------
+    numspatiallocs : int
+        Number of spatial locations (voxels) in the fMRI data.
+    fmri_data : NDArray
+        2D array of fMRI data with shape (numspatiallocs, timepoints).
+    threshval : float
+        Threshold value for masking voxels based on mean signal intensity.
+    lagtc : NDArray
+        2D array of lagged time courses with shape (numspatiallocs, timepoints).
+    optiondict : dict
+        Dictionary containing processing options including:
+        - 'nprocs': number of processors to use (default: 1)
+        - 'showprogressbar': whether to show progress bar (default: True)
+        - 'mp_chunksize': chunk size for multiprocessing (default: 10)
+    wienerdeconv : NDArray
+        Wiener deconvolution kernel or filter.
+    wpeak : NDArray
+        Peak values associated with the Wiener deconvolution.
+    resampref_y : NDArray
+        Resampled reference signal for filtering.
+    rt_floattype : np.dtype, optional
+        Data type for floating-point numbers, default is `np.float64`.
+
+    Returns
+    -------
+    int
+        Total number of voxels processed.
+
+    Notes
+    -----
+    - Voxels are masked based on their mean signal intensity exceeding `threshval`.
+    - If `nprocs` > 1, multiprocessing is used to process voxels in parallel.
+    - The function modifies global variables such as `meanvalue`, `rvalue`, etc.,
+      which are assumed to be defined in the outer scope.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> fmri_data = np.random.rand(100, 50)
+    >>> lagtc = np.random.rand(100, 50)
+    >>> optiondict = {'nprocs': 4, 'showprogressbar': True, 'mp_chunksize': 5}
+    >>> result = wienerpass(
+    ...     numspatiallocs=100,
+    ...     fmri_data=fmri_data,
+    ...     threshval=0.1,
+    ...     lagtc=lagtc,
+    ...     optiondict=optiondict,
+    ...     wienerdeconv=np.array([1, 2, 1]),
+    ...     wpeak=np.array([0.5]),
+    ...     resampref_y=np.array([1, 1, 1])
+    ... )
+    >>> print(result)
+    100
+    """
     rt_floattype = rt_floattype
     inputshape = np.shape(fmri_data)
     themask = np.where(np.mean(fmri_data, axis=1) > threshval, 1, 0)
@@ -73,7 +188,6 @@ def wienerpass(
                             val,
                             lagtc[val, :],
                             fmri_data[val, :],
-                            rt_floatset=rt_floatset,
                             rt_floattype=rt_floattype,
                         )
                     )
@@ -125,8 +239,7 @@ def wienerpass(
                     vox,
                     lagtc[vox, :],
                     inittc,
-                    rt_floatset=rt_floatset,
-                    t_floattype=rt_floattype,
+                    rt_floattype=rt_floattype,
                 )
             volumetotal += 1
 

rapidtide/wiener2.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.
@@ -30,6 +30,7 @@ import matplotlib.pyplot as plt
 import numpy as np
 from matplotlib.backends.backend_pdf import PdfPages
 from numpy.fft import fft, ifft, ifftshift
+from numpy.typing import NDArray
 
 plt.rcParams.update({"font.size": 6})
 
@@ -43,8 +44,42 @@ lambd_est = 1e-3  # estimated noise lev
 ##########################
 
 
-def gen_son(length):
-    "Generate a synthetic un-reverberated 'sound event' template"
+def gen_son(length: int) -> NDArray:
+    """
+    Generate a synthetic un-reverberated 'sound event' template.
+
+    This function creates a synthetic sound template by generating white noise,
+    integrating it, applying an envelope, and normalizing the result.
+
+    Parameters
+    ----------
+    length : int
+        The length of the output array in samples.
+
+    Returns
+    -------
+    NDArray
+        A normalized synthetic sound event template of shape (length,) containing
+        floating point values.
+
+    Notes
+    -----
+    The generated sound template follows these steps:
+    1. Generate white noise using random.randn
+    2. Integrate the noise using cumulative sum
+    3. Apply a triangular envelope with 12.5% attack time
+    4. Normalize the result to unit energy
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> son = gen_son(1000)
+    >>> print(son.shape)
+    (1000,)
+    >>> print(f"Energy: {np.sum(son * son):.2f}")
+    Energy: 1.00
+    """
+    # "Generate a synthetic un-reverberated 'sound event' template"
     # (whitenoise -> integrate -> envelope -> normalise)
     son = np.cumsum(np.random.randn(length))
     # apply envelope
@@ -55,8 +90,43 @@ def gen_son(length):
     return son
 
 
-def gen_ir(length):
-    "Generate a synthetic impulse response"
+def gen_ir(length: int) -> NDArray:
+    """
+    Generate a synthetic impulse response.
+
+    This function creates a synthetic impulse response with a quiet tail, attack envelope,
+    direct signal component, and early reflection spikes. The resulting impulse response
+    is normalized to unit energy.
+
+    Parameters
+    ----------
+    length : int
+        The length of the impulse response array to generate.
+
+    Returns
+    -------
+    NDArray
+        A normalized numpy array of shape (length,) representing the synthetic impulse response.
+
+    Notes
+    -----
+    The generated impulse response includes:
+    - A quiet tail with random noise
+    - An attack envelope that rises from 0.1 to 1 and then falls back to 0.1
+    - A direct signal component at index 5 with amplitude 1
+    - 10 early reflection spikes with random positions and amplitudes
+    - Normalization to unit energy (L2 norm equals 1)
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> ir = gen_ir(100)
+    >>> print(ir.shape)
+    (100,)
+    >>> print(np.isclose(np.sum(ir * ir), 1.0))
+    True
+    """
+    # "Generate a synthetic impulse response"
     # First we generate a quietish tail
     son = np.random.randn(length)
     attacklen = int(length // 2)
@@ -73,8 +143,44 @@ def gen_ir(length):
     return son
 
 
-def wiener_deconvolution(signal, kernel, lambd):
-    "lambd is the SNR"
+def wiener_deconvolution(signal: NDArray, kernel: NDArray, lambd: float) -> NDArray:
+    """
+    Perform Wiener deconvolution on a signal.
+
+    Wiener deconvolution is a method for reversing the effects of convolution
+    in the presence of noise. It uses a regularization parameter to balance
+    between deconvolution accuracy and noise amplification.
+
+    Parameters
+    ----------
+    signal : NDArray
+        Input signal to be deconvolved, assumed to be 1D.
+    kernel : NDArray
+        Convolution kernel (point spread function), assumed to be 1D.
+    lambd : float
+        Regularization parameter (signal-to-noise ratio). Higher values
+        result in more smoothing and less noise amplification.
+
+    Returns
+    -------
+    NDArray
+        Deconvolved signal with same length as input signal.
+
+    Notes
+    -----
+    The function zero-pads the kernel to match the signal length before
+    performing frequency domain operations. The Wiener filter is applied
+    in the frequency domain using the formula:
+    output = real(ifft(fft(signal) * conj(H) / (|H|² + λ²)))
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> signal = np.array([1, 2, 3, 2, 1])
+    >>> kernel = np.array([1, 0.5, 0.25])
+    >>> result = wiener_deconvolution(signal, kernel, lambd=0.1)
+    """
+    # "lambd is the SNR"
     kernel = np.hstack(
         (kernel, np.zeros(len(signal) - len(kernel)))
     )  # zero pad the kernel to same length
@@ -84,7 +190,7 @@ def wiener_deconvolution(signal, kernel, lambd):
 
 
 if __name__ == "__main__":
-    "simple test: get one soundtype and one impulse response, convolve them, deconvolve them, and check the result (plot it!)"
+    # "simple test: get one soundtype and one impulse response, convolve them, deconvolve them, and check the result (plot it!)"
     son = gen_son(sonlen)
     ir = gen_ir(irlen)
     obs = np.convolve(son, ir, mode="full")

rapidtide/workflows/adjustoffset.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,6 +18,7 @@
 #
 import argparse
 import copy
+from typing import Any
 
 import matplotlib.pyplot as plt
 import numpy as np
@@ -33,9 +34,35 @@ DEFAULT_PEAKTHRESH = 0.33
 DEFAULT_HISTBINS = 151
 
 
-def _get_parser():
+def _get_parser() -> Any:
     """
-    Argument parser for adjust offset
+    Argument parser for adjust offset.
+
+    This function constructs and returns an `argparse.ArgumentParser` object configured
+    for parsing command-line arguments used by the `adjustoffset` tool. It defines
+    various options for adjusting the offset of a rapidtide delay map, including
+    masking, histogram-based peak detection, and output control.
+
+    Returns
+    -------
+    argparse.ArgumentParser
+        Configured argument parser for the adjustoffset tool.
+
+    Notes
+    -----
+    The parser includes support for:
+    - Input and output file specifications
+    - Masking options (include, exclude, extra)
+    - Histogram-based offset estimation
+    - Search range limiting
+    - Debugging and display options
+
+    Examples
+    --------
+    >>> parser = _get_parser()
+    >>> args = parser.parse_args(['input.nii', 'output_root'])
+    >>> print(args.inputmap)
+    'input.nii'
     """
     parser = argparse.ArgumentParser(
         prog="adjustoffset",
@@ -159,7 +186,82 @@ def _get_parser():
     return parser
 
 
-def adjustoffset(args):
+def adjustoffset(args: Any) -> None:
+    """
+    Adjust the offset of a NIfTI map based on histogram analysis and optional masking.
+
+    This function reads a NIfTI map file, applies optional inclusion and exclusion masks,
+    and computes a peak location from the histogram of valid voxels. The computed offset
+    is then added to the map values, unless a fixed offset is specified via `args.setoffset`.
+
+    Parameters
+    ----------
+    args : Any
+        An object containing the following attributes:
+        - `inputmap` : str
+            Path to the input NIfTI map file.
+        - `debug` : bool
+            If True, prints debug information.
+        - `includespec` : str, optional
+            Specification for including voxels in the analysis.
+        - `excludespec` : str, optional
+            Specification for excluding voxels from the analysis.
+        - `extramaskname` : str, optional
+            Path to an additional mask file.
+        - `histbins` : int
+            Number of histogram bins to use.
+        - `searchrange` : tuple of float, optional
+            Range of values to consider for histogram analysis.
+        - `refine` : bool
+            Whether to refine the peak detection.
+        - `pickleft` : bool
+            Whether to pick the leftmost peak.
+        - `pickleftthresh` : float, optional
+            Threshold for leftmost peak picking.
+        - `display` : bool
+            Whether to display the histogram.
+        - `histonly` : bool
+            If True, only compute and display the histogram, do not adjust the map.
+        - `setoffset` : float, optional
+            Fixed offset value to apply to the map.
+        - `outputroot` : str
+            Root name for output files.
+
+    Returns
+    -------
+    None
+        This function does not return a value but saves two NIfTI files:
+        - `<outputroot>_maskmap.nii.gz`: The generated mask map.
+        - `<outputroot>_adjustedmaxtime.nii.gz`: The adjusted map with offset applied.
+
+    Notes
+    -----
+    - The function uses `tide_io.readfromnifti` to read the input map and `tide_io.savetonifti` to save outputs.
+    - Masks are generated using `tide_mask.getmaskset` based on inclusion/exclusion specifications.
+    - Histogram analysis is performed using `tide_stats.gethistprops` and `tide_stats.makehistogram`.
+    - If `args.setoffset` is provided, it overrides the computed peak location as the offset.
+
+    Examples
+    --------
+    >>> class Args:
+    ...     inputmap = "input_map.nii.gz"
+    ...     debug = True
+    ...     includespec = "brain"
+    ...     excludespec = None
+    ...     extramaskname = None
+    ...     histbins = 100
+    ...     searchrange = (0.0, 10.0)
+    ...     refine = True
+    ...     pickleft = False
+    ...     pickleftthresh = 0.5
+    ...     display = False
+    ...     histonly = False
+    ...     setoffset = None
+    ...     outputroot = "output"
+    ...
+    >>> args = Args()
+    >>> adjustoffset(args)
+    """
     if args.debug:
         print(f"reading map file {args.inputmap}")
     (
@@ -209,7 +311,7 @@ def adjustoffset(args):
     )
 
     theflatmap = themap_data.reshape((numspatiallocs))
-    theflatmask = theflatmap * 0 + 1
+    theflatmask = np.ones_like(theflatmap)
     if includemask is not None:
         theflatmask = theflatmask * includemask.reshape((numspatiallocs))
     if excludemask is not None:

rapidtide/workflows/aligntcs.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
 #
-#   Copyright 2016-2024 Blaise Frederick
+#   Copyright 2016-2025 Blaise Frederick
 #
 #   Licensed under the Apache License, Version 2.0 (the "License");
 #   you may not use this file except in compliance with the License.
@@ -17,6 +17,7 @@
 #
 #
 import argparse
+from typing import Any
 
 import numpy as np
 
@@ -28,7 +29,32 @@ import rapidtide.resample as tide_resample
 import rapidtide.workflows.parser_funcs as pf
 
 
-def _get_parser():
+def _get_parser() -> Any:
+    """
+    Construct and return an argument parser for aligning two time series.
+
+    This function sets up an `argparse.ArgumentParser` with required and optional
+    arguments for resampling and aligning two time series datasets. It supports
+    specifying input files, sample rates, output file, and various processing options
+    such as plotting and verbosity.
+
+    Returns
+    -------
+    argparse.ArgumentParser
+        Configured argument parser object with all necessary arguments for
+        time series alignment.
+
+    Notes
+    -----
+    The function uses a custom helper `pf.is_float` to validate sample rate inputs.
+    It also adds search range and filter options via `pf.addsearchrangeopts` and
+    `pf.addfilteropts`.
+
+    Examples
+    --------
+    >>> parser = _get_parser()
+    >>> args = parser.parse_args()
+    """
     # get the command line parameters
     parser = argparse.ArgumentParser(
         prog="aligntcs",
@@ -83,7 +109,64 @@ def _get_parser():
     return parser
 
 
-def aligntcs(args):
+def aligntcs(args: Any) -> None:
+    """
+    Align two time series using cross-correlation and resampling.
+
+    This function reads two input time series from text files, aligns them based on
+    cross-correlation, and writes the aligned second time series to an output file.
+    Optional plotting of cross-correlation and aligned signals can be enabled via
+    the `displayplots` argument in `args`.
+
+    Parameters
+    ----------
+    args : Any
+        An object containing the following attributes:
+        - infile1 : str
+            Path to the first input text file.
+        - infile2 : str
+            Path to the second input text file.
+        - insamplerate1 : float
+            Sampling rate of the first input signal.
+        - insamplerate2 : float
+            Sampling rate of the second input signal.
+        - outputfile : str
+            Path to the output file where the aligned second signal will be written.
+        - lagmin : float
+            Minimum lag for cross-correlation search.
+        - lagmax : float
+            Maximum lag for cross-correlation search.
+        - displayplots : bool
+            If True, displays cross-correlation and aligned signals using matplotlib.
+
+    Returns
+    -------
+    None
+        This function does not return a value but writes the aligned data to a file
+        and optionally displays plots.
+
+    Notes
+    -----
+    - The function applies a prefilter to the input data before alignment.
+    - The second time series is resampled to match the timing of the first.
+    - Cross-correlation is performed using a fast correlation method.
+    - If `displayplots` is True, the function will use the 'TkAgg' backend for matplotlib.
+
+    Examples
+    --------
+    >>> import argparse
+    >>> args = argparse.Namespace(
+    ...     infile1='signal1.txt',
+    ...     infile2='signal2.txt',
+    ...     insamplerate1=100.0,
+    ...     insamplerate2=100.0,
+    ...     outputfile='aligned_signal2.txt',
+    ...     lagmin=-0.1,
+    ...     lagmax=0.1,
+    ...     displayplots=False
+    ... )
+    >>> aligntcs(args)
+    """
     if args.displayplots:
         import matplotlib as mpl