Import, Inspect, Analyse, and Report Gazepoint GP3 Exports

Tools for importing, inspecting, cleaning, summarising, modelling, and reporting Gazepoint GP3 and Gazepoint Analysis CSV exports. The package supports offline workflows for all-gaze, fixation, pupil, area-of-interest, transition, time-course, quality-audit, and manuscript-reporting analyses. The package methodology is described in the peer-reviewed software paper .

---

gp3tools

gp3tools provides tools for importing, checking, summarising, exporting, visualising, preprocessing, and modelling Gazepoint GP3 / Gazepoint Analysis export files in R.

The package is designed for exported Gazepoint CSV files, especially:

• User *_all_gaze.csv
• User *_fixations.csv
• Data_Summary_export_*.csv

It supports common Gazepoint workflows, including:

• folder-level import and one-command workflow execution;
• sampling-rate checks and tracking-quality summaries;
• sample-level master-table creation, auditing, and validation;
• light and conservative pupil preprocessing;
• pupil preprocessing audits, reliability checks, interpolation sensitivity, and stimulus-luminance auditing;
• auditable binocular pupil reconstruction, artificial-monocular-loss validation, sensitivity analysis, and reconstruction-burden reporting;
• pupil-window confirmatory LMMs and model-family sensitivity checks;
• AOI entries, AOI windows, AOI denominators, and AOI-window GLMMs;
• AOI/fixation/transition feature extraction and time-varying transition matrices;
• fixation-, saccade-, and AOI-contingent alignment;
• pupil GAMMs, AOI GAMMs, gaze-position/PFE sensitivity GAMMs, and Growth Curve Analysis;
• cluster-based permutation tests and bootstrapped divergence-point estimation;
• standalone model diagnostics for GLMM/LMM/GLM and GAM/BAM models;
• nested model comparison, model-implied prediction plotting, and leave-one-unit model sensitivity;
• manuscript-ready fixed-effect, EMM, contrast, diagnostic, and model-export tables;
• real-data readiness gates, reporting checklists, and final analysis-decision audits;
• stimulus-layout QC, missingness reporting, task-phase coverage, and QC overview bundles;
• explicit trial and participant exclusion recommendations;
• offline gaze recalibration / drift correction when known target coordinates are available;
• diagnostic plots, lightweight HTML reports, and CSV exports;
• package-adapter exports for eyetrackingR-style, pupillometryR-style, gazer-style, and eyetools-style workflows;
• optional external gazeR and eyetools cross-check workflows.
• external facial-behaviour import, quality audit, synchronisation, window summaries, multimodal modelling, and reporting helpers for externally generated face-analysis outputs.

Which workflow should I use?

Use the workflow that matches the research question and the stage of analysis.

For a quick first pass through exported Gazepoint files, use run_gazepoint_workflow(). This imports a folder, checks file pairing, summarises sampling and tracking quality, creates AOI summaries, writes CSV outputs, and optionally saves diagnostic plots and an HTML report.

For analysis-ready sample-level data, create a master table with create_gazepoint_master(), audit it with audit_gazepoint_master(), and validate it with validate_gazepoint_master().

For pupil preprocessing, use the light branch when you need a transparent minimal pipeline:

flag_gazepoint_pupil()
interpolate_gazepoint_pupil()
baseline_correct_gazepoint_pupil()
smooth_gazepoint_pupil()
summarise_gazepoint_pupil_windows()

Use the conservative artifact-cleaned branch when blink/trackloss padding, pupil-speed artifacts, binocular disagreement, or stricter preprocessing decisions are important:

create_gazepoint_preprocessing_registry()
flag_gazepoint_pupil_artifacts()
interpolate_gazepoint_pupil()
baseline_correct_gazepoint_pupil()
smooth_gazepoint_pupil()

Use pupil-window LMMs when the main hypothesis concerns predefined pupil windows. Use pupil GAMMs, PFE-GAMMs, and GCA when the research question concerns time-course shape.

Use AOI-window GLMMs when the main hypothesis concerns predefined AOI time windows. Use AOI GAMMs when the research question concerns smooth target-looking trajectories over time.

Use AOI-entry, fixation, and transition helpers when the analysis concerns looking episodes, fixation summaries, AOI sequences, transition matrices, or scanpath structure.

Use cluster-based permutation testing for time-course inference. Use estimate_gazepoint_divergence_point() as complementary onset/sensitivity evidence, not as a replacement for confirmatory model specification.

Use model diagnostics, model summaries, estimated marginal means, nested model comparison, model-prediction plots, and leave-one-unit sensitivity checks before manuscript reporting.

Use check_gazepoint_real_data_readiness(), recommend_gazepoint_exclusions(), and create_gazepoint_reporting_checklist() before final interpretation. Use summarize_gazepoint_missingness(), segment_gazepoint_task_phases(), collect_gazepoint_qc_summaries(), and report_gazepoint_qc_overview() when preparing transparent data-coverage and QC-reporting summaries.

Function map

gp3tools is organised around a complete Gazepoint analysis workflow:

Task	Main helpers
Import Gazepoint exports	read_gazepoint(), read_gazepoint_folder(), read_gazepoint_summary()
Create and validate master data	create_gazepoint_master(), as_gazepoint_master(), validate_gazepoint_master(), audit_gazepoint_master()
Run a quick end-to-end workflow	run_gazepoint_workflow(), summarise_gazepoint_workflow(), create_gazepoint_report()
Check file pairing, sampling, and signal quality	check_gazepoint_file_pairs(), check_sampling_rate(), summarise_tracking_quality(), audit_gazepoint_gaze_signal_quality()
Review screen, stimulus-layout, and coordinate coverage	audit_gazepoint_screen_bounds(), harmonize_gazepoint_screen_coordinates(), audit_gazepoint_aoi_screen_coverage(), summarize_gazepoint_coordinate_coverage(), plot_gazepoint_stimulus_layout_qc(), add_gazepoint_polygon_aoi(), add_gazepoint_dynamic_aoi(), audit_gazepoint_dynamic_aoi_coverage()
Summarise missingness and task-phase coverage	summarize_gazepoint_missingness(), plot_gazepoint_missingness_profile(), report_gazepoint_missingness(), segment_gazepoint_task_phases(), summarize_gazepoint_phase_coverage(), plot_gazepoint_phase_timeline()
Collect QC outputs for reporting	collect_gazepoint_qc_summaries(), summarize_gazepoint_qc_status(), report_gazepoint_qc_overview(), plot_gazepoint_qc_overview()
Preprocess pupil data	flag_gazepoint_pupil(), flag_gazepoint_pupil_artifacts(), flag_gazepoint_pupil_hampel(), interpolate_gazepoint_pupil(), smooth_gazepoint_pupil(), baseline_correct_gazepoint_pupil(), preprocess_gazepoint_signals()
Reconstruct and validate binocular pupil signals	diagnose_gazepoint_binocular_pupil(), fit_gazepoint_binocular_calibration(), reconstruct_gazepoint_binocular_pupil(), construct_gazepoint_combined_pupil(), validate_gazepoint_binocular_reconstruction(), stress_test_gazepoint_binocular_reconstruction(), audit_gazepoint_binocular_reconstruction(), analyse_gazepoint_binocular_sensitivity(), summarise_gazepoint_binocular_reporting(), plot_gazepoint_binocular_diagnostics()
Compare and benchmark gaze-event detectors	compare_gazepoint_event_detectors(), summarise_gazepoint_event_detector_agreement(), plot_gazepoint_event_detector_agreement(), create_gazepoint_event_review_template(), benchmark_gazepoint_event_detectors(), summarise_gazepoint_event_detector_benchmark(), plot_gazepoint_event_detector_benchmark()
Audit pupil reliability and preprocessing choices	audit_gazepoint_pupil_gaps(), audit_gazepoint_pupil_baseline(), audit_gazepoint_pupil_drift(), audit_gazepoint_pupil_reliability(), audit_gazepoint_pupil_overlap_risk()
Summarise and model pupil outcomes	summarise_gazepoint_pupil(), summarise_gazepoint_pupil_windows(), summarise_gazepoint_pupil_trial_features(), fit_gazepoint_pupil_window_lmm(), fit_gazepoint_pupil_gamm()
Summarise AOI behaviour	summarise_gazepoint_aoi_windows(), summarise_gazepoint_aoi_entries(), summarise_gazepoint_aoi_trial_features(), summarise_gazepoint_fixation_trials()
Model AOI outcomes	prepare_gazepoint_aoi_glmm_data(), fit_gazepoint_aoi_window_glmm(), fit_gazepoint_aoi_model_sensitivity(), prepare_gazepoint_aoi_gamm_data(), fit_gazepoint_aoi_gamm()
Analyse sequences, transitions, and scanpaths	prepare_gazepoint_aoi_sequences(), summarise_gazepoint_aoi_transitions(), compute_gazepoint_aoi_transition_matrix(), compute_gazepoint_time_varying_transition_matrix(), cluster_gazepoint_scanpaths(), select_gazepoint_scanpath_clusters(), extract_gazepoint_representative_scanpaths(), plot_gazepoint_scanpath_clusters(), bootstrap_gazepoint_scanpath_clusters(), summarise_gazepoint_scanpath_cluster_stability(), plot_gazepoint_scanpath_cluster_stability()
Run time-course and advanced sensitivity analyses	fit_gazepoint_gca(), run_gazepoint_cluster_permutation(), estimate_gazepoint_divergence_point(), run_gazepoint_model_leave_one_out()
Prepare reporting and exclusion decisions	check_gazepoint_real_data_readiness(), recommend_gazepoint_exclusions(), create_gazepoint_reporting_checklist(), create_gazepoint_analysis_decision_audit()
Export tables and outputs	export_gazepoint_tables(), export_gazepoint_model_tables(), export_gazepoint_master_audit(), save_gazepoint_plots()
Prepare data for other R eye-tracking packages	prepare_gazepoint_eyetrackingr_data(), prepare_gazepoint_pupillometryr_data(), prepare_gazepoint_gazer_data(), prepare_gazepoint_eyetools_data()
Work with external facial-behaviour outputs	read_gazepoint_face_export(), standardize_gazepoint_face_columns(), audit_gazepoint_face_quality(), sync_gazepoint_face_data(), summarize_gazepoint_face_windows(), fit_gazepoint_multimodal_response_model(), create_gazepoint_face_reporting_checklist(), report_gazepoint_face_qc()

Most users should start with run_gazepoint_workflow() for a quick folder-level pass, then move to the master-table, pupil, AOI, modelling, and reporting helpers as needed.

Statistical, sequence, simulation, and reporting extensions

Version 2.0.0 also includes an optional statistical-extension layer for advanced, audit-friendly workflows:

• AOI sequence structure and uncertainty: compute_gazepoint_aoi_entropy(), compute_gazepoint_aoi_sequence_metrics(), compute_gazepoint_sequence_complexity(), compute_gazepoint_sequence_distance(), compute_gazepoint_scanpath_similarity(), and flag_gazepoint_sequence_anomalies().
• Fixation, scanpath, and transition diagnostics: audit_gazepoint_fixation_reliability(), compute_gazepoint_saccade_metrics(), plot_gazepoint_scanpath(), summarise_gazepoint_markovchain(), summarise_gazepoint_semimarkov(), compute_gazepoint_sequence_recurrence(), and compute_gazepoint_transition_network_metrics().
• Time-course, modelling, and reporting helpers: bootstrap_gazepoint_timecourse(), plot_gazepoint_time_varying_effect(), plot_gazepoint_model_residuals(), and report_gazepoint_multiverse().
• QC coverage and reporting bundles: audit_gazepoint_aoi_screen_coverage(), summarize_gazepoint_missingness(), segment_gazepoint_task_phases(), collect_gazepoint_qc_summaries(), and report_gazepoint_qc_overview().
• Simulation and optional interoperability: simulate_gazepoint_data(), export_gazepoint_to_bids(), fit_gazepoint_aoi_brms(), prepare_gazepoint_traminer_data(), detect_gazepoint_fixations_ivt(), and launch_gazepoint_qc_dashboard().

The rendered site includes a plot-first article for these additions: articles/statistical-extensions-plots.html.

Citation

When gp3tools supports a publication, cite the peer-reviewed software paper and report the package version used in the analysis.

Peer-reviewed software paper

Balaskas, S. (2026). gp3tools: An R Package for Reproducible Analysis and Reporting of Gazepoint GP3 Eye-Tracking Exports. Journal of Eye Movement Research, 19(4), 76. https://doi.org/10.3390/jemr19040076

R package

Balaskas, S. (2026). gp3tools: Import, Inspect, Analyse, and Report Gazepoint GP3 Exports. R package version 2.3.0. https://github.com/stefanosbalaskas/gp3tools

The complete citation entries are available directly from R:

citation("gp3tools")

The previously released 2.0.0 software archive remains available at https://doi.org/10.5281/zenodo.21292384. A version-specific archive DOI for 2.3.0 can be added after the corresponding GitHub/Zenodo release is created.

Installation

During development, install the package locally from the package project folder:

devtools::install(reload = FALSE)

Then restart RStudio and load the package:

library(gp3tools)

Check that the package loads correctly:

packageVersion("gp3tools")

1. Basic Gazepoint folder workflow

Use this workflow when you want a quick reproducible pass from a folder of Gazepoint exports to quality summaries, AOI summaries, exported CSV files, diagnostic plots, and an optional HTML report.

The workflow expects exported Gazepoint files such as:

User 1_all_gaze.csv
User 1_fixations.csv
Data_Summary_export_*.csv

Set the folder containing the Gazepoint exports and an output folder for results:

export_dir <- "C:/Users/YourName/Desktop/gp3_test_exports"
output_dir <- "C:/Users/YourName/Desktop/gp3_outputs"

Run the complete folder workflow:

library(gp3tools)

results <- run_gazepoint_workflow(
  export_dir = export_dir,
  output_dir = output_dir,
  prefix = "study1",
  save_plots = TRUE,
  create_report = TRUE
)

The returned object is a named list containing imported files, quality summaries, AOI summaries, exported file paths, saved plot paths, and optional report path:

names(results)

results$all_gaze
results$all_fix
results$sampling
results$quality
results$flagged_quality
results$aoi_table
results$written_files
results$written_plots
results$report_file

Create a compact one-row summary of the workflow:

workflow_summary <- summarise_gazepoint_workflow(results)

print(workflow_summary, width = Inf)

The workflow summary is useful for quickly checking:

workflow_summary$n_all_gaze_rows
workflow_summary$n_all_fix_rows
workflow_summary$n_sampling_rows
workflow_summary$n_quality_rows
workflow_summary$n_aoi_rows
workflow_summary$n_flagged_recordings
workflow_summary$n_written_files
workflow_summary$n_written_plots
workflow_summary$report_created

When output_dir is provided, the workflow writes standard CSV files such as:

study1_sampling.csv
study1_quality.csv
study1_flagged_quality.csv
study1_aoi_table.csv

When save_plots = TRUE, the workflow also saves diagnostic plots such as:

study1_tracking_quality_plot.png
study1_sampling_rate_plot.png

When create_report = TRUE, the workflow creates a lightweight HTML report.

Manual version of the same workflow

The same workflow can be run step by step when you want more control.

Read all all-gaze files:

all_gaze <- read_gazepoint_folder(
  export_dir,
  pattern = "_all_gaze\\.csv$"
)

dim(all_gaze)

Read all fixation files:

all_fix <- read_gazepoint_folder(
  export_dir,
  pattern = "_fixations\\.csv$"
)

dim(all_fix)

Check that all-gaze and fixation exports are correctly paired:

file_pairs <- check_gazepoint_file_pairs(export_dir)

file_pairs

Estimate sampling rate by participant and stimulus:

sampling <- check_sampling_rate(
  all_gaze,
  group_cols = c("USER_FILE", "MEDIA_ID")
)

sampling

For Gazepoint GP3 60 Hz exports, the estimated frequency should usually be close to 60 Hz.

Summarise tracking quality:

quality <- summarise_tracking_quality(
  all_gaze,
  group_cols = c("USER_FILE", "MEDIA_ID")
)

quality

Flag recordings requiring review:

flagged_quality <- flag_tracking_quality(
  quality = quality,
  sampling = sampling,
  min_gaze_valid_pct = 70,
  min_pupil_valid_pct = 70,
  expected_hz = 60,
  hz_tolerance = 5
)

flagged_quality

Show only recordings that require review:

dplyr::filter(flagged_quality, review_required)

Create a basic AOI summary from all-gaze and fixation exports:

aoi_table <- summarise_gazepoint_aoi(
  gaze_data = all_gaze,
  fixation_data = all_fix
)

aoi_table

The AOI table includes one row per user, media stimulus, and AOI, with metrics such as:

• sample-level time to first view;
• sample count;
• approximate sample-based viewed time;
• fixation count;
• total fixation duration;
• mean fixation duration;
• fixation-based time to first fixation.

Write standard output tables:

written_files <- write_gazepoint_outputs(
  sampling = sampling,
  quality = quality,
  flagged_quality = flagged_quality,
  aoi_table = aoi_table,
  output_dir = output_dir,
  prefix = "gazepoint_test"
)

written_files

Create standard diagnostic plots:

plot_tracking_quality(flagged_quality)

plot_sampling_rate(sampling)

Save standard diagnostic plots:

written_plots <- save_gazepoint_plots(
  flagged_quality = flagged_quality,
  sampling = sampling,
  output_dir = output_dir,
  prefix = "gazepoint_test"
)

written_plots

The basic workflow is useful for first-pass inspection. For advanced preprocessing and modelling, continue by creating a master table.

2. Master-table creation and validation

For advanced preprocessing, AOI modelling, pupil modelling, time-course analysis, and reporting, first convert the imported Gazepoint all-gaze export into a standard sample-level master table.

Start from the all-gaze data imported by run_gazepoint_workflow() or read_gazepoint_folder():

all_gaze <- results$all_gaze

Create the master table:

master <- create_gazepoint_master(all_gaze)

dplyr::glimpse(master)

The master table standardises key fields when available, including:

• participant ID;
• media/stimulus ID;
• trial identifiers;
• time;
• gaze coordinates;
• pupil values;
• gaze-validity and pupil-validity fields;
• AOI state;
• fixation-related fields;
• event labels;
• response-related columns;
• screen and metadata fields.

Inspect the main columns:

names(master)

dplyr::glimpse(
  dplyr::select(
    master,
    dplyr::any_of(c(
      "subject",
      "MEDIA_ID",
      "trial_global",
      "time",
      "x",
      "y",
      "pupil",
      "aoi_current",
      "event_label"
    ))
  )
)

Audit the master table:

master_audit <- audit_gazepoint_master(master)

master_audit$overview
master_audit$subject_summary
master_audit$media_summary
master_audit$aoi_summary
master_audit$pupil_summary
master_audit$coordinate_summary

Use the audit to check whether the imported data contain the expected participants, stimuli, AOI states, pupil values, and gaze-coordinate availability.

Validate the master table before preprocessing or modelling:

validation <- validate_gazepoint_master(master)

validation$summary
validation$checks

Validation is a formal gate. Use it before pupil preprocessing, AOI modelling, time-course analysis, or final reporting.

Export the master table and audit outputs:

master_outputs <- export_gazepoint_master_audit(
  master,
  output_dir = output_dir,
  prefix = "study1_master"
)

master_outputs

This writes the master table, audit tables, and validation outputs to CSV files.

Reading official Gazepoint Analysis summary exports

Official Gazepoint Analysis summary exports can be read separately:

summary_file <- file.path(
  export_dir,
  "Data_Summary_export_06-11-26-23.50.26.csv"
)

summary <- read_gazepoint_summary(summary_file)

summary$metadata
summary$aoi_summary
summary$aoi_by_user

Use read_gazepoint_summary() when you need official Gazepoint Analysis summary values. Metrics recomputed from all-gaze and fixation files may not always exactly reproduce Gazepoint’s internal calculations.

For transparent reproducible analysis from exported rows, continue with the sample-level master table and the preprocessing/modelling helpers.

3. Pupil preprocessing: light branch

Use the light branch when you need a transparent, minimal pupil preprocessing pipeline. This branch is appropriate for early inspection, teaching examples, or studies where conservative artifact padding is not required.

First summarise pupil availability:

pupil_summary <- summarise_gazepoint_pupil(master)

pupil_summary$overall
pupil_summary$subject_summary
pupil_summary$media_summary

Flag missing, non-finite, implausible, and IQR-outlying pupil samples:

flagged_pupil <- flag_gazepoint_pupil(
  master,
  pupil_col = "pupil"
)

attr(flagged_pupil, "gp3_pupil_flag_overview")

Interpolate short internal pupil gaps:

interpolated_pupil <- interpolate_gazepoint_pupil(
  flagged_pupil,
  pupil_col = "pupil_for_preprocessing",
  time_col = "time",
  group_cols = c("subject", "MEDIA_ID", "trial_global")
)

attr(interpolated_pupil, "gp3_pupil_interpolation_overview")

Apply baseline correction:

baseline_corrected <- baseline_correct_gazepoint_pupil(
  interpolated_pupil,
  pupil_col = "pupil_interpolated",
  time_col = "time",
  group_cols = c("subject", "MEDIA_ID", "trial_global"),
  baseline_window = c(0, 200),
  min_baseline_samples = 1
)

attr(baseline_corrected, "gp3_pupil_baseline_overview")

Smooth the baseline-corrected pupil signal:

smoothed_pupil <- smooth_gazepoint_pupil(
  baseline_corrected,
  pupil_col = "pupil_baseline_corrected",
  time_col = "time",
  group_cols = c("subject", "MEDIA_ID", "trial_global"),
  window_samples = 5,
  method = "mean",
  align = "center",
  min_points = 2
)

attr(smoothed_pupil, "gp3_pupil_smoothing_overview")

Summarise the processed pupil signal into analysis windows:

pupil_windows <- summarise_gazepoint_pupil_windows(
  smoothed_pupil,
  pupil_col = "pupil_smoothed",
  time_col = "time",
  windows = c(0, 500, 1000, 2000, 5000),
  group_cols = c("subject", "MEDIA_ID", "trial_global", "condition"),
  min_valid_samples = 1
)

pupil_windows

The light branch gives a simple path from raw pupil values to window-level summaries. For stricter cleaning, use the conservative artifact-cleaned branch.

4. Pupil preprocessing: conservative artifact-cleaned branch

Use the conservative branch when blink/trackloss padding, pupil-speed artifacts, binocular disagreement, or stricter preprocessing decisions are important.

Create a reusable preprocessing registry:

registry <- create_gazepoint_preprocessing_registry(
  blink_padding_ms = 50,
  interpolation_max_gap_ms = 150,
  smoothing_window_samples = 5,
  baseline_window = c(0, 200)
)

registry

Apply conservative artifact flagging:

artifact_pupil <- flag_gazepoint_pupil_artifacts(
  master,
  registry = registry,
  pupil_col = "pupil",
  time_col = "time",
  group_cols = c("subject", "MEDIA_ID", "trial_global")
)

attr(artifact_pupil, "gp3_pupil_artifact_overview")

Interpolate short internal gaps after artifact removal:

interpolated_artifact_pupil <- interpolate_gazepoint_pupil(
  artifact_pupil,
  pupil_col = "pupil_clean",
  time_col = "time",
  group_cols = c("subject", "MEDIA_ID", "trial_global")
)

Apply baseline correction:

baseline_artifact_pupil <- baseline_correct_gazepoint_pupil(
  interpolated_artifact_pupil,
  pupil_col = "pupil_interpolated",
  time_col = "time",
  group_cols = c("subject", "MEDIA_ID", "trial_global"),
  baseline_window = c(0, 200),
  min_baseline_samples = 1
)

Smooth the processed pupil signal:

smoothed_artifact_pupil <- smooth_gazepoint_pupil(
  baseline_artifact_pupil,
  pupil_col = "pupil_baseline_corrected",
  time_col = "time",
  group_cols = c("subject", "MEDIA_ID", "trial_global"),
  window_samples = 5,
  method = "mean",
  align = "center",
  min_points = 2
)

Create pupil-window summaries from the conservative branch:

pupil_windows_conservative <- summarise_gazepoint_pupil_windows(
  smoothed_artifact_pupil,
  pupil_col = "pupil_smoothed",
  time_col = "time",
  windows = c(0, 500, 1000, 2000, 5000),
  group_cols = c("subject", "MEDIA_ID", "trial_global", "condition"),
  min_valid_samples = 1
)

pupil_windows_conservative

The conservative branch is recommended when pupil preprocessing decisions may affect interpretation or when the study will be reported in a manuscript.

5. Pupil audits and reliability checks

After preprocessing, run pupil audits to document missingness, interpolation, baseline quality, imbalance, drift, event-response overlap, reliability, and sensitivity to preprocessing decisions.

Audit interpolation gaps:

gap_audit <- audit_gazepoint_pupil_gaps(
  interpolated_artifact_pupil,
  group_cols = c("subject", "MEDIA_ID", "trial_global")
)

gap_audit$overview
gap_audit$gap_summary

Audit baseline quality:

baseline_audit <- audit_gazepoint_pupil_baseline(
  baseline_artifact_pupil,
  group_cols = c("subject", "MEDIA_ID", "trial_global")
)

baseline_audit$overview
baseline_audit$baseline_summary

Audit preprocessing imbalance across conditions:

imbalance_audit <- audit_gazepoint_pupil_imbalance(
  smoothed_artifact_pupil,
  group_cols = "condition"
)

imbalance_audit$overview
imbalance_audit$imbalance_summary

Audit tonic pupil drift over time:

drift_audit <- audit_gazepoint_pupil_drift(
  smoothed_artifact_pupil,
  pupil_col = "pupil_smoothed",
  time_col = "time",
  group_cols = c("subject", "MEDIA_ID", "trial_global")
)

drift_audit$overview
drift_audit$drift_summary

Audit possible event-response overlap risk:

overlap_audit <- audit_gazepoint_pupil_overlap_risk(
  master,
  time_col = "time",
  event_col = "event_label",
  group_cols = c("subject", "MEDIA_ID", "trial_global")
)

overlap_audit$overview
overlap_audit$risk_summary

Check pupil reliability:

pupil_reliability <- audit_gazepoint_pupil_reliability(
  pupil_windows_conservative,
  subject_col = "subject",
  outcome_col = "mean_pupil",
  condition_col = "condition"
)

pupil_reliability$overview
pupil_reliability$reliability_summary

Run PCHIP interpolation sensitivity when method sensitivity is needed:

pchip_pupil <- interpolate_gazepoint_pupil_pchip(
  artifact_pupil,
  pupil_col = "pupil_clean",
  time_col = "time",
  group_cols = c("subject", "MEDIA_ID", "trial_global")
)

attr(pchip_pupil, "gp3_pchip_overview")

Audit stimulus luminance when image stimuli are used:

luminance_audit <- audit_gazepoint_stimulus_luminance(
  stimulus_data,
  stimulus_col = "stimulus_file",
  condition_col = "condition"
)

luminance_audit$overview
luminance_audit$stimulus_summary
luminance_audit$condition_summary

Apply an optional Hampel filter to pupil data:

hampel_pupil <- flag_gazepoint_pupil_hampel(
  smoothed_artifact_pupil,
  pupil_col = "pupil_smoothed",
  time_col = "time",
  grouping_cols = c("subject", "MEDIA_ID", "trial_global"),
  window_size_samples = 7,
  k = 3,
  min_valid_samples = 3,
  corrected_col = "pupil_hampel_corrected"
)

attr(hampel_pupil, "gp3_hampel_overview")
attr(hampel_pupil, "gp3_hampel_status_summary")

Define and run a preprocessing multiverse when conclusions need sensitivity checks across reasonable preprocessing decisions:

preprocessing_mv <- create_gazepoint_preprocessing_multiverse(
  pupil_max_gap_ms = c(75, 150, 250),
  pupil_smoothing_window_samples = c(3, 5, 7),
  pupil_baseline_windows = list(c(0, 200), c(-200, 0)),
  pupil_artifact_padding_ms = c(0, 50),
  include_pupil = TRUE,
  include_aoi = FALSE,
  label_prefix = "study1"
)

pupil_mv_results <- run_gazepoint_pupil_multiverse(
  master,
  preprocessing_mv,
  pupil_col = "pupil",
  time_col = "time",
  group_cols = c("subject", "MEDIA_ID", "trial_global"),
  keep_outputs = TRUE
)

pupil_mv_summary <- summarise_gazepoint_multiverse_results(
  pupil = pupil_mv_results
)

pupil_mv_summary$overview
pupil_mv_summary$branch_summary
pupil_mv_summary$failure_summary

Use these audits and sensitivity checks to make preprocessing decisions transparent before fitting confirmatory models.

6. Pupil-window LMM workflow

Use pupil-window LMMs when the primary hypothesis concerns predefined pupil windows.

Start from pupil-window summaries:

pupil_windows <- pupil_windows_conservative

Prepare window-level model data:

pupil_window_model_data <- prepare_gazepoint_pupil_window_model_data(
  pupil_windows,
  outcome_col = "mean_pupil",
  subject_col = "subject",
  condition_col = "condition",
  window_col = "window_label",
  trial_col = "trial_global",
  valid_samples_col = "n_valid_samples",
  total_samples_col = "n_samples",
  min_valid_samples = 1
)

dplyr::glimpse(pupil_window_model_data)

dplyr::count(
  pupil_window_model_data,
  pupil_window_condition,
  pupil_window_label,
  pupil_window_model_status
)

Fit the confirmatory pupil-window LMM:

pupil_window_lmm <- fit_gazepoint_pupil_window_lmm(
  pupil_window_model_data,
  random_window_slopes = FALSE,
  use_weights = TRUE,
  REML = FALSE
)

pupil_window_lmm$model_status
pupil_window_lmm$formula
pupil_window_lmm$comparison
pupil_window_lmm$fixed_effects

Run model-family sensitivity checks:

pupil_window_sensitivity <- fit_gazepoint_pupil_window_sensitivity(
  pupil_window_model_data,
  model_types = c(
    "unweighted_lmm",
    "weighted_lmm",
    "fixed_lm",
    "weighted_lm"
  ),
  include_condition = TRUE,
  include_window = TRUE,
  include_interaction = TRUE
)

pupil_window_sensitivity$comparison
pupil_window_sensitivity$fixed_effects
pupil_window_sensitivity$formulas

Compare nested models when needed:

nested_pupil_models <- compare_gazepoint_nested_models(
  models = list(
    null = pupil_m0,
    condition = pupil_m1,
    window = pupil_m2,
    interaction = pupil_m3
  ),
  comparison = "sequential"
)

nested_pupil_models$model_table
nested_pupil_models$lrt_table
nested_pupil_models$ranking_table

Run leave-one-participant sensitivity if the main effect may be driven by a single participant:

pupil_loo <- run_gazepoint_model_leave_one_out(
  data = pupil_window_model_data,
  unit_col = "pupil_window_subject",
  fit_function = function(dat) {
    stats::lm(pupil_window_outcome ~ pupil_window_condition * pupil_window_label, data = dat)
  },
  effect_terms = "pupil_window_condition"
)

pupil_loo$overview
pupil_loo$effect_summary

Plot model-implied predictions when predict() is available:

pupil_prediction_plot <- plot_gazepoint_model_predictions(
  data = pupil_window_model_data,
  model = pupil_window_lmm$model,
  x_col = "pupil_window_label",
  outcome_col = "pupil_window_outcome",
  condition_col = "pupil_window_condition"
)

pupil_prediction_plot

For most confirmatory pupil-window analyses, the recommended sequence is:

pupil_window_model_data <- prepare_gazepoint_pupil_window_model_data(...)
pupil_window_lmm <- fit_gazepoint_pupil_window_lmm(pupil_window_model_data)
pupil_window_sensitivity <- fit_gazepoint_pupil_window_sensitivity(pupil_window_model_data)
diagnostics <- diagnose_gazepoint_glmm(pupil_window_lmm)
model_summary <- tidy_gazepoint_model_summary(pupil_window_lmm)

7. AOI entries, AOI windows, and AOI GLMM workflow

Use AOI-window GLMMs when the primary hypothesis concerns predefined AOI time windows.

Start from a validated master table with sample-level AOI states:

validation <- validate_gazepoint_master(master)

validation$summary

Create ordered AOI-entry episodes:

aoi_entries <- summarise_gazepoint_aoi_entries(
  master,
  time_col = "time",
  aoi_col = "aoi_current",
  group_cols = c("subject", "MEDIA_ID", "trial_global")
)

dplyr::glimpse(aoi_entries)

Create AOI-window summaries:

aoi_windows <- summarise_gazepoint_aoi_windows(
  master,
  windows = c(0, 500, 1000, 2000, 5000, 10000),
  time_col = "time",
  aoi_col = "aoi_current",
  subject_col = "subject",
  condition_col = "condition",
  group_cols = c("subject", "MEDIA_ID", "trial_global"),
  target_aoi_values = "AOI 2",
  distractor_aoi_values = c("AOI 0", "AOI 1")
)

dplyr::glimpse(aoi_windows)

Inspect target-looking proportions:

dplyr::select(
  aoi_windows,
  subject,
  condition,
  MEDIA_ID,
  trial_global,
  window_label,
  n_window_samples,
  n_target_samples,
  n_distractor_samples,
  n_valid_denominator_samples,
  target_sample_prop_valid,
  aoi_window_status
)

Audit denominator adequacy before fitting binomial models:

aoi_window_denominator_audit <- audit_gazepoint_aoi_window_denominators(
  aoi_windows,
  min_denominator_samples = 5,
  min_valid_denominator_prop = 0.70,
  max_denominator_cv = 0.25,
  max_condition_ratio = 2
)

aoi_window_denominator_audit$overview
aoi_window_denominator_audit$window_summary
aoi_window_denominator_audit$condition_window_summary
aoi_window_denominator_audit$denominator_imbalance

dplyr::count(
  aoi_window_denominator_audit$row_audit,
  denominator_audit_status
)

Prepare binomial success/failure data for mixed-effects logistic regression:

aoi_glmm_data <- prepare_gazepoint_aoi_glmm_data(
  aoi_windows,
  success_col = "n_target_samples",
  denominator = "valid",
  subject_col = "subject",
  condition_col = "condition",
  window_col = "window_label",
  window_start_col = "window_start_ms",
  window_end_col = "window_end_ms",
  min_denominator_samples = 5,
  outcome_label = "target"
)

dplyr::glimpse(aoi_glmm_data)

dplyr::count(
  aoi_glmm_data,
  aoi_glmm_condition,
  aoi_glmm_window,
  aoi_glmm_status
)

Fit the main AOI-window binomial GLMM:

aoi_glmm_fit <- fit_gazepoint_aoi_window_glmm(
  aoi_glmm_data,
  random_window_slopes = FALSE
)

aoi_glmm_fit$model_status
aoi_glmm_fit$formula
aoi_glmm_fit$random_effect_structure
aoi_glmm_fit$comparison

if (!is.null(aoi_glmm_fit$model)) {
  lme4::fixef(aoi_glmm_fit$model)
}

Transform AOI proportions into empirical logits for sensitivity models:

aoi_emp_logit <- transform_gazepoint_aoi_empirical_logit(
  aoi_glmm_data,
  numerator_col = "aoi_glmm_success",
  denominator_col = "aoi_glmm_denominator",
  correction = 0.5
)

dplyr::glimpse(aoi_emp_logit)
attr(aoi_emp_logit, "gp3_empirical_logit_overview")

Run AOI model-family sensitivity checks:

aoi_sensitivity <- fit_gazepoint_aoi_model_sensitivity(
  aoi_glmm_data,
  model_types = c(
    "binomial_glmm",
    "empirical_logit_lmm",
    "proportion_lmm",
    "quasibinomial_glm"
  ),
  include_condition = TRUE,
  include_window = TRUE,
  include_interaction = TRUE,
  random_intercept = TRUE
)

aoi_sensitivity$comparison
aoi_sensitivity$fixed_effects
aoi_sensitivity$formulas

For most confirmatory AOI-window analyses, the recommended sequence is:

aoi_windows <- summarise_gazepoint_aoi_windows(...)
aoi_window_denominator_audit <- audit_gazepoint_aoi_window_denominators(aoi_windows)
aoi_glmm_data <- prepare_gazepoint_aoi_glmm_data(aoi_windows)
aoi_glmm_fit <- fit_gazepoint_aoi_window_glmm(aoi_glmm_data)
aoi_sensitivity <- fit_gazepoint_aoi_model_sensitivity(aoi_glmm_data)

8. AOI/fixation/transition workflow

Use this workflow when the research question concerns looking episodes, fixation summaries, AOI sequences, transition matrices, scanpath structure, or event-contingent alignment.

Create transition-ready AOI sequences:

aoi_sequences <- prepare_gazepoint_aoi_sequences(
  master,
  time_col = "time",
  aoi_col = "aoi_current",
  group_cols = c("subject", "MEDIA_ID", "trial_global")
)

dplyr::glimpse(aoi_sequences)

Summarise AOI transitions at the trial level:

aoi_transition_summary <- summarise_gazepoint_aoi_transitions(
  master,
  time_col = "time",
  aoi_col = "aoi_current",
  group_cols = c("subject", "MEDIA_ID", "trial_global"),
  target_aoi_values = "AOI 2",
  distractor_aoi_values = c("AOI 0", "AOI 1")
)

aoi_transition_summary

Create AOI transition matrices:

aoi_transition_matrix <- compute_gazepoint_aoi_transition_matrix(
  master,
  time_col = "time",
  aoi_col = "aoi_current",
  group_cols = c("subject", "MEDIA_ID", "trial_global"),
  target_aoi_values = "AOI 2",
  distractor_aoi_values = c("AOI 0", "AOI 1")
)

aoi_transition_matrix$count_matrix
aoi_transition_matrix$probability_matrix
aoi_transition_matrix$long_table

Plot the transition matrix:

plot_gazepoint_aoi_transition_matrix(
  aoi_transition_matrix,
  value = "prob",
  show_labels = TRUE,
  title = "AOI transition probabilities"
)

Create time-varying AOI transition matrices:

time_varying_transition_matrix <- compute_gazepoint_time_varying_transition_matrix(
  master,
  time_col = "time",
  state_col = "aoi_current",
  group_cols = c("subject", "MEDIA_ID", "trial_global"),
  windows = c(0, 500, 1000, 2000, 5000)
)

time_varying_transition_matrix$overview
time_varying_transition_matrix$transition_summary

Create trial-level AOI features:

aoi_trial_features <- summarise_gazepoint_aoi_trial_features(
  master,
  time_col = "time",
  aoi_col = "aoi_current",
  group_cols = c("subject", "MEDIA_ID", "trial_global"),
  target_aoi_values = "AOI 2",
  distractor_aoi_values = c("AOI 0", "AOI 1")
)

aoi_trial_features

Create trial-level fixation features from Gazepoint fixation exports:

fixation_trial_features <- summarise_gazepoint_fixation_trials(
  all_fix,
  target_aoi_values = "AOI 2",
  distractor_aoi_values = c("AOI 0", "AOI 1")
)

fixation_trial_features

Create fixation-, saccade-, or AOI-contingent aligned data:

fixation_aligned <- prepare_gazepoint_fixation_aligned_data(
  master,
  time_col = "time",
  participant_col = "subject",
  trial_col = "trial_global",
  aoi_col = "aoi_current",
  target_aoi = "AOI 2",
  fixation_col = "is_fixation",
  alignment_event = "first_fixation_to_target",
  baseline_window = c(-200, 0),
  analysis_window = c(0, 800)
)

fixation_aligned$overview
fixation_aligned$event_table
fixation_aligned$trial_summary

Prepare dependency-free advanced sequence-model objects:

markov_obj <- create_gazepoint_markovchain_object(
  aoi_sequences,
  state_col = "aoi"
)

semimarkov_data <- prepare_gazepoint_semimarkov_data(
  aoi_sequences,
  state_col = "aoi",
  time_col = "time"
)

hmm_data <- prepare_gazepoint_hmm_data(
  aoi_sequences,
  state_col = "aoi",
  observation_cols = c("x", "y", "pupil")
)

markov_obj$overview
semimarkov_data$overview
hmm_data$overview

These helpers prepare sequence and transition data for inspection, reporting, export, or specialist modelling packages. They do not directly fit Markov-chain, semi-Markov, or hidden Markov models.

9. Pupil GAMM, AOI GAMM, PFE-GAMM, and GCA workflow

Use time-course models when the research question concerns smooth trajectories rather than predefined confirmatory windows.

Pupil GAMM

Prepare binned pupil time-course data:

pupil_gamm_data <- prepare_gazepoint_pupil_gamm_data(
  smoothed_artifact_pupil,
  pupil_col = "pupil_smoothed",
  time_col = "time",
  subject_col = "subject",
  condition_col = "condition",
  trial_col = "trial_global",
  bin_width_ms = 50,
  min_valid_samples = 1
)

dplyr::glimpse(pupil_gamm_data)

dplyr::count(
  pupil_gamm_data,
  condition,
  condition_status,
  gamm_data_status
)

Fit the main pupil GAMM:

pupil_gamm_fit <- fit_gazepoint_pupil_gamm(
  pupil_gamm_data,
  n_time_basis = 10,
  discrete = TRUE
)

pupil_gamm_fit$model_status
pupil_gamm_fit$formula

summary(pupil_gamm_fit$model)

The model can include smooth time effects, condition-by-time smooths when multiple conditions are available, subject random effects, optional observation weights, and optional autocorrelation settings.

Gaze-position / PFE sensitivity GAMM

Fit a gaze-position-adjusted PFE sensitivity model:

pupil_pfe_fit <- fit_gazepoint_pupil_pfe_gamm(
  pupil_gamm_data,
  n_time_basis = 10,
  n_position_basis = 8,
  discrete = TRUE
)

pupil_pfe_fit$sensitivity_status
pupil_pfe_fit$main_fit$formula
pupil_pfe_fit$pfe_formula
pupil_pfe_fit$comparison

The PFE model should be treated as a sensitivity analysis rather than as the default pupil correction. It tests whether gaze position explains additional pupil variance through a two-dimensional smooth term over gaze coordinates:

te(mean_x, mean_y)

Growth Curve Analysis

Prepare binned pupil data for Growth Curve Analysis:

pupil_gca_data <- prepare_gazepoint_gca_data(
  pupil_gamm_data,
  pupil_col = "mean_pupil",
  time_col = "time_bin_center_ms",
  subject_col = "subject",
  condition_col = "condition",
  degree = 3,
  orthogonal = TRUE,
  valid_samples_col = "n_valid_samples",
  min_valid_samples = 1
)

dplyr::glimpse(pupil_gca_data)

dplyr::count(
  pupil_gca_data,
  condition,
  condition_status,
  gca_data_status
)

Fit a GCA mixed model:

pupil_gca_fit <- fit_gazepoint_gca(
  pupil_gca_data,
  REML = FALSE
)

pupil_gca_fit$model_status
pupil_gca_fit$random_effect_structure
pupil_gca_fit$fallback_used
pupil_gca_fit$singular_fit
pupil_gca_fit$comparison

For quick inspection, avoid printing the full model summary unless needed. Use:

lme4::fixef(pupil_gca_fit$model)
lme4::VarCorr(pupil_gca_fit$model)

Plot observed and fitted GCA trajectories:

plot_gazepoint_gca(
  pupil_gca_fit,
  title = "Observed and fitted GCA trajectory"
)

Subject-level observed trajectories can also be shown:

plot_gazepoint_gca(
  pupil_gca_fit,
  show_subjects = TRUE,
  title = "Subject-level and fitted GCA trajectories"
)

AOI time-course GAMM

Prepare AOI-GAMM data from an AOI-state column:

aoi_gamm_data <- prepare_gazepoint_aoi_gamm_data(
  master,
  aoi_col = "aoi_current",
  target_aoi_values = "AOI 2",
  subject_col = "subject",
  condition_col = "condition",
  time_col = "time",
  trial_col = "trial_global",
  time_window = c(0, 2000),
  bin_size_ms = 50,
  denominator = "valid",
  min_denominator_samples = 1,
  outcome_label = "target_aoi"
)

dplyr::glimpse(aoi_gamm_data)

dplyr::count(
  aoi_gamm_data,
  .gp3_aoi_gamm_condition,
  .gp3_aoi_gamm_condition_status,
  .gp3_aoi_gamm_status
)

Alternatively, create a logical target-AOI indicator first:

master_for_aoi_gamm <- master |>
  dplyr::mutate(target_aoi = aoi_current == "AOI 2")

aoi_gamm_data <- prepare_gazepoint_aoi_gamm_data(
  master_for_aoi_gamm,
  outcome_col = "target_aoi",
  subject_col = "subject",
  condition_col = "condition",
  time_col = "time",
  trial_col = "trial_global",
  time_window = c(0, 2000),
  bin_size_ms = 50,
  min_denominator_samples = 1,
  outcome_label = "target_aoi"
)

Fit the AOI time-course GAMM:

aoi_gamm_fit <- fit_gazepoint_aoi_gamm(
  aoi_gamm_data,
  include_condition = TRUE,
  condition_smooths = TRUE,
  random_subject = TRUE,
  random_subject_time = FALSE,
  time_k = 10
)

aoi_gamm_fit$model_status
aoi_gamm_fit$condition_status
aoi_gamm_fit$formula_text
aoi_gamm_fit$diagnostics
aoi_gamm_fit$smooth_table

Plot observed AOI proportions and fitted GAMM trajectories:

aoi_gamm_plot <- plot_gazepoint_aoi_gamm(
  aoi_gamm_fit,
  n_time_points = 100,
  include_observed = TRUE,
  include_fitted = TRUE,
  show_ci = TRUE
)

aoi_gamm_plot

AOI time-course GAMMs are complementary to AOI-window GLMMs. Use AOI-window GLMMs for predefined confirmatory windows and AOI-GAMMs when the research question concerns smooth target-looking trajectories.

10. Cluster permutation and divergence-point workflow

Use cluster-based permutation testing for time-course inference. Use divergence-point estimation as complementary onset/sensitivity evidence.

Prepare time-course data for cluster-based permutation testing:

cluster_data <- prepare_gazepoint_cluster_data(
  pupil_gamm_data,
  outcome_col = "mean_pupil",
  time_col = "time_bin_center_ms",
  subject_col = "subject",
  condition_col = "condition"
)

dplyr::glimpse(cluster_data)

Run the cluster-based permutation test:

cluster_results <- run_gazepoint_cluster_permutation(
  cluster_data,
  condition_levels = c("control", "treatment"),
  n_permutations = 1000,
  seed = 123
)

cluster_results$overview
cluster_results$clusters

Summarise cluster results:

cluster_summary <- summarise_gazepoint_clusters(cluster_results)

cluster_summary$overview
cluster_summary$all_clusters
cluster_summary$significant_clusters
cluster_summary$circularity_warning

Plot cluster results:

plot_gazepoint_cluster_results(
  cluster_results,
  plot = "difference"
)

plot_gazepoint_cluster_results(
  cluster_results,
  plot = "statistic"
)

Estimate the earliest reliable divergence point:

divergence <- estimate_gazepoint_divergence_point(
  data = timecourse_data,
  outcome_col = "mean_pupil",
  time_col = "time_bin_center_ms",
  condition_col = "condition",
  participant_col = "subject",
  comparison = c("control", "treatment"),
  bootstrap_unit = "participant",
  n_boot = 1000,
  consecutive_points = 2,
  seed = 123
)

divergence$overview
divergence$divergence_point
divergence$difference_summary
divergence$bootstrap_onsets

The cluster-based permutation branch is intended for time-course inference. Do not use a detected exploratory cluster to define a confirmatory window and then retest that same window as if it had been specified a priori.

11. Model diagnostics and manuscript tables

Use model diagnostics and reporting helpers after fitting confirmatory models and sensitivity models.

Check convergence, singularity, and overdispersion separately:

check_gazepoint_model_convergence(aoi_glmm_fit$model)

check_gazepoint_model_singularity(aoi_glmm_fit$model)

check_gazepoint_model_overdispersion(aoi_glmm_fit$model)

Run a combined diagnostics bundle for GLMM, LMM, or GLM models:

glmm_diagnostics <- diagnose_gazepoint_glmm(
  aoi_glmm_fit,
  model_name = "aoi_window_glmm",
  use_dharma = FALSE
)

glmm_diagnostics$overview
glmm_diagnostics$convergence
glmm_diagnostics$singularity
glmm_diagnostics$overdispersion
glmm_diagnostics$dharma

Run a combined diagnostics bundle for mgcv::gam() or mgcv::bam() models:

gamm_diagnostics <- diagnose_gazepoint_gamm(
  aoi_gamm_fit,
  model_name = "aoi_timecourse_gamm",
  use_dharma = FALSE
)

gamm_diagnostics$overview
gamm_diagnostics$convergence
gamm_diagnostics$basis
gamm_diagnostics$overdispersion
gamm_diagnostics$dharma

Optional DHARMa diagnostics can be requested when DHARMa is installed:

glmm_diagnostics_dharma <- diagnose_gazepoint_glmm(
  aoi_glmm_fit,
  use_dharma = TRUE,
  dharma_simulations = 250,
  seed = 123
)

glmm_diagnostics_dharma$dharma

If DHARMa is not installed, diagnostics return skipped_missing_package rather than failing. DHARMa is an optional suggested dependency, not a required import.

Compare nested model sequences:

nested_models <- compare_gazepoint_nested_models(
  models = list(
    null = m0,
    time = m1,
    condition = m2,
    interaction = m3
  ),
  comparison = "sequential"
)

nested_models$overview
nested_models$model_table
nested_models$lrt_table
nested_models$ranking_table

Plot observed summaries together with model-implied prediction trajectories:

prediction_plot <- plot_gazepoint_model_predictions(
  data = model_data,
  model = fitted_model,
  x_col = "time",
  outcome_col = "outcome",
  condition_col = "condition",
  prediction_type = "response"
)

prediction_plot
attr(prediction_plot, "gp3_model_prediction_overview")
attr(prediction_plot, "gp3_model_prediction_prediction_summary")

Run leave-one-unit sensitivity checks for fitted models:

loo_sensitivity <- run_gazepoint_model_leave_one_out(
  data = model_data,
  unit_col = "subject",
  fit_function = function(dat) {
    stats::lm(outcome ~ condition * time, data = dat)
  },
  effect_terms = "conditiontreatment"
)

loo_sensitivity$overview
loo_sensitivity$effect_summary
loo_sensitivity$leave_one_effects

Create a fixed-effect summary table:

fixed_effects <- summarise_gazepoint_fixed_effects(
  aoi_glmm_fit,
  model_name = "aoi_window_glmm",
  exponentiate = TRUE
)

fixed_effects

Use exponentiate = TRUE for logistic, Poisson, or other log/link models when odds ratios, rate ratios, or exponentiated coefficients are preferred.

Create a complete tidy model-summary object:

model_summary <- tidy_gazepoint_model_summary(
  aoi_glmm_fit,
  model_name = "aoi_window_glmm",
  exponentiate = TRUE,
  use_dharma = FALSE
)

model_summary$overview
model_summary$model_info
model_summary$fixed_effects
model_summary$diagnostics$overview

Estimate marginal means and pairwise contrasts when emmeans is installed:

emm_summary <- summarise_gazepoint_emmeans(
  aoi_glmm_fit,
  specs = "aoi_glmm_condition",
  model_name = "aoi_window_glmm",
  type = "response",
  adjust = "tukey"
)

emm_summary$overview
emm_summary$emmeans
emm_summary$contrasts

For condition-by-window models, estimated marginal means can also be requested within windows:

emm_by_window <- summarise_gazepoint_emmeans(
  aoi_glmm_fit,
  specs = "aoi_glmm_condition",
  by = "aoi_glmm_window",
  model_name = "aoi_window_glmm",
  type = "response"
)

emm_by_window$emmeans
emm_by_window$contrasts

Export manuscript-ready model tables to CSV:

model_table_files <- export_gazepoint_model_tables(
  model_summary = model_summary,
  emmeans_summary = emm_summary,
  output_dir = output_dir,
  prefix = "aoi_window_glmm"
)

model_table_files

This writes an export index plus available tables such as:

aoi_window_glmm_model_overview.csv
aoi_window_glmm_model_info.csv
aoi_window_glmm_fixed_effects.csv
aoi_window_glmm_model_settings.csv
aoi_window_glmm_diagnostics_overview.csv
aoi_window_glmm_emmeans_overview.csv
aoi_window_glmm_emmeans.csv
aoi_window_glmm_contrasts.csv
aoi_window_glmm_emmeans_settings.csv
aoi_window_glmm_export_index.csv

The manuscript-table helpers are designed to return structured tables rather than stopping on normal modelling issues. Missing optional emmeans, unsupported model classes, failed contrasts, diagnostic warnings, and disabled diagnostics are recorded through status fields.

12. Real-data readiness and reporting checklist

Use this final-stage workflow before interpreting real study results or preparing a manuscript.

Run the real-data readiness gate:

readiness <- check_gazepoint_real_data_readiness(
  data = master,
  analysis_type = "combined",
  participant_col = "subject",
  trial_col = "trial_global",
  time_col = "time",
  condition_col = "condition",
  aoi_col = "aoi_current",
  pupil_col = "pupil_smoothed"
)

readiness$overview
readiness$gate_decision
readiness$checks
readiness$data_summary
readiness$condition_summary

Create explicit trial-level and participant-level exclusion recommendations:

exclusion_recommendations <- recommend_gazepoint_exclusions(
  master,
  participant_col = "subject",
  trial_col = "trial_global",
  condition_col = "condition",
  validity_col = "valid",
  x_col = "x",
  y_col = "y",
  pupil_col = "pupil",
  artifact_col = "artifact",
  min_trial_samples = 10,
  max_trial_missing_prop = 0.50,
  max_trial_artifact_prop = 0.50,
  min_participant_trials = 2,
  min_participant_valid_trials = 1
)

exclusion_recommendations$overview
exclusion_recommendations$participant_recommendations
exclusion_recommendations$trial_recommendations
exclusion_recommendations$exclusion_table

recommend_gazepoint_exclusions() recommends exclusions only. It does not remove participants, trials, or samples automatically.

Apply offline gaze recalibration only when known target/check-target coordinates are available:

recalibrated_gaze <- recalibrate_gazepoint_gaze(
  master,
  x_col = "x",
  y_col = "y",
  target_x_col = "target_x",
  target_y_col = "target_y",
  time_col = "time",
  grouping_cols = c("subject", "trial_global"),
  calibration_col = "is_check_target",
  calibration_value = TRUE,
  method = "median_shift",
  min_valid_points = 3
)

attr(recalibrated_gaze, "gp3_gaze_recalibration_overview")
attr(recalibrated_gaze, "gp3_gaze_recalibration_group_summary")

This helper estimates group-level horizontal and vertical gaze shifts and applies them to gaze coordinates. It is useful only when the study contains known target/check-target coordinates. It should not be used as a generic correction when no target reference is available.

Create a reporting checklist:

reporting <- create_gazepoint_reporting_checklist(
  data = master,
  objects = list(
    readiness = readiness,
    exclusion_recommendations = exclusion_recommendations,
    pupil_audit = gap_audit,
    aoi_model = aoi_glmm_fit,
    model_summary = model_summary
  ),
  analysis_type = "combined",
  study_title = "Gazepoint eye-tracking study"
)

reporting$overview
reporting$checklist
reporting$section_summary
reporting$object_summary

Create a final analysis-decision audit after confirmatory models, sensitivity checks, exploratory time-course analyses, diagnostics, and manuscript-ready tables have been created:

branch_roles <- tibble::tibble(
  branch_name = c(
    "aoi_glmm",
    "aoi_sensitivity",
    "cluster_test",
    "model_summary"
  ),
  decision_type = c(
    "confirmatory",
    "sensitivity",
    "exploratory",
    "reporting"
  ),
  analysis_family = c(
    "aoi_window_glmm",
    "aoi_model_sensitivity",
    "cluster_permutation",
    "model_tables"
  )
)

decision_audit <- create_gazepoint_analysis_decision_audit(
  aoi_glmm = aoi_glmm_fit,
  aoi_sensitivity = aoi_sensitivity,
  cluster_test = cluster_results,
  model_summary = model_summary,
  branch_roles = branch_roles,
  required_confirmatory = "aoi_glmm",
  diagnostics_required = TRUE,
  require_clean_diagnostics = FALSE
)

decision_audit$overview
decision_audit$branch_audit
decision_audit$diagnostics_summary
decision_audit$interpretation_cautions
decision_audit$readiness

Possible readiness outcomes include:

"ready"
"ready_with_cautions"
"not_ready"

Use ready_with_cautions as a reporting signal, not as a package failure. It means that the analysis can proceed, but the flagged cautions should be reported transparently.

Optional external cross-checks

Optional external cross-checks can be run when the relevant packages are available:

gazer_crosscheck <- run_gazepoint_gazer_crosscheck(master)

eyetools_detection <- run_gazepoint_eyetools_fixation_detection(
  master,
  method = "dispersion"
)

Optional external checks skip or report controlled compatibility statuses when optional packages or method branches are unavailable.

Package-adapter exports

gp3tools includes dependency-free adapter helpers for preparing Gazepoint master/sample tables for use in other R eye-tracking workflows.

eyetrackingr_data <- prepare_gazepoint_eyetrackingr_data(master)

pupillometryr_data <- prepare_gazepoint_pupillometryr_data(master)

gazer_data <- prepare_gazepoint_gazer_data(master)

eyetools_data <- prepare_gazepoint_eyetools_data(master)

The adapter helpers do not import the external packages directly. Instead, they return clean tibbles with standardised column names, status fields, and metadata attributes.

Current package status

Version 2.3.0 includes the core Gazepoint import, quality-control, pupil, AOI, fixation/transition, time-course, model-diagnostics, reporting, ecosystem-adapter, external face-data, and workflow-documentation layers.

Release validation for version 2.3.0 should end with:

devtools::check()
# 0 errors | 0 warnings | 0 notes

Focused tests for the recent external face-data, multimodal, reporting, and workflow-documentation branches have also passed with FAIL 0, WARN 0, and SKIP 0.

During full tests, boundary (singular) fit: see help('isSingular') messages may appear in mixed-model diagnostic contexts. These are expected diagnostic messages from singular-fit test fixtures and are not package failures when the final test summary reports FAIL 0 | WARN 0.

On some Windows systems, a Quarto/TMPDIR message may appear after devtools::check(). This is harmless when the final R CMD check results report:

0 errors | 0 warnings | 0 notes

The build may show a message that the package depends on R >= 4.1.0 because native pipe syntax is used. This is expected.

Example datasets

gp3tools includes lightweight synthetic example datasets so examples, vignettes, tests, and user workflows can be run without private Gazepoint files.

data("gazepoint_example_master")
data("gazepoint_example_fixations")
data("gazepoint_example_aoi_geometry")
data("gazepoint_example_aoi_windows")
data("gazepoint_example_pupil_windows")

The example datasets are artificial and are not from a real participant study. They are intended to show expected column names and runnable workflow structure.

dplyr::glimpse(gazepoint_example_master)
dplyr::glimpse(gazepoint_example_fixations)
dplyr::glimpse(gazepoint_example_aoi_windows)
dplyr::glimpse(gazepoint_example_pupil_windows)

Use these objects when you want to try core workflows without first importing private Gazepoint export files.

Important note

gp3tools can parse official Gazepoint Analysis summary exports, but metrics recomputed from all-gaze and fixation files may not always exactly reproduce Gazepoint’s internal summary calculations. For official Gazepoint summary values, use read_gazepoint_summary(). For transparent reproducible calculations from exported rows, use the sample-level and fixation-level summary functions.

Large-export performance benchmarking

gp3tools includes an auditable framework for measuring selected operations across synthetic export sizes and file counts.

performance <- benchmark_gazepoint_export_performance(
  scales = data.frame(
    total_rows = c(10000L, 50000L),
    n_files = c(1L, 4L)
  ),
  operations = c("generate", "import"),
  trials = 3L
)

performance$summary
performance$regression$overall

Use gp3tools_performance_limits() to inspect or customize the regression limits and write_gazepoint_performance_benchmark() to export the resulting audit tables. Performance depends on hardware, software versions, file structure, and selected operations; the limits are configurable regression guards rather than universal guarantees.

gpbiometrics integration

gp3tools includes a dependency-free synchronization layer for combining standardized gaze samples with time-aligned biometric signal tables.

workflow <- run_gazepoint_gpbiometrics_workflow(
  gaze_data = gaze_data,
  biometrics_data = biometrics_data,
  signal_cols = c("GSR", "HR"),
  tolerance_s = 0.01
)

workflow$audit
workflow$signal_summary

The workflow reports matching coverage and timing differences and supports an optional external adapter. Its signal summaries describe recorded measurements and temporal alignment; they do not independently establish emotion, stress, preference, cognition, comprehension, or diagnosis.

User-facing naming policy

gp3tools uses British English summarise_* names as the canonical spelling for new user-facing summary helpers. Existing American English summarize_* exports remain available for backward compatibility.

policy <- gp3tools_naming_policy()
audit <- audit_gazepoint_naming_consistency()

policy$rules
audit$summary

Compatibility aliases call the same underlying analytical implementation; they do not alter calculations or remove established function names. The complete policy is documented in NAMING_CONVENTIONS.md.