Reference · Data contract

Data Contract & Schema Mapping Center

Use this page when you have a gaze or fixation table and need to answer:

What does GazeAudit require before I can create a canonical GazeStudy?

The runtime authority is the public GazeStudy contract. This page turns that contract into a practical schema-mapping workflow without imposing a vendor-specific export format.

Constructor contract

The current public signature is:

GazeStudy(
    data,
    x="x",
    y="y",
    timestamp="timestamp",
    participant="participant",
    trial="trial",
)

Those default names are software defaults, not a requirement to rename your data.

Map your existing column names

This builder generates the semantic GazeStudy(...) mapping plus an optional documentation-side provenance record. It does not upload or inspect your data, infer units, fabricate source identity, or choose any QC rule.

Complete all five semantic column mappings to generate code.

Complete all five semantic column mappings to generate the mapping record.

Mapping record contract

The generated JSON uses a small documentation schema:

{
  "schema": "gazeaudit-data-mapping-record-v1",
  "source_id": "exports/session_level_long.csv",
  "columns": {
    "participant": "participant_code",
    "trial": "stimulus_trial",
    "timestamp": "recording_time_ms",
    "x": "screen_x_px",
    "y": "screen_y_px"
  },
  "units": {
    "coordinates": "pixels",
    "timestamp": "milliseconds from trial onset"
  },
  "coordinate_convention": "origin top-left; x right; y down",
  "pre_mapping_transformations": "binocular channels combined before canonical table"
}

The record is descriptive. It does not certify that the mapping is scientifically correct, and it does not hash or inspect your data. Its machine-readable structure is governed by the data-mapping record JSON Schema. If source identity must be immutable, record a project-controlled checksum or persistent dataset identifier in source_id.

Continue to Record data-mapping provenance for the governance rules and Mapping change audit for a worked comparison of harmless renames versus substantive transformations.

Construction failure versus structural review

Not every data problem belongs at the same layer.

This separation is intentional. The constructor validates the canonical representation; structural preflight reports conditions that require contextual inspection rather than silently converting them into exclusions.

Minimal valid synthetic table

A table can be small and still satisfy the constructor contract:

import pandas as pd

from gazeaudit import GazeStudy

frame = pd.DataFrame(
    {
        "participant_id": ["P01", "P01"],
        "trial_id": ["T01", "T01"],
        "time_ms": [0.0, 16.7],
        "gaze_x_px": [520.0, 523.0],
        "gaze_y_px": [410.0, 412.0],
    }
)

study = GazeStudy(
    frame,
    x="gaze_x_px",
    y="gaze_y_px",
    timestamp="time_ms",
    participant="participant_id",
    trial="trial_id",
)

This proves only that the canonical constructor contract is satisfied. It does not establish calibration quality, AOI validity, detector validity, adequate sampling, or inferential robustness.

Unit record

Record the units and coordinate convention alongside the mapping. A compact project note can be enough:

x: gaze_x_px — pixels, stimulus coordinate system
y: gaze_y_px — pixels, stimulus coordinate system
timestamp: time_ms — milliseconds from trial onset
participant: participant_id — anonymized participant key
trial: trial_id — within-participant stimulus presentation

If you transform units before construction, record that transformation as preprocessing provenance rather than relying on the canonical object to remember an unrecorded conversion.

What happens next

Continue with Map your table into GazeStudy for the task-oriented procedure, or Valid, invalid, and reviewable tables for a synthetic failure-case walkthrough.