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

rapidtide/workflows/happy2std.py

@@ -21,11 +21,39 @@ import glob
 import os
 import subprocess
 import sys
+from argparse import Namespace
+from typing import Any, Callable, Dict, List, Optional, Tuple, Union
 
 import rapidtide.externaltools as tide_extern
 
 
-def _get_parser():
+def _get_parser() -> Any:
+    """
+    Create and configure an argument parser for the rapidtide2std command-line tool.
+
+    This function sets up an `argparse.ArgumentParser` with specific arguments
+    required for registering happy output maps to standard space. It defines
+    positional and optional arguments for input file roots, output directories,
+    and various transformation options.
+
+    Returns
+    -------
+    argparse.ArgumentParser
+        Configured argument parser object with defined arguments for
+        the rapidtide2std tool.
+
+    Notes
+    -----
+    The parser is configured with a program name, description, and usage string
+    specific to the rapidtide2std tool. It expects three positional arguments:
+    inputfileroot, outputdir, and featdirectory, followed by several optional
+    flags that control the registration process.
+
+    Examples
+    --------
+    >>> parser = _get_parser()
+    >>> args = parser.parse_args()
+    """
     # get the command line parameters
     parser = argparse.ArgumentParser(
         prog="rapidtide2std",
@@ -84,16 +112,74 @@ def _get_parser():
 
 
 def transformmaps(
-    thepath,
-    theoutputdir,
-    subjroot,
-    reftarget,
-    xformfuncmat,
-    warpfuncfile,
-    thefmrimaps=None,
-    theanatmaps=None,
-    preponly=False,
-):
+    thepath: Any,
+    theoutputdir: Any,
+    subjroot: Any,
+    reftarget: Any,
+    xformfuncmat: Any,
+    warpfuncfile: Any,
+    thefmrimaps: Optional[Any] = None,
+    theanatmaps: Optional[Any] = None,
+    preponly: bool = False,
+) -> None:
+    """
+    Apply spatial transformations to fMRI and anatomical maps from a happy dataset using FLIRT and/or
+    copy commands.
+
+    This function applies rigid-body and non-linear transformations to a set of fMRI and/or
+    anatomical maps, based on provided transformation matrices and warp fields. It supports
+    both functional and anatomical image processing pipelines.
+
+    Parameters
+    ----------
+    thepath : Any
+        Path to the directory containing input fMRI maps.
+    theoutputdir : Any
+        Directory where transformed maps will be saved.
+    subjroot : Any
+        Subject identifier used to construct input and output file names.
+    reftarget : Any
+        Reference image to which maps are transformed.
+    xformfuncmat : Any
+        Transformation matrix for functional-to-standard space alignment.
+    warpfuncfile : Any
+        Warp field file for non-linear functional-to-standard space transformation.
+    thefmrimaps : Optional[Any], default=None
+        List of fMRI map names to transform. If None, no fMRI maps are processed.
+    theanatmaps : Optional[Any], default=None
+        List of anatomical map names to transform. If None, no anatomical maps are processed.
+    preponly : bool, default=False
+        If True, only print the commands without executing them.
+
+    Returns
+    -------
+    None
+        This function does not return any value; it performs file I/O operations.
+
+    Notes
+    -----
+    - For fMRI maps, the function uses `tide_extern.makeflirtcmd` to generate and execute
+      FLIRT commands for transformation.
+    - For anatomical maps, it either copies the file or applies a transformation using
+      `tide_extern.makeflirtcmd`, depending on the `aligntohires` flag.
+    - If `preponly` is True, the commands are printed but not executed.
+    - The function assumes that input files exist and are named according to the
+      pattern: ``{subjroot}_{mapname}.nii.gz``.
+
+    Examples
+    --------
+    >>> transformmaps(
+    ...     thepath="/data/subj1",
+    ...     theoutputdir="/data/subj1/transformed",
+    ...     subjroot="subj1",
+    ...     reftarget="/data/templates/MNI152_T1_2mm.nii.gz",
+    ...     xformfuncmat="/data/subj1/reg/func2standard.mat",
+    ...     warpfuncfile="/data/subj1/reg/warpfield.nii.gz",
+    ...     thefmrimaps=["bold", "mask"],
+    ...     theanatmaps=["brain"],
+    ...     preponly=False
+    ... )
+    """
     print("entering transformmaps with:")
     print(thepath)
     print(subjroot)
@@ -151,7 +237,53 @@ def transformmaps(
                 print("no hires anatomic found - skipping")
 
 
-def happy2std(args):
+def happy2std(args: Any) -> None:
+    """
+    Apply FSL-based spatial transformation to fMRI data and anatomical maps.
+
+    This function performs spatial normalization of fMRI data to either high-resolution
+    or standard MNI152 space, using FSL transformation matrices and warp fields. It supports
+    both linear and nonlinear transformations, and can process either a single file or
+    a set of files based on input arguments.
+
+    Parameters
+    ----------
+    args : Any
+        An object containing command-line arguments. Expected attributes include:
+        - featdirectory : str
+            Path to the FEAT directory containing registration files.
+        - aligntohires : bool
+            If True, align to high-resolution anatomical space; otherwise to standard MNI152.
+        - forcelinear : bool
+            If True, forces use of a linear transformation even if warp files are present.
+        - onefilename : str or None
+            If provided, process only this single file.
+        - preponly : bool
+            If True, print the FSL command without executing it.
+        - inputfileroot : str
+            Root path to input files for batch processing.
+        - outputdir : str
+            Output directory for transformed files.
+        - all : bool
+            If True, include additional fMRI maps in processing.
+
+    Returns
+    -------
+    None
+        This function does not return a value but may exit the program on error.
+
+    Notes
+    -----
+    This function requires the FSL environment variable ``FSLDIR`` to be set.
+    It relies on FSL tools like `applywarp` and `flirt` for transformations.
+    The function supports processing of both single files and batches of files
+    using glob patterns.
+
+    Examples
+    --------
+    >>> args = parse_args()  # Assume args is parsed from command line
+    >>> happy2std(args)
+    """
     # make sure the appropriate transformation matrix and targets exist
     fsldir = os.environ.get("FSLDIR")
     if fsldir is None:

rapidtide/workflows/happy_parser.py

@@ -17,20 +17,56 @@
 #
 #
 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.multiproc as tide_multiproc
 import rapidtide.workflows.parser_funcs as pf
 
 DEFAULT_ALIASEDCORRELATIONWIDTH = 5.0
-DEFAULT_DL_MODEL = "model_revised_tf2"
+DEFAULT_PULSATILITYSIGMA = 6.0
+DEFAULT_PULSATILITYTHRESHOLD = 0.5
+DEFAULT_TF_DL_MODEL = "model_revised_tf2"
+DEFAULT_PT_DL_MODEL = "model_cnn_pytorch"
 
 
-def _get_parser():
+def _get_parser() -> Any:
     """
-    Argument parser for happy
+    Create and configure an argument parser for the happy command-line tool.
+
+    This function sets up an `argparse.ArgumentParser` with numerous options for
+    configuring the hypersampling by analytic phase projection (HAPPY) pipeline.
+    It includes arguments for input files, processing steps, performance tuning,
+    preprocessing, cardiac and respiration estimation, output handling, and debugging.
+
+    Returns
+    -------
+    argparse.ArgumentParser
+        Configured argument parser with all supported command-line options.
+
+    Notes
+    -----
+    The parser includes multiple argument groups for different functional areas:
+    - Processing steps
+    - Performance
+    - Preprocessing
+    - Cardiac estimation tuning
+    - External cardiac waveform options
+    - External respiration waveform options
+    - Output processing
+    - Output options
+    - Phase projection tuning
+    - Miscellaneous options
+    - Debugging options
+
+    Examples
+    --------
+    >>> parser = _get_parser()
+    >>> args = parser.parse_args()
     """
     parser = argparse.ArgumentParser(
         prog="happy",
@@ -101,10 +137,10 @@ def _get_parser():
         dest="modelname",
         metavar="MODELNAME",
         help=(
-            f"Use model MODELNAME for dl filter (default is {DEFAULT_DL_MODEL} - "
+            f"Use model MODELNAME for dl filter (default is {DEFAULT_PT_DL_MODEL} - "
             "from the revised NeuroImage paper.) "
         ),
-        default=DEFAULT_DL_MODEL,
+        default=None,
     )
 
     # Performance
@@ -550,6 +586,31 @@ def _get_parser():
         help="Restrict cardiac waveform estimation to putative arteries only.",
         default=False,
     )
+    phase_proj_tuning.add_argument(
+        "--pulsatilitysigma",
+        dest="pulsatilitysigma",
+        action="store",
+        metavar="SIGMAINMM",
+        type=lambda x: pf.is_float(parser, x),
+        help=(
+            "Split pulsatility map spatial frequencies with a gaussian filter with sigma=SIGMAINMM. "
+            f"Default is {DEFAULT_PULSATILITYSIGMA}mm. "
+        ),
+        default=DEFAULT_PULSATILITYSIGMA,
+    )
+    phase_proj_tuning.add_argument(
+        "--pulsatilitythreshold",
+        dest="pulsatilitythreshold",
+        action="store",
+        metavar="THRESHPCT",
+        type=lambda x: pf.is_float(parser, x),
+        help=(
+            "Consider voxels with a high spatial frequency pulsatility above THRESHPCT percent "
+            "to be vessels. "
+            f"Default is {DEFAULT_PULSATILITYTHRESHOLD}mm. "
+        ),
+        default=DEFAULT_PULSATILITYSIGMA,
+    )
 
     # Add version options
     pf.addversionopts(parser)
@@ -563,7 +624,7 @@ def _get_parser():
         metavar="MASKNAME",
         help=(
             "Instead of dynamically generating a processing mask from the data, use "
-            "the mask specified in the file MASKNAME. "            
+            "the mask specified in the file MASKNAME. "
             "The mask must be a 3D NIFTI file with x, y, z dimensions matching the fMRI data. "
         ),
         default=None,
@@ -613,6 +674,13 @@ def _get_parser():
         help="Number of iterations for calculating Wright map. Set to 0 to disable.",
         default=0,
     )
+    misc_opts.add_argument(
+        "--usenewvesselmethod",
+        dest="useoriginalvesselmethod",
+        action="store_false",
+        help="Will use the new pulsatility method to find blood vessels. ",
+        default=True,
+    )
     pf.addtagopts(
         misc_opts,
         helptext="Additional key, value pairs to add to the info json file (useful for tracking analyses).",
@@ -635,6 +703,13 @@ def _get_parser():
         help="Disable data detrending. ",
         default=3,
     )
+    debug_opts.add_argument(
+        "--normvesselmap",
+        dest="unnormvesselmap",
+        action="store_false",
+        help="Find vessels using normalized phase projection. ",
+        default=True,
+    )
     debug_opts.add_argument(
         "--noorthog",
         dest="orthogonalize",
@@ -740,13 +815,57 @@ def _get_parser():
         help="Disable the congrid value cache completely.",
         default=True,
     )
+    debug_opts.add_argument(
+        "--usetensorflow",
+        dest="usepytorch",
+        action="store_false",
+        help=("Switch to the old style tensorflow deep learning filter"),
+        default=True,
+    )
+    debug_opts.add_argument(
+        "--focaldebug",
+        dest="focaldebug",
+        action="store_true",
+        help=("Enable targeted additional debugging output (used during development)."),
+        default=False,
+    )
 
     return parser
 
 
-def process_args(inputargs=None):
+def process_args(inputargs: Optional[Any] = None) -> None:
     """
-    Compile arguments for rapidtide workflow.
+    Compile arguments for happy workflow.
+
+    This function processes input arguments for the happy workflow, handling
+    argument parsing, command line formatting, default model selection, and post-processing
+    of various parameters. It also manages motion file specifications, multiprocessing
+    settings, and output level calculations.
+
+    Parameters
+    ----------
+    inputargs : optional
+        Input arguments to be processed. If None, arguments are parsed from the command line.
+        Default is None.
+
+    Returns
+    -------
+    args : argparse.Namespace
+        Processed arguments namespace containing all parsed and defaulted values.
+
+    Notes
+    -----
+    - If no model is specified, the function sets a default based on whether PyTorch or TensorFlow
+      is being used.
+    - The function writes formatted command line arguments to files for logging purposes.
+    - Multiprocessing is currently disabled due to instability.
+    - The output level is adjusted based on user-provided increments and decrements.
+
+    Examples
+    --------
+    >>> args = process_args()
+    >>> print(args.outputroot)
+    >>> print(args.modelname)
     """
     args, argstowrite = pf.setargs(_get_parser, inputargs=inputargs)
 
@@ -773,6 +892,14 @@ def process_args(inputargs=None):
         formattedcommandline[i] = prefix + formattedcommandline[i] + suffix
     tide_io.writevec(formattedcommandline, args.outputroot + "_formattedcommandline.txt")
 
+    # if user did not specify a model, set the default, depending on DL library
+    if args.modelname is None:
+        if args.usepytorch:
+            args.modelname = DEFAULT_PT_DL_MODEL
+        else:
+            args.modelname = DEFAULT_TF_DL_MODEL
+        print(f"No model specified.  {args.usepytorch=}, so using {args.modelname}")
+
     if args.debug:
         print()
         print("before postprocessing")
@@ -788,12 +915,12 @@ def process_args(inputargs=None):
     args.upsamplefac = 100
     args.centric = True
     args.pulsereconstepsize = 0.01
-    args.unnormvesselmap = True
     args.histlen = 100
     args.softvesselfrac = 0.4
     args.savecardiacnoise = True
     args.colnum = None
     args.colname = None
+    args.notchrolloff = 0.5
 
     # Additional argument parsing not handled by argparse
     # deal with notch filter logic
@@ -807,6 +934,8 @@ def process_args(inputargs=None):
         args.motionfilename = None
 
     # set the number of worker processes if multiprocessing
+    # Multiprocessing is very broken atm.  Hard disable it.
+    # args.nprocs = 1
     if args.nprocs < 1:
         args.nprocs = tide_multiproc.maxcpus()
 

rapidtide/workflows/histnifti.py

@@ -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 = []

rapidtide/workflows/histtc.py

@@ -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 = []