Error and response codes: what's the deal?

Three different header values in CORTEX describe the expected behavioral response and the outcome of the trial. There has been some confusion about how these values are assigned and what they mean and, unfortunately, at one point I contributed to this confusion. I was originally misled by the "official" CORTEX timing file reference manual, in which the family of functions response_XXX() was documented in the following way:

void response_before_test(int expected_response);

purpose: records in the trial header the error code (#7) for a behavioral response before the presentation of the test stimulus (i.e. an aborted trial). Also records in the header the code for the expected response for this trial. The status field in the USER screen will reflect this message.

...which was wrong, because the int argument really represented the actual behavioral response given by the subject, and not the expected response. The expected response is really one of the properties of the condition, although a different name (TRIAL_TYPE) is used. During the trial, the condition's TRIAL_TYPE is written in the trial header field expected_response.

The following table summarizes the labelling and meaning of the 3 header fields:

  the expected response the actual response the trial outcome
meaning what the monkey is supposed to do to get the trial right, or what "type" of trial this is what the monkey actually did during the trial (e.g., right lever turn) the type of error
(where 0 = no error)
CORTEX variables and documentation expected_response response response_error
source determined by the current condition's TRIAL_TYPE field assigned during the trial by the timing file assigned during the trial by the timing file
"old" timing file functions N/A determined by the value in parens in a response_xxx() call determined by which response_xxx() is called
"new" timing file functions set_expected_response()
[note that calling this function overrides the current condition's TRIAL_TYPE value]		 set_response() set_response_error()
@cortex and @key class dot-properties typ, short for type_of_trial giv, short for given_response (previously, and mistakenly, called exp) res, short for response_error

the trial outcome: response_error codes

The most straightforward way to record the trial outcome in the trial header of the data file is to call the function:

set_response_error(RESPONSE_ERROR);

where RESPONSE_ERROR is one of the values included in the table below. Before this function existed, you had to call one of the following "old" timing file functions, depending on the type of error:

code "old" timing file function status screen CORTEX constant Typical use
0 response_correct (short) Done (Ok) NO_ERROR a correct, rewarded trial
1 response_missing (short) No Response NO_RESPONSE no behavioral response when one is expected
2 response_late (short) Late LATER_THAN_EXPECTED a response occurred too late
3 break_fixation_error (void) Lost Fixation BREAK_FIXATION fixation was lost at any time during the trial
4 no_fixation (void) No Fixation NO_FIXATION fixation was never reached
5 response_early (short) Early EARLIER_THAN_EXPECTED behavioral response with a reaction time that is too short to be "true"
6 response_wrong (short) Not Expected NOT_EXPECTED wrong behavioral response (e.g., left- instead of right-lever)
7 response_before_test (short) Before Test BEFORE_FIRST_TEST behavioral response before the onset of a target
8 response_no_bar_down (short) No Bar Down NO_BAR_DOWN the bar was never held (or was never in the upright, resting position)
9 N/A Running RUNNING_TRIAL internal CORTEX use only

Where:

code this number gets written in the trial header of the data file; it represents the trial outcome
"old" timing file function calling one of these functions writes the corresponding code into the trial header; the function argument is the "actual" behavioral response; note that in two cases (#3 and #4) there is no argument because the trial is presumed aborted before a behavioral response
status screen these strings appear on the CORTEX user's screen
CORTEX constant these strings are used internally by CORTEX as replacements for the numerical codes; they are also defined as constants in css_inc.h

Note that, since the response_error trial header code is a short integer, by using set_response_error() you are not limited to codes 0 through 8 to classify error codes. If you come up with your own scheme, however, make sure it's nicely documented, because outside of the convention summarized above people won't know how to interpret your data files.

the actual response: response codes

Response codes
#
 meaning
0
 NO_TRIAL_TYPE
1
 MOVING
2
 IMMEDIATE_RELEASE
3
 DELAYED_RELEASE
4
 TEST1_LEFT_LEVER
5
 TEST1_RIGHT_LEVER
6
 TEST2_LEFT_LEVEL
7
 TEST2_RIGHT_LEVER
8
 TEST3_LEFT_LEVER
9
 TEST3_RIGHT_LEVER
10
 TEST4_LEFT_LEVER
11
 TEST4_RIGHT_LEVER
12
 TEST5_LEFT_LEVER
13
 TEST5_RIGHT_LEVER
14
 ON_OFF
15
 EYE_MOVEMENT
16
 TEST6_LEFT_LEFT
17
 TEST6_RIGHT_LEVER
18
 TEST7_LEFT_LEVER
19
 TEST7_RIGHT_LEVER
20
 TEST8_LEFT_LEVER
21
 TEST8_RIGHT_LEVER
22
 TEST9_LEFT_LEVER
23
 TEST9_RIGHT_LEVER
24
 TEST1_EXTRA_LEVER
25
 TEST2_EXTRA_LEVER
26
 TEST3_EXTRA_LEVER
27
 TEST4_EXTRA_LEVER
28
 TEST5_EXTRA_LEVER
29
 TEST6_EXTRA_LEVER
30
 TEST7_EXTRA_LEVER
31
 TEST8_EXTRA_LEVER
32
 TEST9_EXTRA_LEVER

The most straightforward way to record the behavioral response provided by the monkey in the trial header of the data file is:

set_response(RESPONSE);

where RESPONSE is a short integer. Before this function existed, this value passed to CORTEX as an argument in the response_xxx() function call. In the "official" CORTEX documentation there is a list of RESPONSE values, reported in the table to the right. Personally, I don't find this list very useful: what if, for example, you had 4 stimuli on the screen and wanted to encode a saccade to each one of them? Anyhow, nothing prevents you from setting the RESPONSE field to any value you like (as long as you document it!)

the expected response: trial types

The expected_response code is a property of the condition, and is automatically written in the trial header by CORTEX during the trial. Note, however, that the function:

set_expected_response(EXPECTED_RESPONSE);

allows you to override the condition setting; this can be handy if you don't really need a predefined TRIAL_TYPE, but woud like to write a custom piece of information in the trial header, as the experiment runs.