The session log file

You should read how to write correctly a scenario file first.

Where the file is and what it contains

Every time a scenario is run, OpenMATB records everything that happens into a comma-separated values (.csv) file stored under the sessions/ directory, organized by date:

sessions/<YYYY-MM-DD>/<session_id>_<yymmdd_HHMMSS>.csv

This single file contains all that is needed to understand what happened during a session and to undertake performance calculations afterwards. It is also what the replay feature reads back to reproduce a session.

The file is written by the Logger class (core/logger.py).

The columns

Each row has exactly six columns:

Column	Description
logtime	Absolute timestamp of the entry, in seconds, taken from a high-resolution monotonic clock (time.perf_counter()). Logged with microsecond precision (6 decimals). It is not a wall-clock time; only the differences between logtime values are meaningful.
scenario_time	Time elapsed since the start of the scenario, in seconds. Maintained by the scheduler. Use this to align an entry with the scenario timeline.
type	The category of the entry (see below).
module	The source of the entry: the plugin/task alias (sysmon, track, communications, resman, scheduling, …), keyboard for inputs, or empty for global/manual entries.
address	The target of the entry inside the module: a widget and attribute, a parameter path, a metric name, a key, etc. Its exact meaning depends on type.
value	The logged value.

Note: older versions of OpenMATB included an extra totaltime column in second position. The current format does not have it.

The entry types

The type column tells you how to read address and value:

type	Meaning	address	value
input	A participant input (keyboard or mapped joystick button).	The key/button name (e.g. ENTER, F1, NUM_2).	The key state: press / release.
event	A scenario command being executed (the lines from your scenario file).	self for task-level commands (start/stop/pause…), or the parameter name being set.	The command or the value being applied.
parameter	A plugin parameter value being recorded (e.g. when a task starts or a parameter changes).	The hierarchical parameter path (e.g. scales-1-failure).	The parameter value.
state	A change in a displayed widget's state (text, color, position…). This is what makes replay possible.	"<widget>, <attribute>" (e.g. "task_title, text").	The new attribute value.
performance	A raw performance metric logged by a task. These are the values the performance plugin aggregates (see How to modify automatic performance computation).	The metric name (e.g. cursor_in_target, signal_detection, correct_radio).	The metric value.
aoi	An Area Of Interest (the on-screen bounding box of a widget), useful for eye-tracking analyses.	The widget name.	The box coordinates (x1, y1, x2, y2).
seed_value / seed_output	A pseudo-random seed and its resulting output, logged so a session can be reproduced deterministically.	empty	The seed, then the output.
manual	A manual / global marker. Notably, the final end marker closing the session.	empty	The entry (e.g. end).

Reading the raw metrics per task

The performance rows are where the per-task raw measures live. The most useful keys are:

Task	performance keys
sysmon	signal_detection (HIT / MISS / FA), response_time
track	cursor_in_target (0/1 per frame), center_deviation, response_time
resman	a_in_tolerance, b_in_tolerance (0/1 per frame), a_deviation, b_deviation
communications	correct_radio (bool), response_deviation, response_time, sdt_value

Example

logtime,scenario_time,type,module,address,value
13869.194646,0,input,keyboard,ENTER,release
13869.210557,0,state,sysmon,"task_title, text",SURVEILLANCE
13869.232539,0.018296,event,sysmon,self,start
13869.238017,0.058883,state,track,"task_title, text",POURSUITE
13869.240570,0.058883,event,track,self,start
13869.240641,0.058883,performance,track,cursor_in_target,1
13869.240664,0.058883,performance,track,center_deviation,0.0
14307.553591,150.008259,state,track,"reticle, cursor_relative","(-98.86, 149.15)"
14307.566581,150.022335,event,track,self,stop
14307.620911,150.071739,manual,,,end

• logtime only moves forward; subtract two values to get an elapsed duration.
• scenario_time lets you place each entry on the scenario timeline (here the session lasted ~150 s).
• The closing manual,,,end row marks the clean end of the session.

Tip - filtering the file

Because the format is plain CSV with a type column, you can load it with any spreadsheet or with pandas and filter by type and module. For example, to extract the tracking performance trace:

import pandas as pd
df = pd.read_csv("sessions/2026-06-22/1_260622_143000.csv")
track_perf = df[(df["type"] == "performance") & (df["module"] == "track")]