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

rapidtide/maskutil.py

@@ -21,8 +21,10 @@ import logging
 
 import numpy as np
 from nilearn import masking
+from sklearn.decomposition import PCA
 
 import rapidtide.io as tide_io
+import rapidtide.miscmath as tide_math
 import rapidtide.stats as tide_stats
 
 LGR = logging.getLogger("GENERAL")
@@ -67,8 +69,16 @@ def readamask(
     thresh=None,
     maskname="the",
     tolerance=1.0e-3,
+    debug=False,
 ):
     LGR.debug(f"readamask called with filename: {maskfilename} vals: {valslist}")
+    if debug:
+        print("getmaskset:")
+        print(f"{maskname=}")
+        print(f"\tincludefilename={maskfilename}")
+        print(f"\tincludevals={valslist}")
+        print(f"\t{istext=}")
+        print(f"\t{tolerance=}")
     if istext:
         maskarray = tide_io.readvecs(maskfilename).astype("uint16")
         theshape = np.shape(maskarray)
@@ -109,11 +119,24 @@ def getmaskset(
     extramaskthresh=0.1,
     istext=False,
     tolerance=1.0e-3,
+    debug=False,
 ):
     internalincludemask = None
     internalexcludemask = None
     internalextramask = None
 
+    if debug:
+        print("getmaskset:")
+        print(f"{maskname=}")
+        print(f"\t{includename=}")
+        print(f"\t{includevals=}")
+        print(f"\t{excludename=}")
+        print(f"\t{excludevals=}")
+        print(f"\t{istext=}")
+        print(f"\t{tolerance=}")
+        print(f"\t{extramask=}")
+        print(f"\t{extramaskthresh=}")
+
     if includename is not None:
         LGR.info(f"constructing {maskname} include mask")
         theincludemask = readamask(
@@ -178,3 +201,124 @@ def getmaskset(
                 )
 
     return internalincludemask, internalexcludemask, internalextramask
+
+
+def getregionsignal(
+    indata,
+    filter=None,
+    Fs=1.0,
+    includemask=None,
+    excludemask=None,
+    signalgenmethod="sum",
+    pcacomponents=0.8,
+    signame="global mean",
+    rt_floatset=np.float64,
+    debug=False,
+):
+    # Start with all voxels
+    themask = indata[:, 0] * 0 + 1
+
+    # modify the mask if needed
+    if includemask is not None:
+        themask = themask * includemask
+    if excludemask is not None:
+        themask = themask * (1 - excludemask)
+
+    # combine all the voxels using one of the three methods
+    globalmean = rt_floatset(indata[0, :])
+    thesize = np.shape(themask)
+    numvoxelsused = int(np.sum(np.where(themask > 0.0, 1, 0)))
+    selectedvoxels = indata[np.where(themask > 0.0), :][0]
+    if debug:
+        print(f"getregionsignal: {selectedvoxels.shape=}")
+    LGR.info(f"constructing global mean signal using {signalgenmethod}")
+    if signalgenmethod == "sum":
+        globalmean = np.mean(selectedvoxels, axis=0)
+        globalmean -= np.mean(globalmean)
+    elif signalgenmethod == "meanscale":
+        themean = np.mean(indata, axis=1)
+        for vox in range(0, thesize[0]):
+            if themask[vox] > 0.0:
+                if themean[vox] != 0.0:
+                    globalmean += indata[vox, :] / themean[vox] - 1.0
+    elif signalgenmethod == "pca":
+        themean = np.mean(indata, axis=1)
+        thevar = np.var(indata, axis=1)
+        scaledvoxels = selectedvoxels * 0.0
+        for vox in range(0, selectedvoxels.shape[0]):
+            scaledvoxels[vox, :] = selectedvoxels[vox, :] - themean[vox]
+            if thevar[vox] > 0.0:
+                scaledvoxels[vox, :] = selectedvoxels[vox, :] / thevar[vox]
+        try:
+            thefit = PCA(n_components=pcacomponents).fit(np.transpose(scaledvoxels))
+        except ValueError:
+            if pcacomponents == "mle":
+                LGR.warning("mle estimation failed - falling back to pcacomponents=0.8")
+                thefit = PCA(n_components=0.8).fit(np.transpose(scaledvoxels))
+            else:
+                raise ValueError("unhandled math exception in PCA refinement - exiting")
+
+        varex = 100.0 * np.cumsum(thefit.explained_variance_ratio_)[len(thefit.components_) - 1]
+        thetransform = thefit.transform(np.transpose(scaledvoxels))
+        if debug:
+            print(f"getregionsignal: {thetransform.shape=}")
+        globalmean = np.mean(thetransform, axis=0)
+        globalmean -= np.mean(globalmean)
+        if debug:
+            print(f"getregionsignal: {varex=}")
+        LGR.info(
+            f"Using {len(thefit.components_)} component(s), accounting for "
+            f"{varex:.2f}% of the variance"
+        )
+    elif signalgenmethod == "random":
+        globalmean = np.random.standard_normal(size=len(globalmean))
+    else:
+        raise ValueError(f"illegal signal generation method: {signalgenmethod}")
+    LGR.info(f"used {numvoxelsused} voxels to calculate {signame} signal")
+    if filter is not None:
+        globalmean = filter.apply(Fs, globalmean)
+    if debug:
+        print(f"getregionsignal: {globalmean=}")
+    return tide_math.stdnormalize(globalmean), themask
+
+
+def saveregionaltimeseries(
+    tcdesc,
+    tcname,
+    fmridata,
+    includemask,
+    fmrifreq,
+    outputname,
+    filter=None,
+    initfile=False,
+    excludemask=None,
+    filedesc="regional",
+    suffix="",
+    signalgenmethod="sum",
+    pcacomponents=0.8,
+    rt_floatset=np.float64,
+    debug=False,
+):
+    thetimecourse, themask = getregionsignal(
+        fmridata,
+        filter=filter,
+        Fs=fmrifreq,
+        includemask=includemask,
+        excludemask=excludemask,
+        signalgenmethod=signalgenmethod,
+        pcacomponents=pcacomponents,
+        signame=tcdesc,
+        rt_floatset=rt_floatset,
+        debug=debug,
+    )
+    tide_io.writebidstsv(
+        f"{outputname}_desc-{filedesc}_timeseries",
+        thetimecourse,
+        fmrifreq,
+        columns=[f"{tcname}{suffix}"],
+        extraheaderinfo={
+            "Description": "Regional timecourse averages",
+        },
+        append=(not initfile),
+    )
+    return thetimecourse, themask

rapidtide/refinedelay.py

@@ -110,7 +110,6 @@ def trainratiotooffset(
         "alwaysmultiproc": False,
         "focaldebug": debug,
         "fmrifreq": 1.0 / sampletime,
-        "textio": False,
     }
 
     if trainlagmax - trainlagmin > 0.0:
@@ -233,7 +232,7 @@ def trainratiotooffset(
         funcoffsets.append(trainoffsets[whichoffset] + 0.0)
     maplimits = (xaxis[0], xaxis[-1])
 
-    if outputlevel != "min":
+    if outputlevel != "min" and outputlevel != "onlyregressors":
         resampaxis = np.linspace(xaxis[0], xaxis[-1], num=len(xaxis), endpoint=True)
         outputfuncs = np.zeros((resampaxis.size, numoffsets), dtype=float)
         colnames = []
@@ -429,8 +428,7 @@ def filterderivratios(
     thedims,
     patchthresh=3.0,
     gausssigma=0,
-    fileiscifti=False,
-    textio=False,
+    filetype="nifti",
     rt_floattype="float64",
     verbose=True,
     debug=False,
@@ -448,8 +446,7 @@ def filterderivratios(
         print(f"MAD of regression fit derivative ratios = {themad}")
     outmaparray, internalspaceshape = tide_io.makedestarray(
         nativespaceshape,
-        textio=textio,
-        fileiscifti=fileiscifti,
+        filetype=filetype,
         rt_floattype=rt_floattype,
     )
     mappedregressderivratios = tide_io.populatemap(
@@ -459,7 +456,7 @@ def filterderivratios(
         outmaparray,
         debug=debug,
     )
-    if textio or fileiscifti:
+    if filetype != "nifti":
         medfilt = regressderivratios
         filteredarray = regressderivratios
     else:

rapidtide/tests/cleanposttest

@@ -17,5 +17,4 @@
 #
 
 rm tmp/*
-#rm testdata/*
 rm .coveragerc.*

rapidtide/tests/test_cleanregressor.py

@@ -0,0 +1,185 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+#
+#   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.
+#   You may obtain a copy of the License at
+#
+#       http://www.apache.org/licenses/LICENSE-2.0
+#
+#   Unless required by applicable law or agreed to in writing, software
+#   distributed under the License is distributed on an "AS IS" BASIS,
+#   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#   See the License for the specific language governing permissions and
+#   limitations under the License.
+#
+#
+import os
+
+import matplotlib as mpl
+import numpy as np
+
+import rapidtide.filter as tide_filt
+import rapidtide.helper_classes as tide_classes
+import rapidtide.miscmath as tide_math
+import rapidtide.resample as tide_resample
+import rapidtide.workflows.cleanregressor as tide_cleanregressor
+from rapidtide.tests.utils import get_examples_path, get_test_temp_path, mse
+
+
+def test_cleanregressor(debug=False, local=False, displayplots=False):
+    # set input and output directories
+    if local:
+        exampleroot = "../data/examples/src"
+        testtemproot = "./tmp"
+    else:
+        exampleroot = get_examples_path()
+        testtemproot = get_test_temp_path()
+
+    outputname = os.path.join(testtemproot, "cleanregressortest")
+    thepass = 1
+    padtrs = 30
+    fmrifreq = 1.0
+    oversampfac = 2
+    oversampfreq = oversampfac * fmrifreq
+    theprefilter = tide_filt.NoncausalFilter("lfo")
+    lagmin = -30
+    lagmax = 30
+    lagmininpts = int((lagmin * oversampfreq) - 0.5)
+    lagmaxinpts = int((lagmax * oversampfreq) + 0.5)
+    lagmod = 1000.0
+    noiseamp = 0.25
+    detrendorder = 3
+    windowfunc = "hamming"
+
+    tclen = 500
+    osvalidsimcalcstart = 0
+    osvalidsimcalcend = tclen * oversampfac
+
+    theCorrelator = tide_classes.Correlator(
+        Fs=oversampfreq,
+        ncprefilter=theprefilter,
+        detrendorder=1,
+        windowfunc="hamming",
+        corrweighting="phat",
+    )
+    theFitter = tide_classes.SimilarityFunctionFitter(
+        lagmod=lagmod,
+        lagmin=lagmin,
+        lagmax=lagmax,
+        debug=debug,
+        allowhighfitamps=True,
+        enforcethresh=False,
+        zerooutbadfit=False,
+    )
+
+    # make a reference timecourse
+    rng = np.random.default_rng(seed=1234)
+    basewave = theprefilter.apply(fmrifreq, rng.normal(loc=0.0, scale=1.0, size=tclen))
+    noisewave = rng.normal(loc=0.0, scale=noiseamp, size=tclen)
+    theparamsets = [
+        [2.0, 0.0, False, 0],
+        [2.5, 0.8, True, 0],
+        [5.0, 0.5, True, 0],
+        [7.5, 0.25, True, 100],
+        [10.0, 0.1, True, 0],
+    ]
+    for paramset in theparamsets:
+        echotime = paramset[0]
+        echoamp = paramset[1]
+        check_autocorrelation = paramset[2]
+        osvalidsimcalcstart = paramset[3]
+        if debug:
+            print(
+                "**********Start******************************************************************"
+            )
+            print(f"{echotime=}, {echoamp=}, {check_autocorrelation=}, {osvalidsimcalcstart=}")
+            print(
+                "*********************************************************************************"
+            )
+        theechotc, dummy, dummy, dummy = tide_resample.timeshift(
+            basewave, echotime * oversampfreq, padtrs, doplot=displayplots, debug=debug
+        )
+        resampnonosref_y = basewave + echoamp * theechotc + noisewave
+        resampref_y = tide_resample.upsample(resampnonosref_y, fmrifreq, oversampfreq)
+        theCorrelator.setreftc(resampnonosref_y)
+        referencetc = tide_math.corrnormalize(
+            resampref_y[osvalidsimcalcstart:],
+            detrendorder=detrendorder,
+            windowfunc=windowfunc,
+        )
+
+        resampref_y = tide_resample.upsample(resampnonosref_y, fmrifreq, oversampfreq)
+
+        (
+            cleaned_resampref_y,
+            cleaned_referencetc,
+            cleaned_nonosreferencetc,
+            despeckle_thresh,
+            sidelobeamp,
+            sidelobetime,
+            lagmod,
+            acwidth,
+            absmaxsigma,
+        ) = tide_cleanregressor.cleanregressor(
+            outputname,
+            thepass,
+            referencetc,
+            resampref_y,
+            resampnonosref_y,
+            fmrifreq,
+            oversampfreq,
+            osvalidsimcalcstart,
+            osvalidsimcalcend,
+            lagmininpts,
+            lagmaxinpts,
+            theFitter,
+            theCorrelator,
+            lagmin,
+            lagmax,
+            LGR=None,
+            check_autocorrelation=check_autocorrelation,
+            fix_autocorrelation=True,
+            despeckle_thresh=5.0,
+            lthreshval=0.0,
+            fixdelay=False,
+            detrendorder=detrendorder,
+            windowfunc=windowfunc,
+            respdelete=False,
+            displayplots=displayplots,
+            debug=debug,
+            rt_floattype="float64",
+            rt_floatset=np.float64,
+        )
+        print(f"\t{len(referencetc)=}")
+        print(f"\t{len(resampref_y)=}")
+        print(f"\t{len(resampnonosref_y)=}")
+        print(f"\t{len(cleaned_resampref_y)=}")
+        print(f"\t{len(cleaned_referencetc)=}")
+        print(f"\t{len(cleaned_nonosreferencetc)=}")
+        print(f"\t{check_autocorrelation=}")
+        print(f"\t{despeckle_thresh=}")
+        print(f"\t{sidelobeamp=}")
+        print(f"\t{sidelobetime=}")
+        print(f"\t{lagmod=}")
+        print(f"\t{acwidth=}")
+        print(f"\t{absmaxsigma=}")
+        assert len(referencetc) == len(cleaned_referencetc)
+        assert len(resampref_y) == len(cleaned_resampref_y)
+        assert len(resampnonosref_y) == len(cleaned_nonosreferencetc)
+
+        if debug:
+            print(
+                "*********************************************************************************"
+            )
+            print(f"{echotime=}, {echoamp=}, {check_autocorrelation=}, {osvalidsimcalcstart=}")
+            print(
+                "**************End****************************************************************"
+            )
+
+
+if __name__ == "__main__":
+    mpl.use("TkAgg")
+    test_cleanregressor(debug=True, local=True, displayplots=True)

rapidtide/tests/test_fullrunrapidtide_v1.py

@@ -23,6 +23,7 @@ import matplotlib as mpl
 import rapidtide.qualitycheck as rapidtide_quality
 import rapidtide.workflows.rapidtide as rapidtide_workflow
 import rapidtide.workflows.rapidtide_parser as rapidtide_parser
+import rapidtide.workflows.retroregress as rapidtide_retroregress
 from rapidtide.tests.utils import get_examples_path, get_test_temp_path
 
 
@@ -56,6 +57,8 @@ def test_fullrunrapidtide_v1(debug=False, local=False, displayplots=False):
     rapidtide_workflow.rapidtide_main(rapidtide_parser.process_args(inputargs=inputargs))
     rapidtide_quality.qualitycheck(os.path.join(testtemproot, "sub-RAPIDTIDETEST1"))
 
+
+    # test fixval
     inputargs = [
         os.path.join(exampleroot, "sub-RAPIDTIDETEST.nii.gz"),
         os.path.join(testtemproot, "sub-RAPIDTIDETEST1_fixval"),
@@ -77,6 +80,7 @@ def test_fullrunrapidtide_v1(debug=False, local=False, displayplots=False):
     ]
     rapidtide_workflow.rapidtide_main(rapidtide_parser.process_args(inputargs=inputargs))
 
+    # test fixmap
     inputargs = [
         os.path.join(exampleroot, "sub-RAPIDTIDETEST.nii.gz"),
         os.path.join(testtemproot, "sub-RAPIDTIDETEST1_fixmap"),

rapidtide/tests/test_fullrunrapidtide_v3.py

@@ -23,6 +23,7 @@ import matplotlib as mpl
 import rapidtide.workflows.rapidtide as rapidtide_workflow
 import rapidtide.workflows.rapidtide_parser as rapidtide_parser
 from rapidtide.tests.utils import get_examples_path, get_test_temp_path
+import rapidtide.workflows.retroregress as rapidtide_retroregress
 
 
 def test_fullrunrapidtide_v3(debug=False, local=False, displayplots=False):
@@ -76,6 +77,15 @@ def test_fullrunrapidtide_v3(debug=False, local=False, displayplots=False):
     #    "--cleanrefined",
     rapidtide_workflow.rapidtide_main(rapidtide_parser.process_args(inputargs=inputargs))
 
+    inputargs = [
+        os.path.join(exampleroot, "sub-RAPIDTIDETEST.nii.gz"),
+        os.path.join(testtemproot, "sub-RAPIDTIDETEST3"),
+        "--alternateoutput",
+        os.path.join(testtemproot, "onlyregressors"),
+        "--outputlevel",
+        "onlyregressors",
+    ]
+    rapidtide_retroregress.retroregress(rapidtide_retroregress.process_args(inputargs=inputargs))
 
 if __name__ == "__main__":
     mpl.use("TkAgg")

rapidtide/tests/test_fullrunrapidtide_v6.py

@@ -17,7 +17,6 @@
 #
 #
 import os
-import subprocess
 
 import matplotlib as mpl
 

rapidtide/tests/test_fullrunrapidtide_v7.py

@@ -0,0 +1,114 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+#
+#   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.
+#   You may obtain a copy of the License at
+#
+#       http://www.apache.org/licenses/LICENSE-2.0
+#
+#   Unless required by applicable law or agreed to in writing, software
+#   distributed under the License is distributed on an "AS IS" BASIS,
+#   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#   See the License for the specific language governing permissions and
+#   limitations under the License.
+#
+#
+import os
+
+import matplotlib as mpl
+import numpy as np
+
+import rapidtide.io as tide_io
+import rapidtide.workflows.rapidtide as rapidtide_workflow
+import rapidtide.workflows.rapidtide_parser as rapidtide_parser
+import rapidtide.workflows.retroregress as rapidtide_retroregress
+from rapidtide.tests.utils import get_examples_path, get_test_temp_path, mse
+
+
+def test_fullrunrapidtide_v7(debug=False, local=False, displayplots=False):
+    # set input and output directories
+    if local:
+        exampleroot = "../data/examples/src"
+        testtemproot = "./tmp"
+    else:
+        exampleroot = get_examples_path()
+        testtemproot = get_test_temp_path()
+
+    # test anatomic masks
+    inputargs = [
+        os.path.join(exampleroot, "sub-RAPIDTIDETEST.nii.gz"),
+        os.path.join(testtemproot, "sub-RAPIDTIDETEST_seg"),
+        "--nprocs",
+        "-1",
+        "--passes",
+        "3",
+        "--brainmask",
+        os.path.join(exampleroot, "sub-RAPIDTIDETEST_brainmask.nii.gz"),
+        "--graymattermask",
+        os.path.join(exampleroot, "sub-RAPIDTIDETEST_synthseg.nii.gz:SSEG_GRAY"),
+        "--whitemattermask",
+        os.path.join(exampleroot, "sub-RAPIDTIDETEST_synthseg.nii.gz:SSEG_WHITE"),
+        "--csfmask",
+        os.path.join(exampleroot, "sub-RAPIDTIDETEST_synthseg.nii.gz:SSEG_CSF"),
+    ]
+    rapidtide_workflow.rapidtide_main(rapidtide_parser.process_args(inputargs=inputargs))
+
+    inputargs = [
+        os.path.join(exampleroot, "sub-RAPIDTIDETEST.nii.gz"),
+        os.path.join(testtemproot, "sub-RAPIDTIDETEST_seg"),
+        "--alternateoutput",
+        os.path.join(testtemproot, "segtest"),
+        "--nprocs",
+        "-1",
+        "--outputlevel",
+        "max",
+    ]
+    rapidtide_retroregress.retroregress(rapidtide_retroregress.process_args(inputargs=inputargs))
+
+    inputargs = [
+        os.path.join(exampleroot, "sub-RAPIDTIDETEST.nii.gz"),
+        os.path.join(testtemproot, "sub-RAPIDTIDETEST_seg"),
+        "--alternateoutput",
+        os.path.join(testtemproot, "regressoronly"),
+        "--nprocs",
+        "-1",
+        "--outputlevel",
+        "onlyregressors",
+    ]
+    rapidtide_retroregress.retroregress(rapidtide_retroregress.process_args(inputargs=inputargs))
+
+    # check to see that rapidtide and retroregress output match
+    msethresh = 1e-6
+    aethresh = 2
+    tclist = ["brain", "GM", "WM", "CSF"]
+    for timecourse in tclist:
+        infilespec = os.path.join(
+            testtemproot,
+            f"sub-RAPIDTIDETEST_seg_desc-regionalpostfilter_timeseries.json:{timecourse}",
+        )
+        insamplerate, instarttime, incolumns, indata, incompressed, infiletype = (
+            tide_io.readvectorsfromtextfile(infilespec, onecol=True, debug=debug)
+        )
+        outfilespec = os.path.join(
+            testtemproot, f"segtest_desc-regionalpostfilter_timeseries.json:{timecourse}"
+        )
+        outsamplerate, outstarttime, outcolumns, outdata, outcompressed, outfiletype = (
+            tide_io.readvectorsfromtextfile(outfilespec, onecol=True, debug=debug)
+        )
+        assert insamplerate == outsamplerate
+        assert instarttime == outstarttime
+        assert incompressed == outcompressed
+        assert infiletype == outfiletype
+        assert incolumns == outcolumns
+        assert indata.shape == outdata.shape
+        assert indata.shape[0] == indata.shape[0]
+        assert mse(indata, outdata) < msethresh
+        np.testing.assert_almost_equal(indata, outdata, aethresh)
+
+
+if __name__ == "__main__":
+    mpl.use("TkAgg")
+    test_fullrunrapidtide_v7(debug=True, local=True, displayplots=True)