Events

Events in BDM describe something that happened at specific point in time during an experiment.

Understanding and modeling events is crucial for interpreting the experimental data as events are typically considered the primary raw data.

They include information about a wide range of stuff, from a simple stimulus shown or a button pressed to complex interactions with virtual environments. They may capture changes in the agent (e.g., physiological responses), the environment (e.g., stimulus presentation), or the interactions between the agents and the environment (e.g., user response to a stimulus).

Events schema

BDM events follow the xAPI specification, which is a standard for tracking and recording of learning experiences. The BDM events schema 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 front-end software that interacts with the agents) and sent to the LRS (Learning Record Store; a data collection backend) 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) Same as schema:agent, extends xapi:actor
verb (str | dict) The verb should be prefixed and compatible with xAPI, SchemaOrg, ActivityStreams2, or BDM ontologies. Extends schema:Action schema:CreateAction
or xapi:completed
object (dict) If “objectType” is not defined, it will be treated as “schema:Event”.
version (str) The associated BDM version (“latest” for the latest).
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 | Study) This represents the study, for which the event was collected. It also contains metadata about the studyflow that was executed for the data collection and further processing.
result (dict) { "accuracy": 1 }
authority (User) Client app developer authenticated by the API key.
Populated by LRS
attachments (list) Ordered list of additional objects, e.g., stimulus, image, information about the environment, etc. []

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

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

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"

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 specific intervals and typically used to capture physiological signals, neural activity, or other continuous measurements that vary over time.

In BDM, timeseries are considered as specific type of events. The main difference between timeseries and regular events is that timeseries are dense, continuous, and homogeneously typed (e.g., resting-state EEG data collected at 500 Hz), while events are sparse, discrete, and heterogeneous (e.g., a stimulus presentation, a button press, or an EEG marker).

As raw timeseries data is dense and homogeneous, it is stored as a separate domain-appropriate file (e.g., CSV, parquet, safetensor, binary) associated with metadata that describes the data type, recording parameters, sampling rate, and other relevant information.

The same schema can be used to represent metadata for timeseries, with the addition of a link to the timeseries data file in the attachments field:

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