Package {gp3tools}

Type:	Package
Title:	Import, Inspect, Analyse, and Report Gazepoint GP3 Exports
Version:	2.0.1
Description:	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 <doi:10.3390/jemr19040076>.
License:	MIT + file LICENSE
LazyData:	true
Encoding:	UTF-8
Language:	en-US
Depends:	R (≥ 4.1.0)
Imports:	dplyr, ggplot2, readr, rlang, stringr, tibble, tidyr
Suggests:	brms, DHARMa, emmeans, eyetools, glmmTMB, knitr, lme4, magick, mgcv, png, pracma, rmarkdown, shiny, testthat (≥ 3.0.0), TraMineR
VignetteBuilder:	knitr
Config/testthat/edition:	3
Config/roxygen2/version:	8.0.0
URL:	https://github.com/stefanosbalaskas/gp3tools, https://stefanosbalaskas.github.io/gp3tools/, https://doi.org/10.5281/zenodo.21292384, https://doi.org/10.3390/jemr19040076
BugReports:	https://github.com/stefanosbalaskas/gp3tools/issues
Config/Needs/website:	rmarkdown
NeedsCompilation:	no
Packaged:	2026-07-14 11:10:48 UTC; Stefanos-PC
Author:	Stefanos Balaskas [aut, cre]
Maintainer:	Stefanos Balaskas <s.balaskas@ac.upatras.gr>
Repository:	CRAN
Date/Publication:	2026-07-14 17:10:02 UTC

Convert Gazepoint all-gaze data to a master sample table

Description

Converts a Gazepoint all-gaze export into a standard sample-level table with one row per gaze sample. The returned table keeps Gazepoint identifiers but also adds analysis-friendly columns such as subject, media_id, time_ms, x, y, left_pupil, right_pupil, mean_pupil, valid_sample, missing_gaze, missing_pupil, trackloss, blink, aoi_current, message, and event_type.

Usage

as_gazepoint_master(
  data,
  screen_width_px = NULL,
  screen_height_px = NULL,
  source_col = "USER_FILE",
  media_col = "MEDIA_ID",
  media_name_col = "MEDIA_NAME",
  time_col = "TIME",
  coordinate_unit = c("auto", "normalised", "pixels"),
  event_latency_offset_ms = 0
)

Arguments

Details

This function is intended as a bridge between raw Gazepoint exports and more advanced eye-tracking workflows. It does not require an external trial log. Later, experiment-level information such as condition, trial ID, response, accuracy, or reaction time can be joined to the returned table.

Value

A tibble with one row per sample and standardised sample-level eye-tracking columns.

Examples

## Not run: 
results <- run_gazepoint_workflow(
  export_dir = "C:/Users/YourName/Desktop/gp3_test_exports",
  output_dir = "C:/Users/YourName/Desktop/gp3_outputs"
)

master <- as_gazepoint_master(
  results$all_gaze,
  screen_width_px = 1920,
  screen_height_px = 1080
)

dplyr::glimpse(master)

## End(Not run)

Audit AOI coding against geometry

Description

Validate observed sample-level AOI labels against AOI labels derived from gaze coordinates and AOI geometry.

Usage

audit_gazepoint_aoi_coding_matrix(
  gaze_data,
  aoi_geometry,
  observed_aoi_col = NULL,
  gaze_x_col = NULL,
  gaze_y_col = NULL,
  gaze_stimulus_col = NULL,
  sample_id_cols = NULL,
  geometry_aoi_col = NULL,
  geometry_stimulus_col = NULL,
  x_min_col = NULL,
  y_min_col = NULL,
  x_max_col = NULL,
  y_max_col = NULL,
  x_col = NULL,
  y_col = NULL,
  width_col = NULL,
  height_col = NULL,
  screen_x_range = c(0, 1),
  screen_y_range = c(0, 1),
  tie_method = c("ambiguous", "first"),
  outside_label = "outside",
  ambiguous_label = "ambiguous",
  missing_label = "missing_coordinate",
  observed_outside_values = c("outside", "none", "no_aoi", "non_aoi", "background",
    "off_aoi"),
  max_mismatch_prop = 0.05,
  max_ambiguous_prop = 0.05,
  max_missing_coordinate_prop = 0.2,
  ignore_invalid_geometry = TRUE
)

Arguments

Value

A list with class gp3_aoi_coding_matrix_audit containing overview, geometry_summary, sample_coding, coding_matrix, observed_summary, derived_summary, flagged_samples, and settings tables.

Audit AOI geometry definitions

Description

Create a publication-level audit of AOI geometry definitions, including AOI size, area, coordinate validity, screen-bound checks, and duplicate geometry.

Usage

audit_gazepoint_aoi_geometry(
  data,
  aoi_col = NULL,
  stimulus_col = NULL,
  x_min_col = NULL,
  y_min_col = NULL,
  x_max_col = NULL,
  y_max_col = NULL,
  x_col = NULL,
  y_col = NULL,
  width_col = NULL,
  height_col = NULL,
  screen_x_range = c(0, 1),
  screen_y_range = c(0, 1),
  min_width = 0,
  min_height = 0,
  min_area = 0,
  max_area_prop = 1,
  require_within_screen = TRUE
)

Arguments

Value

A list with class gp3_aoi_geometry_audit containing overview, geometry_summary, size_summary, flagged_aois, duplicate_geometry, and settings tables.

Audit AOI margin sensitivity

Description

Audit whether sample-level AOI assignments are sensitive to small expansions or shrinkages of AOI boundaries.

Usage

audit_gazepoint_aoi_margin_sensitivity(
  gaze_data,
  aoi_geometry,
  gaze_x_col = NULL,
  gaze_y_col = NULL,
  gaze_stimulus_col = NULL,
  sample_id_cols = NULL,
  geometry_aoi_col = NULL,
  geometry_stimulus_col = NULL,
  x_min_col = NULL,
  y_min_col = NULL,
  x_max_col = NULL,
  y_max_col = NULL,
  x_col = NULL,
  y_col = NULL,
  width_col = NULL,
  height_col = NULL,
  margins = c(-0.02, 0, 0.02),
  screen_x_range = c(0, 1),
  screen_y_range = c(0, 1),
  tie_method = c("ambiguous", "first"),
  outside_label = "outside",
  ambiguous_label = "ambiguous",
  missing_label = "missing_coordinate",
  max_margin_change_prop = 0.1,
  max_ambiguous_prop = 0.05,
  ignore_invalid_geometry = TRUE
)

Arguments

Value

A list with class gp3_aoi_margin_sensitivity_audit containing overview, geometry_summary, sample_sensitivity, margin_summary, aoi_margin_summary, flagged_samples, and settings tables.

Audit AOI overlap

Description

Create a publication-level audit of pairwise AOI overlap within each stimulus.

Usage

audit_gazepoint_aoi_overlap(
  data,
  aoi_col = NULL,
  stimulus_col = NULL,
  x_min_col = NULL,
  y_min_col = NULL,
  x_max_col = NULL,
  y_max_col = NULL,
  x_col = NULL,
  y_col = NULL,
  width_col = NULL,
  height_col = NULL,
  screen_x_range = c(0, 1),
  screen_y_range = c(0, 1),
  min_overlap_area = 0,
  min_overlap_prop = 0,
  ignore_invalid_geometry = TRUE
)

Arguments

Value

A list with class gp3_aoi_overlap_audit containing overview, geometry_summary, pairwise_overlap, overlap_summary, flagged_overlaps, and settings tables.

Audit AOI coverage against screen bounds

Description

Checks rectangular AOIs against declared screen or stimulus dimensions. The helper reports missing geometry, invalid rectangle order, off-screen AOIs, raw AOI area, clipped on-screen area, and screen-coverage rates. Coverage summaries are descriptive and do not correct for AOI overlap.

Usage

audit_gazepoint_aoi_screen_coverage(
  data,
  screen_width,
  screen_height,
  aoi_col = NULL,
  x_min_col = "x_min",
  x_max_col = "x_max",
  y_min_col = "y_min",
  y_max_col = "y_max",
  margin = 0
)

Arguments

Value

A list with AOI-level summary, overall summary, and settings.

Examples

aoi <- data.frame(
  aoi = c("left", "right"),
  x_min = c(100, 1200),
  x_max = c(500, 1700),
  y_min = c(100, 100),
  y_max = c(400, 400)
)
audit_gazepoint_aoi_screen_coverage(aoi, 1920, 1080, aoi_col = "aoi")

Audit AOI window denominators before binomial modelling

Description

Audit AOI-window sample denominators before confirmatory binomial or logistic mixed-effects modelling. The function is designed for output from summarise_gazepoint_aoi_windows().

Usage

audit_gazepoint_aoi_window_denominators(
  data,
  window_col = "window_label",
  window_start_col = "window_start_ms",
  window_end_col = "window_end_ms",
  denominator_col = "n_valid_denominator_samples",
  total_col = "n_window_samples",
  target_col = "n_target_samples",
  condition_col = "condition",
  group_cols = NULL,
  min_denominator_samples = 5,
  min_valid_denominator_prop = 0.7,
  max_denominator_cv = 0.25,
  max_condition_ratio = 2
)

Arguments

Value

A named list containing overview, row audit, window summary, condition-window summary, denominator-imbalance summary, flagged rows, and settings.

Audit condition-level quality imbalance

Description

Create a publication-level audit of whether gaze, pupil, retention, or other quality metrics differ across experimental conditions.

Usage

audit_gazepoint_condition_quality_imbalance(
  data,
  condition_col = "condition",
  quality_cols = NULL,
  subject_col = NULL,
  min_units_per_condition = 1L,
  max_mean_difference = 0.1,
  max_condition_ratio = 2,
  lower_is_better = c("missing_gaze_prop", "offscreen_prop", "excluded_prop",
    "failure_prop", "artifact_prop")
)

Arguments

Value

A list with class gp3_condition_quality_imbalance_audit containing overview, condition_summary, metric_summary, flagged_metrics, and settings tables.

Audit Gazepoint experimental design balance

Description

Create a publication-level audit of observed design balance across subjects, conditions, and optional stimulus/trial identifiers.

Usage

audit_gazepoint_design_balance(
  data,
  subject_col = "subject",
  condition_col = "condition",
  unit_cols = c("media_id", "trial_global"),
  expected_conditions = NULL,
  min_units_per_condition = 1L,
  max_condition_ratio = 2,
  require_all_conditions_per_subject = TRUE
)

Arguments

Value

A list with class gp3_design_balance_audit containing overview, subject_summary, condition_summary, cell_summary, imbalance_summary, flagged_cells, and settings tables.

Audit Gazepoint event and timing synchronisation

Description

Create a publication-level audit of event timing, trial timing, and event availability in a Gazepoint master table or sample-level export.

Usage

audit_gazepoint_event_sync(
  data,
  time_col = "time",
  event_col = NULL,
  group_cols = c("subject", "media_id", "trial_global"),
  condition_col = NULL,
  expected_event_labels = NULL,
  onset_event_label = NULL,
  response_event_label = NULL,
  min_samples_per_unit = 1L,
  max_time_gap_ms = NULL
)

Arguments

Value

A list with class gp3_event_sync_audit containing overview, unit_summary, event_summary, expected_event_summary, flagged_units, and settings tables.

Audit Gazepoint exclusion and retention flow

Description

Create a publication-level audit of retained and excluded analysis units.

Usage

audit_gazepoint_exclusion_flow(
  data,
  subject_col = "subject",
  condition_col = NULL,
  unit_cols = c("media_id", "trial_global"),
  include_col = NULL,
  exclude_col = NULL,
  status_col = NULL,
  reason_col = NULL,
  included_values = c("included", "include", "kept", "keep", "retained", "ok", "ready",
    "complete", "completed"),
  excluded_values = c("excluded", "exclude", "drop", "dropped", "removed", "fail",
    "failed", "not_ready", "review", "invalid"),
  min_retained_prop = 0.7,
  max_condition_exclusion_ratio = 2
)

Arguments

Value

A list with class gp3_exclusion_flow_audit containing overview, unit_flow, reason_summary, condition_summary, subject_summary, flagged_units, and settings tables.

Audit external facial-behaviour data quality

Description

Audits the quality of standardised external facial-behaviour data imported with read_gazepoint_face_export() and standardised with standardize_gazepoint_face_columns(). The helper checks face-detection validity, confidence, success, duplicate frame indices, and basic timing continuity. It does not infer facial expressions or emotional states.

Usage

audit_gazepoint_face_quality(
  data,
  group_cols = c("participant_id", "face_file"),
  confidence_threshold = 0.8,
  min_valid_percent = 70,
  warning_valid_percent = 85,
  max_time_gap_sec = NULL,
  max_duplicate_frame_percent = 1,
  standardize = TRUE
)

Arguments

Value

A list with overview, group_summary, issue_summary, data, and settings. The returned object has class gp3_face_quality_audit.

Examples

face <- data.frame(
  frame = 1:3,
  timestamp = c(0, 0.033, 0.066),
  confidence = c(0.95, 0.90, 0.40),
  success = c(1, 1, 1),
  AU12_r = c(0.1, 0.2, 0.3)
)

audit_gazepoint_face_quality(face)

Audit synchronisation between Gazepoint and external facial-behaviour data

Description

Summarises the output of sync_gazepoint_face_data() by reporting matched, unmatched, outside-tolerance, and missing-timing/frame rows. For nearest-time synchronisation, it also reports absolute time-difference summaries. The helper audits alignment quality only; it does not infer facial expressions or emotional states.

Usage

audit_gazepoint_face_sync(
  data,
  group_cols = NULL,
  min_matched_percent = 70,
  warning_matched_percent = 85,
  max_abs_diff_sec = NULL
)

Arguments

Value

A list with overview, group_summary, issue_summary, data, and settings. The returned object has class gp3_face_sync_audit.

Examples

gaze <- data.frame(
  subject_id = "P001",
  time_sec = c(0.00, 0.03, 0.07)
)

face <- data.frame(
  participant_id = "P001",
  frame = 1:3,
  timestamp = c(0.00, 0.033, 0.066),
  confidence = c(0.95, 0.94, 0.93),
  success = c(1, 1, 1)
)

synced <- sync_gazepoint_face_data(
  gaze,
  face,
  by = c(subject_id = "participant_id"),
  gaze_time_col = "time_sec"
)

audit_gazepoint_face_sync(synced)

Audit split-half reliability of fixation or AOI metrics

Description

Computes odd-even or random split-half reliability for common fixation and AOI-derived metrics. The audit returns the split-half correlation and the Spearman-Brown corrected reliability estimate.

Usage

audit_gazepoint_fixation_reliability(
  data,
  subject_col,
  trial_col,
  metric = c("fixation_count", "mean_fixation_duration", "total_fixation_duration",
    "aoi_dwell_prop", "transition_count", "entropy_score"),
  duration_col = NULL,
  aoi_col = NULL,
  target_aoi = NULL,
  time_col = NULL,
  group_cols = NULL,
  min_trials = 4,
  split_method = c("odd_even", "random"),
  seed = NULL,
  correlation_method = c("pearson", "spearman")
)

Arguments

Value

A data frame containing split-half reliability diagnostics.

Examples

dat <- expand.grid(
  subject = paste0("S", 1:6),
  trial = paste0("T", 1:4),
  KEEP.OUT.ATTRS = FALSE
)
dat$duration <- rep(seq_len(6), each = 4) + rep(c(0, 0.1, 0, 0.1), 6)

audit_gazepoint_fixation_reliability(
  dat,
  subject_col = "subject",
  trial_col = "trial",
  metric = "total_fixation_duration",
  duration_col = "duration"
)

Audit Gazepoint gaze-signal quality

Description

Create a publication-level audit of gaze coordinate availability, validity, off-screen samples, and optional pupil availability.

Usage

audit_gazepoint_gaze_signal_quality(
  data,
  subject_col = "subject",
  condition_col = NULL,
  group_cols = c("subject", "media_id", "trial_global"),
  x_col = NULL,
  y_col = NULL,
  validity_cols = NULL,
  pupil_col = NULL,
  screen_x_range = c(0, 1),
  screen_y_range = c(0, 1),
  min_gaze_valid_prop = 0.7,
  max_missing_gaze_prop = 0.3,
  max_offscreen_prop = 0.3,
  min_pupil_valid_prop = 0.7
)

Arguments

Value

A list with class gp3_gaze_signal_quality_audit containing overview, unit_summary, subject_summary, condition_summary, signal_issue_summary, flagged_units, and settings tables.

Audit a Gazepoint master sample table

Description

Creates compact quality-audit tables from a master sample-level table created by as_gazepoint_master() or create_gazepoint_master(). The audit summarises missing gaze, missing pupil, off-screen gaze, AOI states, pupil availability, coordinate ranges, and subject/media-level quality.

Usage

audit_gazepoint_master(master)

Arguments

Value

A named list of tibbles:

overview

One-row overview of the master table.

by_subject

Quality summary by participant/source.

by_media

Quality summary by media/stimulus.

by_subject_media

Quality summary by participant/source and media/stimulus.

aoi_states

Counts and percentages of AOI states.

pupil_summary

Pupil summary by participant/source and media/stimulus.

coordinate_summary

Coordinate range and off-screen summary.

Examples

## Not run: 
results <- run_gazepoint_workflow(
  export_dir = "C:/Users/YourName/Desktop/gp3_test_exports",
  output_dir = "C:/Users/YourName/Desktop/gp3_outputs"
)

master <- create_gazepoint_master(
  gaze_data = results$all_gaze,
  screen_width_px = 1920,
  screen_height_px = 1080
)

audit <- audit_gazepoint_master(master)

audit$overview
audit$by_subject
audit$aoi_states

## End(Not run)

Audit post-exclusion condition balance

Description

Create a publication-level audit of whether the retained analysis sample remains balanced across subjects and experimental conditions after exclusions.

Usage

audit_gazepoint_post_exclusion_balance(
  data,
  subject_col = "subject",
  condition_col = "condition",
  unit_cols = c("media_id", "trial_global"),
  retained_col = NULL,
  include_col = NULL,
  exclude_col = NULL,
  status_col = NULL,
  expected_conditions = NULL,
  included_values = c("included", "include", "kept", "keep", "retained", "ok", "ready",
    "complete", "completed"),
  excluded_values = c("excluded", "exclude", "drop", "dropped", "removed", "fail",
    "failed", "not_ready", "review", "invalid"),
  min_retained_units_per_condition = 1L,
  min_retained_units_per_subject_condition = 1L,
  max_condition_count_ratio = 2,
  max_subject_condition_ratio = 2,
  require_all_conditions_per_subject = TRUE
)

Arguments

Value

A list with class gp3_post_exclusion_balance_audit containing overview, unit_flow, cell_summary, condition_summary, subject_summary, flagged_cells, flagged_subjects, and settings tables.

Audit Gazepoint pupil baseline quality

Description

Summarise baseline quality after baseline_correct_gazepoint_pupil().

Usage

audit_gazepoint_pupil_baseline(
  data,
  group_cols = c("subject", "media_id"),
  time_col = "time",
  pupil_col = "pupil_interpolated",
  baseline_n_col = "pupil_baseline_n",
  baseline_status_col = "pupil_baseline_status",
  baseline_available_col = "pupil_baseline_available",
  baseline_used_col = "pupil_baseline_used",
  baseline_window_start_col = "pupil_baseline_window_start",
  baseline_window_end_col = "pupil_baseline_window_end",
  baseline_flag_col = NULL,
  interpolated_col = "pupil_was_interpolated",
  artifact_col = NULL,
  artifact_reason_col = NULL,
  min_baseline_samples = 1,
  max_missing_pct = 50,
  max_interpolated_pct = 50,
  max_artifact_pct = 50
)

Arguments

Details

The function reports baseline-row counts, valid/missing baseline samples, interpolated baseline samples, artifact-flagged baseline samples, no-baseline cases, and low-quality baseline flags by subject, media, trial, condition, or any selected grouping variables.

Value

A tibble with one row per group.

Audit Gazepoint pupil drift

Description

Summarise tonic pupil/time-on-task drift in processed Gazepoint pupil data.

Usage

audit_gazepoint_pupil_drift(
  data,
  group_cols = "subject",
  pupil_col = NULL,
  time_col = "time",
  order_col = "trial",
  condition_col = "condition",
  exclude_col = "excluded_trial",
  include_excluded = FALSE,
  min_valid_samples = 3,
  max_abs_slope_per_min = 1,
  max_condition_time_mean_diff_ms = 1000,
  max_condition_order_mean_diff = 1
)

Arguments

Details

The function estimates simple linear pupil trends over time within selected grouping variables, usually subjects. It also reports subject-level drift, condition-level drift, and possible condition imbalance in time-on-task.

Value

A named list containing by_group, by_subject, by_condition, condition_balance, and summary tibbles.

Audit Gazepoint pupil interpolation gaps

Description

Summarise observed, interpolated, and remaining missing pupil samples, together with gap-level counts and gap duration/sample-size summaries.

Usage

audit_gazepoint_pupil_gaps(
  data,
  group_cols = c("subject", "media_id"),
  status_col = "pupil_interpolation_status",
  gap_id_col = "pupil_gap_id",
  gap_n_samples_col = "pupil_gap_n_samples",
  gap_duration_col = "pupil_gap_duration_ms",
  interpolated_col = "pupil_was_interpolated",
  pupil_col = "pupil_interpolated"
)

Arguments

Details

This function is intended for data returned by interpolate_gazepoint_pupil(), but it can also be used with any table that contains compatible interpolation-status and gap columns.

Value

A tibble with one row per group, or one row overall when group_cols = character(0).

Audit Gazepoint pupil preprocessing imbalance

Description

Check whether pupil preprocessing loss differs across experimental conditions or other grouping variables.

Usage

audit_gazepoint_pupil_imbalance(
  data,
  group_cols = "condition",
  pupil_col = "pupil_interpolated",
  interpolated_col = "pupil_was_interpolated",
  interpolation_status_col = "pupil_interpolation_status",
  artifact_col = NULL,
  artifact_reason_col = NULL,
  min_group_n = 1,
  max_valid_pct_diff = 10,
  max_artifact_pct_diff = 10,
  max_missing_pct_diff = 10,
  max_interpolated_pct_diff = 10
)

Arguments

Details

The function summarises valid pupil samples, interpolated samples, artifact-flagged samples, and remaining missing samples. It also adds simple imbalance flags based on differences between groups.

Value

A tibble with one row per group and imbalance-warning columns.

Audit Gazepoint pupil-response overlap risk

Description

Check whether event-related pupil-response windows may overlap.

Usage

audit_gazepoint_pupil_overlap_risk(
  data,
  group_cols = "subject",
  trial_col = "trial_global",
  time_col = "time",
  event_time_cols = c("stimulus_onset_time", "target_onset_time", "response_time"),
  window_start_ms = 0,
  window_end_ms = 2000,
  min_event_gap_ms = 1000,
  exclude_col = "excluded_trial",
  include_excluded = FALSE
)

Arguments

Details

This function is designed as a deconvolution/readiness gate. It checks whether events within the same trial are too close together and whether their response windows overlap. If no usable event-time values are found, the function returns a clean audit with overlap_assessment_status = "no_usable_event_times".

Value

A named list containing events, event_gaps, by_trial, and summary tibbles.

Audit split-half reliability for Gazepoint pupil outcomes

Description

Create a split-half reliability audit for trial-level or window-level pupil outcomes. The helper is intended for publication-readiness checks when pupil features are interpreted as stable participant-level outcomes or individual difference measures.

Usage

audit_gazepoint_pupil_reliability(
  data,
  outcome_cols = NULL,
  participant_col = NULL,
  trial_col = NULL,
  split_col = NULL,
  by_cols = NULL,
  split_method = c("odd_even", "first_second"),
  aggregate_function = c("mean", "median"),
  correlation_method = c("pearson", "spearman"),
  min_trials_per_split = 2,
  name = "gazepoint_pupil_reliability"
)

Arguments

Value

A list with class gp3_pupil_reliability_audit.

Audit Gazepoint gaze coordinates against screen bounds

Description

Checks whether gaze coordinates are missing, equal to ⁠(0, 0)⁠, or outside the expected screen/stimulus bounds. The helper is intended for transparent quality-control reporting, not for automatic exclusion decisions.

Usage

audit_gazepoint_screen_bounds(
  data,
  x_col,
  y_col,
  screen_width,
  screen_height,
  group_cols = NULL,
  margin = 0,
  treat_zero_zero_as_out_of_bounds = TRUE
)

Arguments

Value

A list with row-level flags, group-level summary, overall summary, and settings.

Examples

x <- simulate_gazepoint_pupil_data(n_subjects = 2, n_trials = 2, n_time_bins = 5, seed = 1)
audit_gazepoint_screen_bounds(x, "gaze_x", "gaze_y", 1920, 1080)

Audit stimulus luminance and brightness for Gazepoint studies

Description

Compute stimulus-level luminance, brightness, and contrast summaries for image stimuli used in Gazepoint eye-tracking and pupillometry studies. This helper is intended as a publication-readiness audit because pupil size is strongly affected by stimulus brightness.

Usage

audit_gazepoint_stimulus_luminance(
  data,
  stimulus_file_col = NULL,
  stimulus_id_col = NULL,
  condition_col = NULL,
  image_dir = NULL,
  recursive = TRUE,
  name = "gazepoint_stimulus_luminance"
)

Arguments

Value

A list with class gp3_stimulus_luminance_audit.

Audit a Gazepoint time-course grid for cluster-permutation readiness

Description

Check whether a prepared or raw long-format time-course data set has the subject-by-condition-by-time structure expected by the conservative two-condition cluster-permutation workflow.

Usage

audit_gazepoint_timecourse_grid(
  data,
  subject_col = ".gp3_cluster_subject",
  condition_col = ".gp3_cluster_condition",
  time_col = ".gp3_cluster_time_bin",
  outcome_col = ".gp3_cluster_outcome"
)

Arguments

Value

A list containing grid counts, missing cells, duplicate cells, and readiness flags.

Baseline-correct Gazepoint pupil data

Description

Computes baseline-corrected pupil columns from a Gazepoint pupil time series, typically after flag_gazepoint_pupil() and interpolate_gazepoint_pupil(). Baselines can be defined either by a time window, such as c(-200, 0), or by a user-supplied logical baseline/pre-stimulus flag column.

Usage

baseline_correct_gazepoint_pupil(
  data,
  pupil_col = NULL,
  time_col = NULL,
  baseline_time_col = NULL,
  baseline_window = c(-200, 0),
  baseline_flag_col = NULL,
  group_cols = c("subject", "media_id"),
  baseline_method = c("mean", "median"),
  min_baseline_samples = 1
)

Arguments

Value

A tibble containing the original data plus baseline-correction columns.

Examples

## Not run: 
flagged <- flag_gazepoint_pupil(master)
interpolated <- interpolate_gazepoint_pupil(flagged)

corrected <- baseline_correct_gazepoint_pupil(
  interpolated,
  baseline_window = c(-200, 0)
)

corrected <- baseline_correct_gazepoint_pupil(
  interpolated,
  baseline_window = c(0, 200)
)

## End(Not run)

Bootstrap time-course summaries

Description

Compute simple nonparametric bootstrap confidence intervals for a time-varying gaze or pupil measure. The function is intentionally lightweight and returns a tidy data frame that can be plotted or used as a descriptive robustness check alongside model-based analyses.

Usage

bootstrap_gazepoint_timecourse(
  data,
  time_col,
  value_col,
  group_col = NULL,
  subject_col = NULL,
  n_boot = 1000,
  ci = 0.95,
  statistic = c("mean", "median"),
  difference_groups = NULL,
  seed = NULL
)

Arguments

Value

A data frame with time, group/contrast, estimate, lower and upper bootstrap interval limits, sample size, and status columns.

Check readiness of a Gazepoint-derived dataset for Bayesian or advanced models

Description

Performs lightweight structural checks before Bayesian, GAMM, HDDM, or other advanced modelling workflows. The function does not fit any model.

Usage

check_gazepoint_bayesian_readiness(
  data,
  outcome,
  subject,
  trial = NULL,
  time = NULL,
  condition = NULL,
  metric_type = "continuous",
  baseline_window = NULL,
  min_observations_per_subject = 10,
  max_missing_trial_prop = 0.2
)

Arguments

Value

A data frame of checks, status values, and messages.

Check Gazepoint all-gaze and fixation file pairs

Description

Checks whether each Gazepoint participant/source has both an all-gaze CSV file and a fixation CSV file before running the full workflow.

Usage

check_gazepoint_file_pairs(
  folder,
  all_gaze_pattern = "_all_gaze\\.csv$",
  fixation_pattern = "_fixations\\.csv$",
  recursive = FALSE
)

Arguments

Value

A tibble with one row per detected participant/source and file-pair status.

Check model convergence

Description

Check convergence status for fitted models used in gp3tools workflows.

Usage

check_gazepoint_model_convergence(model, model_name = NULL)

Arguments

Details

This helper supports lme4 mixed models, mgcv GAM/GAMM objects, glm objects, and lm objects where convergence is meaningful. It returns a compact diagnostic table instead of printing model-specific messages.

Value

A tibble with model class, convergence status, diagnostic status, and message.

Check model overdispersion

Description

Compute a Pearson-residual overdispersion diagnostic for models where this is meaningful, especially binomial and count models.

Usage

check_gazepoint_model_overdispersion(
  model,
  ratio_threshold = 1.2,
  model_name = NULL
)

Arguments

Details

This helper supports glm, lme4 GLMMs, and mgcv GAM/GAMM objects when their family is binomial, quasibinomial, Poisson, quasipoisson, or negative-binomial-like. Gaussian lm, lmer, and Gaussian GAM models return a structured not_applicable diagnostic row.

Value

A tibble with Pearson chi-square, residual degrees of freedom, dispersion ratio, overdispersion flag, diagnostic status, and message.

Check model singularity

Description

Check whether a fitted mixed model has a singular random-effects structure.

Usage

check_gazepoint_model_singularity(model, tolerance = 1e-04, model_name = NULL)

Arguments

Details

This helper is primarily intended for lme4 mixed models. For model classes where singularity is not meaningful, such as lm, glm, and mgcv GAM objects, it returns a structured not_applicable diagnostic row.

Value

A tibble with model class, singular-fit status, diagnostic status, and message.

Check real-data readiness before Gazepoint analysis

Description

Create an explicit final readiness gate for real Gazepoint or gp3tools master data before confirmatory analysis. The gate checks required identifiers, trial/time structure, analysis-specific columns, missingness, basic design balance, and optional upstream audit objects.

Usage

check_gazepoint_real_data_readiness(
  data,
  analysis_type = c("general", "pupil", "aoi", "combined"),
  participant_col = NULL,
  trial_col = NULL,
  time_col = NULL,
  condition_col = NULL,
  stimulus_col = NULL,
  aoi_col = NULL,
  pupil_col = NULL,
  gaze_x_col = NULL,
  gaze_y_col = NULL,
  tracking_valid_col = NULL,
  required_cols = NULL,
  audit_objects = NULL,
  min_rows = 1L,
  min_participants = 1L,
  min_trials = 1L,
  max_missing_pupil_prop = 0.4,
  max_missing_gaze_prop = 0.4,
  max_condition_imbalance_ratio = 3,
  name = "gazepoint_real_data_readiness_gate"
)

Arguments

Details

This helper is a final decision wrapper. It complements, but does not replace, validate_gazepoint_master() or create_gazepoint_analysis_decision_audit().

Value

A list with class gp3_real_data_readiness_gate.

Check sampling rate by group

Description

Check sampling rate by group

Usage

check_sampling_rate(data, group_cols = "MEDIA_ID", time_col = "TIME")

Arguments

Value

A tibble with sample interval and estimated Hz.

Classify gaze events with a lightweight unsupervised HMM

Description

Estimates gaze velocity, initializes hidden states by k-means, estimates a Gaussian-emission HMM, and decodes the most likely sequence with Viterbi. This is a lightweight package-internal HMM classifier and not a replacement for validated laboratory event-detection software.

Usage

classify_gazepoint_events_hmm(
  data,
  x,
  y,
  time,
  subject = NULL,
  n_states = 3,
  state_labels = NULL
)

Arguments

Value

The input data with velocity, hmm_state, and hmm_event columns.

Classify a Gazepoint export

Description

Uses the filename and header structure to classify a file as all_gaze, fixations, summary, or unknown.

Usage

classify_gazepoint_export(path)

Arguments

Value

A single character string.

Flag or filter Gazepoint data by trackloss

Description

Computes trackloss rates globally or within user-specified grouping columns, then flags or removes groups exceeding a transparent threshold. Trackloss can be supplied directly through a validity/tracking column or inferred from missing/out-of-range gaze coordinates.

Usage

clean_gazepoint_by_trackloss(
  data,
  group_cols = NULL,
  tracking_col = NULL,
  x_col = NULL,
  y_col = NULL,
  max_trackloss = 0.25,
  action = c("flag", "filter"),
  treat_zero_zero_as_loss = TRUE,
  rate_col = ".gp3_trackloss_rate",
  exclude_col = ".gp3_trackloss_exclude"
)

Arguments

Value

A data frame with diagnostic columns. If action = "filter", rows from excluded groups are removed. A compact summary is stored in the "gp3_trackloss_summary" attribute.

Examples

x <- data.frame(
  participant = c("P1", "P1", "P2", "P2"),
  trial = c(1, 1, 1, 1),
  valid = c(1, 0, 1, 1)
)
clean_gazepoint_by_trackloss(
  x,
  group_cols = c("participant", "trial"),
  tracking_col = "valid",
  max_trackloss = 0.25
)

Collect Gazepoint QC summaries

Description

Collects compact overview/status information from gp3tools audit, workflow, checklist, readiness, diagnostic, or reporting objects. The helper is intended to make existing QC outputs easier to review together; it does not rerun checks or define exclusion rules.

Usage

collect_gazepoint_qc_summaries(
  objects,
  object_names = NULL,
  name = "gazepoint_qc_summary_bundle",
  include_overview_rows = TRUE
)

Arguments

Value

A list with overview, object_summary, overview_rows, and settings.

Examples

audit <- list(
  overview = data.frame(
    audit_status = "ok",
    message = "Example audit passed."
  )
)
collect_gazepoint_qc_summaries(list(example_audit = audit))

Combine left and right Gazepoint eye channels

Description

Combines two numeric eye-specific columns into a single analysis column. The helper is intentionally simple and transparent: it can average available left/right values, prefer one eye with fallback to the other, or select the globally less-missing eye as a pragmatic "best eye" rule.

Usage

combine_gazepoint_eyes(
  data,
  left_col,
  right_col,
  output_col = "combined_eye",
  method = c("mean", "left", "right", "prefer_left", "prefer_right", "best"),
  valid_min = NULL,
  valid_max = NULL
)

Arguments

Value

A copy of data with output_col added.

Examples

x <- data.frame(left_pupil = c(3.1, NA, 3.4), right_pupil = c(3.3, 3.2, NA))
combine_gazepoint_eyes(x, "left_pupil", "right_pupil", "pupil")

Compare nested Gazepoint models

Description

Compare a sequence of nested models, such as null, main-effect, time, condition, and interaction models. The helper returns model-level fit indices, likelihood-ratio comparisons, ranking information, and extraction statuses.

Usage

compare_gazepoint_nested_models(
  models,
  model_names = NULL,
  comparison = c("sequential", "against_first"),
  name = "gazepoint_nested_model_comparison"
)

Arguments

Details

This helper is useful for GCA, confirmatory LMM/GLMM workflows, AOI GLMMs, pupil LMMs, and other fitted model workflows where reviewers expect explicit model-comparison evidence.

Value

A list with class gp3_nested_model_comparison.

Compute AOI entropy metrics

Description

Computes spatial AOI entropy, directed transition entropy, and conditional transition entropy for Gazepoint-style AOI sequences. The function is useful for quantifying how concentrated, dispersed, or predictable gaze allocation is across Areas of Interest.

Usage

compute_gazepoint_aoi_entropy(
  data,
  aoi_col,
  group_cols = NULL,
  time_col = NULL,
  include_missing = FALSE,
  missing_label = "missing",
  collapse_repeats = FALSE,
  log_base = 2
)

Arguments

Value

A data frame with one row per group and entropy/count columns.

Examples

dat <- data.frame(
  subject = "S01",
  trial = "T01",
  time = 1:6,
  AOI = c("A", "A", "B", "C", "B", "A")
)

compute_gazepoint_aoi_entropy(
  dat,
  aoi_col = "AOI",
  group_cols = c("subject", "trial"),
  time_col = "time"
)

Compute AOI sequence metrics

Description

Computes compact scanpath-style descriptors from Gazepoint AOI sequences, including sequence length, AOI visits, transitions, revisits, first and last AOI, dominant AOI, and run-length summaries.

Usage

compute_gazepoint_aoi_sequence_metrics(
  data,
  aoi_col,
  group_cols = NULL,
  time_col = NULL,
  include_missing = FALSE,
  missing_label = "missing",
  collapse_repeats = TRUE
)

Arguments

Value

A data frame with one row per group and sequence-metric columns.

Examples

dat <- data.frame(
  subject = "S01",
  trial = "T01",
  time = 1:6,
  AOI = c("A", "A", "B", "A", "C", "C")
)

compute_gazepoint_aoi_sequence_metrics(
  dat,
  aoi_col = "AOI",
  group_cols = c("subject", "trial"),
  time_col = "time"
)

Compute Gazepoint AOI transition matrices

Description

Compute AOI transition count and probability matrices from sample-level Gazepoint AOI data, AOI-entry tables, or AOI-sequence tables. The function returns both matrix and long-table forms.

Usage

compute_gazepoint_aoi_transition_matrix(
  data,
  aoi_col = NULL,
  time_col = "time",
  group_cols = c("subject", "MEDIA_ID", "trial_global"),
  by_cols = NULL,
  include_non_aoi = TRUE,
  include_self_transitions = TRUE,
  states = NULL,
  time_window = NULL,
  non_aoi_values = c("non_aoi", "none", "background", "outside", "outside_aoi",
    "missing", "missing_aoi"),
  missing_aoi_label = "missing_aoi"
)

Arguments

Value

A list containing count matrices, probability matrices, and long-form transition counts/probabilities.

Compute basic saccade metrics from fixation coordinates

Description

Compute between-fixation displacement metrics from ordered fixation coordinates. The function does not perform raw event detection; it assumes that fixation-level coordinates are already available, for example from Gazepoint fixation exports.

Usage

compute_gazepoint_saccade_metrics(
  data,
  x_col,
  y_col,
  group_cols = NULL,
  time_col = NULL,
  start_time_col = NULL,
  end_time_col = NULL,
  distance_scale = 1,
  drop_missing = TRUE
)

Arguments

Value

A data frame with one row per between-fixation movement.

Compute scanpath geometry features by subject and trial

Description

Computes scanpath length, straight-line distance, efficiency, convex-hull area, and spatial dispersion from sequential gaze/fixation coordinates.

Usage

compute_gazepoint_scanpath_geometry(
  data,
  x,
  y,
  subject,
  trial,
  time = NULL,
  condition = NULL
)

Arguments

Value

A trial-level data frame of scanpath geometry features.

Compute AOI scanpath similarity

Description

Compute pairwise AOI-sequence similarity between grouped scanpaths using a lightweight Levenshtein edit-distance implementation. Similarity is reported as 1 - normalized_distance, where normalized distance is divided by the longer sequence length.

Usage

compute_gazepoint_scanpath_similarity(
  data,
  aoi_col,
  group_cols,
  time_col = NULL,
  include_missing = FALSE,
  missing_label = "missing",
  collapse_repeats = FALSE,
  max_sequences = 200
)

Arguments

Value

A long-format data frame containing pairwise edit distances, normalized distances, and similarities.

Compute AOI sequence complexity metrics

Description

Compute compact sequence-complexity summaries from AOI labels. This helper complements transition and entropy summaries by returning simple, interpretable indices such as type-token ratio, transition density, normalized entropy, and a combined complexity index.

Usage

compute_gazepoint_sequence_complexity(
  data = NULL,
  sequence = NULL,
  aoi_col = NULL,
  group_cols = NULL,
  time_col = NULL,
  include_missing = FALSE,
  missing_label = "missing",
  collapse_repeats = FALSE
)

Arguments

Value

A data frame with sequence length, unique-state count, entropy, transition density, type-token ratio, and complexity index.

Compute AOI sequence distance

Description

Computes a lightweight edit distance between two AOI sequences using a vector-based Levenshtein distance. This provides a simple scanpath dissimilarity measure without requiring heavy sequence-analysis dependencies.

Usage

compute_gazepoint_sequence_distance(
  sequence_a,
  sequence_b,
  ignore_missing = TRUE,
  missing_label = "missing",
  collapse_repeats = FALSE,
  substitution_cost = 1,
  insertion_cost = 1,
  deletion_cost = 1
)

Arguments

Value

A one-row data frame with edit distance, normalized distance, and sequence lengths.

Examples

compute_gazepoint_sequence_distance(
  sequence_a = c("Claim", "Evidence", "CTA"),
  sequence_b = c("Claim", "CTA", "Evidence")
)

Compute simple categorical sequence recurrence metrics

Description

Compute lightweight recurrence metrics from AOI/state sequences. This is a compact categorical recurrence helper, not a full replacement for dedicated CRQA/RQA packages.

Usage

compute_gazepoint_sequence_recurrence(
  data = NULL,
  sequence = NULL,
  aoi_col = NULL,
  group_cols = NULL,
  time_col = NULL,
  min_line = 2,
  include_missing = FALSE,
  missing_label = "missing"
)

Arguments

Value

A data frame of recurrence metrics.

Compute time-varying Gazepoint transition matrices

Description

Compute transition-count and transition-probability matrices across time windows. This helper is a convenience wrapper for studies where AOI/state transitions are expected to vary over the course of a stimulus, trial, or analysis window.

Usage

compute_gazepoint_time_varying_transition_matrix(
  data,
  from_col = NULL,
  to_col = NULL,
  time_col = NULL,
  window_col = NULL,
  window_size_ms = NULL,
  by_cols = NULL,
  count_col = NULL,
  states = NULL,
  complete_states = TRUE,
  drop_self_transitions = FALSE,
  normalise = c("row", "global", "none"),
  name = "gazepoint_time_varying_transition_matrix"
)

Arguments

Value

A list with class gp3_time_varying_transition_matrix.

Compute lightweight AOI transition-network metrics

Description

Compute graph-style summaries from AOI transitions without requiring network packages. Metrics include state count, edge count, density, self-loops, and in/out-degree summaries.

Usage

compute_gazepoint_transition_network_metrics(
  data,
  aoi_col = NULL,
  from_col = NULL,
  to_col = NULL,
  group_cols = NULL,
  time_col = NULL,
  include_self_loops = TRUE
)

Arguments

Value

A list with graph-level and state-level summaries.

Compute an AOI transition matrix

Description

Compute an AOI transition matrix

Usage

compute_transition_matrix(
  data,
  group_cols = "MEDIA_ID",
  aoi_col = "AOI",
  time_col = "TIME",
  collapse_repeats = TRUE
)

Arguments

Value

A tibble with from, to, n, and prob.

Create a final Gazepoint analysis-decision audit

Description

Create a final audit table for a Gazepoint analysis workflow. The function records which analysis branches were run, classifies them as confirmatory, sensitivity, exploratory, diagnostic, preprocessing, or reporting branches, summarises available diagnostics, flags interpretation cautions, and creates a final analysis-readiness table.

Usage

create_gazepoint_analysis_decision_audit(
  ...,
  results = NULL,
  branch_roles = NULL,
  required_confirmatory = character(),
  diagnostics_required = TRUE,
  require_clean_diagnostics = FALSE
)

Arguments

Value

A list with class gp3_analysis_decision_audit containing overview, branch audit, diagnostics summary, interpretation cautions, readiness, and settings tables.

Create a Bayesian ocular Statistical Analysis Plan checklist

Description

Generates a structured checklist for Bayesian or advanced eye-tracking and pupillometry analysis planning.

Usage

create_gazepoint_bayesian_sap(
  outcome,
  design,
  primary_model,
  baseline_window = NULL,
  analysis_window = NULL,
  missingness_threshold = 0.2,
  blink_padding_ms = 50,
  output = c("data.frame", "markdown")
)

Arguments

Value

A data frame or markdown character vector.

Create brms formula and prior templates for Gazepoint-derived metrics

Description

Returns formula, family, prior, and reporting-note templates. The function does not require or call brms.

Usage

create_gazepoint_brms_template(
  metric_type,
  outcome,
  time = NULL,
  condition = NULL,
  subject = NULL,
  item = NULL
)

Arguments

Value

A list containing formula, family, priors, and notes.

Create a reporting checklist for external facial-behaviour workflows

Description

Creates a compact checklist for reporting external facial-behaviour analyses alongside Gazepoint data. The checklist is designed for reviewer-facing transparency: it records whether import, quality auditing, synchronisation, window summaries, reactivity summaries, and modelling outputs are available. It also includes interpretation cautions. The helper does not infer facial expressions or emotional states.

Usage

create_gazepoint_face_reporting_checklist(
  face_data = NULL,
  quality_audit = NULL,
  sync_audit = NULL,
  window_summary = NULL,
  reactivity_summary = NULL,
  multimodal_model = NULL,
  include_interpretation_cautions = TRUE
)

Arguments

Value

A tibble with class gp3_face_reporting_checklist.

Examples

quality <- list(
  overview = data.frame(
    n_rows = 10,
    valid_percent = 95,
    face_quality_status = "pass"
  ),
  issue_summary = data.frame(
    issue = "missing_confidence",
    n_groups_affected = 0
  )
)
class(quality) <- c("gp3_face_quality_audit", "list")

create_gazepoint_face_reporting_checklist(quality_audit = quality)

Create a Python HDDM fitting script from a Gazepoint HDDM export

Description

Writes a Python script for fitting an HDDMRegressor model. The function does not fit HDDM inside R and does not require Python. It creates a reproducible script that can be run in a Python/HDDM environment.

Usage

create_gazepoint_hddm_fit_script(
  data_file,
  output_file = "fit_gazepoint_hddm.py",
  regressions = c(v = "target_dwell_ms_z", a = "pupil_peak_z"),
  include = c("v", "a", "t"),
  draws = 5000,
  burn = 2000,
  dbname = "hddm_traces.db"
)

Arguments

Value

Invisibly returns output_file.

Create a Gazepoint AOI Markov-chain object

Description

Create a dependency-free Markov-chain-style object from AOI/state sequences. The function computes transition counts, transition probabilities, and matrix representations from ordered gaze/AOI states. It does not require the external markovchain package; instead, it returns a lightweight gp3tools object that can be inspected, exported, or converted later.

Usage

create_gazepoint_markovchain_object(
  data,
  state_col = NULL,
  participant_col = NULL,
  trial_col = NULL,
  time_col = NULL,
  sequence_id_cols = NULL,
  state_order = NULL,
  exclude_states = c("missing", "missing_aoi", "missing_coordinate", "trackloss",
    "track_loss"),
  missing_state_label = NULL,
  include_self_transitions = TRUE,
  laplace = 0,
  empty_state_handling = c("self", "zero", "NA"),
  name = "gazepoint_markovchain"
)

Arguments

Value

A list with class gp3_markovchain_object.

Create a master long-format dataset from Gazepoint all-gaze data

Description

Converts Gazepoint all-gaze exports imported with read_gazepoint() or read_gazepoint_folder() into a master sample-level structure suitable for quality checks, AOI summaries, pupil preprocessing, time-course analyses, and publication reporting.

Usage

create_gazepoint_master(
  gaze_data,
  screen_width_px = NULL,
  screen_height_px = NULL,
  screen_width_cm = NULL,
  screen_height_cm = NULL,
  viewing_distance_cm = NULL,
  time_unit = c("seconds", "milliseconds"),
  user_col = "USER_FILE",
  media_col = "MEDIA_ID",
  media_name_col = "MEDIA_NAME",
  tracker_model = "Gazepoint",
  tracker_sampling_rate = 60,
  event_latency_offset_ms = 0,
  baseline_window = NULL,
  analysis_window = NULL
)

Arguments

Value

A tibble with one row per Gazepoint sample and publication-oriented master columns.

Create a Gazepoint preprocessing multiverse

Description

Create a preprocessing multiverse specification for Gazepoint pupil and AOI workflows. The returned object defines alternative preprocessing decisions that can later be passed to pupil or AOI multiverse runners.

Usage

create_gazepoint_preprocessing_multiverse(
  pupil_max_gap_ms = c(75, 150, 250),
  pupil_smoothing_window_samples = c(3L, 5L, 7L),
  pupil_baseline_windows = list(c(0, 200), c(-200, 0)),
  pupil_artifact_padding_ms = c(0, 50),
  aoi_denominators = c("valid", "all", "aoi_only"),
  aoi_min_denominator_samples = c(1L, 5L, 10L),
  include_pupil = TRUE,
  include_aoi = TRUE,
  label_prefix = "mv"
)

Arguments

Value

A list with class gp3_preprocessing_multiverse containing overview, pupil grid, AOI grid, combined grid, and settings tables.

Create a Gazepoint pupil-preprocessing registry

Description

Creates a compact registry of commonly used preprocessing parameters for Gazepoint pupil and gaze analyses. The registry is designed to make preprocessing choices explicit, auditable, and easy to report.

Usage

create_gazepoint_preprocessing_registry(
  blink_padding_pre_ms = 100,
  blink_padding_post_ms = 100,
  max_interpolation_gap_ms = 150,
  smoothing_window_ms = 50,
  baseline_start_ms = -200,
  baseline_end_ms = 0,
  pupil_physiological_min = 1,
  pupil_physiological_max = 9,
  pupil_speed_mad_k = 6,
  binocular_mad_k = 6,
  baseline_missing_prop_threshold = 0.3,
  baseline_interpolated_prop_threshold = 0.3,
  baseline_artifact_prop_threshold = 0.3,
  overlap_trial_duration_ms = 3000,
  overlap_event_gap_ms = 1000
)

Arguments

Value

A tibble with one row per preprocessing parameter.

Examples

registry <- create_gazepoint_preprocessing_registry()
registry

Create a Gazepoint HTML diagnostic report

Description

Creates a lightweight HTML report from a gp3tools workflow result object. The report includes dataset dimensions, sampling-rate checks, flagged recordings, AOI summaries, and standard diagnostic plots.

Usage

create_gazepoint_report(
  results,
  output_file,
  title = "Gazepoint diagnostic report",
  overwrite = TRUE,
  max_rows = 30,
  save_plots = TRUE,
  plot_dir = NULL
)

Arguments

Value

A tibble with the written report path and plot folder.

Create a Gazepoint reporting checklist

Description

Create an auto-generated reporting checklist for Gazepoint/gp3tools analyses. The checklist summarises whether key dataset, preprocessing, quality-control, AOI, pupil, modelling, sensitivity, and reproducibility elements are present or still need reporting.

Usage

create_gazepoint_reporting_checklist(
  data = NULL,
  objects = NULL,
  analysis_type = c("general", "pupil", "aoi", "combined"),
  study_title = NULL,
  required_sections = NULL,
  include_optional = TRUE,
  name = "gazepoint_reporting_checklist"
)

Arguments

Details

This helper is intended as a reporting aid. It does not replace the underlying audit, preprocessing, modelling, or readiness-gate functions.

Value

A list with class gp3_reporting_checklist.

Detect simple I-VT fixations from gaze samples

Description

Apply a lightweight velocity-threshold fixation detector to ordered gaze samples. This helper is intended for exploratory checks and teaching; it does not replace dedicated event-detection packages or Gazepoint's native fixation export.

Usage

detect_gazepoint_fixations_ivt(
  data,
  x_col,
  y_col,
  time_col,
  group_cols = NULL,
  velocity_threshold = 0.01,
  min_duration_ms = 60,
  distance_scale = 1,
  time_scale = 1
)

Arguments

Value

A fixation-level data frame.

Diagnose the design assumptions of a Gazepoint cluster-permutation workflow

Description

Provide a compact diagnostic summary for the conservative two-condition, within-subject, one-dimensional cluster-permutation workflow.

Usage

diagnose_gazepoint_cluster_design(
  data,
  subject_col = ".gp3_cluster_subject",
  condition_col = ".gp3_cluster_condition",
  time_col = ".gp3_cluster_time_bin",
  outcome_col = ".gp3_cluster_outcome"
)

Arguments

Value

A data frame of design checks and cautious interpretations.

Diagnose GAM and BAM models

Description

Run a compact diagnostics bundle for mgcv GAM/BAM models used in gp3tools workflows. The function combines convergence, basis-dimension checks, overdispersion checks, and optional DHARMa simulation-based residual diagnostics.

Usage

diagnose_gazepoint_gamm(
  model,
  model_name = NULL,
  check_convergence = TRUE,
  check_basis = TRUE,
  check_overdispersion = TRUE,
  use_dharma = FALSE,
  dharma_simulations = 250,
  seed = 123
)

Arguments

Details

The function accepts raw mgcv::gam() / mgcv::bam() model objects, gp3tools fit objects containing a ⁠$model⁠ element, or a named list of fitted model objects.

Value

A list with overview, convergence, basis, overdispersion, DHARMa diagnostics, and settings.

Diagnose GLMM, LMM, and GLM models

Description

Run a compact diagnostics bundle for model objects used in gp3tools workflows. The function combines convergence, singularity, overdispersion, and optional DHARMa simulation-based residual diagnostics.

Usage

diagnose_gazepoint_glmm(
  model,
  model_name = NULL,
  check_convergence = TRUE,
  check_singularity = TRUE,
  check_overdispersion = TRUE,
  use_dharma = TRUE,
  dharma_simulations = 250,
  seed = 123
)

Arguments

Details

The function accepts raw fitted models, gp3tools fit objects containing a ⁠$model⁠ element, or a named list of fitted models. DHARMa diagnostics are optional and are skipped cleanly when DHARMa is not installed.

Value

A list with overview, convergence, singularity, overdispersion, DHARMa diagnostics, and settings.

Guardrail for exact cluster-offset estimation

Description

This function intentionally fails safely. Cluster-permutation results should not be used as exact effect-offset estimates.

Usage

estimate_gazepoint_cluster_offset(...)

Arguments

Value

This function always stops with an explanatory error.

Guardrail for exact cluster-onset estimation

Description

This function intentionally fails safely. Cluster-permutation results should not be used as exact effect-onset estimates.

Usage

estimate_gazepoint_cluster_onset(...)

Arguments

Value

This function always stops with an explanatory error.

Estimate a bootstrapped divergence point between two Gazepoint time courses

Description

Estimate the earliest time point at which two condition-level time courses reliably diverge. The helper computes observed condition curves, bootstraps the condition difference, identifies the first time point where the bootstrap confidence interval excludes the null value for a requested number of consecutive time points, and returns a bootstrap uncertainty interval for the divergence onset.

Usage

estimate_gazepoint_divergence_point(
  data,
  outcome_col,
  time_col,
  condition_col,
  participant_col = NULL,
  trial_col = NULL,
  comparison = NULL,
  bootstrap_unit = c("participant", "trial", "row"),
  summary_function = c("mean", "median"),
  n_boot = 1000L,
  ci = 0.95,
  consecutive_points = 1L,
  null_value = 0,
  min_abs_difference = 0,
  direction = c("two_sided", "positive", "negative"),
  seed = NULL,
  keep_bootstrap = TRUE,
  name = "gazepoint_divergence_point"
)

Arguments

Details

This helper complements cluster-permutation analysis. Cluster permutation asks where a reliable time window exists; divergence-point analysis asks when the condition difference first emerges.

Value

A list with class gp3_divergence_point_analysis.

Export Gazepoint cluster-permutation results

Description

Export cluster tables, optional null distributions, settings, and cautious report text to a folder of CSV/TXT files.

Usage

export_gazepoint_cluster_results(result, outdir, overwrite = FALSE)

Arguments

Value

A data frame listing written files.

Export a Gazepoint heatmap plot to PNG

Description

export_gazepoint_heatmap_png() saves a ggplot heatmap to a PNG file.

Usage

export_gazepoint_heatmap_png(
  plot,
  filename,
  width = 8,
  height = 5,
  units = "in",
  dpi = 300,
  create_dir = TRUE,
  ...
)

Arguments

Value

Invisibly returns the output path.

Examples

gaze <- data.frame(
  x = c(0.20, 0.25, 0.70),
  y = c(0.30, 0.35, 0.60)
)

p <- plot_gazepoint_heatmap(
  gaze,
  x_col = "x",
  y_col = "y",
  bins = 10
)

out <- tempfile(fileext = ".png")
export_gazepoint_heatmap_png(p, out, width = 4, height = 3)

Export a Gazepoint master table, audit tables, and validation tables

Description

Exports a Gazepoint master sample-level table together with the output of audit_gazepoint_master() and, optionally, validate_gazepoint_master(). This function is useful after creating a master table with as_gazepoint_master() or create_gazepoint_master().

Usage

export_gazepoint_master_audit(
  master,
  audit = NULL,
  validation = NULL,
  output_dir = ".",
  prefix = "gazepoint",
  export_master = TRUE,
  export_audit = TRUE,
  export_validation = TRUE,
  overwrite = TRUE,
  na = ""
)

Arguments

Value

A tibble listing the exported files, table names, and dimensions.

Examples

## Not run: 
master <- create_gazepoint_master(
  gaze_data = results$all_gaze,
  screen_width_px = 1920,
  screen_height_px = 1080
)

audit <- audit_gazepoint_master(master)
validation <- validate_gazepoint_master(master)

exported <- export_gazepoint_master_audit(
  master = master,
  audit = audit,
  validation = validation,
  output_dir = "gazepoint_outputs",
  prefix = "study1"
)

exported

## End(Not run)

Export Gazepoint time-course data for MNE-style cluster workflows

Description

Write a conservative long-format CSV file and README for continuation in an external Python/MNE workflow. This helper prepares data only; it does not run MNE, construct adjacency matrices, validate exchangeability, or validate the external analysis.

Usage

export_gazepoint_mne_cluster_input(
  data,
  outdir,
  subject_col = ".gp3_cluster_subject",
  condition_col = ".gp3_cluster_condition",
  time_col = ".gp3_cluster_time_bin",
  outcome_col = ".gp3_cluster_outcome",
  overwrite = FALSE
)

Arguments

Value

A data frame listing written files.

Export manuscript-ready model tables

Description

Export model-summary tables and optional estimated marginal means tables to CSV files. The function is designed for objects returned by tidy_gazepoint_model_summary() and summarise_gazepoint_emmeans().

Usage

export_gazepoint_model_tables(
  model_summary = NULL,
  emmeans_summary = NULL,
  output_dir,
  prefix = "gazepoint_model",
  overwrite = TRUE,
  include_diagnostics = TRUE
)

Arguments

Value

A tibble indexing the written files.

Export Gazepoint time-course data for permuco-style cluster workflows

Description

Write a conservative long-format CSV file and README for continuation in an external R/permuco workflow. This helper prepares data only; it does not run permuco or validate the external model specification.

Usage

export_gazepoint_permuco_cluster_input(
  data,
  outdir,
  subject_col = ".gp3_cluster_subject",
  condition_col = ".gp3_cluster_condition",
  time_col = ".gp3_cluster_time_bin",
  outcome_col = ".gp3_cluster_outcome",
  overwrite = FALSE
)

Arguments

Value

A data frame listing written files.

Export Gazepoint time-course data for permutes-style cluster workflows

Description

Write a conservative long-format CSV file and README for continuation in an external R/permutes workflow. This helper prepares data only; it does not run permutes or validate the external model specification.

Usage

export_gazepoint_permutes_cluster_input(
  data,
  outdir,
  subject_col = ".gp3_cluster_subject",
  condition_col = ".gp3_cluster_condition",
  time_col = ".gp3_cluster_time_bin",
  outcome_col = ".gp3_cluster_outcome",
  overwrite = FALSE
)

Arguments

Value

A data frame listing written files.

Export Gazepoint analysis tables to CSV files

Description

Writes a named list of analysis tables to CSV files in an output folder.

Usage

export_gazepoint_tables(
  tables,
  output_dir,
  prefix = NULL,
  overwrite = TRUE,
  na = ""
)

Arguments

Value

A tibble with table names and written file paths.

Export Gazepoint data to a lightweight BIDS-style folder

Description

Write a conservative BIDS-style eye-tracking folder from a Gazepoint-style data frame. This helper creates standard-looking TSV and JSON sidecar files for sharing and inspection, but it does not claim full validation against a specific evolving BIDS eye-tracking validator.

Usage

export_gazepoint_to_bids(
  data,
  outdir,
  subject_col,
  task = "gazepoint",
  session = NULL,
  time_col,
  x_col,
  y_col,
  pupil_col = NULL,
  trial_col = NULL,
  aoi_col = NULL,
  overwrite = FALSE
)

Arguments

Value

A data frame listing written files.

Apply uncertainty filtering to Bayesian CNN or webcam gaze outputs

Description

Provides a lightweight post-processing helper for externally generated webcam/CNN gaze predictions. The function does not train a CNN. It filters or down-weights frame-level gaze estimates using an uncertainty column.

Usage

filter_gazepoint_cnn_uncertainty(
  data,
  x,
  y,
  uncertainty = NULL,
  max_uncertainty = NULL,
  weight_output = "cnn_uncertainty_weight",
  valid_output = "cnn_valid_frame"
)

Arguments

Value

Data frame with uncertainty weights and validity flags.

Fit an optional Bayesian AOI model with brms

Description

Prepare and optionally fit a Bayesian AOI model using brms. The dependency is optional: the function checks for brms only when dry_run = FALSE. Tests and lightweight workflows can use dry_run = TRUE to inspect the formula and data without running Stan.

Usage

fit_gazepoint_aoi_brms(
  data,
  response,
  predictors,
  subject_col = NULL,
  family = "bernoulli",
  prior = NULL,
  dry_run = TRUE,
  ...
)

Arguments

Value

A dry-run specification list or a brmsfit object.

Fit AOI time-course GAMMs

Description

Fit binomial GAMMs for AOI target-looking time courses prepared by prepare_gazepoint_aoi_gamm_data(). The model uses target-looking successes and failures over time and can include condition effects, condition-specific smooths, and subject random-effect smooths.

Usage

fit_gazepoint_aoi_gamm(
  data,
  include_condition = TRUE,
  condition_smooths = TRUE,
  random_subject = TRUE,
  random_subject_time = FALSE,
  time_k = 10,
  subject_time_k = 5,
  family = stats::binomial(),
  method = "fREML",
  discrete = FALSE,
  select = FALSE,
  drop_non_ok = TRUE,
  min_rows = 10,
  min_subjects = 2,
  min_time_bins = 4,
  ...
)

Arguments

Details

This function is intended for AOI time-course modelling. It is separate from confirmatory AOI-window GLMMs and from cluster-based permutation tests.

Value

A list containing the fitted model, formula, model status, diagnostics, parametric table, smooth table, and settings.

Fit AOI-window model-family sensitivity checks

Description

Fit a compact set of sensitivity models for AOI-window outcomes. The main model is a binomial GLMM. Additional checks can include an empirical-logit LMM, a weighted proportion LMM, and a fixed-effects quasibinomial GLM.

Usage

fit_gazepoint_aoi_model_sensitivity(
  data,
  success_col = "aoi_glmm_success",
  failure_col = "aoi_glmm_failure",
  denominator_col = "aoi_glmm_denominator",
  proportion_col = "aoi_glmm_prop",
  subject_col = "aoi_glmm_subject",
  condition_col = "aoi_glmm_condition",
  window_col = "aoi_glmm_window",
  model_types = c("binomial_glmm", "empirical_logit_lmm", "proportion_lmm",
    "quasibinomial_glm"),
  include_condition = TRUE,
  include_window = TRUE,
  include_interaction = TRUE,
  random_intercept = TRUE,
  optimizer = "bobyqa",
  maxfun = 2e+05,
  nAGQ = 0,
  empirical_logit_correction = 0.5,
  drop_missing = TRUE
)

Arguments

Value

A list containing fitted models, formulas, comparison table, fixed effects table, settings, and status information.

Fit an AOI-window binomial GLMM

Description

Fit a confirmatory AOI-window mixed-effects logistic regression from data prepared by prepare_gazepoint_aoi_glmm_data().

Usage

fit_gazepoint_aoi_window_glmm(
  data,
  success_col = "aoi_glmm_success",
  failure_col = "aoi_glmm_failure",
  subject_col = "aoi_glmm_subject",
  condition_col = "aoi_glmm_condition",
  window_col = "aoi_glmm_window",
  include_condition = TRUE,
  include_window = TRUE,
  include_interaction = TRUE,
  random_intercept = TRUE,
  random_window_slopes = FALSE,
  fallback_on_singular = TRUE,
  optimizer = "bobyqa",
  maxfun = 2e+05,
  nAGQ = 0,
  drop_missing = TRUE
)

Arguments

Value

A list with fitted model, attempted model, formulas, comparison table, settings, status fields, and model data.

Fit an optional brms model for Gazepoint-derived data

Description

Fits a Bayesian model using brms when brms is installed. brms is treated as an optional external backend; gp3tools does not import or require it.

Usage

fit_gazepoint_brms_model(
  data,
  formula,
  family = "gaussian",
  prior = NULL,
  chains = 4,
  iter = 2000,
  warmup = floor(iter/2),
  cores = 1,
  backend = NULL,
  ...
)

Arguments

Value

A fitted brms model.

Fit a facial-behaviour window mixed or linear model

Description

Fits an explicit model to a face-window or multimodal analysis table. If random_effects is supplied, the model is fitted with lme4::lmer(); otherwise stats::lm() is used. The helper is a modelling convenience wrapper and does not interpret facial-behaviour variables as emotions.

Usage

fit_gazepoint_face_window_lmm(
  data,
  outcome,
  predictors,
  covariates = NULL,
  random_effects = NULL,
  na_action = c("na.omit", "na.exclude"),
  REML = FALSE
)

Arguments

Value

A list with model, formula, data, and settings. The object has class gp3_face_window_lmm.

Examples

dat <- data.frame(
  participant_id = c("P001", "P002", "P003"),
  AU12_r_mean = c(0.1, 0.2, 0.3),
  rating = c(3, 4, 5)
)

fit_gazepoint_face_window_lmm(
  dat,
  outcome = "rating",
  predictors = "AU12_r_mean"
)

Fit a Gazepoint Growth Curve Analysis mixed model

Description

Fit a Growth Curve Analysis (GCA) mixed model to prepared pupil time-course data. The function first attempts a random-intercept plus random-time-slopes model and, if the model fails or is singular, falls back to a random-intercept model.

Usage

fit_gazepoint_gca(
  data,
  outcome_col = "gca_pupil",
  subject_col = "subject",
  condition_col = "condition",
  time_terms = NULL,
  degree = NULL,
  weights_col = "gca_weight",
  use_weights = TRUE,
  random_slopes = TRUE,
  fallback_on_singular = TRUE,
  REML = FALSE,
  optimizer = "bobyqa",
  maxfun = 2e+05,
  drop_missing = TRUE
)

Arguments

Value

A list of class gp3_gca_model containing the fitted model, attempted and final formulas, model comparison information, settings, and status.

Fit a multimodal response model

Description

Fits an explicit response model using multimodal predictors. Linear models, generalised linear models, and mixed-effects models are supported depending on family and random_effects. The helper prepares and fits the model only; it does not make causal, diagnostic, or emotion-inference claims.

Usage

fit_gazepoint_multimodal_response_model(
  data,
  outcome,
  predictors,
  covariates = NULL,
  random_effects = NULL,
  family = NULL,
  na_action = c("na.omit", "na.exclude"),
  REML = FALSE,
  ...
)

Arguments

Value

A list with model, formula, data, and settings. The object has class gp3_multimodal_response_model.

Examples

dat <- data.frame(
  participant_id = c("P001", "P002", "P003"),
  AU12_r_mean = c(0.1, 0.2, 0.3),
  dwell_time = c(1.2, 1.4, 1.1),
  rating = c(3, 4, 5)
)

fit_gazepoint_multimodal_response_model(
  dat,
  outcome = "rating",
  predictors = c("AU12_r_mean", "dwell_time")
)

Fit a Gazepoint pupil GAMM

Description

Fit a generalized additive mixed model for binned pupil time-course data using mgcv::bam(). The function is designed to work with data prepared by prepare_gazepoint_pupil_gamm_data().

Usage

fit_gazepoint_pupil_gamm(
  data,
  pupil_col = "mean_pupil",
  time_col = "time_bin_center_ms",
  subject_col = "subject",
  condition_col = "condition",
  n_time_basis = 10,
  use_condition_smooths = TRUE,
  include_subject_random_effect = TRUE,
  family = c("gaussian", "scat"),
  method = "fREML",
  discrete = TRUE,
  rho = NULL,
  ar_start_col = "AR.start",
  weights_col = NULL,
  drop_missing = TRUE
)

Arguments

Value

A list of class gp3_pupil_gamm containing the fitted model, formula, data, settings, and status information.

Fit a gaze-position-adjusted pupil GAMM sensitivity model

Description

Fit and compare a main pupil GAMM with a gaze-position-adjusted sensitivity model. The adjusted model adds a two-dimensional tensor-product smooth over mean gaze x/y position using te(mean_x, mean_y).

Usage

fit_gazepoint_pupil_pfe_gamm(
  data,
  pupil_col = "mean_pupil",
  time_col = "time_bin_center_ms",
  subject_col = "subject",
  condition_col = "condition",
  x_col = "mean_x",
  y_col = "mean_y",
  n_time_basis = 10,
  n_position_basis = 8,
  use_condition_smooths = TRUE,
  include_subject_random_effect = TRUE,
  family = c("gaussian", "scat"),
  method = "fREML",
  discrete = TRUE,
  rho = NULL,
  ar_start_col = "AR.start",
  weights_col = NULL,
  drop_missing = TRUE
)

Arguments

Value

A list of class gp3_pupil_pfe_gamm containing the main model, the gaze-position-adjusted model, formulas, comparison table, settings, and status information.

Fit confirmatory pupil-window linear mixed models

Description

Fit the main confirmatory trial/window-level pupil model from data prepared with prepare_gazepoint_pupil_window_model_data(). The default model is a linear mixed model with pupil outcome as the continuous dependent variable, condition and/or window fixed effects when available, and a subject random intercept when feasible.

Usage

fit_gazepoint_pupil_window_lmm(
  data,
  formula = NULL,
  outcome_col = "pupil_model_outcome",
  subject_col = "pupil_model_subject",
  condition_col = "pupil_model_condition",
  window_col = "pupil_model_window",
  weights_col = "pupil_model_weight",
  use_weights = FALSE,
  include_condition = TRUE,
  include_window = TRUE,
  include_interaction = TRUE,
  random_intercept = TRUE,
  random_window_slopes = FALSE,
  fallback_on_singular = TRUE,
  REML = FALSE,
  optimizer = "bobyqa",
  maxfun = 2e+05,
  drop_missing = TRUE,
  ...
)

Arguments

Value

A list containing the fitted model, formula, attempted model, fallback information, fixed effects, comparison table, settings, and model diagnostics.

Run sensitivity models for confirmatory pupil-window analyses

Description

Run a compact set of sensitivity models for confirmatory pupil-window analyses. Supported model families are the main linear mixed model, a weighted linear mixed model, a fixed-effects linear model, and a weighted fixed-effects linear model. Weighted models use the prepared valid-sample count column as weights by default.

Usage

fit_gazepoint_pupil_window_sensitivity(
  data,
  outcome_col = "pupil_model_outcome",
  subject_col = "pupil_model_subject",
  condition_col = "pupil_model_condition",
  window_col = "pupil_model_window",
  weights_col = "pupil_model_weight",
  model_types = c("lmm", "weighted_lmm", "lm", "weighted_lm"),
  include_condition = TRUE,
  include_window = TRUE,
  include_interaction = TRUE,
  random_intercept = TRUE,
  random_window_slopes = FALSE,
  fallback_on_singular = TRUE,
  REML = FALSE,
  optimizer = "bobyqa",
  maxfun = 2e+05,
  drop_missing = TRUE,
  ...
)

Arguments

Value

A list containing fitted models, formulas, fixed effects, a comparison table, settings, and model-status information.

Fit optional negative-binomial transition-count sensitivity models

Description

Fit an optional negative-binomial sensitivity model for AOI/state transition counts using glmmTMB when it is installed. This helper is intended as a publication sensitivity branch for overdispersed transition-count outcomes.

Usage

fit_gazepoint_transition_count_nb_sensitivity(
  data,
  count_col = NULL,
  from_col = NULL,
  to_col = NULL,
  condition_cols = NULL,
  random_effect_cols = NULL,
  exposure_col = NULL,
  offset_col = NULL,
  formula = NULL,
  family = c("nbinom2", "nbinom1"),
  zero_inflation = FALSE,
  ziformula = NULL,
  dispformula = NULL,
  control = NULL,
  name = "gazepoint_transition_count_nb_sensitivity"
)

Arguments

Details

The helper keeps glmmTMB optional. If glmmTMB is not installed, it returns a structured skipped object rather than failing.

Value

A list with class gp3_transition_count_nb_sensitivity.

Flag invalid, missing, implausible, and outlying Gazepoint pupil samples

Description

Adds pupil-quality flags to a Gazepoint master sample-level table created by as_gazepoint_master() or create_gazepoint_master(). This function is intended as a preprocessing step before interpolation, filtering, baseline correction, or pupil-based modelling.

Usage

flag_gazepoint_pupil(
  master,
  pupil_col = NULL,
  time_col = NULL,
  missing_pupil_col = NULL,
  group_cols = c("subject", "media_id"),
  min_pupil = 0,
  max_pupil = Inf,
  outlier_k = 1.5,
  flag_iqr_outliers = TRUE
)

Arguments

Value

A tibble containing the original master table plus pupil-flagging columns.

Examples

## Not run: 
flagged <- flag_gazepoint_pupil(master)

dplyr::count(flagged, pupil_flag_reason)

## End(Not run)

Flag Gazepoint pupil artifacts before interpolation

Description

Adds pupil-specific artifact flags for blink/trackloss contamination, physiological implausibility when pupil units are millimetres, pupil-speed outliers, left-right binocular pupil disagreement, and temporal padding around bad samples. The function preserves raw pupil columns and creates pupil_clean, which can be used as input for interpolation.

Usage

flag_gazepoint_pupil_artifacts(
  data,
  pupil_col = NULL,
  left_pupil_col = NULL,
  right_pupil_col = NULL,
  time_col = NULL,
  blink_col = NULL,
  trackloss_col = NULL,
  missing_pupil_col = NULL,
  pupil_unit_col = NULL,
  group_cols = c("subject", "media_id"),
  registry = NULL,
  blink_padding_pre_ms = NULL,
  blink_padding_post_ms = NULL,
  pupil_min_mm = NULL,
  pupil_max_mm = NULL,
  pupil_speed_mad_k = NULL,
  binocular_mad_k = NULL,
  max_physio_outlier_prop = 0.8,
  flag_speed_outliers = TRUE,
  flag_binocular_disagreement = TRUE,
  flag_physiological_outliers = TRUE
)

Arguments

Value

A tibble containing the original data plus pupil-artifact columns.

Examples

## Not run: 
registry <- create_gazepoint_preprocessing_registry()

artifact_pupil <- flag_gazepoint_pupil_artifacts(
  master,
  registry = registry
)

dplyr::count(artifact_pupil, pupil_artifact_reason)

## End(Not run)

Flag pupil artifacts with a Hampel filter

Description

Apply a rolling Hampel filter to a Gazepoint pupil column. The helper computes a rolling median and median absolute deviation (MAD) within a centred sample window, then flags pupil samples whose absolute deviation from the local median exceeds k * MAD.

Usage

flag_gazepoint_pupil_hampel(
  data,
  pupil_col,
  time_col = NULL,
  grouping_cols = NULL,
  window_size_samples = 7L,
  k = 3,
  min_valid_samples = 3L,
  scale_mad = 1.4826,
  flag_col = "pupil_hampel_outlier",
  median_col = "pupil_hampel_median",
  mad_col = "pupil_hampel_mad",
  threshold_col = "pupil_hampel_threshold",
  corrected_col = NULL,
  status_col = "pupil_hampel_status",
  overwrite = FALSE,
  name = "gazepoint_pupil_hampel"
)

Arguments

Details

This helper is intended as an optional sensitivity/artifact-flagging branch. It complements existing pupil artifact checks and should not automatically replace confirmatory preprocessing decisions.

Value

A tibble with Hampel-filter columns added. The object has class gp3_pupil_hampel_flags.

Flag unusual AOI sequences

Description

Identify grouped AOI sequences that are unusually short, unusually long, have high missingness, or contain very few unique AOI states. The function is intended as a lightweight quality-control helper rather than a definitive exclusion rule.

Usage

flag_gazepoint_sequence_anomalies(
  data,
  aoi_col,
  group_cols,
  time_col = NULL,
  min_length = 2,
  max_length = NULL,
  max_missing_prop = 0.5,
  z_threshold = 3,
  min_unique_aoi = 1
)

Arguments

Value

A data frame with sequence diagnostics and anomaly flags.

Flag low-quality Gazepoint recordings

Description

Combines tracking-quality and sampling-rate summaries and flags rows with low gaze validity, low pupil validity, abnormal sampling rate, or short duration.

Usage

flag_tracking_quality(
  quality,
  sampling,
  by = c("USER_FILE", "MEDIA_ID"),
  min_gaze_valid_pct = 70,
  min_pupil_valid_pct = 70,
  expected_hz = 60,
  hz_tolerance = 5,
  min_duration_sec = NULL
)

Arguments

Value

A tibble with quality, sampling, flag columns, and an overall review flag.

Example AOI geometry table

Description

A lightweight synthetic AOI geometry table for AOI-verification examples. Coordinates are normalised to a 0–1 screen coordinate system.

Usage

gazepoint_example_aoi_geometry

Format

A tibble with one row per stimulus and AOI, including:

media_id

Synthetic stimulus identifier.

aoi

Synthetic AOI label.

x_min, y_min, x_max, y_max

Normalised rectangular AOI boundaries.

Examples

data(gazepoint_example_aoi_geometry)
gazepoint_example_aoi_geometry

Example AOI-window summary table

Description

A lightweight synthetic AOI-window summary table created from gazepoint_example_master. It can be used in examples for AOI-window denominator checks, GLMM preparation, and AOI-window modelling.

Usage

gazepoint_example_aoi_windows

Format

A tibble with one row per participant, stimulus/trial, and AOI time window.

Examples

data(gazepoint_example_aoi_windows)
head(gazepoint_example_aoi_windows)

Example Gazepoint fixation table

Description

A lightweight synthetic Gazepoint-style fixation table for examples, tests, README workflows, and vignettes. The data are artificial and are not from a real participant study.

Usage

gazepoint_example_fixations

Format

A tibble with fixation-level rows and columns including:

USER_FILE

Synthetic participant/file identifier.

subject

Synthetic participant identifier.

MEDIA_ID

Synthetic stimulus identifier.

trial_global

Synthetic trial identifier.

condition

Synthetic experimental condition.

FPOGID

Synthetic fixation identifier.

FPOGS

Synthetic fixation start time.

FPOGD

Synthetic fixation duration.

FPOGX, FPOGY

Synthetic fixation coordinates.

FPOGV

Synthetic fixation validity flag.

AOI

Synthetic AOI label.

Examples

data(gazepoint_example_fixations)
head(gazepoint_example_fixations)

Example Gazepoint master table

Description

A lightweight synthetic Gazepoint-style sample-level master table for examples, tests, README workflows, and vignettes. The data are artificial and are not from a real participant study.

Usage

gazepoint_example_master

Format

A tibble with sample-level rows and columns including:

subject

Synthetic participant identifier.

USER_FILE

Gazepoint-style participant/file identifier.

MEDIA_ID

Synthetic stimulus identifier.

trial_global

Synthetic trial identifier.

condition

Synthetic experimental condition.

time

Sample time in milliseconds.

x, y

Normalised gaze coordinates.

pupil

Synthetic pupil value.

valid

Logical gaze/pupil validity flag.

artifact

Logical synthetic pupil-artifact flag.

aoi_current

Synthetic AOI state.

is_fixation, is_saccade

Synthetic fixation and saccade indicators.

event_label

Synthetic event marker.

Examples

data(gazepoint_example_master)
head(gazepoint_example_master)

Example pupil-window summary table

Description

A lightweight synthetic pupil-window summary table created from gazepoint_example_master. It can be used in examples for pupil-window model-data preparation and confirmatory pupil-window modelling.

Usage

gazepoint_example_pupil_windows

Format

A tibble with one row per participant, stimulus/trial, condition, and pupil time window.

Examples

data(gazepoint_example_pupil_windows)
head(gazepoint_example_pupil_windows)

Harmonize Gazepoint screen coordinates across resolutions

Description

Rescales gaze coordinates from one screen or stimulus resolution to another. This is a deterministic coordinate transformation for harmonizing exports before plotting, AOI checks, or descriptive summaries. It does not recalibrate gaze data or correct measurement error.

Usage

harmonize_gazepoint_screen_coordinates(
  data,
  x_col,
  y_col,
  from_width,
  from_height,
  to_width,
  to_height,
  output_x_col = "gaze_x_harmonized",
  output_y_col = "gaze_y_harmonized",
  keep_original = TRUE
)

Arguments

Value

A copy of data with harmonized coordinate columns.

Examples

x <- data.frame(gaze_x = c(0, 960, 1920), gaze_y = c(0, 540, 1080))
harmonize_gazepoint_screen_coordinates(
  x,
  x_col = "gaze_x",
  y_col = "gaze_y",
  from_width = 1920,
  from_height = 1080,
  to_width = 1280,
  to_height = 720
)

Impute missing pupil samples with a lightweight Gaussian-process smoother

Description

Performs within-subject/trial Gaussian-process interpolation using a squared exponential kernel. This helper is intended for short missing segments after blink detection, not for reconstructing long unusable trials.

Usage

impute_gazepoint_pupil_gp(
  data,
  pupil,
  time,
  subject = NULL,
  trial = NULL,
  length_scale = NULL,
  noise = 1e-04,
  max_train = 300,
  output = "pupil_gp_imputed",
  flag = "pupil_was_gp_imputed"
)

Arguments

Value

Data frame with imputed pupil values and an imputation flag.

Inspect Gazepoint columns

Description

Inspect Gazepoint columns

Usage

inspect_gazepoint_columns(x)

Arguments

Value

A tibble describing column names, semantic groups, and missingness.

Interpolate short missing gaps in Gazepoint pupil data

Description

Performs linear interpolation over short internal gaps in Gazepoint pupil data. This function is intended to be used after flag_gazepoint_pupil() or flag_gazepoint_pupil_artifacts(). When available, pupil_clean is used as the preferred default input column, followed by pupil_for_preprocessing. Leading gaps, trailing gaps, long gaps, non-finite time values, and groups with too few valid pupil samples are not interpolated.

Usage

interpolate_gazepoint_pupil(
  data,
  pupil_col = NULL,
  time_col = NULL,
  group_cols = c("subject", "media_id"),
  max_gap_ms = 150,
  max_gap_samples = Inf,
  min_valid_points = 2
)

Arguments

Value

A tibble containing the original data plus interpolation columns.

Examples

## Not run: 
flagged <- flag_gazepoint_pupil(master)

interpolated <- interpolate_gazepoint_pupil(flagged)

dplyr::count(interpolated, pupil_interpolation_status)

artifact_flagged <- flag_gazepoint_pupil_artifacts(master)

artifact_interpolated <- interpolate_gazepoint_pupil(artifact_flagged)

dplyr::count(artifact_interpolated, pupil_interpolation_status)

## End(Not run)

Interpolate Gazepoint pupil data using PCHIP

Description

Apply shape-preserving piecewise cubic Hermite interpolation to short internal gaps in Gazepoint pupil time series. This helper is intended as a sensitivity branch alongside the default linear interpolation workflow. It does not overwrite the original pupil column.

Usage

interpolate_gazepoint_pupil_pchip(
  data,
  pupil_col = NULL,
  time_col = NULL,
  grouping_cols = NULL,
  max_gap_ms = 500,
  max_gap_samples = NULL,
  min_valid_points = 3,
  output_col = "pupil_interpolated_pchip",
  flag_col = "interpolated_pupil_pchip",
  status_col = "pchip_interpolation_status"
)

Arguments

Value

A tibble with PCHIP interpolation columns added.

Launch or describe a lightweight QC dashboard

Description

Provide a minimal optional Shiny dashboard launcher for inspecting a data frame. With launch = FALSE, the function returns a dashboard specification without requiring Shiny.

Usage

launch_gazepoint_qc_dashboard(
  data = NULL,
  title = "gp3tools QC dashboard",
  launch = FALSE
)

Arguments

Value

A dashboard specification, or a Shiny app object when launched.

Plot AOI time-course GAMM results

Description

Plot observed AOI target-looking proportions and fitted GAMM trajectories from a model returned by fit_gazepoint_aoi_gamm().

Usage

plot_gazepoint_aoi_gamm(
  fit,
  n_time_points = 100,
  include_observed = TRUE,
  include_fitted = TRUE,
  show_ci = TRUE,
  ci_level = 0.95,
  exclude_random_effects = TRUE,
  observed_summary = c("pooled"),
  point_size = 1.8,
  point_alpha = 0.65,
  line_width = 0.8,
  ribbon_alpha = 0.15,
  title = NULL,
  subtitle = NULL,
  x_label = "Time (ms)",
  y_label = "Target AOI looking probability",
  y_limits = c(0, 1)
)

Arguments

Details

The plot supports single-condition fallback models and multi-condition AOI time-course GAMMs. By default, fitted trajectories are population-level predictions with subject random-effect smooths excluded.

Value

A ggplot object with prediction and observed data stored as attributes.

Plot an AOI timeline

Description

Creates a scarf-style timeline plot showing the current AOI over time for each subject, trial, or user-defined row grouping.

Usage

plot_gazepoint_aoi_timeline(
  data,
  aoi_col,
  time_col,
  y_col = NULL,
  subject_col = NULL,
  trial_col = NULL,
  group_cols = NULL,
  include_missing = FALSE,
  missing_label = "missing",
  sample_width = NULL,
  title = NULL,
  x_label = "Time",
  y_label = NULL,
  aoi_label = "AOI"
)

Arguments

Value

A ggplot object.

Examples

dat <- data.frame(
  subject = rep(c("S01", "S02"), each = 4),
  trial = "T01",
  time = rep(1:4, 2),
  AOI = c("A", "A", "B", "C", "A", "B", "B", "C")
)

plot_gazepoint_aoi_timeline(
  dat,
  aoi_col = "AOI",
  time_col = "time",
  subject_col = "subject",
  trial_col = "trial"
)

Plot Gazepoint AOI transition matrix

Description

Plot a heatmap of AOI transition counts or probabilities from the output of compute_gazepoint_aoi_transition_matrix() or from a compatible long-form transition table.

Usage

plot_gazepoint_aoi_transition_matrix(
  transitions,
  value = c("prob", "n"),
  state_order = NULL,
  by_cols = NULL,
  include_zero = TRUE,
  show_labels = TRUE,
  label_digits = 2,
  label_size = 3,
  facet = TRUE,
  title = NULL
)

Arguments

Value

A ggplot2 plot object.

Plot AOI geometry for visual verification

Description

Create a visual verification plot of AOI rectangles, with optional gaze samples overlaid.

Usage

plot_gazepoint_aoi_verification(
  aoi_geometry,
  gaze_data = NULL,
  geometry_aoi_col = NULL,
  geometry_stimulus_col = NULL,
  x_min_col = NULL,
  y_min_col = NULL,
  x_max_col = NULL,
  y_max_col = NULL,
  x_col = NULL,
  y_col = NULL,
  width_col = NULL,
  height_col = NULL,
  gaze_x_col = NULL,
  gaze_y_col = NULL,
  gaze_stimulus_col = NULL,
  screen_x_range = c(0, 1),
  screen_y_range = c(0, 1),
  facet_by_stimulus = TRUE,
  show_labels = TRUE,
  show_gaze = TRUE,
  invert_y = TRUE,
  point_alpha = 0.35,
  point_size = 1.2,
  line_width = 0.8,
  label_size = 3
)

Arguments