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

rapidtide/workflows/diffrois.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,18 +18,46 @@
 #
 import argparse
 import copy
+from argparse import Namespace
+from typing import Any, Callable, Dict, List, Optional, Tuple, Union
 
 import nibabel as nib
 import numpy as np
 import pandas as pd
+from numpy.typing import NDArray
 
 import rapidtide.io as tide_io
 import rapidtide.workflows.parser_funcs as pf
 
 
-def _get_parser():
+def _get_parser() -> Any:
     """
-    Argument parser for diffrois
+    Argument parser for diffrois.
+
+    This function creates and configures an argument parser for the diffrois command-line tool.
+    It defines required and optional arguments needed to process ROI (Region of Interest) data
+    from a CSV file and generate difference matrices.
+
+    Returns
+    -------
+    argparse.ArgumentParser
+        Configured argument parser object with defined arguments for diffrois.
+
+    Notes
+    -----
+    The parser is configured with:
+    - A required datafile argument (CSV input)
+    - A required outputroot argument (root name for output files)
+    - Optional keyfile argument to specify region label order
+    - Optional maxlines argument to limit processing to first N lines
+    - Optional debug flag for verbose output
+
+    Examples
+    --------
+    >>> parser = _get_parser()
+    >>> args = parser.parse_args(['data.csv', 'output_root'])
+    >>> print(args.datafile)
+    'data.csv'
     """
     parser = argparse.ArgumentParser(
         prog="diffrois",
@@ -77,7 +105,57 @@ def _get_parser():
     return parser
 
 
-def diffrois(args):
+def diffrois(args: Any) -> None:
+    """
+    Compute pairwise differences between regions in a CSV file and save results as NIfTI images.
+
+    This function reads region data from a CSV file, computes pairwise differences between
+    regions, and saves the results as NIfTI images. It also computes mean and standard
+    deviation maps of the differences and saves those as well. The function supports
+    optional masking of invalid (NaN) values and can limit the number of input lines
+    processed.
+
+    Parameters
+    ----------
+    args : argparse.Namespace
+        An object containing the following attributes:
+        - datafile : str
+            Path to the input CSV file containing region data.
+        - keyfile : str, optional
+            Path to a file listing column keys in the CSV to use for processing.
+        - outputroot : str
+            Root name for output NIfTI files.
+        - maxlines : int, optional
+            Maximum number of lines to process from the input CSV.
+        - debug : bool
+            If True, print debug information during execution.
+
+    Returns
+    -------
+    None
+        This function does not return any value but saves multiple NIfTI files to disk.
+
+    Notes
+    -----
+    The function saves the following NIfTI files:
+    - `{outputroot}_diffs.nii.gz`: Pairwise differences between regions.
+    - `{outputroot}_mask.nii.gz`: Binary mask indicating valid (non-NaN) values.
+    - `{outputroot}_meandiffs.nii.gz`: Mean of differences for each region pair.
+    - `{outputroot}_stddiffs.nii.gz`: Standard deviation of differences for each region pair.
+    - `{outputroot}_demeaneddiffs.nii.gz`: Demeaned differences (difference minus mean).
+
+    Examples
+    --------
+    >>> import argparse
+    >>> args = argparse.Namespace(
+    ...     datafile='data.csv',
+    ...     keyfile='keys.txt',
+    ...     outputroot='output',
+    ...     maxlines=100,
+    ...     debug=False
+    ... )
+    >>> diffrois(args)
+    """
     df = pd.read_csv(args.datafile)
 
     theregions = np.array(df.columns[1:].values)
@@ -141,8 +219,8 @@ def diffrois(args):
     numvox = numoutregions * numoutregions
     thediffs_rs = thediffs.reshape((numvox, numlabels))
     themask_rs = themask.reshape((numvox, numlabels))
-    themeandiffs_rs = thediffs_rs[:, 0] * 0.0
-    thestddiffs_rs = thediffs_rs[:, 0] * 0.0
+    themeandiffs_rs = np.zeros_like(thediffs_rs[:, 0])
+    thestddiffs_rs = np.zeros_like(thediffs_rs[:, 0])
     for idx in range(numvox):
         inputvec = thediffs_rs[idx, :]
         inputmask = themask_rs[idx, :]

rapidtide/workflows/endtidalproc.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.
@@ -19,19 +19,85 @@
 import argparse
 import bisect
 import sys
+from argparse import Namespace
+from typing import Any, Callable, Dict, List, Optional, Tuple, Union
 
 import numpy as np
+from numpy.typing import NDArray
 
 import rapidtide.fit as tide_fit
 import rapidtide.io as tide_io
 from rapidtide.workflows.parser_funcs import invert_float, is_float
 
 
-def phase(mcv):
+def phase(mcv: Any) -> None:
+    """
+    Compute the phase angle of a complex number.
+
+    This function calculates the phase angle (also known as the argument) of a complex number
+    using the arctan2 function, which correctly handles all quadrants and special cases.
+
+    Parameters
+    ----------
+    mcv : Any
+        A complex number or array of complex numbers for which to compute the phase angle.
+        Can be a scalar complex number or an array-like object containing complex numbers.
+
+    Returns
+    -------
+    ndarray or scalar
+        The phase angle in radians. The return type matches the input type, returning
+        a scalar for scalar input or an array for array input. The phase angle is
+        in the range [-π, π].
+
+    Notes
+    -----
+    This function uses `np.arctan2(mcv.imag, mcv.real)` which is preferred over
+    `np.arctan(mcv.imag/mcv.real)` because it correctly handles the quadrant
+    and avoids division by zero errors.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> phase(1+1j)
+    0.7853981633974483
+
+    >>> phase(-1-1j)
+    -2.3561944901923448
+
+    >>> phase(np.array([1+1j, -1-1j]))
+    array([ 0.78539816, -2.35619449])
+    """
     return np.arctan2(mcv.imag, mcv.real)
 
 
-def _get_parser():
+def _get_parser() -> Any:
+    """
+    Create and configure an argument parser for the endtidalproc command-line tool.
+
+    This function sets up an `argparse.ArgumentParser` with various options to process
+    a gas trace and generate an endtidal waveform. It supports input and output file
+    specifications, sample rate configuration, time range settings, threshold for
+    peak detection, and debugging options.
+
+    Returns
+    -------
+    argparse.ArgumentParser
+        Configured argument parser object with all required and optional arguments.
+
+    Notes
+    -----
+    The parser is designed for use with the `endtidalproc` program and includes
+    mutually exclusive group for specifying sample rate either as frequency or
+    time step. The default sample rate is 1 Hz.
+
+    Examples
+    --------
+    >>> parser = _get_parser()
+    >>> args = parser.parse_args(['input.txt', 'output.txt'])
+    >>> print(args.infilename)
+    'input.txt'
+    """
     # get the command line parameters
     parser = argparse.ArgumentParser(
         prog="endtidalproc",
@@ -90,7 +156,7 @@ def _get_parser():
         dest="thresh",
         metavar="PCT",
         type=float,
-        help="Amount of fall (or rise) needed, in percent, to recognize a peak (or trough).",
+        help="Amount of fall (or rise) needed, in percent, to recognize a peak (or through).",
         default=1.0,
     )
     parser.add_argument(
@@ -104,7 +170,45 @@ def _get_parser():
     return parser
 
 
-def process_args():
+def process_args(args: Any) -> None:
+    """
+    Process and validate input arguments for audio processing.
+
+    This function sets default values for samplerate if not provided and
+    optionally prints debug information when debug mode is enabled.
+
+    Parameters
+    ----------
+    args : Any
+        An object containing audio processing arguments. Expected to have
+        attributes 'samplerate' and 'debug'. The 'samplerate' attribute
+        will be set to 1.0 if None, and 'debug' controls whether to print
+        argument information.
+
+    Returns
+    -------
+    None
+        This function modifies the args object in-place and does not return
+        a value.
+
+    Notes
+    -----
+    - The function modifies the input args object in-place
+    - Default samplerate is set to 1.0 when None is provided
+    - Debug output is printed only when args.debug is True
+
+    Examples
+    --------
+    >>> class Args:
+    ...     def __init__(self):
+    ...         self.samplerate = None
+    ...         self.debug = True
+    ...
+    >>> args = Args()
+    >>> process_args(args)
+    >>> print(args.samplerate)
+    1.0
+    """
     if args.samplerate is None:
         args.samplerate = 1.0
 
@@ -116,8 +220,44 @@ def process_args():
     return args
 
 
-def endtidalproc(args):
-    args = process_args()
+def endtidalproc() -> None:
+    """
+    Process tidal data to detect peaks and interpolate values for output.
+
+    This function reads a time series from an input file, detects either maximum or
+    minimum peaks depending on whether the data is treated as oxygen or CO2, and
+    interpolates the peak values over the full time range. The resulting interpolated
+    data is written to an output file.
+
+    Parameters
+    ----------
+    None
+        This function does not take any direct parameters. It reads from command-line
+        arguments and system input files.
+
+    Returns
+    -------
+    None
+        This function does not return any value. It performs file I/O operations
+        and writes results to disk.
+
+    Notes
+    -----
+    - The function uses `bisect` to find the start and end indices in the time vector
+      based on the provided start and end times.
+    - Peak detection is performed using `tide_fit.peakdetect`, which requires a
+      `lookahead` parameter and a `delta` threshold.
+    - If `isoxygen` is True, the function detects minimum peaks; otherwise, it detects
+      maximum peaks.
+    - The interpolation is linear between detected peaks.
+
+    Examples
+    --------
+    >>> endtidalproc()
+    Fitting trace as CO2
+    endtime must be greater then starttime;
+    """
+    args = process_args(_get_parser().parse_args(sys.argv[1:]))
 
     if args.isoxygen:
         print("Fitting trace as oxygen")
@@ -138,7 +278,7 @@ def endtidalproc(args):
     args.thestarttime = xvec[thestartpoint]
     args.theendtime = xvec[theendpoint]
 
-    # set parameters - maxtime is the longest to look ahead for a peak (or trough) in seconds
+    # set parameters - maxtime is the longest to look ahead for a peak (or through) in seconds
     # lookahead should be '(samples / period) / f' where '4 >= f >= 1.25' might be a good value
     maxtime = 1.0
     f = 2.0
@@ -166,4 +306,4 @@ def endtidalproc(args):
 
 
 if __name__ == "__main__":
-    main()
+    endtidalproc()

rapidtide/workflows/fdica.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.
@@ -40,22 +40,126 @@ if pyfftwpresent:
     pyfftw.interfaces.cache.enable()
 
 
+from argparse import Namespace
+from typing import Any, Callable, Dict, List, Optional, Tuple, Union
+
+from numpy.typing import NDArray
+
 import rapidtide.filter as tide_filt
 import rapidtide.io as tide_io
 from rapidtide.workflows.parser_funcs import is_valid_file
 
 
-def P2R(radii, angles):
+def P2R(radii: Any, angles: Any) -> None:
+    """
+    Convert polar coordinates to complex numbers.
+
+    Convert polar coordinates (radii, angles) to complex numbers using the formula
+    z = r * exp(i * θ), where r is the radius and θ is the angle in radians.
+
+    Parameters
+    ----------
+    radii : Any
+        The radial coordinates (magnitude) of the points in polar coordinates.
+        Should be a numeric type or array-like object.
+    angles : Any
+        The angular coordinates (in radians) of the points in polar coordinates.
+        Should be a numeric type or array-like object.
+
+    Returns
+    -------
+    complex
+        Complex numbers in the form z = r * exp(i * θ).
+        Returns None if the input parameters are not compatible.
+
+    Notes
+    -----
+    This function assumes that the angles are provided in radians.
+    The function uses NumPy's exponential function for complex number computation.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> P2R(1, 0)
+    (1+0j)
+
+    >>> P2R(2, np.pi/2)
+    (1.2246467991473532e-16+2j)
+
+    >>> P2R([1, 2, 3], [0, np.pi/2, np.pi])
+    [1.+0.j 2.+0.j 3.+0.j]
+    """
     return radii * np.exp(1j * angles)
 
 
-def R2P(x):
+def R2P(x: Any) -> None:
+    """
+    Convert rectangular coordinates to polar coordinates.
+
+    This function converts complex numbers from rectangular (Cartesian) coordinates
+    to polar coordinates, returning the magnitude (absolute value) and phase angle.
+
+    Parameters
+    ----------
+    x : Any
+        Input array-like object containing complex numbers or real numbers.
+        Can be a scalar, list, tuple, or numpy array.
+
+    Returns
+    -------
+    tuple
+        A tuple containing two numpy arrays:
+        - First array: absolute values (magnitudes) of input elements
+        - Second array: angles (in radians) of input elements
+
+    Notes
+    -----
+    For real numbers, the angle is 0 for positive values and π for negative values.
+    For complex numbers, the angle is computed using numpy's angle function.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> R2P([1+1j, -1-1j, 2])
+    (array([1.41421356, 1.41421356, 2.        ]), array([0.78539816, -2.35619449, 0.        ]))
+
+    >>> R2P(np.array([3+4j, 1-1j]))
+    (array([5., 1.41421356]), array([0.92729522, -0.78539816]))
+    """
     return np.absolute(x), np.angle(x)
 
 
-def _get_parser():
+def _get_parser() -> Any:
     """
-    Argument parser for fdica
+    Argument parser for fdica.
+
+    This function constructs and returns an `argparse.ArgumentParser` object configured
+    for parsing command-line arguments for the `fdica` tool. The parser is designed to
+    handle inputs for fitting a spatial template to 3D or 4D NIFTI files, with options
+    for spatial filtering, PCA, and ICA decomposition.
+
+    Returns
+    -------
+    argparse.ArgumentParser
+        Configured argument parser for the fdica tool.
+
+    Notes
+    -----
+    The parser expects three required positional arguments:
+    - `datafile`: The 3D or 4D NIFTI file to fit.
+    - `datamask`: A 3D NIFTI file mask (must match `datafile`).
+    - `outputroot`: Root name for output files.
+
+    Optional arguments include:
+    - `--spatialfilt`: Apply Gaussian spatial filtering.
+    - `--pcacomponents`: Number of PCA components for phase fitting.
+    - `--icacomponents`: Number of ICA components for decomposition.
+    - `--debug`: Enable debugging output.
+
+    Examples
+    --------
+    >>> parser = _get_parser()
+    >>> args = parser.parse_args()
     """
     parser = argparse.ArgumentParser(
         prog="fdica",
@@ -117,16 +221,65 @@ def _get_parser():
 
 
 def fdica(
-    datafile,
-    datamask,
-    outputroot,
-    gausssigma=0.0,
-    pcacomponents="mle",
-    icacomponents=None,
-    lowerfreq=0.009,
-    upperfreq=0.15,
-    debug=False,
-):
+    datafile: Any,
+    datamask: Any,
+    outputroot: Any,
+    gausssigma: float = 0.0,
+    pcacomponents: str = "mle",
+    icacomponents: Optional[Any] = None,
+    lowerfreq: float = 0.009,
+    upperfreq: float = 0.15,
+    debug: bool = False,
+) -> None:
+    """
+    Perform frequency-domain independent component analysis (FDICA) on fMRI data.
+
+    This function reads fMRI data and a corresponding mask, applies spatial filtering if
+    requested, performs FFT, and conducts PCA and ICA on the frequency-domain data to
+    decompose the signal into independent components. It saves various intermediate and
+    final outputs including magnitude, phase, PCA components, and ICA components.
+
+    Parameters
+    ----------
+    datafile : Any
+        Path to the input NIfTI fMRI data file.
+    datamask : Any
+        Path to the NIfTI mask file defining the region of interest.
+    outputroot : Any
+        Root name for output NIfTI files.
+    gausssigma : float, optional
+        Standard deviation for Gaussian spatial smoothing. If less than 0, automatically
+        calculated as mean of spatial dimensions divided by 2. Default is 0.0.
+    pcacomponents : str or int, optional
+        Number of PCA components to retain. If "mle", uses the minimum description
+        length criterion. Default is "mle".
+    icacomponents : int, optional
+        Number of ICA components to extract. If None, defaults to the number of PCA
+        components. Default is None.
+    lowerfreq : float, optional
+        Lower frequency bound in Hz. Default is 0.009.
+    upperfreq : float, optional
+        Upper frequency bound in Hz. Default is 0.15.
+    debug : bool, optional
+        If True, enables debug output. Default is False.
+
+    Returns
+    -------
+    None
+        The function writes multiple NIfTI files and text files to disk but does not return anything.
+
+    Notes
+    -----
+    - The function assumes the input data is in NIfTI format and the mask is 3D.
+    - Frequency trimming is performed based on the specified lower and upper bounds.
+    - PCA and ICA are applied to the phase data after detrending.
+    - Intermediate outputs include magnitude, phase, PCA components, and ICA components.
+    - The final reconstructed signal is saved as a NIfTI file.
+
+    Examples
+    --------
+    >>> fdica('fmri_data.nii', 'mask.nii', 'output', gausssigma=2.0, lowerfreq=0.01, upperfreq=0.1)
+    """
     # read in data
     print("reading in data arrays")
     (
@@ -269,7 +422,7 @@ def fdica(
     # remove mean and linear component
     phasemeans = np.zeros((numfitvoxels), dtype="float")
     phaseslopes = np.zeros((numfitvoxels), dtype="float")
-    detrendedphasedata = phasedata * 0.0
+    detrendedphasedata = np.zeros_like(phasedata)
     print(f"shape of detrendedphasedata: {detrendedphasedata.shape}")
     X = np.linspace(lowerbin * hzperpoint, upperbin * hzperpoint, trimmedsize)
     for i in range(numfitvoxels):
@@ -422,7 +575,34 @@ def fdica(
     )
 
 
-def main():
+def main() -> None:
+    """
+    Main function to execute the FDICA (Fast Independent Component Analysis) pipeline.
+
+    This function parses command line arguments, prints them for debugging purposes,
+    and executes the FDICA algorithm with the specified parameters.
+
+    Parameters
+    ----------
+    None
+
+    Returns
+    -------
+    None
+        This function does not return any value but executes the FDICA pipeline
+        and produces output files based on the provided arguments.
+
+    Notes
+    -----
+    The function uses a parser to handle command line arguments and includes
+    error handling for argument parsing. If parsing fails, the help message is
+    displayed before raising the SystemExit exception.
+
+    Examples
+    --------
+    >>> main()
+    # This would execute the FDICA pipeline with arguments parsed from command line
+    """
     try:
         args = _get_parser().parse_args()
     except SystemExit:

rapidtide/workflows/filtnifti.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,17 +17,40 @@
 #
 #
 import argparse
+from argparse import Namespace
+from typing import Any, Callable, Dict, List, Optional, Tuple, Union
 
 import numpy as np
+from numpy.typing import NDArray
 
 import rapidtide.filter as tide_filt
 import rapidtide.io as tide_io
 
 
-def _get_parser():
+def _get_parser() -> Any:
     """
-    Argument parser for filtnifti
+    Argument parser for filtnifti.
 
+    Creates and configures an argument parser for the filtnifti command-line tool
+    that temporally filters NIFTI files.
+
+    Returns
+    -------
+    argparse.ArgumentParser
+        Configured argument parser object with required command-line arguments
+
+    Notes
+    -----
+    The parser expects four command-line arguments in the following order:
+    1. inputfilename - path to input NIFTI file
+    2. outputfilename - path to output NIFTI file
+    3. lowestfreq - low passband frequency limit in Hz (negative values disable HPF)
+    4. highestfreq - high passband frequency limit in Hz (negative values disable LPF)
+
+    Examples
+    --------
+    >>> parser = _get_parser()
+    >>> args = parser.parse_args(['input.nii', 'output.nii', '0.01', '0.1'])
     """
     # get the command line parameters
     parser = argparse.ArgumentParser(
@@ -50,7 +73,51 @@ def _get_parser():
     return parser
 
 
-def filtnifti(args):
+def filtnifti(args: Any) -> None:
+    """
+    Apply a frequency-domain filter to a 4D NIfTI file containing fMRI data.
+
+    This function reads an input NIfTI file, applies a bandpass or arbitrary frequency filter
+    to each voxel's time series, and saves the filtered data to a new NIfTI file. The filter
+    parameters are specified via the `args` object, which should contain attributes such as
+    `inputfilename`, `outputfilename`, `lowestfreq`, and `highestfreq`.
+
+    Parameters
+    ----------
+    args : Any
+        An object containing the following attributes:
+        - inputfilename : str
+            Path to the input NIfTI file.
+        - outputfilename : str
+            Path to the output NIfTI file.
+        - lowestfreq : float
+            Lowest frequency for the filter. If negative, highpass filtering is disabled.
+        - highestfreq : float
+            Highest frequency for the filter. If negative, lowpass filtering is disabled.
+
+    Returns
+    -------
+    None
+        This function does not return a value but saves the filtered data to a NIfTI file.
+
+    Notes
+    -----
+    - The function uses a non-causal filter (`tide_filt.NoncausalFilter`) for filtering.
+    - The TR (repetition time) is read from the NIfTI header, and the sampling frequency
+      is computed as `Fs = 1 / TR`.
+    - Filtering is applied slice-by-slice to each voxel's time series.
+    - If `lowestfreq` or `highestfreq` is set to a negative value, the corresponding filter
+      is disabled.
+
+    Examples
+    --------
+    Assuming `args` is an object with the required attributes:
+
+    >>> filtnifti(args)
+
+    This will read the input NIfTI file, apply the specified filter, and save the result
+    to the output file.
+    """
     # get the input TR
     inputtr_fromfile, numinputtrs = tide_io.fmritimeinfo(args.inputfilename)
     print("input data: ", numinputtrs, " timepoints, tr = ", inputtr_fromfile)