The Neurophysiological Biomarker Toolbox (NBT)



Quick Guide to NBT script (for advanced users)

This tutorial aims at showing how to use NBT with code in stead of with the GUI. For demonstration we use the demo dataset available at DemoDataSet. Download the dataset and save it in a folder.

The dataset contains recordings of 129 EEG channels from 10 subjects in two conditions (ECR1 and EOR1), downsampled at 200Hz. The format of the dataset follows the NBT standard (for more info see Importing data into nbt format.

Before proceeding with the demonstration download and install NBT

More details about how to use NBT functions are directly available using the help function_name command.

You can now start with the tutorial following the steps listed hereafter:

Load data

Let's start with loading the first data. Use nbt_load_file function and indicate the name of the file as input to the function. If the Matlab current directory is not the same as the directory where you files are stored, you should inicate also the path of the folder where your data are saved.

[Signal,SignalInfo,SignalPath] = nbt_load_file('NBT.S0006.081215.EOR1.mat');
or
[Signal,SignalInfo,SignalPath] = nbt_load_file('C:\Demoset\NBT.S0006.081215.EOR1.mat');

If you can this function without specifying any inputs a popup window will appear allowing you to directly select the file you want to process.

This function load in the Workspace the following variables: Signal which is a matrix containing the signals for each channel (channels are organized in column), SignaLInfo which is a struct containing information on the signal according to nbt_info file format, SignalPath which is a string containing the path of the directory where you signal is stored.

When loading you need to specify the Signal file (i.e. NBT.S0006.081215.EOR1.mat), the SignalInfo file (i.e. NBT.S0006.081215.EOR1_info.mat) will be loaded automatically with the Signal file

Visualize data

After loading the signal into the Workspace, you may want to visualize both the temporal evolution of the signal and its time-frequency content.

Use the function nbt_plot for visualizing the signal in each channel and the function nbt_plot_TF_and_spectrum_one_channel for plotting the time-frequency spectrum. These function have as inputs the variable Signal and SignalInfo.

nbt_plot(Signal,SignalInfo);
nbt_plot_TF_and_spectrum_one_channel(Signal,SignalInfo);

For both plots you can interactively set specific parameters, manipulating the values in the Specify plot parameters popup window that will appear.

Clean data

The process of data cleaning consists in removing bad channels ( i.e. channels with poor contact to the scalp) and removing noisy intervals.

The noisy intervals and channels are stored in the corresponding Info file. In subsequent analysis, you can omit these artifacts. Once the artifacts are determined, they will be removed in subsequent analysis before the calculation of already implemented biomarkers.

Follow these instructions:

  • If you haven't done it before, load your data using nbt_load_file function.
  • Bad channels can be detected both automatically, using proper algorithmic techniques, or manually.
    • For automatic bad channel detection use the following command:
[Signal,SignalInfo] = nbt_EEGLABwrp(@nbt_FindBadChannels, Signal, SignalInfo, SignalPath,0);

The nbt_FindBadChannels function allows you to select among different techniques (Joint probability, Kurtosis, Faster toolbox, Correlation method, PCA method, or abnormal Spectra). Type F to the question that appears in the command window (F stands for Faster toolbox; you can also try different algorithms). A figure showing the channels position and a figure(Channel data(scroll) produced by EEGLAB) showing the EEG channels (tracks in red indicate the bad channels) similar to the one produced by the nbt_plot function will appear. By looking at the signals you can decide if accept or discharge some of the bad channels automatically selected, and answer to the question Do you want to change this list? appearing in the command window. If you select Y, it will ask you to specify a new bad channel list.

Since the nbt_FindBadChannels function update the bad channel list inside the EEG struct typical of EEGLAB format, the function nbt_EEGLABwrp will automatically convert the information from EEGLAB to NBT format.

  • For manual bad channel detection and for artifacts removal use the function nbt_get_artifacts, specifying the variables Signal,SignalInfo and SignalPath as input variables.
SignalInfo=nbt_get_artifacts(Signal,SignalInfo,SignalPath);

This function exploits the nbt_plot function to visualize the signal and interactively set plotting parameters (such as filtering settings) and select noisy intervals by clicking on the button click here to select noisy interval. At this stage you can also identify and select bad channels using right click of the mouse on the selected track.

  • Once you have done, click on the button click here to finish.
  • A message on the command window will appear asking if you want to save the signal. Type Y (yes) and then type CleanSignal for answering to the question “Name of NBT Signal? (should contain the word Signal)”.
  • Select a folder where to save your data. You can select the same folder where the original dataset is stored. In the latter case the original data and clean signals will be kept in the same file name and when you will try to load again the file NBT.S0006.081215.ECR1.mat, a window will appear asking if you want to load the original signal or the cleaned signal.

When you high pass filter before having cleaned your data, you smear out your artifacts in time (elongating them). It's recommended then to apply substantial high-pass filter (low cut off freq >0.05-0.1 Hz) for visualization purposes only. Typical settings for displaying: the high-pass filter and a low-pass filter are 0.5-1 Hz and 35–70 Hz, respectively. The high-pass filter typically filters out slow artifacts, such as electrogalvanic signals and movement artifacts, whereas the low-pass filter filters out high-frequency artifacts, such as electromyographic signals.

You can avoid to include in the transient artifacts eye-blinking artifacts. Eye-blink appears in the form of slower perturbation of the signal. Eye-blink artifacts can be removed applying Independent Component Analysis

Good practice to detect bad channels and noisy intervals: Together with the automatic selection of the bad channels we invite you to scroll with attention through all the signals using the plotting tools previously introduced. Although this procedure is tedious and requires time, it is crucial for the analysis of your data.

Compute Independent Component Analysis

An EEG signal is a mixture of signals from many sources. Some of these sources are not from the brain and produce so-called artifacts. Typical sources of artifacts are eye-blinks, breathing, heartbeat, or 50 Hz line noise. We want to clean our EEG signal from artifacts and, therefore, need a way of filtering these signals away. Independent component analysis (ICA) is a method which can extract signals from an EEG signal.

ICA will find, as the name indicates, independent components (i.e., signals) in the EEG signal. We can then select which of these components we want to reject and remove them from the EEG signal using a mathematical procedure called “projection”.

The ICA components are signals that have been combined from several EEG channels, this means that they act as spatial filters on the data. What the ICA algorithm does is to put different weights on each EEG channel such that each component is “independent” from all other components.

Click here for a more technical explanation

Here we describe how to extract ICA components from our demo dataset.

  1. Load and Clean your data
  2. Run ICA
  3. Filter ICA components
  4. Mark ICA components as bad
  5. Repeat steps 2,3
  6. Reject filtered ICA components
  7. Re-reference data to common average electrode
  8. Save ICA Processing

Most of the processing of ICA components works using EEGLAB format. This requires the conversion from NBT format to EEGLAB, the functions nbt_NBTtoEEG and nbt_EEGtoNBT allow you to create this bridge between the two toolbox. This can also be done by using the nbt_EEGLABwrp function. We suggest to first convert your NBT signal into EEGLAB format using nbt_NBTtoEEG, then perform ICA processing and re-referencing and in the final step reconvert to NBT format using nbt_EEGtoNBT or directly save your data using the nbt_EEGlab2NBTsignal function.

1. Load and Clean your data

Load and Clean your data from bad channels and noisy transient artifacts following the previous sections.

If you have already cleaned your data and saved as Clean Signal, you can load directly the cleaned signal using the nbt_load_file function:

[Signal,SignalInfo,SignalPath] = nbt_load_file('C:\Demoset\NBT.S0006.081215.EOR1.mat');

A window will appear asking which signal you want to load (the original or the cleaned), select CleanSignalInfo from the list.

2. Run ICA

ICA only gives good results if the signal is relatively stationary. We, therefore, apply a 0.5 Hz high-pass filter, this happens automatically (and is only done for the ICA, your signal will not be filtered) using the function nbt_filterbeforeICA. At the beginning of the process you will be asked to insert the number of ICA components you want to compute, type 15 in the appearing popup windows.

EEG = nbt_NBTtoEEG(Signal, SignalInfo, SignalPath); 
EEG = nbt_filterbeforeICA(EEG, 'EEG.data = nbt_filter_firHp(EEG.data,0.5,EEG.srate,4);',4);

3. Filter ICA components

To start rejecting ICA components we need to filter the components, i.e., we remove the frequencies below 0.5 Hz.

We need to filter the components, because the ICA components were calculated on the filtered signal. This is done by using the function nbt_filter_firHp:

offset = 4;
EEG.NBTEEGtmp = EEG.data;
EEG.data = nbt_filter_firHp(EEG.data,0.5,EEG.srate,4)
EEG.data = EEG.data';
EEG.data = EEG.data(:,(offset*EEG.srate):end);
EEG.pnts = size(EEG.data,2);
EEG.icaact = [];
EEG.icawinv = [];

At this point we need to inspect the outcome of the ICA for manually selecting the components to reject. We will use different methods to identify brain component and artifacts.

  • First, we inspect component activations, i.e., how the components change over time.
[com] = pop_eegplot(EEG,0,1,1);

If no clear components exist, it might help to remove more transient artifacts. If the component activation traces are crossing a lot, you may want to change the scaling of the y-axis using the + and - signs in the lower right corner of the scroll window. Try to identify which components you think are artifact? And which are brain components? Artifact components are characterized by sharp changes, or huge variations in voltage. Brain components would, e.g., have a clear alpha rhythm (~ 10 Hz). Which components would you reject? By scrolling the activation plot it is possible to identify Components 7 and 11 as candidates to reject.

  • To have more descriptive information on the components use the Reject components by map.
[EEG, com] = pop_selectcomps( EEG, 1:15);

Single component properties can be observed by clicking on the button indicating the number of the component (see figures below). Component 1 clearly comes from the brain, because of the strong ~10 Hz peak in the power spectrum. While Component 7 can be classified as an artifact component, because of the sharp changes in the component activations, and the typical eye-region topographic map.

  • To strengthen our confidence that a component is an artifact component we can also study the component statistics.
pop_signalstat( EEG, 1);

Write the number of the component you want to study, and click Ok. Most often brain components will have a gaussian distribution, as seen below for component 1, whereas component 7, which we assume to be an artifact component, has a non-gaussian distribution (see Figure below). The figure shows you a histogram of component activity (left) and a QQ plot (right) (see QQ plot on wikipedia. The QQ plot is a straight line if the distribution is normal, if not it has a bend like as seen in the second Figure below.

  • We get a better understanding of our components if we plot their power spectrum and distribution on the scalp.
pop_spectopo(EEG,0);

A power spectrum shows you how much power the signal has at each frequency; you will, therefore, see a peak in the alpha frequency range (8-13 Hz) if your signal contains alpha oscillations. Go to the menu Plot|Component spectra and maps in the EEGlab window, click on OK in the popup window. We see that components 1, 2, 3 have a clear alpha peak, whereas other components have a flat power spectrum. It seems that components 1, 2, 3, come from the brain. Which components did you select above?

4. Mark ICA components as bad

To improve the ICA result, we need to remove components identified as bad (i.e. 7, 11, 13, 14). Insert the numbers of the bad components (use space between numbers, without parenthesis), click OK.

EEG=nbt_MarkICBadChannel(EEG);

5. Repeat steps 2,3

When it ask for the number of ICA components (running the function nbt_filterbeforeICA) you should specified a number which is the difference between the initial selected component and the component marked as bad. In this case 11.

After having launched nbt_filter_firHp command, inspect again the components activation and make use of the above mentioned plotting tools (Component spectra and maps, power spectrum and topographic plots) for rejecting the bad components.

6. Reject filtered ICA components

Now you are ready to reject the selected components using again the function pop_subcomp

EEG.data = EEG.NBTEEGtmp;
EEG.NBTEEGtmp = [];
EEG.pnts = size(EEG.data,2);
EEG.icaact = [];
EEG.icawinv = [];
EEG = eeg_checkset(EEG);
EEG = pop_subcomp( EEG );

Only remove maximal 4 components! And only remove components that are clear artifacts.

When you are done rejecting artifacts, you need to re-reference the data and then save the cleaned data!

7. Re-reference data to common average electrode

The signal value for each electrode is calculated as the potential difference between the electrode and a reference electrode. Your data will have been created using Cz as a reference which is located in the center of the scalp, because it is the place with the least artifacts (far from neck and facial muscles). The Cz, however, is not convenient as a reference electrode, e.g., when plotting topographies of oscillation power plots, because it will appear as if there is almost no activity at Cz. Therefore, you should re-reference your data to a so-called “average reference”. After re-referencing, the potential at a given electrode is given relative to the mean across all channels.

The function nbt_AverageReference allows you to complete this step.

EEG=nbt_AverageReference(EEG)

8. Save ICA Processing

At this point the function nbt_EEGlab2NBTsignal allows you to directly save your data in NBT files without transforming first the EEGLAB variables into NBT variables (Signal and SignalInfo) into the workspace.

nbt_EEGlab2NBTsignal(EEG,1)

When asked for NBT Signal name write ICASignal. Then, select the folder where you want to store your signal. We recommend to use the folder where the original data file is, then the ICA signal will be appended (added) to this file and you will have the three signals in one file (original, cleaned, ICA). Wait for confirmation that the signal has been saved.

quick_guide_to_nbt_gui_developers/start.txt · Last modified: 2012/05/29 15:51 by Simon-Shlomo Poil
The NBTwiki platform - version 2.8 - 9 May 2013
Copyright (C) 2008-2015