Events data

Events in BDM describe something that happened during a cognitive test, game, or questionnaire. Understanding and modeling events is crucial for interpreting the experimental data as events are typically considered the primary raw data and they include information about a wide range of stuff, from a simple stimulus shown or a button pressed to complex interactions with virtual environments. Overall, they may represent changes in the environment or the interactions between the agents and the environment.

BDM events are based on xAPI, 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. It assumes that events are generated by a client app (a front-end app that interacts with the agents) and sent to the LRS (Learning Record Store; a data collection backend) for storage and analysis.

Each event is then an object (e.g., as in JSON or YAML) that follows a specific schema as defined in BDM. Here is a summary of the BDM events schema:

Variable Description Example
version (str) Behaverse Events 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
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”.
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 (dict) key-value pairs of additional information, e.g., stimulus, 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:
    stimulus: "Stimulus Name"
    environment: "Environment Name"

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": {
    "stimulus": "Stimulus Name",
    "environment": "Environment Name"
  }
}
Back to top