rapidtide 3.0.11__py3-none-any.whl → 3.1.1__py3-none-any.whl

rapidtide/workflows/atlasaverage.py

@@ -18,8 +18,10 @@
 #
 import argparse
 import sys
+from typing import Any
 
 import numpy as np
+from numpy.typing import NDArray
 from statsmodels.robust import mad
 
 import rapidtide.io as tide_io
@@ -28,43 +30,35 @@ import rapidtide.stats as tide_stats
 import rapidtide.workflows.parser_funcs as pf
 
 
-def summarizevoxels(thevoxels, method="mean"):
-    theshape = thevoxels.shape
-    if len(theshape) > 1:
-        numtimepoints = theshape[1]
-    else:
-        numtimepoints = 1
+def _get_parser() -> Any:
+    """
+    Construct and return an argument parser for the atlasaverage command-line tool.
 
-    if method == "CoV":
-        if numtimepoints > 1:
-            regionsummary = 100.0 * np.nan_to_num(
-                np.std(thevoxels, axis=0) / np.mean(thevoxels, axis=0)
-            )
-        else:
-            regionsummary = 100.0 * np.nan_to_num(np.std(thevoxels) / np.mean(thevoxels))
-    else:
-        if method == "mean":
-            themethod = np.mean
-        elif method == "sum":
-            themethod = np.sum
-        elif method == "median":
-            themethod = np.median
-        elif method == "std":
-            themethod = np.std
-        elif method == "MAD":
-            themethod = mad
-        else:
-            print(f"illegal summary method {method} in summarizevoxels")
-            sys.exit()
+    This function builds an `argparse.ArgumentParser` object configured with all
+    required and optional arguments needed to run the `atlasaverage` utility. It
+    handles input validation for file paths and defines various options for
+    normalizing, summarizing, and filtering data within atlas regions.
 
-        if numtimepoints > 1:
-            regionsummary = np.nan_to_num(themethod(thevoxels, axis=0))
-        else:
-            regionsummary = np.nan_to_num(themethod(thevoxels))
-    return regionsummary
+    Returns
+    -------
+    argparse.ArgumentParser
+        Configured argument parser object for the atlasaverage tool.
 
+    Notes
+    -----
+    The parser is set up with:
+    - Two required positional arguments: `datafile` and `templatefile`.
+    - One required positional argument: `outputroot`.
+    - Several optional arguments controlling normalization, summarization,
+      masking, and output formatting.
 
-def _get_parser():
+    Examples
+    --------
+    >>> parser = _get_parser()
+    >>> args = parser.parse_args(['data.nii', 'atlas.nii', 'output'])
+    >>> print(args.datafile)
+    'data.nii'
+    """
     # get the command line parameters
     parser = argparse.ArgumentParser(
         prog="atlasaverage",
@@ -203,7 +197,160 @@ def _get_parser():
     return parser
 
 
-def atlasaverage(args):
+def summarizevoxels(thevoxels: NDArray, method: str = "mean") -> float:
+    """
+    Summarize voxel data using specified statistical method.
+
+    Parameters
+    ----------
+    thevoxels : ndarray
+        Input voxel data array. Can be 1D or 2D, where 2D arrays are interpreted
+        as time series with shape (voxels, timepoints).
+    method : str, default="mean"
+        Summary method to apply. Options are:
+        - "mean": Compute mean along axis 0
+        - "sum": Compute sum along axis 0
+        - "median": Compute median along axis 0
+        - "std": Compute standard deviation along axis 0
+        - "MAD": Compute median absolute deviation along axis 0
+        - "CoV": Compute coefficient of variation (std/mean) along axis 0
+
+    Returns
+    -------
+    float or ndarray
+        Summary statistic(s) of the voxel data. Returns a scalar for 1D input
+        or array of statistics for 2D input along axis 0.
+
+    Notes
+    -----
+    - NaN values are converted to zero using `np.nan_to_num` before computation
+    - For coefficient of variation ("CoV"), the result is multiplied by 100 to
+      express as percentage
+    - When input is 1D, time dimension is treated as single timepoint
+    - The function handles both 1D and 2D input arrays appropriately
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> voxels = np.array([[1, 2, 3], [4, 5, 6]])
+    >>> summarizevoxels(voxels, method="mean")
+    array([2.5, 3.5, 4.5])
+
+    >>> summarizevoxels(voxels, method="CoV")
+    array([40.82482905, 33.33333333, 25.        ])
+    """
+    theshape = thevoxels.shape
+    if len(theshape) > 1:
+        numtimepoints = theshape[1]
+    else:
+        numtimepoints = 1
+
+    if method == "CoV":
+        if numtimepoints > 1:
+            regionsummary = 100.0 * np.nan_to_num(
+                np.std(thevoxels, axis=0) / np.mean(thevoxels, axis=0)
+            )
+        else:
+            regionsummary = 100.0 * np.nan_to_num(np.std(thevoxels) / np.mean(thevoxels))
+    else:
+        if method == "mean":
+            themethod = np.mean
+        elif method == "sum":
+            themethod = np.sum
+        elif method == "median":
+            themethod = np.median
+        elif method == "std":
+            themethod = np.std
+        elif method == "MAD":
+            themethod = mad
+        else:
+            print(f"illegal summary method {method} in summarizevoxels")
+            sys.exit()
+
+        if numtimepoints > 1:
+            regionsummary = np.nan_to_num(themethod(thevoxels, axis=0))
+        else:
+            regionsummary = np.nan_to_num(themethod(thevoxels))
+    return regionsummary
+
+
+def atlasaverage(args: Any) -> None:
+    """
+    Compute average timecourses or summary statistics for regions defined by an atlas.
+
+    This function reads fMRI data and a template (atlas) file, extracts timecourses
+    or summary statistics for each region in the atlas, and saves the results to
+    output files. It supports multiple normalization methods and can process both
+    3D and 4D input data.
+
+    Parameters
+    ----------
+    args : argparse.Namespace
+        Arguments parsed from command line. Expected attributes include:
+        - datafile : str
+            Path to the input fMRI NIfTI file.
+        - templatefile : str
+            Path to the template NIfTI file defining regions.
+        - normmethod : str
+            Normalization method for timecourses: 'none', 'pct', 'std', 'var', 'p2p'.
+        - outputroot : str
+            Root name for output files.
+        - debug : bool
+            If True, enable debug printing and save intermediate masks.
+        - includespec : str or None
+            Specification for including voxels in analysis.
+        - excludespec : str or None
+            Specification for excluding voxels from analysis.
+        - extramaskname : str or None
+            Path to an additional mask file.
+        - regionlabelfile : str or None
+            Path to a file containing region labels.
+        - regionlistfile : str or None
+            Path to a file listing regions to include.
+        - summarymethod : str
+            Method for summarizing voxel values (e.g., 'mean', 'median').
+        - datalabel : str or None
+            Label to prepend to output summary.
+        - ignorezeros : bool
+            If True, exclude zero voxels when computing summaries.
+        - numpercentiles : int
+            Number of percentiles to compute for each region.
+        - headerline : bool
+            If True, include a header line in the summary CSV.
+
+    Returns
+    -------
+    None
+        This function does not return a value but writes output files to disk.
+
+    Notes
+    -----
+    For 4D data, the function computes timecourses for each region and saves them
+    as a TSV file. For 3D data, it computes summary statistics and saves both
+    a labeled NIfTI file and a CSV/TSV summary.
+
+    Examples
+    --------
+    >>> import argparse
+    >>> args = argparse.Namespace(
+    ...     datafile='fmri.nii.gz',
+    ...     templatefile='atlas.nii.gz',
+    ...     normmethod='std',
+    ...     outputroot='output',
+    ...     debug=False,
+    ...     includespec=None,
+    ...     excludespec=None,
+    ...     extramaskname=None,
+    ...     regionlabelfile=None,
+    ...     regionlistfile=None,
+    ...     summarymethod='mean',
+    ...     datalabel=None,
+    ...     ignorezeros=False,
+    ...     numpercentiles=5,
+    ...     headerline=True
+    ... )
+    >>> atlasaverage(args)
+    """
     if args.normmethod == "none":
         print("will not normalize timecourses")
     elif args.normmethod == "pct":
@@ -302,14 +449,21 @@ def atlasaverage(args):
             )
 
     # get the region names
+    numregions = np.max(templatevoxels)
     if args.regionlabelfile is None:
         regionlabels = []
-        numregions = np.max(templatevoxels)
         numdigits = int(np.log10(numregions)) + 1
         for regnum in range(1, numregions + 1):
             regionlabels.append(f"region_{str(regnum).zfill(numdigits)}")
     else:
         regionlabels = tide_io.readlabels(args.regionlabelfile)
+        if len(regionlabels) != numregions:
+            print(
+                "Error: number of labels in label file does not match the number of regions in the template."
+            )
+            sys.exit()
+    if args.debug:
+        print(f"Region labels: {regionlabels}")
 
     # decide what regions we will summarize
     if args.regionlistfile is None:
@@ -322,6 +476,8 @@ def atlasaverage(args):
         for theregion in range(numregions):
             newlabels.append(regionlabels[theregion])
         regionlabels = newlabels
+    if args.debug:
+        print(f"Region labels to use: {regionlabels}")
 
     timecourses = np.zeros((numregions, numtimepoints), dtype="float")
     print(f"{numregions=}, {regionlist=}")
@@ -380,18 +536,21 @@ def atlasaverage(args):
     else:
         print("processing 3D input file")
         outputvoxels = inputvoxels * 0.0
-        theregnums = []
+        thereglabels = []
         thevals = []
         thepercentiles = []
-        thesizes = []
+        theregsizes = []
         thefracs = np.linspace(0.0, 1.0, args.numpercentiles + 2, endpoint=True).tolist()
         numsubregions = len(thefracs) - 1
         segmentedatlasvoxels = inputvoxels * 0.0
+        if args.debug:
+            print(f"{len(regionlist)=}, {regionlist=}")
+            print(f"{len(regionlabels)=}, {regionlabels=}")
         if args.datalabel is not None:
-            theregnums.append("Region")
+            thereglabels.append("Region")
             thevals.append(args.datalabel)
         for theregion in regionlist:
-            theregnums.append(str(theregion))
+            thereglabels.append(regionlabels[theregion - 1])
             theregionvoxels = inputvoxels[np.where(templatevoxels * themask == theregion)]
             initnum = theregionvoxels.shape[0]
             if args.ignorezeros:
@@ -404,13 +563,15 @@ def atlasaverage(args):
                 if args.debug:
                     print(
                         f"extracting {theregionvoxels.shape[0]} "
-                        f"non-zero voxels from region {theregion} of {numregions}{extrabit}"
+                        f"non-zero voxels from region {theregion} of {numregions}{extrabit} "
+                        f"({thereglabels[-1]})"
                     )
             else:
                 if args.debug:
                     print(
                         f"extracting {theregionvoxels.shape[0]} "
-                        f"voxels from region {theregion} of {numregions}"
+                        f"voxels from region {theregion} of {numregions} "
+                        f"({thereglabels[-1]})"
                     )
             if theregionvoxels.shape[0] > 0:
                 regionval = summarizevoxels(theregionvoxels, method=args.summarymethod)
@@ -426,7 +587,7 @@ def atlasaverage(args):
                 ]
                 outputvoxels[np.where(templatevoxels == theregion)] = regionval
                 thevals.append(str(regionval))
-                thesizes.append(str(regionsizes))
+                theregsizes.append(str(regionsizes))
                 thepercentiles.append(regionpercentiles)
             else:
                 if args.debug:
@@ -462,21 +623,23 @@ def atlasaverage(args):
             )
         if args.headerline:
             tide_io.writevec(
-                [",".join(theregnums), ",".join(thevals)],
+                np.array([",".join(thereglabels), ",".join(thevals)]),
                 f"{args.outputroot}_regionsummaries.csv",
             )
         else:
             tide_io.writevec(
-                [",".join(thevals)],
+                np.array([",".join(thevals)]),
                 f"{args.outputroot}_regionsummaries.csv",
             )
 
         outlines = []
         pctstrings = [f"{num:.0f}" for num in (np.array(thefracs) * 100.0).tolist()]
         outlines.append("Region\tVoxels\t" + "pct-" + "\tpct-".join(pctstrings))
-        for idx, region in enumerate(theregnums):
-            outlines.append(region + "\t" + thesizes[idx] + "\t" + "\t".join(thepercentiles[idx]))
+        for idx, region in enumerate(thereglabels):
+            outlines.append(
+                region + "\t" + theregsizes[idx] + "\t" + "\t".join(thepercentiles[idx])
+            )
             tide_io.writevec(
-                outlines,
+                np.array(outlines),
                 f"{args.outputroot}_regionpercentiles.tsv",
             )

rapidtide/workflows/atlastool.py

@@ -20,18 +20,42 @@ import argparse
 import os
 import subprocess
 import sys
+from argparse import Namespace
 from glob import glob
+from typing import Any, Callable, Dict, List, Optional, Tuple, Union
 
 import numpy as np
+from numpy.typing import NDArray
 
 import rapidtide.externaltools as tide_exttools
 import rapidtide.io as tide_io
 import rapidtide.workflows.parser_funcs as pf
 
 
-def _get_parser():
+def _get_parser() -> Any:
     """
-    Argument parser for atlastool
+    Argument parser for atlastool.
+
+    This function constructs and returns an `argparse.ArgumentParser` object configured
+    with all the necessary arguments for the `atlastool` utility. It supports parsing
+    of NIfTI atlas files, with options for transforming, splitting, masking, and
+    reformatting atlas data.
+
+    Returns
+    -------
+    argparse.ArgumentParser
+        Configured argument parser for atlastool.
+
+    Notes
+    -----
+    The parser includes both required and optional arguments for handling NIfTI files,
+    including support for 3D and 4D output formats, splitting regions along the midline,
+    applying masks, and debugging options.
+
+    Examples
+    --------
+    >>> parser = _get_parser()
+    >>> args = parser.parse_args()
     """
     parser = argparse.ArgumentParser(
         prog="atlastool",
@@ -156,7 +180,80 @@ def _get_parser():
     return parser
 
 
-def atlastool(args):
+def atlastool(args: Any) -> None:
+    """
+    Process and convert atlas templates for neuroimaging analysis.
+
+    This function reads a template NIfTI file, reshapes it into a 4D array, and optionally
+    splits left-right regions, resamples to a target resolution, applies a mask, and saves
+    the processed data as a new NIfTI file. It supports both 3D and 4D input templates,
+    and can handle label files for region mapping.
+
+    Parameters
+    ----------
+    args : Any
+        An object containing command-line arguments. Expected attributes include:
+        - inputtemplatename : str
+            Path to the input NIfTI template file.
+        - debug : bool
+            If True, print debug information.
+        - maxval : float, optional
+            Maximum value to truncate template data.
+        - labelfile : str, optional
+            Path to a text file containing region labels.
+        - dosplit : bool
+            If True, split regions into left and right hemispheres.
+        - LtoR : bool
+            If True, assign left hemisphere labels first.
+        - targetfile : str, optional
+            Path to a target NIfTI file for resampling.
+        - xfm : str, optional
+            Path to transformation file for resampling.
+        - maskfile : str, optional
+            Path to a mask NIfTI file.
+        - maskthresh : float
+            Threshold for generating mask from template if no maskfile is provided.
+        - removeemptyregions : bool
+            If True, remove regions with no voxels.
+        - volumeperregion : bool
+            If True, save each region as a separate volume; otherwise, save as a
+            single label map.
+        - outputtemplatename : str
+            Path for the output NIfTI file.
+
+    Returns
+    -------
+    None
+        This function does not return a value but saves processed data to disk.
+
+    Notes
+    -----
+    - The function supports both 3D and 4D input templates.
+    - If `targetfile` is provided, the template is resampled using FSL or ANTs.
+    - If `maskfile` is not provided, a mask is generated from the template using
+      `maskthresh`.
+    - Labels from `labelfile` are used in the output if provided.
+
+    Examples
+    --------
+    >>> import argparse
+    >>> args = argparse.Namespace(
+    ...     inputtemplatename='template.nii.gz',
+    ...     debug=False,
+    ...     maxval=None,
+    ...     labelfile='labels.txt',
+    ...     dosplit=True,
+    ...     LtoR=True,
+    ...     targetfile='target.nii.gz',
+    ...     xfm='transform.mat',
+    ...     maskfile=None,
+    ...     maskthresh=0.5,
+    ...     removeemptyregions=True,
+    ...     volumeperregion=False,
+    ...     outputtemplatename='output.nii.gz'
+    ... )
+    >>> atlastool(args)
+    """
     if args.debug:
         print(args)