Events

Events describe something that happened at specific point in time during an experiment. There are associated with timestamps and, where applicable, durations. Events can capture a wide range of occurrences, from a simple stimulus presentation or button press to complex interactions with virtual environments.

They may record changes in the agent (e.g., physiological responses), in the environment (e.g., stimulus presentation), or in the interactions between agents and the environment (e.g., a response to a stimulus).

Events are typically the primary raw data of an experiment, so understanding and modeling them is crucial for interpreting experimental results.

Events schema

Events in BDM follow the xAPI specification, which is a standard for tracking and recording of learning experiences. The BDM events format extends the xAPI specification to include additional information specific to the cognitive tests and questionnaires.

Just like xAPI, BDM assumes that events are generated by a client app (a graphical software that interacts with the agents) and sent to the LRS (Learning Record Store; a data collection server) for storage and analysis.

Each event is an object (as in JSON or YAML) that follows a specific structure as below:

Variable Description Example
agent
(str | dict)		 The person or software that performed the action described by the event. Same as schema:agent, extends xapi:actor

verb
(str | dict)

The action performed by the agent. It describes what happened in the event. Extends schema:Action

schema:CreateAction
or xapi:completed
object
(str | dict)		 The object of the event. It describes what the action was performed on. It can be a stimulus, a response, a questionnaire item, etc. It is typically represented as an activity (xapi:Activity) or an entity (schema:Thing)
version
(str)		 The associated BDM version
Populated by LRS		 "v25.0228"
timestamp
(datetime)		 When the event occurred.
Formatted as RFC9557 datetime with TimeZone offset (this is the same as RFC3339 as ISO 8601 profile)		 1996-12-19T16:39:57-08:00Z
stored
(datetime)		 When the event was stored in the LRS.
Populated by LRS		 1996-12-19T16:39:57-08:00Z
updated
(datetime)		 When the event was updated in the LRS.
Populated by LRS		 1996-12-19T16:39:57-08:00Z
context
(str | dict)		 Additional information about the event, e.g., the study or studyflow in which the event occurred, the environment, etc.
result
(dict)		 The outcome of the event, e.g., the accuracy of a response, response time, the score of a questionnaire item, etc. { "accuracy": 1 }
authority
(dict)		 The authority that generated the event, e.g., the client app that sent the event to the LRS. It can include information about the software or the developer.
Populated by LRS
attachments
(list)		 Additional files or data associated with the event, e.g., a stimulus file, a screenshot of the environment. Each attachment can include metadata about the content type, description, etc. []

Example

In YAML format, a single BDM event looks like this:

version: "v25.0228"
timestamp: 1996-12-19T16:39:57-08:00Z
stored: 1996-12-19T16:39:57-08:00Z
updated: 1996-12-19T16:39:57-08:00Z
agent:
  name: "John Doe"
verb: "xapi:completed"
object:
  objectType: "schema:Event"
  id: "https://example.com/event/12345"
  name: "Test Event"
context:
    study: "Study Name"
    studyflow: "Studyflow Name"
result:
    accuracy: 1
authority:
    name: "Client App Developer"
attachments:
  - type: "Stimulus"
    stimulus_description: "SymbolA"
  - type: "Environment"
    runtime: "WebGL"

The following prefixes are already imported in the BDM events schema:

  • xapi: Experience API
  • schema: SchemaOrg
  • as2: ActivityStream 2

In JSON format, the same event looks like this:

{
    "version": "v25.0228",
    "timestamp": "1996-12-19T16:39:57-08:00Z",
    "stored": "1996-12-19T16:39:57-08:00Z",
    "updated": "1996-12-19T16:39:57-08:00Z",
    "agent": {
        "name": "John Doe"
    },
    "verb": "xapi:completed",
    "object": {
        "objectType": "schema:Event",
        "id": "https://example.com/event/12345",
        "name": "Test Event"
    },
    "context": {
        "study": "Study Name",
        "studyflow": "Studyflow Name"
    },
    "result": {
        "accuracy": 1
    },
    "authority": {
        "name": "Client App Developer"
    },
    "attachments": [
        {
            "type": "Stimulus",
            "stimulus_description": "SymbolA"
        },
        {
            "type": "Environment",
            "runtime": "WebGL"
        }
    ]
}

Timeseries

Timeseries represent streams of observations collected at fixed intervals and are typically used to capture physiological signals, neural activity, or other continuous measurements that vary over time.

In BDM, a timeseries is a specific type of event. The difference is in shape: timeseries are dense, continuous, and homogeneously typed (e.g., resting-state EEG sampled at 500 Hz), whereas regular events are sparse, discrete, and heterogeneous (e.g., a stimulus presentation, a button press, or an EEG marker).

Because raw timeseries data is dense and homogeneous, it is unsuitable for storage inline within event records. Instead, BDM treats the raw signal as a blob: the data is written to a separate, domain-appropriate file (e.g., CSV, Parquet, safetensors, EDF, or another binary format) and only referenced from the event. The event record itself stays small and queryable, while the payload lives in blob storage.

The reference is carried in the attachments field, alongside metadata describing the data type, recording parameters, sampling rate, and any other information needed to interpret the blob:

attachments:
  - type: "bdm:Timeseries"
    contentType: "application/x-edf"
    url: "file:///eeg_timeseries_data.edf"
    ...

This keeps the event format uniform (every observation, sparse or dense, is represented by an event record) while large signals live in storage suited to their size and access requirements.

Back to top