Skip to content

The raw log files generated by matbii can be a bit cumbersome to work with. Not all of the events will be relevant to your specific research question or summary statistics. The matbii.extras.analysis module provides functionality that can parse, extract and visualise information that may be relevant to your research questions.

Parsing log files

Parsing the log files is done using the EventLogParser class. This class can be used to extract events from the log file.

from matbii.extras.analysis import EventLogParser
from icua.event import MouseButtonEvent, RenderEvent

# create the parser instance
parser = EventLogParser()
# gather all the event types present in matbii and ensure they are loaded properly before parsing
parser.discover_event_classes("matbii")

# locate the log file in an experiment directory (if it is known you might skip this step)
PATH = "<MY LOGGING PATH>" # path to the directory that contains the .log file. 
log_file = parser.get_event_log_file(PATH)

# this parses the log file and produces a list of (logging_timestamp, event) tuples
events = list(parser.parse(log_file))

You can filter this list of events based on the event type, and once filtered, you can convert it to a pandas dataframe. 

mouse_button_events = parser.filter_events(events, MouseButtonEvent)
mouse_button_df = parser.as_dataframe(mouse_button_events, include=["timestamp", "button", "status"])

There are some convenience functions for loading common event types, instead of the above you could use:

from matbii.extras.analysis import get_mouse_button_events
mouse_button_df = get_mouse_button_events(events)

For user input, the following convenience functions are available:

  • get_mouse_motion_events
  • get_mouse_button_events
  • get_keyboard_events
  • get_eyetracking_events

Similar functions are available to track the state of each task:

  • get_system_monitoring_task_events
  • get_resource_management_task_events
  • get_tracking_task_events

And for guidance, acceptability and attention:

  • get_guidance_intervals
  • get_acceptable_intervals
  • get_unacceptable_intervals
  • get_attention_intervals

See the reference documentation for details on the use of these functions.

Visualisation

COMING SOON

Scripts

To quickly produce a summary of the data generated during an experiment, you can make use of the --script <SCRIPT> command line argument.

These scripts will use the functionality present in matbii.extras.analysis to produce .csv files (from event dataframes) and/or plots.

The most useful of these scripts is probably summary, which will generate a comprehensive summary of the logged data. 

python -m matbii --script summary --path <LOG_DIRECTORY> --output <OUTPUT_DIRECTORY>

You can quickly test this by using an example: 

python -m matbii --example only-tracking --config.logging.path './example-log'
python -m matbii --script summary --path './example-log'