Package 'gp3tools'

Description

Labels gaze samples using one or more rectangular AOI definitions.

Usage

add_gazepoint_aoi(
  master_df,
  aoi_defs,
  x_col = "FPOGX",
  y_col = "FPOGY",
  aoi_name = NULL,
  output = c("logical", "label", "both"),
  prefix = "aoi_",
  label_col = "aoi_current",
  outside_label = "outside",
  overlap = c("first", "last", "error"),
  include_overlap_count = TRUE
)

Arguments

Value

The input data with AOI membership columns.

Examples

gaze <- data.frame(
  FPOGX = c(0.2, 0.5, 0.8),
  FPOGY = c(0.2, 0.5, 0.8)
)
defs <- data.frame(
  name = c("top_left", "bottom_right"),
  L = c(0, 0.6),
  R = c(0.4, 1),
  T = c(0, 0.6),
  B = c(0.4, 1)
)
add_gazepoint_aoi(gaze, defs, output = "both")

Description

Match each gaze sample to a time-indexed AOI definition and classify the sample against rectangular or polygon geometry. Definitions can also be grouped by participant, stimulus, trial, or other shared columns.

Usage

add_gazepoint_dynamic_aoi(
  master_df,
  aoi_defs,
  x_col = "FPOGX",
  y_col = "FPOGY",
  time_col = "TIME",
  aoi_time_col = "aoi_time",
  aoi_name_col = "aoi_name",
  shape = c("auto", "rectangle", "polygon"),
  group_cols = NULL,
  match = c("nearest", "previous", "next"),
  max_time_gap = Inf,
  left_col = "left",
  right_col = "right",
  top_col = "top",
  bottom_col = "bottom",
  vertex_x_col = "vertex_x",
  vertex_y_col = "vertex_y",
  vertex_order_col = NULL,
  output = c("label", "logical", "both"),
  prefix = "aoi_",
  label_col = "aoi_current",
  outside_label = "outside",
  overlap = c("first", "last", "error"),
  boundary = c("inside", "outside"),
  definition_time_col = "aoi_definition_time",
  time_gap_col = "aoi_time_gap",
  include_overlap_count = TRUE
)

Arguments

Value

The input data with dynamic AOI membership and match-diagnostic columns.

Description

Classify sample-level gaze coordinates against one or more polygon AOIs using a base-R ray-casting implementation. Polygon vertices are grouped by AOI name and ordered either by row order or an explicit vertex-order column.

Usage

add_gazepoint_polygon_aoi(
  master_df,
  vertices,
  x_col = "FPOGX",
  y_col = "FPOGY",
  aoi_col = "aoi_name",
  vertex_x_col = "vertex_x",
  vertex_y_col = "vertex_y",
  vertex_order_col = NULL,
  output = c("label", "logical", "both"),
  prefix = "aoi_",
  label_col = "aoi_current",
  outside_label = "outside",
  overlap = c("first", "last", "error"),
  boundary = c("inside", "outside"),
  include_overlap_count = TRUE
)

Arguments

Value

The input data with polygon AOI membership columns.

Examples

gaze <- data.frame(
  FPOGX = c(0.2, 0.7, 0.9),
  FPOGY = c(0.2, 0.7, 0.1)
)

triangle <- data.frame(
  aoi_name = "triangle",
  vertex_x = c(0, 1, 0),
  vertex_y = c(0, 0, 1)
)

add_gazepoint_polygon_aoi(
  gaze,
  triangle,
  output = "both"
)

Description

Constructs the same pupil stream under multiple declared policies and compares data retention, descriptive distribution summaries, condition means/contrasts, and pairwise series correlations. It deliberately avoids converting policy disagreement into an automatic inferential verdict.

Usage

analyse_gazepoint_binocular_sensitivity(
  data,
  left_col,
  right_col,
  policies = c("complete_case", "available_eye", "reconstructed_mean", "left_only",
    "right_only"),
  prefix = "gp3_binocular",
  group_cols = NULL,
  condition_col = NULL,
  valid_min = NULL,
  valid_max = NULL
)

Arguments

Value

A gp3_binocular_sensitivity object containing policy summaries, pairwise correlations, optional condition summaries/contrasts, and the constructed long series.

See Also

audit_gazepoint_binocular_reconstruction()

Examples

dat <- simulate_gazepoint_pupil_data(n_subjects = 4, n_trials = 2, seed = 24)
dat$pupil_right[20:24] <- NA_real_
rec <- reconstruct_gazepoint_binocular_pupil(
  dat, "pupil_left", "pupil_right", group_cols = "subject", min_pairs = 20
)
analyse_gazepoint_binocular_sensitivity(
  rec, "pupil_left", "pupil_right", condition_col = "condition"
)

Description

Creates overlapping or non-overlapping time windows and calculates selected summary statistics for numeric gaze or pupil columns.

Usage

analyze_gazepoint_window(
  et_data,
  window_size = 50,
  step = 10,
  summary_stats = c("mean", "sd"),
  by = "USER_ID",
  condition_col = NULL,
  value_cols = NULL,
  ts_col = "TIME",
  window_unit = c("milliseconds", "seconds", "native"),
  time_unit = c("auto", "seconds", "milliseconds"),
  include_partial = FALSE
)

Arguments

Value

A tibble with one row per group and time window.

Examples

pupil <- data.frame(
  USER_ID = "P01",
  TIME = seq(0, 0.99, by = 0.01),
  mean_pupil = sin(seq(0, 2 * pi, length.out = 100))
)
analyze_gazepoint_window(
  pupil,
  window_size = 100,
  step = 50,
  value_cols = "mean_pupil"
)

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)

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.

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.

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.

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.

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")

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.

Description

Summarises how much of the retained pupil signal depends on model-based reconstruction, where reconstruction was blocked, whether reconstruction is uneven across declared groups, and how much reconstruction shifts a simple available-eye combined signal.

Usage

audit_gazepoint_binocular_reconstruction(
  data,
  by = NULL,
  prefix = "gp3_binocular",
  max_reconstruction_prop = NULL,
  max_group_rate_difference = NULL
)

Arguments

Details

Thresholds are governance flags, not statistical tests and not universal validity cutoffs.

Value

A gp3_binocular_audit object with overall burden, grouped burden, status counts, model diagnostics, and audit status.

See Also

analyse_gazepoint_binocular_sensitivity(), summarise_gazepoint_binocular_reporting()

Examples

dat <- simulate_gazepoint_pupil_data(n_subjects = 4, n_trials = 2, seed = 23)
dat$pupil_left[35:38] <- NA_real_
rec <- reconstruct_gazepoint_binocular_pupil(
  dat, "pupil_left", "pupil_right", group_cols = "subject", min_pairs = 20
)
audit_gazepoint_binocular_reconstruction(rec, by = "condition")

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.

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.

Description

Summarise whether gaze samples could be matched to dynamic AOI definitions, how large the definition-time gaps were, and how often samples fell inside versus outside defined AOIs.

Usage

audit_gazepoint_dynamic_aoi_coverage(
  data,
  label_col = "aoi_current",
  definition_time_col = "aoi_definition_time",
  time_gap_col = "aoi_time_gap",
  group_cols = NULL,
  outside_label = "outside",
  max_time_gap = Inf,
  x_col = NULL,
  y_col = NULL
)

Arguments

Value

An object of class "gp3_dynamic_aoi_coverage_audit" containing overview, group, AOI, and flagged-row tables plus settings.

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.

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.

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)

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)

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"
)

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.

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)

Description

Audit British and American summary-function spellings

Usage

audit_gazepoint_naming_consistency(exports = NULL)

Arguments

Value

A "gazepoint_naming_audit" object containing paired names and an overall status.

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.

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.

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.

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).

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.

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.

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.

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)

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.

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.

Description

Compares a sustained-threshold onset and maximum-slope tangent onset while reporting estimator spread, sampling rate, robust baseline noise, and a latency-resolvability label. This is a QC/reporting diagnostic rather than a claim that any one estimator is universally correct.

Usage

audit_gp3_pupil_latency_resolution(
  time,
  pupil,
  event_time = 0,
  baseline_window = c(-0.5, 0),
  search_window = c(0, 2),
  direction = c("constriction", "dilation"),
  threshold_sigma = 3,
  sustain_ms = 50
)

Arguments

Value

A structured pupil-latency QC record suitable for reports.

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)

Description

Compare standardized fixation intervals from one or more detectors with a manually reviewed or synthetic reference-event table. Matching is one-to-one within each participant/trial sequence and is based on interval intersection-over-union. Results quantify methodological agreement with the supplied reference annotations; they do not establish a universally correct detector.

Usage

benchmark_gazepoint_event_detectors(
  x,
  reviewed_events,
  sequence_cols = NULL,
  reviewed_start_col = "start_time",
  reviewed_end_col = "end_time",
  reviewed_id_col = "review_event_id",
  review_status_col = "review_status",
  accepted_status = c("accepted", "include", "reviewed", "confirmed"),
  min_overlap = 0.5,
  time_unit = c("seconds", "milliseconds")
)

Arguments

Value

An object of class "gp3_event_detector_benchmark" containing detector-level metrics, sequence-level metrics, one-to-one matches, unmatched-event diagnostics, accepted reviewed events, detector events, detector-run information, and settings.

Examples

reviewed <- data.frame(
  USER_ID = "P01",
  trial = "T01",
  review_event_id = 1:2,
  start_time = c(0, 2),
  end_time = c(1, 3)
)

detected <- data.frame(
  USER_ID = "P01",
  trial = "T01",
  detector = "velocity_10",
  family = "velocity",
  threshold = 10,
  event_id = 1:2,
  start_time = c(0.05, 2.05),
  end_time = c(1.05, 3.05),
  duration_ms = 1000
)

benchmark <- benchmark_gazepoint_event_detectors(
  detected,
  reviewed,
  sequence_cols = c("USER_ID", "trial")
)

benchmark$detector_metrics

Description

Generates deterministic Gazepoint-like all-gaze exports and benchmarks selected package operations across increasing row and file counts. Ordinary unit tests should use small scales. The script installed under ⁠inst/benchmarks/⁠ runs the large-export profile.

Usage

benchmark_gazepoint_export_performance(
  scales = data.frame(total_rows = c(10000L, 50000L, 200000L), n_files = c(1L, 4L, 8L)),
  operations = c("generate", "import", "master", "sampling", "quality"),
  trials = 3L,
  seed = 20260717L,
  limits = gp3tools_performance_limits(),
  stop_on_regression = FALSE,
  output_dir = NULL,
  keep_exports = FALSE,
  on_error = c("record", "stop")
)

Arguments

Value

A "gazepoint_performance_benchmark" object containing trial-level measurements, aggregated summaries, regression checks, settings, and session metadata.

Description

Evaluate the stability of scanpath clustering by repeatedly subsampling scanpaths, refitting the clustering solution, and recording co-clustering, adjusted Rand agreement, and representative-scanpath selection.

Usage

bootstrap_gazepoint_scanpath_clusters(
  x,
  k = 3L,
  n_boot = 200L,
  sample_fraction = 0.8,
  method = c("hierarchical", "pam"),
  linkages = "average",
  seed = NULL,
  aoi_col = NULL,
  group_cols = NULL,
  time_col = NULL,
  distance_col = "normalized_distance",
  include_missing = FALSE,
  missing_label = "missing",
  collapse_repeats = FALSE,
  max_sequences = 200
)

Arguments

Details

The routine reuses the distance formats accepted by cluster_gazepoint_scanpaths(). Hierarchical solutions can be compared across multiple linkage methods. PAM remains optional through cluster.

Value

An object of class "gp3_scanpath_cluster_bootstrap" containing full-data reference fits, co-clustering and pair-coverage matrices, iteration-level adjusted Rand results, representative stability, the reusable distance object, and resolved settings.

Examples

latent <- rep(1:3, each = 2)
d <- outer(
  latent,
  latent,
  FUN = function(x, y) ifelse(x == y, 0.1, 1)
)
diag(d) <- 0
dimnames(d) <- list(LETTERS[1:6], LETTERS[1:6])

stability <- bootstrap_gazepoint_scanpath_clusters(
  d,
  k = 3,
  n_boot = 10,
  seed = 1
)

stability$iteration_summary

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.

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.

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.

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.

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.

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.

Description

Applies explicit absolute limits and, optionally, compares matched rows with a saved baseline. Scaling exponents are estimated from median elapsed times across row-count levels.

Usage

check_gazepoint_performance_regression(
  x,
  limits = gp3tools_performance_limits(),
  baseline = NULL,
  elapsed_ratio_limit = 1.5,
  memory_ratio_limit = 1.5
)

Arguments

Value

A "gazepoint_performance_regression" object.

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.

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.

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.

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.

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
)

Description

Cluster scanpaths from long-format AOI observations, pairwise scanpath distances, a numeric distance matrix, or a "dist" object.

Usage

cluster_gazepoint_scanpaths(
  x,
  k = 3,
  method = c("hierarchical", "pam"),
  linkage = c("average", "complete", "single", "ward.D2", "ward.D", "mcquitty", "median",
    "centroid"),
  aoi_col = NULL,
  group_cols = NULL,
  time_col = NULL,
  distance_col = "normalized_distance",
  include_missing = FALSE,
  missing_label = "missing",
  collapse_repeats = FALSE,
  max_sequences = 200
)

Arguments

Details

Long-format AOI data are converted to pairwise normalized edit distances with compute_gazepoint_scanpath_similarity. Hierarchical clustering uses base R. Partitioning around medoids requires the optional cluster package.

Value

An object of class "gp3_scanpath_clusters" containing:

• assignments: scanpath identifiers and cluster assignments;

• distance: the clustering distance object;

• model: the fitted hierarchical or PAM model;

• medoids: PAM medoid identifiers, when applicable;

• silhouette: scanpath-level silhouette diagnostics when cluster is available;

• clustering settings and status fields.

Examples

distance_matrix <- matrix(
  c(
    0, 1, 5, 6,
    1, 0, 6, 5,
    5, 6, 0, 1,
    6, 5, 1, 0
  ),
  nrow = 4,
  byrow = TRUE,
  dimnames = list(
    c("scanpath_1", "scanpath_2", "scanpath_3", "scanpath_4"),
    c("scanpath_1", "scanpath_2", "scanpath_3", "scanpath_4")
  )
)

result <- cluster_gazepoint_scanpaths(
  distance_matrix,
  k = 2,
  method = "hierarchical"
)

result$assignments

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))

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")

Description

Run native velocity-threshold detection, the lightweight gp3tools HMM classifier, and an optional eyetools branch on the same sample-level gaze data. Detector failures are recorded without invalidating successful branches.

Usage

compare_gazepoint_event_detectors(
  data,
  id_col = "USER_ID",
  trial_col = NULL,
  group_cols = NULL,
  x_col = "FPOGX",
  y_col = "FPOGY",
  time_col = "TIME",
  methods = c("velocity", "hmm", "eyetools"),
  velocity_thresholds = c(5, 10, 20),
  min_duration = 50,
  hmm_states = 3L,
  eyetools_method = c("vti", "dispersion"),
  run_optional_eyetools = FALSE,
  min_overlap = 0.5,
  velocity_args = list(),
  hmm_args = list(),
  eyetools_args = list()
)

Arguments

Value

An object of class "gp3_event_detector_comparison" containing standardized event tables, detector-run status, detector summaries, pairwise agreement, unmatched events, raw detector outputs, and settings.

Examples

gaze <- data.frame(
  USER_ID = rep("P01", 80),
  trial = rep("T01", 80),
  TIME = seq(0, by = 0.01, length.out = 80),
  FPOGX = c(rep(0.2, 30), seq(0.2, 0.8, length.out = 10), rep(0.8, 40)),
  FPOGY = 0.5
)

comparison <- compare_gazepoint_event_detectors(
  gaze,
  trial_col = "trial",
  methods = "velocity",
  velocity_thresholds = c(5, 10)
)

comparison$detector_summary

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.

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"
)

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.