Changes

== Markers ==

== Markers ==

All processing steps and pipelines need to be executed at a specific time and in a specific order. This is handled by markers, which are received in synchrony with the data stream. Markers in themselves do not represent any kind of processing. Meaning is given to them by the actions (processing steps or pipelines) associated with the markers. Actions can be freely defined in order to accomplish some particular task, for example presenting stimuli to participants, numerical data processing, or controlling a data acquisition system. Incoming markers can initiate an unlimited sequence of actions at an unlimited number of timepoints. Users can control the [.DocsSectionsMarkerHandling insertion of markers] and [.DocsSectionsBuildingExperiments#SecActions specify the actions] associated with them.

All processing steps and pipelines need to be executed at a specific time and in a specific order. This is handled by markers, which are received in synchrony with the data stream. Markers in themselves do not represent any kind of processing. Meaning is given to them by the actions (processing steps or pipelines) associated with the markers. Actions can be freely defined in order to accomplish some particular task, for example presenting stimuli to participants, numerical data processing, or controlling a data acquisition system. Incoming markers can initiate an unlimited sequence of actions at an unlimited number of timepoints. Users can control the [[BrainStreamMarkerHandling|insertion of markers]] and [[BrainStreamBuildingExperiments#SecActions|specify the actions]] associated with them.

Outside BrainStream, markers are represented as numbers. However, as numbers are easy to confuse, the BrainStream platform works with marker names everywhere. Names are strings, can contain characters (a-z), numbers (0-9), and must start with a character. Users can specify any name for their markers, except the set of [.DocsSectionsReservedNames#ResMarkers reserved marker names] that are already used by BrainStream.

Outside BrainStream, markers are represented as numbers. However, as numbers are easy to confuse, the BrainStream platform works with marker names everywhere. Names are strings, can contain characters (a-z), numbers (0-9), and must start with a character. Users can specify any name for their markers, except the set of [[BrainStreamReservedNames#ResMarkers|reserved marker names]] that are already used by BrainStream.

There are different marker types, for example stimulus, response and device control markers. Marker name, number, and type combinations are stored in [.DocsSectionsBuildingExperiments#SecDict Dictionary tables]. The set of dictionaries must be unique, i.e., for a certain marker type one cannot specify the same number multiple times, and overall marker names must be unique.

There are different marker types, for example stimulus, response and device control markers. Marker name, number, and type combinations are stored in [[BrainStreamBuildingExperiments#SecDict|Dictionary tables]]. The set of dictionaries must be unique, i.e., for a certain marker type one cannot specify the same number multiple times, and overall marker names must be unique.

When a marker is received by the platform it instatiates a new event.

When a marker is received by the platform it instatiates a new event.

Every marker that is received by BrainStream instantiates a new event. During an event, one or more actions can be executed at one or more different timepoints. Possible actions are modifying variables, executing functions or collecting data. An event ends when all actions that are specified for this event have been executed. A timeline with 3 events is show below:

Every marker that is received by BrainStream instantiates a new event. During an event, one or more actions can be executed at one or more different timepoints. Possible actions are modifying variables, executing functions or collecting data. An event ends when all actions that are specified for this event have been executed. A timeline with 3 events is show below:

[[File:DocsSectionsImportantConcepts.Event1.png]]

[[File:ImportantConceptsEvent1.png|717px|104x]]

''Figure 1: Three events''

''Figure 1: Three events''

Event 1 begins when marker mrk1 arrives. During Event 1, only one action is executed. The event ends when this execution is complete. Markers mrk2 and mrk3 start Event 2 and Event 3, respectively. For Events 2 and 3, multiple actions and timepoints are specified. These events end when all actions associated with them have been executed.

Event 1 begins when marker mrk1 arrives. During Event 1, only one action is executed. The event ends when this execution is complete. Markers mrk2 and mrk3 start Event 2 and Event 3, respectively. For Events 2 and 3, multiple actions and timepoints are specified. These events end when all actions associated with them have been executed.

[[File:DocsSectionsImportantConcepts.Event2.png]]

[[File:ImportantConceptsEvent2.png|722px|105x]]

''Figure 2: Events end when all associated actions have been executed''

''Figure 2: Events end when all associated actions have been executed''

Thus, the scope of events can range from a single processing step to very complicated processing pipelines. Especially in more complex cases, events may contain a lot of information, for example a list of which actions must be executed at which timepoints, variables associated with the actions, and data that has been collected during the event. All this information is organized in a Matlab [http://www.mathworks.nl/help/techdoc/ref/struct.html structure]] variable with the name ''event''. This structure contains a number of fixed fields and may contain additional fields depending on the experiment. For more detailed information see [[.DocsSectionsEventFields Fields of the Event Structure].

Thus, the scope of events can range from a single processing step to very complicated processing pipelines. Especially in more complex cases, events may contain a lot of information, for example a list of which actions must be executed at which timepoints, variables associated with the actions, and data that has been collected during the event. All this information is organized in a Matlab [[http://www.mathworks.nl/help/techdoc/ref/struct.html structure]] variable with the name ''event''. This structure contains a number of fixed fields and may contain additional fields depending on the experiment. For more detailed information see [[BrainStreamEventFields|Fields of the Event Structure]].

''Within'' an event, information can be transferred from one action to another via the event structure. For example, take a look at Event 2 in figure 1. Let's assume that action 1 adds a variable Var1 to the event structure, in the field event.Var1: <tt>event.Var1 = 3</tt>. During action 2, this variable is modified, so that <tt>event.Var1 = 4</tt>. If Var1 is used for performing action 3, the change that was made by action 2 will be incorporated. However, the event structure has a limited lifetime: it only exists for the duration of the event. When action 3 is completed, the event structure associated with Event 2 disappears. Var1 and the change that action 2 made to it will not be transferred to later events, for example Event 3. Thus, we cannot transfer information ''between'' events via the event structure. For this, we must use global variables.

''Within'' an event, information can be transferred from one action to another via the event structure. For example, take a look at Event 2 in figure 1. Let's assume that action 1 adds a variable Var1 to the event structure, in the field event.Var1: <tt>event.Var1 = 3</tt>. During action 2, this variable is modified, so that <tt>event.Var1 = 4</tt>. If Var1 is used for performing action 3, the change that was made by action 2 will be incorporated. However, the event structure has a limited lifetime: it only exists for the duration of the event. When action 3 is completed, the event structure associated with Event 2 disappears. Var1 and the change that action 2 made to it will not be transferred to later events, for example Event 3. Thus, we cannot transfer information ''between'' events via the event structure. For this, we must use global variables.

Within events, information between different processing steps is preserved. However, different events can only exchange information via a set of globally maintained variables, also called the user state.

Within events, information between different processing steps is preserved. However, different events can only exchange information via a set of globally maintained variables, also called the user state.

[[File:DocsSectionsImportantConcepts.GlobalVars1.png]]

[[File:ImportantConceptsGlobalVars1.png|600px|219x]]

''Figure 3: Information exchange between events via the global variables''

''Figure 3: Information exchange between events via the global variables''

<div id="GetPut"></div>

<div id="GetPut"></div>

=== Retrieving and updating content of global variables ===

=== Retrieving and updating content of global variables ===

The statements 'get' and 'put' in the [.DocsSectionsBuildingExperiments#SecActions Actions table] control the exchange of variable content between the global variables and the current event. These statements can be used for exchange of information ''between different events'' within the same block.<br /><br /><strong>get</strong>: copy content of a variable from the global variables into the event structure. The content will be copied into a new field of the event structure with the name of the variable. For example, a get statement for variable Var1 will create the field event.Var1.<br /><strong>put</strong>: copy the (modified) content of a variable from the event structure into the global variables.<br /><br />The statements 'load' and 'save' in the Actions table control the exchange of variable content between a location on disk and the current event. These statements can be used for exchange of information ''between different blocks''.<br /><br /><strong>load</strong>: load variable content from the [.DocsSectionsPathsFolders#OutputFolder session folder] into a new field of the event structure with the name of the variable. For example, a variable stored in the session folder with the name Var1.mat will create the field event.Var1. It may often be useful to execute all load actions at the BS_INIT marker, as this will make sure that the variables are loaded at the very beginning of the block.<br /><strong>save</strong>: save the content of a variable to the session folder and runfolder. If 'save' is executed multiple times for a specific variable during the same block, backup copies will be saved in the runfolder while the session folder only stores the last updated value. It may often be useful to execute all save actions at the BS_EXIT marker.

The statements 'get' and 'put' in the [[BrainStreamBuildingExperiments#SecActions|Actions table]] control the exchange of variable content between the global variables and the current event. These statements can be used for exchange of information ''between different events'' within the same block.<br /><br /><strong>get</strong>: copy content of a variable from the global variables into the event structure. The content will be copied into a new field of the event structure with the name of the variable. For example, a get statement for variable Var1 will create the field event.Var1.<br /><strong>put</strong>: copy the (modified) content of a variable from the event structure into the global variables.<br /><br />The statements 'load' and 'save' in the Actions table control the exchange of variable content between a location on disk and the current event. These statements can be used for exchange of information ''between different blocks''.<br /><br /><strong>load</strong>: load variable content from the [[BrainStreamPathsFolders#OutputFolder|session folder]] into a new field of the event structure with the name of the variable. For example, a variable stored in the session folder with the name Var1.mat will create the field event.Var1. It may often be useful to execute all load actions at the BS_INIT marker, as this will make sure that the variables are loaded at the very beginning of the block.<br /><strong>save</strong>: save the content of a variable to the session folder and runfolder. If 'save' is executed multiple times for a specific variable during the same block, backup copies will be saved in the runfolder while the session folder only stores the last updated value. It may often be useful to execute all save actions at the BS_EXIT marker.

As all these actions take time, it is advisable to perform them only when needed (for example, do not copy variables into the event structure that are not used during the current event).

As all these actions take time, it is advisable to perform them only when needed (for example, do not copy variables into the event structure that are not used during the current event).

<div id="ModVars"></div>

<div id="ModVars"></div>

=== Modifying variables ===

=== Modifying variables ===

Variables&rsquo; content can be modified by changing them during execution of functions, or by specifying expressions in the Actions table. Possible expressions are listed below.<br /><br />Specifying only a number or string means the variable will be set to that value:

Variables&rsquo; content can be modified by changing them during execution of functions, or by specifying expressions in the Actions table. Possible expressions are listed below.<br /><br />Specifying only a number or string means the variable will be set to that value:

<pre>-1, 0, [], {}  

<pre>-1, 0, [], {}