= Tutorial 7: Event markers =
''Authors: Francois Tadel, Elizabeth Bock, John C Mosher''

<<TableOfContents(2,2)>>

== Lists of events ==
You  probably noticed colored dots on top of the recordings in  the MEG figure. They represent the event markers saved in this dataset. In this documentation, they can be called indefferently '''events''', '''markers '''or '''triggers'''.  Some are stimulus triggers that were generated by the stimulation computer (Psychophysics toolbox), others are the subject responses recorded from a button box. This tutorial shows how to manipulate those markers.

 * Open the MEG recordings for file '''AEF#01'''.
 * Make sure it is configured as presented here: Montage "CTF LF", [DC] button selected, 3s pages.
 * All the markers available in the file are listed in the Events section of the Record tab.
 * On the left, you have the groups of events and the number of occurrence for each group:
  * '''200 standard''' audio stimulations
  * '''40 deviant''' audio stimulations
  * '''49 button''' responses: The subject presses a button with the right index finger when a deviant is presented. This is a very easy task so all the deviant are detected. Because of some issues with the way this CTF system saves the triggers, some are doubled, which explains the 49 responses for 40 deviants. In most cases, only the first one is to consider. We will check this in the next tutorial.

 * On the right, you have the list of the time instants at which the selected event occurs.
 * Those  two lists are interactive. If you click on a  event group (left list),  it shows the corresponding occurrences in the right list.  If you click on one particular event in  the right list, the file viewer jumps to it. It works the other way as well: if you click on a  dot representing an event in the MEG  figure, the corresponding event  group and occurrence are selected in  the Record tab. <<BR>><<BR>> {{attachment:events_list.gif||height="205",width="591"}}

== Adding events ==
The markers can represent  either stimulation triggers or subject responses that were  recorded  during the acquisition. It can also be useful to add new markers during the analysis of the recordings, to identify events of interest that are not detected at the time of the recordings, such as artifacts (eye movements, heartbeats, subject movements) or specific patterns of brain activity (epileptic spikes).

 * Create a new group of events "Test" with the menu '''Events > Add group'''.
 * Click on this new category to select it. It contains no occurrences at the beginning (x0). <<BR>><<BR>> {{attachment:events_newgroup.gif||height="112",width="504"}}
 * Then place the time cursor (red vertical bar) where you want to add a new marker "Test".
 * Add a few occurrences with any of the three  methods:
  * In the Record tab: Select the menu Events > '''Add / delete event '''
  * In the time series figure: Right-click > '''Add / delete event '''
  * In the time series figure: Press '''Ctrl + E '''
 * Note that you can click outside of the white area to select the time (on  top of the figure), or use the shortcut '''Shift+click'''. If the display is too dense, it can be difficult to set the current time instead of selecting a channel. <<BR>><<BR>> {{attachment:events_newmarker.gif||height="137",width="555"}}
 * Remove all the event occurrences in "Test", but not the group itself. Use any of the three methods:
  * In the Record tab: Select one or more event occurrences, press the '''Delete''' '''key'''.
  * In the time series figure: Click on an event dot and right-click > '''Add / delete event '''
  * In the time series figure: Click on an event dot and press '''Ctrl + E'''

== Extended events ==
You can  also use this interface to create events that have a temporal extension,  ie. that last for more than one time sample. This can be used to  define bad segments in the recordings.

 * In the time series window, select a time range (click + move).
 * Add an event: menus or Ctrl+E.
 * The  first occurrence you add in an event group defines its type:  single time point (simple events), or time range (extended events). You cannot mix different types of  events in a group. You get an error when you try to add a time segment in a event category that already contains a simple event.<<BR>><<BR>> {{attachment:events_extended.gif||height="140",width="570"}}
 * Remove the event group "Test": Click on it in the list and press the '''Delete''' '''key'''.

== Custom shortcuts ==
When  reviewing long recordings and adding manually lots of events (eg. when  marking manually epileptic spikes), using the menus presented above is not convenient because they require many mouse clicks.

Using  the menu '''Events > Edit keyboard shortcuts''', you can  associate custom events to the key 1 to 9 of the keyboard. Define the  name of the event type to create for each key, and then simply press the  corresponding key to add/delete a marker at the current time position.

{{attachment:events_shortcuts.gif||height="329",width="666"}}

== Bad segments ==
It is very  common to have portions of the recordings heavily contaminated by events  coming from the subject (eye blinks, movements, heartbeats, teeth  clenching) or from the environment (stimulation equipment, elevators,  cars, trains, building vibrations...). Some of them are well defined  and can be removed efficiently,  some are too complexed to be modeled efficiently. For this last category, it is usually safer to mark the  noisy segments as bad, and ignore them for the rest of the analysis.

To  mark a segment of recordings as bad, the procedure is the same as for  defining an extended event: select a time window, and then tag it as bad  with one of the following methods.

 * In the Record tab: Select the menu '''Events > Reject time segment''',
 * In the time series figure: Right-click > '''Reject time segment''',
 * In the time series figure: Press '''Ctrl + B'''

It  creates a new event group BAD, and add an extended event to it.  Later,  when epoching this file (extracting time blocks and  saving them in the database), the trials that contain a  bad segment will be imported but tagged as bad, and ignored in  the rest of  the analysis.

You can create multiple groups of bad segments, for instance to identify different types of artifacts. Any event group that contains the tag "BAD" will be considered as indicating bad segments.

{{attachment:events_bad.gif||height="140",width="595"}}

== Saving modifications ==
Now you can  delete all the event groups that you've just created and leave only the  initial ones (button, standard, deviant): select the event groups and press '''Delete''', or use the menu '''Events > Delete group'''.

When   you close the continuous file viewer, or the last figure that shows a part of   the raw file, the dataset is unloaded, the file is released and the   memory is freed.

If  you edited the events for  this file, you are asked whether to save the  modifications or not.  If you answer "Yes", the modifications are saved  only  in  the database link (Link to raw file), not in the original  file itself. Therefore, you would see the changes the next time you  double-click on the "link to raw file" again, but not if you open the  original .ds file in another protocol or with an external  program.

{{attachment:events_save.gif||height="130",width="378"}}

Note   that events you edit are not saved automatically until that moment. As   you would do with any other type of computer work, save your work  regularly, to  limit the damages of a program or computer crash. In the  Record tab, use the menu ''' File > Save modifications'''.

== Other menus ==
{{http://neuroimage.usc.edu/brainstorm/Tutorials/TutRawViewer?action=AttachFile&do=get&target=menuFile.gif|menuFile.gif|height="316",width="407",class="attachment"}}

==== File ====
 * '''Import in database''':  Import blocks of the current continuous file into the database.  Equivalent to a right click on the "Link to raw file" in the database  explorer > Import in database.
 * '''Save modifications''': Save the modifications made to the events in the database link.
 * '''Add events from file''': Import events from an external file. Many file formats are supported.
 * '''Read events from channel''':  Read the information saved during the acquisition in an digital  auxiliary channel (eg. a stimulus channel) and generate events.
 * '''Export all events''': Save all the events in an external file.
 * '''Export selected events''': Same as "Export all events" but exports only the selected events.

==== Events ====
 * '''Rename group''': Rename the selected group of events. Shortcut: '''double-click'''.
 * '''Set color''': Change the color associated with an event group.
 * '''Merge groups''': Merge to event groups into a new group. Initial groups are deleted. To keep them, duplicate them before merging.
 * '''Combine stim/response''':  Shortcut to call the process "Import recordings > Combine  stim/response", to create new groups of events based on stim/response  logic. <<BR>>Example: Stimulus A can be followed by response B or C. Use this process  to split the group A in two groups: AB, followed by B; and AC, followed  by C.
 * '''Duplicate groups''': Make a copy of the selected event groups.
 * '''Convert to simple events''':  Convert a group of extended events (several time points for each  event), to simple events (one time point). An option window asks you  whether to keep the first or the last sample only of the extended  events.
 * '''Edit keyboard shortcuts''': Custom associations between keys 1..9 and events
 * '''Reject time segment''': Mark the current time selection as bad.
 * '''Jump to previous/next event''': Convenient way of browsing through all the markers in a group.<<BR>>Shortcut: '''Shift + left/right'''

<<EmbedContent("http://neuroimage.usc.edu/bst/get_prevnext.php?prev=Tutorials/MultipleWindows&next=Tutorials/StimDelays")>>

<<EmbedContent(http://neuroimage.usc.edu/bst/get_feedback.php?Tutorials/EventMarkers)>>