BrainStreamPlugIns

Importing tables

Introduction

When building new experiments it is often possible to make use of parts that have been developed previously and are shared among the different type of experiments. For this reason, BrainStream supports a mechanism to import parts of an earlier designed experiment into your current experiment definition table, which may save users a lot of development time. Also, common parts can be maintained better only having to update that single experiment definition table that is referred to by all other experiments. Like ordinary experiment definition tables, imported tables can specify any number of actions for multiple markers at different timepoints. Importing definitions from other tables also results in a more structured and readable design since functional parts of the design can be split up into different tables. The import option also incorporates a mechanism to copy a set of definitions to an entire list of markers, which prevents lots of repeated definitions that would heavily obscure the experiment overview.

The general import behaviour can be described as reading the content of the imported table and process it identical to the case where the import-table content would be directly specified in the original table. However, imported actions are treated as defaults and therefore, if the line with the import reference in the original table also defines actions, they will overwrite the defaults retrieved from the import-table.

You can import definitions from another table by placing the @ symbol followed by the table name in the marker column of your main Actions table. If your imported table resides in an excel file with multiple sheets, you can also refer to a specific sheet by adding the name of the sheet after the tables's name. For example, if you want to use Sheet1 of a table called MyTable you would specify '@MyTable.xls Sheet1' in the marker column of your Actions table.

Import tables

Imported tables completely define a part of an experiment. If a DATA timepoint is specified for one or more actions, the table needs its own DataSelection table.

In order to import a table, you only have to specify the reference to it in your main Actions table. A simplified example of an imported table is given below:

Main Actions Table
marker	time	function	All_Pictures	Picture
BS_INIT	EVENT	init_bci, bs_send_buffer_marker('start_bci','eeg',0,'now')
start_bci	EVENT	bci_processing_pipeline
@Pictures	EVENT	show_picture	get	get

Main Dictionary Table
marker	type	value
start_bci	stimulus	1

At the BS_INIT marker, the BCI experiment will be initialized and subsequently a BCI processing pipeline will be executed. Let's assume that inside this processing pipeline is a function that inserts a marker whenever a picture needs to be shown. The presentation of pictures is taken care of by the Pictures table (@Pictures):

Imported Actions table
marker	time	function	All_Pictures	Picture
BS_INIT	EVENT	load_pictures{'instruction.jpg','fixation_cross.jpg','continue.jpg','end.jpg'}	[],get,put	[],put
instruction	EVENT			'instruction.jpg'
fixation_cross	EVENT			'fixation_cross.jpg'
continue	EVENT			'continue.jpg'
end	EVENT			'end.jpg'

Imported Dictionary table
marker	type	value
instruction	stimulus	11
fixation_cross	stimulus	12
continue	stimulus	13
end	stimulus	14

At the BS_INIT marker, first the user defined variables All_Pictures and Pictures are initialized. Then the function load_pictures() is executed, which loads all pictures that are needed for the experiment and stores them in the variable All_Pictures. Finally, the content of the user defined variables is copied to the global variables with the put statement.

Whenever one of the markers instruction, fixation_cross, continue or end is inserted, the imported Actions table specifies that the content of the variable Picture should be changed to the name of the corresponding picture. After this has happened, the function show_picture (in the main Actions table) will use this new variable content for showing the picture.

The advantage of the imported Pictures table in the example above is that the main Actions table remains concise. In the Table Expansion section you can see how the experiment definition tables would look if no import had been used. In addition, other experiments that make use of the same pictures, can do so simply by referring to this same imported table. Any changes to this table, for example changing the pictures that are to be used, will automatically be incorporated in all the experiments that are using the same imported table.

Table expansion

In the examples above, only one table was imported. However, the main table can specify references to more imported tables, or an imported table itself may import another table. The expanded experiment definition table shows you how your experiment looks when the main table and all imported tables are combined.

At the start of each BrainStream experiment, the main experiment definition tables and all references to import-tables will be combined into one table, a process called 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. Thus, in the example mentioned above, the expanded tables would look like this:

Expanded Actions Table
marker	time	function	All_Pictures	Picture
BS_INIT	EVENT	init_bci, bs_insert_marker('start_bci',0), load_pictures{'instruction.jpg','fixation_cross.jpg','continue.jpg','end.jpg'}	[],get,put	[],put
start_bci	EVENT	bci_processing_pipeline
instruction	EVENT	show_picture	get	'instruction.jpg', get
fixation_cross	EVENT	show_picture	get	'fixation_cross.jpg', get
continue	EVENT	show_picture	get	'continue.jpg', get
end	EVENT	show_picture	get	'end.jpg', get

Expanded Dictionary Table
marker	type	value
start_bci	stimulus	1
instruction	stimulus	11
fixation_cross	stimulus	12
continue	stimulus	13
end	stimulus	14

When the experiment is finished, you can find the expanded tables in the [.DocsSectionsLogFile Log file]. Additionally, if you are using the BrainStream editor, you can view your expanded tables before running the experiment by clicking on the 'Expand table' button.