Changes

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''

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 [.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.

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, [], {}