Response
Main table where each row describes a response in a trial.
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).
Summary view. Full reference → on behaverse.org/schemas.
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. Note: This identifier is used by other tables, for example Stimulus table which describes in greater detail the sequence of images shown during a trial, their timing, and visual properties. That table will refer to this id in order to link those descriptions (typically multiple lines in the Stimulus table) to a unique row in the Response table. |
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_id |
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. Range: index of session within subject. Note: We currently don’t use session_name, session_id and session_repetition in this table. |
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 session has activity_index = 2; even if the second activity is an exact repetition of the first one. Range: 1-based index of activity within the subject-level data. Note: See Studyflow table for more details. |
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. Range: id in the Instrument table. |
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. Range: 0-based |
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. Range: 0-based |
multitask_type |
enum | required | Subjects may be required to perform multiple tasks at the same time. This variable indicates the type of multitasking required. Range: - Empty: No multitasking, i.e., single-tasking. - concurrent: There are two independent tasks that need to be completed in parallel. - compound: The task requires multiple successive stages or involves tasks that are dependent/coupled. Note: If no multitasking was involved, leave this field blank. Note: This characterization of multitasking_type is rudimentary and will likely evolve in the future. |
task_index |
index | optional | when multitask_type is not empty, task_index refers to each of the individual tasks. For example, for auditoy-visual dual N-back, task_index=1 is the auditory task and task_index=2 is the visual task. Range: 1-based index. |
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). Range: - new: The job has never been seen before by this subject in the current study. - repeat: The job is the same as the previous trial. - switch: The job is different from the previous trial but has been seen prior in the timeline. |
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). Range: 1-based index of the block within the timeline Note: In questionnaires, block_index may refer to distinct pages where each page may contain multiple questions. |
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). Range: - tutorial: A simplified version of the test designed to teach participants how the test works. - practice: Typically identical to the main test blocks but are used to get subjects accustomed to the task in a no-stakes environment. - test: Primary blocks used to measure the desired behaviors. - instruction: Presents written and/or visual instructions to the subject. |
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).’ Note: - The transformation/projection encapsulates the domain rules that define a “trial” for a given task. It defines what constitutes a “trial”. |
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. Range: Preferably 1-based integer index. Note: This field emphasizes order of trials and alignment with projection-based definition of trials. A more complete name would be projection_index or pojected_trial_index. For brevity, BDM uses trial_id instead. |
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). Range: 1-based interger index. |
trial_start_datetime |
datetime | required | The the first event of the trial occured. |
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. Note: Use semicolon-separated indices if more then one stimulus were presented, e.g., 1;2;3. |
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 Range: - message: The stimulus is a message shown to subjects (e.g., task instructions). - question: The stimulus may consist of text, images and/or sounds; they require subjects to make a decision based on the content of the stimulus. |
stimulus_onset |
float | optional | Duration between the start of the trial and the appearance of the stimulus, in seconds. Range: 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 Range: - unitary: Only one stimulus is shown, alone. - set: Many stimuli are shown, either at the same time or not; order does not matter. - sequence: Multiple stimuli are shown, either at the same time or not; order does matter (order may be indicated by the order of presentation or by a digit for example). |
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 Range: - none: when stimulus_structure == unitary.”, - preset: The structure of stimuli is hard coded in a file. - generator: A procedure was used to generate the stimulus_structure. |
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. Note: To specify “infinity” in a CSV file we use +Inf and -Inf; these are correctly recognized in R (tidyverse) and Python (pandas) as being valid numbers rather than strings. |
stimulus_count |
integer | optional | The number of stimuli shown to the participant during the trial. Range: This should match number of stimuli in stimulus_id |
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. Range: - “set”:“stimulus is sampled from a fixed set of stimuli.” - “generator”: “stimulus is created using a procedure/algorithm.” |
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”. Note: It is not because a particular stimulus_source is used in a given timeline that all possible stimuli of that source are displayed to the user. For example, the AX-CPT may use “upper-case-letters” but only use a subset of those letters (e.g., “A”, “B”, “X”, “Y”). Whenever possible, we specify the most relevant/specific set (e.g., “digit1to9” rather than “digit”). |
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. Note: In some cases, when stimuli are too complex or can’t be precisely described, a summary of all stimuli is given instead. |
stimulus_role |
enum | optional | A stimulus may play different roles within a trial. Below is a list of some possible roles: Range: - “target”: “A stimulus the subject must process and which should trigger the completion of the response (e.g., classify, reach, memorize) if the subject is doing the task as intended. Note that in some cases (e.g., in a go/no-go task) the correct response to a stimulus is to NOT click the button. In this case, the stimulus that triggered the decision to NOT click the button is still a target.” - “non_target”: “A stimulus the subject must process but which does not trigger the completion of the response (e.g., the first two stimuli in a 2-back test).” - “distractor”: “A stimulus the subject should not process at all (i.e., ignore) and which is unrelated to the correct execution of the task.” - “location_cue”: “A stimulus giving a spatial location information that subjects could use to improve their performance.” - “job_specifier”: “A stimulus specifying which job the subject should perform.” - “stop_signal”: “A stimulus signaling the participant he should abort his current action.” - “probe”: “A stimulus indicating about which stimulus to respond.” |
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). Note: While there is a stimulus_index_in_source to refer to the particular stimulus that was used, we don’t have an equivalent opiton_index_in_source since all options are displayed. Instead, we use response_index and expected_response_index to refer to a particular option within the set of options. |
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: Range: - “nominal”: Set of unordered labels (e.g., {“Luxembourg”, “France”, “Germany”}). - “ordinal”: “Ordered values without clear distance (e.g., {“a lot”, “a bit”, “not at all”}). -”interval”: Ordered values with clear distances but no absolute zero (e.g., 10 versus 20 degrees Celsius). - “ratio”: Values with clear distance metrics and absolute zero (e.g., length in cm). |
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: Range: - “nominal”: Set of unordered labels (e.g., {“Luxembourg”, “France”, “Germany”}). - “ordinal”: “Ordered values without clear distance (e.g., {“a lot”, “a bit”, “not at all”}). -”interval”: Ordered values with clear distances but no absolute zero (e.g., 10 versus 20 degrees Celsius). - “ratio”: Values with clear distance metrics and absolute zero (e.g., length in cm). |
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): Range: - keyboard: A keyboard is displayed on the screen. - buttons: Dedicated buttons on the screen. - stimulus-button: Stimuli serves as buttons. - text-field: A text field is displayed on the screen. - slider: A slider is displayed on the screen. |
input_action_type |
enum | optional | Refers to the type of action the subject performs to give a response. Possible values include (non-exhaustive): Range: - “mouse-click” - “mouse-release” - “key-press” - “key-release” - “mouse-drag” - “touch” - “swipe” Note: The type of input_action determines the structure of detailed response data (i.e., mouse-click data is different from key-press data). |
input_count |
integer | optional | The number of inputs (i.e., actions) the user made during the trial. Note: For mouse-drag, it corresponds to the number of drag points that have been sampled during the drag-and-drop. |
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. Note: When expected_response_index = 0, it means that the subject should not respond at all. Note: Sometimes stimuli serve both as stimuli and as response options as subjects have to click on a particular stimuli to give their response (e.g., spatial span, odd one out). It is convenient in those cases to use stimulus_position_index to order/index the options (i.e., option_index == stimulus_position_index) and consequently also the responses. |
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: Range: - unitary: The subject provides a single input (e.g., chooses option same). - set: The subject provides a set of information, and the order does not matter (e.g., list words that start with the letter A). - sequence: The subject provides a sequence of information, and the order matters (e.g., a sequence of memorized digits in their order of appearance). Note: Note that the distinction between set and sequence refers to the importance of order information to evaluate if the response is correct or not; a response with a set structure may unfold over time (each piece of information is given in a particular temporal order) and it may be of scientific interest to take into account that order; however, the order itself is not important within the task itself. For example, in the MOT task one may ask subjects to point to all dots that hide a token. If subjects point to all such dots they will be correct no matter in which order the dots were clicked in. |
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). Note: response_count is different from input_count; a subject may in some cases change their response multiple times before submitting the final response. In such cases, there would be many more inputs than there are components to the final response. Note: While we have stimulus_set_size we currently don’t have a response_set_size, but we do have option_count and response_count. |
response_option_index |
integer | optional | The index of the option the participant chose, starting from 1. Note: response_option_index = 0 means the subject chose none of the options (e.g., a “no-go” response in a Go/No-go task). Note: response_index can be directly compared to expected_response_index. Note: response_index refers to an entry in the Option table (i.e., there is no Response table). |
response_description |
string | optional | A description of participant’s response; typically the description of the option that was chosen. Note: response_description can be directly compared to expected_response_description. |
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: Range: - correct: The response is correct. - error: The response is incorrect. - hit: The stimulus was present and the subject correctly responded present. - miss: The stimulus was present and the subject correctly responded absent. - fa: The stimulus was absent and the subject correctly responded present. - cr: The stimulus was absent and the subject correctly responded absent. |
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: Range: - none: No feedback was shown. - expected_response: Feedback indicated what the correct response would have been. - explanation: Feedback explains why a certain option is the correct one. - correctness_on_option: “Feedback indicates (on the option itself) if the option chosen by the participant was the correct one (e.g., in green), or not (e.g., in red). - correctness_on_screen:”Feedback displayed on the screen center indicates if the response to the current trial was correct or not (e.g., using a green check or a red cross). Note: This list is not exhaustive and characterizing feedback in the future will involve more variables (e.g., separating the type of information shown (e.g., correctness) and how it is shown (“on_option” versus “on_screen”). Note: NOTE2: We don’t consider here as “feedback”, the kind of feedback that is used in UI to confirm to users that a button has indeed been clicked. |
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): Range: - mouse_trajectories - fmri - eye_tracking - heart_rate Note: Leave this field empty if no additional measures were recorded for this specific response. |
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. Note: For example, 1up-2down. The 1-up, 2-down is a common adaptive staircase procedure used to estimate a subject’s threshold or sensitivity. After a correct response, the difficulty level is increased, and after two incorrect responses, the difficulty level is decreased. |
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. Range: Data type depends on the type of the adaptive parameter, as defined in adaptive_parameter_name) |
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. Range: Data type depends on the type of the adaptive parameter, as defined in adaptive_parameter_name) |