Tobii: source export to BIDS derivatives¶

This notebook runs the complete Pyxations workflow on the bundled Tobii tabular export. It uses the built-in Engbert detector, so no optional dependency is needed.

The current tobii reader accepts the tab-separated export demonstrated here. Titta/PsychoPy HDF5 containers are a different input format and are not currently read directly.

In [1]:

from pathlib import Path

from pyxations import Experiment, compute_derivatives_for_dataset, dataset_to_bids

from pathlib import Path from pyxations import Experiment, compute_derivatives_for_dataset, dataset_to_bids

Convert the vendor export into raw BIDS, then compute derivatives from that BIDS dataset. This export carries no synchronisation messages, so the recording is not segmented into trials and every fixation belongs to a single unnamed phase.

In [2]:

repo = next(
    path
    for path in (Path.cwd(), *Path.cwd().parents)
    if (path / "pyproject.toml").is_file()
)
source = repo / "examples" / "tobii_sceneviewing"
output = repo / "generated"

raw_bids = dataset_to_bids(
    output,
    source,
    "tobii-sceneviewing",
    format_name="tobii",
    overwrite=True,
)
derivatives = compute_derivatives_for_dataset(
    raw_bids,
    "tobii",
    detection_algorithm="engbert",
    screen_height=1080,
    screen_width=1920,
    num_processes=1,
    overwrite=True,
)
derivatives

repo = next( path for path in (Path.cwd(), *Path.cwd().parents) if (path / "pyproject.toml").is_file() ) source = repo / "examples" / "tobii_sceneviewing" output = repo / "generated" raw_bids = dataset_to_bids( output, source, "tobii-sceneviewing", format_name="tobii", overwrite=True, ) derivatives = compute_derivatives_for_dataset( raw_bids, "tobii", detection_algorithm="engbert", screen_height=1080, screen_width=1920, num_processes=1, overwrite=True, ) derivatives

Out[2]:

PosixPath('/home/runner/work/pyxations/pyxations/generated/tobii-sceneviewing_derivatives')

The experiment hierarchy reads the canonical derivative TSV.GZ/JSON files and returns Polars DataFrames.

In [3]:

experiment = Experiment(raw_bids)
experiment.load_data("engbert")
trial = experiment["0001"]["sceneviewing"][0]
trial.fixations().head()

experiment = Experiment(raw_bids) experiment.load_data("engbert") trial = experiment["0001"]["sceneviewing"][0] trial.fixations().head()

Out[3]:

shape: (5, 13)

tStart	tEnd	duration	xAvg	yAvg	pupilAvg	eye	Eyes_recorded	Rate_recorded	chunk	trial_number	phase	bad
f64	f64	f64	f64	f64	f64	str	str	f64	i64	i64	str	bool
6.701904	6.701904	3.351	0.0	0.0	null	"L"	"LR"	298.418383	0	0	""	false
6.701904	6.701904	3.351	0.0	0.0	null	"R"	"LR"	298.418383	0	0	""	false
20.105957	167.550049	150.795	689.00162	137.403631	3.205764	"L"	"LR"	298.418383	0	0	""	false
20.105957	167.550049	150.795	701.5391	137.92982	3.488234	"R"	"LR"	298.418383	0	0	""	false
288.186035	321.696045	36.861	0.0	0.0	null	"R"	"LR"	298.418383	0	0	""	false

In [4]:

trial.plot_scanpath(screen_height=1080, screen_width=1920, display=True)

trial.plot_scanpath(screen_height=1080, screen_width=1920, display=True)

/home/runner/work/pyxations/pyxations/pyxations/analysis/generic.py:2010: UserWarning: No named trial phase was found, so every fixation is plotted as a single unnamed phase. Pass start_msgs and end_msgs to compute_derivatives_for_dataset to segment the recording into named phases.
  vis.scanpath(