Trial

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

Identifier

id id

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.

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 Trial table.

Context

study_name string

The name of the study the subjects participated in.


group_name string

Subjects may be assigned to different groups. Typically, different groups will have different experiences within a study.


subject_id string

A unique identifier assigned to the agent (typically person) generating the responses. This ID tracks their participation and responses throughout the study. See Subjects table.


session_id integer

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.

We currently don’t use session_name, session_id and session_repetition in this table.


activity_index index

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.

See StudyFlow table for more details.

Task

language string

The language the task was completed in, expressed as a two-letter code within the ISO_639-1 standard.


instrument_id string

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

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

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

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

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.

If no multitasking was involved, leave this field blank.

This characterization of multitasking_type is rudimentary and will likely evolve in the future.


task_index index

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

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

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

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

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

In questionnaires, block_index may refer to distinct pages where each page may contain multiple questions.


block_name string

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

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.

projection_name string

Refers to the specific events-to-trials function used to construct rows of this table from raw events. The projection embodies the definition of a trial for a particular task.

The projection name refers to a code in the format of a function f(trial_state, event) => trial_state, where event is the event occured 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).

  • The projection encapsulates the domain rules defining a “trial” for a given task. It defines what constitutes a “trial”.

trial_id id

Sequential identifier representing the application count of the projection rule to the events occured. It increases with each re-computation of the trial based on updated or newly received events.

Range

Preferably 1-based integer index.

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.


trial_start_datetime datetime

The the first event of the trial occured.


trial_seed integer | string

Random seed used in the trial (if any).

Stimulus

stimulus_index list[index]

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.

Use semicolon-separated indices if more then one stimulus were presented, e.g., 1;2;3.


stimulus_id integer

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

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_panel_count integer

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

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

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

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

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.

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

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

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

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

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”.

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

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

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.

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

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

option_source_type enum

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

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).

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

The number of options the participant can choose from on a given trial.


option_id integer

Is a unique identifier for the option (set or generator) used on a given trial.


option_data_type enum

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

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

input_interface_type enum

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

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”

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

The number of inputs (i.e., actions) the user made during the trial.

For mouse-drag, it corresponds to the number of drag points that have been sampled during the drag-and-drop.

Expectation

expected_response_option_index integer

The index of the option the subject is expected to choose from the set of options.

When expected_response_index = 0, it means that the subject should not respond at all.

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

A description of the expected response using the same convention as response_description.

Response

response_structure string

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 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

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_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.

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

The index of the option the participant chose, starting from 1.

response_index = 0 means the subject chose none of the options (e.g., a “no-go” response in a Go/No-go task).

response_index can be directly compared to expected_response_index.

response_index refers to an entry in the Option table (i.e., there is no Response table).


response_description string

A description of participant’s response; typically the description of the option that was chosen.

response_description can be directly compared to expected_response_description.


response_numeric float

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

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

The datetime corresponding to the completion of the response.


response_validation_time float

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

In some cases (e.g., a reaching movement) it might be useful to encode when a response was initiated.


response_skipped boolean

In some cases (e.g., in some questionnaires), subjects have the option to skip a question.


timed_out boolean

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

accuracy float

A task-dependent accuracy measure ranging from 0 to 1 (inclusive).


correct boolean

Indicates whether the response matches the expected response (i.e., correct = TRUE) or not (i.e., correct = FALSE).


score float

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

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

feedback_description string

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).

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”).

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

outcome_description string

Describes the observable consequences of the subject’s response (e.g., “the opened box is empty”).


outcome_numeric float

A numeric value describing the observable consequences of the subject’s response (e.g., +3 points).

Accessory

additional_measures string

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

Leave this field empty if no additional measures were recorded for this specific response.

Experimental Design

adaptive_method_name enum

Specifies the adaptive procedure used to modify instrument parameters in response to subject performance (e.g., staircase).


adaptive_method_config string

More detailed configuration for the adaptive method, including initial values, step sizes, and termination criteria.

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

Specific instrument parameter that is dynamically modified based on the subject’s performance.


adaptive_parameter_value any

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

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)

No matching items