the @key class

overview

  • A @key object contains one or more keys.
  • Keys are necessary in order to analyze specific data from a @cortex object. Each key contains:
    • criteria to select subsets of trials from a @cortex object
    • duration and position of an analysis epoch for the selected trials
  • To create a @key object use the constructor function.
  • To retrieve parts of the object or set their values, use the dot-properties of the @key class.
  • Individual keys or whole @key objects are required arguments for most @cortex methods.

object structure

Like all Matlab objects, a @key object is essentially a structure. Each key in the object has the following fields:

field
default
 meaning type
label
'noname'
 the name of the key character string
start
0
 beginning of analysis window (ms offset from cue event) integer scalar
finish
300
 end of analysis window (ms offset from cue event) integer scalar (>start)
cues
23
 one or more events ("encodes") to which analysis windows lock on array of unsigned integers
or -1 to include all
trials
-1
 range of "absolute" trials (from 1 to c.trials)
relat (*)
-1
 range of trial header values to match; a @cortex object trial will be included in the analysis if each of its trial header values is found in the corresponding key field;

in order to include all possible values for a header field, set the corresponding key field to -1

note that all @cortex methods internally call the function trialset to perform trial selection based on a key;
block
-1
cond
-1
rept
-1
type (**)
-1
given (**)
-1
resp (**)
0

(*) the relative_trial field contains the trial# recorded in the trial header. Within the same @cortex object, trial numbering restarts from 1 at the beginning of a new run. The field trials refers instead to the "absolute" trial number for the whole object, which spans 1:c.trials.

(**) the trial header fields related to behavioral response and trial outcome have created some confusion in the past, and should be interpreted as follows:

  • type_of_trial: a property of the condition; typically meant to indicate the expected behavioral response for that condition
  • given_response: the actual behavioral response (formerly and mistakenly referred to as 'expected')
  • response_error: the trial outcome (a 0 means no error, i.e., a correct, rewarded trial)

multiple-key objects

there are two ways to create objects with more than one key. First, you can concatenate existing objects by simply using the 'plus' sign:

>> k1=key('one',50,250,23,1,1,0,-1,-1,-1,-1,-1)
>> k2=key('two',50,250,25,2,1,0,-1,-1,-1,-1,-1)
>> k3 = k1+k2;
>> k3.print

Content of the @key object:
    ===========================================
    sta fin cue con blo res tri typ exp rep rel
Key #1: one
    50 250 [ 23] [ 1] [ 1] [ 0] [ -1] [ -1] [ -1] [ -1] [ -1]
Key #2: two
    50 250 [ 25] [ 2] [ 1] [ 0] [ -1] [ -1] [ -1] [ -1] [ -1]

More often, you will create objects based on a text file, as described in the 3rd syntax of the constructor

simple keys and complex keys

It is not always possible to specify with a single key all the trials that belong together in the analysis. For example, you might want to include in the same analysis trials of conditions [6:10], where the cue event is 25, and trials of conditions [16:20], where the cue event is 27. This can be accomplished by creating "complex" keys, i.e., keys composed of more than one subkey.

If two consecutive "keys" have the same label, they will actually be considered as subkeys of the same key. This can be done in the KEYFILE, as in the following example:

% this file is named 'mykeys.key'
label        start finish cues conds resps
one_analysis  -100  200    25   6:10   0 % this is a comment
one_analysis  -100  200    27  16:20   0
another_one   -100  200    25  11:15   0
another_one   -100  200    27  21:25   0
another_one   -100  200    28  26:30   0

>> k1=key('mykeys.key');
>> k1.length
ans =
     2

>> k1.size
ans = 
     2  3
  • k.len reports the number of keys in the object
  • k.size is an array of k.len length, indicating the number of subkeys in each of the keys

Subkeys can also be created by concatenating @key objects at the command line:

>> k2=key('another_one',50,250,23,1,1,0,-1,-1,-1,-1,-1);
>> k3=k1+k2;
>> k3.size
ans =
     2  4