HED tags

Authors: Anna Zaidi and Raymundo Cassani

Hierarchical Event Descriptors (HED) provide a standardized and machine-readable way to describe events in neuroimaging datasets. Brainstorm now includes support for viewing, editing (with CTagger), validating, and using HED tags during analysis. This tutorial shows how to work with HED tags in Brainstorm and how to select trials based on their HED annotations.

This tutorial is based on the protocol that is generated by going through the Introduction tutorials, thus it assumes that you have completed them at least up to the point where trials are imported using the event occurrences (this is to say completed Tutorial #15).

Add and edit HED tags

In this section, we were are going add HED tags to the events standard, deviant and button in the TutorialIntroduction protocol. The HED tags to be added are derived from the description of the introduction dataset.

1. Double-click the pre-processed continuous file (Raw | notch(60Hz 120Hz 180Hz)) in the folder for Run 01 (S01_AEF_20131218_01_600Hz_notch).
   
   

   
   

2. While in the Record tab, in the Event list select (using the Ctrl key) the three events of interest, i.e. standard, deviant and button. Then open Record tab > Events > Edit HED tags with CTagger.
   

   If this is the fist time using CTagger, a message will appear saying, "Plugin ctagger is not installed on your computer. Download the latest version of Neuromaps now?" click Yes. For further information, see the plugins tutorial.
   
   

   
   

3. For each event, you can start adding HED tags by typing on the right text field of the window, or by using the Show HED schema. Add the following HED tags to the events:
   
   

   • standard: Sensory-event, Experimental-stimulus, Auditory-presentation, Tone, Expected

   • deviant: Sensory-event, Experimental-stimulus, Auditory-presentation, Tone, Oddball

   • button: Participant-response, Action, Push-button, (Right, Index-finger)
     
     

   
   
   

   • For information on the use of CTagger consult the CTagger guide and the video Easy HED annotation with CTAGGER

4. On the CTagger GUI, click on Validate all, then click on Finish. The selected HED tags are shown as a JSON sidecar file, click on Ok to close the CTagger.
   

   
   
   

5. Back on Brainstorm, verify that the HED tags were added to the events. In the Record tab, open the menu Record tab > Events > Show HED tags.

   
   
   

6. Finally, we copy use these HED tags to all the files where the events occur. In the Record tab, open the menu Record tab > Events > Uniform HED tags in protocol, and click on Run.
   
   

Selecting files using HED tags

Once the events have their HED tags, and these are uniform for all the files in the Protocol, we can sue the HED tags to filter trials. As proof of concept, we will compute the average event-related field (with respect to the auditory stimulus) for all trials that contained the HED tag Participant-response, which is related to participant pressing a button with their right index finger.

1. In the Process1 tab add all trials (deviant and standard) for Run 01, and click on [Run]
   

   
   

2. Select the process File > Select files by HED tags with these parameters:

   • HED tags(s): Participant-response

   • Check the option Select files

   Do not run the pipeline yet.
   

   
   

3. Select the process Average > Average files:
   

   • Group files: Everything

   • Function: Arithmetic average

   • Check Keep all the event markers ...

   
   

4. Run the pipeline. A new file Avg: 20 files is created, and it contains the average of all trials with auditory presentation (either standard or deviant) and button press. You can check which were the files averaged in the History of the average file, right-click on it then File > View history.

As sanity check, we will time-average in the the 375-500 ms window the average event-related response. The expected result is a higher activity in the sensors over the left sensorimotor cortex.

1. Drag-and-drop the file Avg: 20 files in the rocess1 tab and run the process Average > Average time using a the time window from 375 to 500 ms, and the Arithmetic average function.

   
   

2. Right-click on the resulting file Avg: 20 files | mean(375ms,500ms) and select MEG > 3d sensor cap to plot the activity on the MEG helmet and the participant scalp. Note the higher activity on the left-central sensors.

   
   

Filtering trials but HED tags allows you to compute condition-specific ERPs/ERFs based on semantic event annotations instead of the event names, and despite of importing epochs with a different event. As in this case, we selected al files with the Participant-response regardless of type of tone that was presented.

Exporting and importing HED tags

In addition to the manually edition of HED tags, it is also possible to import (and export) HED tags from (and to) a JSON sidecar file as mentioned in BIDS specification. These options are found in the Record tab > File menu, or as processes.

When a BIDS dataset is imported in Brainstorm (as shown in the OMEGA tutorial), if there are HED tags available these are automatically added their corresponding events.

Additional documentation

Related tutorials

• Epoching

• Event markers

• Scripting

Articles

• Robbins, K., Truong, D., Appelhoff, S., Delorme, A., & Makeig, S.
  Capturing the nature of events and event context using hierarchical event descriptors (HED).
  NeuroImage, 245, 118766.

Forum discussions

• Template: https://neuroimage.usc.edu/forums/t/XXXX