Importing and Harmonizing Eye-Tracking Exports

The adapter layer converts source-specific exports into explicit canonical records, streams, samples, eye samples, episodes, events, intervals, AOIs, biometrics, quality results, and provenance.

Automatic detection

detect_eye_format("participant-01.tsv")
x <- read_eye_export("participant-01.tsv", vendor = "auto")

Detection is intentionally conservative. If no adapter is sufficiently confident, use an explicit mapping.

Generic mapping

mapping <- eye_mapping(
  participant = "subject",
  recording = "recording",
  timestamp = "timestamp_us",
  x = "gaze_x",
  y = "gaze_y",
  pupil_left = "pupil_left_mm",
  pupil_right = "pupil_right_mm",
  trial = "trial_id",
  item = "item_id",
  response = "answer",
  score = "correct",
  response_time = "response_time_ms"
)

x <- read_eye_generic(
  "export.csv",
  mapping = mapping,
  time_unit = "microseconds",
  coordinate_space = "display_pixels_top_left",
  screen_width = 1920,
  screen_height = 1080,
  pupil_unit = "millimetres"
)

Dedicated vendor adapters

tobii   <- read_tobii("tobii-pro-lab.tsv")
neon    <- read_pupil_neon("neon-export-folder")
core    <- read_pupil_core("pupil-player-export")
eyelink <- read_eyelink_asc("recording.asc")
smi     <- read_smi("begaze-export.txt")

Preserve source meaning

x$raw
x$vendor_metadata
x$coordinate_spaces
x$streams
x$provenance

audit_coordinate_spaces(x)
audit_timebase(x)
audit_clock_sync(x)

No coordinate conversion, interpolation, resampling, or event reclassification should occur silently.