Changes

450 bytes removed , 10:14, 26 September 2018

Line 3: Line 3:

__TOC__

−

An experiment in BrainStream consists of [~~.DocsSectionsBuildingExperiments~~#SecExpDef experiment definition tables], [~~.DocsSectionsBuildingExperiments~~#SecBlock block files and common block files]. The experiment may also need [~~.DocsSectionsBuildingExperiments~~#SecUserFun user defined functions]. The entire experiment is summarized in the [~~.DocsSectionsBuildingExperiments~~#SecProjectFile BrainStream Project file]. In the following, each of these components will be discussed.

+

An experiment in BrainStream consists of [[#SecExpDef|experiment definition tables]], [[#SecBlock|block files and common block files]]. The experiment may also need [[#SecUserFun|user defined functions]]. The entire experiment is summarized in the [#SecProjectFile|BrainStream Project file]]. In the following, each of these components will be discussed.

== Experiment definition tables ==

−

The experiment definition tables (.edt) form the core of your BCI [~~.DocsSectionsGlossary~~#SecE experiment]. In these tables is specified which actions need to be executed at what time. For each experiment, four different tables are needed: the [~~.DocsSectionsBuildingExperiments~~#SecActions Actions table], the [~~.DocsSectionsBuildingExperiments~~#SecDataSel DataSelection table], the [~~.DocsSectionsBuildingExperiments~~#SecDict Dictionary table], and [~~.DocsSectionsBuildingExperiments~~#SecTrigger Trigger table]. Together, the [~~.DocsSectionsBuildingExperiments~~#SecExpDef experiment definition tables] are called the [~~.DocsSectionsGlossary~~#SecE experiment definition file]. !Brainstream has its own [~~.DocsSectionsBrainStreamEditor~~ internal editor] for creating the tables, however, for backwards compatibility reasons it also supports excel files where each table is put in a different sheet. In the following, the experiment definition tables will be discussed in more detail.

+

The experiment definition tables (.edt) form the core of your BCI [[BrainStreamGlossary#SecE|experiment]]. In these tables is specified which actions need to be executed at what time. For each experiment, four different tables are needed: the [[#SecActions|Actions table]], the [[#SecDataSel|DataSelection table]], the [[#SecDict|Dictionary table]], and [[#SecTrigger|Trigger table]]. Together, the [[#SecExpDef|experiment definition tables]] are called the [[BrainStreamGlossary#SecE|experiment definition file]]. Brainstream has its own [[BrainStreamBrainStreamEditor|internal editor]] for creating the tables, however, for backwards compatibility reasons it also supports excel files where each table is put in a different sheet. In the following, the experiment definition tables will be discussed in more detail.

Line 15: Line 15:

The Actions table specifies the actions that should be executed for each marker. Table 1 is an example of an Actions table:

−

{| ~~border~~="1"

+

{| class="wikitable"

|-

| marker || time || function || feval || looptick || client

Line 27: Line 27:

|}

−

Table 1: Actions table The first column of the Actions table, the marker column, contains the names of all [[~~DocsSectionsImportantConcepts~~#SecMarkers|markers]] that elicit the execution of certain actions. If actions for the same marker are listed in different rows of the table, the marker name only needs to be specified in the first row. For example, in table 1, the actions for marker mrk1 are specified in two different rows, and the marker column can remain empty for the second of these rows. Multiple markers can be specified, separated by commas. Any of the markers from this list will trigger the execution of the associated actions. For example, in table 1, function fnc4 will be executed whenever either marker mrk2 or mrk3 arrives. The marker column can also contain a reference to another table (see [~~.DocsSectionsPlugIns~~ Import-tables]).

+

Table 1: Actions table The first column of the Actions table, the marker column, contains the names of all [[BrainStreamImportantConcepts#SecMarkers|markers]] that elicit the execution of certain actions. If actions for the same marker are listed in different rows of the table, the marker name only needs to be specified in the first row. For example, in table 1, the actions for marker mrk1 are specified in two different rows, and the marker column can remain empty for the second of these rows. Multiple markers can be specified, separated by commas. Any of the markers from this list will trigger the execution of the associated actions. For example, in table 1, function fnc4 will be executed whenever either marker mrk2 or mrk3 arrives. The marker column can also contain a reference to another table (see [[BrainStreamPlugIns|Import-tables]]).

The second column (time) specifies at which timepoints, relative to the time of the incoming marker, the actions should be executed. The exact timing of execution can be specified in several ways. The action can be executed directly at marker onset, when a certain amount of data becomes available, some time after the marker, or when another marker arrives (see table 2). For example, table 1 specifies that functions fnc1 and fnc2 are executed at the onset of marker mrk1 whereas function fnc3 takes place one second after marker onset.

−

<table bgcolor="#ffffff" cellpadding="3" ~~border~~="1"><tr><td> '''EVENT''' '''DATA''' a ''number'' another ''mrk'' </td> <td> Executed at marker onset Executed as data becomes available Executed ''number'' seconds ''after'' marker onset Executed at onset of marker ''mrk'' </td></tr></table>

+

<table bgcolor="#ffffff" cellpadding="3" class="wikitable"><tr><td> '''EVENT''' '''DATA''' a ''number'' another ''mrk'' </td> <td> Executed at marker onset Executed as data becomes available Executed ''number'' seconds ''after'' marker onset Executed at onset of marker ''mrk'' </td></tr></table>

Table 2: Specifying time of action execution

−

The third column (function) can contain one or more functions that will be executed in the order in which they appear in the table. So, in table 1, at the onset of marker mrk1, first function fnc1 and then function fnc2 will be executed. One second after the onset of marker mrk1, fnc3 will be executed. A number of [~~.DocsSectionsProgrmmersGuide~~ BrainStream functions] can be used in the function column. Alternatively, you can write your own user defined functions, which will be discussed in detail [~~.DocsSectionsBuildingExperiments~~#SecUserFun below].

+

The third column (function) can contain one or more functions that will be executed in the order in which they appear in the table. So, in table 1, at the onset of marker mrk1, first function fnc1 and then function fnc2 will be executed. One second after the onset of marker mrk1, fnc3 will be executed. A number of [[BrainStreamProgrmmersGuide|BrainStream functions]] can be used in the function column. Alternatively, you can write your own user defined functions, which will be discussed in detail [[#SecUserFun|below]].

−

The next three columns are optional. The [~~.DocsSectionsBuildingExperiments~~#SecFeval feval] column allows for specification of any functions that do not process any of the [[~~DocsSectionsImportantConcepts~~#SecVariables|global variables]]. The [~~.DocsSectionsBuildingExperiments~~#SecLooptick looptick] column can contain special functions that will be put into a loop by BrainStream. The ''client'' column can be used to direct execution of functions to another remote Matlab session (see [~~.DocsSectionsParallelMode~~ Parallel Mode]).

+

The next three columns are optional. The [[#SecFeval|feval]] column allows for specification of any functions that do not process any of the [[BrainStreamImportantConcepts#SecVariables|global variables]]. The [[#SecLooptick|looptick]] column can contain special functions that will be put into a loop by BrainStream. The ''client'' column can be used to direct execution of functions to another remote Matlab session (see [[BrainStreamParallelMode|Parallel Mode]]).

−

Although the order of these first columns in the table is arbitrary, it is best to keep it as described here. All subsequent columns are free to use for an arbitrary number of [~~.DocsSectionsBuildingExperiments~~#SecUserFun user defined variables] (more on this later).

+

Although the order of these first columns in the table is arbitrary, it is best to keep it as described here. All subsequent columns are free to use for an arbitrary number of [[#SecUserFun|user defined variables]] (more on this later).

+

=== Trigger table ===

While actions give meaning to the events, the Trigger table implements the logic of the experiment program flow. It defines how each event possibly triggers the execution of other events. Conditional expressions implement runtime dependent triggered events, made possible by allowing global variables to be used in these expressions. An example would be to either trigger the <tt>next_trial</tt> event or <tt>next_sequence</tt> event based on the current state of the <tt>num_acquired_trials</tt> variable. Table 3 demonstrates corresponding Trigger table.

−

{| ~~border~~="1"

+

{| class="wikitable"

|-

| marker || time || fire || datasource || delay || condition || triggeraction

Line 67: Line 68:

=== DataSelection table ===

−

Sometimes a marker signals a time point around which data should be collected. For example, if you are building an ERP-based BCI, you might want to collect a certain amount of data after each stimulus. For that purpose, each marker can specify a segment of data that should come along with the [[~~DocsSectionsImportantConcepts~~#SecEvents|event]]. In the [~~.DocsSectionsBuildingExperiments~~#SecActions Actions table], markers calling for [~~.DocsSectionsGlossary~~#SecD data selection] have a DATA statement in the time column. The DataSelection table lists the markers that call for data selection and specifies the time period of data selection relative to marker onset.

+

Sometimes a marker signals a time point around which data should be collected. For example, if you are building an ERP-based BCI, you might want to collect a certain amount of data after each stimulus. For that purpose, each marker can specify a segment of data that should come along with the [[BrainStreamImportantConcepts#SecEvents|event]]. In the [[#SecActions|Actions table]], markers calling for [BrainStreamGlossary#SecD|data selection] have a DATA statement in the time column. The DataSelection table lists the markers that call for data selection and specifies the time period of data selection relative to marker onset.

The DataSelection table consists of a marker column, a begindata column, and an enddata column. Data selection may start before or after onset of the marker, indicated by negative and positive numbers respectively. The end of data selection can be before or after the onset of the marker specified in the marker column, when a new marker arrives (with or without extra timing), or when nothing happens for a specified period of time (timeout). If multiple endtimes, seperated by a comma, are specified, the one that happens first will end the data selection.

−

{| ~~border~~="1"

+

{| class="wikitable"

|-

| marker || begintime || endtime || datasource

Line 100: Line 101:

The datasource column is optional. If multiple data sources are used in the experiment, the datasource column specifies for which data source the dictionary information is meant. If only one datasource is involved, this column can be left out and BrainStream will apply the definitions to the single data source.

−

{| ~~border~~="1"

+

{| class="wikitable"

|-

| marker || type || value || datasource

Line 118: Line 119:

=== Preventing conflicts with imported tables ===

−

BrainStream supports the use of [.DocsSectionsPlugIns imported] tables. When BrainStream is started, all experiment definition tables that are used in the experiment - including the imported tables - are combined in a process called [~~.DocsSectionsPlugIns~~#TableExpansion table expansion]. This means that all Action tables will be integrated into a single Action table, and the same is true for the DataSelection and Dictionary tables. Importantly, the information in the individual tables should not conflict. For example, you should prevent double definitions of marker names or numbers in the Dictionary tables.

+

BrainStream supports the use of [.DocsSectionsPlugIns imported] tables. When BrainStream is started, all experiment definition tables that are used in the experiment - including the imported tables - are combined in a process called [[BrainStreamPlugIns#TableExpansion|table expansion]. This means that all Action tables will be integrated into a single Action table, and the same is true for the DataSelection and Dictionary tables. Importantly, the information in the individual tables should not conflict. For example, you should prevent double definitions of marker names or numbers in the Dictionary tables.

Line 124: Line 125:

== User defined functions and variables ==

=== Functions in the 'function' column ===

−

In the Actions table, certain actions are assigned to markers. You can define the actions directly in the table, but it is also possible to specify actions by adding [~~.DocsSectionsGlossary~~#SecU user defined functions] to your table. The functions that you write may need certain variables as input. An arbitrary number of columns in the Action table can be used for these [~~.DocsSectionsGlossary~~#SecU user defined variables].

+

In the Actions table, certain actions are assigned to markers. You can define the actions directly in the table, but it is also possible to specify actions by adding [[BrainStreamGlossary#SecU|user defined functions]] to your table. The functions that you write may need certain variables as input. An arbitrary number of columns in the Action table can be used for these [[BrainStreamGlossary#SecU|user defined variables]].

−

If a function needs a user defined variable, you first need to get it from the [[~~DocsSectionsImportantConcepts~~#SecVariables|global variables]]. This is done by putting a ‘get’ statement in the corresponding cell. For example, consider the following Actions table:

+

If a function needs a user defined variable, you first need to get it from the [[BrainStreamImportantConcepts#SecVariables|global variables]]. This is done by putting a ‘get’ statement in the corresponding cell. For example, consider the following Actions table:

−

{| ~~border~~="1"

+

{| class="wikitable"

|-

| marker || time || function || feval || looptick || client || var1 || ........ || varN

Line 145: Line 146:

<pre>event = my_function(event,c1,c2,...)</pre>

−

The input and output argument 'event' is obligatory. [[~~DocsSectionsImportantConcepts~~#SecEvents|Event]] is a Matlab type [http://www.mathworks.nl/help/techdoc/ref/struct.html structure]] variable. The fields of this structure contain copies of the current content of the variables with a 'get' statement in the table. In the above example, var1 was made available to function my_fnc1 with a 'get' statement. Thus, the my_fnc1 input argument 'event' will contain the field event.var1, which holds a copy of var1. In contrast, the input argument 'event' of function my_fnc2 will not contain the field event.var1 (no 'get' statement in the Actions table), but it will have a field called event.varN, which contains a copy of variable varN. The additional input arguments (c1, c2, ...) are optional. You can enter [[~~.DocsSectionsGlossary~~#SecC constants] there, if your function needs them. For example, in table 5, function my_fnc2 needs the constant c1 as an input argument. Note that in the Actions table you do not need to enter 'event' as the first input argument to your functions, as BrainStream will automatically pass the event structure to all functions.

+

The input and output argument 'event' is obligatory. [[BrainStreamImportantConcepts#SecEvents|Event]] is a Matlab type [http://www.mathworks.nl/help/techdoc/ref/struct.html structure]] variable. The fields of this structure contain copies of the current content of the variables with a 'get' statement in the table. In the above example, var1 was made available to function my_fnc1 with a 'get' statement. Thus, the my_fnc1 input argument 'event' will contain the field event.var1, which holds a copy of var1. In contrast, the input argument 'event' of function my_fnc2 will not contain the field event.var1 (no 'get' statement in the Actions table), but it will have a field called event.varN, which contains a copy of variable varN. The additional input arguments (c1, c2, ...) are optional. You can enter [[BrainStreamGlossary#SecC|constants] there, if your function needs them. For example, in table 5, function my_fnc2 needs the constant c1 as an input argument. Note that in the Actions table you do not need to enter 'event' as the first input argument to your functions, as BrainStream will automatically pass the event structure to all functions.

−

Your user defined function might change the content of some the variables you use as input. If you want to save these changes, you can place a 'put' statement in the corresponding cell in the Actions table, which updates the modified variables to the [[~~DocsSectionsImportantConcepts~~#SecVariables|global variables]]. In the example above, changes that my_fnc2 makes to varN are saved, but changes that my_fnc1 makes to var1 are not (no 'put' statement). For more information about loading, modifying and saving user defined variables, see [~~.DocsSectionsImportantConcepts~~#ModVars Modifying variables].

+

Your user defined function might change the content of some the variables you use as input. If you want to save these changes, you can place a 'put' statement in the corresponding cell in the Actions table, which updates the modified variables to the [[BrainStreamImportantConcepts#SecVariables|global variables]]. In the example above, changes that my_fnc2 makes to varN are saved, but changes that my_fnc1 makes to var1 are not (no 'put' statement). For more information about loading, modifying and saving user defined variables, see [[BrainStreamImportantConcepts#ModVars|Modifying variables]].

Line 154: Line 155:

In the ''feval'' column, you can specify functions that do not process any of the user defined variables. Examples are Matlab's <tt>[[Http://www.mathworks.nl/help/techdoc/ref/tic.htmlTic|http://www.mathworks.nl/help/techdoc/ref/tic.html tic]]/[[Http://www.mathworks.nl/help/techdoc/ref/toc.htmlToc|http://www.mathworks.nl/help/techdoc/ref/toc.html toc]]</tt> or [[Http://www.mathworks.nl/help/techdoc/ref/disp.htmlDisp|http://www.mathworks.nl/help/techdoc/ref/disp.html disp]] functions. In the example below, <tt>tic</tt> and <tt>toc</tt> are used to evaluate the time it takes to execute function my_fnc1:

−

{| ~~border~~="1"

+

{| class="wikitable"

|-

| marker || time || function || feval

Line 167: Line 168:

In the following table, the execution time of multiple functions will be measured:

−

{| ~~border~~="1"

+

{| class="wikitable"

|-

| marker || time || function || feval

Line 182: Line 183:

Functions specified in the feval column can take user defined variables as input arguments, as in the following example:

−

{| ~~border~~="1"

+

{| class="wikitable"

|-

| marker || time || function || feval || Var1

Line 190: Line 191:

|}

−

In this table is specified that the value of Var1 is displayed when marker ''mrk1'' arrives. As is the case for functions in the function column, a get statement is required to copy the content of Var1 from the [[~~DocsSectionsImportantConcepts~~#SecVariables|global variables]] into the [[~~DocsSectionsImportantConcepts~~#SecEvents|event]] structure.

+

In this table is specified that the value of Var1 is displayed when marker ''mrk1'' arrives. As is the case for functions in the function column, a get statement is required to copy the content of Var1 from the [[BrainStreamImportantConcepts#SecVariables|global variables]] into the [[BrainStreamImportantConcepts#SecEvents|event]] structure.

=== Functions in the 'looptick' column ===

−

Looptick functions are a specific type of loop function that can be used when BrainStream is running in [~~.DocsSectionsParallelMode~~ parallel mode]. More information on these functions can be found in the advanced topic [~~.DocsSectionsLoopTick~~ Looptick Functions].

+

Looptick functions are a specific type of loop function that can be used when BrainStream is running in [[BrainStreamParallelMode|parallel mode]]. More information on these functions can be found in the advanced topic [[BrainStreamLoopTick|Looptick Functions]].

== Block files and common block files ==

−

To initiate your experiment in BrainStream, you need to compose one or more initialization run files, also called block files (.blk). Each block file contains or refers to all information needed to initiate the particular block of the experiment. For example, BrainStream needs to know to which data acquisition source it is connected, where to store output and where the experiment definition tables are located. The format of the block files is according to the Windows .ini file style with [~~.DocsSectionsGlossary~~#SecT topics] enclosed in brackets and subsequent lines to define [~~.DocsSectionsGlossary~~#SecK keys] that belong to this topic. If another bracketed line is encountered, a new topic is started and additional lines will add keys to this new topic. The notation of the topics and keys is in Matlab style, which means that every valid Matlab statement is possible here. For example, Matlabs comment character (%) can be utilized. An example of a block file is shown below. In this example, all minimally required topics with their keys are shown.

+

To initiate your experiment in BrainStream, you need to compose one or more initialization run files, also called block files (.blk). Each block file contains or refers to all information needed to initiate the particular block of the experiment. For example, BrainStream needs to know to which data acquisition source it is connected, where to store output and where the experiment definition tables are located. The format of the block files is according to the Windows .ini file style with [[BrainStreamGlossary#SecT|topics]] enclosed in brackets and subsequent lines to define [[BrainStreamGlossary#SecK|keys] that belong to this topic. If another bracketed line is encountered, a new topic is started and additional lines will add keys to this new topic. The notation of the topics and keys is in Matlab style, which means that every valid Matlab statement is possible here. For example, Matlabs comment character (%) can be utilized. An example of a block file is shown below. In this example, all minimally required topics with their keys are shown.

<pre>[DataSources]

Line 210: Line 211:

[Files]

−

[[ExperimentDefinitionFile~~|Experiment Definition File]]~~ = '/Volumes/Data/ExpDefs/SubRhythm/SubjectiveRhythm.xls'

+

ExperimentDefinitionFile = '/Volumes/Data/ExpDefs/SubRhythm/SubjectiveRhythm.xls'

−

[[OutFolder~~|Out Folder]]~~ = '/Volumes/Data/Experiment/'

+

OutFolder = '/Volumes/Data/Experiment/'

[Experiment]

Line 217: Line 218:

</pre>

−

Additional possible topics with their keys are listed [~~.DocsSectionsBlockFile~~ here].

+

Additional possible topics with their keys are listed [[BrainStreamBlockFile|here]].

−

In addition to the listed topics and keys you can add your own topics and keys, as long as they are not used by BrainStream itself. The advantage is that these items are readily accessible for your own written [~~.DocsSectionsBuildingExperiments~~#SecUserFun user defined functions] throughout the whole experiment. Information in the block files can be accessed using the [~~.DocsSectionsProgrmmersGuide~~#GetBlockVal bs_get_blockvalue] function.

+

In addition to the listed topics and keys you can add your own topics and keys, as long as they are not used by BrainStream itself. The advantage is that these items are readily accessible for your own written [[#SecUserFun|user defined functions]] throughout the whole experiment. Information in the block files can be accessed using the [[BrainStreamProgrmmersGuide#GetBlockVal|bs_get_blockvalue] function.

Line 262: Line 263:

All keys defined under topic CommonStimulusSettings in block file block1.blk will be added to the StimulusSettings topic.

−

Note that the block file to which you refer must be in the same folder as where the current processed blockfile is located or on the [~~.DocsSectionsPathsFolders~~ Matlab search path].

+

Note that the block file to which you refer must be in the same folder as where the current processed blockfile is located or on the [[BrainStreamPathsFolders|Matlab search path].

Wiki-admin

Bureaucrats, Administrators

1,658

edits

Changes

BrainStreamBuildingExperiments (view source)

Revision as of 10:14, 26 September 2018

Navigation menu

Search