Validating Real Eye-Tracking Exports

In eyeprocess: Harmonize Eye-Tracking, Pupillometry, Biometrics, and Psychometric Process Data

knitr::opts_chunk$set(collapse = TRUE, comment = "#>")
library(eyeprocess)

Why empirical validation is separate from declared support

An adapter can be structurally implemented and exercised with synthetic fixtures without yet being validated against the diversity of real exports created by different device models, software versions, export selections, and laboratory conventions. eyeprocess therefore distinguishes:

1. declared support, based on the implemented parser and documented format;
2. synthetic-fixture validation, based on reproducible package fixtures;
3. real-export validation, based on de-identified empirical files.

head(eye_format_profiles())

Validate one source

The following example uses the bundled Gazepoint fixture. For real work, replace path with a source file or export folder.

path <- system.file("extdata", "gazepoint", "demo-user.csv", package = "eyeprocess")

result <- validate_eye_source(
  path,
  vendor = "gazepoint",
  spec = format_validation_spec(run_roundtrip = TRUE),
  import_args = list(recording_id = "R001", quiet = TRUE),
  retain_dataset = TRUE,
  case_id = "gazepoint-demo"
)

summary(result)
result$checks

The result retains separate evidence for format detection, adapter-specific findings, canonical validation, schema coverage, source preservation, quality audits, and canonical round-trip comparison.

Build a validation corpus

Create a private corpus skeleton with:

init_validation_corpus("C:/private/eyeprocess-validation-corpus")

The initializer is safe to run repeatedly: existing manifest and case files are preserved unless overwrite = TRUE is supplied.

A corpus should normally contain one directory per export case. Record the vendor, device model, software version, export family, and any known options in a manifest.

manifest <- validation_manifest(
  paths = c(
    system.file("extdata", "gazepoint", "demo-user.csv", package = "eyeprocess"),
    system.file("extdata", "tobii-demo.tsv", package = "eyeprocess")
  ),
  vendor = c("gazepoint", "tobii"),
  format_family = c("gazepoint_analysis", "tobii_pro_lab"),
  software_version = c("fixture", "fixture"),
  case_id = c("gp-fixture", "tobii-fixture")
)

corpus <- validate_eye_corpus(
  manifest,
  spec = format_validation_spec(run_roundtrip = FALSE),
  import_args = list(
    `gp-fixture` = list(recording_id = "R001", quiet = TRUE),
    `tobii-fixture` = list(recording_id = "R002", quiet = TRUE)
  )
)

corpus$summary

The compatibility matrix can then combine declared capabilities with observed case outcomes.

format_compatibility_matrix(corpus)[, c(
  "format_id", "adapter", "validation_level",
  "empirical_cases", "empirical_passes", "empirical_failures"
)]

Produce a safe validation bundle

Validation bundles contain the report, checks, manifests, coverage tables, and optionally an anonymized canonical dataset. They do not include raw vendor exports.

create_validation_bundle(
  result,
  path = "gazepoint-validation-bundle.zip",
  include_dataset = TRUE,
  anonymize = TRUE,
  overwrite = TRUE
)

Automated anonymization replaces core identifiers, removes raw data and source paths, and can redact free-text values. It cannot identify every possible study-specific disclosure. Review every bundle before sharing it.

Recommended real-export acceptance process

For each vendor and software version:

1. collect multiple de-identified exports with different export selections;
2. record device, firmware, software version, sampling rate, and coordinate configuration;
3. validate each case using a manifest;
4. inspect every warning and failed canonical field;
5. verify trial markers, pupil units, fixation provenance, and AOI semantics;
6. retain compatibility evidence with the package release;
7. promote support from fixture-tested to empirically validated only after all required cases pass.

eyeprocess documentation built on Sept. 28, 2026, 5:08 p.m.