Test/II.Importing & Exporting Data
| Main Tutorial: Multiple Datasets
Importing continuous and epoched data
Importing a Matlab array
We first construct a 2-D Matlab array 'eegdata' containing simulated EEG data in which rows are channels and columns are data points:
eegdata = rand(32, 256*100); % build a matrix of random test data (32 channels, 100 seconds at 256 Hz)
To import these data, select the menu item File > Import data > from ascii/float file or Matlab array. At the Data file/array click on option Matlab variable from the list and set the name to eegdata. Set the sampling frequency to 256 Hz, press OK. Other dataset parameters will be automatically adjusted.
Note on importing data from other file formats: To import continuous data from a Matlab .mat file instead from a Matlab array, scroll the list of choices in the box above that shows Matlab .mat file.
Note: When reading a Matlab .mat file, EEGLAB assumes it contains only one Matlab variable. For reading a (32-bit) binary float-format data file, two choices are available: float le (little-endian) and float be (big-endian) The correct choice here depends on operating system. In case the bit ordering is unknown, try each of them. Note that the toolbox command line function shortread() can also be used to read data from a (16-bit) short-integer file. The resulting Matlab array may then be imported into EEGLAB as shown above.
Now is a good time to add a Description about the dataset. A window will pop up containing a text box for this purpose. Enter as much information about the dataset as possible. The information you enter will be saved with the dataset for future reference by you or by others who may load the data. You can add to or revise these comments later by selecting menu item Edit > Dataset info. It is also possible to save the newly created data into a new dataset, either retaining or overwriting (in Matlab process memory) the old dataset. To also save the new dataset (with all its accompanying information fields) to disk, enter a filename in the lower edit field. Press OK to accept.
Then use menu item Plot > Channel data (scroll) to visualize the imported data.
Importing Biosemi .BDF files
Biosemi has extended the 16-bit European standard "EDF" (European Data Format) to their 24-bit data format, BDF (Biosemi Data Format). Select menu item File > Import data > From Biosemi .BDF file (calling function pop_readbdf()). A window will pop up to ask for a file name.
Press OPEN to import a file.
Then a second window pops up, press Ok.
The third window to pop up ask for a new dataset name.
Press OK, then select menu item Plot > Channel data (scroll) to inspect the data. A sample .BDF file is available -- TEST_256.BDF (use save link as in your browser). (More sample files and reading functions are also available from the Biosemi ftp site). To extract event records from .BDF data, select menu item File > Import event info > From data channel as explained elsewhere in this tutorial.
Importing European data format .EDF files
To import data collected in the joint European 16-bit data format (EDF), select menu item File > Import data > From European data format .EDF file (calling function pop_readedf()). A window will pop up to ask for a file name. Then select menu item Plot > EEG data (scroll) to inspect the data. A sample .EDF file is available -- TEST.EDF (use save link as in your browser). To extract event records from .EDF data, select menu item File > Import event info > From data channel as explained elsewhere in this tutorial.
Importing EGI .RAW continuous files
To read EGI (Electrical Geodesics Incorporated) .RAW data files, select menu item File > Import data > From EGI .RAW file. The following window will appear
The function pop_readegi() should be able to read EGI Version 2 and Version 3 data files. The presence of events in the EGI format is recorded in an additional EGI data channel. Information from this channel is automatically imported into the EEGLAB event table and this channel is then removed by EEGLAB from the EEGLAB data. (If, for any reason this fails to occur, extract events using menu item File > Import event info > From data channel as explained elsewhere in this tutorial.)
Importing .RAW EGI data epoch files
Select File > Import data > From .RAW file. A window will pop up to ask for the file name. Then select menu item Plot > EEG data (scroll) to inspect the imported data (a sample file is available here for testing).
Importing Neuroscan .CNT continuous files
Note: In our experience, importing Neuroscan files is not an easy matter and no universal read function may exist. It seems that the EEGLAB function works properly in most cases, even for recent (2002) data files. For more about how to read Neuroscan files under Matlab, see a helper page. A stand-alone Matlab function for reading this format is also available on the function index page as loadcnt(). You may import the EEG test file TEST.CNT and use it to test the following tutorial steps.
Start by selecting the menu item File > Import data > From .CNT data file, which calls the pop_loadcnt() function. The following window will appear:
Select the file to input (after changing the filter to the correct directory if necessary), and press OPEN. The following window will pop up:
The first input field concerns the structure of the .CNT file. If the imported data don't look like continuous EEG, try changing this number. Most often it should be 1 or 40, but other values may work. Now press OK. A window asking for a new set name will pop up, press OK to save the new data set.
Next, use menu item Plot > Channel data (scroll) to inspect the input data and menu item Edit > Event values to inspect the input event field latencies. EEGLAB (from version 4.31) automatically reads channel labels. If you call the menu Edit > Channel locations, EEGLAB will automatically find the location of most channels (based on channel labels).
We will now illustrate how to import additional epoch event information contained in an accompanying Neuroscan .DAT file into the EEGLAB dataset. Before importing the .DAT file, you must first epoch the loaded data (i.e., you must separate it into data epochs). To epoch the data, select Tools > Extract epochs
Simply press OK to epoch the data based on the events contained in the .CNT file (here using a time window extending from -1 s before to 2 s after events). The following window will appear:
Use this window to enter description and save the new dataset. For computers with limited memory (RAM), try overwriting the parent dataset (here, the continuous dataset we have just imported) by checking the Overwrite parent box in this window. One may also save the dataset to disk. Press OK when done. The following baseline removal window will pop up:
Simply press OK and continue.
Importing Neuroscan .EEG data epoch files
Select File > Import data > From .EEG data file, calling function pop_loadeeg(). A first window will pop up to ask for the file name and a second window (below) will query for data format (16 or 32 bits) and for data range. See the pop_loadeeg() function for more details (a 16-bit sample file is available here for testing). Data epochs have now been extracted from the EEG data. See also the section below about importing DAT file containing epoch information.
Then select menu item Plot > EEG data (scroll) to inspect the imported data. In this case, epoch events have also been imported from the file and can be visualized using menu item Edit > Event values.
Importing Snapmaster .SMA files
Select menu item File > Import data > From Snapmaster .SMA file (calling function pop_snapread()). A window will pop up to ask for a file name. The following window will pop up to ask for relative gain, leave it on 400 and press Ok.
A window will pop up to ask for a file name. Then select menu item Plot > Channel data (scroll) to inspect the data and item Edit > Event values to inspect event latencies and types. A sample .SMA data file is available -- TEST.SMA (use save link as in your browser).
Importing ERPSS .RAW or .RDF data files
To read ERPSS files (Event-Related Potential Software System, JS Hansen, Event-Related Potential Laboratory, University of California San Diego, La Jolla, CA, 1993), select menu item File > Import data > From ERPSS .RAW or .RDF file (calling function pop_read_erpss()). A window will pop up to ask for a file name. Then select menu item Plot > Channel data (scroll) to inspect the data and item Edit > Event values to inspect event latencies and types. A sample .RDF data file is available -- TEST.RDF (use Save link as in your browser). A header file for the ERPSS format is also available here.>
Importing Brain Vision Analyser Matlab files
To read Brain Vision Analyser (BVA) Matlab files, first export Matlab files from the BVA software. Then use menu item File > Import data > From Brain Vis. Anal. Matlab file (calling function pop_loadbva()). A window will pop up asking for a file name. After reading the data file, select menu item Plot > Channel data (scroll) to inspect the data and item Edit > Event values to inspect event latencies and types. Channel locations will also be imported and can be visualized using menu item Plot > Channel locations > By name. A sample BVA Matlab data file is available -- TESTBVA.MAT (use Save link as in your browser). Note that you need a macro (and Matlab installed) to be able to export Matlab files from Brain Vision Analyser.
Importing sets of data averages into EEGLAB
EEGLAB was made to process and visualize single-trial data. Event-related potential (ERP) averages can also be processed and visualized, but they should not be imported directly. Note that in our current practice, we perform averaging over trials after applying ICA and not before (see Makeig et al. Science, 2002).
However, an increasing number of ERP researchers find it of interest to apply ICA to related sets of ERP grand averages (see Makeig et al, J. Neuroscience, 1999 and Makeig et al., Royal Society, 1999). To import data grand-average epochs into EEGLAB, stack the different conditions in a single array as explained below.
First, the data averages for different conditions must be imported to Matlab. For example, one may export these averages in text format and then use the standard Matlab function
>> load -ascii filename.txt
Note that to import ASCII files to Matlab, all column names and row names must be removed. For Neuroscan user, we have also programmed the function loadavg() which can read most binary .AVG Neuroscan files.
Then you will need to concatenate data averages. For example, from a three-condition experiment, we may derive three ERP averages with a sampling rate of 1000 Hz, covering from -100 to 600 ms with respect to stimulus onsets (Note that we always process each subject individually and then compare the results across subjects at the end of the analysis).
For instance typing >> whos under Matlab might return:
Name Size Bytes Class avgcond1 31x600 14880 double array avgcond2 31x600 14880 double array avgcond3 31x600 14880 double array Grand total is 55800 elements using 446400 bytes
Note: If necessary, transpose the arrays (so rows=channels, colunmns=data samples, i.e. chan*samp) like this (not necessary for this example)
>> avgcond1 = avgcond1';
Then concatenate the arrays
>> allcond = [ avgcond1 avgcond2 avgcond3 ];
Finaly, you will need to import concatenated data averages into EEGLAB. First start EEGLAB:
Select menu item File > Importing data > From ascii/float file or Matlab array
Enter the information as indicated above. The following window pops up and allows you to add comments and/or save the new dataset immediately. Press OK to create a new dataset.
Select Plot > Channel ERPs> in rect. array and set the last option, 'Plot single trials', to YES to visualize the three condition ERPs.
It is possible to process the three average-ERP epochs as if they were single-trial epochs (although in this case some EEGLAB functions may not be meaningful). See the Data analysis tutorial for more information.
Importing data in other data formats
The Biosig toolbox (biosig.sf.net) contains links to functions to read other EEG data formats in Matlab. You may download the Biosig plugin for EEGLAB (see the EEGLAB plugin page).
For other non-suported data format, the home page of Alois Schlolg contains links to other Matlab reading functions. We are also willing to add other data importing functions to EEGLAB, so please send us a sample raw data file together with a Matlab function to read it and a README file describing the origin of the data and its format. We will attempt to include such functions in future releases of EEGLAB. Contributing authors will retain all rights to the functions they submit, and the authors' name(s) will be displayed in the function header. See our page on how to contribute to EEGLAB.
The EEGLAB discussion list archive also contains messages from users for importing specific data formats. You may search the list archive (and the rest of the EEGLAB web site) archive using Google from the bottom of the main EEGLAB web page.
Importing event and epoch information
EEGLAB counts records of the time and nature of experimental events to analyze the EEG data. This section details how to load in event information which coded in one of the data channels, stored in a Matlab array or separate ascii file. When event information is read in, (as of v4.2) EEGLAB copies the resulting EEG.event structure to a back-up (ur) copy, EEG.urevent and creates links from each event to the corresponding urevent. This allows the user to select events based on the previous (or future) event context, even after data containing some events has been rejected from the data (see the event tutorial for more information).
Importing events from a data channel
Often, information about experimental events are recorded onto one of the rows (channels) of the EEG data matrix. Once more we create simulated data to illustrate how to import events from a data channel. Assuming an EEG dataset with 33 rows (channels), out of which the first 32 are channels and the last (33) is an event channel with values 1 (stimulus onset), 2 (subject response), and 0 (other), Matlab code for generating such data follows (to test, copy and paste the code to the Matlab command line):
>> eegdata = rand(32, 256*100); % 32 channels of random activity (100 s sampled at 256 Hz). >> eegdata(33,[10:256:256*100]) = 1; % simulating a stimulus onset every second >> eegdata(33,[100:256:256*100]+round(rand*128)) = 2; % simulating reaction times about 500 ms after stimulus onsets
After copying the code above to Matlab and importing the array eegdata into EEGLAB as a test dataset (see Matlab arrays in this section), select menu item File > Import event info > from data channel to call function pop_chanevent() .
Enter 33 as the event channel and set the edge-extract type to up (leading)
Note: place the mouse over the text Transitions to extract to see contextual help).
Press OK. Now, the event information will have been imported into the test EEGLAB dataset. At the same time, channel 33 will have been deleted from the test data. Select menu item Edit > Event values to inspect the imported event types and latencies.
Importing events from a Matlab array or text file
Using the random EEG dataset created above, we import event information stored in an ASCII text file, tutorial_eventtable.txt. This text file is composed of three columns, the first containing the latency of the event (in seconds), the second the type of the event, and the third a parameter describing the event (for example, the position of the stimulus). For example, the top lines of such a file might be:
Select menu item File > Import event info > Import Matlab array or ASCII file
Browse for the tutorial text file, set the number of header lines to 1 (for the first line of the file, which gives the column field names) and set the input fields (i.e., the names associated with the columns in the array) to latency type position. If these field names are quoted or separated by commas, these extra characters are ignored. (NOTE: It is NECESSARY to use the names latency and type for two of the fields. These two field names are used by EEGLAB to extract, sort and display events. These fields must be lowercase since Matlab is case sensitive.) In this interactive window the input Event indices and checkbox Append events? can be used to insert new events or replace a subset of events with new events (for instance for large EEG files which may have several event files).
Important note about aligning events
An essential input above is Align event latencies to data events which aligns the first event latency to the existing event latency and checks latency consistency. A value of NaN (Matlab for not-a-number) indicates that this option is ignored (as in the example above). However, for most EEG data, the EEG is recorded with basic events stored in an event channel (see Import events from a data channel above) for instance. Detailed event information is recorded separately in a text file: as a consequence the events recorded in the text file have to be aligned with the events recorded in the EEG.
To do so, set the input for Align event latencies to data events to 0 if the first event in the text file correspond to the first event recorded in the EEG (i.e., if the offset between the two is 0). Setting this value to 1 indicates that event 1 in the event text file corresponds to event number 2 in the EEG data. Here, negative values can also be used to indicate that events in text file start before those recorded in the EEG).
When aligning events, as shown in the following section, the function displays the latencies of the two event types, so the user can check that they are aligned based on his knowledge of the experiment (for instance, there may be more events in the text file than recorded in the EEG).
The last checkbox allow to automatically adjust the sampling rate of the new events so they best align with the closest old event. This may take into account small differences in sampling rates that could lead to big differences by the end of the experiment (e.g., a 0.01% clock difference during would lead to a 360-ms difference after one hour if not corrected).
Importing events from a Presentation file
Then the following window pops-up
Scroll file fields to select which field (i.e., file column) contain the event type and which column contain the event latency. The default is fine with this specific file, so simply press OK. Matlab then returns:
Replacing field 'Event Type' by 'type' for EEGLAB compatibility Replacing field 'Time' by 'latency' for EEGLAB compatibility Renaming second 'Uncertainty' field Reading file (lines): 6 Check alignment between pre-existing (old) and loaded event latencies: Old event latencies (10 first): 10789 21315 31375 41902 51962 62489 … New event latencies (10 first): 10789 21315 31376 41902 51963 62489 … Best sampling rate ratio found is 0.9999895. Below latencies after adjustment Old event latencies (10 first): 10789 21315 31376 41902 51963 62488 … New event latencies (10 first): 10789 21315 31375 41902 51962 62489 … Pop_importevent warning: 0/6 have no latency and were removed eeg_checkset: value format of event field 'Duration' made uniform eeg_checkset: value format of event field 'Uncertainty2' made uniform eeg_checkset note: creating the original event table (EEG.urevent) Done.
The function aligns the first event latency recorded in the Presentation file to the first event latency recorded in the EEG in the SnapMaster file. Check that the events recorded in the SnapMaster file have the same latencies as the ones recorded in the .LOG presentation file. The function then computes the best sampling rate ratio: this may account for small differences in sampling rate that could lead to big differences at the end of the experiment (e.g., 0.01% clock difference during half an hour would lead to a 360-ms difference after one hour if not corrected). Note that if the events are shifted (with respect to events from the binary EEG file), it is always possible to suppress events manually or to import the presentation file as a text file, as described in the previous section. Note that some Presentation files that contain comments at the end of the file may not be supported. If you are not able to import a Presentation file, try removing any comments from the end of the file. If it still does not work, try importing the Presentation file as a text file as described in the previous section.
Importing Neuroscan .DAT information files
To import the .DAT file linked to a previously loaded .CNT file, select menu item File > Import epoch info > From Neuroscan .DAT info file (calling function pop_loaddat()). The sample .DAT file associated with the continuous .CNT file we used above is available for download -- TEST.DAT
Select the file to import in the resulting window. A second window will then appear:
In .DAT files, there must be a reaction time (in milliseconds) for each epoch. However, depending on experiment design there may be no reaction time in a given epoch. Then one has to use a code value for reaction time latencies in these epochs. For instance, you might decide that a value of 1000 (ms) would indicate that the subject did not respond. (If all the epochs of the experiment already have a reaction time, do not enter anything here.)
Importing epoch info Matlab array or text file into EEGLAB
Importing epoch information means that data epochs have already been extracted from the continuous EEG data, and that the Matlab array or text epoch information file has one entry per epoch. To illustrate how to import such a file or array, we will once more create some simulated EEG data.
eegdata = rand(32, 256, 10); % 32 channels, 256 time points per epoch, 10 epochs
Select menu item File > Import data > From ascii/float data file or Matlab array.
Press OK in this window (Note: If you select a data importing format different from Matlab variable, be sure to click on it to actually select the option.) Then, a second window will pop up.
Press OK in this window (see how to import at the beginning of this page for more information). Note that the Matlab array, being 3-D, is automatically imported as data epochs: the first dimension is interpreted as data channels, the second as data points and the third as data epochs or trials (e.g., our sample data matrix above contains 10 epochs). Let us imagine that our simulated EEG data came from a simple stimulus/response task, with subject responses being either 'correct' or 'wrong' and response latencies recorded in milliseconds. Then the epoch event file might look something like this:
This file tutorial_epoch.txtcan be downloaded or copied from the array above in a text file. Then select menu item File > Import epoch info > from Matlab array or ascii file, bringing up the following window:
Above, browse for the tutorial_epoch.txt file, set the input fields to epoch response rt (where rt is an acronym for 'reaction time'). The only one of these fields that contains latency information is rt, so it is entered to the as input to the Field name(s) containing latencies query box. This file (see above) has 1 header line, as we need to specify in the Number of file header lines to ignore box. Finally the reaction times are recorded in milliseconds, which we indicate as 1E-3 (i.e., one-thousandth of a second). Note that the last entry, Remove old epoch ..., allows the user to import other information later if it is unset. Press OK when done. Now select Edit > Event fields.
It is a good idea to click each of the Field description buttons above to add detailed descriptions of the meaning of each of the fields and the coding of the field values (for example: 1 = correct, 2 = wrong, etc.). This information is stored along with the event field values when the dataset is saved (very useful for later analysis by you or others!).
Above, there are now five fields, not three as for the file data. Also note that the field rt is not present. All of this is normal because EEGLAB does not store epoch information as such, but converts it into fields in its events structure. Though this seems a bit complicated in the beginning, it helps avoid redundancy and inconsistencies between epoch and event information. It also means that new data epochs can be re-extracted from data epochs based on the stored events. Now select menu item Edit > Event values to inspect what happened to the reaction time information (use the arrow to move to the second event):
As shown above, when epoch information was imported, events with type named rt were created and assigned a latency. If we had had several columns containing latency information, the function would have created several types.
Programming note: For convenience, standard epoch information is available from the command line in the variable EEG.epoch. Also, event information available in EEG.event can be used for script or command line data processing. See the script writing tutorial for more information.
Exporting data and ICA matrices
Exporting data to an ASCII text file
EEGLAB datasets can be exported as ASCII files using menu item File > Exports> Data and ICA activity to text file. Enter a file name (mydata.txt, for instance). Check the second checkbox to export the average ERP instead of the data epochs. By default, the electrode labels are saved for each row (4th check box) and the time values are saved for each column (5th checkbox). Time units can be specified in the edit box closest to the time values checkbox. Finally, check the third checkbox to transpose the matrix before saving.
The file written to disk may look like this:
FPz EOG1 F3 Fz F4 EOG2 FC5 FC1 ... -1000.0000 -1.1091 2.0509 0.1600 -0.1632 -0.4848 -1.3799 -0.0254 -0.4788 ... -992.1880 0.6599 1.7894 0.3616 0.6354 0.8656 -2.9291 -0.0486 -0.4564 ... -984.3761 1.8912 1.3653 -0.6887 -0.0437 0.2176 -0.9767 -0.6973 -1.5856 ... -976.5641 0.5129 -0.5399 -1.4076 -1.2616 -0.8667 -3.5189 -1.5411 -1.9671 ... -968.7521 -0.0322 -0.4172 -0.9411 -0.6027 -0.9955 -2.3535 -1.6068 -1.0640 ... -960.9402 0.1491 0.0898 -0.0828 0.3378 0.0312 -2.4982 -0.9694 -0.0787 ... -953.1282 -1.9682 -1.5161 -1.2022 -0.8192 -1.1344 -3.3198 -1.6298 -0.9119 ... -945.3162 -3.7540 -2.1106 -2.6597 -2.4203 -2.2365 -3.5267 -1.9910 -2.7470 ... -937.5043 -2.4367 -0.1690 -0.9962 -1.7021 -2.8847 -2.1883 -0.2790 -1.5198 ... -929.6923 -2.8487 -0.3114 -1.6495 -2.6636 -4.0906 -1.7708 -1.2317 -2.3702 ... -921.8803 -2.8535 0.1097 -1.5272 -2.0674 -3.8161 -3.1058 -0.8083 -1.5088 ... -914.0684 -3.9531 -0.4527 -1.8168 -2.2164 -3.4805 -2.1490 -1.0269 -1.3791 ... -906.2564 -3.9945 -0.1054 -1.8921 -2.8029 -3.5642 -3.4692 -1.1435 -2.2091 ... -898.4444 -4.4166 -0.8894 -3.3775 -3.8089 -3.8068 -1.7808 2.5074 -3.5267 ... -890.6325 -3.0948 0.5812 -2.5386 -1.7772 -1.8601 -2.8900 -2.0421 -2.0238 ... -882.8205 -3.1907 0.7619 -3.6440 -2.1976 -1.4996 -0.6483 -3.4281 -2.7645 ... -875.0085 -1.7072 2.5182 -3.2136 -2.4219 -1.3372 -1.5834 -2.9586 -2.8805 ... -867.1966 -1.8022 1.7044 -2.6813 -3.2165 -2.7036 0.0279 -2.5038 -3.4211 ... -859.3846 -3.1016 -0.1176 -3.6396 -4.3637 -3.9712 -3.5499 -3.4217 -4.5840 ... -851.5726 -1.7027 0.7413 -3.3635 -3.8541 -3.5940 -1.3157 -2.9060 -3.8355 ... -843.7607 -0.2382 0.5779 -1.9576 -2.6630 -1.8187 -1.1834 -1.4307 -2.4980 ... -835.9487 0.7006 0.4125 -0.4827 -1.7712 -2.0397 0.2534 0.2594 -1.2367 ... -828.1367 -0.2056 -0.3509 0.4829 -0.6850 -1.1222 0.0394 1.4929 0.7069 ... -820.3248 0.3797 -0.3791 0.9267 0.2139 -0.6116 -0.7612 1.3307 1.5108 ... -812.5128 -0.8168 -1.4683 -0.3252 -0.8263 -1.5868 -0.7416 -0.2708 -0.1987 ... -804.7009 -0.7432 -0.3581 -0.9168 -0.8350 -1.7733 -0.4928 -0.7747 -0.6256 ... ...
The first column contains the time axis and the other the data for each electrode. This file might, for example, be imported into SPSS or BMDP.
Exporting ICA weights and inverse weight matrices
Use menu item File > Export> Weight matrix to text file to export the ICA unmixing matrix (weights*sphere). Simply enter a file name in the pop-up window and press Save.
The text file on disk then contains the weight matrix. It may be re-imported into another EEGLAB dataset using menu item Edit > Dataset info. As shown below, enter the filename in the ICA weight array edit box. Leave the sphere edit box empty, or empty it if it is not empty. See the ICA decomposition tutorial for more details on sphere and weight matrices.
| Main Tutorial: Multiple Datasets