BrainStreamSmartGetPut

Dedicated get and put actions

There are cases in your experiment design where it would be handy to update information to the global variables in a user definable way, for instance to partially update or retrieve a variables structure field or to collect data in specific data structures. Such a feature can be implemented through dedicated get or put actions.

If you have plans to implement such custom-made functions, you should read following paragraph that explains how this can be done. Otherwise, jump directly to the next paragraph that demonstrates some examples that come standardly with BrainStream and demonstrate dedicated get/put actions to implement four data structures and direct update/retrieval from structure fields.

Building custom-made dedicated get and put actions

Those functions should obey to a fixed format, where each format is different for get, put and a new get+mod actions. Also, function names should always be prefixed with either of the following options: 'get_', 'pop_', 'put_', 'push_', 'load_' or 'save_' in order to be recognized by BrainStream as a dedicated get/put action. The functions should be copied to the BrainStream $BRAINSTREAM_FOLDER/core/getput/ folder.

get:

general format implementation func:

      function ret = get_fun(var, varargin)
         get_fun: the function name of your dedicated ''get'' action  
         var: the global variable
         varargin: any additional user input arguments 
         ret: returned content derived from global variable  

specification in the table:

      get_fun(field,varargin)

Notice the difference between function format and what is specified in your experiment definition table. In the table, the first argument field is the name of the event structure field that gets the content assigned. Also, the global variable var is automatically added as input argument by BrainStream, like this is also happening in the table for functions and the first event input argument.

         field: content is stored in this field of local event structure 
         varargin: any additional user input arguments  

examples:

get_item (data structures: array, shiftreg)  
load_var

put:

general format implementation func:

      function var = put_fun(var, update, varargin)
         put_fun: the function name of your dedicated ''put'' action 
         var: the global variable
         update: content to update the global variable 
         varargin: any additional user input arguments 

specification table:

      put_fun(content,varargin)
         update: content to update the global variable, i.e., a constant, 
                  function or name of event structure field (prefix name with a dot) 
         varargin: any additional user input arguments  

examples:

      put_item, push_item, put_new, put_clear (data structures: array, shiftreg, stack, queue)       
      save_var 

get+mod:

general format implementation func:

      function [ret, var] = get_fun(var, varargin) 
         get_fun: the function name of your dedicated combined ''get+mod'' action 
         var: the global variable 
         varargin: any additional user input arguments 

specification table:

      getmod_fun(content,varargin)        
         content: constant, function or name of field for event structure 
         varargin: any additional user input arguments  

examples:

      pop_item (data structures: stack, queue) 

NOTE: this is a special newly introduced operation since it combines both a get- and a mod-operation. This combined action is necessary to implement data structures with pop behaviour, where a get operation not only retrieves some content from the data structure, but also modifies the content and thus implicitly also involves a mod operation to update the corresponding global variables content.

Important: Function names should always be prefixed with either of the following options: 'get_', 'pop_', 'put_', 'push_', 'load_' or 'save_' in order to be recognized by BrainStream as a dedicated get/put action. The functions should be copied to the BrainStream $BRAINSTREAM_FOLDER/core/getput/ folder.

Examples of custom-made get/put actions

From abovementioned smart get/put general function formats, users can derive their own custom made function to achieve dedicated get/put retrieval/updating functionality. BrainStream comes standardly with an implementation of the four data structures:

• queue
• stack
• array
• shiftreg (shift register)

These data structures are default available to the user and are modifiable via the functions:

• put_new: initiate a new data structure (all four data structures)
• put_clear: clear previously initiated data structure (all four data structures)
• put_item: put new content to data structure ( array )
• push_item: push new content to data structure ( stack, shiftreg, queue )
• pop_item: pop item from data structure ( stack, queue )
• get_item: get item from data structure ( array, shiftreg )
• get_whole: get entire data returned (all four data structures)

Note: The format below is how users should specify it in their experiment definition tables.

put_new(type, dims, len, returnascell [, field]) for: array, shiftreg

put_new(type, dims, returnascell [, field]) for: queue, buffer, stack

• dims: dimensions of added content (empty if not known) <numeric>
• len: length of array or shift register <numeric>
• returnascell: set to zero if entire content can and should be returned as numeric matrix <1,0>
• field: assign update to structure field of global variable <char>

put_clear([field])

• field: assign update to structure field of global variable <char>

put_item(update, idx [, field])

• update: the content to be updated (either constant value or a field of the event structure, literally specified and prefixed with a dot <any type>
• idx: index position of entry to be updated <number>
• field: assign update to structure field of global variable <char>

push_item(update [, field])

• update: the content to be updated (either constant value or a field of the event structure, literally specified and prefixed with a dot <any type>
• field: assign update to structure field of global variable <char>

pop_item(.event_field [, field])

• .event_field: Brain Stream assigns returned result to event.event_field <char>
• field: retrieved from global variables structure field <char>

get_item(.event_field [,idx, field])

• .event_field: BrainStream assigns returned result to event.event_field <char>
• idx: index position of entry to retrieve <number>
• field: retrieved from global variables structure field <char>

get_whole(.event_field [, field])

• .event_field: BrainStream assigns returned result to event.event_field <char>
• field: retrieved from global variables structure field <char>

Some other examples:

put_field(update, field)

• update: the content to be updated (either constant value or a field of the event structure, literally specified and prefixed with a dot <any type>
• field: assign update to structure field of global variable <char>

get_field(.event_field, field)

• .event_field: BrainStream assigns returned result to event.event_field <char>
• field: retrieved from global variables structure field <char>

save_var(update, name [, option]) % Note: it also incorporates a put action, i.e., it updates the global variable and saves it to a user-specified file.

• update: the content to be updated (also updates global variable!) <any type>
• name: name of the file (Note: folder is determlined by blocksettings for Out Folder) <char>
• option: Matlab has different options on how to compress the variable before saving it. <char>

load_var(.event_field, name)

• .event_field: BrainStream assigns returned result to event.event_field <char>
• name: name of the file to load from <char>

Todo: Add example table to demonstarte how this can be used in an experiment

Examples of dedicated get and put actions

Example dedicated put: stack
marker	time	function	trials	sequence
BS_INIT	EVENT		[],put_new('stack')
trial	DATA	process_data	push_item(data)
BS_END	EVENT		get_whole(.sequence)	save

The BS_INIT event initialises a new stack ( put_new('stack')), configured to collect items in a cell-array (omitted input argument returnascell defaults to cell-type). For every incoming trial event, event.data is pushed ( push_item(.data)) to the stack (no pops so we are just collecting all data here). At the BS_END event the information on the stack is merged into a cell-array ( get_whole(.sequence)) as field of the event structure ( event.sequence), which is then saved to disk via the save keyword for the sequence variable.