the @key class constructor

creates a @key object from scratch or from a disk file

Syntax

KEY(LABEL,START,FINISH,CUES,CONDS,BLOCKS,RESPS,TRIALS,TYPE,GIVEN,REPT,REL) creates and returns a single-key object and assigns the values passed as arguments to the following corresponding fields:

  • LABEL: the name of the key;
  • START / FINISH: the offset in ms from the cue event;
  • CUES: the cue events, an array of encodes to time-lock analysis on;

    • The next 8 arguments are arrays of values that restrict analyses to subsets of trials:

  • CONDS: condition numbers
  • BLOCKS: block numbers
  • RESPS: response_error(s) (i.e., the trial outcome)
  • TRIALS: "absolute" trial numbers
  • TYPE: trial types (i.e., the expected response)
  • GIVEN: given responses (aka the "response")
  • REPT: repetition numbers
  • REL: "relative" trial numbers (trial # recorded in trial header)

note that passing -1 is equivalent to including all possible field values (e.g., if k.blocks == -1 then all blocks are included in the analysis performed by SPIKEMATRIX).

KEY without arguments returns a single-key object and sets its fields to the following default values: LABEL='noname', START=0, FINISH=300, CUES=23, RESPONSES=0; CONDITIONS = BLOCKS = TRIALS = TYPE = GIVEN = REPT = REL = -1.

KEY(KEYFILE) returns a multiple-key object created on the basis of the KEYFILE text file. The text file is composed of one header line and any number of key lines, as in the example below. These are the rules for a well-written KEYFILE:

  • the first line in the file must contain the header;
  • the first field in the header must be 'label';
  • the rest of the header can contain any combination, in any order, of the following valid fields:
    • start,
    • finish,
    • cues,
    • trials,
    • relative_trials,
    • conditions,
    • blocks,
    • repetition,
    • type_of_trial,
    • given_response
    • response_error
  • only the first 3 (case-irrelevant) characters are considered by the parser. Thus, you don't have to necessarily use the entire labels listed above
  • if a field is omitted in the keyfile, the default values (see table above) are automatically assigned by the constructor
  • each record must contain the same number of fields specified in the header, in the same order;
  • each field can be of any length in characters;
  • fields must be separated by any combination of spaces and tabs;
  • records can be separated by any number of empty lines;
  • the label cannot contain spaces, so use underscores if necessary (e.g., attend_away)
  • if you need to use spaces between values in a field, enclose the whole field in square brackets (e.g., [1 2 3:5])
  • you can add comments (MatLab style) either at the end of a record or on an empty line, but not between or within fields.

Notes

the @key class replaces the @rules class

Examples

Suppose you have the following text file named 'mykeys.key'

% this is a sample keyfile
label       start finish cues conds resps
red_vert     -100  200    23  [1:10 100]   0 % this is a comment
red_horiz    -100  200    25  11:20   0
blue_vert    -100  200    23  21:30   0
blue_horiz   -100  200    25  31:40   0
another_one  -100  200    27  41:50   0
% this last analysis is a weird one
yet_another  -150  300    [29 32]   -1    -1

You can create a @key object by calling the 3rd form of the constructor, and then list the object by using the print dot-property

>> k = key('mykeys.key');
>> k.print

Content of the @key object:
    ===========================================
    sta fin cue con blo res tri typ exp rep rel
Key #1: red_vert
    -100 200 [ 23] [ 1 2 3 4 5 6 7 8 9 10 100] [ -1] [ 0] [ -1] [ -1] [ -1] [ -1] [ -1]
Key #2: red_horiz
    -100 200 [ 25] [ 11 12 13 14 15 16 17 18 19 20] [ -1] [ 0] [ -1] [ -1] [ -1] [ -1] [ -1]
Key #3: blue_vert
    -100 200 [ 23] [ 21 22 23 24 25 26 27 28 29 30] [ -1] [ 0] [ -1] [ -1] [ -1] [ -1] [ -1]
Key #4: blue_horiz
    -100 200 [ 25] [ 31 32 33 34 35 36 37 38 39 40] [ -1] [ 0] [ -1] [ -1] [ -1] [ -1] [ -1]
Key #5: another_one
    -100 200 [ 27] [ 41 42 43 44 45 46 47 48 49 50] [ -1] [ 0] [ -1] [ -1] [ -1] [ -1] [ -1]
Key #6: yet_another
    -150 300 [ 29 32] [ -1] [ -1] [ -1] [ -1] [ -1] [ -1] [ -1] [ -1]