rapidtide 3.0.1__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/regressfrommaps.py

@@ -53,6 +53,7 @@ def regressfrommaps(
     mp_chunksize=50000,
     showprogressbar=True,
     alwaysmultiproc=False,
+    saveEVsandquit=False,
     debug=False,
 ):
     if debug:
@@ -107,12 +108,6 @@ def regressfrommaps(
             },
         )
 
-    # and do the filtering
-    if LGR is not None:
-        LGR.info("Start filtering operation")
-    if TimingLGR is not None:
-        TimingLGR.info("Start filtering operation")
-
     if regressderivs > 0:
         if debug:
             print(f"adding derivatives up to order {regressderivs} prior to regression")
@@ -126,9 +121,19 @@ def regressfrommaps(
             print(f"using raw lagged regressors for regression")
         regressorset = lagtc
         evset = rt_floatset(genlagtc.yfromx(initial_fmri_x))
-
     if debug:
         print(f"{regressorset.shape=}")
+
+    if saveEVsandquit:
+        return 0, regressorset, evset
+
+    # now do the filtering
+    if LGR is not None:
+        LGR.info("Start filtering operation")
+    if TimingLGR is not None:
+        TimingLGR.info("Start filtering operation")
+
+
     voxelsprocessed_regressionfilt = tide_linfitfiltpass.linfitfiltpass(
         numvalidspatiallocs,
         fmri_data_valid,