Rapidtide is a suite of Python programs used to model, characterize, visualize, and remove time varying, physiological blood signals from fMRI and fNIRS datasets. The primary workhorses of the package are the rapidtide program, which characterizes bulk blood flow, and happy, which focusses on the cardiac band.
Full documentation is at: http://rapidtide.readthedocs.io/en/latest/
|PyPi Latest Version| |PyPi - Python Versions| |License| |Documentation Status| |CircleCI| |Coverage| |DOI| |Funded by NIH|
Rapidtide is also the name of the first program in the package, which is used to perform rapid time delay analysis on functional imaging data to find time lagged correlations between the voxelwise time series and other time series, primarily in the LFO band.
Why do I want to know about time lagged correlations?
This comes out of work by our group (The Opto-Magnetic group at McLean
Hospital - http://www.nirs-fmri.net) looking at the correlations between
neuroimaging data (fMRI) and NIRS data recorded simultaneously, either
in the brain or the periphery. We found that a large fraction of the
\"noise\" we found at low frequency in fMRI data was due to real,
random[*] fluctuations of blood oxygenation and volume (both of which
affect the intensity of BOLD fMRI images) in the blood passing through
the brain. More interestingly, because these characteristics of blood
move with the blood itself, this gives you a way to determine blood
arrival time at any location in the brain. This is interesting in and of
itself, but also, this gives you a method for optimally modelling (and
removing) in band physiological noise from fMRI data (see references
below).
After working with this for several years we\'ve also found that you
don\'t need to used simultaneous NIRS to find this blood borne signal -
you can get it from blood rich BOLD voxels for example in the superior
sagittal sinus, or bootstrap it out of the global mean signal in the
BOLD data. You can also track exogenously applied waveforms, such as
hypercarbic and/or hyperoxic gas challenges to really boost your signal
to noise. So there are lots of times when you might want to do this type
of correlation analysis.
As an aside, some of these tools are just generally useful for looking
at correlations between timecourses from other sources – for example
doing PPI, or even some seed based analyses.
[*] \"random\" in this context means \"determined by something we don\'t
have any information about\" - maybe EtCO2 variation, or sympathetic
nervous system activity - so not really random.
Correlation analysis is easy - why use this package?The simple answer is \"correlation analysis is easy, but using a prewritten package that handles file I/O, filtering, resampling, windowing, and the rest for you is even easier\". A slightly more complex answer is that while correlation analysis is pretty easy to do, it\'s hard to do right; there are lots and lots of ways to do it incorrectly. Fortunately, I\'ve made most of those mistakes for you over the last 8 years, and corrected my code accordingly. So rather than repeat my boring mistakes, why not make new, interesting mistakes? Explore your own, unique chunk of wrongspace…
More recently, inspired by Henning Voss\' paper on hypersampling of cardiac signals in fMRI, we developed a method to extract and clean cardiac waveforms from fMRI data, even when the fMRI TR is far too long to properly sample cardiac waveforms. This cardiac waveform can then be to track the pulsatile cardiac pressure wave through the brain in somewhat the same way that we track the LFO signals. Among other things, this allows you to get cardiac waveforms during scans even when either 1) you didn\'t use a plethysmograph, or 2) you did, but the recording was of poor quality, which happens more than you might think.
What does \"happy\" have to do with any of this?
As to why happy is part of rapidtide, that\'s partially for practical reasons (the
libraries in rapidtide have an awful lot of code that is reused in happy), and
partially thematically - rapidtide has evolved from a \"let\'s look at low
frequency signals in fMRI data\" package to a \"let\'s look at everything in
fMRI data EXCEPT neuronal activation\", so happy fits right in.
Why are you releasing this package?
===================================
For a number of reasons.
- I want people to use it! I think if it were easier for people to do
time delay analysis, they\'d be more likely to do it. I don\'t have
enough time or people in my group to do every experiment that I think
would be interesting, so I\'m hoping other people will, so I can read
their papers and learn interesting things.
- It\'s the right way to do science – I can say lots of things, but if
nobody can replicate my results, nobody will believe it (we\'ve gotten
that a lot, because some of the implications of what we\'ve seen in
resting state data can be a little uncomfortable). We\'ve reached a
stage in fMRI where getting from data to results involves a huge
amount of processing, so part of confirming results involves being
able to see how the data were processed. If you had to do everything
from scratch, you\'d never even try to confirm anybody\'s results.
- In any complicated processing scheme, it\'s quite possible (or in my
case, likely) to make dumb mistakes, either coding errors or
conceptual errors, and I almost certainly have made some (although
hopefully the worst ones have been dealt with at this point). More
users and more eyes on the code make it more likely that they will be
found. As much as I\'m queasy about somebody potentially finding a
mistake in my code, I\'d rather that they did so, so I can fix it[‡].
- It\'s giving back to the community. I benefit from the generosity of a
lot of authors who have made the open source tools I use for work and
play, so I figure I can pony up too.
[‡] or better yet, you, empowered user, can fix it, and push back a fix
that benefits everybody…
Stability, etc.
===============
This is an evolving code base. I\'m constantly tinkering with it. That
said, now that I\'ve sent this off into to the world, I\'m being somewhat
more responsible about locking down stable release points. In between
releases, however, I\'ll be messing with things, although for the most
part this will be restricted to the dev branch.
**It\'s very possible that at any given time the dev branch will be very broken,
so stay away from it unless you have a good reason to be using it.**
I\'ve finally become a little more modern and started
adding automated testing, so as time goes by hopefully the \"in between\"
releases will be somewhat more reliable. That said, my tests routinely fail, even
when things actually work. Probably should deal with that. Check back often for exciting
new features and bug fixes!
Python version compatibility
============================
I switched over a while ago to using Python 3 as my daily driver, so I know
that everything works there. However, I know that a lot of people can\'t
or won\'t switch from Python 2x, so I kept Python 2.7 compatibility for
quite some time.
That said, the writing is on the wall, and since I depend on a number of
packages that have dropped Python 2.x support, as of 2.0, so has rapidtide. However,
as of version 1.9.0 I\'m also releasing the code in a docker
container (fredericklab/rapidtide), which has everything nicely installed in
a fully configured Python 3 environment, so there\'s really no need for me continue 2.x
support. So now it's f-strings all the way, kids!
Ok, I\'m sold. What\'s in here?
===============================
- **rapidtide** - This is the heart of the package - this is the
workhorse program that will determine the time lagged correlations
between all the voxels in a NIFTI file and a temporal \"probe\"
regressor (which can come from a number of places, including the data
itself) - it rapidly determines time delays… There are a truly
bewildering array of options, and just about everything can be
adjusted, however I\'ve tried to pick a good set of default options
for the most basic processing to get you going. At a minimum, it
requires a 4D NIFTI file as input, and a root name for all of the
output files. It generates a number of 3D NIFTI file maps of various
parameters (lag time of maximum correlation, maximum correlation
value, a mask of which voxels have valid fits, etc.) and some text
files with useful information (significance thresholds, processing
timing information, a list of values of configurable options).
- **happy** - This is a companion to rapidtide that focusses on cardiac signals.
happy does three things - it attempts to determine the cardiac
waveform over the time course of an fMRI dataset using slice
selective averaging of fully unprocessed fMRI data. It also
cleans up this initial estimate using a deep learning filter to
infer what the simultaneously recorded plethysmogram would be.
Finally, it uses either the derived or a supplied plethysmogram
signal to construct a cardiac pulsation map over a single
cycle of the cardiac waveform, a la Voss.
- **showxcorrx** - Like rapidtide, but for single time courses. Takes
two text files as input, calculates and displays the time lagged
cross correlation between them, fits the maximum time lag, and
estimates the significance of the correlation. It has a range of
filtering, windowing, and correlation options.
- **rapidtide2x_legacy**, **happy_legacy**, **showxcorr_legacy** - The
older versions of the similarly named programs. These use the old calling
conventions, for compatibility with older workflows. These will go away
eventually, and they don't really get updates or bugfixes, so if you're
using them, change to the new ones, and if you're not using them, don't.
- **rapidtide2std** - This is a utility for registering rapidtide
output maps to standard coordinates. It\'s usually much faster to run
rapidtide in native space then transform afterwards to MNI152 space.
NB: this will only work if you have a working FSL installation.
- **happy2std** - Guess.
- **showtc** - A very simple command line utility that takes timecourses from text
files and plots the data in it in a matplotlib window. That\'s it. A
good tool for quickly seeing what\'s in a file. Has a number of options to
make the plot prettier.
- **showxy** - Another simple command line utility that displays the
the data contained in text files containing whitespace separated x-y pairs.
- **showhist** - Another simple command line utility that displays the
histograms generated by rapidtide.
- **resamp1tc** - takes an input text file at some sample rate and
outputs a text file resampled to the specified sample rate.
- **resamplenifti** - takes an input nifti file at some TR and outputs
a nifti file resampled to the specified TR.
- **tidepool** - This is a GUI tool for displaying all of
the various maps and timecourses generated by rapidtide in one place, overlaid on
an anatomic image. This makes it a bit easier to see how all the maps
are related to one another, how the probe regressor evolves over the run, and the
effect of the filtering parameters. To use it, launch tidepool from the
command line, and then select a lag time map - tidepool will figure
out the root name and pull in all of the other associated data. Works
in native or standard space.
Financial Support
=================
This code base is being developed and supported by grants from the US
NIH (`1R01 NS097512 <http://grantome.com/grant/NIH/R01-NS097512-02>`__, RF1 MH130637-01)
.. |PyPi Latest Version| image:: https://img.shields.io/pypi/v/rapidtide.svg
:target: https://pypi.python.org/pypi/rapidtide/
.. |PyPi - Python Versions| image:: https://img.shields.io/pypi/pyversions/rapidtide.svg
:target: https://pypi.python.org/pypi/rapidtide/
.. |License| image:: https://img.shields.io/badge/License-Apache%202.0-blue.svg
:target: https://opensource.org/licenses/Apache-2.0
.. |Documentation Status| image:: https://readthedocs.org/projects/rapidtide/badge/?version=stable
:target: http://rapidtide.readthedocs.io/en/stable/?badge=stable
.. |CircleCI| image:: https://circleci.com/gh/bbfrederick/rapidtide.svg?branch=main&style=shield
:target: https://circleci.com/gh/bbfrederick/rapidtide
.. |Coverage| image:: https://codecov.io/gh/bbfrederick/rapidtide/branch/main/graph/badge.svg
:target: https://codecov.io/gh/bbfrederick/rapidtide
.. |DOI| image:: https://zenodo.org/badge/DOI/10.5281/zenodo.814990.svg
:target: https://doi.org/10.5281/zenodo.814990
.. |Funded by NIH| image:: https://img.shields.io/badge/NIH-RF1--MH130637--01-yellowgreen.svg
:target: https://reporter.nih.gov/project-details/10509534