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

rapidtide/workflows/spectrogram.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,19 +18,54 @@
 #
 import argparse
 import sys
+from typing import Any, Tuple, Union
 
 import matplotlib.pyplot as plt
 import numpy as np
 from mpl_toolkits.axes_grid1 import make_axes_locatable
-from scipy.signal import check_NOLA, stft
+from numpy.typing import NDArray
+from scipy.signal import ShortTimeFFT, check_NOLA, stft
 
 import rapidtide.io as tide_io
 from rapidtide.workflows.parser_funcs import is_float, is_int, is_valid_file
 
+NPFloat2DArray = NDArray[Union[np.float32, np.float64]]
 
-def _get_parser():
+
+def _get_parser() -> Any:
     """
-    Argument parser for spectrogram
+    Argument parser for spectrogram.
+
+    This function creates and configures an argument parser for the spectrogram
+    command-line tool that computes and displays spectrograms from text files
+    containing timecourse data.
+
+    Returns
+    -------
+    argparse.ArgumentParser
+        Configured argument parser object with all required and optional
+        arguments for spectrogram computation.
+
+    Notes
+    -----
+    The parser expects a text file containing one data point per line and a
+    specified sample rate. The spectrogram is computed using the Short-Time
+    Fourier Transform (STFT) with configurable segment length.
+
+    Examples
+    --------
+    >>> parser = _get_parser()
+    >>> args = parser.parse_args(['input.txt', '44100'])
+    >>> print(args.textfilename)
+    'input.txt'
+    >>> print(args.samplerate)
+    44100
+
+    See Also
+    --------
+    is_valid_file : Validates input file existence and readability
+    is_float : Validates float conversion
+    is_int : Validates integer conversion
     """
     parser = argparse.ArgumentParser(
         prog="spectrogram",
@@ -38,15 +73,14 @@ def _get_parser():
         allow_abbrev=False,
     )
 
-    # Required arguments
+    # Required argument
     parser.add_argument(
-        "textfilename",
+        "inputfile",
         type=lambda x: is_valid_file(parser, x),
         help="The input data file (text file containing a timecourse, one point per line).",
     )
-    parser.add_argument(
-        "samplerate", type=lambda x: is_float(parser, x), help="Sample rate in Hz."
-    )
+
+    # Optional arguments
     parser.add_argument(
         "--nperseg",
         dest="nperseg",
@@ -55,6 +89,15 @@ def _get_parser():
         help=("The number of points to include in each spectrogram (default is 128)."),
         default=128,
     )
+    parser.add_argument(
+        "--samplerate",
+        dest="samplerate",
+        metavar="RATE",
+        action="store",
+        type=lambda x: is_float(parser, x),
+        help="Sample rate in Hz.",
+        default=None,
+    )
     parser.add_argument(
         "--debug",
         dest="debug",
@@ -66,32 +109,138 @@ def _get_parser():
     return parser
 
 
-def calcspecgram(x, time, nperseg=32, windowtype="hann"):
-    """Make and plot a log-scaled spectrogram"""
+def calcspecgram(
+    x: NDArray[np.floating[Any]],
+    time: NDArray[np.floating[Any]],
+    nperseg: int = 32,
+    windowtype: str = "hann",
+) -> Tuple[NDArray, NDArray, NDArray, bool]:
+    """
+    Make and plot a log-scaled spectrogram.
+
+    This function computes a spectrogram using the Short-Time Fourier Transform (STFT)
+    with configurable window parameters and returns frequency, time, and STFT data
+    along with a check for invertibility.
+
+    Parameters
+    ----------
+    x : NDArray[np.floating[Any]]
+        Input signal data to compute the spectrogram for.
+    time : NDArray[np.floating[Any]]
+        Time vector corresponding to the input signal. Used to calculate sampling
+        frequency from the time differences.
+    nperseg : int, optional
+        Length of each segment for the STFT, by default 32.
+    windowtype : str, optional
+        Type of window to use for the STFT, by default "hann".
+
+    Returns
+    -------
+    freq : ndarray
+        Array of frequencies corresponding to the spectrogram rows.
+    segtimes : ndarray
+        Array of time points corresponding to the spectrogram columns.
+    thestft : ndarray
+        Short-Time Fourier Transform of the input signal.
+    isinvertable : bool
+        Boolean flag indicating whether the window satisfies the Non-Overlap
+        Additivity of Overlapped Windows (NOLA) constraint for invertibility.
+
+    Notes
+    -----
+    The function calculates the sampling frequency from the time vector and uses
+    the ShortTimeFFT library to compute the STFT. The window overlap is set to
+    ensure maximum overlap (nperseg - 1) for optimal spectrogram resolution.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from scipy.signal import chirp
+    >>> t = np.linspace(0, 1, 1000)
+    >>> x = chirp(t, f0=1, f1=10, t1=1, method='linear')
+    >>> freq, times, stft, invertible = calcspecgram(x, t)
+    >>> print(f"Frequency range: {freq[0]:.2f} to {freq[-1]:.2f} Hz")
+    >>> print(f"Time range: {times[0]:.2f} to {times[-1]:.2f} seconds")
+    """
     dt = np.diff(time)[0]  # In days...
     fs = 1.0 / dt
-    nfft = nperseg
     noverlap = nperseg - 1
 
-    freq, segtimes, thestft = stft(
-        x,
-        fs=fs,
-        window=windowtype,
-        nperseg=nperseg,
-        noverlap=noverlap,
-        nfft=nfft,
-        detrend="linear",
-        return_onesided=True,
-        boundary="zeros",
-        padded=True,
-        axis=-1,
+    SFT = ShortTimeFFT.from_window(
+        windowtype,
+        fs,
+        nperseg,
+        noverlap,
+        mfft=nperseg,
+        fft_mode="onesided",
+        scale_to="magnitude",
+        phase_shift=None,
     )
+    freq = SFT.f
+    thestft = SFT.stft(x, p0=0, p1=(len(x) - noverlap) // SFT.hop, k_offset=nperseg // 2)
+    segtimes = SFT.t(len(x), p0=0, p1=(len(x) - noverlap) // SFT.hop, k_offset=nperseg // 2)
 
     isinvertable = check_NOLA(windowtype, nperseg, noverlap, tol=1e-10)
     return freq, segtimes, thestft, isinvertable
 
 
-def showspecgram(thestft, time, freq, ax, fig, mode="mag"):
+def showspecgram(
+    thestft: Any, time: Any, freq: Any, ax: Any, fig: Any, mode: str = "mag"
+) -> Tuple[Any, Any]:
+    """
+    Display a spectrogram plot based on the provided STFT data.
+
+    This function visualizes the Short-Time Fourier Transform (STFT) of a signal
+    in the form of a spectrogram. It supports multiple display modes including
+    magnitude, phase, real, and imaginary components. The function also handles
+    logarithmic scaling for amplitude values and includes a colorbar with appropriate
+    labeling.
+
+    Parameters
+    ----------
+    thestft : Any
+        The Short-Time Fourier Transform (STFT) of the signal. Typically a 2D array
+        where rows correspond to frequency bins and columns to time frames.
+    time : Any
+        Time vector corresponding to the STFT columns. Used for x-axis labeling.
+    freq : Any
+        Frequency vector corresponding to the STFT rows. Used for y-axis labeling.
+    ax : Any
+        Matplotlib axis object on which the spectrogram will be plotted.
+    fig : Any
+        Matplotlib figure object used to create the colorbar.
+    mode : str, optional
+        The mode of visualization. Options are:
+        - "mag": Magnitude of the STFT (default)
+        - "phase": Phase of the STFT
+        - "real": Real part of the STFT
+        - "imag": Imaginary part of the STFT
+
+    Returns
+    -------
+    Tuple[Any, Any]
+        A tuple containing:
+        - im: The image object returned by `pcolormesh`
+        - cbar: The colorbar object added to the plot
+
+    Notes
+    -----
+    - For magnitude mode, the data is log-scaled using `log10`.
+    - For phase mode, the data is scaled between -π and π.
+    - The y-axis is set to range from `freq[1]` to `freq.max()` to avoid potential
+      issues with zero frequency bins.
+    - X-axis tick labels are hidden for cleaner visualization.
+    - If an invalid `mode` is provided, the function will print an error and exit.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> import matplotlib.pyplot as plt
+    >>> # Assuming `sft` is your STFT data, `t` is time, `f` is frequency
+    >>> fig, ax = plt.subplots()
+    >>> im, cbar = showspecgram(sft, t, f, ax, fig, mode="mag")
+    >>> plt.show()
+    """
     # Log scaling for amplitude values
     if mode == "mag":
         spec_img = np.log10(np.abs(thestft))
@@ -145,13 +294,84 @@ def showspecgram(thestft, time, freq, ax, fig, mode="mag"):
     return im, cbar
 
 
-def make_legend_axes(ax):
+def make_legend_axes(ax: Any) -> object:
+    """
+    Create a new axes for legend placement next to the given axes.
+
+    This function creates a new axes object positioned to the right of the
+    provided axes, which can be used for placing legends. The new axes is
+    created using matplotlib's make_axes_locatable utility.
+
+    Parameters
+    ----------
+    ax : matplotlib.axes.Axes
+        The original axes object to which the legend axes will be appended.
+
+    Returns
+    -------
+    matplotlib.axes.Axes
+        The newly created axes object that can be used for legend placement.
+
+    Notes
+    -----
+    The legend axes is positioned to the right of the original axes with:
+    - Size: 0.4 inches width
+    - Padding: 0.2 inches from the original axes
+
+    Examples
+    --------
+    >>> import matplotlib.pyplot as plt
+    >>> fig, ax = plt.subplots()
+    >>> ax.plot([1, 2, 3], [1, 4, 9])
+    >>> legend_ax = make_legend_axes(ax)
+    >>> ax.legend(['data'], bbox_to_anchor=(1.05, 1), loc='upper left')
+    >>> plt.show()
+    """
     divider = make_axes_locatable(ax)
     legend_ax = divider.append_axes("right", 0.4, pad=0.2)
     return legend_ax
 
 
-def ndplot(x, time, thelabel, nperseg=32):
+def ndplot(x: Any, time: Any, thelabel: Any, nperseg: int = 32) -> None:
+    """
+    Plot spectrogram magnitude, phase, and time-domain signal.
+
+    This function computes and displays a spectrogram of the input signal `x` using
+    the Short-Time Fourier Transform (STFT). It shows the magnitude and phase of
+    the spectrogram in separate subplots, and overlays the original time-domain
+    signal on a third subplot.
+
+    Parameters
+    ----------
+    x : array-like
+        Input signal to be analyzed.
+    time : array-like
+        Time vector corresponding to the signal `x`.
+    thelabel : str
+        Label used for plotting titles.
+    nperseg : int, optional
+        Length of each segment for the STFT. Default is 32.
+
+    Returns
+    -------
+    None
+        This function does not return any value. It displays the plot directly.
+
+    Notes
+    -----
+    - The function uses `calcspecgram` to compute the STFT and checks if the
+      spectrogram is invertible.
+    - The magnitude and phase are plotted in the first two subplots.
+    - The time-domain signal is overlaid in the third subplot.
+    - The function relies on `showspecgram` for plotting the spectrograms.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> t = np.linspace(0, 1, 1000)
+    >>> x = np.sin(2 * np.pi * 50 * t)
+    >>> ndplot(x, t, "Example Signal")
+    """
     print("arrived in ndplot")
     fig = plt.figure()
 
@@ -196,7 +416,45 @@ def ndplot(x, time, thelabel, nperseg=32):
     # plt.subplots_adjust(hspace=0.0)
 
 
-def spectrogram(args):
+def spectrogram(args: Any) -> None:
+    """
+    Compute and display spectrogram of time series data from text file.
+
+    This function reads time series data from a text file, computes its spectrogram
+    using Welch's method, and displays the result. The spectrogram shows how
+    the frequency content of the signal changes over time.
+
+    Parameters
+    ----------
+    args : Any
+        Command line arguments containing:
+        - textfilename : str
+            Path to the text file containing time series data
+        - samplerate : float
+            Sampling rate of the tidal data in Hz
+        - nperseg : int, optional
+            Length of each segment for FFT (default: 256)
+        - debug : bool, optional
+            Enable debug output (default: False)
+
+    Returns
+    -------
+    None
+        This function displays the spectrogram plot and does not return any value.
+
+    Notes
+    -----
+    The function uses Welch's method for spectral estimation, which divides the
+    signal into overlapping segments and averages their periodograms. The time
+    axis is automatically calculated based on the sampling rate and data length.
+
+    Examples
+    --------
+    >>> import argparse
+    >>> args = argparse.Namespace(textfilename='tidal_data.txt',
+    ...                          samplerate=10.0, nperseg=512, debug=False)
+    >>> spectrogram(args)
+    """
     # get the command line parameters
     try:
         args = _get_parser().parse_args()
@@ -206,12 +464,27 @@ def spectrogram(args):
     if args.debug:
         print(args)
 
-    # handle required args first
-    timestep = 1.0 / args.samplerate
+    # read in data
+    (
+        samplerate,
+        starttime,
+        colnames,
+        yvec,
+        compressed,
+        filetype,
+    ) = tide_io.readvectorsfromtextfile(args.inputfile, onecol=True)
+
+    # get the sample rate squared away
+    if args.samplerate is not None:
+        samplerate = args.samplerate
+    else:
+        if samplerate is None:
+            print("Sample rate must be specified in input file or with --samplerate")
+            sys.exit()
+    timestep = 1.0 / samplerate
 
-    yvec = tide_io.readvec(args.textfilename)
-    xvec = np.arange(0.0, len(yvec), 1.0) * timestep
+    xvec = np.arange(0.0, len(yvec), 1.0) * timestep + starttime
 
-    thelabel = args.textfilename
+    thelabel = args.inputfile
     ndplot(yvec, xvec, thelabel, nperseg=args.nperseg)
     plt.show()

rapidtide/workflows/synthASL.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
 #
-#   Copyright 2020-2024 Blaise Frederick
+#   Copyright 2020-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,14 +17,42 @@
 #
 #
 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.io as tide_io
 from rapidtide.RapidtideDataset import RapidtideDataset
 
 
-def _get_parser():
+def _get_parser() -> Any:
+    """
+    Get the argument parser for the synthASL command-line tool.
+
+    This function constructs and returns an `argparse.ArgumentParser` object configured
+    with the necessary arguments for running the synthASL tool, which uses rapidtide
+    output to predict ASL (Arterial Spin Labeling) images.
+
+    Returns
+    -------
+    argparse.ArgumentParser
+        Configured argument parser with required and optional arguments for synthASL.
+
+    Notes
+    -----
+    The parser includes both required positional arguments and several optional
+    arguments that control the ASL synthesis process. Default values are set according
+    to typical parameters used in ASL analysis.
+
+    Examples
+    --------
+    >>> parser = _get_parser()
+    >>> args = parser.parse_args(['dataset_name', 'output.nii.gz'])
+    >>> print(args.dataset)
+    'dataset_name'
+    """
     # get the command line parameters
     parser = argparse.ArgumentParser(
         prog="synthASL",
@@ -70,8 +98,73 @@ def _get_parser():
     return parser
 
 
-def calcASL(lags, strengths, widths, mask, tagoffset=2.945, pld=1.8, TI=1.8, bloodT1=1.841):
-    theaslimage = lags * 0.0
+def calcASL(
+    lags: Any,
+    strengths: Any,
+    widths: Any,
+    mask: Any,
+    tagoffset: float = 2.945,
+    pld: float = 1.8,
+    TI: float = 1.8,
+    bloodT1: float = 1.841,
+) -> None:
+    """
+    Calculate ASL (Arterial Spin Labeling) signal based on lags, strengths, and timing parameters.
+
+    This function computes the ASL signal by applying temporal dynamics to the input lags and
+    strengths, considering blood T1 relaxation effects and tagging timing parameters.
+
+    Parameters
+    ----------
+    lags : array-like
+        Time lags for the ASL signal calculation
+    strengths : array-like
+        Signal strengths corresponding to the lags
+    widths : array-like
+        Widths parameter (not used in current implementation)
+    mask : array-like
+        Binary mask for region of interest
+    tagoffset : float, optional
+        Tagging offset in seconds, default is 2.945
+    pld : float, optional
+        Preparation delay in seconds, default is 1.8
+    TI : float, optional
+        Inversion time in seconds, default is 1.8
+    bloodT1 : float, optional
+        Blood T1 relaxation time in seconds, default is 1.841
+
+    Returns
+    -------
+    tuple
+        A tuple containing:
+        - theaslimage : array-like
+          Calculated ASL image signal
+        - tagdecayfac : array-like
+          Tagging decay factor
+        - oxyfac : array-like
+          Oxygenation factor (constant value of 1.0)
+        - cbvfac : array-like
+          CBV (Cerebral Blood Volume) factor
+        - calcmask : array-like
+          Calculated mask with time constraints
+        - offsets : array-like
+          Time offsets after adding tagoffset
+
+    Notes
+    -----
+    The function applies exponential decay based on blood T1 relaxation and only considers
+    positive delays after the preparation delay (pld). The calculation uses a linear
+    interpolation over 50 time points between pld and pld + TI.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> lags = np.array([0.5, 1.0, 1.5])
+    >>> strengths = np.array([1.0, 1.5, 2.0])
+    >>> mask = np.array([1, 1, 1])
+    >>> result = calcASL(lags, strengths, None, mask)
+    """
+    theaslimage = np.zeros_like(lags)
 
     # convert rapidtide delays to time from tagging, and only keep positive delays after pld
     offsets = lags + tagoffset
@@ -79,13 +172,71 @@ def calcASL(lags, strengths, widths, mask, tagoffset=2.945, pld=1.8, TI=1.8, blo
 
     for imtime in np.linspace(pld, pld + TI, num=50, endpoint=True):
         tagdecayfac = np.exp(-(offsets + imtime) / bloodT1) * calcmask
-        oxyfac = strengths * 0.0 + 1.0
+        oxyfac = np.ones_like(strengths)
         cbvfac = np.fabs(strengths) * oxyfac
         theaslimage += tagdecayfac * cbvfac
     return theaslimage, tagdecayfac, oxyfac, cbvfac, calcmask, offsets
 
 
-def synthASL(args):
+def synthASL(args: Any) -> None:
+    """
+    Generate synthetic ASL (Arterial Spin Labeling) images and associated parameters.
+
+    This function reads ASL dataset parameters from a specified input dataset,
+    computes synthetic ASL signal using the `calcASL` function, and saves the
+    resulting images and intermediate outputs as NIfTI files.
+
+    Parameters
+    ----------
+    args : Any
+        Command-line arguments object containing the following attributes:
+        - dataset : str
+            Path to the input dataset.
+        - outputfilename : str
+            Base name for output NIfTI files.
+        - bloodT1 : float
+            Blood T1 relaxation time in seconds.
+        - tagoffset : float
+            Tag offset in seconds.
+        - pld : float
+            Post-labeling delay in seconds.
+        - labelduration : float
+            Labeling pulse duration in seconds.
+
+    Returns
+    -------
+    None
+        This function does not return a value but writes multiple NIfTI files
+        to disk, including:
+        - `<outputfilename>_ASL.nii.gz`
+        - `<outputfilename>_tagdecayfac.nii.gz`
+        - `<outputfilename>_oxyfac.nii.gz`
+        - `<outputfilename>_cbvfac.nii.gz`
+        - `<outputfilename>_calcmask.nii.gz`
+        - `<outputfilename>_offsets.nii.gz`
+        - `<outputfilename>_lagmask.nii.gz`
+        - `<outputfilename>_lagtimes.nii.gz`
+        - `<outputfilename>_lagstrengths.nii.gz`
+
+    Notes
+    -----
+    The function relies on the `RapidtideDataset` class to load overlay data
+    and uses `calcASL` to compute the synthetic ASL signal. All outputs are
+    saved using `tide_io.savetonifti`.
+
+    Examples
+    --------
+    >>> import argparse
+    >>> args = argparse.Namespace(
+    ...     dataset="path/to/dataset",
+    ...     outputfilename="output",
+    ...     bloodT1=1.6,
+    ...     tagoffset=0.0,
+    ...     pld=1.5,
+    ...     labelduration=1.0
+    ... )
+    >>> synthASL(args)
+    """
     # get the command line parameters
     try:
         args = _get_parser().parse_args()