---
title: "Importing and Harmonizing Eye-Tracking Exports"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Importing and Harmonizing Eye-Tracking Exports}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>", eval = FALSE)
```

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

```{r}
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

```{r}
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

```{r}
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

```{r}
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.