Start

Getting started

This page takes you from installation to a small uncertainty-aware AOI analysis using only NumPy, pandas, and GazeAudit.

1. Install the public release

For isolated-environment setup, optional extras, tested Python versions, and source-checkout commands, start with the Install & environment center.

python -m pip install gazeaudit==0.2.0

Confirm the installed package:

python -c "import gazeaudit; print(gazeaudit.__version__)"

The package declares Python >=3.10; the repository CI currently tests Python 3.10–3.13. The Install Center generates this compatibility summary from package metadata and the test matrix.

Optional interoperability extras

Install only the adapter family you need. The complete generated extras inventory is maintained in the Install Center:

python -m pip install "gazeaudit[pymovements]==0.2.0"

For pEYES integration, Python 3.12+ is required by the current pEYES dependency range:

python -m pip install "gazeaudit[peyes]==0.2.0"

Before using your own table

Post-release development on main includes a structural study preflight. Map the source table explicitly and inspect it before downstream analysis:

import pandas as pd

from gazeaudit import GazeStudy, audit_study_qc

frame = pd.read_csv("my_eye_tracking_export.csv")
study = GazeStudy(
    frame,
    x="gaze_x_px",
    y="gaze_y_px",
    timestamp="time_ms",
    participant="participant_id",
    trial="trial_id",
)
report = audit_study_qc(study)
print(report.status, report.issue_codes)

The preflight is descriptive, not a universal quality score. See Data onboarding and structural preflight for the full contract and a runnable example.

2. Fit a transparent gaze-error model

A GaussianGazeErrorModel treats validation residuals as observed-minus-target x/y error. The model stores estimated systematic bias and the residual covariance matrix.

import pandas as pd

from gazeaudit import GaussianGazeErrorModel

validation = pd.DataFrame(
    {
        "observed_x": [501, 500, 499, 502],
        "observed_y": [400, 399, 401, 400],
        "target_x": [500, 500, 500, 500],
        "target_y": [400, 400, 400, 400],
    }
)

error_model = GaussianGazeErrorModel.fit(validation)

print(error_model.mean_error)
print(error_model.covariance)

3. Define AOIs

Rectangle and circle AOIs are available as lightweight primitives.

from gazeaudit import RectangleAOI

aois = [
    RectangleAOI("claim", 450, 350, 500, 450),
    RectangleAOI("price", 500, 350, 550, 450),
]

Here the two rectangles share a boundary at x = 500. A conventional hard assignment has to decide which side owns a fixation observed on or near that boundary.

4. Propagate measurement uncertainty

import numpy as np

from gazeaudit import aoi_probabilities

fixations = np.array(
    [
        [500.0, 400.0],
        [490.0, 405.0],
    ]
)

probabilities = aoi_probabilities(
    fixations,
    aois,
    error_model,
    draws=4000,
    rng=42,
)

print(probabilities)

Each AOI column is a marginal membership probability. AOIs may overlap, so AOI probabilities are not required to sum to one. When include_outside=True (the default), the result also contains the probability that a latent true point belongs to none of the supplied AOIs.

5. Convert probabilities to an endpoint

If fixation durations are available, use expected dwell instead of a hard AOI sum:

from gazeaudit import expected_dwell

durations_ms = np.array([180.0, 220.0])

claim_dwell = expected_dwell(
    probabilities,
    durations=durations_ms,
    aoi="claim",
)

print(claim_dwell)

The same measurement-error model can then be scaled or grouped in a sensitivity analysis rather than treated as unquestionable truth.

6. Compare hard and probabilistic assignments

compare_hard_probabilistic() takes the observed points, AOIs, and fitted error model and returns one row per observation × AOI, including hard membership, probabilistic membership, flip probability, and boundary risk.

from gazeaudit import compare_hard_probabilistic, summarize_aoi_risk

comparison = compare_hard_probabilistic(
    fixations,
    aois,
    error_model,
    draws=4000,
    rng=42,
)

risk = summarize_aoi_risk(comparison)

print(comparison)
print(risk)

The comparison is useful for identifying observations whose substantive contribution changes when spatial uncertainty is acknowledged. The high_risk_threshold used by summarize_aoi_risk() is a descriptive reporting threshold, not a universal exclusion rule.

7. Move from one pipeline to a decision space

A single uncertainty-aware analysis is still only one analytical specification. When multiple scientifically defensible choices exist, define them explicitly with PipelineSpace and evaluate a common endpoint across all valid combinations.

Continue with the specification-space guide or jump directly to the specification-curve example.

Recommended learning path