ERPin3D: A Novel 3D Visualization for Event-Related Potential Data

Implementation

The code starts with a block of constants that define the size of the standard space for plotting. We defined the extent of this standard space to be +/- 500 in each dimension in the xy-plane (electrode_xyplane_extent), and to run from -200 to 1200 along the z-axis (time_range). Any values in the data set with times outside of this range are not plotted. Here we also set the voxel extent in the x- and y-dimensions. For a convenient size, this is set to 75, but could be adjusted by the user as discussed above. We also set the voxel transparency here to .3.

The code then asks for user input to grab the electrode_coordinate file and the data file (described in detail below). The data file is read into a cell array, which specifies the electrode labels and the data values. At this point, the extent of each voxel in the z-dimension is also determined: The height of each voxel is set as the difference of the time values for the first two data points (thus while the voxels may not appear to be continuous in the xy plane, they do appear continuous in the z-dimension).

Next, the user is prompted to select a colormap from a set of choices (e.g, ‘jet’, ‘hot’, ‘cold’), and is prompted to enter voltage values to exclude. The user determines a range of voltage values that will not be plotted (e.g. -2 to 5), and any values within that range in the data will be left out of the resulting plot. Thus if the user selects a lower bound of -2 and an upper bound of 5, the code will plot all values smaller than -2 and all values larger than 5 (i.e., values relatively close to 0 will be skipped).

Next the empty plot is created, and the blank head image is inserted into the space. A color scale is created using the user-selected colormap. An array for the voxel faces and the positions of the vertices of the voxels are defined. The code then loops through the data file assigning each voltage value to a voxel and assigning a color to each face of the voxel, skipping voxels that are within the range of voltage values to exclude. Once the loop is completed, the voxels are plotted and assigned their colors at the correct transparency. Finally, the colormap scale is created and added to the image.

Operation

ERPin3D was created with MATLAB R2024b (version: 24.2.0.2806996; R2024b; https://www.mathworks.com) but runs on earlier versions of MATLAB (verified on R2022a, R2021a), and the same code is fully compatible with GNU Octave (version 9.4.0; http://octave.org). Our code is freely available with the MIT no attribution license (see software availability statement below).

The default head image

The default head image (blank_head_ERPin3D.jpg) is a 500x500 pixel RGB image file with the outline of a head (including nose and ears) in black on a white background. It is inserted by default into the image space at z=-200 (time -200ms). The purpose of this image is to help orient the viewer in the space by making it clearer how the electrodes are positioned relative to the front and back and left and right sides of the head.

Preparing the electrode coordinate file

The electrode coordinate file is a tab delimited text file that contains one column for the labels of the electrodes to be plotted (“label”), one column each for the 2D projected x and y coordinates (“x” and “y”), and two additional columns that scale the projected coordinates into the 3D space for the figure (“x-scaled” and “y-scaled”). The first row is a header row. The included projections are pre-computed based on the 3D coordinates of the standard position for each electrode in the International 10-5 system of electrode placement.¹ For the default coordinates for the 2D projection, we used the coordinates in the standard_1005_2D.tsv file from Appelhoff and Brunner (v1.2.0).² The scaled coordinates were created by multiplying each standard projected coordinate by 500. This is an arbitrary factor based on the (hard-coded) size of the image space. Electrode labels should match the labels in the data file. Any electrode in the data file that is not included in this file will not be plotted. Additional electrodes in the electrode coordinate file that are not in the data file are ignored when the code runs.

Preparing the data file

The data file should be a tab delimited text file. The first column contains the electrode labels to be plotted, and the first row contains the time stamps for each data point. The total number of rows should equal the number of electrodes (plus one for the header row). The code cycles through the rows and columns in the data file and plots all data points.

Running the code

When the code is executed, the user is prompted to select the electrode coordinate file and the data file. A second dialog box appears after that to allow the user to select the color space (drop down menu) and to input the upper and lower bound of the voltage values to be excluded. Once those are set, the code runs without interruption until the image is created. Note that the electrode coordinate file and data files are text files that can be created by any means as long as they meet the structure described above.

Test case

As a test case, we created a plot for data eliciting an N400 effect in a standard priming task from the ERP core³ (https://osf.io/thsqg/). In this task, the N400 effect is seen as the voltage for primed targets (bin4) is less negative than the voltage for unprimed targets (bin3) over centro-parietal electrode positions, with the difference peaking about 400ms post-stimulus onset. This data set included 28 scalp electrodes sampled every 5ms in a 795ms epoch with a 200ms baseline (plotted from -200 to 795). Here we describe in detail how we extracted the data for plotting, as an illustrative example. To create our test image, we created a grand-averaged data file, then applied a bin operation in ERPLAB (version 12.00; https://erpinfo.org/erplab)⁴ in EEGLAB (v2024.2; https://sccn.ucsd.edu/eeglab/)⁵ to compute the difference wave (bin4 – bin3) for the N400 effect. Standard ERP plots of this effect are seen in Figure 1 (primed and unprimed conditions) and Figure 2 (difference wave).

Figure 1. A typical plot showing the voltage over time at multiple electrode positions in a topological arrangement reflecting the scalp position of each electrode.

Negative is plotted up. The plotted data shows a centroparietal N400 effect from roughly 300-500ms, with a more negative voltage for words that were unprimed (red line) vs. primed (black line). However, the location of the effect’s maximum and its spatial extent are not too easy to discern from the image.

Figure 2. A heatmap plot showing the voltage of the difference wave (“bin5”, which is the subtraction unprimed – primed) for an N400 effect across three successive time windows (100-300ms, 300-500ms, 500-700ms).

The spatial extent of the N400 effect and the location of its maximum difference can be clearly seen as the blue blob in the center image. However, the temporal extent of the effect is not precisely discernable from the image, as the data have been averaged across 200ms time windows.

For our ERPin3D plot, we exported the ERP for the difference wave (bin5). To export the data, we used the “Export ERP to text (universal)” option in the “Export and Import ERP” section of the ERPLAB menu. We chose our newly created bin5 to export, named the file, selected the option to include time values (in milliseconds), the option to include electrode labels, and in the Transpose data section, we chose the option to have the electrodes in rows and points in columns. We kept the default numeric precision value of 4 (changing this value might make small differences in the color values but otherwise has no impact on the plot).

Figure 3a and 3b illustrate the initial plot for the N400 effect from 2 different angles (created by taking screenshots of the generated plot after rotating it by mouse in matlab). We chose the ‘jet’ color map, corresponding to the magnitude of the voltage at that voxel. Though this plot shows all of the data, it is difficult to see the N400 effect – it’s buried in the middle of the figure, surrounded by other voxels. To improve visibility, we include a feature to allow the user to select a range of voltage values to exclude. The exclusion settings can be guesstimated based on other plots or by rerunning the code with different values until the desired visualization is achieved, but could be determined more objectively in future versions based on data quality measures, effect size measures, or other statistical information about the effect. In Figure 3c and 3d we show the same effect from the same 2 angles, removing voltages from -4 (lower range of data values to exclude) to 500 (arbitrarily large value for the upper range of data values to exclude), avoiding all positive voltage values in the data, and removing relatively small negative values close to zero. With these changes, the time course and spatial extent of the N400 effect can be more clearly seen.

Figure 3. Visualization of an N400 effect with centroparietal scalp distribution.

The N400 data is shown first from the default left posterior vantage point (A) and a rotated central posterior vantage point (B). Transparency of each voxel was set at 0.3, but no voxels were excluded from this initial view. In the images in the bottom row, voxels with voltage values between -4μV and 500μV were excluded, leaving only the blue voxels corresponding to the effect, seen from the same default vantage point (C) and rotated vantage point (D) of the images in the top row. With the extraneous voxels removed the spatial extent, temporal extent, and voltage intensity of the N400 effect can all be seen clearly, and particularly so when the image is live in MATLAB and can be rotated by clicking and dragging within the image.