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

rapidtide/workflows/happy2std.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.
@@ -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

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
 #
-#   Copyright 2019-2024 Blaise Frederick
+#   Copyright 2019-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,61 @@
 #
 #
 import argparse
-import sys
+from typing import Any, Optional
 
 import numpy as np
 
 import rapidtide.io as tide_io
+import rapidtide.multiproc as tide_multiproc
 import rapidtide.workflows.parser_funcs as pf
 
+try:
+    import tensorflow as tf
 
-def _get_parser():
+    tensorflowpresent = True
+except ImportError:
+    tensorflowpresent = False
+
+DEFAULT_ALIASEDCORRELATIONWIDTH = 5.0
+DEFAULT_PULSATILITYSIGMA = 6.0
+DEFAULT_PULSATILITYTHRESHOLD = 0.5
+DEFAULT_TF_DL_MODEL = "model_revised_tf2"
+DEFAULT_PT_DL_MODEL = "model_ppgattention_pytorch_w128_fulldata"
+
+
+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",
@@ -70,18 +114,19 @@ def _get_parser():
         help="Disable deep learning cardiac waveform filter.  ",
         default=True,
     )
-    processing_steps.add_argument(
-        "--usesuperdangerousworkaround",
-        dest="mpfix",
-        action="store_true",
-        help=(
-            "Some versions of tensorflow seem to have some weird conflict with MKL which"
-            "I don't seem to be able to fix.  If the dl filter bombs complaining about "
-            "multiple openmp libraries, try rerunning with the secret and inadvisable "
-            "'--usesuperdangerousworkaround' flag.  Good luck! "
-        ),
-        default=False,
-    )
+    if tensorflowpresent:
+        processing_steps.add_argument(
+            "--usesuperdangerousworkaround",
+            dest="mpfix",
+            action="store_true",
+            help=(
+                "Some versions of tensorflow seem to have some weird conflict with MKL which"
+                "I don't seem to be able to fix.  If the dl filter bombs complaining about "
+                "multiple openmp libraries, try rerunning with the secret and inadvisable "
+                "'--usesuperdangerousworkaround' flag.  Good luck! "
+            ),
+            default=False,
+        )
     processing_steps.add_argument(
         "--slicetimesareinseconds",
         action="store_true",
@@ -98,10 +143,10 @@ def _get_parser():
         dest="modelname",
         metavar="MODELNAME",
         help=(
-            "Use model MODELNAME for dl filter (default is model_revised - "
-            "from the revised NeuroImage paper. "
+            f"Use model MODELNAME for dl filter (default is {DEFAULT_PT_DL_MODEL} - "
+            "from the revised NeuroImage paper.) "
         ),
-        default="model_revised",
+        default=None,
     )
 
     # Performance
@@ -119,7 +164,20 @@ def _get_parser():
         ),
         default=1,
     )
-
+    performance_opts.add_argument(
+        "--nprocs",
+        dest="nprocs",
+        action="store",
+        metavar="NPROCS",
+        type=lambda x: pf.is_int(parser, x),
+        help=(
+            "Use NPROCS CPUs to accelerate processing (defaults to 1 - more "
+            "CPUs up to the number of cores can accelerate processing a lot, but "
+            "you need to remember to ask for this many CPUs on clusters.)  Entering a mulitprocessor "
+            "routine disables mklthreads (otherwise there's chaos)."
+        ),
+        default=1,
+    )
     # Preprocessing
     preprocessing_opts = parser.add_argument_group("Preprocessing")
     preprocessing_opts.add_argument(
@@ -142,7 +200,7 @@ def _get_parser():
     )
     preprocessing_opts.add_argument(
         "--motionfile",
-        dest="motionfilename",
+        dest="motionfilespec",
         metavar="MOTFILE",
         help=(
             "Read 6 columns of motion regressors out of MOTFILE file (.par or BIDS .json) "
@@ -178,13 +236,6 @@ def _get_parser():
         ),
         default=True,
     )
-    preprocessing_opts.add_argument(
-        "--motpos",
-        dest="motfilt_pos",
-        action="store_true",
-        help=("Include motion position regressors. "),
-        default=False,
-    )
     preprocessing_opts.add_argument(
         "--nomotderiv",
         dest="motfilt_deriv",
@@ -192,6 +243,17 @@ def _get_parser():
         help=("Do not use motion derivative regressors. "),
         default=True,
     )
+    preprocessing_opts.add_argument(
+        "--motfiltorder",
+        dest="motfilt_order",
+        action="store",
+        metavar="N",
+        type=lambda x: pf.is_int(parser, x),
+        help=(
+            "Include powers of each confound regressor up to order N. Default is 1 (no expansion). "
+        ),
+        default=1,
+    )
     preprocessing_opts.add_argument(
         "--discardmotionfiltered",
         dest="savemotionglmfilt",
@@ -203,10 +265,10 @@ def _get_parser():
     # Cardiac estimation tuning
     cardiac_est_tuning = parser.add_argument_group("Cardiac estimation tuning")
     cardiac_est_tuning.add_argument(
-        "--estmask",
-        dest="estmaskname",
+        "--estweights",
+        dest="estweightsname",
         action="store",
-        metavar="MASKNAME",
+        metavar="WEIGHTSNAME",
         help=(
             "Generation of cardiac waveform from data will be restricted to "
             "voxels in MASKNAME and weighted by the mask intensity.  If this is "
@@ -288,6 +350,15 @@ def _get_parser():
         ),
         default=False,
     )
+    cardiac_est_tuning.add_argument(
+        "--teoffset",
+        dest="teoffset",
+        action="store",
+        metavar="TE",
+        type=lambda x: pf.is_float(parser, x),
+        help="Specify the echo time in seconds.  This is used when combining multiecho data.  Default is 0. ",
+        default=None,
+    )
 
     # External cardiac waveform options
     external_cardiac_opts = parser.add_argument_group("External cardiac waveform options")
@@ -429,15 +500,15 @@ def _get_parser():
     # Output processing
     output_proc = parser.add_argument_group("Output processing")
     output_proc.add_argument(
-        "--spatialglm",
-        dest="dospatialglm",
+        "--spatialregression",
+        dest="dospatialregression",
         action="store_true",
         help="Generate framewise cardiac signal maps and filter them out of the input data. ",
         default=False,
     )
     output_proc.add_argument(
-        "--temporalglm",
-        dest="dotemporalglm",
+        "--temporalregression",
+        dest="dotemporalregression",
         action="store_true",
         help="Generate voxelwise aliased synthetic cardiac regressors and filter them out of the input data. ",
         default=False,
@@ -521,12 +592,49 @@ 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)
 
     # Add miscellaneous options
     misc_opts = parser.add_argument_group("Miscellaneous options.")
+    misc_opts.add_argument(
+        "--processmask",
+        dest="processmask",
+        action="store",
+        metavar="MASKNAME",
+        help=(
+            "Instead of dynamically generating a processing mask from the data, use "
+            "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,
+    )
     misc_opts.add_argument(
         "--aliasedcorrelation",
         dest="doaliasedcorrelation",
@@ -534,6 +642,15 @@ def _get_parser():
         help="Attempt to calculate absolute delay using an aliased correlation (experimental).",
         default=False,
     )
+    misc_opts.add_argument(
+        "--aliasedcorrelationwidth",
+        dest="aliasedcorrelationwidth",
+        metavar="WIDTH",
+        action="store",
+        type=lambda x: pf.is_float(parser, x),
+        help=f"Width of the aliased correlation calculation (default is {DEFAULT_ALIASEDCORRELATIONWIDTH}). ",
+        default=DEFAULT_ALIASEDCORRELATIONWIDTH,
+    )
     misc_opts.add_argument(
         "--upsample",
         dest="doupsampling",
@@ -555,6 +672,21 @@ def _get_parser():
         help="Will disable showing progress bars (helpful if stdout is going to a file). ",
         default=True,
     )
+    misc_opts.add_argument(
+        "--wrightiterations",
+        dest="wrightiterations",
+        action="store",
+        type=lambda x: pf.is_int(parser, x),
+        help="Number of iterations for calculating Wright map. Set to 0 to disable.",
+        default=0,
+    )
+    misc_opts.add_argument(
+        "--useoldvesselmethod",
+        dest="useoriginalvesselmethod",
+        action="store_true",
+        help="Will use the old method to find blood vessels. ",
+        default=False,
+    )
     pf.addtagopts(
         misc_opts,
         helptext="Additional key, value pairs to add to the info json file (useful for tracking analyses).",
@@ -577,6 +709,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",
@@ -654,35 +793,92 @@ def _get_parser():
         help="Decrease the number of intermediate output files. ",
         default=0,
     )
+    debug_opts.add_argument(
+        "--nompdetrend",
+        dest="mpdetrend",
+        action="store_false",
+        help="Disable multiproc detrending.",
+        default=True,
+    )
+    debug_opts.add_argument(
+        "--nompphaseproject",
+        dest="mpphaseproject",
+        action="store_false",
+        help="Disable multiproc phase projection.",
+        default=True,
+    )
+    debug_opts.add_argument(
+        "--noprefillcongrid",
+        dest="preloadcongrid",
+        action="store_false",
+        help="Don't prefill the congrid value cache.",
+        default=True,
+    )
+    debug_opts.add_argument(
+        "--nocongridcache",
+        dest="congridcache",
+        action="store_false",
+        help="Disable the congrid value cache completely.",
+        default=True,
+    )
+    if tensorflowpresent:
+        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) -> Any:
     """
-    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)
     """
-    if inputargs is None:
-        print("processing command line arguments")
-        # write out the command used
-        try:
-            args = _get_parser().parse_args()
-            argstowrite = sys.argv
-        except SystemExit:
-            _get_parser().print_help()
-            raise
-    else:
-        print("processing passed argument list:")
-        try:
-            args = _get_parser().parse_args(inputargs)
-            argstowrite = inputargs
-        except SystemExit:
-            print("Use --help option for detailed informtion on options.")
-            raise
+    args, argstowrite = pf.setargs(_get_parser, inputargs=inputargs)
 
     # save the raw and formatted command lines
     args.commandline = " ".join(argstowrite)
-    tide_io.writevec([args.commandline], args.outputroot + "_commandline.txt")
+    tide_io.writevec(np.array([args.commandline]), args.outputroot + "_commandline.txt")
     formattedcommandline = []
     for thetoken in argstowrite[0:3]:
         formattedcommandline.append(thetoken)
@@ -701,7 +897,19 @@ def process_args(inputargs=None):
         else:
             suffix = ""
         formattedcommandline[i] = prefix + formattedcommandline[i] + suffix
-    tide_io.writevec(formattedcommandline, args.outputroot + "_formattedcommandline.txt")
+    tide_io.writevec(np.array(formattedcommandline), args.outputroot + "_formattedcommandline.txt")
+
+    if not tensorflowpresent:
+        args.usepytorch = True
+        args.mpfix = False
+
+    # 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()
@@ -712,26 +920,36 @@ def process_args(inputargs=None):
     args.outputlevel = 1
     args.maskthreshpct = 10.0
     args.domadnorm = True
-    args.nprocs = 1
     args.verbose = False
     args.smoothlen = 101
     args.envthresh = 0.2
     args.upsamplefac = 100
     args.centric = True
     args.pulsereconstepsize = 0.01
-    args.aliasedcorrelationwidth = 3.0
-    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
     if args.disablenotch:
         args.notchpct = None
 
+    # process motionfile information
+    if args.motionfilespec is not None:
+        (args.motionfilename, args.motionfilecolspec) = tide_io.parsefilespec(args.motionfilespec)
+    else:
+        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()
+
     # process infotags
     args = pf.postprocesstagopts(args)