Research recipes¶

Start here when you have a study task, not a module name. Each recipe points to the smallest defensible GazeForge route, names the reviewable artifacts you should retain, and states the scientific boundary that must travel with the result.

Recipes are workflows, not automatic validity

A function running successfully establishes software compatibility with the supplied inputs. It does not, by itself, establish device validity, construct validity, label validity, threshold optimality, or substantive psychological interpretation.

Choose a route¶

Research task	Start with	Keep as artifacts	Principal boundary
Outcome/estimand preregistration	Outcome & estimand preregistration clinic	outcome/estimand/contrast/sensitivity/deviation registries	preregistration ≠ estimator choice, construct validity, or causal validity
Static-stimulus AOI study	`AOI`, `map_fixations_to_aois()`	frozen AOI table, review record, fixation assignments, scanpaths	AOI membership is not a psychological state
Dynamic/video AOI study	`DynamicAOIKeyframe`, `map_fixations_to_dynamic_aois()`	keyframes, interpolation policy, assignments, review record	bounded interpolation only; no silent extrapolation
Real tracker → canonical table → QC	Worked tracker import + Real-data import clinic	untouched source, import contract, canonical table, metadata, QC table	import compatibility is not device validation
Transparent event baseline	`ivt_classify_events()` or angular I-VT	explicit threshold, sample labels, event intervals	example thresholds are not universal cutoffs
Learned event validation	Event-model validation clinic	fold ledger, matched predictions, sample/event metrics, calibration/coverage	name the held-out unit and native/derived rate
Scanpath / transition analysis	`to_semantic_scanpaths()`	ordered fixation assignments, sequences, motifs/embeddings	sequence structure does not establish motive or intent
Statistical analysis handoff	Analysis handoff	trial × AOI/event tables, denominators, missingness/censoring states, provenance	missing ≠ zero; repeated fixations/samples ≠ independent participants
Manuscript / archive handoff	Reporting clinic + Publication readiness	software identity, manifest, fingerprints, evidence boundary, claim-safe prose	report only what the design and evidence support

Recipe 0 · Outcomes and estimands before modelling¶

Use when: the research question is defined and measurement/model fitting has not yet started or the study is being frozen before confirmatory analysis.

Run:

python examples/13_worked_estimand_preregistration.py \\
  --output-dir worked-estimand-preregistration

Register primary/secondary/exploratory status, exact observable definition, row/inferential unit, exposure/denominator, missing/zero/censoring semantics, target population, contrast, multiplicity family, and prespecified sensitivity checks. Start with an empty deviation ledger and append later changes rather than rewriting the original plan.

Boundary: GazeForge records the plan; it does not choose the statistical estimator, establish construct validity, or make the contrast causal.

Preregistration clinic → · Study-design templates → · Analysis handoff →

Recipe 1 · Static-stimulus semantic AOIs¶

Use when: the relevant regions do not move during the analysed trial.

Prerequisites: timestamped fixations or fixation centroids in pixels; explicit stimulus geometry; a documented AOI definition/review process.

from gazeforge import AOI, map_fixations_to_aois, to_semantic_scanpaths

aois = [
    AOI("brand", "brand", 80, 80, 520, 280, source="researcher_defined"),
    AOI("claim", "claim", 80, 340, 940, 650, source="researcher_defined"),
]
assigned = map_fixations_to_aois(fixations, aois, overlap_rule="first")
scanpaths = to_semantic_scanpaths(assigned)

Retain: AOI definitions, stimulus/version identity, overlap rule, any accept/reject/edit decisions, fixation assignments, semantic scanpaths, and source fingerprints.

Boundary: assigning a fixation to claim or brand records observable gaze-region correspondence. It does not by itself establish comprehension, persuasion, liking, memory, or purchase intention.

Worked static study → · Study templates →

Recipe 2 · Dynamic/video AOIs¶

Use when: an object, label, product, interface element, or other semantic region changes position or size over time.

from gazeforge import DynamicAOIKeyframe, map_fixations_to_dynamic_aois

keyframes = [
    DynamicAOIKeyframe("product", "product", 0.0, 500, 320, 980, 800),
    DynamicAOIKeyframe("product", "product", 100.0, 620, 320, 1100, 800),
]
assigned = map_fixations_to_dynamic_aois(
    fixations,
    keyframes,
    max_interpolation_gap_ms=100.0,
    overlap_rule="highest_confidence",
)

GazeForge interpolates only between observed keyframes whose gap is within the explicit maximum. It does not extrapolate before the first or after the last keyframe.

Retain: original keyframes/tracks, timestamps, geometry, confidence/source/model metadata, interpolation-gap rule, overlap rule, review decisions, and fixation assignments.

Boundary: a detector or tracker can propose dynamic AOIs, but proposal accuracy and fixation-assignment validity require task-appropriate empirical validation. A software demo is not detector validation.

Worked dynamic study → · Dynamic AOI method → · Dynamic AOI evaluation →

Recipe 3 · Real tracker import → canonical schema → QC¶

Start with the executable Worked tracker import and QC, then use the Real-data import clinic for deeper source variants and troubleshooting.

Preserve the raw export and make these values explicit before analysis:

participant and trial identity columns;
timestamp column and unit;
coordinate columns and coordinate basis;
screen width and height when normalized coordinates must be converted;
native/nominal acquisition rate and separately observed timestamp cadence;
pupil/validity fields if used; and
exact analysed file/table identity.

A Gazepoint-style contract can be explicit:

from gazeforge import adapt_gazepoint_samples

gaze = adapt_gazepoint_samples(
    source,
    screen_size_px=(1920, 1080),
    participant_col="USER_FILE",
    trial_col="MEDIA_ID",
    timestamp_col="TIME",
    x_col="BPOGX",
    y_col="BPOGY",
    time_unit="seconds",
    coordinates="normalized",
    sampling_rate_hz=None,
)

Then inspect identity, duplicate sample keys, observed cadence, coordinate bounds, and row-count preservation before anomaly scoring. Do not silently guess units, rate, geometry, or identity, and do not treat anomaly flags as automatic invalidity labels.

The worked import script deliberately retains duplicate keys, off-screen coordinates, and a missing gaze coordinate. That is the intended behavior: review cases remain visible in the source, canonical, and QC records.

Retain: untouched source file/table, checksum/fingerprint, import contract, canonical table, acquisition metadata, preflight diagnostics, QC sample table, trial-quality summary, and any reviewed exclusion decisions.

Boundary: successful import or adapter compatibility does not establish native-device, Gazepoint, GP3, native-60-Hz, event-model, or measurement validity. Observed timestamp cadence is a diagnostic of the analysed stream, not proof of native hardware rate.

Run the worked import → · Import clinic → · Adapters & validation →

Recipe 4 · Transparent event baseline¶

Use a deterministic baseline before a learned event model when you need an inspectable reference rule.

from gazeforge import ivt_classify_events, samples_to_event_intervals

predicted = ivt_classify_events(
    gaze,
    sampling_rate_hz=60.0,
    velocity_threshold_px_s=1000.0,
)
intervals = samples_to_event_intervals(
    predicted,
    label_col="predicted_event",
    sampling_rate_hz=60.0,
)

Retain: threshold, units, rate, geometry assumptions, sample-level labels, event intervals, and sensitivity checks where the threshold materially affects inference.

Boundary: 1000 px/s in an example is an explicit demonstration setting, not a universal physiological threshold or device-validity result.

I-VT tutorial → · Event-level evaluation →

Recipe 5 · Learned event-model validation and calibration¶

Start with the Event-model validation clinic. A publishable learned-model result needs more than fitted predictions: predeclare the held-out unit, prevent leakage, retain fold identity, evaluate both sample- and event-level estimands, and inspect probability calibration where probabilities are interpreted.

For a matched three-model reference workflow, GazeForge can evaluate I-VT, Random Forest, and ContextMLP on identical group-held-out rows:

from gazeforge import compare_event_models_grouped

comparison = compare_event_models_grouped(
    labelled_gaze,
    label_col="event_label",
    group_col="participant_id",
    n_splits=5,
    sampling_rate_hz=60.0,
    include_event_level_metrics=True,
)

Use the grouped validation functions appropriate to the model and preserve whether the analysed rate is native or derived. If identity is only a source token, report a source-token-disjoint split; do not promote it to participant-disjoint. If confidence thresholds or models are selected from validation results, separate selection from final confirmatory evaluation or label the choice exploratory.

Retain: reference-label provenance, explicit participant/split ledger, predictions/probabilities, matched held-out row identity, separate sample/event metric tables, calibration bins, confidence/coverage, abstention rule, software/model identity, and sampling-rate provenance.

Boundary: good sample-level discrimination does not imply good event segmentation; good calibration does not imply every prediction is correct; selective accuracy must travel with coverage; derived 60 Hz evidence does not become native 60 Hz evidence; and a synthetic model ordering is not a universal ranking.

Validation clinic → · Worked validation example → · Reporting cookbook → · Calibration → · Validation guide →

Recipe 6 · Scanpaths, transitions, and motifs¶

Start from ordered, reviewed fixation-to-AOI assignments.

from gazeforge import find_scanpath_motifs, to_semantic_scanpaths

scanpaths = to_semantic_scanpaths(assignments)
motifs = find_scanpath_motifs(scanpaths, ngram_range=(2, 3), min_count=2)

If you add learned embeddings or clustering, record vectorizer/reducer settings, random seed, fitted training scope, and the meaning you assign to clusters only after appropriate external or human validation.

Retain: fixation order, AOI labels, durations, collapse/drop-unassigned rules, semantic sequences, and any learned representation metadata.

Boundary: a recurring sequence is a structural pattern in the recorded representation; it is not direct evidence of strategy, cognition, preference, or intent.

Methods overview → · Worked studies →

Recipe 7 · Reviewed outputs → statistical analysis handoff¶

Use when: event/AOI outputs have been reviewed and you need a defensible table for inferential modelling.

Run the deterministic worked route:

python examples/10_worked_analysis_handoff.py \
  --output-dir worked-analysis-handoff-demo

Preserve participant/trial grouping, explicit exposure denominators, missing-versus-observed-zero status, and latency censoring. The worked bundle writes participant × trial × AOI and participant × trial × event tables plus a separate descriptive summary and two diagnostic figures.

Boundary: GazeForge prepares the measurement handoff; it does not silently choose a GLM/GLMM, survival model, SEM, Bayesian model, or other inferential estimator. Failed convergence or invalid diagnostics remain a stop condition in the specialist statistical environment.

Analysis handoff → · Artifact dictionary →

Recipe 8 · Manuscript and archive handoff¶

Before writing a headline result, freeze the research identity of the analysis:

package version and exact commit when using a development checkout;
acquisition hardware, native/nominal rate, observed cadence, units, geometry, and participant/trial identity;
source fingerprint/checksum, import mapping, duplicate/bounds preflight, and row-count preservation;
QC/exclusion decisions and their review provenance;
event/AOI/scanpath model identity and parameters;
validation split unit and leakage checks;
native-versus-derived sampling status;
source and output fingerprints; and
the explicit evidence boundary—what the study does not establish.

Use the Study-design templates to make those values copy-ready, the Worked tracker import to freeze the real-data handoff, the Validation reporting cookbook for validation-specific wording, the Reporting & interpretation clinic for the whole frozen artifact set, then run the Publication-readiness checklist.

From a recipe to code¶

Runnable examples gives exact commands and output inventories, including tracker-import/QC, participant-held-out validation, research-evidence-bundle, and statistical-handoff studies.
Outcome & estimand preregistration freezes planned outcomes, contrasts, exposure/censoring policies, sensitivity checks, and deviations before model fitting.
Analysis handoff covers inferential units, denominators/exposure, missing-versus-zero semantics, latency censoring, descriptive-only summaries, and the boundary to specialist statistics.
Worked tracker import and QC covers explicit source mapping, unit conversion, preflight, nominal-versus-observed cadence, non-destructive QC, and provenance.
Event-model validation clinic covers leakage-safe learned event evaluation, calibration, abstention, and sample/event estimands.
Study lifecycle connects design, acquisition, QC, modelling, validation, freeze, and publication.
Reproducible reporting and the Validation reporting cookbook provide manuscript-facing wording and claim-safe contrasts.
Evidence status and the Benchmark guide define the current empirical boundaries.