GazeForge

Auditable AI for eye-tracking research.

Import · QC · eye events · AOIs · scanpaths · validation · provenance · reproducible reporting

Website · Start here · Task map · Method chooser · Examples · Learning paths · Evidence status · API

New to GazeForge? Start with the tour

If you are asking “What does GazeForge actually do?”, do not start with the API reference.

Read the GazeForge Tour and run the smallest package-wide example:

python examples/00_gazeforge_tour.py --output-dir gazeforge-tour-demo

The tour shows one gaze table moving through:

source gaze
   ↓
canonical gaze
   ↓
non-destructive QC
   ↓
transparent eye events
   ↓
researcher-defined AOIs
   ↓
semantic scanpaths
   ↓
provenance + reviewable output bundle

It creates ordinary CSV/JSON files you can inspect side-by-side. It also verifies that the source table is unchanged and that sample rows are preserved through non-destructive sample-level stages.

Tour boundary: the tour uses deterministic synthetic/demo data. It is not empirical validation evidence, a tracker-validity result, or a claim that QC flags should automatically become exclusions.

What GazeForge is

GazeForge is a vendor-neutral Python research-software package for integrating auditable AI and reproducible workflows into eye-tracking analysis.

It is not one detector or one classifier. It connects the analysis stages that researchers normally have to manage separately while keeping transformations, uncertainty, model identity, sampling assumptions, human review, and provenance visible.

Scientific contract: AI may propose, score, classify, embed, or flag. It must not silently alter the empirical record.

GazeForge does not infer diagnoses, emotions, personality, protected traits, or unsupported latent mental states from gaze.

Choose the path you need

Browse all exact commands and output inventories in the Runnable examples gallery.

What GazeForge adds to eye-tracking analysis

Installation and immutable release identity

Install the exact public alpha:

python -m pip install "gazeforge==0.1.0a2"

The immutable 0.1.0a1 release is published at PyPI and archived on Zenodo with version DOI 10.5281/zenodo.22650013. The Zenodo concept/latest-release DOI is 10.5281/zenodo.22650012.

The exact GitHub Release distributions are identity-matched to the published alpha:

gazeforge-0.1.0a1-py3-none-any.whl  sha256:3e409fbfc3c194db30ba25fefdf7f6459a3a003aefa0ab4303555d96982fbb46
gazeforge-0.1.0a1.tar.gz            sha256:cee4e061a90d74b3a354a0fb4aa5c7bd00d53577e17167f75342cd476a5c25fa

Optional open-vocabulary semantic AOI detection:

python -m pip install "gazeforge[vision]==0.1.0a2"

For development or commit-pinned research work:

git clone https://github.com/stefanosbalaskas/GazeForge.git
cd GazeForge
python -m pip install -e ".[dev]"
pytest

Release & install guidance →

Minimal Python workflow

from gazeforge import ai_flag_anomalies, canonicalize_gaze, simulate_gaze

raw = simulate_gaze(n_participants=3, n_trials=2, samples_per_trial=180)
gaze = canonicalize_gaze(raw, sampling_rate_hz=60)
flagged = ai_flag_anomalies(gaze.data, sampling_rate_hz=gaze.sampling_rate_hz)

The input rows remain present. QC adds review evidence rather than deleting observations.

For a more informative first run, use examples/00_gazeforge_tour.py instead of stopping at this snippet.

Example progression

The repository now has a task-oriented learning sequence:

00  package-wide GazeForge tour
01  synthetic non-destructive QC
02  transparent I-VT baseline
03  visual diagnostics
04  worked static advertising/interface study
05  worked dynamic-AOI study
06  participant-held-out event-model validation
07  tracker import + QC
08  QC review + exclusion ledger
09  archive-facing research evidence bundle
10  statistical analysis handoff + diagnostic figures
11  manuscript/reporting derivatives + claim boundaries
12  measurement/interpretation claim audit
13  outcome & estimand preregistration registry
14  reviewer/replication handoff
15  sensitivity/robustness audit
16  denominator/exposure/censoring audit
17  model diagnostics/convergence audit
18  missing-data assumptions/treatment audit
19  uncertainty/multiplicity inferential reporting audit
20  grouping/repeated-measures/pseudoreplication audit
+   complete end-to-end research workflow

Every learning example uses deterministic synthetic/demo inputs and carries an explicit evidence boundary.

Validation is visible, not implied

GazeForge separates software capability from empirical support. The canonical public status is generated from versioned evidence policy and integrity-checked artifacts.

GazeForge never silently upgrades derived or partial evidence into a stronger category. For VISUS specifically, the current public derivative supports bounded empirical observations only; it does not recover the original full benchmark or establish model validity, independent human-human agreement, Frozen Evidence, unrestricted source redistribution, or native GP3 validity.

Evidence status → · Frozen evidence → · Validation matrix →

First frozen Lund2013 checkpoint

The first audited external benchmark tranche uses the public Lund2013 expert-labelled corpus with exact source verification and participant-held-out evaluation. The primary RA-labelled derived 60 Hz comparison is intentionally multi-criterion: learned models are stronger on sample-level multiclass classification in this checkpoint, while transparent I-VT is stronger on contiguous event segmentation/boundary fidelity.

Human MN–RA agreement remains strong from native 500 Hz to the derived 60 Hz condition. These results are not native GP3/60 Hz device validation; a genuinely native 60 Hz/GP3-class manually labelled event corpus remains an open evidence requirement.

Inspect the complete frozen reports →

Research workflow

tracker / raw export
        │
        ▼
explicit source contract
        │
        ▼
canonical gaze table
        │
        ├── non-destructive QC ── review/exclusion ledger
        ├── eye-event labels/probabilities ── validation
        ├── static/dynamic AOIs ── human review
        └── semantic scanpaths
                         │
                         ▼
               reviewed analytic derivative
                         │
                         ▼
              statistics / models / report
                         │
                         ▼
          provenance + fingerprints + archive

For a manuscript-facing study, record acquisition hardware, nominal/native rate, observed timestamp cadence, source mapping/units, source fingerprints, QC and exclusion decisions, event/AOI model identity, split design, native/derived status, and the exact GazeForge version/commit. The Research evidence bundle shows how to freeze those layers without collapsing source, QC, review decisions, and analysis derivatives into one table.

Scientific governance

Confirmatory workflows should lock model/version information, sampling rates, exclusions, validation splits, and human review decisions before final inference. External benchmark files remain external unless their reuse terms clearly permit redistribution.

Scientific governance → · Publication readiness →

Documentation

The strict-built MkDocs Material site is the primary long-form documentation surface:

https://stefanosbalaskas.github.io/GazeForge/

Recommended entry points:

• GazeForge Tour
• Getting started
• Learning paths
• Method chooser
• Artifact & output dictionary
• Research evidence bundle
• Outcome & estimand preregistration clinic
• Analysis handoff
• Grouping, repeated measures & pseudoreplication clinic
• Denominator, exposure & censoring clinic
• Missing-data assumptions & treatment handoff
• Measurement & interpretation clinic
• Sensitivity & robustness clinic
• Reporting & interpretation clinic
• Reviewer & replication handoff
• Research recipes
• Runnable examples
• Evidence status

Project status

GazeForge is active public-alpha research software. The package has broad implemented workflow coverage and audited external evidence, while important scientific gates remain explicit rather than being hidden behind the software feature set.

Before a stable scientific release, key open requirements include native 60 Hz/GP3-class expert-labelled event validation, resolution of remaining benchmark identity/licensing boundaries, stronger full-source VISUS recovery/authorization, broader cross-dataset validation, validated dynamic-detection/tracking results, and final API stability beyond the alpha series.

The active benchmark plan is tracked in Issue #1.

Citation

For work using the first public alpha:

Balaskas, S. (2026). GazeForge: Auditable AI for Eye-Tracking Analysis (Version 0.1.0a1) [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.22650013

Use the exact GazeForge version or full commit SHA in reproducible methods. Machine-readable citation metadata is available in CITATION.cff.

License

MIT License. External validation datasets retain their own licenses and are not silently redistributed by GazeForge.