The goal of ravetools
is to provide memory-efficient signal & image processing toolbox for intracranial Electroencephalography
. Highlighted features include:
-
Notch filter
(remove electrical line frequencies) -
Welch Periodogram
(averaged power over frequencies) -
Wavelet
(frequency-time decomposition) - 2D, 3D image convolution via
FFT
-
CT/MRI
toMRI
image alignment
Installation
The package is available on CRAN
. To install the compiled version, simply run:
install.packages("ravetools")
Installing the package from source requires installation of proper compilers and some C
libraries; see this document for details.
iEEG
preprocess pipeline
This is a basic example which shows you how to preprocess an iEEG
signal. The goal here is to:
- Plot diagnostic graphs to inspect channels
- Apply Notch filters to remove electrical line noise
- Frequency-time decomposition and show the power densities
* Channel referencing is not included
1. Generate toy examples:
library(ravetools)
# Generate 20 second data at 2000 Hz
time <- seq(0, 20, by = 1 / 2000)
signal <- sin( 120 * pi * time) +
sin(time * 20*pi) +
exp(-time^2) *
cos(time * 10*pi) +
rnorm(length(time))
diagnose_channel(signal, srate = 2000)
2. Apply Notch
filters and inspect Periodograms
## ------- Notch filter --------
signal2 <- notch_filter(signal, sample_rate = 2000)
diagnose_channel(signal, signal2, srate = 2000,
name = c("Raw", "Filtered"))
3. Frequency-time decomposition
Current version of ravetools
provides two approaches: Wavelet
and Multi-taper
. Wavelet
uses the Morlet wavelet
and obtains both amplitude and phase data, while Multi-taper
does not generate phase data. However, the amplitude obtained from Multi-taper
is smoother than Wavelet
.
Using Wavelet
:
## ---------- Wavelet -----------
coef <- morlet_wavelet(
signal2, freqs = seq(1, 100, by = 1),
srate = 2000, wave_num = c(2, 15))
amplitude <- 20 * log10(Mod(coef[]))
# For each frequency, decimate to 100 Hz
downsample_amp <- apply(amplitude, 2, decimate, q = 20)
downsample_time <- decimate(time, q = 20)
par(mfrow = c(1,1))
image(
z = downsample_amp,
x = downsample_time,
y = seq(1, 100, by = 1),
xlab = "Time (s)",
ylab = "Frequency (Hz)",
main = "Amplitude (dB)",
sub = "Wavelet at 2000 Hz, then down-sampled to 100 Hz",
col = matlab_palette()
)
Multi-taper
Alternatively you can use Multi-tapers
to obtain amplitude data. The algorithm is modified from source code here. Please credit them as well if you adopt this approach.
## ---------- Multitaper -----------
res <- multitaper(
data = signal2,
fs = 2000,
frequency_range = c(1, 100),
time_bandwidth = 1.5,
window_params = c(2, 0.01),
nfft = 100
)
par(mfrow = c(1,1))
image(
x = res$time,
y = res$frequency,
z = 10 * log10(res$spec),
xlab = "Time (s)",
ylab = 'Frequency (Hz)',
col = matlab_palette(),
main = "Amplitude (dB)"
)
Image alignment
ravetools
provides imaging co-registration via NiftyReg
(doi.org/10.1117/1.JMI.1.2.024003
). You can align CT
to MRI
, or MRI
(T2) to MRI
(T1). The method can be body rigid
, affine
, or non-linear
.
source <- system.file("extdata", "epi_t2.nii.gz", package="RNiftyReg")
target <- system.file("extdata", "flash_t1.nii.gz", package="RNiftyReg")
aligned <- register_volume(source, target, verbose = FALSE)
source_img <- aligned$source[[1]]
target_img <- aligned$target
aligned_img <- aligned$image
par(mfrow = c(2, 2), mar = c(0.1, 0.1, 3.1, 0.1))
pal <- grDevices::grey.colors(256, alpha = 1)
image(source_img[,,30], asp = 1, axes = FALSE,
col = pal, main = "Source image")
image(target_img[,,64], asp = 1, axes = FALSE,
col = pal, main = "Target image")
image(aligned_img[,,64], asp = 1, axes = FALSE,
col = pal, main = "Aligned image")
# bucket fill and calculate differences
aligned_img[is.nan(aligned_img) | aligned_img <= 1] <- 1
target_img[is.nan(target_img) | aligned_img <= 1] <- 1
diff <- abs(aligned_img / target_img - 1)
image(diff[,,64], asp = 1, axes = FALSE,
col = pal, main = "Percentage Difference")
References
To cite ravetools in publications use, please cite the RAVE
paper from Beauchamp's lab
: comprehensive
Magnotti, JF, and Wang, Z, and Beauchamp, MS. RAVE-source software for reproducible analysis and visualization of
open223, p.117341. intracranial EEG data. NeuroImage,
The multitaper
function (MIT License) uses the script derived from Prerau's lab
. The TinyParallel
script is derived from RcppParallel
package (GPL License) with TBB
features removed (only use tinythreads
). The register_volume
function uses NiftyReg
(BSD License) developed by CMIC
at University College London, UK (its R implementation is released under GPL license).
1] Magnotti, JF, and Wang, Z, and Beauchamp, MS. RAVE: comprehensive
[-source software for reproducible analysis and visualization of
open223, p.117341.
intracranial EEG data. NeuroImage, 2] Prerau, Michael J, and Brown, Ritchie E, and Bianchi, Matt T, and
[
Ellenbogen, Jeffrey M, and Purdon, Patrick L. Sleep Neurophysiological
Dynamics Through the Lens of Multitaper Spectral Analysis. Physiology,7, 2016, 60-92.
December 3] Modat, M., Cash, D.M., Daga, P., Winston, G.P., Duncan, J.S. and
[2014. Global image registration using a symmetric
Ourselin, S., -matching approach. Journal of medical imaging, 1(2), pp.024003-024003.
block4] JJ Allaire, Romain Francois, Kevin Ushey, Gregory Vandenbrouck, Marcus
[Intel (2022). RcppParallel: Parallel Programming Tools for
Geelnard and 'Rcpp'. R package version 5.1.5.
://CRAN.R-project.org/package=RcppParallel https