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

rapidtide/wiener.py

@@ -17,13 +17,20 @@
 #
 #
 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"):
+def _procOneVoxelWiener(
+    vox: int,
+    lagtc: NDArray,
+    inittc: NDArray,
+    rt_floatset: type = np.float64,
+    rt_floattype: str = "float64",
+) -> tuple[int, NDArray, NDArray, NDArray, NDArray, NDArray, NDArray, NDArray]:
     thefit, R2 = tide_fit.mlregress(lagtc, inittc)
     fitcoff = rt_floatset(thefit[0, 1])
     datatoremove = rt_floatset(fitcoff * lagtc)
@@ -40,17 +47,17 @@ def _procOneVoxelWiener(vox, lagtc, inittc, rt_floatset=np.float64, rt_floattype
 
 
 def wienerpass(
-    numspatiallocs,
-    fmri_data,
-    threshval,
-    lagtc,
-    optiondict,
-    wienerdeconv,
-    wpeak,
-    resampref_y,
-    rt_floatset=np.float64,
-    rt_floattype="float64",
-):
+    numspatiallocs: int,
+    fmri_data: NDArray,
+    threshval: float,
+    lagtc: NDArray,
+    optiondict: dict,
+    wienerdeconv: NDArray,
+    wpeak: NDArray,
+    resampref_y: NDArray,
+    rt_floatset: type = np.float64,
+    rt_floattype: str = "float64",
+) -> int:
     rt_floatset = (rt_floatset,)
     rt_floattype = rt_floattype
     inputshape = np.shape(fmri_data)

rapidtide/wiener2.py

@@ -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 : numpy.ndarray
+        Input signal to be deconvolved, assumed to be 1D.
+    kernel : numpy.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
+    -------
+    numpy.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/wiener_doc.py

@@ -0,0 +1,255 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+#
+#   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.
+#   You may obtain a copy of the License at
+#
+#       http://www.apache.org/licenses/LICENSE-2.0
+#
+#   Unless required by applicable law or agreed to in writing, software
+#   distributed under the License is distributed on an "AS IS" BASIS,
+#   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#   See the License for the specific language governing permissions and
+#   limitations under the License.
+#
+#
+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: int,
+    lagtc: NDArray,
+    inittc: NDArray,
+    rt_floatset: type = np.float64,
+    rt_floattype: str = "float64",
+) -> tuple[int, NDArray, NDArray, NDArray, NDArray, 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_floatset : type, optional
+        Real-time float type for output arrays, default is np.float64
+    rt_floattype : str, optional
+        String representation of the real-time float type, default is "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 = rt_floatset(thefit[0, 1])
+    datatoremove = rt_floatset(fitcoff * lagtc)
+    return (
+        vox,
+        rt_floatset(thefit[0, 0]),
+        rt_floatset(np.sqrt(R2)),
+        rt_floatset(R2),
+        fitcoff,
+        rt_floatset(thefit[0, 1] / thefit[0, 0]),
+        datatoremove,
+        rt_floatset(inittc - datatoremove),
+    )
+
+
+def wienerpass(
+    numspatiallocs: int,
+    fmri_data: NDArray,
+    threshval: float,
+    lagtc: NDArray,
+    optiondict: dict,
+    wienerdeconv: NDArray,
+    wpeak: NDArray,
+    resampref_y: NDArray,
+    rt_floatset: type = np.float64,
+    rt_floattype: str = "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 : numpy.ndarray
+        2D array of fMRI data with shape (numspatiallocs, timepoints).
+    threshval : float
+        Threshold value for masking voxels based on mean signal intensity.
+    lagtc : numpy.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 : numpy.ndarray
+        Wiener deconvolution kernel or filter.
+    wpeak : numpy.ndarray
+        Peak values associated with the Wiener deconvolution.
+    resampref_y : numpy.ndarray
+        Resampled reference signal for filtering.
+    rt_floatset : type, optional
+        Data type for floating-point numbers, default is `np.float64`.
+    rt_floattype : str, optional
+        String representation of the floating-point data type, default is "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_floatset = (rt_floatset,)
+    rt_floattype = rt_floattype
+    inputshape = np.shape(fmri_data)
+    themask = np.where(np.mean(fmri_data, axis=1) > threshval, 1, 0)
+    if optiondict["nprocs"] > 1:
+        # define the consumer function here so it inherits most of the arguments
+        def Wiener_consumer(inQ, outQ):
+            while True:
+                try:
+                    # get a new message
+                    val = inQ.get()
+
+                    # this is the 'TERM' signal
+                    if val is None:
+                        break
+
+                    # process and send the data
+                    outQ.put(
+                        _procOneVoxelWiener(
+                            val,
+                            lagtc[val, :],
+                            fmri_data[val, :],
+                            rt_floatset=rt_floatset,
+                            rt_floattype=rt_floattype,
+                        )
+                    )
+
+                except Exception as e:
+                    print("error!", e)
+                    break
+
+        data_out = tide_multiproc.run_multiproc(
+            Wiener_consumer,
+            inputshape,
+            themask,
+            nprocs=optiondict["nprocs"],
+            showprogressbar=True,
+            chunksize=optiondict["mp_chunksize"],
+        )
+        # unpack the data
+        volumetotal = 0
+        for voxel in data_out:
+            meanvalue[voxel[0]] = voxel[1]
+            rvalue[voxel[0]] = voxel[2]
+            r2value[voxel[0]] = voxel[3]
+            fitcoff[voxel[0]] = voxel[4]
+            fitNorm[voxel[0]] = voxel[5]
+            datatoremove[voxel[0], :] = voxel[6]
+            filtereddata[voxel[0], :] = voxel[7]
+            volumetotal += 1
+        data_out = []
+    else:
+        volumetotal = 0
+        for vox in tqdm(
+            range(0, numspatiallocs),
+            desc="Voxel",
+            unit="voxels",
+            disable=(not optiondict["showprogressbar"]),
+        ):
+            inittc = fmri_data[vox, :].copy()
+            if np.mean(inittc) >= threshval:
+                (
+                    dummy,
+                    meanvalue[vox],
+                    rvalue[vox],
+                    r2value[vox],
+                    fitcoff[vox],
+                    fitNorm[vox],
+                    datatoremove[vox],
+                    filtereddata[vox],
+                ) = _procOneVoxelWiener(
+                    vox,
+                    lagtc[vox, :],
+                    inittc,
+                    rt_floatset=rt_floatset,
+                    t_floattype=rt_floattype,
+                )
+            volumetotal += 1
+
+    return volumetotal

rapidtide/workflows/adjustoffset.py

@@ -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}")
     (

rapidtide/workflows/aligntcs.py

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