Package 'gpbiometrics'

Description

Add one structured record to a decision log created with create_gazepoint_analysis_decision_log().

Usage

add_gazepoint_decision(
  log,
  stage,
  object_type,
  object_id = NA_character_,
  decision,
  reason = NA_character_,
  function_name = NA_character_,
  parameter = NA_character_,
  value = NA_character_,
  reviewer_note = NA_character_,
  timestamp = Sys.time()
)

Arguments

Value

Updated decision log.

Description

Aligns biometric rows to TTL/event markers and returns event-relative time and sample indices. The helper is conservative: TTL events are detected from rising edges by default, validity flags are used when available, and no physiological interpretation is added.

Usage

align_gazepoint_biometrics_to_ttl(
  data,
  ttl_cols = NULL,
  event_col = NULL,
  ttl_valid_col = NULL,
  time_col = NULL,
  sample_col = NULL,
  group_cols = NULL,
  participant_col = NULL,
  stimulus_col = NULL,
  trial_col = NULL,
  event_value = NULL,
  valid_values = c(TRUE, 1, "1"),
  event_edge = c("rising", "change", "active"),
  pre_window_ms = 1000,
  post_window_ms = 5000,
  pre_window_samples = NULL,
  post_window_samples = NULL,
  collapse_nearby_ms = 0,
  require_valid_ttl = TRUE
)

Arguments

Value

A list with overview, events, aligned_data, and settings.

Description

Estimates offset or linear drift between a reference stream and a target stream using matched event times, then adds an aligned reference-clock time column to the target stream.

Usage

align_gazepoint_streams_by_events(
  reference,
  target,
  reference_events,
  target_events,
  reference_time_col = NULL,
  target_time_col = NULL,
  reference_event_time_col = NULL,
  target_event_time_col = NULL,
  event_id_col = NULL,
  method = c("linear", "offset"),
  include_streams = TRUE
)

Arguments

Value

Object of class gazepoint_stream_alignment.

Description

Estimates a constant offset or linear offset-plus-drift mapping from matched Gazepoint and EEG events, then applies that mapping to a Gazepoint stream.

Usage

align_gazepoint_to_eeg(
  gazepoint,
  gazepoint_events,
  eeg_events,
  gazepoint_time_col = NULL,
  gazepoint_event_time_col = NULL,
  eeg_event_time_col = NULL,
  eeg_event_sample_col = NULL,
  gazepoint_event_id_col = NULL,
  eeg_event_id_col = NULL,
  gazepoint_time_unit = c("auto", "seconds", "milliseconds", "samples"),
  eeg_time_unit = c("auto", "seconds", "milliseconds", "samples"),
  eeg_sampling_rate_hz = NULL,
  method = c("offset", "linear"),
  match_by = c("auto", "id", "row"),
  robust = TRUE,
  maximum_residual_s = NULL,
  residual_action = c("error", "allow"),
  output_col = "time_eeg_s"
)

Arguments

Value

A "gazepoint_eeg_alignment" object.

Description

Computes summaries for specialised alternating-current EDA recordings. This function is for true AC admittance/susceptance data, not ordinary DC skin-conductance columns such as GSR_US.

Usage

analyze_gazepoint_ac_susceptance(
  dat,
  conductance_col = NULL,
  susceptance_col = NULL,
  admittance_col = NULL,
  phase_col = NULL,
  frequency_col = NULL,
  time_col = NULL,
  group_cols = NULL
)

Arguments

Value

A list with overview, timeseries, summary, and settings.

Description

Computes dependency-light linear Granger-style directionality tests between a respiration proxy and heart-rate or IBI/RR signal. This estimates predictive directionality in a VAR-style model. It does not prove physiological causality from observational data by itself.

Usage

analyze_gazepoint_cardiorespiratory_causality(
  dat,
  respiration_col,
  cardiac_col,
  time_col = NULL,
  group_cols = NULL,
  lag_order = 3,
  min_rows = 30,
  standardise = TRUE
)

Arguments

Value

A list with overview, causality_summary, and settings.

Description

Computes skin-potential level and skin-potential response descriptors from a voltage-like skin-potential column. This is for endosomatic skin-potential recordings, not standard exosomatic skin conductance.

Usage

analyze_gazepoint_skin_potential(
  dat,
  sp_col,
  time_col,
  group_cols = NULL,
  response_direction = c("both", "positive", "negative"),
  response_threshold = NULL,
  min_response_distance_s = 1
)

Arguments

Value

A list with overview, level_summary, response_table, timeseries, and settings.

Description

Replaces selected identifier columns with deterministic sequential codes. This function supports de-identification workflows, but it does not by itself guarantee anonymity or regulatory compliance.

Usage

anonymize_gazepoint_data(
  data,
  id_cols,
  prefix = "P",
  width = 3,
  keep_mapping = TRUE
)

Arguments

Value

A data frame with class gazepoint_anonymized_data.

Description

Validates expected columns and either throws an error, raises a warning, or returns a summary table.

Usage

assert_gazepoint_columns(
  data,
  required,
  optional = character(),
  mode = c("error", "warning", "summary"),
  ignore_case = TRUE
)

Arguments

Value

Invisibly TRUE for passing checks, or a summary data frame when mode = "summary".

Description

Computes descriptive quality-control summaries for a Gazepoint HRP/PPG waveform column. The output is intended for waveform availability, missingness, flatness, and timing-gap review. It does not infer diagnosis, emotion, valence, cognition, preference, or true physiological state.

Usage

assess_gazepoint_hrp_waveform_quality(
  data,
  hrp_col = NULL,
  time_col = NULL,
  group_cols = NULL,
  sampling_rate = NULL,
  time_unit = c("auto", "ms", "seconds", "samples"),
  min_rows = 20,
  min_finite_prop = 0.8,
  max_flat_prop = 0.95,
  flat_tolerance = 1e-08,
  max_gap_multiplier = 3
)

Arguments

Value

A list with overview, group_quality, row_flags, and settings.

Description

Summarizes median sample interval, effective sampling rate, jitter, repeated timestamps, negative steps, and large gaps overall or by group.

Usage

assess_gazepoint_sampling_irregularity(
  data,
  time_col = NULL,
  group_cols = NULL,
  nominal_rate_hz = NULL,
  large_gap_factor = 3
)

Arguments

Value

Data frame with one row per group.

Description

Assigns sample-level gaze coordinates or fixation centroids to rectangular or polygonal areas of interest (AOIs). The original rows are preserved and augmented with an AOI label, match count, ambiguity flag, and assignment status.

Usage

assign_gazepoint_aoi(
  data,
  aois,
  x_col = NULL,
  y_col = NULL,
  aoi_label_col = "aoi",
  format = c("auto", "rectangle", "polygon"),
  aoi_id_col = NULL,
  data_match_cols = NULL,
  aoi_match_cols = data_match_cols,
  xmin_col = "xmin",
  xmax_col = "xmax",
  ymin_col = "ymin",
  ymax_col = "ymax",
  vertex_x_col = "vertex_x",
  vertex_y_col = "vertex_y",
  priority_col = NULL,
  overlap = c("priority", "first", "smallest", "all", "error"),
  boundary = c("inside", "outside"),
  output_col = "AOI",
  match_count_col = "aoi_match_count",
  ambiguous_col = "aoi_ambiguous",
  status_col = "aoi_assignment_status",
  all_separator = "|",
  overwrite = FALSE
)

Arguments

Details

Rectangular AOIs use one row per definition with minimum and maximum x and y coordinates. Polygon AOIs use long-format vertices, with one row per vertex and repeated AOI identifiers or labels.

Optional matching columns can restrict AOIs to particular trials, screens, media items, stimuli, or other recording contexts. Missing or blank values in AOI matching columns act as wildcards.

Supported assignment statuses are:

• "matched": exactly one AOI matched;

• "ambiguous_resolved": multiple AOIs matched and one was selected;

• "ambiguous_all": all matching labels were retained;

• "unmatched": valid coordinates did not fall within an eligible AOI;

• "invalid_coordinate": x or y was missing or non-finite.

Coordinate systems are not transformed. Gaze coordinates and AOI definitions must therefore use the same scale, orientation, and origin.

Value

A data frame with class "gazepoint_aoi_assignment". Attributes aoi_assignment_log, aoi_assignment_settings, and aoi_definitions contain structured provenance information.

See Also

summarize_gazepoint_fixations(), summarize_gazepoint_aoi_dwell(), summarise_gazepoint_aoi_biometrics()

Examples

gaze <- data.frame(
  gaze_x = c(0.1, 0.5, 0.9),
  gaze_y = c(0.5, 0.5, 0.5)
)

rectangles <- data.frame(
  aoi = c("left", "right"),
  xmin = c(0, 0.6),
  xmax = c(0.4, 1),
  ymin = c(0, 0),
  ymax = c(1, 1)
)

assign_gazepoint_aoi(
  gaze,
  rectangles,
  x_col = "gaze_x",
  y_col = "gaze_y"
)

Description

Flags short, long, non-finite, duplicate-time, and abrupt-change intervals in beat or inter-beat-interval data. The function is intended for quality control and audit reporting only. It does not remove beats, modify data, or make physiological, psychological, diagnostic, or clinical claims.

Usage

audit_gazepoint_beats(
  data,
  ibi_col = NULL,
  beat_time_col = NULL,
  group_cols = NULL,
  min_ibi = 300,
  max_ibi = 2000,
  duplicate_tolerance = 0,
  max_relative_change = NULL
)

Arguments

Value

A list with class gazepoint_beat_audit, containing beat-level flags, group summaries, and parameters.

Description

Summarises missingness and zero values for Gazepoint biometric columns. This is useful because Gazepoint exports may contain biometric columns even when a channel was inactive or invalid during recording.

Usage

audit_gazepoint_biometric_missingness(data, columns = NULL)

Arguments

Value

A data frame with one row per audited column.

Description

Audits timing or row-order information in Gazepoint Biometrics exports. The function checks monotonicity, duplicate timestamps, nonpositive intervals, and estimated sampling rate when the selected time column has a real time unit. If only CNT is available, the function can still check ordering but does not estimate a sampling rate unless time_unit is explicitly meaningful.

Usage

audit_gazepoint_biometric_sampling(
  data,
  group_columns = NULL,
  time_column = NULL,
  time_unit = c("seconds", "milliseconds", "microseconds", "samples"),
  expected_rate_hz = 60,
  tolerance_hz = 5
)

Arguments

Value

A data frame with one row per group.

Description

Combines time-order/reset diagnostics with conservative signal-lag summaries across signal pairs and groups. The helper is intended for quality control and synchronization review. It does not infer emotional valence, cognitive states, causal timing, or true physiological latency.

Usage

audit_gazepoint_biometric_sync_drift(
  data,
  time_col = NULL,
  group_cols = NULL,
  signal_pairs = NULL,
  signal_cols = NULL,
  reference_signal_col = NULL,
  max_lag = 1000,
  lag_step = NULL,
  drift_tolerance = NULL,
  method = c("pearson", "spearman"),
  min_complete_pairs = 20,
  use_first_difference = FALSE,
  include_reset_segments = TRUE
)

Arguments

Value

A list with overview, checks, time_reset_audit, lag_by_group, lag_profile, drift_summary, and settings.

Description

Provides a single front-door preflight audit for a Gazepoint-style biometric export. The audit standardizes column names when requested, reports likely modality availability, schema status, timestamp irregularity, missingness, duplicate rows, and reviewer-facing warnings.

Usage

audit_gazepoint_biometrics_file(
  path = NULL,
  data = NULL,
  expected_modalities = c("time", "eda", "ppg", "hr", "ibi", "pupil", "gaze", "events"),
  time_col = NULL,
  standardize = TRUE,
  include_data = FALSE,
  long_gap_s = NULL
)

## S3 method for class 'gazepoint_biometrics_audit'
print(x, ...)

## S3 method for class 'gazepoint_biometrics_audit'
summary(object, ...)

Arguments

Value

An object of class gazepoint_biometrics_audit.

Description

Summarise condition balance across participants and trials before modelling, event-window summaries, or two-condition time-course workflows.

Usage

audit_gazepoint_condition_balance(
  data,
  participant_col,
  condition_col,
  trial_col = NULL,
  expected_conditions = NULL
)

Arguments

Value

A list with class "gazepoint_condition_balance_audit".

Description

Checks a dataset or export folder for expected directories, files, filename patterns, duplicate names, empty files, and optional sidecar coverage. This is a lightweight structure audit, not a full BIDS validator or converter.

Usage

audit_gazepoint_dataset_structure(
  root,
  expected_dirs = NULL,
  expected_files = NULL,
  expected_patterns = NULL,
  allowed_extensions = c("csv", "tsv", "txt", "json", "xlsx", "rds"),
  require_sidecars = FALSE,
  recursive = TRUE,
  include_hidden = FALSE
)

Arguments

Value

A list with class gazepoint_dataset_structure_audit.

Description

Compares signal distributions across sessions/blocks using baseline-vs-current differences, Kolmogorov-Smirnov tests, and Population Stability Index (PSI).

Usage

audit_gazepoint_distributional_drift(
  dat,
  signal_cols,
  session_col = "session",
  participant_col = NULL,
  reference_session = NULL,
  bins = 10,
  psi_warn = 0.1,
  psi_fail = 0.25
)

Arguments

Value

A list with overview, drift_summary, and settings.

Description

Flags row-level artifacts in Gazepoint electrodermal activity signals, preferring GSR_US conductance when available. The helper detects abrupt jumps, abrupt slopes, flatline runs, zero runs, negative conductance values, and optional out-of-range values. It is a conservative preprocessing/QC helper and does not interpret EDA as emotional valence.

Usage

audit_gazepoint_eda_artifacts(
  data,
  signal_col = NULL,
  time_col = NULL,
  group_cols = NULL,
  prefer_gsr_us = TRUE,
  jump_threshold_sd = 6,
  slope_threshold_sd = 6,
  flat_run_length = 20,
  zero_run_length = 20,
  saturation_min = NULL,
  saturation_max = NULL,
  negative_allowed = NULL
)

Arguments

Value

A list with overview, row_flags, artifact_runs, group_summary, and settings.

Description

Audits Gazepoint engagement-dial values for missingness, inactive rows, validity flags, plausible range, flatlining, and usable sample coverage.

Usage

audit_gazepoint_engagement_dial(
  data,
  value_column = "DIAL",
  validity_column = "DIALV",
  min_value = 0,
  max_value = 1,
  jump_threshold = NULL
)

Arguments

Value

A one-row data frame summarising signal quality.

Description

Check whether expected events, TTL markers, AOI events, or task events are present across participant/trial/condition units.

Usage

audit_gazepoint_event_coverage(
  data,
  event_col,
  participant_col = NULL,
  trial_col = NULL,
  condition_col = NULL,
  expected_events = NULL,
  unit_cols = NULL
)

Arguments

Value

A list with class "gazepoint_event_coverage_audit".

Description

Check whether an imported or prepared Gazepoint workflow table contains the expected participant, trial, condition, and optional session structure before modelling, event-locking, or time-course analysis.

Usage

audit_gazepoint_experiment_design(
  data,
  participant_col,
  trial_col = NULL,
  condition_col = NULL,
  session_col = NULL,
  expected_conditions = NULL,
  min_trials_per_condition = 1L
)

Arguments

Value

A list with class "gazepoint_experiment_design_audit".

Examples

dat <- data.frame(
  participant = rep(paste0("P", 1:4), each = 4),
  trial = rep(1:4, times = 4),
  condition = rep(c("A", "B"), times = 8)
)

audit_gazepoint_experiment_design(
  dat,
  participant_col = "participant",
  trial_col = "trial",
  condition_col = "condition",
  expected_conditions = c("A", "B")
)

Description

Reports whether expected Gazepoint-style roles are present, missing, or ambiguous, using the same alias dictionary as standardize_gazepoint_column_names().

Usage

audit_gazepoint_export_schema(
  data,
  expected_roles = NULL,
  dictionary = NULL,
  strict = FALSE
)

Arguments

Value

Data frame with one row per expected role.

Description

Audits Gazepoint GSR/EDA columns for missingness, inactive zero rows, validity flags, plausible value ranges, flatlining, and usable sample coverage. When available, GSR_US is used by default because it represents skin conductance in microsiemens in Gazepoint exports.

Usage

audit_gazepoint_gsr_quality(
  data,
  value_column = NULL,
  validity_column = "GSRV",
  min_value = 0,
  max_value = 100,
  jump_threshold = NULL
)

Arguments

Value

A one-row data frame summarising signal quality.

Description

Checks whether a Gazepoint GSR/EDA column looks more like conductance in microSiemens or resistance/impedance-like values in Ohms. This is a preprocessing safety audit, not a definitive device calibration test.

Usage

audit_gazepoint_gsr_units(
  dat,
  gsr_col = "GSR",
  convert = FALSE,
  output_col = NULL,
  resistance_to_us_factor = 1e+06
)

Arguments

Value

A list with overview, diagnostics, recommendation, and, when requested, data.

Description

Audits Gazepoint heart-rate values for missingness, inactive zero rows, validity flags, plausible value ranges, sudden jumps, flatlining, and usable sample coverage. HRV is treated as the heart-rate validity flag, not as a heart-rate-variability metric.

Usage

audit_gazepoint_hr_quality(
  data,
  value_column = "HR",
  validity_column = "HRV",
  min_value = 30,
  max_value = 220,
  jump_threshold = 25
)

Arguments

Value

A one-row data frame summarising signal quality.

Description

Audits inter-beat interval (IBI) or RR-interval values in Gazepoint Biometrics-style exports. This helper deliberately does not use raw HRV columns as HRV metrics. HRV-style summaries should be derived only from genuine IBI/RR interval columns.

Usage

audit_gazepoint_ibi_quality(
  data,
  ibi_col = NULL,
  group_cols = NULL,
  time_col = NULL,
  unit = c("auto", "milliseconds", "seconds"),
  min_ibi_ms = 300,
  max_ibi_ms = 2000,
  max_jump_ms = 500
)

Arguments

Value

A list with overview, samples, group_summary, and settings.

Examples

df <- data.frame(
  USER = rep(c("P1", "P2"), each = 4),
  IBI = c(800, 810, 790, 805, 900, 910, 905, 920)
)
audit_gazepoint_ibi_quality(df, group_cols = "USER")

Description

Checks whether declared bridge functions are exported and records the installed versions of optional R and Python dependencies. Missing optional dependencies are recorded for review rather than treated as core-package failures.

Usage

audit_gazepoint_interoperability_versions(
  manifest = gazepoint_interoperability_manifest(),
  include_python = TRUE,
  strict = FALSE
)

Arguments

Details

Python package versions are queried through importlib.metadata; target modules are not imported merely to determine their versions.

Value

An object of class "gazepoint_interoperability_audit" containing:

• results: target-level compatibility findings;

• summary: aggregate pass and review counts;

• session: R, Python, operating-system, package, and timestamp metadata;

• manifest: the manifest used for the audit.

Examples

audit <- audit_gazepoint_interoperability_versions(
  include_python = FALSE
)
audit$summary

Description

Checks a pipeline map for missing expected steps, duplicate step identifiers, edge references to missing nodes, and simple ordering violations. The audit is descriptive and does not evaluate whether a scientific analysis is valid.

Usage

audit_gazepoint_pipeline_steps(
  pipeline,
  expected_steps = NULL,
  required_order = NULL,
  allow_extra = TRUE
)

Arguments

Value

A list with class gazepoint_pipeline_audit.

Description

Checks whether a preregistration checklist has corresponding evidence objects and whether those evidence objects contain expected fields. The audit is a documentation-readiness check only; it does not judge study quality or perform automatic exclusion.

Usage

audit_gazepoint_preregistration_consistency(
  checklist = NULL,
  evidence = list(),
  require_required_fields = TRUE
)

Arguments

Value

A list with class gazepoint_preregistration_audit.

Description

Computes correlations between pupil size and luminance/brightness and flags groups where the absolute association exceeds a threshold.

Usage

audit_gazepoint_pupil_luminance(
  data,
  pupil_col = NULL,
  luminance_col = NULL,
  group_cols = NULL,
  threshold = 0.3,
  method = c("pearson", "spearman")
)

Arguments

Value

Data frame with correlation and flag columns.

Description

Performs conservative package-level checks for release preparation. The audit inspects package files, exported functions, manual pages, tests, pkgdown reference pages, vignettes/articles, and optional roadmap terms. It does not inspect participant-level data and does not make biometric, psychological, clinical, or diagnostic interpretations.

Usage

audit_gazepoint_release_readiness(
  path = ".",
  required_files = c("DESCRIPTION", "NAMESPACE", "R", "man", "tests/testthat",
    "_pkgdown.yml"),
  expected_exports = NULL,
  roadmap_terms = NULL,
  require_pkgdown = TRUE
)

Arguments

Value

A list with checks, overview, exports, feature coverage, release checklist, and settings. The object has class gazepoint_release_readiness_audit.

Description

Aggregates selected QC metrics by session, participant, trial, or another grouping unit, then flags unusual values using transparent z-score and/or IQR rules. The function is intended for audit reporting only and does not imply automatic exclusion.

Usage

audit_gazepoint_session_comparability(
  data,
  metric_cols,
  group_cols = NULL,
  method = c("both", "z", "iqr"),
  z_threshold = 2,
  iqr_multiplier = 1.5
)

Arguments

Value

A list with class gazepoint_session_comparability_audit.

Description

Screens biometric signal columns for missingness, all-zero channels, constant values, low variation, and active signal presence within groups. This helper is designed to identify inactive files or channels before event-level EDA, HR, IBI, or multimodal analysis.

Usage

audit_gazepoint_signal_activity(
  data,
  signal_cols = NULL,
  group_cols = NULL,
  zero_is_inactive = TRUE,
  min_unique_nonzero = 2,
  missing_as_inactive = TRUE
)

Arguments

Value

A list with overview, signal_by_group, inactive_groups, inactive_signals, and settings.

Description

Checks that a smoke-test result contains no private paths, source filenames, participant-level identifier columns, or retained raw workflow objects.

Usage

audit_gazepoint_smoke_privacy(x, private_values = NULL)

Arguments

Value

A data frame of privacy checks and pass/fail statuses.

Description

Flags or removes the initial stabilization period in each recording/group. This is intended to prevent early skin-electrode drift from being treated as a stable physiological baseline.

Usage

audit_gazepoint_stabilization_period(
  dat,
  time_col = "CNT",
  group_cols = NULL,
  stabilization_minutes = 10,
  action = c("flag", "trim"),
  output_col = "in_stabilization_period",
  time_units = c("auto", "seconds", "milliseconds")
)

Arguments

Value

A data frame with stabilization-period attributes.

Description

Detects negative time steps, duplicate time steps, non-finite time values, and recording segments within grouped Gazepoint biometric exports. This helper is intended for quality control and synchronization inspection. It does not alter raw values unless return_reindexed_time = TRUE, in which case an additional segment-relative time column is added.

Usage

audit_gazepoint_time_resets(
  data,
  time_col = NULL,
  group_cols = NULL,
  allow_ties = TRUE,
  split_on_negative_step = TRUE,
  return_reindexed_time = FALSE,
  min_segment_rows = 1
)

Arguments

Value

A list with overview, segment_summary, row_flags, data_with_segments, and settings.

Description

Checks whether a time-course data set has a complete participant by condition by time grid. This is intended as a safety diagnostic before calling run_gazepoint_cluster_permutation().

Usage

audit_gazepoint_timecourse_grid(
  data,
  subject,
  condition,
  time,
  value = NULL,
  max_report_cells = 1000L
)

Arguments

Value

An object of class gazepoint_timecourse_grid_audit.

Description

Adds a baseline-corrected GSR/EDA column to a Gazepoint Biometrics table. When available, GSR_US is used by default because it represents skin conductance in microsiemens in Gazepoint exports. The baseline is estimated from rows selected by baseline_rows, optionally within groups.

Usage

baseline_correct_gazepoint_gsr(
  data,
  baseline_rows,
  value_column = NULL,
  validity_column = "GSRV",
  group_columns = NULL,
  output_column = NULL,
  summary = c("mean", "median"),
  exclude_zero = TRUE
)

Arguments

Value

A data frame with the added baseline-corrected column and a baseline-summary attribute named "baseline_summary".

Description

Adds a baseline-corrected heart-rate column to a Gazepoint Biometrics table. HRV is treated as the heart-rate validity flag, not as a heart-rate variability metric.

Usage

baseline_correct_gazepoint_hr(
  data,
  baseline_rows,
  value_column = "HR",
  validity_column = "HRV",
  group_columns = NULL,
  output_column = NULL,
  summary = c("mean", "median"),
  exclude_zero = TRUE
)

Arguments

Value

A data frame with the added baseline-corrected column and a baseline-summary attribute named "baseline_summary".

Description

Applies subtractive or divisive baseline correction to pupil-size data within trials or other grouping units.

Usage

baseline_correct_gazepoint_pupil(
  dat,
  pupil_col = NULL,
  time_col = "CNT",
  stimulus_onset_col = NULL,
  trial_cols = NULL,
  baseline_window = c(-240, -200),
  baseline_function = c("median", "mean"),
  correction = c("subtract", "divide"),
  suffix = "_baseline_corrected",
  min_baseline_rows = 2,
  overwrite = FALSE
)

Arguments

Value

A data frame with a corrected pupil column and baseline attributes.

Description

Converts gaze or fixation samples into binned AOI proportions by participant, trial, condition, or other grouping columns. AOIs can be supplied as labels or derived from rectangular AOI definitions.

Usage

build_gazepoint_aoi_timecourse(
  data,
  time_col = NULL,
  aoi_col = NULL,
  x_col = NULL,
  y_col = NULL,
  aoi_definitions = NULL,
  group_cols = NULL,
  bin_width_s = 0.1,
  valid_col = NULL,
  include_empty = TRUE
)

Arguments

Value

Tidy AOI time-course data frame.

Description

Calculates dependency-light RSA proxy summaries from IBI/RR intervals and, optionally, PPG-derived respiration features from extract_gazepoint_pdr_signals(). This provides peak-to-trough and Porges-Bohrer-inspired band-power proxy summaries. These outputs should be interpreted as respiration-informed HRV/RSA features, not direct clinical vagal-tone estimates.

Usage

calculate_gazepoint_rsa(
  dat,
  ibi_col = "IBI",
  time_col = "CNT",
  group_cols = NULL,
  pdr = NULL,
  resp_rate_hz = NULL,
  respiration_band = c(0.12, 0.4),
  resample_rate = 4
)

Arguments

Value

A list with overview, rsa_summary, and settings.

Description

Performs a conservative, Gazepoint-oriented audit of a dataset folder that follows, or approximately follows, a BIDS-like organization. This function is not a full BIDS validator and does not convert data. It checks only simple, reviewable layout features such as dataset-level metadata files, subject folders, Gazepoint-like export files, and optional JSON sidecars.

Usage

check_gazepoint_bids(
  root,
  subject_pattern = "^sub-[A-Za-z0-9]+$",
  recursive = TRUE,
  expected_files = c("dataset_description.json", "participants.tsv"),
  gazepoint_patterns = c("all[_-]?gaze", "fixation", "summary", "biometric", "eda",
    "gsr", "ecg", "ppg", "hr", "ibi")
)

Arguments

Value

A list with class gazepoint_bids_layout_audit containing the root path, check table, discovered files, and summary counts.

Description

Checks whether a data frame contains known Gazepoint Biometrics columns. This function does not assume that the channels are active. It only checks whether the expected columns are present.

Usage

check_gazepoint_biometric_columns(data)

Arguments

Value

A data frame describing expected columns, their signal family, interpretation, and whether they are present.

Description

Checks whether an object follows the package's plotting return convention.

Usage

check_gazepoint_plot_contract(
  plot,
  require_plot_data = TRUE,
  require_settings = TRUE
)

Arguments

Value

A list with overview, checks, plot_data, and settings.

Description

Check binary quality of Gazepoint pulse/PPG analysis results

Usage

check_gazepoint_ppg_binary_quality(
  measures = NULL,
  peaks = NULL,
  min_peaks = 5L,
  bpm_range = c(40, 180),
  max_missing_prop = 0.25
)

Arguments

Value

Data frame with binary quality status.

Description

Check whether NN intervals are inside a plausible interval

Usage

check_gazepoint_pyhrv_interval(nni_ms, min_ms = 250, max_ms = 2500)

Arguments

Value

Data frame with interval status.

Description

Adds programmatic fixed-duration chunks/episodes to continuous biometric data. This is useful for baseline segmentation, repeated-measures feature extraction, and analyses that do not rely on external TTL markers.

Usage

chunk_gazepoint_biometrics(
  dat,
  time_col = "CNT",
  group_cols = NULL,
  chunk_seconds = 60,
  start_time = NULL,
  chunk_col = "chunk_id",
  episode_col = "episode_id",
  include_partial = FALSE
)

Arguments

Value

A data frame with chunk columns and chunk-summary attributes.

Description

Classifies descriptive EDA response patterns from an EDA/SCR feature column. The labels are intended for quality-control and descriptive reporting only. They do not infer emotion, valence, stress, trust, preference, cognition, or diagnosis.

Usage

classify_gazepoint_eda_response_pattern(
  data,
  response_col = NULL,
  group_cols = NULL,
  summary_function = c("max_abs", "mean_abs", "median_abs"),
  no_response_threshold = 0.01,
  low_response_threshold = 0.05,
  moderate_response_threshold = 0.2
)

Arguments

Value

A list with overview, classifications, and settings.

Description

Classifies extracted SCRs into first-, second-, and third-interval response windows based on response latency after stimulus onset.

Usage

classify_gazepoint_scr_intervals(
  dat,
  response_time_col = NULL,
  stimulus_onset_col = NULL,
  latency_col = NULL,
  output_col = "scr_interval",
  latency_output_col = "scr_latency_s",
  fir = c(1, 4),
  sir = c(4, 7),
  tir = c(7, 10)
)

Arguments

Value

A data frame with interval labels and latency metadata.

Description

Applies user-visible threshold rules to a signal-quality table. The function adds review labels and failing-rule descriptions. It does not remove data.

Usage

classify_gazepoint_signal_quality(quality, rules = NULL)

Arguments

Value

A data frame with class gazepoint_signal_quality_classification.

Description

Compatibility helper for users searching for a short pupil-cleaning function. By default it applies transparent blink/dropout interpolation using interpolate_gazepoint_pupil_blinks(). Set prefer_existing = TRUE to delegate to clean_gazepoint_pupil_signal() when compatible with the supplied arguments.

Usage

clean_gazepoint_pupil(
  data,
  pupil_cols = NULL,
  time_col = NULL,
  blink_col = NULL,
  max_gap_s = NULL,
  method = c("linear", "constant"),
  suffix = "_clean",
  prefer_existing = FALSE,
  ...
)

Arguments

Value

Data frame with cleaned pupil columns and interpolation flags.

Description

Flags blink samples, non-positive pupil values, and robust outlier spikes, then interpolates short missing segments. The function returns the original data with cleaned pupil columns and provenance flags.

Usage

clean_gazepoint_pupil_signal(
  data,
  pupil_cols = NULL,
  time_col = NULL,
  group_cols = NULL,
  validity_cols = NULL,
  method = c("linear", "locf", "nocb", "nearest", "constant"),
  max_gap = Inf,
  spike_mad = 6,
  combine = c("all", "any"),
  min_blink_samples = 1L,
  suffix = "_clean",
  keep_flags = TRUE
)

Arguments

Value

Data frame with cleaned pupil columns and a pupil_cleaning_summary attribute.

Examples

dat <- data.frame(time_s = 0:4, LPD = c(3, NA, 3.2, 40, 3.1))
clean_gazepoint_pupil_signal(dat, pupil_cols = "LPD", time_col = "time_s")

Description

Clean RR or IBI intervals using HeartPy-style methods

Usage

clean_gazepoint_rr_intervals(
  rr_ms,
  method = c("quotient", "iqr", "modified_z", "zscore", "none"),
  group_col = "group",
  quotient_threshold = 0.2,
  iqr_multiplier = 1.5,
  z_threshold = 3.5
)

Arguments

Value

Cleaned interval table, or cleaned peak table when a peak table is supplied.

Description

Combine multiple Gazepoint marker channels PsPM-style

Usage

combine_gazepoint_marker_channels_pspm_style(
  data,
  marker_cols = NULL,
  time_col = NULL,
  sampling_rate_hz = NULL,
  group_cols = NULL,
  combined_col = "pspm_marker"
)

Arguments

Value

List with combined data and marker table.

Description

Compares two conditions using a transparent percentile bootstrap. The helper is intended for trial-level, participant-level, or event-locked summaries produced by gpbiometrics. When participant_col is supplied, observations are first averaged at the participant-by-condition level to reduce pseudo-replication. When paired = TRUE, only participants with both conditions are retained and resampled as paired units.

Usage

compare_gazepoint_conditions_bootstrap(
  data,
  outcome_col,
  condition_col,
  participant_col = NULL,
  condition_levels = NULL,
  paired = FALSE,
  by_cols = NULL,
  statistic = c("mean_difference", "median_difference", "standardized_mean_difference"),
  n_boot = 2000,
  conf_level = 0.95,
  seed = NULL,
  na_rm = TRUE
)

Arguments

Value

Object of class gazepoint_bootstrap_condition_comparison, stored as a data frame. Bootstrap samples are stored in the bootstrap_samples attribute.

Description

Compare two or more objects created by profile_gazepoint_export_folder(). The comparison reports folder-level dimensions and column-role coverage across profiles.

Usage

compare_gazepoint_export_profiles(..., labels = NULL)

Arguments

Value

A list with class "gazepoint_export_profile_comparison".

Description

Compares recorded HR against HR derived from genuine IBI/RR intervals using 60000 / IBI_ms.

Usage

compare_gazepoint_hr_ibi_consistency(
  data,
  hr_col = "HR",
  ibi_col = "IBI",
  time_col = NULL,
  group_cols = NULL,
  unit = c("auto", "ms", "seconds"),
  max_abs_diff_bpm = 10,
  max_rel_diff_prop = 0.15
)

Arguments

Value

A list with overview, row_diagnostics, group_summary, and settings.

Description

Compare pyHRV-style PSD methods

Usage

compare_gazepoint_pyhrv_psd_methods(
  nni_ms,
  time_s = NULL,
  methods = c("welch", "lomb", "ar"),
  plot = FALSE
)

Arguments

Value

List with method outputs and combined measures.

Description

Computes ICC(A,1), Lin's concordance correlation coefficient, and Bland-Altman bias/95% limits. Agreement is deliberately scoped to the supplied metric and acquisition configuration; it is not a global ECG/PPG equivalence decision.

Usage

compare_hrv_prv_devices(
  reference,
  candidate,
  metric,
  reference_source = "ECG-HRV",
  candidate_source = "PPG-PRV",
  reference_site = NA_character_,
  candidate_site = NA_character_
)

Arguments

Value

A metric-specific agreement record.

Description

Summarizes a continuous engagement-dial signal, typically scaled from 0 to 100, into interpretable behavioral indices such as mean engagement, percent time above threshold, volatility, and area under the curve.

Usage

compute_gazepoint_engagement_index(
  dial,
  time = NULL,
  threshold = 50,
  group = NULL,
  return = c("data", "scalar")
)

Arguments

Value

Data frame of engagement metrics or a scalar.

Examples

compute_gazepoint_engagement_index(c(20, 60, 80), time = 1:3)

Description

Computes a conservative Haar-style multiscale power summary for RR/NN intervals. This is intended as a lightweight, CRAN-safe exploratory nonstationary-HRV helper, not as a replacement for specialist HRV packages.

Usage

compute_gazepoint_hrv_wavelet_psd(
  rr_intervals,
  time = NULL,
  bands = list(vlf = c(0.0033, 0.04), lf = c(0.04, 0.15), hf = c(0.15, 0.4)),
  max_scale = NULL
)

Arguments

Value

List with psd, band_power, and settings.

Description

Compute Gazepoint pulse/PPG frequency-domain measures

Usage

compute_gazepoint_ppg_frequency_measures(
  peaks = NULL,
  rr_ms = NULL,
  rr_time_s = NULL,
  group_col = "group",
  method = c("welch", "fft", "periodogram"),
  resample_hz = 4,
  bands = list(lf = c(0.05, 0.15), hf = c(0.15, 0.5)),
  welch_window_seconds = 64,
  welch_overlap = 0.5
)

Arguments

Value

Data frame of frequency-domain measures.

Description

Compute HeartPy-style pulse/PPG measures

Usage

compute_gazepoint_ppg_measures(peaks, group_col = "group")

Arguments

Value

Data frame with BPM, IBI, SDNN, SDSD, RMSSD, pNN20, pNN50, MAD, LF, HF, HF/LF, and breathing rate.

Description

Extracts peak-centered PPG windows, builds a median beat template, and computes per-beat correlation with the template as an interpretable quality metric.

Usage

compute_gazepoint_ppg_template_similarity(
  data,
  time_col = NULL,
  ppg_col = NULL,
  peaks = NULL,
  window_s = c(-0.25, 0.45),
  sampling_rate_hz = NULL,
  n_grid = 101,
  similarity_threshold = 0.8
)

Arguments

Value

List with beats, template, summary, and settings.

Description

Compute pyHRV-style autoregressive PSD

Usage

compute_gazepoint_pyhrv_ar_psd(
  nni_ms,
  time_s = NULL,
  resample_hz = 4,
  order = NULL
)

Arguments

Value

List with PSD and measures.

Description

Compute detrended fluctuation analysis

Usage

compute_gazepoint_pyhrv_dfa(
  nni_ms,
  scales = unique(round(exp(seq(log(4), log(64), length.out = 12))))
)

Arguments

Value

Data frame with DFA alpha estimates.

Description

Compute pyHRV-style frequency-domain summary

Usage

compute_gazepoint_pyhrv_frequency_domain(
  nni_ms,
  time_s = NULL,
  method = c("welch", "lomb", "ar")
)

Arguments

Value

List with PSD and measures.

Description

Compute heart rate from NN intervals

Usage

compute_gazepoint_pyhrv_heart_rate(nni_ms)

Arguments

Value

Numeric heart rate in beats per minute.

Description

Compute pyHRV-style heart-rate parameters

Usage

compute_gazepoint_pyhrv_hr_parameters(nni_ms)

Arguments

Value

Data frame of heart-rate parameters.

Description

Compute pyHRV-style Lomb PSD

Usage

compute_gazepoint_pyhrv_lomb_psd(
  nni_ms,
  time_s = NULL,
  min_hz = 0.003,
  max_hz = 0.4,
  n_freq = 512
)

Arguments

Value

List with PSD and measures.

Description

Compute NN interval differences

Usage

compute_gazepoint_pyhrv_nn_diff(nni_ms, absolute = FALSE)

Arguments

Value

Numeric successive NN differences in milliseconds.

Description

Compute NN20 and pNN20

Usage

compute_gazepoint_pyhrv_nn20(nni_ms)

Arguments

Value

Data frame with NN20 and pNN20.

Description

Compute NN50 and pNN50

Usage

compute_gazepoint_pyhrv_nn50(nni_ms)

Arguments

Value

Data frame with NN50 and pNN50.

Description

Compute pyHRV-style NNI difference parameters

Usage

compute_gazepoint_pyhrv_nni_differences_parameters(nni_ms)

Arguments

Value

Data frame of successive-difference parameters.

Description

Compute pyHRV-style NNI parameters

Usage

compute_gazepoint_pyhrv_nni_parameters(nni_ms)

Arguments

Value

Data frame of NNI parameters.

Description

Compute NNxx and pNNxx

Usage

compute_gazepoint_pyhrv_nnxx(nni_ms, threshold_ms = 50)

Arguments

Value

Data frame with NNxx and pNNxx.

Description

Compute pyHRV-style nonlinear summary

Usage

compute_gazepoint_pyhrv_nonlinear(nni_ms)

Arguments

Value

Data frame with nonlinear measures.

Description

Compute pyHRV-style Poincare measures

Usage

compute_gazepoint_pyhrv_poincare(nni_ms, plot = FALSE)

Arguments

Value

Data frame of Poincare measures.

Description

Compute pyHRV-style PSD waterfall over segments

Usage

compute_gazepoint_pyhrv_psd_waterfall(
  nni_ms,
  segment_seconds = 300,
  method = c("welch", "lomb", "ar"),
  plot = FALSE
)

Arguments

Value

List with PSD grid and segment measures.

Description

Compute RMSSD

Usage

compute_gazepoint_pyhrv_rmssd(nni_ms)

Arguments

Value

RMSSD in milliseconds.

Description

Compute sample entropy

Usage

compute_gazepoint_pyhrv_sample_entropy(nni_ms, m = 2L, r = NULL)

Arguments

Value

Sample entropy.

Description

Compute SDANN

Usage

compute_gazepoint_pyhrv_sdann(nni_ms, segment_seconds = 300)

Arguments

Value

SDANN in milliseconds.

Description

Compute SDNN

Usage

compute_gazepoint_pyhrv_sdnn(nni_ms)

Arguments

Value

SDNN in milliseconds.

Description

Compute SDNN index

Usage

compute_gazepoint_pyhrv_sdnn_index(nni_ms, segment_seconds = 300)

Arguments

Value

SDNN index in milliseconds.

Description

Compute SDSD

Usage

compute_gazepoint_pyhrv_sdsd(nni_ms)

Arguments

Value

SDSD in milliseconds.

Description

Compute pyHRV-style time-domain summary

Usage

compute_gazepoint_pyhrv_time_domain(nni_ms, segment_seconds = 300)

Arguments

Value

Data frame with time-domain HRV measures.

Description

Compute TINN

Usage

compute_gazepoint_pyhrv_tinn(nni_ms, bin_width_ms = 7.8125)

Arguments

Value

Approximate TINN in milliseconds.

Description

Compute triangular index

Usage

compute_gazepoint_pyhrv_triangular_index(nni_ms, bin_width_ms = 7.8125)

Arguments

Value

HRV triangular index.

Description

Compute pyHRV-style Welch PSD

Usage

compute_gazepoint_pyhrv_welch_psd(
  nni_ms,
  time_s = NULL,
  resample_hz = 4,
  window_seconds = 256,
  overlap = 0.5
)

Arguments

Value

List with PSD and measures.

Description

Combines user-selected numeric QC metrics into a transparent row-level heuristic quality index. Metrics are range-scaled by default and combined using user-supplied directions and weights. The result is intended for quality-control summaries only. It does not remove data and does not make physiological, psychological, diagnostic, or clinical claims.

Usage

compute_gazepoint_quality_index(
  data,
  metric_cols,
  directions = NULL,
  weights = NULL,
  index_col = "quality_index",
  component_prefix = "quality_component_",
  overwrite = FALSE
)

Arguments

Value

A data frame with class gazepoint_quality_index.

Description

Estimates habituation of SCR amplitudes across ordered trials, either for a vector or within subjects/groups in a data frame.

Usage

compute_gazepoint_scr_habituation(
  data,
  amplitude_col = NULL,
  trial_col = NULL,
  subject_col = NULL,
  method = c("linear", "log_linear", "ratio"),
  min_trials = 3
)

Arguments

Value

Data frame with habituation slope, p value, correlation, and first/last response summaries.

Description

Estimates onset latency, peak latency, peak amplitude, AUC, and half-recovery latency for each event using a baseline window and response window.

Usage

compute_gazepoint_scr_latency(
  data,
  events,
  time_col = NULL,
  eda_col = NULL,
  event_time_col = NULL,
  event_id_col = NULL,
  group_cols = NULL,
  baseline_window_s = c(-1, 0),
  response_window_s = c(0, 5),
  onset_threshold = 0.01,
  recovery_fraction = 0.5
)

Arguments

Value

Data frame with one row per event.

Description

Compute signal band power

Usage

compute_gazepoint_signal_band_power(
  x,
  sampling_rate_hz = NULL,
  bands = list(very_low = c(0.003, 0.04), low = c(0.04, 0.15), high = c(0.15, 0.4)),
  relative = TRUE
)

Arguments

Value

Data frame of band powers.

Description

Compute correlation between two Gazepoint signals

Usage

compute_gazepoint_signal_correlation(
  x,
  y,
  method = c("pearson", "spearman", "kendall"),
  lag_max = NULL
)

Arguments

Value

Correlation summary.

Description

Computes pairwise lag/correlation summaries across synchronized numeric signals. The output is useful as a compact multimodal lag screen before event-locked or mixed-model analyses.

Usage

compute_gazepoint_signal_lag_matrix(
  data,
  signal_cols = NULL,
  time_col = NULL,
  group_cols = NULL,
  max_lag_s = 2,
  lag_step_s = NULL,
  min_overlap = 10
)

Arguments

Value

Data frame with one row per group and signal pair.

Description

Compute phase-locking value between two signals

Usage

compute_gazepoint_signal_phase_locking(x, y, sampling_rate_hz, band = NULL)

Arguments

Value

Data frame with phase-locking value and circular phase difference.

Description

Compute signal power spectrum

Usage

compute_gazepoint_signal_power_spectrum(x, sampling_rate_hz, detrend = TRUE)