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

rapidtide/workflows/histnifti.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,8 +19,11 @@
 import argparse
 import copy
 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
 from tqdm import tqdm
 
 import rapidtide.io as tide_io
@@ -29,7 +32,47 @@ import rapidtide.util as tide_util
 import rapidtide.workflows.parser_funcs as pf
 
 
-def _get_parser():
+def _get_parser() -> Any:
+    """
+    Generate and return an argument parser for the histnifti command-line tool.
+
+    This function constructs an `argparse.ArgumentParser` object configured with
+    all necessary arguments for processing NIFTI files and generating histograms
+    of their voxel values. It supports various options for controlling binning,
+    masking, normalization, and display behavior.
+
+    Returns
+    -------
+    argparse.ArgumentParser
+        Configured argument parser object ready to parse command-line arguments.
+
+    Notes
+    -----
+    The parser includes the following positional and optional arguments:
+
+    - Positional arguments:
+        - inputfile: Path to the input NIFTI file.
+        - outputroot: Root name for output files.
+
+    - Optional arguments:
+        - --histlen: Set histogram length to LEN (default: auto).
+        - --minval: Minimum bin value in histogram.
+        - --maxval: Maximum bin value in histogram.
+        - --robustrange: Use robust range (2nd to 98th percentile) for histogram limits.
+        - --transform: Replace data values with their percentile scores.
+        - --nozero: Exclude zero values from histogram.
+        - --nozerothresh: Threshold for considering values as zero (default: 0.01).
+        - --normhist: Return probability density instead of raw counts.
+        - --maskfile: Only process voxels within a 3D mask.
+        - --nodisplay: Do not display histogram.
+
+    Examples
+    --------
+    >>> parser = _get_parser()
+    >>> args = parser.parse_args(['input.nii', 'output_root'])
+    >>> print(args.inputfile)
+    'input.nii'
+    """
     # get the command line parameters
     parser = argparse.ArgumentParser(
         prog="histnifti",
@@ -119,7 +162,80 @@ def _get_parser():
     return parser
 
 
-def histnifti(args):
+def histnifti(args: Any) -> None:
+    """
+    Compute and save histograms, sorted data, and percentiles from NIfTI image data.
+
+    This function reads input NIfTI data and optionally a mask, computes histograms
+    for each voxel (or across all voxels if 3D), and saves sorted data, percentiles,
+    and histogram results as NIfTI files. It supports both 3D and 4D data processing.
+
+    Parameters
+    ----------
+    args : argparse.Namespace
+        Command-line arguments containing:
+        - inputfile : str
+            Path to the input NIfTI file.
+        - maskfile : str, optional
+            Path to the mask NIfTI file. If None, a full mask is generated.
+        - outputroot : str
+            Root name for output files.
+        - robustrange : bool
+            If True, use 2nd and 98th percentiles for histogram range.
+        - minval : float, optional
+            Minimum value for histogram range.
+        - maxval : float, optional
+            Maximum value for histogram range.
+        - histlen : int, optional
+            Number of histogram bins. If None, computed based on data size.
+        - nozero : bool
+            If True, exclude zero values from histogram calculation.
+        - nozerothresh : float
+            Threshold for excluding zero-like values when `nozero` is True.
+        - transform : bool
+            If True, apply a transformation to the data.
+        - display : bool
+            If True, display histogram plots.
+        - normhist : bool
+            If True, normalize histogram values.
+
+    Returns
+    -------
+    None
+        This function does not return a value but saves multiple NIfTI files:
+        - `<outputroot>_sorted.nii.gz`: Sorted time series data.
+        - `<outputroot>_pcts.nii.gz`: Percentile values.
+        - `<outputroot>_hists.nii.gz`: Histogram data per voxel.
+        - `<outputroot>_transformed.nii.gz`: Transformed data (if `transform` is True).
+        - `<outputroot>_hist.txt`: Histogram plot (if `display` is True).
+
+    Notes
+    -----
+    - For 4D data, the function computes histograms, sorted arrays, and percentiles
+      for each voxel.
+    - For 3D data, the function can compute a global histogram or apply a transformation.
+    - The function uses `tide_io` for reading/writing NIfTI files and `tide_stats` for
+      statistical operations.
+
+    Examples
+    --------
+    >>> import argparse
+    >>> args = argparse.Namespace(
+    ...     inputfile='data.nii.gz',
+    ...     maskfile=None,
+    ...     outputroot='output',
+    ...     robustrange=False,
+    ...     minval=None,
+    ...     maxval=None,
+    ...     histlen=None,
+    ...     nozero=False,
+    ...     nozerothresh=0.0,
+    ...     transform=False,
+    ...     display=False,
+    ...     normhist=False
+    ... )
+    >>> histnifti(args)
+    """
     # set default variable values
     thepercentiles = [0.2, 0.25, 0.5, 0.75, 0.98]
     thepvalnames = []
@@ -294,7 +410,7 @@ def histnifti(args):
         if args.transform:
             thehist, bins = np.histogram(validdata, bins=thehistlen, range=(histmin, histmax))
             npbins = np.asarray(bins[:-1], dtype=float) + (bins[1] - bins[0]) / 2.0
-            transformeddataasmatrix = dataasmatrix * 0.0
+            transformeddataasmatrix = np.zeros_like(dataasmatrix)
             for thevoxel in validvoxels:
                 transformeddataasmatrix[thevoxel] = (
                     100.0 * tide_util.valtoindex(npbins, dataasmatrix[thevoxel]) / len(npbins)

rapidtide/workflows/histtc.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,39 @@
 #
 #
 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
 import rapidtide.stats as tide_stats
 import rapidtide.workflows.parser_funcs as pf
 
 
-def _get_parser():
+def _get_parser() -> Any:
     """
-    Argument parser for histtc
+    Argument parser for histtc.
+
+    This function constructs and returns an `argparse.ArgumentParser` object configured
+    for parsing command-line arguments for the `histtc` tool, which generates histograms
+    from timecourse data.
+
+    Returns
+    -------
+    argparse.ArgumentParser
+        Configured argument parser for histtc.
+
+    Notes
+    -----
+    The parser includes both required and optional arguments for specifying input/output
+    files, histogram bin settings, and various data filtering options.
+
+    Examples
+    --------
+    >>> parser = _get_parser()
+    >>> args = parser.parse_args(['--inputfilename', 'data.txt', '--outputroot', 'output'])
     """
     parser = argparse.ArgumentParser(
         prog="histtc",
@@ -108,7 +130,66 @@ def _get_parser():
     return parser
 
 
-def histtc(args):
+def histtc(args: Any) -> None:
+    """
+    Compute and save a histogram of input data, optionally filtered and normalized.
+
+    This function reads input data from a text file, computes specified percentiles,
+    and generates a histogram with optional normalization and range settings.
+
+    Parameters
+    ----------
+    args : argparse.Namespace
+        An object containing the following attributes:
+        - inputfilename : str
+            Path to the input text file containing the data.
+        - debug : bool
+            If True, print debug information during execution.
+        - nozero : bool
+            If True, exclude values with absolute magnitude less than or equal to `nozerothresh`.
+        - nozerothresh : float
+            Threshold for excluding zero-like values when `nozero` is True.
+        - histlen : int
+            Number of bins for the histogram.
+        - outputroot : str
+            Root name for output files.
+        - robustrange : bool
+            If True, use robust range (2nd and 98th percentiles) for histogram.
+        - minval : float, optional
+            Minimum value for histogram range. If None, use data minimum.
+        - maxval : float, optional
+            Maximum value for histogram range. If None, use data maximum.
+        - normhist : bool
+            If True, normalize the histogram.
+
+    Returns
+    -------
+    None
+        This function does not return a value but saves a histogram to disk.
+
+    Notes
+    -----
+    The function uses `tide_io.readvectorsfromtextfile` to read input data and
+    `tide_stats.getfracvals` to compute percentiles. It then calls
+    `tide_stats.makeandsavehistogram` to generate and save the histogram.
+
+    Examples
+    --------
+    >>> import argparse
+    >>> args = argparse.Namespace(
+    ...     inputfilename='data.txt',
+    ...     debug=False,
+    ...     nozero=True,
+    ...     nozerothresh=1e-6,
+    ...     histlen=50,
+    ...     outputroot='output',
+    ...     robustrange=False,
+    ...     minval=None,
+    ...     maxval=None,
+    ...     normhist=True
+    ... )
+    >>> histtc(args)
+    """
     # set default variable values
     thepercentiles = [0.2, 0.25, 0.5, 0.75, 0.98]
     thepvalnames = []

rapidtide/workflows/{glmfilt.py → linfitfilt.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,20 +17,47 @@
 #
 #
 import argparse
+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 is_valid_file
 
 
-def _get_parser():
+def _get_parser() -> Any:
     """
-    Argument parser for glmfilt
+    Argument parser for linfitfilt.
+
+    This function constructs and returns an `argparse.ArgumentParser` object configured
+    for the `linfitfilt` command-line tool. It defines all required and optional arguments
+    needed to specify input files, regression parameters, and output options.
+
+    Returns
+    -------
+    argparse.ArgumentParser
+        Configured argument parser for the linfitfilt tool.
+
+    Notes
+    -----
+    The parser is designed to handle:
+    - Input NIfTI files (3D or 4D)
+    - EV (event-related) files for regression
+    - Data masking options
+    - Timecourse skipping for fitting
+    - Output filtering and saving options
+
+    Examples
+    --------
+    >>> parser = _get_parser()
+    >>> args = parser.parse_args()
     """
     parser = argparse.ArgumentParser(
-        prog="glmfilt",
+        prog="linfitfilt",
         description="Fits and removes the effect of voxel specific and/or global regressors.",
         allow_abbrev=False,
     )
@@ -75,7 +102,67 @@ def _get_parser():
     return parser
 
 
-def glmfilt(inputfile, numskip, outputroot, evfilename, datamaskname, saveall=True):
+def linfitfilt(
+    inputfile: Any,
+    numskip: Any,
+    outputroot: Any,
+    evfilename: Any,
+    datamaskname: Any,
+    saveall: bool = True,
+) -> None:
+    """
+    Perform linear regression fitting on 4D NIfTI data using specified regressors.
+
+    This function fits a linear model to each voxel's time series using the provided
+    regressors and saves the resulting fit coefficients, R-squared values, and filtered
+    data. It supports both NIfTI and text-based regressor files, as well as FSL par files
+    for global regressors.
+
+    Parameters
+    ----------
+    inputfile : str or pathlib.Path
+        Path to the input 4D NIfTI file containing the time series data.
+    numskip : int
+        Number of initial time points to skip when fitting the model.
+    outputroot : str
+        Root name for output NIfTI files (e.g., '_mean', '_fit0', '_R2', etc.).
+    evfilename : list of str or pathlib.Path
+        List of paths to files containing regressor time series. Can be NIfTI files,
+        text files, or FSL par files.
+    datamaskname : str or pathlib.Path, optional
+        Path to a NIfTI file defining the mask for data analysis. If None, a full mask
+        is assumed.
+    saveall : bool, optional
+        If True, save all intermediate and final output files. Default is True.
+
+    Returns
+    -------
+    None
+        This function does not return a value but saves multiple NIfTI files to disk.
+
+    Notes
+    -----
+    - The function performs ordinary least squares (OLS) regression for each voxel.
+    - The regressors are applied to the data after skipping the first `numskip` time points.
+    - Output files include:
+        - `<outputroot>_mean.nii.gz`: Mean of the data.
+        - `<outputroot>_fit{j}.nii.gz`: Fitted coefficients for regressor j.
+        - `<outputroot>_R2.nii.gz`: R-squared values for the model.
+        - `<outputroot>_totaltoremove.nii.gz`: Regressor contributions to be removed.
+        - `<outputroot>_trimmed.nii.gz`: Trimmed input data.
+        - `<outputroot>_filtered.nii.gz`: Final filtered data.
+
+    Examples
+    --------
+    >>> linfitfilt(
+    ...     inputfile='data.nii.gz',
+    ...     numskip=5,
+    ...     outputroot='output',
+    ...     evfilename=['regressor1.txt', 'regressor2.nii.gz'],
+    ...     datamaskname='mask.nii.gz',
+    ...     saveall=True
+    ... )
+    """
     # initialize some variables
     evdata = []
     evisnifti = []
@@ -104,7 +191,7 @@ def glmfilt(inputfile, numskip, outputroot, evfilename, datamaskname, saveall=Tr
             sys.exit()
         print("done reading in mask array")
     else:
-        datamask_data = nim_data[:, :, :, 0] * 0.0 + 1.0
+        datamask_data = np.ones_like(nim_data[:, :, :, 0])
 
     numregressors = 0
     for i in range(0, len(evfilename)):
@@ -167,7 +254,7 @@ def glmfilt(inputfile, numskip, outputroot, evfilename, datamaskname, saveall=Tr
     print("will perform GLM with ", numregressors, " regressors")
     meandata = np.zeros((xsize, ysize, numslices), dtype="float")
     fitdata = np.zeros((xsize, ysize, numslices, numregressors), dtype="float")
-    Rdata = np.zeros((xsize, ysize, numslices), dtype="float")
+    R2data = np.zeros((xsize, ysize, numslices), dtype="float")
     trimmeddata = 1.0 * nim_data[:, :, :, numskip:]
 
     for z in range(0, numslices):
@@ -182,15 +269,15 @@ def glmfilt(inputfile, numskip, outputroot, evfilename, datamaskname, saveall=Tr
                         else:
                             regressorvec.append(evdata[j])
                     if np.max(trimmeddata[x, y, z, :]) - np.min(trimmeddata[x, y, z, :]) > 0.0:
-                        thefit, R = tide_fit.mlregress(regressorvec, trimmeddata[x, y, z, :])
+                        thefit, R2 = tide_fit.mlregress(regressorvec, trimmeddata[x, y, z, :])
                         meandata[x, y, z] = thefit[0, 0]
-                        Rdata[x, y, z] = R
+                        R2data[x, y, z] = R2
                         for j in range(0, numregressors):
                             fitdata[x, y, z, j] = thefit[0, j + 1]
                             # datatoremove[x, y, z, :, j] = thefit[0, j + 1] * regressorvec[j]
                     else:
                         meandata[x, y, z] = 0.0
-                        Rdata[x, y, z] = 0.0
+                        R2data[x, y, z] = 0.0
                         for j in range(0, numregressors):
                             fitdata[x, y, z, j] = 0.0
                             # datatoremove[x, y, z, :, j] = 0.0 * regressorvec[j]
@@ -205,8 +292,8 @@ def glmfilt(inputfile, numskip, outputroot, evfilename, datamaskname, saveall=Tr
         tide_io.savetonifti(meandata, theheader, outputroot + "_mean")
         for j in range(0, numregressors):
             tide_io.savetonifti(fitdata[:, :, :, j], theheader, outputroot + "_fit" + str(j))
-    tide_io.savetonifti(Rdata, theheader, outputroot + "_R")
-    Rdata = None
+    tide_io.savetonifti(R2data, theheader, outputroot + "_R2")
+    R2data = None
 
     print()
     print("Now constructing the array of data to remove")
@@ -237,14 +324,41 @@ def glmfilt(inputfile, numskip, outputroot, evfilename, datamaskname, saveall=Tr
     tide_io.savetonifti(filtereddata, theheader, outputroot + "_filtered")
 
 
-def main():
+def main() -> None:
+    """
+    Main function to execute the linear fit and filter pipeline.
+
+    This function parses command line arguments and executes the linear fit and
+    filter process on the input data file. It handles argument parsing exceptions
+    and provides help output when needed.
+
+    Parameters
+    ----------
+    None
+
+    Returns
+    -------
+    None
+        This function does not return any value.
+
+    Notes
+    -----
+    The function relies on `_get_parser()` to create and return an argument parser
+    with the necessary command line options. The parsed arguments are then passed
+    to the `linfitfilt` function for processing.
+
+    Examples
+    --------
+    >>> main()
+    # Executes the linear fit and filter pipeline with arguments from command line
+    """
     try:
         args = vars(_get_parser().parse_args())
     except SystemExit:
         _get_parser().print_help()
         raise
 
-    glmfilt(
+    linfitfilt(
         args["inputfile"],
         args["numskip"],
         args["outputroot"],