Package 'gp3tools'

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)

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

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

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

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

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

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

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

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

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

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

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

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

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

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.

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.

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.

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.

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.

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.

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.

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

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.

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.

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.

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.

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.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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)

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)

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.

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.

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

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)

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)

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.