-
Notifications
You must be signed in to change notification settings - Fork 10
Home
#EDA Toolbox
EDA is a Matlab toolbox distributed under the free GNU GPL license for Electrodermal Activity (EDA) processing and analysis. Users can import data from proprietary file formats (Biopac and BrainProducts), preprocess, analyze and generate tables of descriptive statistics using the toolbox's graphical user interface (eda_gui.m) or command-line batch scripts (e.g. eda_script.m).
Currently, the EDA Toolbox automatically detects electrodermal responses (EDRs) in the EDA signal and classify them according to Bucsein's1 criterion. The program measures several parameters from the detected EDRs: amplitude, rise time and slope. When a matlab file (*.mat) with the experimental conditions (i.e. names, onsets and durations) is provided, the program also calculates the EDR's latency and the electrodermal level (EDL) of every event and groups them according to the conditions.
The following sections consist of the most up-to-date documentation about EDA Toolbox:
- Getting Started (under construction)
- Download and Installation
- Compatibility and Requirements
- Development History
- References
Note: This document is published as a wiki so that it can be edited by everyone. Please feel free to edit it for any improvements you feel are needed. I can always revert the changes, if I think it is necessary.
EDA Toolbox functions can be called from the Matlab command line or through the EDA Toolbox Graphical User Interface (GUI). To launch the EDA Toolbox GUI, type
>> eda_gui
in the Matlab command line. Usually, calling the toolbox functions from the command line will allow for a more flexible control of the functions input and output arguments. A batch script example with all the steps involved in a standard analysis is available in eda_script.m.
The standard procedure for preprocessing and analyzing the EDA signal is described below:
First, the EDA signal must be imported from the acquisition system's proprietary format to Matlab. If the data is already available in Matlab, two variables named data and fs must exist in the Matlab workspace or saved in a Matlab *.mat file
data % m-by-n matrix of EDA data (m channels by n samples)
fs % EDA sampling rate (Hz)The EDA Toolbox allows users to import data from two commercial acquisition systems' file formats: Biopac (AcqKnowledge 3.9.x or below) and BrainProducts. If you already have your data in Matlab, you can skip this section and go to Low-pass Filtering section.
Note: The script acqmat2mat.m is also available to transform generic data saved in Matlab format (*.mat) to the data matrix format used by the EDA Toolbox. This is useful to transform data exported from Acknowledge software (later than 3.9.x) in Matlab format (*.mat) to the data matrix format used by the EDA Toolbox.
-
Using the command line:
EDA Toolbox offers two functions for file conversion: acq2mat.m and vhdmr2mat.m. The first one converts files from Biopac Acknowledge format (*.acq) to Matlab format (*.mat). The second one converts from Brain Products Vision Recorder format (*.vhdmr) () to Matlab format (*.mat). In order to use vhdmr2mat.m, you will need to have EEGLAB software installed. To use these functions, type
>> [data fs] = acq2mat;or
>> [data fs] = vhdr2mat;in the Matlab command line. A dialog box for the user to select a *.acq or *.vhdmr input file, respectively, will be displayed. The acquired data matrix data and its acquisition sampling rate fs will be returned as outputs. For more information on how to use them, type
>> help acq2mator
>> help vhdmr2mat -
Using the GUI:
From the menu in the top of the GUI window, select File > Import from File > Data. In this case, *.acq, *.vhdmr or *.mat input files can be selected. The dialog also allows for the selection of a *.mat file. In this case, the selected *.mat file must contain a data matrix named data and the sampling rate stored in a scalar named fs.
The next preprocessing step is to low-pass filter the EDA signal. By default, EDA Toolbox will use a 5th-order low-pass Butterworth filter with cutoff frequency at 1Hz. But these parameters can be changed by the user both from the command line or the GUI.
-
Using the command line:
The function for filtering the EDA signal is eda_filt.m. First, select which channel (i.e. row in the data matrix) should be filtered
>> nChan = 1;>> eda = data(nChan,:);Next, call the eda_filt.m function using the default filtering parameters
>> [eda filt] = eda_filt(eda, fs, 'default');If other filtering parameters are desired, a filt structure array can be entered as input argument instead of the string 'default'. The filtered EDA signal, eda, and the filter parameters used, filt, are returned as outputs. For more information about eda_filt.m and its arguments, type
>> help eda_filt -
Using the GUI:
From the menu in the top of the GUI window, select Data> EDA > Filter.
Eventually, the EDA signal might have been acquired with very high sampling rate (e.g. > 1000Hz). In these cases, the user may desire to downsample the original signal to save disk space and increase processing speed. Usually, downsampling must be performed only after low-pass filtering the signal, and care must be taken for maintaining the Shannon-Nyquist sampling theorem criterion, which states that the sampling rate fs must be greater than twice the bandwith of the signal.
-
Using the command line:
The function for downsampling the EDA signal is eda_downsample.m. The new sampling rate requested, which must be lower than the original, is passed as the third input argument to the function (e.g. 100 Hz. In this example, 100 must be lower than the original value of fs)
>> [eda fs] = eda_downsample(eda, fs, 100);The new downsampled EDA signal, eda, and the new sampling rate, fs, are returned as outputs. Note that, in this example, the returned values will overwrite the original eda and fs values. If the ratio between the original sampling rate fs and the requested sampling rate (e.g. 100 Hz) is not an integer, the new sampling rate fs will be slightly different from the requested one. For more information on how to use eda_downsample.m, type
>> help eda_downsample -
Using the GUI:
From the menu in the top of the GUI window, select Data> EDA > Downsample.
Next, the Electrodermal Responses (EDR) in the EDA signal can be automatically detected by the program. First, the approximate first time-derivative of the filtered EDA signal is calculated using a difference function. The onset (valley) and peak of the EDRs are automatically detected when the first derivative changes sign. Onsets are identified by a negative to positive zero crossing, while peaks are identified by a positive to negative zero crossing. The EDR amplitude is calculated as the difference between the EDA signal amplitude at peak and onset times. The rise time is the interval between the onset and the peak time of the EDR. The slope is the rate of change of the EDR amplitude, and it is calculated as the ratio between the EDR amplitude and its rise time.
-
Using the command line:
The function for automatic detection of EDRs is eda_edr.m. In Matlab command line, type
>> edr = eda_edr(eda, fs);A structure array with the threshold values used for EDRs detection can be passed as a third input argument to the function. If nothing is specified, the following threshold values are used as default
thresh_def.amp.min = 0.02; % EDR amplitude minimum value
thresh_def.amp.max = Inf; % EDR amplitude maximum value
thresh_def.slope.min = 0.0; % EDR slope minimum value
thresh_def.slope.max = Inf; % EDR slope maximum value
thresh_def.risetime.min = 0; % EDR risetime minimum value
thresh_def.risetime.max = Inf; % EDR risetime maximum value
thresh_def.overlap = false; % Detect EDRs overlappingOnly EDRs with amplitude, slope and rise time within these threshold limits are detected by the program. Overlapping EDRs means that, if an accelerating deflection is found between a valley-peak pair, it will be assumed as two overlapping EDRs and they will be split for posterior analyses. Otherwise, the program will treat them as a single EDR. The edr output structure array contains the following fields:
edr.iPeaks % EDR peaks index in eda vector
edr.iValleyes % EDR valleys index in eda vector
edr.thresh % Threshold structure used for EDR detection
edr.type % EDR type according Bucsein's criterionThe EDR type can be one of the following:
- single response (never happens in practice)
- response overlaps preceding response during recovery time
- response overlaps preceding response during rise time
- response manually detected by the user (see section Visual Inspection and Manual Removal of Spurious Responses)
For more information on how to use eda_edr.m, type
>> help eda_edr
-
Using the GUI:
From the menu in the top of the GUI window, select Data> EDR > Automatic Detection.
Next, it is necessary to inspect the filtered EDA signal and control for any spurious EDR that might have been automatically detected. This can only be done through the EDA graphical user interface (GUI). It offers an interactive interface for visualization of the EDA signal and manually detection/removal of EDRs.
Each EDR is identified in the plot by a pair of valley (blue dot) and peak (red dot). Left-clicking with the mouse over the EDA signal plot allows the manual addition or removal of EDRs. A right-click over a detected EDR will open a message box with a summary of the selected EDR parameters (index, amplitude, slope, rise time, etc).
Additionally, if a Matlab file (*.mat) with the experimental conditions (i.e. names, onsets and durations) is provided, the program will also measure the EDR's latency and the EDL for each event, and allow their visualization in the GUI together with the conditions onsets and durations. The conditions file must include three cell arrays (each 1-by-n) named names, onsets and durations
names=cell(1,5); % contains the name of each conditions
onsets=cell(1,5); % contains the onsets of every event for each conditions
durations=cell(1,5); % contains the duration of every event for each conditions.
% The duration vectors can contain a single entry if the
% durations are identical for all events.
% For instance, required details of the second condition could be
% (the same should be done for the every conditions)
names{2}='cond2';
onsets{2}=[10 40 70 100 130];
durations{2}=[0 0 0 0 0];Conditions file can be imported to the GUI, using the menu File > Import from File > Conditions. Conditions are displayed as shaded areas on top of the EDA signal. The shaded area related to each event of a condition may correspond to the EDR onset latency window or to the full duration of the event itself. To switch between these two display modes, use the menu Data > Conditions > Shade > .... Right-clicking with the mouse on top of the conditions' shaded area, a context menu will open that allows switch to another conditions.
-
Using the command line:
Not available
-
Using the GUI:
The EDA GUI function is eda_gui.m. If eda and fs variables are already loaded in the Matlab workspace, type
>> eda_gui(eda, fs);Matlab command line. Otherwise, type
>> eda_gui;and the variables eda and fs will need to be imported from a file using the menu File > Import from File > Data
After making any change to the data or detected EDRs, the user needs to save them to a new file, using the GUI menu File > Export to File > Data, or to export the changed variables (eda, filt, edr and/or conds) to the Matlab workspace, using the GUI menu File > Export to MATLAB workspace> ...
For more information on how to use eda_gui.m, type
>> help eda_gui
After the EDRs have been correctly detected in the EDA signal, tables of results can be generated by the program in text format. Two types of tables are possible: one that includes only the list of detected EDRs and its parameters (valley time, peak time, amplitude, rise time, slope and type); and another that includes the results grouped by conditions (but requires the conditions file to be provided). If the conditions file is provided, the table of results will include the following information for every event defined in the conditions file: Condition name, Event onset, Event duration, Event latency window, Index of EDRs detected during the event, 'number of detected EDRs during the event, Minimum EDR amplitude during the event, Maximum EDR amplitude during the event, Mean EDR amplitude during the event and EDL during the event.
-
Using the command line:
The function for generating tables of results in text format is eda_save_text.m. To generate a table listing only the EDRs detected and their parameters
>> eda_save_text(eda, fs, edr);To generate a table of results grouped by conditions: first, load the conditions using the function eda_conditions.m
>> conds = eda_conditions(eda, fs, [], edr);and next call the function eda_save_text.m passing the conds as input argument
>> eda_save_text(eda, fs, edr, conds);For more information on how to use eda_save_text.m, type
>> help eda_save_text -
Using the GUI:
From the menu in the top of the GUI window, select File> Export to File... > Results....
The following code eda_script.m provides an example of batch file scripting to automatize the analysis of EDA data including all the processing steps described above. It should be modified according to individual needs.
The last version of EDA Toolbox can be downloaded from https://github.com/mateusjoffily/EDA.
To install EDA Toolbox, extract the content of the downloaded *.zip file to a folder and add this folder to your Matlab search path. In Matlab, use the File > Set Path dialog box or the command line
>> addpath('EDAfullpath').
To use vhdmr2mat.m to convert files from Brain Products Vision Recorder format (*.vhdmr) () to Matlab format (*.mat), you will need to have EEGLAB software installed.
EDA Toolbox has been developed on Matlab 7.5 (R2007b) under Windows XP operating system. It requires Matlab Signal Processing toolbox to be installed.
EDA Toolbox has been developed by Mateus Joffily during various stages with financial support from Federal University of Rio de Janeiro (UFRJ, Brazil), National Council of Scientific and Technological Development (CNPq, Brazil), Cognitive Neuroscience Centre (CNC, France), National Center for Scientific Research (CNRS, France) and Center for Mind/Brain Sciences (CIMeC, Italy).
For further information, comments, suggestions or bug report contact mateusjoffily@gmail.com.