rapidtide 3.0.2__tar.gz → 3.0.3__tar.gz

{rapidtide-3.0.2 → rapidtide-3.0.3}/CHANGELOG.md

@@ -1,8 +1,18 @@
 # Release history
 
+## Version 3.0.3 (5/4/25)
+* (rapidtide, retroregress) If you supply a brain, GM, WM, or CSF mask, rapidtide extracts the matching timecourse from the mask at startup, and after filtering, if it's done.  retroregress extracts the timecourses after filtering.
+* (rapidtide) Fixed mask logic when gray matter mask is provided.
+* (rapidtide) Fixed a crash when ``--acfix`` is selected and a bad sidelobe is encountered if the similarity calculation range is not the entire timecourse (THAT was hard to pin down...).
+* (rapidtide, tidepool) Fixed a serious cosmetic bug in corrout files introduced in v3.0.2 - teoffset was not being set properly by rapidtide, so the tidepool similarity function display was very wrong.
+* (rapidtide) shiftedtcs file is now written during each pass if ``--saveintermediatemaps`` is set and ``--outputlevel`` is ``more`` or ``max`` (in response to a feature request).
+* (rapidtide) Added back the ability to have integral powers of the motion regressors.
+* (rapidtide) Added the ability to specify a CSF mask.
+
+
 ## Version 3.0.2 (4/28/25)
-* (rapidtide) Leaned harder into using the voxelData class, and beefed up its capabilities.
 * (retroregress) Added a new argument to ``--outputlevel``, ``onlyregressors``.  When selected, retroregress generates the voxel specific sLFO regressor(s), saves them, and exits.  This option exists so that you can use the rapidtide voxel specific sLFO regressors in an external processing routine such as XCP-D without extraneous data storage or processing time. 
+* (rapidtide) Leaned harder into using the voxelData class, and beefed up its capabilities.
 * (happy) Updated to use voxelData.
 * (happy) Moved phase projection to an external routine.
 * (documentation) Fixed a few more typos.

{rapidtide-3.0.2/rapidtide.egg-info → rapidtide-3.0.3}/PKG-INFO

@@ -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>

{rapidtide-3.0.2 → rapidtide-3.0.3}/rapidtide/calcsimfunc.py

@@ -69,6 +69,7 @@ def correlationpass(
     chunksize=1000,
     rt_floatset=np.float64,
     rt_floattype="float64",
+    debug=False,
 ):
     """
 
@@ -96,6 +97,8 @@ def correlationpass(
     -------
 
     """
+    if debug:
+        print(f"calling setreftc in calcsimfunc with length {len(referencetc)}")
     theCorrelator.setreftc(referencetc)
     theCorrelator.setlimits(lagmininpts, lagmaxinpts)
 

{rapidtide-3.0.2 → rapidtide-3.0.3}/rapidtide/correlate.py

@@ -86,11 +86,12 @@ def disablenumba():
 def check_autocorrelation(
     corrscale,
     thexcorr,
-    delta=0.1,
+    delta=0.05,
     acampthresh=0.1,
     aclagthresh=10.0,
     displayplots=False,
     detrendorder=1,
+    debug=False,
 ):
     """Check for autocorrelation in an array.
 
@@ -110,10 +111,23 @@ def check_autocorrelation(
     sidelobetime
     sidelobeamp
     """
+    if debug:
+        print("check_autocorrelation:")
+        print(f"delta: {delta}")
+        print(f"acampthresh: {acampthresh}")
+        print(f"aclagthresh: {aclagthresh}")
+        print(f"displayplots: {displayplots}")
     lookahead = 2
+    if displayplots:
+        print(f"check_autocorrelation: {displayplots=}")
+        plt.plot(corrscale, thexcorr)
+        plt.show()
     peaks = tide_fit.peakdetect(thexcorr, x_axis=corrscale, delta=delta, lookahead=lookahead)
     maxpeaks = np.asarray(peaks[0], dtype="float64")
     if len(peaks[0]) > 0:
+        if debug:
+            print(f"found {len(peaks[0])} peaks")
+            print(peaks)
         LGR.debug(peaks)
         zeropkindex = np.argmin(abs(maxpeaks[:, 0]))
         for i in range(zeropkindex + 1, maxpeaks.shape[0]):
@@ -155,6 +169,9 @@ def check_autocorrelation(
                     )
                     plt.show()
                 return sidelobetime, sidelobeamp
+    else:
+        if debug:
+            print("no peaks found")
     return None, None
 
 

rapidtide-3.0.3/rapidtide/data/examples/src/testfmri

@@ -0,0 +1,15 @@
+#!/bin/bash
+
+rapidtide \
+    --spatialfilt -1 \
+    --nprocs -1 \
+    --searchrange -5 20 \
+    --simcalcrange 50 -1 \
+    --outputlevel more \
+    --dofinalrefine \
+    --graymattermask sub-RAPIDTIDETEST_synthseg.nii.gz:SSEG_GRAY \
+    --brainmask sub-RAPIDTIDETEST_brainmask.nii.gz \
+    --whitemattermask sub-RAPIDTIDETEST_synthseg.nii.gz:SSEG_WHITE \
+    --csfmask sub-RAPIDTIDETEST_synthseg.nii.gz:SSEG_CSF \
+    sub-RAPIDTIDETEST.nii.gz \
+    ../dst/sub-RAPIDTIDETEST

{rapidtide-3.0.2 → rapidtide-3.0.3}/rapidtide/data/examples/src/testretro

@@ -1,10 +1,16 @@
 #!/bin/bash
 
 rapidtide \
+    --spatialfilt -1 \
     --nprocs -1 \
-    --passes 3 \
-    --outputlevel max \
-    --regressderivs 1 \
+    --searchrange -5 20 \
+    --simcalcrange 50 -1 \
+    --outputlevel more \
+    --dofinalrefine \
+    --graymattermask sub-RAPIDTIDETEST_synthseg.nii.gz:SSEG_GRAY \
+    --brainmask sub-RAPIDTIDETEST_brainmask.nii.gz \
+    --whitemattermask sub-RAPIDTIDETEST_synthseg.nii.gz:SSEG_WHITE \
+    --csfmask sub-RAPIDTIDETEST_synthseg.nii.gz:SSEG_CSF \
     sub-RAPIDTIDETEST.nii.gz \
     ../dst/sub-RAPIDTIDETEST
 
@@ -15,7 +21,7 @@ retroregress \
     ../dst/sub-RAPIDTIDETEST \
     --alternateoutput ../dst/specialtest \
     --nprocs -1 \
-    --outputlevel onlyregressors
+    --outputlevel normal
 
 #retroregress sub-RAPIDTIDETEST.nii.gz ../dst/sub-RAPIDTIDETEST --alternateoutput ../dst/0deriv_refined --nprocs -1 --regressderivs 0 --makepseudofile --outputlevel max --refinedelay --nofilterwithrefineddelay
 #retroregress sub-RAPIDTIDETEST.nii.gz ../dst/sub-RAPIDTIDETEST --alternateoutput ../dst/0deriv_refinedfit --nprocs -1 --regressderivs 0 --makepseudofile --outputlevel max --refinedelay

{rapidtide-3.0.2 → rapidtide-3.0.3}/rapidtide/helper_classes.py

@@ -310,7 +310,7 @@ class MutualInformationator(SimilarityFunctionator):
     def run(self, thetc, locs=None, trim=True, gettimeaxis=True):
         if len(thetc) != len(self.reftc):
             print(
-                "timecourses are of different sizes:",
+                "MutualInformationator: timecourses are of different sizes:",
                 len(thetc),
                 "!=",
                 len(self.reftc),
@@ -434,7 +434,7 @@ class Correlator(SimilarityFunctionator):
     def run(self, thetc, trim=True):
         if len(thetc) != len(self.reftc):
             print(
-                "timecourses are of different sizes:",
+                "Correlator: timecourses are of different sizes:",
                 len(thetc),
                 "!=",
                 len(self.reftc),
@@ -580,7 +580,7 @@ class Coherer:
     def run(self, thetc, trim=True, alt=False):
         if len(thetc) != len(self.reftc):
             print(
-                "timecourses are of different sizes:",
+                "Coherer: timecourses are of different sizes:",
                 len(thetc),
                 "!=",
                 len(self.reftc),
@@ -1076,7 +1076,7 @@ class SimilarityFunctionFitter:
                     maxval_init = 0.0
                     if self.debug:
                         print("bad initial amp:", maxval_init, "is less than 0.0")
-                if maxval_init > 1.0:
+                if (maxval_init > 1.0) and self.enforcethresh:
                     failreason |= self.FML_INITAMPHIGH
                     maxval_init = 1.0
                     if self.debug:

{rapidtide-3.0.2 → rapidtide-3.0.3}/rapidtide/io.py

@@ -1996,12 +1996,14 @@ def colspectolist(colspec, debug=False):
         ("APARC_CORTGRAY", "1000-1035,2000-2035"),
         ("APARC_GRAY", "8-13,17-20,26-28,47-56,58-60,96,97,1000-1035,2000-2035"),
         ("APARC_WHITE", "2,7,41,46,177,219,3000-3035,4000-4035,5001,5002"),
+        ("APARC_CSF", "4,5,14,15,24,31,43,44,63,72"),
         (
             "APARC_ALLBUTCSF",
             "2,7-13,17-20,26-28,41,46-56,58-60,96,97,177,219,1000-1035,2000-2035,3000-3035,4000-4035,5001,5002",
         ),
         ("SSEG_GRAY", "3,8,10-13,16-18,26,42,47,49-54,58"),
         ("SSEG_WHITE", "2,7,41,46"),
+        ("SSEG_CSF", "4,5,14,15,24,43,44"),
     )
     preprocessedranges = []
     for thisrange in theranges:

{rapidtide-3.0.2 → rapidtide-3.0.3}/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-3.0.3/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-3.0.2 → rapidtide-3.0.3}/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"),