Independent Vendor Validation and Semantic Fidelity

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

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

Why import success is not validation

eyeprocess treats vendor compatibility as an evidence claim. A file that can be read without error has established only parser reachability. It has not shown that timestamps, coordinate systems, eye identity, pupil units, event meanings, or missingness semantics survived harmonisation.

Version 0.7 therefore adds a detailed evidence ladder:

eyeprocess::validation_evidence_levels()

The intended progression is:

1. declared
2. synthetic-fixture
3. vendor-example
4. independent-public-real
5. multisession-multidevice-real
6. semantic-roundtrip-validated

These detailed tiers complement, rather than replace, the package's existing support-status mechanism.

Public validation corpus

The package does not auto-download public human-participant datasets. Use the manifest to review licences/terms and select cases deliberately.

corpus <- eyeprocess::public_validation_corpus()
corpus[, c("ecosystem", "device", "corpus", "evidence_goal", "access")]

The initial corpus targets two independent Gazepoint GP3 HD repeated-session sets, raw EyeLink EDF data, GazeBase, a 2026 EyeLink smooth-pursuit benchmark, Tobii Pro Fusion, Tobii Pro Glasses 3, and the official Pupil Labs Neon example.

Semantic round-trip contract

A strong test is not

native -> import succeeds

but

native vendor
   -> eyeprocess canonical
   -> BIDS eye tracking
   -> eyeprocess canonical
   -> field-by-field semantic comparison

Every compared field should be classified explicitly, for example as LOSSLESS, UNIT_TRANSFORMED, COORDINATE_TRANSFORMED, SEMANTICALLY_EQUIVALENT, DERIVED, UNSUPPORTED, INTENTIONALLY_DROPPED, or AMBIGUOUS.

spec <- semantic_fidelity_spec(
  timestamp_tolerance = 1e-6,
  coordinate_tolerance = 1e-6,
  pupil_tolerance = 1e-6
)

audit <- semantic_roundtrip_audit(
  original = native_canonical,
  roundtrip = bids_reimported,
  key = c("recording_id", "sample_index"),
  fields = c("timestamp", "gaze_x", "gaze_y", "pupil", "eye", "event")
)

semantic_loss_map(audit)
plot(audit)

Timestamp semantics

Clock meaning is part of the schema. Device timestamps and system timestamps are not interchangeable merely because both are numeric.

timestamp_fidelity_audit(
  source = imported_native,
  roundtrip = imported_bids,
  source_time = "device_time",
  roundtrip_time = "device_time",
  tolerance = 1e-6
)

validate_vendor_timestamp_semantics(imported_native)

Coordinate and pupil fidelity

Coordinate transformations are acceptable when they are explicit and invertible. Silent transformations are evidence failures.

coordinate_fidelity_audit(
  source = original,
  roundtrip = transformed_back,
  source_x = "gaze_x",
  source_y = "gaze_y",
  roundtrip_x = "gaze_x",
  roundtrip_y = "gaze_y"
)

pupil_unit_fidelity_audit(
  source = original,
  roundtrip = transformed_back,
  source_pupil = "pupil_left",
  roundtrip_pupil = "pupil_left"
)

BIDS eye-tracking semantics

BIDS 1.11.1 now specifies eye tracking under physiological recordings. Among the important semantics are PhysioType = "eyetrack", RecordedEye, and SampleCoordinateSystem; gaze-on-screen recordings also require screen presentation metadata. validate_bids_eye_semantics() is a lightweight structural audit for these requirements. It is intentionally not presented as a replacement for the official BIDS validator.

validate_bids_eye_semantics(
  data = bids_table,
  metadata = bids_json
)

HED event semantics

Event survival is not enough. An event that becomes event_17 has preserved an identifier but may have lost experimental meaning. HED provides a controlled, machine-actionable event vocabulary.

event_semantics_audit(original_events, roundtrip_events,
                      key = "event_id", label = "trial_type", time = "timestamp")
validate_hed_event_semantics(events)

validate_hed_event_semantics() performs only package-level structural checks. For formal HED-schema validation, use the official HED tooling.

Evidence matrix

base <- build_compatibility_matrix()
case_evidence <- data.frame(
  ecosystem = "Gazepoint",
  device = "GP3 HD",
  evidence_level = "independent-public-real",
  semantic_roundtrip_pass = FALSE
)

mat <- compatibility_evidence_matrix(base, case_evidence)
plot(mat)

A vendor should be promoted only from retained evidence, not from undocumented manual impressions.

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