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

rapidtide/workflows/polyfitim.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,17 +18,49 @@
 #
 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 polyfitim
+    Argument parser for polyfitim.
+
+    This function constructs and returns an `argparse.ArgumentParser` object configured
+    to parse command-line arguments for the `polyfitim` tool. It is designed to handle
+    the fitting of a spatial template to 3D or 4D NIFTI files, with optional region-specific
+    fitting using an atlas file.
+
+    Returns
+    -------
+    argparse.ArgumentParser
+        Configured argument parser for `polyfitim` command-line interface.
+
+    Notes
+    -----
+    The parser expects several required NIFTI files:
+    - Data file (`datafile`)
+    - Data mask file (`datamask`)
+    - Template file (`templatefile`)
+    - Template mask file (`templatemask`)
+
+    Optional arguments include:
+    - `--regionatlas`: File containing a 3D NIFTI atlas for region-specific fitting.
+    - `--order`: Polynomial order for the fit (default is 1).
+
+    Examples
+    --------
+    >>> parser = _get_parser()
+    >>> args = parser.parse_args(['data.nii', 'mask.nii', 'template.nii', 'template_mask.nii', 'output'])
+    >>> print(args.datafile)
+    'data.nii'
     """
     parser = argparse.ArgumentParser(
         prog="polyfitim",
@@ -78,14 +110,69 @@ def _get_parser():
 
 
 def polyfitim(
-    datafile,
-    datamask,
-    templatefile,
-    templatemask,
-    outputroot,
-    regionatlas=None,
-    order=1,
-):
+    datafile: Any,
+    datamask: Any,
+    templatefile: Any,
+    templatemask: Any,
+    outputroot: Any,
+    regionatlas: Optional[Any] = None,
+    order: int = 1,
+) -> None:
+    """
+    Fit polynomial models to time series data within regions defined by masks.
+
+    This function performs polynomial fitting of specified order to time series data
+    within spatial regions defined by a template mask. It supports both global and
+    region-specific fitting, and outputs fitted time series, polynomial coefficients,
+    and R² values.
+
+    Parameters
+    ----------
+    datafile : Any
+        Path to the input NIfTI file containing the time series data.
+    datamask : Any
+        Path to the NIfTI file containing the data mask. Can be 3D or 4D.
+    templatefile : Any
+        Path to the NIfTI file containing the template (e.g., a regressor) for fitting.
+    templatemask : Any
+        Path to the NIfTI file containing the mask for the template.
+    outputroot : Any
+        Root name for output files (e.g., 'output' will produce 'output_fit.nii.gz').
+    regionatlas : Any, optional
+        Path to the NIfTI file containing region labels. If provided, fitting is
+        performed separately for each region. Default is None.
+    order : int, optional
+        Order of the polynomial to fit. Must be >= 1. Default is 1 (linear fit).
+
+    Returns
+    -------
+    None
+        Function writes multiple output files:
+        - Fitted time series (NIfTI format)
+        - Residuals (NIfTI format)
+        - R² values (text file)
+        - Polynomial coefficients (text files)
+
+    Notes
+    -----
+    - The function assumes that all input files are in NIfTI format.
+    - If `datamask` is 4D, it is treated as a time-varying mask.
+    - If `regionatlas` is provided, fitting is performed separately for each region.
+    - The function uses `tide_io` for reading/writing NIfTI files and `tide_fit.mlregress`
+      for polynomial regression.
+
+    Examples
+    --------
+    >>> polyfitim(
+    ...     datafile='data.nii.gz',
+    ...     datamask='mask.nii.gz',
+    ...     templatefile='template.nii.gz',
+    ...     templatemask='template_mask.nii.gz',
+    ...     outputroot='output',
+    ...     regionatlas='atlas.nii.gz',
+    ...     order=2
+    ... )
+    """
     # check the order
     if order < 1:
         print("order must be >= 1")
@@ -189,10 +276,10 @@ def polyfitim(
     fitdata = np.zeros((numspatiallocs, timepoints), dtype="float")
     if regionatlas is not None:
         polycoffs = np.zeros((numregions, order + 1, timepoints), dtype="float")
-        rvals = np.zeros((numregions, timepoints), dtype="float")
+        r2vals = np.zeros((numregions, timepoints), dtype="float")
     else:
         polycoffs = np.zeros((order + 1, timepoints), dtype="float")
-        rvals = np.zeros(timepoints, dtype="float")
+        r2vals = np.zeros(timepoints, dtype="float")
 
     if regionatlas is not None:
         print("making region masks")
@@ -219,7 +306,7 @@ def polyfitim(
                 evlist = []
                 for i in range(1, order + 1):
                     evlist.append((rs_templatefile[voxelstofit]) ** i)
-                thefit, R = tide_fit.mlregress(
+                thefit, R2 = tide_fit.mlregress(
                     evlist,
                     rs_datafile[voxelstofit, thetime][0],
                 )
@@ -230,14 +317,14 @@ def polyfitim(
                     fitdata[voxelstoreconstruct, thetime] += polycoffs[region, i, thetime] * (
                         rs_templatefile[voxelstoreconstruct] ** i
                     )
-                rvals[region, thetime] = R
+                r2vals[region, thetime] = R2
         else:
             voxelstofit = np.where(thisdatamask > 0.5)
             voxelstoreconstruct = np.where(rs_templatemask > 0.5)
             evlist = []
             for i in range(1, order + 1):
                 evlist.append((rs_templatefile[voxelstofit]) ** i)
-            thefit, R = tide_fit.mlregress(evlist, rs_datafile[voxelstofit, thetime][0])
+            thefit, R2 = tide_fit.mlregress(evlist, rs_datafile[voxelstofit, thetime][0])
             for i in range(order + 1):
                 polycoffs[i, thetime] = thefit[0, i]
             fitdata[voxelstoreconstruct, thetime] = polycoffs[0, thetime]
@@ -245,13 +332,13 @@ def polyfitim(
                 fitdata[voxelstoreconstruct, thetime] += polycoffs[i, thetime] * (
                     rs_templatefile[voxelstoreconstruct] ** i
                 )
-            rvals[thetime] = R
+            r2vals[thetime] = R2
     residuals = rs_datafile - fitdata
 
     # write out the data files
     print("writing time series")
 
-    tide_io.writenpvecs(rvals, outputroot + "_rvals.txt")
+    tide_io.writenpvecs(r2vals, outputroot + "_r2vals.txt")
     if regionatlas is not None:
         for region in range(0, numregions):
             outstring = f"region {region + 1}:"
@@ -279,7 +366,60 @@ def polyfitim(
     )
 
 
-def main(args):
+def main(args: Any) -> None:
+    """
+    Main function to perform polynomial fitting on imaging data.
+
+    This function serves as the entry point for polynomial fitting operations
+    on medical imaging data using template-based registration and fitting.
+
+    Parameters
+    ----------
+    args : Any
+        Namespace object containing all required arguments for the polynomial fitting
+        operation. Expected attributes include:
+
+        - datafile : str
+            Path to the input data file to be fitted
+        - datamask : str
+            Path to the data mask file for region of interest specification
+        - templatefile : str
+            Path to the template file for reference
+        - templatemask : str
+            Path to the template mask file for reference region specification
+        - outputroot : str
+            Root path for output files
+        - regionatlas : str, optional
+            Path to region atlas file for anatomical labeling
+        - order : int, optional
+            Order of the polynomial to fit (default is typically 1)
+
+    Returns
+    -------
+    None
+        This function does not return any value. It performs the polynomial fitting
+        operation and saves results to the specified output directory.
+
+    Notes
+    -----
+    The function internally calls `polyfitim` with the provided arguments to
+    perform the actual polynomial fitting computation. All input files must be
+    properly formatted and accessible.
+
+    Examples
+    --------
+    >>> import argparse
+    >>> args = argparse.Namespace(
+    ...     datafile='data.nii.gz',
+    ...     datamask='data_mask.nii.gz',
+    ...     templatefile='template.nii.gz',
+    ...     templatemask='template_mask.nii.gz',
+    ...     outputroot='output',
+    ...     regionatlas='atlas.nii.gz',
+    ...     order=2
+    ... )
+    >>> main(args)
+    """
     polyfitim(
         args.datafile,
         args.datamask,

rapidtide/workflows/proj2flow.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,14 +18,44 @@
 #
 import argparse
 import copy
+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:
+    """
+    Create and configure argument parser for phase projection to velocity map conversion.
+
+    This function sets up the command line argument parser for the proj2flow tool,
+    which converts phase projection movies to velocity maps. It defines required
+    positional arguments for input and output files, as well as optional debugging
+    flag.
+
+    Returns
+    -------
+    argparse.ArgumentParser
+        Configured argument parser object with defined command line arguments
+
+    Notes
+    -----
+    The function currently has commented-out frequency filter arguments (lowestfreq
+    and highestfreq) that can be enabled if needed for specific use cases.
+
+    Examples
+    --------
+    >>> parser = _get_parser()
+    >>> args = parser.parse_args(['input.nii', 'output_root'])
+    >>> print(args.inputfilename)
+    'input.nii'
+    >>> print(args.outputroot)
+    'output_root'
+    """
     # get the command line parameters
     parser = argparse.ArgumentParser(
         prog="proj2flow",
@@ -57,7 +87,50 @@ def _get_parser():
     return parser
 
 
-def proj2flow(args):
+def proj2flow(args: Any) -> None:
+    """
+    Compute 3D velocity fields from projected 4D fMRI data using forward and backward differences.
+
+    This function reads 4D NIfTI fMRI data, computes velocity fields at each timepoint by
+    calculating forward and backward differences in spatial and temporal dimensions, and
+    saves the resulting velocity fields as 3D NIfTI files. It also saves an average velocity
+    field across all timepoints.
+
+    Parameters
+    ----------
+    args : argparse.Namespace
+        Command-line arguments parsed by `_get_parser()`. Expected attributes include:
+        - `inputfilename` : str
+            Path to the input NIfTI file containing 4D fMRI data.
+        - `outputroot` : str
+            Root name for output NIfTI files.
+        - `debug` : bool, optional
+            If True, enables debug printing and additional checks.
+
+    Returns
+    -------
+    None
+        This function does not return a value. It writes NIfTI files to disk.
+
+    Notes
+    -----
+    - The function assumes the input data is in the same spatial and temporal dimensions
+      as specified by the NIfTI header.
+    - Forward and backward differences are computed using a 3x3x3 neighborhood in space
+      and a single timepoint difference.
+    - Velocity fields are saved with intent code 2003 (indicating a vector field).
+    - The output files are named using the format:
+        - `{outputroot}_{timepoint:02d}.nii.gz` for each timepoint
+        - `{outputroot}_average.nii.gz` for the average velocity field
+
+    Examples
+    --------
+    >>> import argparse
+    >>> args = argparse.Namespace(inputfilename='fmri_data.nii.gz',
+    ...                           outputroot='velocity',
+    ...                           debug=False)
+    >>> proj2flow(args)
+    """
     # set default variable values
     displayplots = False
 

rapidtide/workflows/rankimage.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,16 +17,41 @@
 #
 #
 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
 from scipy.stats import rankdata
 
 import rapidtide.io as tide_io
 
 
-def _get_parser():
+def _get_parser() -> Any:
     """
-    Argument parser for pixelcomp
+    Argument parser for rankimage.
+
+    Creates and configures an argument parser for the rankimage tool that converts
+    3D or 4D nifti images into percentile maps.
+
+    Returns
+    -------
+    argparse.ArgumentParser
+        Configured argument parser object with all required and optional arguments
+        for the rankimage tool.
+
+    Notes
+    -----
+    The parser is configured with:
+    - Required arguments: inputfilename, maskfilename, outputroot
+    - Optional argument: --debug flag for additional debugging information
+
+    Examples
+    --------
+    >>> parser = _get_parser()
+    >>> args = parser.parse_args(['input.nii', 'mask.nii', 'output_root'])
+    >>> print(args.inputfilename)
+    'input.nii'
     """
     parser = argparse.ArgumentParser(
         prog="rankimage",
@@ -50,12 +75,49 @@ def _get_parser():
     return parser
 
 
-def imtopercentile(image, mask, debug=False):
-    outmaparray = image * 0.0
+def imtopercentile(image: Any, mask: Any, debug: bool = False) -> NDArray:
+    """
+    Convert image values to percentile scores within masked region.
+
+    This function computes percentile rankings for all voxels within a specified
+    mask region of a 3D image. The percentile scores are calculated using the
+    'dense' ranking method, where tied values receive the same rank.
+
+    Parameters
+    ----------
+    image : array-like
+        Input 3D image data array
+    mask : array-like
+        Binary mask defining the region of interest (values > 0 are considered valid)
+    debug : bool, optional
+        If True, print debugging information about processing (default is False)
+
+    Returns
+    -------
+    NDArray
+        Array of same shape as input image containing percentile scores for
+        valid voxels, with zeros for masked-out voxels
+
+    Notes
+    -----
+    - Only voxels where mask > 0 are processed
+    - Percentile calculation uses 'dense' ranking method
+    - The percentile score ranges from 0 to 100
+    - Invalid voxels (where mask <= 0) are set to 0 in output
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> image = np.random.rand(10, 10, 10)
+    >>> mask = np.ones((10, 10, 10))
+    >>> mask[0:5, :, :] = 0  # Mask out first 5 slices
+    >>> result = imtopercentile(image, mask)
+    """
+    outmaparray = np.zeros_like(image)
     nativespaceshape = image.shape
     validvoxels = np.where(mask > 0)
     numvalidspatiallocs = np.shape(validvoxels[0])[0]
-    input_data_valid = image[validvoxels] + 0.0
+    input_data_valid = image[validvoxels].copy()
 
     if debug:
         print(
@@ -69,7 +131,52 @@ def imtopercentile(image, mask, debug=False):
     return outmaparray.reshape(nativespaceshape)
 
 
-def rankimage(args):
+def rankimage(args: Any) -> None:
+    """
+    Convert input NIfTI image data to percentile-ranked values using a mask.
+
+    This function reads an input NIfTI image and a corresponding mask, checks
+    that their spatial dimensions match, and computes percentile-ranked values
+    for each voxel within the mask. The result is saved as a new NIfTI file with
+    associated BIDS metadata.
+
+    Parameters
+    ----------
+    args : Any
+        An object containing the following attributes:
+        - inputfilename : str
+            Path to the input NIfTI image file.
+        - maskfilename : str
+            Path to the mask NIfTI file.
+        - outputroot : str
+            Root name for the output NIfTI file (without extension).
+        - debug : bool, optional
+            If True, enables debug output. Default is False.
+
+    Returns
+    -------
+    None
+        The function writes the percentile-ranked image to a NIfTI file and
+        a JSON metadata file, but does not return any value.
+
+    Notes
+    -----
+    - The function supports both 3D and 4D NIfTI files.
+    - For 4D files, the percentile ranking is computed separately for each
+      timepoint.
+    - The output file is saved with the extension `.nii.gz`.
+    - BIDS metadata is saved in a `.json` file with the same root name.
+
+    Examples
+    --------
+    >>> class Args:
+    ...     inputfilename = "input.nii.gz"
+    ...     maskfilename = "mask.nii.gz"
+    ...     outputroot = "output"
+    ...     debug = False
+    >>> args = Args()
+    >>> rankimage(args)
+    """
     input_img, input_data, input_hdr, thedims, thesizes = tide_io.readfromnifti(args.inputfilename)
     (
         mask_img,
@@ -92,7 +199,7 @@ def rankimage(args):
 
     if is4d:
         print("processing 4D nifti file")
-        percentiles = input_data * 0.0
+        percentiles = np.zeros_like(input_data)
         for i in range(timepoints):
             percentiles[:, :, :, i] = imtopercentile(
                 input_data[:, :, :, i], mask_data[:, :, :, i], debug=args.debug