Response

Main table where each row describes a response in a trial.

note

The information in this table should be sufficient for most analyses, but more detailed information may be linked from other tables via identifiers (response_id and trial_index).

Key

Field	Type	Requirement	Description
response_id	PRIMARY KEY	required	A unique identifier assigned to responses in temporal order, meaning that larger IDs correspond to more recent responses that occurred later in time. This ID is unique within this table; no two rows share the same value.

Context

Field	Type	Requirement	Description
study_name	string	required	The name of the study or experiment.
group_name	string	optional	Subjects may be assigned to different groups. Typically, different groups will have different experiences within a study.
agent_id	string	required	A unique identifier assigned to the agent (typically person) generating the responses. This ID tracks their participation and responses throughout the study. See Agent table.
session_index	integer	required	When there are multiple sessions, this variable indicates the order of each session (i.e., the first session completed by the subject has session_index = 1, the second session has session_index = 2; even if the second session is an exact repetition of the first one).
session_uuid	string	optional	A globally unique identifier (UUID) for the session, assigned by the recording engine when the session starts. Unlike session_index (a per-subject ordinal), session_uuid identifies the session across datasets and systems; it is the value event streams refer to when scoping events to a session.
activity_index	index	optional	When subjects complete multiple activities (e.g., a cognitive test followed by a questionnaire), this variable indicates the order of each activity (i.e., the first activity completed by the subject has activity_index = 1, the second activity has activity_index = 2; even if the second activity is an exact repetition of the first one).
response_index	index	optional	The 1-based ordinal position of this response within the subject's participation in the study. response_index is nested within subjects — not within any lower-level construct (session, activity, block, or trial) — so the counter starts at the subject's first response and increments to their last without ever resetting. Its maximum value for a given subject equals the number of responses recorded from that subject in the study.

Task

Field	Type	Requirement	Description
language	string	optional	The language the task was completed in, expressed as a two-letter code within the ISO_639-1 standard.
instrument_id	string	required	The unique identifier of the instrument used for collecting data (e.g., the name of the computer script used to run the test). Unique in the Instrument table and corresponding files in the instruments/ folder.
instrument_repetition	integer	optional	The number of times this particular instrument has already been completed anytime in the past by this particular subject in this study. This variable has a value 0 the first time an instrument is used.
timeline_id	string	optional	Timelines are specific parameterization of an instrument and their identifiers are unique within the corresponding table for the instrument in the instruments/ folder.
timeline_repetition	integer	optional	The number of times this particular timeline has already been completed anytime in the past by this particular subject in this study. This variable has a value 0 the first time a timeline is completed.
multitask_type	enum	required	Subjects may be required to perform multiple tasks at the same time. This variable indicates the type of multitasking required.
task_index	index	optional	when multitask_type is not empty, task_index refers to each of the individual tasks. For example, for auditory-visual dual N-back, task_index=1 is the auditory task and task_index=2 is the visual task.
subtrial_count	integer	optional	The number of subtrials (successive dependent stages, each with its own stimulus → response → outcome cycle) that make up this trial; equals the largest subtrial_index among this trial's rows in the Subtrial table. Derived; 1 for simple single-stage trials.
job_type	string	optional	The general type of operation the subject needs to perform. The job typically is expressed as a verb (e.g., "recall", "sort") and can be the same for different instruments (e.g., Digit Span test and Spatial Span test both have a job of type "recall-forward").
job_description	string	optional	The more specific description of a job, which gives more information about what the participant sees and has to do. Whereas the job_type typically uses only verbs and adjectives, the job_description also contains nouns (e.g., “recall-digits-forward”, “recall-letters-backward”).
job_repeat	enum	optional	Whether this trial's job has not been seen before in this timeline (i.e., specific version of the instrument).
block_index	index	required	Refers to the order in which this block has been experienced by the subject. When there are multiple blocks, this variable indicates the order of each block (i.e., the first block completed by the subject has block_index=1, the second block has block_index=2, even if the second block is an exact repetition of the first one).
block_name	string	optional	The name of a particular block in a timeline. If the same block is completed twice in a row, they would have different block_index values (1 and 2, respectively) but they would have the same block_name (e.g., “NB_timeline1_block1”). More details about the block_name is available in the Instrument table.
block_type	enum	required	Specifies the experimental role of the block (e.g., tutorial, practice, test, instruction).
transformation_name	string	required	Refers to the specific events-to-trials function used to construct rows of this table from raw events. The transformation (or projection in DDD terminology) embodies the definition of a trial for a particular task. The transformer name refers to a code in the format of a function f(trial_state, event) => trial_state, where event is the event occurred during the performance of the task, and trial_state is the data stored for the trial. The final state of a trial is thus the result of applying a sequence of projections such that trial = f(f(f(initial()), e), e), e).'
trial_index	id	required	Sequential identifier representing number of times transformation rule to the events occurred. It increases with each re-computation of the trial based on updated or newly received events.
episode_index	index	optional	Episodes are temporally distinct bins of time (no overlap and discrete). The binning of the time into successive episodes depends on the task; it is mostly used and necessary to group data in cases where two distinct trials occurred at the same time (e.g., dual N-back).
trial_start_datetime	datetime	required	The datetime at which the first event of the trial occurred.
trial_seed	integer | string	optional	Random seed used in the trial (if any).

Stimulus

Field	Type	Requirement	Description
stimulus_index	list[index]	optional	Indexes in chronological (or spatial) order the stimuli shown within an instrument (counting one stimulus per response). stimulus_index may for instance be used to refer to the nth question asked within a questionnaire.
stimulus_id	integer	required	Is a unique identifier for the (unitary, set or sequence of) stimuli presented during a trial; if those exact same stimuli are repeated in a different trial, that trial would have the same value for stimulus_id. stimulus_id may also be used to refer to a specific message or question in a questionnaire.
stimulus_type	enum	required	BDM distinguishes the following stimulus types: messages and questions
stimulus_onset	float	optional	Duration between the start of the trial and the appearance of the stimulus, in seconds.
stimulus_panel_count	integer	optional	The number of panels or screen areas stimuli may appear on during the trial. For example, in a task where stimuli to be compared are presented on the left and right side of the screen, stimulus_panel_count = 2.
stimulus_structure	enum	optional	We distinguish three stimulus structures: unitary, set, sequence
stimulus_structure_source_type	enum	optional	Indicates the type of method used to generate the stimulus_structure (this is relevant when a trial displays a sequence of or set of stimuli): none, preset, generator
stimulus_structure_source	string	optional	Refers to the specific generator used to produce the stimulus_structure (e.g., sequence of digits in a digit span test). When no generator was used, this variable has a value of none.
stimulus_set_size	integer	optional	The number of different values each presented stimulus could have taken. This value gives an indication of the complexity of the stimulus space. When this number is large we set this variable to infinity, when for any reason it was not computed, it has a value of NA.
stimulus_count	integer	optional	The number of stimuli shown to the participant during the trial.
stimulus_source_type	enum	optional	A stimulus is typically created using a particular procedure/algorithm ("generator") or is sampled from a particular set ("set"). This variable indicates which of these two applies for the current stimulus.
stimulus_source	string	optional	Refers to the specific generator or set the stimulus belongs to. Stimuli that stem from the same source have the same data scheme and could thus be described in a table named after stimulus_source (i.e., stimulus_source indicates which table contains the full information about the stimulus; e.g., "digit1to9").
stimulus_index_in_source	integer	optional	Index of the stimulus within the table referred to by stimulus_source. : For example, if stimulus_source == "digit1to9", stimulus_index_in_source = 1 refers to "1" while for stimulus_source == "LettersAtoD", stimulus_index_in_source = 1 refers to "A".
stimulus_position_index	integer	optional	Refers to discrete positions on the screen the stimulus may appear on. The set and ordering of possible positions depends on the test. Whenever possible, it follows a natural order (left to right, top to bottom), but in free-form layouts, indices are arbitrary.
stimulus_description	string	optional	A human readable, compact description of the main aspects of the stimulus. The description for a given stimulus depends on the task but follows a specific template for a given task. Because of this, it looks like the stimulus_description could be "parsed" and "tidied"---however, this is not the intention; parsed/tidied data will be available in other tables; description is for human readability and facilitates the understanding of the data.
stimulus_role	enum	optional	A stimulus may play different roles within a trial. Below is a list of some possible roles:

Option

Field	Type	Requirement	Description
option_source_type	enum	optional	A set of options is typically created using a particular procedure/algorithm (“generator”) or is sampled from a particular set (“set”). This variable indicates which of these two applies for the current options.
option_source	string	optional	Refers to the specific generator or set that determined the options on a given trial. Option that stem from the same source have the same data scheme and could thus be described in a table named after option_source (i.e., option_source indicates which table contains the full information about the option set).
option_count	integer	optional	The number of options the participant can choose from on a given trial.
option_id	integer	optional	Is a unique identifier for the option (set or generator) used on a given trial.
option_data_type	enum	optional	Describes the type of data this option entails. Possible values include:
measurement_type	enum	optional	Describes the type of measurement implied by Option which in turn has implications on how that data should be processed during analysis; takes a value in:

Input

Field	Type	Requirement	Description
input_interface_type	enum	optional	Refers to the type of interface subjects used to input actions. Possible values include (non-exhaustive):
input_action_type	enum	optional	Refers to the type of action the subject performs to give a response. Possible values include (non-exhaustive):
input_count	integer	optional	The number of inputs (i.e., actions) the user made during the trial.

Expectation

Field	Type	Requirement	Description
expected_response_option_index	integer	optional	The index of the option the subject is expected to choose from the set of options.
expected_response_description	string	optional	A description of the expected response using the same convention as response_description.

Response

Field	Type	Requirement	Description
response_structure	string	optional	The structure of the response required by the subject; can take values in:
response_type	enum	optional	The form of the response act — what kind of answer is collected: choice, rating, ranking (selected from what is presented) or production, motor (generated by the subject). Declared per response even where derivable from other fields, because the derivations then serve as validation checks rather than the source of truth.
response_count	integer	optional	Each trial contains by definition only one response. However, when response_structure is other than unitary, a response comprises multiple pieces of information (e.g., “3-5-7” could be one response in the digit span task and this response contains three components, namely “3”, “5” and “7”). response_count refers to the number of components that make up a response (not the number of responses within a trial).
response_option_index	integer	optional	The index of the option the participant chose, starting from 1.
response_description	string	optional	A description of participant’s response; typically the description of the option that was chosen.
response_numeric	float	optional	A numeric value associated with a particular response; this could be a numeric value entered directly by the subject or the numeric meaning of a selected option (for example, the choice of option "Never" may be associated with the numeric value of 0). Note that this variable describes the subject's response; it does not describe the value (e.g., correctness or goodness) that is associated with that response.
response_time	float	optional	The duration, in seconds, between the earliest possible time a response could have been completed and the moment that response was actually completed (and NOT when it was initiated).
response_datetime	datetime	optional	The datetime corresponding to the completion of the response.
response_validation_time	float	optional	In some cases, subjects may need to press an extra key to validate previous responses. When relevant, this variable may encode this duration.
response_initiation_time	float	optional	In some cases (e.g., a reaching movement) it might be useful to encode when a response was initiated.
response_skipped	boolean	optional	In some cases (e.g., in some questionnaires), subjects have the option to skip a question.
timed_out	boolean	optional	Some tasks require subjects to give a response within a certain time limit. When subjects fail to respond before that time runs out, timed_out is set to TRUE.

Evaluation

Field	Type	Requirement	Description
accuracy	float	optional	A task-dependent accuracy measure ranging from 0 to 1 (inclusive).
correct	boolean	optional	Indicates whether the response matches the expected response (i.e., correct = TRUE) or not (i.e., correct = FALSE).
score	float	optional	A numeric value associated with a particular response in a given context. This variable may be used to compute a performance metric or a questionnaire level index (e.g., a well-being score).
evaluation_label	enum	optional	There are several labels that can be assigned to a given response to specify what that response means in terms of evaluation within a task. The most general terms are "correct” and "error" (which are already given by the correct variable). There are however more specific sets of terms that may apply in different contexts. For example, in a signal detection task, it is common to use labels from the signal detection theory framework (i.e., “hit”, “miss”, “false alarm”, “correct rejection”). In other contexts, researchers might use terms like “omission” or “commission” errors or even things like “perseveration” error (e.g., in the Wisconsin Card Sorting Test). Note that these terms are not always well defined or exclusive. For example, a “hit” is also a “correct” response and a “false alarm” may be synonymous to “commission error”. Whenever possible use the more specific terms (i.e., always use “hit” rather than “correct” when applicable). Here are few evaluation labels that are commonly used:

Feedback

Field	Type	Requirement	Description
feedback_description	string	optional	Lists the different kinds of feedback that were shown on a given trial. When multiple types of feedback were used, feedback will list them using ; as a separator. If a given type of feedback was shown multiple times during a trial, that feedback type is listed only once (i.e., feedback_description does NOT represent the sequence of feedbacks). The possible values for feedback are:

Outcome

Field	Type	Requirement	Description
outcome_description	string	optional	Describes the observable consequences of the subject's response (e.g., "the opened box is empty").
outcome_numeric	float	optional	A numeric value describing the observable consequences of the subject's response (e.g., +3 points).

Accessory

Field	Type	Requirement	Description
additional_measures	string	optional	Indicates whether additional measures have been recorded during this trial and if so what kind of measures they are. Possible values include (non-exhaustive):

Experimental Design

Field	Type	Requirement	Description
adaptive_method_name	enum	optional	Specifies the adaptive procedure used to modify instrument parameters in response to subject performance (e.g., staircase).
adaptive_method_config	string	optional	More detailed configuration for the adaptive method, including initial values, step sizes, and termination criteria.
adaptive_parameter_name	string	optional	Specific instrument parameter that is dynamically modified based on the subject's performance.
adaptive_parameter_value	any	optional	The specific value of the instrument parameter that was used for this trial. This value is updated as the adaptive algorithm adjusts the parameter based on the subject's responses.
adaptive_parameter_value_next	any	optional	The next value of the adaptive parameter that will be used in the subsequent trial, as determined by the adaptive algorithm.