rapidtide 3.0.2__py3-none-any.whl → 3.0.3__py3-none-any.whl

rapidtide/workflows/rapidtide_parser.py

@@ -29,6 +29,7 @@ import rapidtide.io as tide_io
 import rapidtide.util as tide_util
 import rapidtide.workflows.parser_funcs as pf
 
+
 # Create a sentinel.
 # from https://stackoverflow.com/questions/58594956/find-out-which-arguments-were-passed-explicitly-in-argparse
 class _Sentinel:
@@ -43,7 +44,7 @@ LGR = logging.getLogger(__name__)
 DEFAULT_SPATIALFILT = -1
 DEFAULT_HISTLEN = 101
 DEFAULT_DETREND_ORDER = 3
-DEFAULT_GLOBAL_PCACOMPONENTS = 0.8
+DEFAULT_INITREGRESSOR_PCACOMPONENTS = 0.8
 DEFAULT_CORRMASK_THRESHPCT = 1.0
 DEFAULT_MUTUALINFO_SMOOTHINGTIME = 3.0
 DEFAULT_LAGMIN = -30.0
@@ -62,7 +63,7 @@ DEFAULT_MAXPASSES = 15
 DEFAULT_REFINE_TYPE = "pca"
 DEFAULT_INTERPTYPE = "univariate"
 DEFAULT_WINDOW_TYPE = "hamming"
-DEFAULT_GLOBALSIGNAL_METHOD = "sum"
+DEFAULT_INITREGRESSOR_METHOD = "sum"
 DEFAULT_CORRWEIGHTING = "phat"
 DEFAULT_CORRTYPE = "linear"
 DEFAULT_SIMILARITYMETRIC = "correlation"
@@ -193,7 +194,7 @@ def _get_parser():
     )
     analysis_type.add_argument(
         "--globalpreselect",
-        dest="globalpreselect",
+        dest="initregressorpreselect",
         action="store_true",
         help=(
             "Treat this run as an initial pass to locate good candidate voxels for global mean "
@@ -259,7 +260,7 @@ def _get_parser():
             "2) decide which voxels in which to calculate delays, "
             "3) refine the regressor at the end of each pass, 4) determine the zero time offset value, and 5) process "
             "to remove sLFO signal. "
-            "Setting --globalmeaninclude, --refineinclude, --corrmaskinclude or --offsetinclude explicitly will "
+            "Setting --initregressorinclude, --corrmaskinclude, --refineinclude or --offsetinclude explicitly will "
             "override this for the given include mask."
         ),
         default=None,
@@ -272,9 +273,8 @@ def _get_parser():
             "This specifies a gray matter mask registered to the input functional data.  "
             "If VALSPEC is given, only voxels in the mask with integral values listed in VALSPEC are used, otherwise "
             "voxels with value > 0.1 are used.  If this option is set, "
-            "rapidtide will use voxels in the gray matter mask to 1) calculate the initial global mean regressor, "
-            "and 2) for determining the zero time offset value. "
-            "Setting --globalmeaninclude or --offsetinclude explicitly will override this for "
+            "rapidtide will use voxels in the gray matter mask to calculate the initial global mean regressor. "
+            "Setting --initregressorinclude  explicitly will override this for "
             "the given include mask."
         ),
         default=None,
@@ -287,8 +287,21 @@ def _get_parser():
             "This specifies a white matter mask registered to the input functional data.  "
             "If VALSPEC is given, only voxels in the mask with integral values listed in VALSPEC are used, otherwise "
             "voxels with value > 0.1 are used.  "
-            "This currently isn't used for anything, but rapidtide will keep track of it and might use if for something "
-            "in a later version."
+            "This will be used to calculate the white matter timecourse before running rapidtide, and after sLFO "
+            "filtering (if enabled)."
+        ),
+        default=None,
+    )
+    anatomy.add_argument(
+        "--csfmask",
+        dest="csfincludespec",
+        metavar="MASK[:VALSPEC]",
+        help=(
+            "This specifies a CSF mask registered to the input functional data.  "
+            "If VALSPEC is given, only voxels in the mask with integral values listed in VALSPEC are used, otherwise "
+            "voxels with value > 0.1 are used.  "
+            "This will be used to calculate the CSF timecourse before running rapidtide, and after sLFO "
+            "filtering (if enabled)."
         ),
         default=None,
     )
@@ -437,7 +450,7 @@ def _get_parser():
     )
     preproc.add_argument(
         "--globalmean",
-        dest="useglobalref",
+        dest="useinitregressorref",
         action="store_true",
         help=(
             "Generate a global mean regressor and use that as the reference "
@@ -448,10 +461,10 @@ def _get_parser():
     )
     preproc.add_argument(
         "--globalmeaninclude",
-        dest="globalmeanincludespec",
+        dest="initregressorincludespec",
         metavar="MASK[:VALSPEC]",
         help=(
-            "Only use voxels in mask file NAME for global regressor "
+            "Only use voxels in mask file NAME for the initial regressor "
             "generation (if VALSPEC is given, only voxels "
             "with integral values listed in VALSPEC are used)."
         ),
@@ -459,10 +472,10 @@ def _get_parser():
     )
     preproc.add_argument(
         "--globalmeanexclude",
-        dest="globalmeanexcludespec",
+        dest="initregressorexcludespec",
         metavar="MASK[:VALSPEC]",
         help=(
-            "Do not use voxels in mask file NAME for global regressor "
+            "Do not use voxels in mask file NAME for the initial regressor "
             "generation (if VALSPEC is given, only voxels "
             "with integral values listed in VALSPEC are excluded)."
         ),
@@ -479,6 +492,16 @@ def _get_parser():
         ),
         default=None,
     )
+    preproc.add_argument(
+        "--motpowers",
+        dest="mot_power",
+        metavar="N",
+        type=lambda x: pf.is_int(parser, x, minval=1),
+        help=(
+            "Include powers of each motion regressor up to order N. Default is 1 (no expansion). "
+        ),
+        default=1,
+    )
     preproc.add_argument(
         "--nomotderiv",
         dest="mot_deriv",
@@ -530,32 +553,32 @@ def _get_parser():
     )
     preproc.add_argument(
         "--globalsignalmethod",
-        dest="globalsignalmethod",
+        dest="initregressorsignalmethod",
         action="store",
         type=str,
         choices=["sum", "meanscale", "pca", "random"],
         help=(
-            "The method for constructing the initial global signal regressor - straight summation, "
-            "mean scaling each voxel prior to summation, MLE PCA of the voxels in the global signal mask, "
+            "The method for constructing the initial signal regressor - straight summation, "
+            "mean scaling each voxel prior to summation, MLE PCA of the voxels in the initial regressor mask, "
             "or initializing using random noise."
-            f'Default is "{DEFAULT_GLOBALSIGNAL_METHOD}."'
+            f'Default is "{DEFAULT_INITREGRESSOR_METHOD}."'
         ),
-        default=DEFAULT_GLOBALSIGNAL_METHOD,
+        default=DEFAULT_INITREGRESSOR_METHOD,
     )
     preproc.add_argument(
         "--globalpcacomponents",
-        dest="globalpcacomponents",
+        dest="initregressorpcacomponents",
         action="store",
         type=float,
         metavar="VALUE",
         help=(
-            "Number of PCA components used for estimating the global signal.  If VALUE >= 1, will retain this"
+            "Number of PCA components used for estimating the initial regressor.  If VALUE >= 1, will retain this"
             "many components.  If "
             "0.0 < VALUE < 1.0, enough components will be retained to explain the fraction VALUE of the "
             "total variance. If VALUE is negative, the number of components will be to retain will be selected "
-            f"automatically using the MLE method.  Default is {DEFAULT_GLOBAL_PCACOMPONENTS}."
+            f"automatically using the MLE method.  Default is {DEFAULT_INITREGRESSOR_PCACOMPONENTS}."
         ),
-        default=DEFAULT_GLOBAL_PCACOMPONENTS,
+        default=DEFAULT_INITREGRESSOR_PCACOMPONENTS,
     )
     preproc.add_argument(
         "--slicetimes",
@@ -1270,7 +1293,7 @@ def _get_parser():
         "--saveintermediatemaps",
         dest="saveintermediatemaps",
         action="store_true",
-        help="Save lag times, strengths, widths, and mask for each pass.",
+        help="Save lag times, strengths, widths, mask (and shiftedtcs, if they'd normally be saved) for each pass.",
         default=False,
     )
     output.add_argument(
@@ -1911,20 +1934,27 @@ def process_args(inputargs=None):
     else:
         args["inputfreq_nondefault"] = True
 
-    # mask processing
-    if args["corrmaskincludespec"] is not None:
-        (
-            args["corrmaskincludename"],
-            args["corrmaskincludevals"],
-        ) = tide_io.processnamespec(
-            args["corrmaskincludespec"],
-            "Including voxels where ",
-            "in correlation calculations.",
-        )
-    else:
-        args["corrmaskincludename"] = None
-
-    # if brainmaskincludespec is set, set corrmaskinclude to it.
+    # initial mask values from anatomical images (before any overrides)
+    for key in [
+        "corrmaskincludename",
+        "corrmaskincludevals",
+        "initregressorincludename",
+        "initregressorincludevals",
+        "initregressorexcludename",
+        "initregressorexcludevals",
+        "refineincludename",
+        "refineincludevals",
+        "refineexcludename",
+        "refineexcludevals",
+        "offsetincludename",
+        "offsetincludevals",
+        "offsetexcludename",
+        "offsetexcludevals",
+    ]:
+        args[key] = None
+
+    # if brainmaskincludespec is set, set initregressorinclude, corrmaskinclude, refineinclude, and offsetinclude to it.
+    brainmasks = ["initregressor", "corrmask", "refine", "offset"]
     if args["brainmaskincludespec"] is not None:
         (
             args["brainmaskincludename"],
@@ -1934,12 +1964,22 @@ def process_args(inputargs=None):
         )
         if not os.path.isfile(args["brainmaskincludename"]):
             raise FileNotFoundError(f"file {args['brainmaskincludename']} does not exist.")
+        for masktype in brainmasks:
+            (
+                args[f"{masktype}includename"],
+                args[f"{masktype}includevals"],
+            ) = (
+                args["brainmaskincludename"],
+                args["brainmaskincludevals"],
+            )
+            print(f"setting {masktype}include mask to gray matter mask")
     else:
         args["brainmaskincludename"] = None
         args["brainmaskincludevals"] = None
 
-    # if graymatterincludespec is set, set globalmeaninclude, offsetinclude to it.
-    graymasks = ["globalmean", "offset"]
+    # if graymatterincludespec is set, set initregressorinclude, offsetinclude to it.
+    # graymasks = ["initregressor", "offset"]
+    graymasks = ["initregressor"]
     if args["graymatterincludespec"] is not None:
         (
             args["graymatterincludename"],
@@ -1961,9 +2001,6 @@ def process_args(inputargs=None):
     else:
         args["graymatterincludename"] = None
         args["graymatterincludevals"] = None
-        for masktype in graymasks:
-            args[f"{masktype}includename"] = None
-            args[f"{masktype}includevals"] = None
 
     if args["whitematterincludespec"] is not None:
         (
@@ -1976,26 +2013,47 @@ def process_args(inputargs=None):
         args["whitematterincludename"] = None
         args["whitematterincludevals"] = None
 
-    if args["globalmeanincludespec"] is not None:
+    if args["csfincludespec"] is not None:
         (
-            args["globalmeanincludename"],
-            args["globalmeanincludevals"],
+            args["csfincludename"],
+            args["csfincludevals"],
         ) = tide_io.processnamespec(
-            args["globalmeanincludespec"], "Including voxels where ", "in global mean."
+            args["csfincludespec"], "Including voxels where ", "in CSF mask."
         )
+    else:
+        args["csfincludename"] = None
+        args["csfincludevals"] = None
 
-    if args["globalmeanexcludespec"] is not None:
+    # individual mask processing (including overrides)
+    if args["corrmaskincludespec"] is not None:
         (
-            args["globalmeanexcludename"],
-            args["globalmeanexcludevals"],
+            args["corrmaskincludename"],
+            args["corrmaskincludevals"],
         ) = tide_io.processnamespec(
-            args["globalmeanexcludespec"],
+            args["corrmaskincludespec"],
+            "Including voxels where ",
+            "in correlation calculations.",
+        )
+
+    if args["initregressorincludespec"] is not None:
+        (
+            args["initregressorincludename"],
+            args["initregressorincludevals"],
+        ) = tide_io.processnamespec(
+            args["initregressorincludespec"],
+            "Including voxels where ",
+            "in initial regressor calculation.",
+        )
+
+    if args["initregressorexcludespec"] is not None:
+        (
+            args["initregressorexcludename"],
+            args["initregressorexcludevals"],
+        ) = tide_io.processnamespec(
+            args["initregressorexcludespec"],
             "Excluding voxels where ",
-            "from global mean.",
+            "from initial regressor calculation.",
         )
-    else:
-        args["globalmeanexcludename"] = None
-        args["globalmeanexcludevals"] = None
 
     if args["refineincludespec"] is not None:
         (
@@ -2004,9 +2062,6 @@ def process_args(inputargs=None):
         ) = tide_io.processnamespec(
             args["refineincludespec"], "Including voxels where ", "in refinement."
         )
-    else:
-        args["refineincludename"] = None
-        args["refineincludevals"] = None
 
     if args["refineexcludespec"] is not None:
         (
@@ -2015,9 +2070,6 @@ def process_args(inputargs=None):
         ) = tide_io.processnamespec(
             args["refineexcludespec"], "Excluding voxels where ", "from refinement."
         )
-    else:
-        args["refineexcludename"] = None
-        args["refineexcludevals"] = None
 
     if args["offsetincludespec"] is not None:
         (
@@ -2034,9 +2086,6 @@ def process_args(inputargs=None):
         ) = tide_io.processnamespec(
             args["offsetexcludespec"], "Excluding voxels where ", "from offset calculation."
         )
-    else:
-        args["offsetexcludename"] = None
-        args["offsetexcludevals"] = None
 
     # motion processing
     if args["motionfilespec"] is not None:
@@ -2091,7 +2140,7 @@ def process_args(inputargs=None):
         args["outputlevel"] = "min"
         args["dolinfitfilt"] = False
 
-    if args["globalpreselect"]:
+    if args["initregressorpreselect"]:
         LGR.warning('Using "globalpreselect" analysis mode. Overriding any affected arguments.')
         args["passes"] = 1
         args["despeckle_passes"] = 0
@@ -2198,7 +2247,7 @@ def process_args(inputargs=None):
             args["territorymapname"],
             args["territorymapincludevals"],
         ) = tide_io.processnamespec(
-            args["territorymap"], "Including voxels where ", "in global mean."
+            args["territorymap"], "Including voxels where ", "in initial regressor calculation."
         )
     else:
         args["territorymapname"] = None

rapidtide/workflows/retroregress.py

@@ -28,6 +28,7 @@ import numpy as np
 
 import rapidtide.filter as tide_filt
 import rapidtide.io as tide_io
+import rapidtide.maskutil as tide_mask
 import rapidtide.miscmath as tide_math
 import rapidtide.multiproc as tide_multiproc
 import rapidtide.refinedelay as tide_refinedelay
@@ -802,16 +803,138 @@ def retroregress(args):
                 "message3": "voxels",
             },
         )
-        # finalrawvariance = tide_math.imagevariance(filtereddata, None, 1.0 / fmritr)
         finalvariance = tide_math.imagevariance(filtereddata, theprefilter, 1.0 / fmritr)
 
         divlocs = np.where(finalvariance > 0.0)
         varchange = initialvariance * 0.0
         varchange[divlocs] = 100.0 * (finalvariance[divlocs] / initialvariance[divlocs] - 1.0)
 
-        """divlocs = np.where(finalrawvariance > 0.0)
-        rawvarchange = initialrawvariance * 0.0
-        rawvarchange[divlocs] = 100.0 * (finalrawvariance[divlocs] / initialrawvariance[divlocs] - 1.0)"""
+        # save regional timecourses if masks are defined
+        # read in the anatomic masks
+        anatomiclist = [
+            ["brainmaskincludename", "brainmaskincludevals", "brainmask"],
+            ["graymatterincludename", "graymatterincludevals", "graymattermask"],
+            ["whitematterincludename", "whitematterincludevals", "whitemattermask"],
+            ["csfincludename", "csfincludevals", "csfmask"],
+        ]
+        anatomicmasks = []
+        for thisanatomic in anatomiclist:
+            if therunoptions[thisanatomic[0]] is not None:
+                anatomicmasks.append(
+                    tide_mask.readamask(
+                        therunoptions[thisanatomic[0]],
+                        theinputdata.nim_hdr,
+                        xsize,
+                        istext=(theinputdata.filetype == "text"),
+                        valslist=therunoptions[thisanatomic[1]],
+                        maskname=thisanatomic[2],
+                        tolerance=therunoptions["spatialtolerance"],
+                        debug=args.focaldebug,
+                    )
+                )
+                anatomicmasks[-1] = np.uint16(np.where(anatomicmasks[-1] > 0.1, 1, 0))
+            else:
+                anatomicmasks.append(None)
+        brainmask = anatomicmasks[0]
+        graymask = anatomicmasks[1]
+        whitemask = anatomicmasks[2]
+        csfmask = anatomicmasks[3]
+
+        """if internalinitregressorincludemask is not None:
+            thisincludemask = internalinitregressorincludemask[validvoxels]
+        else:
+            thisincludemask = None
+        if internalinitregressorexcludemask is not None:
+            thisexcludemask = internalinitregressorexcludemask[validvoxels]
+        else:
+            thisexcludemask = None
+
+        meanvec, meanmask = tide_mask.saveregionaltimeseries(
+            "initial regressor",
+            "startregressormask",
+            filtereddata,
+            thisincludemask,
+            1.0 / fmritr,
+            outputname,
+            initfile=True,
+            excludemask=thisexcludemask,
+            filedesc="regionalpostfilter",
+            suffix="",
+            debug=args.debug,
+        )"""
+        # reformat the anatomic masks, if they exist
+        if brainmask is None:
+            invbrainmask = None
+
+            internalbrainmask = None
+            internalinvbrainmask = None
+        else:
+            invbrainmask = 1 - brainmask
+            internalbrainmask = brainmask.reshape((numspatiallocs))
+            internalinvbrainmask = invbrainmask.reshape((numspatiallocs))
+        if graymask is None:
+            internalgraymask = None
+        else:
+            internalgraymask = graymask.reshape((numspatiallocs))
+        if whitemask is None:
+            internalwhitemask = None
+        else:
+            internalwhitemask = whitemask.reshape((numspatiallocs))
+        if csfmask is None:
+            internalcsfmask = None
+        else:
+            internalcsfmask = csfmask.reshape((numspatiallocs))
+        if brainmask is not None:
+            brainvec, dummy = tide_mask.saveregionaltimeseries(
+                "whole brain",
+                "brain",
+                filtereddata,
+                internalbrainmask[validvoxels],
+                1.0 / fmritr,
+                outputname,
+                filedesc="regionalpostfilter",
+                suffix="",
+                debug=args.debug,
+            )
+        if graymask is not None:
+            grayvec, dummy = tide_mask.saveregionaltimeseries(
+                "gray matter",
+                "GM",
+                filtereddata,
+                internalgraymask[validvoxels],
+                1.0 / fmritr,
+                outputname,
+                excludemask=internalinvbrainmask[validvoxels],
+                filedesc="regionalpostfilter",
+                suffix="",
+                debug=args.debug,
+            )
+        if whitemask is not None:
+            whitevec, dummy = tide_mask.saveregionaltimeseries(
+                "white matter",
+                "WM",
+                filtereddata,
+                internalwhitemask[validvoxels],
+                1.0 / fmritr,
+                outputname,
+                excludemask=internalinvbrainmask[validvoxels],
+                filedesc="regionalpostfilter",
+                suffix="",
+                debug=args.debug,
+            )
+        if csfmask is not None:
+            grayvec, dummy = tide_mask.saveregionaltimeseries(
+                "CSF",
+                "CSF",
+                filtereddata,
+                internalcsfmask[validvoxels],
+                1.0 / fmritr,
+                outputname,
+                excludemask=internalinvbrainmask[validvoxels],
+                filedesc="regionalpostfilter",
+                suffix="",
+                debug=args.debug,
+            )
 
         # save outputs
         TimingLGR.info("Starting output save")
@@ -899,8 +1022,20 @@ def retroregress(args):
                     "second",
                     "Lag time in seconds used for calculation",
                 ),
-                (corrmask_valid, "corrfitREAD", "mask", None, "Correlation mask used for calculation"),
-                (procmask_valid, "processedREAD", "mask", None, "Processed mask used for calculation"),
+                (
+                    corrmask_valid,
+                    "corrfitREAD",
+                    "mask",
+                    None,
+                    "Correlation mask used for calculation",
+                ),
+                (
+                    procmask_valid,
+                    "processedREAD",
+                    "mask",
+                    None,
+                    "Processed mask used for calculation",
+                ),
             ]
         if args.savenormalsLFOfiltfiles:
             if args.regressderivs > 0 or args.refinedelay:
@@ -1109,33 +1244,35 @@ def retroregress(args):
                 )
             TimingLGR.info("Filtering for maxcorralt calculation complete")
             TimingLGR.info("GLM for maxcorralt calculation start")
-            voxelsprocessed_regressionfilt, regressorset, evset = tide_regressfrommaps.regressfrommaps(
-                fmri_data_valid,
-                validvoxels,
-                initial_fmri_x,
-                lagstouse_valid,
-                corrmask_valid,
-                genlagtc,
-                mode,
-                outputname,
-                oversamptr,
-                sLFOfitmean,
-                rvalue,
-                r2value,
-                fitNorm[:, : args.regressderivs + 1],
-                fitcoeff[:, : args.regressderivs + 1],
-                movingsignal,
-                lagtc,
-                filtereddata,
-                LGR,
-                TimingLGR,
-                threshval,
-                args.saveminimumsLFOfiltfiles,
-                nprocs_makelaggedtcs=args.nprocs,
-                nprocs_regressionfilt=args.nprocs,
-                regressderivs=args.regressderivs,
-                showprogressbar=args.showprogressbar,
-                debug=args.debug,
+            voxelsprocessed_regressionfilt, regressorset, evset = (
+                tide_regressfrommaps.regressfrommaps(
+                    fmri_data_valid,
+                    validvoxels,
+                    initial_fmri_x,
+                    lagstouse_valid,
+                    corrmask_valid,
+                    genlagtc,
+                    mode,
+                    outputname,
+                    oversamptr,
+                    sLFOfitmean,
+                    rvalue,
+                    r2value,
+                    fitNorm[:, : args.regressderivs + 1],
+                    fitcoeff[:, : args.regressderivs + 1],
+                    movingsignal,
+                    lagtc,
+                    filtereddata,
+                    LGR,
+                    TimingLGR,
+                    threshval,
+                    args.saveminimumsLFOfiltfiles,
+                    nprocs_makelaggedtcs=args.nprocs,
+                    nprocs_regressionfilt=args.nprocs,
+                    regressderivs=args.regressderivs,
+                    showprogressbar=args.showprogressbar,
+                    debug=args.debug,
+                )
             )
             TimingLGR.info(
                 "GLM for maxcorralt calculation done",
@@ -1241,7 +1378,6 @@ def retroregress(args):
             debug=args.debug,
         )
 
-
     # write the runoptions file
     print("writing runoptions")
     if args.refinedelay:

{rapidtide-3.0.2.dist-info → rapidtide-3.0.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rapidtide
-Version: 3.0.2
+Version: 3.0.3
 Summary: Tools for performing correlation analysis on fMRI data.
 Author: Taylor Salo, Daniel M. Drucker, Ph.D., Jeffrey N Stout, Yaroslav O. Halchenko, Derek Monroe
 Author-email: "Blaise deB. Frederick" <blaise.frederick@gmail.com>