Skip to content

Download data: Events structure

The events structure is a list of timed events during a task. It contains events such as a participant interacting with a stimulus, or resizing the screen.

When to use events structure

Events structure is ideal when you need:

  • Detailed timing data — Millisecond-precision timestamps for each action
  • Behavioral sequences — Understand the order of participant interactions
  • Debugging — Investigate specific participant sessions in detail

For aggregated results, use Tree, Table, or Annotations structures.

Compatible file types

Events structure data is currently only available in the LOG file type.

Structure

Each event is represented by one row. There are three columns:

  • time — The time of the event in milliseconds elapsed since January 1, 1970 00:00 UTC (Unix epoch)
  • name — The name of the event (see examples below)
  • variables — A key/value map with variables, such as the stimulus affected by the user action

Loading events data

Open the LOG file in a spreadsheet application:

  1. Open Microsoft Excel or Google Sheets
  2. Use File → Import or File → Open
  3. Select the .log file
  4. Choose Tab as the delimiter when prompted

Note

The variables column contains JSON-formatted data which may require additional parsing for analysis.

import pandas as pd
import json
from datetime import datetime

# Load the log file (tab-delimited)
data = pd.read_csv('Meadows_myStudy_events.log', sep='\t', 
                   names=['time', 'name', 'variables'])

# Parse the variables column from JSON strings
data['variables'] = data['variables'].apply(json.loads)

# Convert timestamp to datetime
data['datetime'] = pd.to_datetime(data['time'], unit='ms')

# Display the first few rows
print(data.head())

# Filter by event type
placement_events = data[data['name'] == 'placed']

library(jsonlite)

# Load the log file (tab-delimited)
data <- read.delim('Meadows_myStudy_events.log', header = FALSE,
                   col.names = c('time', 'name', 'variables'))

# Convert timestamp to datetime
data$datetime <- as.POSIXct(data$time / 1000, origin = '1970-01-01')

# Display the first few rows
head(data)

Example

Below is the content of an example log file containing events:

1522184853949   logStarted  {}
1522184853950   screenSize  {'h': 1080, 'w': 1920}
1522184853953   viewportSize    {'h': 858.2666625976562, 'w': 1222}
1522184853958   placed  {'id': 'eVgbZ', 'x': 0, 'y': -0.5, 'cat': 'first'}
1522184853958   placed  {'id': '0YpAC', 'x': -0.05962680651716577, 'y': 0.014922748834862198, 'cat': 'first'}
1522184853958   placed  {'id': 'XLZHk', 'x': 0, 'y': -0.5, 'cat': 'second'}
1522184854018   queueSampled    {'from': 0}
1522184863281   saveprogress    {}
1522185089525   placed  {'id': 'Q5OS4', 'x': 0.288995726610676, 'y': 0.14435351882160383, 'cat': 'first'}
1522185089547   queueSampled    {'from': 0}
1522185091444   placed  {'id': 'UTrzw', 'x': -0.236287732351751, 'y': 0.14435351882160383, 'cat': 'second'}

Common event types

Event name Description
logStarted Logging session started
screenSize Screen dimensions (width and height in pixels)
viewportSize Browser viewport dimensions
placed Stimulus was placed at a position
saveprogress Progress was saved
queueSampled Stimulus queue was sampled