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

rapidtide/workflows/regressfrommaps.py

@@ -0,0 +1,308 @@
+#!/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.
+#
+#
+
+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
+import rapidtide.linfitfiltpass as tide_linfitfiltpass
+import rapidtide.makelaggedtcs as tide_makelagged
+
+
+def regressfrommaps(
+    fmri_data_valid: Any,
+    validvoxels: Any,
+    initial_fmri_x: Any,
+    lagtimes: Any,
+    fitmask: Any,
+    genlagtc: Any,
+    mode: Any,
+    outputname: Any,
+    oversamptr: Any,
+    sLFOfitmean: Any,
+    rvalue: Any,
+    r2value: Any,
+    fitNorm: Any,
+    fitcoeff: Any,
+    movingsignal: Any,
+    lagtc: Any,
+    filtereddata: Any,
+    LGR: Any,
+    TimingLGR: Any,
+    regressfiltthreshval: Any,
+    saveminimumsLFOfiltfiles: Any,
+    nprocs_makelaggedtcs: int = 1,
+    nprocs_regressionfilt: int = 1,
+    regressderivs: int = 0,
+    chunksize: int = 50000,
+    showprogressbar: bool = True,
+    alwaysmultiproc: bool = False,
+    saveEVsandquit: bool = False,
+    coefficientsonly: bool = False,
+    timemask: Optional[NDArray] = None,
+    debug: bool = False,
+) -> Tuple[int, NDArray, NDArray]:
+    """
+    Perform regression analysis on fMRI data using lagged timecourses.
+
+    This function generates voxel-specific regressors from lagged timecourses,
+    applies filtering, and performs regression to estimate model coefficients.
+    It supports various modes including cross-validation regression (cvrmap),
+    and can optionally save intermediate results or quit early.
+
+    Parameters
+    ----------
+    fmri_data_valid : array-like
+        Valid fMRI data to be processed.
+    validvoxels : array-like
+        Indices or mask of valid voxels.
+    initial_fmri_x : array-like
+        Initial fMRI timecourse (e.g., stimulus timing).
+    lagtimes : array-like
+        Time lags to be used for generating lagged regressors.
+    fitmask : array-like
+        Mask for selecting voxels to fit.
+    genlagtc : object
+        Generator for lagged timecourses.
+    mode : str
+        Processing mode (e.g., 'cvrmap').
+    outputname : str
+        Base name for output files.
+    oversamptr : float
+        Oversampling rate for timecourse generation.
+    sLFOfitmean : array-like
+        Mean of sLFO fit values.
+    rvalue : array-like
+        R-values from regression.
+    r2value : array-like
+        R-squared values from regression.
+    fitNorm : array-like
+        Normalization values for fit.
+    fitcoeff : array-like
+        Coefficients from the fit.
+    movingsignal : array-like
+        Moving signal components.
+    lagtc : array-like
+        Lagged timecourses.
+    filtereddata : array-like
+        Filtered fMRI data.
+    LGR : object, optional
+        Logger for general logging.
+    TimingLGR : object, optional
+        Logger for timing information.
+    regressfiltthreshval : float
+        Threshold for regression filtering.
+    saveminimumsLFOfiltfiles : bool
+        Whether to save noise removed timeseries.
+    nprocs_makelaggedtcs : int, optional
+        Number of processes for making lagged timecourses (default is 1).
+    nprocs_regressionfilt : int, optional
+        Number of processes for regression filtering (default is 1).
+    regressderivs : int, optional
+        Order of derivatives to include in regressors (default is 0).
+    chunksize : int, optional
+        Size of chunks for processing (default is 50000).
+    showprogressbar : bool, optional
+        Whether to show progress bar (default is True).
+    alwaysmultiproc : bool, optional
+        Force multiprocessing even for small tasks (default is False).
+    saveEVsandquit : bool, optional
+        Save EVs and quit early (default is False).
+    coefficientsonly : bool, optional
+        Return only coefficients (default is False).
+    timemask : NDArray, optional
+       Mask of timepoints to include in regression filtering.
+    debug : bool, optional
+        Enable debug output (default is False).
+
+    Returns
+    -------
+    tuple
+        If `saveEVsandquit` is True, returns (0, regressorset, evset).
+        Otherwise, returns (voxelsprocessed_regressionfilt, regressorset, evset).
+
+    Notes
+    -----
+    - The function modifies `fitcoeff` in-place when `mode == "cvrmap"` by multiplying by 100.
+    - The function uses multiprocessing if `alwaysmultiproc` is True or if `nprocs > 1`.
+    - Filtering is performed using `tide_linfitfiltpass.linfitfiltpass`.
+
+    Examples
+    --------
+    >>> regressfrommaps(
+    ...     fmri_data_valid=data,
+    ...     validvoxels=voxels,
+    ...     initial_fmri_x=stimulus,
+    ...     lagtimes=lags,
+    ...     fitmask=mask,
+    ...     genlagtc=gen,
+    ...     mode="cvrmap",
+    ...     outputname="output",
+    ...     oversamptr=2.0,
+    ...     sLFOfitmean=mean,
+    ...     rvalue=r_vals,
+    ...     r2value=r2_vals,
+    ...     fitNorm=norm,
+    ...     fitcoeff=coeffs,
+    ...     movingsignal=moving,
+    ...     lagtc=lagged_tc,
+    ...     filtereddata=filtered,
+    ...     LGR=logger,
+    ...     TimingLGR=timing_logger,
+    ...     regressfiltthreshval=0.5,
+    ...     saveminimumsLFOfiltfiles=True,
+    ...     nprocs_makelaggedtcs=4,
+    ...     nprocs_regressionfilt=2,
+    ...     regressderivs=2,
+    ...     chunksize=10000,
+    ...     showprogressbar=True,
+    ...     alwaysmultiproc=False,
+    ...     saveEVsandquit=False,
+    ...     coefficientsonly=False,
+    ...     debug=False,
+    ... )
+    """
+    if debug:
+        print("regressfrommaps: Starting")
+        print(f"\t{nprocs_makelaggedtcs=}")
+        print(f"\t{nprocs_regressionfilt=}")
+        print(f"\t{regressderivs=}")
+        print(f"\t{chunksize=}")
+        print(f"\t{showprogressbar=}")
+        print(f"\t{alwaysmultiproc=}")
+        print(f"\t{mode=}")
+        print(f"\t{outputname=}")
+        print(f"\t{oversamptr=}")
+        print(f"\t{regressfiltthreshval=}")
+    rt_floattype = np.float64
+    numvalidspatiallocs = np.shape(validvoxels)[0]
+
+    # generate the voxel specific regressors
+    if LGR is not None:
+        LGR.info("Start lagged timecourse creation")
+    if TimingLGR is not None:
+        TimingLGR.info("Start lagged timecourse creation")
+
+    voxelsprocessed_makelagged = tide_makelagged.makelaggedtcs(
+        genlagtc,
+        initial_fmri_x,
+        fitmask,
+        lagtimes,
+        lagtc,
+        LGR=LGR,
+        nprocs=nprocs_makelaggedtcs,
+        alwaysmultiproc=alwaysmultiproc,
+        showprogressbar=showprogressbar,
+        chunksize=chunksize,
+        rt_floattype=rt_floattype,
+        debug=debug,
+    )
+    if timemask is not None:
+        lagtc = lagtc * timemask[None, :]
+
+    if debug:
+        print(f"\t{lagtimes.shape=}")
+        threshmask = np.where(fitmask > 0, 1, 0)
+        print(f"\t{np.sum(threshmask)} nonzero mask voxels")
+        print(f"\tafter makelaggedtcs: shifted {voxelsprocessed_makelagged} timecourses")
+    if LGR is not None:
+        LGR.info("End lagged timecourse creation")
+    if TimingLGR is not None:
+        TimingLGR.info(
+            "Lagged timecourse creation end",
+            {
+                "message2": voxelsprocessed_makelagged,
+                "message3": "voxels",
+            },
+        )
+
+    if regressderivs > 0:
+        if debug:
+            print(f"adding derivatives up to order {regressderivs} prior to regression")
+        regressorset = tide_linfitfiltpass.makevoxelspecificderivs(lagtc, regressderivs)
+        baseev = (genlagtc.yfromx(initial_fmri_x)).astype(rt_floattype)
+        evset = tide_linfitfiltpass.makevoxelspecificderivs(
+            baseev.reshape((1, -1)), regressderivs
+        ).reshape((-1, 2))
+    else:
+        if debug:
+            print(f"using raw lagged regressors for regression")
+        regressorset = lagtc
+        evset = (genlagtc.yfromx(initial_fmri_x)).astype(rt_floattype)
+    if debug:
+        print(f"{regressorset.shape=}")
+
+    if saveEVsandquit:
+        return 0, regressorset, evset
+
+    # now do the filtering
+    if LGR is not None:
+        LGR.info("Start filtering operation")
+    if TimingLGR is not None:
+        TimingLGR.info("Start filtering operation")
+
+    voxelsprocessed_regressionfilt = tide_linfitfiltpass.linfitfiltpass(
+        numvalidspatiallocs,
+        fmri_data_valid,
+        regressfiltthreshval,
+        regressorset,
+        sLFOfitmean,
+        rvalue,
+        r2value,
+        fitcoeff,
+        fitNorm,
+        movingsignal,
+        filtereddata,
+        coefficientsonly=coefficientsonly,
+        nprocs=nprocs_regressionfilt,
+        alwaysmultiproc=alwaysmultiproc,
+        showprogressbar=showprogressbar,
+        verbose=(LGR is not None),
+        chunksize=chunksize,
+        rt_floattype=rt_floattype,
+        debug=debug,
+    )
+
+    if mode == "cvrmap":
+        # if we are doing a cvr map, multiply the fitcoeff by 100, so we are in percent
+        fitcoeff *= 100.0
+
+    # determine what was removed
+    if not coefficientsonly:
+        removeddata = fmri_data_valid - filtereddata
+        noiseremoved = np.var(removeddata, axis=0)
+        if saveminimumsLFOfiltfiles:
+            tide_io.writebidstsv(
+                f"{outputname}_desc-lfofilterNoiseRemoved_timeseries",
+                noiseremoved,
+                1.0 / oversamptr,
+                starttime=0.0,
+                columns=[f"removedbyglm"],
+                extraheaderinfo={
+                    "Description": "Variance over space of data removed by the sLFO filter at each timepoint"
+                },
+                append=False,
+            )
+
+    if debug:
+        print("regressfrommaps: End\n\n")
+
+    return voxelsprocessed_regressionfilt, regressorset, evset

rapidtide/workflows/resamplenifti.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,10 @@ with warnings.catch_warnings():
     else:
         pyfftwpresent = True
 
+from argparse import Namespace
+from typing import Any, Callable, Dict, List, Optional, Tuple, Union
+
+from numpy.typing import NDArray
 from scipy import fftpack
 
 import rapidtide.io as tide_io
@@ -40,9 +44,37 @@ if pyfftwpresent:
     pyfftw.interfaces.cache.enable()
 
 
-def _get_parser():
+def _get_parser() -> Any:
     """
-    Argument parser for resamplenifti
+    Argument parser for resamplenifti.
+
+    Creates and configures an argument parser for the resamplenifti command-line tool
+    that resamples NIfTI files to a different temporal resolution (TR).
+
+    Returns
+    -------
+    argparse.ArgumentParser
+        Configured argument parser object with all required and optional arguments
+        for the resamplenifti tool.
+
+    Notes
+    -----
+    The returned parser includes the following positional arguments:
+    - inputfile: Path to the input NIfTI file
+    - outputfile: Path to the output NIfTI file
+    - outputtr: Target temporal resolution in seconds
+
+    And the following optional arguments:
+    - --noantialias: Disable antialiasing filter (enabled by default)
+    - --normalize: Normalize data and save as UINT16 (disabled by default)
+    - --debug: Print debugging information (disabled by default)
+
+    Examples
+    --------
+    >>> parser = _get_parser()
+    >>> args = parser.parse_args(['input.nii', 'output.nii', '2.0'])
+    >>> print(args.inputfile)
+    'input.nii'
     """
     parser = argparse.ArgumentParser(
         prog="resamplenifti",
@@ -78,7 +110,57 @@ def _get_parser():
     return parser
 
 
-def resamplenifti(args):
+def resamplenifti(args: Any) -> None:
+    """
+    Resample a 4D NIfTI file to a specified temporal resolution.
+
+    This function reads a 4D NIfTI file, resamples its time series data to a
+    new temporal resolution specified by `args.outputtr`, and saves the
+    resampled data to a new NIfTI file. The resampling is performed using
+    spline interpolation, and optional antialiasing is applied based on the
+    input and output temporal resolutions.
+
+    Parameters
+    ----------
+    args : argparse.Namespace
+        An object containing the following attributes:
+        - inputfile : str
+            Path to the input NIfTI file.
+        - outputfile : str
+            Path to the output NIfTI file.
+        - outputtr : float
+            Desired output temporal resolution (TR) in seconds.
+        - antialias : bool, optional
+            Whether to apply antialiasing during resampling. Default is True.
+        - debug : bool, optional
+            If True, print debugging information. Default is False.
+
+    Returns
+    -------
+    None
+        This function does not return a value but saves the resampled NIfTI
+        file to the specified output path.
+
+    Notes
+    -----
+    - If the input TR is greater than the output TR (i.e., upsampling), antialiasing
+      is automatically disabled.
+    - The function processes each voxel individually, which may be time-consuming
+      for large datasets.
+    - The output NIfTI header is updated to reflect the new temporal resolution.
+
+    Examples
+    --------
+    >>> import argparse
+    >>> args = argparse.Namespace(
+    ...     inputfile='input.nii.gz',
+    ...     outputfile='output.nii.gz',
+    ...     outputtr=1.0,
+    ...     antialias=True,
+    ...     debug=False
+    ... )
+    >>> resamplenifti(args)
+    """
     # get the input TR
     inputtr, numinputtrs = tide_io.fmritimeinfo(args.inputfile)
     if args.debug:

rapidtide/workflows/resampletc.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,18 +17,49 @@
 #
 #
 import argparse
+from argparse import Namespace
+from typing import Any, Callable, Dict, List, Optional, Tuple, Union
 
 import matplotlib.pyplot as plt
 import numpy as np
+from numpy.typing import NDArray
 
 import rapidtide.io as tide_io
 import rapidtide.resample as tide_resample
 import rapidtide.workflows.parser_funcs as pf
 
 
-def _get_parser():
+def _get_parser() -> Any:
     """
-    Argument parser for resamp1tc
+    Argument parser for resamp1tc.
+
+    This function constructs and returns an `argparse.ArgumentParser` object configured
+    for parsing command-line arguments for the `resamp1tc` utility. It defines required
+    and optional arguments needed to resample a timeseries file.
+
+    Returns
+    -------
+    argparse.ArgumentParser
+        Configured argument parser for the resamp1tc utility.
+
+    Notes
+    -----
+    The parser includes the following required arguments:
+
+    - ``inputfile``: Path to the input timeseries file.
+    - ``insamplerate``: Input sample rate in Hz.
+    - ``outputfile``: Path to the output resampled file.
+    - ``outsamplerate``: Output sample rate in Hz.
+
+    Optional arguments include:
+
+    - ``--nodisplay``: Do not display data.
+    - ``--noantialias``: Disable antialiasing.
+
+    Examples
+    --------
+    >>> parser = _get_parser()
+    >>> args = parser.parse_args()
     """
     parser = argparse.ArgumentParser(
         prog="resampletc",
@@ -91,7 +122,64 @@ def _get_parser():
     return parser
 
 
-def resampletc(args):
+def resampletc(args: Any) -> None:
+    """
+    Resample a time series signal from an input file to a specified output sampling rate.
+
+    This function reads a time series from a text file, resamples it to a new sampling rate,
+    and writes the resampled data to an output file. Optionally, it displays the original
+    and resampled signals for visual comparison.
+
+    Parameters
+    ----------
+    args : Any
+        An object containing the following attributes:
+        - `inputfile` : str
+            Path to the input text file containing the time series data.
+        - `outputfile` : str
+            Path to the output text file where resampled data will be written.
+        - `insamplerate` : float
+            Input sampling rate (Hz) of the data in the input file.
+        - `outsamplerate` : float
+            Desired output sampling rate (Hz) for the resampled data.
+        - `antialias` : bool
+            Whether to apply anti-aliasing during resampling.
+        - `display` : bool
+            If True, plots the original and resampled signals.
+        - `starttime` : float, optional
+            Start time for the output signal. If None, uses the start time from input.
+        - `endtime` : float, optional
+            End time for the output signal. If None, uses the end time from input.
+
+    Returns
+    -------
+    None
+        This function does not return a value. It writes the resampled data to a file
+        and optionally displays a plot.
+
+    Notes
+    -----
+    - The input file is expected to contain a single column of time series data.
+    - If the sampling rate specified in the input file does not match `args.insamplerate`,
+      a warning is printed.
+    - The function uses `tide_resample.arbresample` for resampling with configurable
+      anti-aliasing.
+    - If `args.display` is True, the original and resampled signals are plotted
+      with the original in black and the resampled in red.
+
+    Examples
+    --------
+    >>> import argparse
+    >>> args = argparse.Namespace(
+    ...     inputfile='input.txt',
+    ...     outputfile='output.txt',
+    ...     insamplerate=10.0,
+    ...     outsamplerate=5.0,
+    ...     antialias=True,
+    ...     display=False
+    ... )
+    >>> resampletc(args)
+    """
     intimestep = 1.0 / args.insamplerate
     outtimestep = 1.0 / args.outsamplerate
     (