Importing tables

Generate current PDF

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

Topic revision: r14 - 17 Nov 2014 - 08:23:57 - PhilipVanDenBroek
BrainStreamDocs.DocsSectionsPlugIns moved from BrainStream.DocsSectionsPlugIns on 14 Nov 2011 - 10:26 by MarjoleinVanDerWaal - put it back
 
This site is powered by the TWiki collaboration platformCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback