Package {gp3tools}

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

results <- run_gazepoint_workflow(
  export_dir = system.file("extdata", "gazepoint_realistic_demo_exports", package = "gp3tools"),
  output_dir = file.path(tempdir(), "gp3_outputs")
)

master <- as_gazepoint_master(
  gazepoint_example_master,
  screen_width_px = 1920,
  screen_height_px = 1080
)

dplyr::glimpse(master)

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

master <- gazepoint_example_master
results <- run_gazepoint_workflow(
  export_dir = system.file("extdata", "gazepoint_realistic_demo_exports", package = "gp3tools"),
  output_dir = file.path(tempdir(), "gp3_outputs")
)

master <- create_gazepoint_master(
  gaze_data = gazepoint_example_master,
  screen_width_px = 1920,
  screen_height_px = 1080
)

audit <- audit_gazepoint_master(master)

audit$overview
audit$by_subject
audit$aoi_states

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

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

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

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

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

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.

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 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 = NULL,
  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

master <- tibble::tibble(
  subject = c("P1", "P1", "P2", "P2"),
  MEDIA_ID = c("M1", "M1", "M1", "M1"),
  time = c(0, 16, 0, 16),
  x = c(100, 120, 200, 220),
  y = c(100, 130, 200, 230),
  raw_x = c(0.10, 0.12, 0.20, 0.22),
  raw_y = c(0.20, 0.26, 0.30, 0.34),
  valid_sample = c(TRUE, TRUE, TRUE, TRUE),
  missing_gaze = c(FALSE, FALSE, FALSE, FALSE),
  missing_pupil = c(FALSE, FALSE, FALSE, FALSE),
  gaze_offscreen = c(FALSE, FALSE, FALSE, FALSE),
  mean_pupil = c(3.5, 3.6, 3.7, 3.8),
  aoi_current = c("AOI 1", "AOI 1", "AOI 2", "AOI 2"),
  aoi_count = c(1L, 1L, 1L, 1L),
  screen_width_px = rep(1000, 4),
  screen_height_px = rep(500, 4)
)

exported <- export_gazepoint_master_audit(
  master = master,
  output_dir = file.path(tempdir(), "gp3_master_audit"),
  prefix = "example"
)

exported

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

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

master <- gazepoint_example_master
flagged <- flag_gazepoint_pupil(master)

dplyr::count(flagged, pupil_flag_reason)

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

master <- gazepoint_example_master
registry <- create_gazepoint_preprocessing_registry()

artifact_pupil <- flag_gazepoint_pupil_artifacts(
  master,
  registry = registry
)

dplyr::count(artifact_pupil, pupil_artifact_reason)

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

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

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

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.

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

Value

A ggplot object.

Plot cluster-based permutation results

Description

Create a publication-ready time-course plot from the output of run_gazepoint_cluster_permutation(). The plot can show the mean condition difference, the time-wise test statistic, or both. Candidate time bins and cluster-level significant windows can be highlighted.

Usage

plot_gazepoint_cluster_results(
  result,
  plot_type = c("both", "difference", "statistic"),
  alpha = 0.05,
  significant_only = TRUE,
  show_clusters = TRUE,
  show_candidates = TRUE,
  show_threshold = TRUE,
  show_zero_line = TRUE,
  title = NULL,
  subtitle = NULL,
  x_label = "Time (ms)",
  y_label = NULL,
  line_width = 0.7,
  point_size = 1.8,
  cluster_alpha = 0.12
)

Arguments

Details

Cluster-based permutation tests are intended for time-course inference. They should not be used to discover a confirmatory time window and then test that same window again in a second confirmatory model.

Value

A ggplot object.

Plot observed and fitted Growth Curve Analysis trajectories

Description

Plot observed and fitted pupil trajectories from a gp3_gca_model object. The function aggregates observed and fitted values by condition and time, and returns a ggplot2 object.

Usage

plot_gazepoint_gca(
  model,
  data = NULL,
  time_col = "gca_time",
  observed_col = "gca_pupil",
  fitted_col = "gca_fitted",
  condition_col = "condition",
  subject_col = "subject",
  summarise = TRUE,
  show_observed = TRUE,
  show_fitted = TRUE,
  show_subjects = FALSE,
  interval = TRUE,
  title = NULL,
  point_size = 1.6,
  line_width = 0.8,
  alpha = 0.75
)

Arguments

Value

A ggplot2 object.

Plot observed summaries and model-implied predictions

Description

Create a reporting plot that overlays observed outcome summaries with fitted/model-predicted trajectories. The helper is intentionally generic and can be used with linear models, GLMs, mixed models, GAMMs, GCA-style models, AOI GLMMs, and pupil LMMs when the fitted object supports predict().

Usage

plot_gazepoint_model_predictions(
  data,
  model = NULL,
  x_col,
  outcome_col,
  condition_col = NULL,
  group_cols = NULL,
  facet_cols = NULL,
  newdata = NULL,
  prediction_type = c("response", "link"),
  include_random_effects = FALSE,
  observed_summary_function = c("mean", "median"),
  ci = 0.95,
  show_observed = TRUE,
  show_observed_ci = TRUE,
  show_predictions = TRUE,
  show_prediction_ci = TRUE,
  point_alpha = 0.55,
  line_width = 1,
  name = "gazepoint_model_predictions"
)

Arguments

Value

A ggplot object with attributes containing the observed summary, prediction summary, overview, and settings.

Plot Gazepoint preprocessing multiverse results

Description

Create diagnostic plots from preprocessing multiverse summaries or from pupil/AOI multiverse result objects.

Usage

plot_gazepoint_multiverse_results(
  x,
  plot = c("status", "rows", "pupil_parameters", "aoi_denominators"),
  family = c("all", "pupil", "aoi"),
  title = NULL,
  show_labels = TRUE
)

Arguments

Value

A ggplot object.

Plot Gazepoint pupil preprocessing for one trial

Description

Create a visual audit plot for one selected subject, media item, trial, or trial-global identifier. The plot can show raw pupil, cleaned pupil, interpolated pupil, baseline-corrected pupil, smoothed pupil, and artifact flags.

Usage

plot_gazepoint_pupil_preprocessing(
  data,
  subject = NULL,
  media_id = NULL,
  trial = NULL,
  trial_global = NULL,
  condition = NULL,
  subject_col = "subject",
  media_col = "MEDIA_ID",
  trial_col = "trial",
  trial_global_col = "trial_global",
  condition_col = "condition",
  time_col = "time",
  raw_pupil_col = "pupil",
  clean_pupil_col = "pupil_clean",
  interpolated_pupil_col = "pupil_interpolated",
  baseline_pupil_col = "pupil_baseline_corrected",
  smoothed_pupil_col = "pupil_smoothed",
  artifact_col = NULL,
  artifact_reason_col = NULL,
  status_col = "pupil_interpolation_status",
  plot_style = c("faceted", "overlaid"),
  bin_width_ms = 50,
  max_event_marks = 150,
  point_size = 0.8,
  line_width = 0.35,
  alpha = 0.95
)

Arguments

Value

A ggplot2 plot object.

Plot Gazepoint pupil preprocessing status

Description

Visualise observed, interpolated, missing, artifact, and other pupil-sample statuses over time or as grouped percentages.

Usage

plot_gazepoint_pupil_status(
  data,
  time_col = "time",
  pupil_col = NULL,
  status_col = "pupil_interpolation_status",
  interpolated_col = "pupil_was_interpolated",
  artifact_col = NULL,
  artifact_reason_col = NULL,
  group_cols = c("subject", "trial_global"),
  facet_cols = NULL,
  plot_type = c("timeline", "summary"),
  point_size = 0.7,
  alpha = 0.8,
  max_points = 50000
)

Arguments

Value

A ggplot2 plot object.

Plot Gazepoint pupil time course

Description

Plot a binned pupil time course with a mean line and confidence band. The function can plot one overall time course or condition-wise time courses, with optional faceting by variables such as condition, media, AOI, subject, or trial.

Usage

plot_gazepoint_pupil_timecourse(
  data,
  pupil_col = NULL,
  time_col = "time",
  condition_col = "condition",
  facet_cols = NULL,
  bin_width_ms = 100,
  ci_level = 0.95,
  min_samples = 1,
  band_alpha = 0.2,
  line_width = 0.8
)

Arguments

Value

A ggplot2 plot object.

Plot Gazepoint sampling-rate diagnostics

Description

Creates a diagnostic plot of estimated sampling rate by participant/file and media stimulus.

Usage

plot_sampling_rate(
  sampling,
  user_col = "USER_FILE",
  media_col = "MEDIA_ID",
  expected_hz = 60,
  hz_tolerance = 5
)

Arguments

Value

A ggplot object.

Plot Gazepoint tracking-quality diagnostics

Description

Creates a readable diagnostic plot of selected gaze and pupil validity percentages by participant/file and media stimulus.

Usage

plot_tracking_quality(
  data,
  metric_cols = NULL,
  user_col = "USER_FILE",
  media_col = "MEDIA_ID",
  review_col = "review_required",
  min_valid_pct = 70
)

Arguments

Value

A ggplot object.

Plot an AOI transition heatmap

Description

Plot an AOI transition heatmap

Usage

plot_transition_heatmap(transitions)

Arguments

Value

A ggplot object.

Prepare AOI time-course data for GAMM analysis

Description

Prepare sample-level or binned Gazepoint AOI data for AOI time-course GAMM analysis. The function creates binned subject-by-condition-by-time summaries with binomial success/failure counts for target-AOI looking over time.

Usage

prepare_gazepoint_aoi_gamm_data(
  data,
  aoi_col = "aoi_current",
  target_aoi_values = NULL,
  outcome_col = NULL,
  subject_col = "subject",
  condition_col = "condition",
  time_col = "time",
  trial_col = NULL,
  time_bin_col = NULL,
  conditions = NULL,
  time_window = NULL,
  bin_size_ms = 50,
  denominator = c("valid", "all", "aoi_only"),
  valid_aoi_values = NULL,
  non_aoi_values = c("non_aoi"),
  missing_aoi_values = c("missing", ""),
  min_denominator_samples = 1,
  drop_invalid = TRUE,
  missing_condition_label = "all_data",
  outcome_label = "target_aoi"
)

Arguments

Details

This helper is intended for modelling AOI time-course trajectories, such as target-AOI looking probability over time. It is separate from confirmatory AOI-window GLMMs and from cluster-based permutation tests.

Value

A tibble with standardised AOI-GAMM columns.

Prepare AOI-window data for binomial GLMMs

Description

Prepare AOI-window summaries for confirmatory binomial mixed-effects modelling. The function creates success, failure, denominator, proportion, subject, condition, and window columns from output produced by summarise_gazepoint_aoi_windows().

Usage

prepare_gazepoint_aoi_glmm_data(
  data,
  success_col = "n_target_samples",
  denominator = c("valid", "all", "aoi", "custom"),
  denominator_col = NULL,
  valid_denominator_col = "n_valid_denominator_samples",
  all_denominator_col = "n_window_samples",
  aoi_denominator_col = "n_aoi_samples",
  subject_col = "subject",
  condition_col = "condition",
  window_col = "window_label",
  window_start_col = "window_start_ms",
  window_end_col = "window_end_ms",
  group_cols = NULL,
  min_denominator_samples = 1,
  drop_invalid = TRUE,
  missing_condition_label = "all_data",
  outcome_label = "target"
)

Arguments

Value

A tibble of GLMM-ready AOI-window rows.

Prepare Gazepoint AOI sequences

Description

Create ordered AOI-state sequences from sample-level Gazepoint AOI data or from the output of summarise_gazepoint_aoi_entries(). The output is transition-ready and includes the current AOI state, previous state, next state, dwell time before transition, and self-transition flags.

Usage

prepare_gazepoint_aoi_sequences(
  data,
  aoi_col = NULL,
  time_col = "time",
  group_cols = c("subject", "MEDIA_ID", "trial_global"),
  include_non_aoi = TRUE,
  non_aoi_values = c("non_aoi", "none", "background", "outside", "outside_aoi",
    "missing", "missing_aoi"),
  missing_aoi_label = "missing_aoi",
  include_terminal = TRUE
)

Arguments

Value

A tibble with ordered AOI sequence and transition fields.

Prepare time-course data for cluster-based permutation tests

Description

Prepare sample-level or already binned Gazepoint time-course data for cluster-based permutation testing. The function standardises subject, condition, time-bin, outcome, sample-count, trial-count, and status columns. It can be used for AOI proportions, pupil time-course outcomes, or other continuous time-varying measures.

Usage

prepare_gazepoint_cluster_data(
  data,
  outcome_col,
  subject_col = "subject",
  condition_col = "condition",
  time_col = "time",
  trial_col = NULL,
  time_bin_col = NULL,
  conditions = NULL,
  time_window = NULL,
  bin_size_ms = 50,
  aggregation = c("mean", "proportion", "sum", "median"),
  min_samples_per_bin = 1,
  paired = TRUE,
  drop_invalid = TRUE,
  missing_condition_label = "all_data",
  outcome_label = "outcome"
)

Arguments

Details

Cluster-based permutation tests are intended for time-course inference. They should not be used to discover a time window and then test that same window again as a confirmatory analysis.

Value

A tibble with standardised cluster-test preparation columns.

Prepare Gazepoint master data for eyetools-style workflows

Description

Convert a gp3tools master table into a dependency-free, eyetools-friendly sample-level table. The returned data frame keeps one row per sample and creates standard participant, trial, time, gaze-coordinate, binocular coordinate, pupil, AOI, fixation, event, validity, trackloss, and status columns.

Usage

prepare_gazepoint_eyetools_data(
  data,
  participant_col = NULL,
  trial_col = NULL,
  time_col = NULL,
  x_col = NULL,
  y_col = NULL,
  left_x_col = NULL,
  left_y_col = NULL,
  right_x_col = NULL,
  right_y_col = NULL,
  pupil_col = NULL,
  left_pupil_col = NULL,
  right_pupil_col = NULL,
  media_col = NULL,
  condition_col = NULL,
  aoi_col = NULL,
  fixation_col = NULL,
  event_col = NULL,
  validity_cols = NULL,
  trackloss_col = NULL,
  screen_x_range = c(0, 1),
  screen_y_range = c(0, 1),
  missing_aoi_label = "missing_aoi",
  keep_original_cols = TRUE
)

Arguments

Value

A tibble with class gp3_eyetools_data.

Prepare Gazepoint master data for eyetrackingR-style workflows

Description

Convert a gp3tools master table into a dependency-free, eyetrackingR-friendly sample-level table. The returned data frame keeps one row per gaze sample and creates standard participant, trial, time, gaze-coordinate, AOI, trackloss, and AOI-indicator columns.

Usage

prepare_gazepoint_eyetrackingr_data(
  data,
  participant_col = NULL,
  trial_col = NULL,
  time_col = NULL,
  aoi_col = NULL,
  x_col = NULL,
  y_col = NULL,
  media_col = NULL,
  condition_col = NULL,
  validity_cols = NULL,
  aoi_values = NULL,
  aoi_prefix = "aoi_",
  missing_aoi_label = "missing_aoi",
  non_aoi_values = c("outside", "none", "no_aoi", "non_aoi", "background", "off_aoi",
    "missing", "NA"),
  trackloss_col = NULL,
  keep_original_cols = TRUE
)

Arguments

Value

A tibble with class gp3_eyetrackingr_data.

Prepare fixation- or saccade-contingent aligned Gazepoint data

Description

Align Gazepoint observations to a within-trial event such as first fixation, first target-AOI entry, first fixation to a target AOI, first saccade to a target AOI, or a custom event marker. The helper returns the original data with event-aligned time, event metadata, pre-event/post-event flags, and trial-level summaries that help separate event-driven looking from looks that were already present before the event.

Usage

prepare_gazepoint_fixation_aligned_data(
  data,
  time_col,
  participant_col = NULL,
  trial_col = NULL,
  aoi_col = NULL,
  target_aoi = NULL,
  fixation_col = NULL,
  saccade_col = NULL,
  event_col = NULL,
  event_value = NULL,
  alignment_event = c("first_target_entry", "first_fixation_to_target",
    "first_saccade_to_aoi", "first_fixation", "custom"),
  baseline_window = NULL,
  analysis_window = NULL,
  keep_unaligned = FALSE,
  name = "gazepoint_fixation_aligned_data"
)

Arguments

Value

A list with class gp3_fixation_aligned_data.

Prepare Gazepoint master data for gazer-style workflows

Description

Convert a gp3tools master table into a dependency-free, gazer-friendly sample-level table. The returned data frame keeps one row per gaze sample and creates standard participant, trial, time, gaze-coordinate, pupil, AOI, fixation, validity, trackloss, and screen-bound status columns.

Usage

prepare_gazepoint_gazer_data(
  data,
  participant_col = NULL,
  trial_col = NULL,
  time_col = NULL,
  x_col = NULL,
  y_col = NULL,
  pupil_col = NULL,
  media_col = NULL,
  condition_col = NULL,
  aoi_col = NULL,
  fixation_col = NULL,
  validity_cols = NULL,
  trackloss_col = NULL,
  screen_x_range = c(0, 1),
  screen_y_range = c(0, 1),
  missing_aoi_label = "missing_aoi",
  keep_original_cols = TRUE
)

Arguments

Value

A tibble with class gp3_gazer_data.

Prepare Gazepoint Growth Curve Analysis data

Description

Prepare binned pupil time-course data for Growth Curve Analysis (GCA). The function creates orthogonal polynomial time terms, preserves subject and condition information, and standardises key columns for later mixed-model fitting.

Usage

prepare_gazepoint_gca_data(
  data,
  pupil_col = "mean_pupil",
  time_col = "time_bin_center_ms",
  subject_col = "subject",
  condition_col = "condition",
  degree = 3,
  orthogonal = TRUE,
  time_window = NULL,
  valid_samples_col = "n_valid_samples",
  min_valid_samples = 1,
  weights_col = NULL,
  missing_condition_label = "all_data",
  drop_missing = TRUE
)

Arguments

Value

A tibble of class gp3_gca_data with standard GCA columns and polynomial time terms.

Prepare Gazepoint AOI/state sequences for HMM-style workflows

Description

Convert ordered Gazepoint AOI/state observations into a dependency-free hidden-Markov-model-ready structure. The helper creates ordered sequence data, transition tables, initial-state probabilities, transition-probability matrices, and observation/emission summaries. It does not fit an HMM and does not import external HMM packages.

Usage

prepare_gazepoint_hmm_data(
  data,
  state_col = NULL,
  participant_col = NULL,
  trial_col = NULL,
  time_col = NULL,
  observation_cols = NULL,
  sequence_id_cols = NULL,
  covariate_cols = NULL,
  state_order = NULL,
  exclude_states = c("missing", "missing_aoi", "missing_coordinate", "trackloss",
    "track_loss"),
  missing_state_label = NULL,
  scale_numeric_observations = FALSE,
  include_terminal_state = FALSE,
  terminal_state_label = "END",
  name = "gazepoint_hmm_data"
)

Arguments

Value

A list with class gp3_hmm_data.

Prepare Gazepoint pupil GAMM data

Description

Prepare binned pupil time-course data for GAMM modelling with mgcv::bam(). The function aggregates processed sample-level pupil data into subject-by- condition-by-time-bin rows and creates an AR.start indicator for autoregressive GAMM models.

Usage

prepare_gazepoint_pupil_gamm_data(
  data,
  pupil_col = NULL,
  time_col = "time",
  subject_col = "subject",
  condition_col = "condition",
  x_col = NULL,
  y_col = NULL,
  group_cols = c("subject", "condition"),
  bin_width_ms = 50,
  time_window = NULL,
  min_valid_samples = 1,
  missing_condition_label = "all_data"
)

Arguments

Value

A tibble with binned pupil time-course data for GAMM modelling.

Prepare pupil-window data for confirmatory mixed models

Description

Prepare pupil-window summaries or pupil trial-feature tables for confirmatory window-level modelling. The function standardises subject, condition, window, trial/media identifiers, outcome, valid-sample counts, total-sample counts, valid-sample proportions, weights, and model-readiness status columns.

Usage

prepare_gazepoint_pupil_window_model_data(
  data,
  outcome_col = "mean_pupil",
  subject_col = "subject",
  condition_col = "condition",
  window_col = "window_label",
  window_start_col = "window_start_ms",
  window_end_col = "window_end_ms",
  trial_col = NULL,
  media_col = "media_id",
  valid_samples_col = "n_valid_pupil",
  total_samples_col = "n_samples",
  min_valid_samples = 5,
  min_valid_prop = 0.7,
  drop_invalid = TRUE,
  missing_condition_label = "all_data",
  outcome_label = "pupil"
)

Arguments

Value

A tibble of pupil-window rows prepared for confirmatory modelling.

Prepare Gazepoint master data for pupillometryR-style workflows

Description

Convert a gp3tools master table into a dependency-free, pupillometryR-friendly sample-level pupil table. The returned data frame keeps one row per sample and creates standard participant, trial, time, pupil, condition, event, baseline, validity, trackloss, and status columns.

Usage

prepare_gazepoint_pupillometryr_data(
  data,
  participant_col = NULL,
  trial_col = NULL,
  time_col = NULL,
  pupil_col = NULL,
  media_col = NULL,
  condition_col = NULL,
  event_col = NULL,
  baseline_col = NULL,
  validity_cols = NULL,
  pupil_status_col = NULL,
  trackloss_col = NULL,
  invalid_pupil_status = c("missing", "artifact", "blink", "trackloss", "track_loss",
    "invalid", "excluded", "bad", "outlier"),
  keep_original_cols = TRUE
)

Arguments

Value

A tibble with class gp3_pupillometryr_data.

Prepare Gazepoint AOI sequences for semi-Markov modelling

Description

Convert ordered AOI/state observations into state-visit and transition-level semi-Markov data. Consecutive repeated states can be collapsed into dwell episodes, producing one row per state visit with dwell duration and next-state information.

Usage

prepare_gazepoint_semimarkov_data(
  data,
  state_col = NULL,
  participant_col = NULL,
  trial_col = NULL,
  time_col = NULL,
  duration_col = NULL,
  sequence_id_cols = NULL,
  covariate_cols = NULL,
  exclude_states = c("missing", "missing_aoi", "missing_coordinate", "trackloss",
    "track_loss"),
  missing_state_label = NULL,
  collapse_repeated_states = TRUE,
  include_terminal_states = TRUE,
  terminal_next_state_label = "END",
  name = "gazepoint_semimarkov_data"
)

Arguments

Value

A list with class gp3_semimarkov_data.

Read a Gazepoint all-gaze or fixation CSV export

Description

Reads Gazepoint all-gaze and fixation CSV exports, standardises timestamped column names, and removes empty trailing columns produced by Gazepoint exports.

Usage

read_gazepoint(path, standardise_names = TRUE, drop_empty_cols = TRUE)

Arguments

Value

A tibble with attributes gp3_file_type and gp3_source_file.

Read multiple Gazepoint CSV exports from a folder

Description

Reads all Gazepoint all-gaze or fixation CSV exports in a folder that match a filename pattern and combines them into one tibble.

Usage

read_gazepoint_folder(
  folder,
  pattern = "\\.csv$",
  source_col = "USER_FILE",
  recursive = FALSE,
  ...
)

Arguments

Value

A tibble containing all matching files combined row-wise.

Read a Gazepoint Analysis Data Summary export

Description

Parses the multi-section Data_Summary_export_*.csv file into metadata, aoi_summary, and aoi_by_user tables.

Usage

read_gazepoint_summary(path)

Arguments

Value

A list with metadata, aoi_summary, and aoi_by_user.

Offline gaze recalibration using known target coordinates

Description

Apply an offline drift-correction shift to Gazepoint gaze coordinates using known fixation/check-target coordinates. For each group, the helper estimates the horizontal and vertical gaze offset from valid target samples and applies the correction to all gaze samples in the same group.

Usage

recalibrate_gazepoint_gaze(
  data,
  x_col,
  y_col,
  target_x_col,
  target_y_col,
  time_col = NULL,
  grouping_cols = NULL,
  calibration_col = NULL,
  calibration_value = NULL,
  method = c("median_shift", "mean_shift"),
  min_valid_points = 3L,
  max_shift = NULL,
  output_x_col = "gaze_x_recalibrated",
  output_y_col = "gaze_y_recalibrated",
  dx_col = "gaze_recalibration_dx",
  dy_col = "gaze_recalibration_dy",
  shift_col = "gaze_recalibration_shift",
  error_before_col = "gaze_error_before_recalibration",
  error_after_col = "gaze_error_after_recalibration",
  status_col = "gaze_recalibration_status",
  overwrite = FALSE,
  name = "gazepoint_gaze_recalibration"
)

Arguments