RAVE:ravepreprocess

From OpenWetWare
Jump to navigationJump to search
RAVE logo R Analysis and Visualization of iEEG

RAVE


Overview

To load your data into RAVE, the following items are required:

  1. iEEG data
  2. MRI data (volumetric or FreeSurfer) for visualizing anatomical locations of electrodes

RAVE can assist with generating two additional requirements:

  1. list of electrode labels and co-ordinates, generated from a post-implantation CT scan
  2. list of event times and labels, generated during the experimental session (e.g. t = 2 sec Event type 1 started; t = 3 sec Event type 1 stopped; t = 14 sec Event type 2 started; t = 16 sec Event type 2 stopped; etc.)

Preparing data

RAVE prefers a separate data file for each electrode (containing the raw voltage by time information) in the standard ".mat" format. Commercial iEEG amplifiers use proprietary formats, so a conversion routine provided by the manufacturer is need to prepare the data for ingestion. For instance, Blackrock Microsystems creates data files with the extensions ".CCF", ".NEV", ".NSx". The manufacturer maintains conversion routines here: https://github.com/BlackrockNeurotech/NPMK

Ingesting data

Detailed tutorial on ingesting data.

 rave::rave_import_rawdata('subject_code','project_name')

This command searches for the specified project_name directory within the specified subject_code directory and copies all files found there into RAVE's directory and file structure. The script requests the sampling rate of the data during data acquisition (e.g. enter 2000 for 2 kHz sampling rate), then scans the specified directory. The user selects the data blocks corresponding to the appropriate project_name. The script determined whether the data is stored as 1 file per channel or 1 file containing all channels (for this, the file name must be exactly the same across the selected blocks.)

Alternate Method: Instead of using the script, users can manually place files in the correct directory structure.

Selecting data to preprocess

To begin, launch the RAVE Preprocessing Module from RStudio with the following command:

rave::rave_preprocess() 

The Preprocessing Module will launch in a browser window or tab, if the browser is already opened. The initial page should be the Overview page. If not, select “Overview” from the black panel list at left.

The Overview page has two sections, called panels, that contain text boxes, droplists, or checkboxes with which the files and settings for the current RAVE session are selected, or data calculated from the current panel entries. All panels have a header with the panel’s name and a minimize icon (a minus sign, “-”) that will hide the panel without altering the data therein. There may also be a help icon (a question mark, “?”), a refresh icon (a pair of circled arrows), or an expand icon (a segmented box). Those will be covered as they appear.

Look first at the left panel. The panel is organized into Steps for loading a subject’s data for preprocessing. Step 1 is the subject code. This is the name of the folder in which the subject’s raw data, in the form of .h5 files from an iEEG recording, are stored. In the Beauchamp lab, we use a three-letter subject code such as YAB or YAD. The demo data set includes these subjects as well as one named “demo.”

Step 2 is to select a project folder in which to store the subject data. The project folders are stored in the RAVE directory; each project will have a folder for each subject included, and a subject can be included in any number of projects. To create a new project here, select “new…” from the drop-down menu labeled “Project.” A text box will appear in the Step 2 section. Enter the desired name of the project here and click “Create” to make that folder in the RAVE directory. From this point on, this project folder can be selected from the “Project” droplist.

Step 3 is to select the data that will be loaded for preprocessing. RAVE uses iEEG data stored in numerically-identified recording sessions, henceforth referred to as “blocks,” named with a zero-padded integer according to the order in which they were recorded. Select the subject’s recording blocks associated with the set project from the uppermost droplist in this section. In the text box below, enter the range of electrodes to be loaded. It is recommended to run the preprocessing steps on all electrodes at once (i.e., the range entered should be “1-max” up to the largest electrode value of the subject’s recording). The lowermost textbox sets the sample rate at which the preprocessing will be run. This should be identical to the sample rate of the iEEG recording equipment.

Look now at the right panel. This panel displays the current entries of the left panel for review. At the bottom it displays a log of events that occur to the currently-selected dataset.

Click the “Load Subject” button to set the current selection and begin preprocessing.

IMPORTANT NOTE: Currently, all blocks for a subject must be preprocessed at once. This is to make sure that all blocks have the same number of electrodes and sampling rate. If additional blocks need to be added later, a second subject must be created (e.g. YDJ2) and preprocessed. If the same parameters are used, the two subjects (e.g. YDJ and YDJ2) can then be merged.

Tip: a common issue is that there are some channels that you do not wish to analyze with RAVE (for instance, data from EKG leads). RAVE is designed for the case where there is a brain electrode for each channel's data stream. There are several ways to eliminate channels without associated brain electrodes. In the "Overview" menu in RAVE_Preprocess, select only the electrodes that you wish to analyze in the "Electrodes" input box (e.g. if there are 90 channels, but channels 5 through 10 are EKG channels, enter "1-4,11-90" into the input box). This will allow RAVE to skip the EKG channels. Alternately, one could make a .mat file that contains only channels 1-4 and 11-90 and then load the entire file into RAVE. Note that in this case the channel numbering will be off relative to the original channel numbering.

Click on the "?" in the menu screenshot below for more details.

RAVE:ravepreprocess:ravepreprocessoverview:input overviewRAVE:ravepreprocess:ravepreprocessoverview:output informationPreprocessing

Notch filtering

Click on the "?" in the menu screenshot below for more details.

RAVE:ravepreprocess:ravepreprocessnotch:input notchfilterRAVE:ravepreprocess:ravepreprocessnotch:input inspectionRAVE:ravepreprocess:ravepreprocessnotch:output notchinspectsignalsPreprocessing

The Notch Filter is a form of band-stop filter that attenuates signals in one or a few narrow bandwidths to minimal levels while leaving signals outside the bandwidth(s) unaltered. Many iEEG setups that include an amplifier introduce harmonics at certain frequencies to the signal data. This filter removes these as a calculation of multiples of a base frequency. This panel, as well as some others seen throughout RAVE’s modules, will be autofilled with a default set of parameters; these parameters represent common settings found in iEEG and are fully customizable when encountered. The panel loads with default settings for the Notch Filter that will remove commonly-found harmonics of 60Hz introduced by most amplifiers.

First, look at the Notch Filter panel. The first text box is for the base frequency, in Hertz, of the filter. Enter here the base frequency for the notch filter. In the second text box, choose the multiplier(s) of the base frequency to be filtered out as well. The default settings are “1,2,3” and will create stopbands at 60Hz, 120Hz, and 180Hz. More multipliers can be added to cover the data’s entire frequency range if needed or, alternatively, fewer multipliers for fewer or a single stopband. The third textbox is used to set the width, in Hertz, of each stopband. One value should be entered for each harmonic, separated by commas. The default settings of “1,2,2” refer to, respectively, the 60, 120, and 180Hz bands, and refer to the +/- for each. Using the default settings, this sets the first harmonic stopband to 59-61Hz, the second to 118-122Hz, and the third to 178-182Hz. The information at the bottom of this panel will describe the number of stopbands and the ranges of each; this information will update automatically as the settings are adjusted.

Look at the Inspection panel. This panel controls the settings of the Notch – Inspect Signals panel to the immediate right which displays the raw and, after calculation, the filtered signal of each channel loaded, so these panels will be discussed together. There are two droplists side-by-side at the top of the Inspection panel. The first, to the left, controls the currently-displayed block and the second, to the right, controls the currently-displayed channel. Setting either of these will automatically update the Notch – Inspect Signals panel to display the selected recording. If it does not update automatically, click the refresh button at the top of the Notch – Inspect Signals panel. Refreshing the browser page will reset the panels to their default settings.

The “Previous” and “Next” buttons below these droplists on the Inspection panel are used to navigate between channels; pressing “Previous” will set the Notch – Inspect Signals panel to display the numerical channel immediately below the current selection, and pressing “Next” will display the channel immediately above it.

At the bottom of the Notch – Inspect Signals panel, there are two Welch periodograms and a histogram of the selected channel. Welch periodograms display the estimated power of a signal across frequencies. The rightmost plot is a standard periodogram. The middle plot is a transformation of that periodogram with a logarithmic x-axis. This makes viewing the signals at lower frequencies easier. The leftmost plot is a histogram of the voltage samples making up the displayed signal. To alter these panels, look at the three sliders at the bottom of the Inspection panel. The top slider sets the width of the Welch periodograms within the page. This will not alter the data, solely the display size of the plots within the Notch – Inspect Signals panel. The middle slider sets the frequency range of the periodograms. Frequencies outside of this range are not excluded from analysis, only from the display; the maximum frequency of the data itself is set by the recording parameters of the iEEG setting. The bottom slider controls the number of bins in the histogram. Each of these sliders can be adjusted by channel to best fit the display settings to the current signal.

Wavelet decomposition

Click on the "?" in the menu screenshot below for more details.

RAVE:ravepreprocess:ravepreprocesswavelet:input generalsettingsRAVE:ravepreprocess:ravepreprocesswavelet:input waveletsettingsRAVE:ravepreprocess:ravepreprocesswavelet:input detailsRAVE:ravepreprocess:ravepreprocesswavelet:output waveletkernelsPreprocessing

First look at the General Settings panel on the upper left. This panel has three textboxes. In the uppermost textbox labeled “Electrodes,” enter the range of the electrodes to be transformed. It’s recommended to run the wavelet across all electrodes at the same time for both consistency and best performance, so the value entered here should be “1-max” up to the largest numerical electrode value.

The wavelet is run at a native sample rate, by default 100Hz, before being down-sampled. For a different target sample rate, enter the desired value in Hertz into the second textbox.

The settings of every wavelet run are stored as a CSV file within each subject’s folder within the project. The droplist here can be used to select a previously-run wavelet setting file to repeat the transformation with the same parameters. If the desired file isn’t listed automatically in the droplist, click the “Browse” button to open a directory navigator and select the appropriate file. At the bottom of the panel is the “Run Wavelet” button that will begin the wavelet transformation. Because this process is so demanding, a dialogue box will pop up to confirm this choice. Click “Yes” if the computer is ready to run the transformation or “No” to close the dialogue box and continue editing the settings.

The Details panel does not alter the settings of the wavelet but rather displays them as a table for review. This panel will update automatically if information in the General Settings panel is changed or if a CSV file is loaded through the Wavelet Settings panel. At the top of the panel is a small blue link, “Download Current Setting.” Clicking this will download the table as a CSV to the local computer. This file is also saved automatically upon completion of the wavelet to the subject’s /meta/ folder within a project in the RAVE directory.

The Wavelet Kernels panel is the largest panel of the Wavelet page and displays graphically the details of the wavelet transformation that will be run.


Troubleshooting: If Wavelet decomposition crashes, it is often because the "Number of Cores" setting is too high. Using more CPU cores speeds up processing but also requires more RAM. Try decreasing the "Number of Cores" setting. This setting is available in the third textbox. Because the wavelet transformation requires a large amount of RAM, it must be run in parallel across multiple cores to avoid a memory shortage. The maximum number of cores and the RAM per core available to RAVE are set in the RAVE options menu, accessible by the command:

rave_options()

Epoching

Epoch data

Import MRIs

Overview of imaging data and electrode localization

Import volumetric MRI data and cortical surface models

Localize electrodes

Overview of imaging data and electrode localization

Introduction to localizing electrodes

Detailed tutorial on electrode localization.

Referencing

Tutorial on Referencing.

Annotated screenshot of Reference module.