Package {gpbiometrics}

gpbiometrics: Process, Audit, Plot, and Report Gazepoint Biometrics Data

Description

gpbiometrics provides helper functions for importing, checking, preprocessing, summarising, diagnosing, plotting, and reporting Gazepoint Biometrics exports. It is designed for reproducible offline workflows involving physiological, response-channel, event-marker, and timing data exported alongside Gazepoint eye-tracking recordings.

Details

The package supports common Gazepoint biometric channels, including GSR/EDA, heart rate, interbeat interval or RR-style intervals, engagement dial, and TTL markers. It provides functions for folder-level import, data-summary import, schema and timebase detection, active-channel detection, column validation, missingness audits, signal-quality audits, sampling and timing audits, dropout and flatline flagging, baseline correction, smoothing, window summaries, TTL event extraction, biometric-to-gaze synchronisation, exclusion recommendations, workflow diagnostics, report-ready tables, cautious methods text, lightweight report generation, and base-R diagnostic plotting.

Schema and timing helpers include standardise_gazepoint_biometric_names(), detect_gazepoint_biometric_schema(), detect_gazepoint_time_columns(), and detect_gazepoint_biometric_timebase(). Signal-availability and quality helpers include summarise_gazepoint_biometric_validity(), flag_gazepoint_biometric_dropouts(), audit_gazepoint_gsr_quality(), audit_gazepoint_hr_quality(), audit_gazepoint_engagement_dial(), and audit_gazepoint_ibi_quality().

Preprocessing and summary helpers include baseline_correct_gazepoint_gsr(), baseline_correct_gazepoint_hr(), smooth_gazepoint_biometrics(), convert_gazepoint_gsr_to_conductance(), summarise_gazepoint_gsr_windows(), summarise_gazepoint_hr_windows(), summarise_gazepoint_engagement_windows(), summarise_gazepoint_dial_windows(), summarise_gazepoint_ibi_windows(), summarise_gazepoint_gsr_tonic_phasic(), summarise_gazepoint_multimodal_windows(), summarise_gazepoint_ibi_hrv_windows(), and summarise_gazepoint_full_biometric_windows().

Synchronisation, modelling, workflow, and reporting helpers include sync_gazepoint_biometrics_with_gaze(), join_gazepoint_biometrics_to_master(), join_gazepoint_biometrics_to_gp3tools(), prepare_gazepoint_multimodal_model_data(), run_gazepoint_biometrics_workflow(), summarise_gazepoint_biometrics_workflow(), diagnose_gazepoint_biometrics_workflow(), create_gazepoint_biometrics_checklist(), create_gazepoint_biometrics_methods_text(), create_gazepoint_biometrics_report_tables(), write_gazepoint_biometrics_report_tables(), and create_gazepoint_biometrics_report(). Diagnostic plotting helpers include plot_gazepoint_biometric_signals() and plot_gazepoint_biometric_quality().

The package treats biometric signals conservatively. GSR/EDA is handled as an electrodermal activity or arousal-related signal rather than emotional valence. Heart-rate summaries should be interpreted relative to baseline, artefact handling, and task context. Raw Gazepoint HRV columns should be treated as validity or vendor flags unless independent documentation proves otherwise. IBI-derived HRV-style summaries should be computed only from genuine interbeat interval or RR-style interval columns. Eye-tracking measures, when combined with biometric data, should be interpreted as indicators of visual attention rather than direct evidence of cognition, scrutiny, or evaluation.

Main workflow

The main workflow function is:

run_gazepoint_biometrics_workflow()

Useful follow-up helpers include:

summarise_gazepoint_biometrics_workflow(), diagnose_gazepoint_biometrics_workflow(), create_gazepoint_biometrics_report_tables(), write_gazepoint_biometrics_report_tables(), and create_gazepoint_biometrics_report().

Interpretation caution

gpbiometrics is a preprocessing, quality-control, visualisation, and reporting toolkit. It does not classify emotions, mental states, or cognitive processes directly. Researchers should interpret biometric signals in relation to experimental design, baseline periods, stimulus timing, task demands, artefact handling, and complementary behavioural or self-report measures.

Author(s)

Maintainer: Stefanos Balaskas s.balaskas@ac.upatras.gr

Authors:

• Stefanos Balaskas s.balaskas@ac.upatras.gr

See Also

Useful links:

• https://github.com/stefanosbalaskas/gpbiometrics

• https://stefanosbalaskas.github.io/gpbiometrics/

• Report bugs at https://github.com/stefanosbalaskas/gpbiometrics/issues

Add a decision to a Gazepoint analysis decision log

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.

Align Gazepoint biometric samples to TTL events

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.

Align two Gazepoint streams using matched event markers

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.

Align Gazepoint timestamps to an EEG clock

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.

Analyse AC EDA admittance and susceptance recordings

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.

Analyse cardiorespiratory Granger-style directionality

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.

Analyse endosomatic skin-potential recordings

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.

Pseudonymize participant or record identifiers

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.

Assert that required Gazepoint columns are present

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

Assess Gazepoint HRP waveform quality

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.

Assess sampling irregularity in Gazepoint time series

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.

Assign Gazepoint coordinates to areas of interest

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

Audit beat or IBI sequences

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.

Audit missingness in Gazepoint biometric channels

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.

Audit Gazepoint biometric sampling and timing

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.

Audit Gazepoint biometric synchronization drift

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.

Audit a Gazepoint biometrics file before analysis

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.

Audit Gazepoint condition balance

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

Audit Gazepoint dataset structure

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.

Audit distributional drift across sessions or ordered blocks

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.

Audit Gazepoint EDA/GSR artifacts

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.

Audit Gazepoint engagement-dial signal quality

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.

Audit Gazepoint event coverage

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

Audit Gazepoint experiment design structure

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

Audit a Gazepoint export schema

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.

Audit Gazepoint GSR/EDA signal quality

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.

Audit likely GSR/EDA units

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.

Audit Gazepoint heart-rate signal quality

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.

Audit IBI/RR interval 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")

Audit external interoperability versions

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

Audit Gazepoint pipeline steps

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.

Audit preregistration checklist consistency

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.

Audit pupil-luminance confounding

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.

Audit gpbiometrics release readiness

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.

Audit session comparability across QC metrics

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.

Audit Gazepoint biometric signal activity

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.

Audit a smoke-test result for private information

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.

Audit or trim the EDA electrode stabilization period

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.

Audit Gazepoint biometric time resets

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.

Audit the participant-condition-time grid for cluster-permutation analysis

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.

Baseline-correct Gazepoint GSR/EDA

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

Baseline-correct Gazepoint heart rate

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

Baseline-correct Gazepoint pupil size

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.

Build a tidy AOI time course

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.

Calculate respiration-informed RSA proxy features

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.

Check a Gazepoint dataset for a BIDS-like layout

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.

Check Gazepoint biometric columns

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.

Check a Gazepoint plot return contract

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.

Check binary quality of Gazepoint pulse/PPG analysis results

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.

Check whether NN intervals are inside a plausible interval

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.

Chunk Gazepoint biometric data into fixed analysis episodes

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.

Classify descriptive Gazepoint EDA response patterns

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.

Classify SCRs into FIR, SIR, and TIR latency intervals

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.

Classify signal-quality rows using transparent threshold rules

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.

Clean Gazepoint pupil data

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.

Clean Gazepoint pupil signal

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

Clean RR or IBI intervals using HeartPy-style methods

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.

Combine multiple Gazepoint marker channels PsPM-style

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.

Bootstrap condition comparisons for Gazepoint-derived outcomes

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.

Compare Gazepoint export-folder profiles

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

Compare Gazepoint HR and IBI-derived heart rate

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.

Compare pyHRV-style PSD methods

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.

Compare ECG-HRV and PPG-PRV devices for one derived metric

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.

Compute engagement-dial summary indices

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)

Compute a simple Haar-style HRV wavelet PSD summary

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.

Compute Gazepoint pulse/PPG frequency-domain measures

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.

Compute HeartPy-style pulse/PPG 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.

Compute PPG beat-template similarity

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.

Compute pyHRV-style autoregressive PSD

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.

Compute detrended fluctuation analysis

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.

Compute pyHRV-style frequency-domain summary

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.

Compute heart rate from NN intervals

Description

Compute heart rate from NN intervals

Usage

compute_gazepoint_pyhrv_heart_rate(nni_ms)

Arguments

Value

Numeric heart rate in beats per minute.

Compute pyHRV-style heart-rate parameters

Description

Compute pyHRV-style heart-rate parameters

Usage

compute_gazepoint_pyhrv_hr_parameters(nni_ms)

Arguments

Value

Data frame of heart-rate parameters.

Compute pyHRV-style Lomb PSD

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.

Compute NN20 and pNN20

Description

Compute NN20 and pNN20

Usage

compute_gazepoint_pyhrv_nn20(nni_ms)

Arguments

Value

Data frame with NN20 and pNN20.

Compute NN50 and pNN50

Description

Compute NN50 and pNN50

Usage

compute_gazepoint_pyhrv_nn50(nni_ms)

Arguments

Value

Data frame with NN50 and pNN50.

Compute NN interval differences

Description

Compute NN interval differences

Usage

compute_gazepoint_pyhrv_nn_diff(nni_ms, absolute = FALSE)

Arguments

Value

Numeric successive NN differences in milliseconds.

Compute pyHRV-style NNI difference parameters

Description

Compute pyHRV-style NNI difference parameters

Usage

compute_gazepoint_pyhrv_nni_differences_parameters(nni_ms)

Arguments

Value

Data frame of successive-difference parameters.

Compute pyHRV-style NNI parameters

Description

Compute pyHRV-style NNI parameters

Usage

compute_gazepoint_pyhrv_nni_parameters(nni_ms)

Arguments

Value

Data frame of NNI parameters.

Compute NNxx and pNNxx

Description

Compute NNxx and pNNxx

Usage

compute_gazepoint_pyhrv_nnxx(nni_ms, threshold_ms = 50)

Arguments

Value

Data frame with NNxx and pNNxx.

Compute pyHRV-style nonlinear summary

Description

Compute pyHRV-style nonlinear summary

Usage

compute_gazepoint_pyhrv_nonlinear(nni_ms)

Arguments

Value

Data frame with nonlinear measures.

Compute pyHRV-style Poincare measures

Description

Compute pyHRV-style Poincare measures

Usage

compute_gazepoint_pyhrv_poincare(nni_ms, plot = FALSE)

Arguments

Value

Data frame of Poincare measures.

Compute pyHRV-style PSD waterfall over segments

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.

Compute RMSSD

Description

Compute RMSSD

Usage

compute_gazepoint_pyhrv_rmssd(nni_ms)

Arguments

Value

RMSSD in milliseconds.

Compute sample entropy

Description

Compute sample entropy

Usage

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

Arguments

Value

Sample entropy.

Compute SDANN

Description

Compute SDANN

Usage

compute_gazepoint_pyhrv_sdann(nni_ms, segment_seconds = 300)

Arguments

Value

SDANN in milliseconds.

Compute SDNN

Description

Compute SDNN

Usage

compute_gazepoint_pyhrv_sdnn(nni_ms)

Arguments

Value

SDNN in milliseconds.

Compute SDNN index

Description

Compute SDNN index

Usage

compute_gazepoint_pyhrv_sdnn_index(nni_ms, segment_seconds = 300)

Arguments

Value

SDNN index in milliseconds.

Compute SDSD

Description

Compute SDSD

Usage

compute_gazepoint_pyhrv_sdsd(nni_ms)

Arguments

Value

SDSD in milliseconds.

Compute pyHRV-style time-domain summary

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.

Compute TINN

Description

Compute TINN

Usage

compute_gazepoint_pyhrv_tinn(nni_ms, bin_width_ms = 7.8125)

Arguments

Value

Approximate TINN in milliseconds.

Compute triangular index

Description

Compute triangular index

Usage

compute_gazepoint_pyhrv_triangular_index(nni_ms, bin_width_ms = 7.8125)

Arguments

Value

HRV triangular index.

Compute pyHRV-style Welch PSD

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.

Compute a heuristic QC quality index

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.

Compute SCR habituation across trials

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.

Compute SCR latency metrics from event-locked EDA

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.

Compute signal band power

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.

Compute correlation between two Gazepoint signals

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.

Compute a pairwise signal-lag matrix

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.

Compute phase-locking value between two signals

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.

Compute signal power spectrum

Description

Compute signal power spectrum

Usage

compute_gazepoint_signal_power_spectrum(x, sampling_rate_hz, detrend = TRUE)

Arguments

Value

Data frame with frequency and power.

Compute transparent signal-quality indicators

Description

Computes conservative, rule-based descriptive quality indicators for one or more Gazepoint biometric signal columns. The function does not interpret the physiological meaning of the signal and does not exclude data.

Usage

compute_gazepoint_signal_quality(
  data,
  signal_cols,
  group_cols = NULL,
  flatline_tolerance = 0,
  long_missing_run_threshold = 10,
  long_constant_run_threshold = 10,
  spike_z = 4,
  extreme_z = 4
)

Arguments

Value

A data frame with class gazepoint_signal_quality.

Convert Gazepoint GSR resistance to conductance

Description

Converts GSR resistance values to conductance in microSiemens. The helper is intentionally conservative. If a conductance column such as GSR_US is already present, the data are returned unchanged unless overwrite = TRUE. If input_unit = "auto", conversion is performed only when the source column has a resistance-like name, such as GSR_OHMS or resistance_ohms.

Usage

convert_gazepoint_gsr_to_conductance(
  data,
  gsr_col = NULL,
  output_col = "GSR_US",
  input_unit = c("auto", "ohms", "kohms", "microsiemens"),
  overwrite = FALSE
)

Arguments

Details

Generic GSR columns are not automatically assumed to be resistance because Gazepoint exports and workflows may represent GSR/EDA differently. For a generic GSR column, use input_unit = "ohms" or input_unit = "kohms" only when the study documentation confirms resistance units.

Value

The input data frame with a conductance column when conversion is possible. A structured conversion summary is stored in the gsr_conversion_summary attribute.

Examples

df <- data.frame(GSR_OHMS = c(1000000, 500000, NA))
convert_gazepoint_gsr_to_conductance(df)

Apply conservative rule-based IBI corrections

Description

Applies a conservative correction action to beats flagged by audit_gazepoint_beats(). The default action masks flagged intervals by setting their corrected IBI to NA. The local-median action replaces flagged intervals only when an unflagged local or group median is available. Every change is logged. The function does not add or remove beat rows and does not compute or interpret HRV outcomes.

Usage

correct_gazepoint_beats(
  audit,
  action = c("mask", "local_median"),
  corrected_col = "ibi_corrected",
  local_window = 5,
  overwrite = FALSE,
  ...
)

Arguments

Value

A list with class gazepoint_beat_correction, containing corrected beat data, a correction log, a summary table, and parameters.

Correct EDA for ambient or body temperature

Description

Regresses an EDA/conductance signal on one or more continuous temperature covariates and returns a temperature-adjusted residual series. The adjusted signal is temperature-adjusted EDA, not "pure" cognitive or emotional EDA.

Usage

correct_gazepoint_eda_temperature(
  dat,
  eda_col = "GSR_US",
  temperature_cols,
  group_cols = NULL,
  time_col = NULL,
  output_col = "eda_temperature_adjusted",
  fitted_col = "eda_temperature_fitted",
  model_by_group = TRUE,
  add_intercept_mean = TRUE
)

Arguments

Value

A data frame with adjusted EDA columns and model-summary attributes.

Apply Hampel-style correction to raw pulse/PPG data

Description

Apply Hampel-style correction to raw pulse/PPG data

Usage

correct_gazepoint_ppg_hampel(
  x,
  sampling_rate_hz,
  window_seconds = 1,
  n_sigmas = 3
)

Arguments

Value

Corrected numeric signal.

Correct local RRI/IBI artifacts

Description

Correct local RRI/IBI artifacts

Usage

correct_gazepoint_rri_artifacts_local(
  rri_ms,
  method = c("local_median", "quotient", "zscore"),
  window_intervals = 5L,
  threshold = 0.2,
  replacement = c("local_median", "interpolate")
)

Arguments

Value

Data frame with corrected RRI values and artifact flags.

Create a Gazepoint analysis decision log

Description

Create an empty structured log for recording preprocessing choices, exclusions, missing channels, quality-control decisions, modelling settings, cluster-permutation settings, and reviewer-facing notes.

Usage

create_gazepoint_analysis_decision_log(
  study_id = NA_character_,
  analyst = NA_character_,
  description = NA_character_
)

Arguments

Value

A data frame with class "gazepoint_analysis_decision_log".

Examples

log <- create_gazepoint_analysis_decision_log(
  study_id = "demo_study",
  analyst = "analyst"
)

log <- add_gazepoint_decision(
  log,
  stage = "preprocessing",
  object_type = "signal",
  object_id = "GSR",
  decision = "baseline_corrected",
  reason = "Pre-event baseline window available",
  function_name = "baseline_correct_gazepoint_gsr",
  parameter = "baseline_window",
  value = "-1000_to_0_ms"
)

summarise_gazepoint_decision_log(log)

Create a Gazepoint analysis manifest

Description

Creates a reproducibility manifest containing package version, files, settings, outputs, exclusions, and optional session information. If path is supplied, a plain-text manifest is written for audit trails.

Usage

create_gazepoint_analysis_manifest(
  files = NULL,
  settings = list(),
  outputs = NULL,
  exclusions = NULL,
  path = NULL,
  include_session = TRUE
)

Arguments

Value

Manifest list.

Create a Gazepoint audit index

Description

Normalizes one or more Gazepoint audit/check objects into a single tabular index. The function is designed for reproducibility and reporting: it records object identifiers, source tables, checks, items, statuses, messages, and optional paths. It does not modify data and does not make scientific or clinical interpretations.

Usage

create_gazepoint_audit_index(
  audits,
  audit_ids = NULL,
  include_summary_rows = FALSE
)

Arguments

Value

A data frame with class gazepoint_audit_index.

Create a Gazepoint audit-report section

Description

Create a concise integrated report section from available Gazepoint audit objects.

Usage

create_gazepoint_audit_report_section(
  export_profile = NULL,
  design_audit = NULL,
  event_audit = NULL,
  condition_audit = NULL,
  decision_log = NULL,
  include_warnings = TRUE
)

Arguments

Value

A character vector with class "gazepoint_report_text".

Create a Gazepoint Biometrics reporting checklist

Description

Creates a compact reporting checklist for Gazepoint Biometrics exports. The checklist summarises detected biometric channels, validation issues, signal quality, missingness, available workflow domains, and interpretation cautions. It is intended to support transparent manuscript reporting and reviewer-facing methods documentation.

Usage

create_gazepoint_biometrics_checklist(data, require_active_signal = TRUE)

Arguments

Value

A list with overview, channels, quality, missingness, validation_issues, workflow_capabilities, feature_inventory, reporting_guidance, and interpretation_cautions.

Create a gpbiometrics feature inventory

Description

Creates a structured inventory of implemented gpbiometrics helper functions. This is useful for reporting, readiness checks, documentation, and package development audits.

Usage

create_gazepoint_biometrics_feature_inventory(include_internal = FALSE)

Arguments

Value

A list with overview, inventory, domain_summary, missing_expected, and settings.

Create Gazepoint Biometrics methods text

Description

Creates a compact draft methods paragraph describing Gazepoint Biometrics data processing. The text is intentionally cautious and avoids making emotional or cognitive claims from physiological or eye-tracking measures alone.

Usage

create_gazepoint_biometrics_methods_text(
  checklist = NULL,
  data = NULL,
  include_cautions = TRUE
)

Arguments

Value

A character string containing draft methods text.

Create a Gazepoint Biometrics report

Description

Creates a structured, manuscript-oriented report object for Gazepoint Biometrics data, workflow outputs, quality checks, report tables, methods text, and reporting checklists. The report is intentionally conservative: GSR/EDA is described as electrodermal activity/arousal-related signal rather than emotional valence; heart-rate interpretation is tied to baseline/task context; eye-tracking is described as visual attention rather than direct cognition; and raw HRV columns are not treated as HRV metrics.

Usage

create_gazepoint_biometrics_report(
  data = NULL,
  workflow = NULL,
  validation = NULL,
  quality = NULL,
  sampling = NULL,
  missingness = NULL,
  exclusions = NULL,
  report_tables = NULL,
  methods_text = NULL,
  checklist = NULL,
  title = "Gazepoint Biometrics report",
  subtitle = NULL,
  output_file = NULL,
  format = c("markdown", "html"),
  include_timestamp = FALSE,
  overwrite = FALSE,
  max_table_rows = 20L
)

Arguments

Details

The function can also write a lightweight Markdown or HTML file without adding heavy reporting dependencies.

Value

A list of class "gazepoint_biometrics_report" with overview, sections, tables, objects, output_file, and settings.

Examples

df <- data.frame(
  CNT = 1:5,
  GSR = c(1, 1.1, 1.2, 1.1, 1),
  HR = c(70, 71, 72, 71, 70),
  DIAL = c(40, 42, 44, 43, 41)
)
report <- create_gazepoint_biometrics_report(df)
names(report)

Create Gazepoint Biometrics report tables

Description

Creates compact report-ready tables from a Gazepoint Biometrics workflow object or from separate workflow components. The function does not write files. It returns cleaned tables that can be printed, exported, or inserted into reports and supplementary materials.

Usage

create_gazepoint_biometrics_report_tables(
  workflow = NULL,
  validation = NULL,
  quality = NULL,
  sampling = NULL,
  diagnostics = NULL,
  exclusion_recommendations = NULL,
  ttl_events = NULL,
  max_ttl_events = 20
)

Arguments

Value

A list of report-ready tables.

Create a simple Gazepoint data dictionary

Description

Creates a column-level dictionary from a data frame or from CSV file headers. The output is intended for reporting and reproducibility documentation.

Usage

create_gazepoint_dictionary(
  data = NULL,
  file_paths = NULL,
  units = NULL,
  descriptions = NULL,
  required_cols = NULL,
  write_path = NULL
)

Arguments

Value

A data frame with class gazepoint_dictionary.

Create a Gazepoint EDA analysis pipeline guide

Description

Creates a structured six-phase analysis pipeline for Gazepoint Biometrics EDA/GSR workflows. The helper maps each phase to native gpbiometrics functions, optional external-method bridges, and optional downstream model templates for brms and lme4.

Usage

create_gazepoint_eda_analysis_pipeline(
  include_external_bridges = TRUE,
  include_model_templates = TRUE,
  include_reporting_guidance = TRUE,
  style = c("compact", "detailed")
)

Arguments

Details

This function does not fit statistical models, does not run external software, and does not infer emotion, valence, stress, trust, preference, cognition, or diagnosis. It is a reproducible planning and reporting aid.

Value

A list with overview, phases, function_map, model_templates, reporting_guidance, interpretation_guardrails, and settings.

Create reproducible Gazepoint eye-tracking methods text

Description

Create reproducible Gazepoint eye-tracking methods text

Usage

create_gazepoint_eye_methods_text(
  sampling_rate_hz,
  device_model = "Gazepoint GP3",
  calibration_points = 9L,
  binocular = TRUE,
  software = "Gazepoint Analysis",
  screen_resolution = NULL,
  viewing_distance_cm = NULL,
  coordinate_space = NULL,
  preprocessing = NULL,
  fixation_detection = NULL,
  aoi_definition = NULL,
  synchronization = NULL,
  exclusions = NULL,
  tense = c("past", "future"),
  include_package_version = TRUE
)

Arguments

Value

A character object of class "gazepoint_eye_methods_text".

Create HeartPy-style report tables for Gazepoint pulse/PPG data

Description

Create HeartPy-style report tables for Gazepoint pulse/PPG data

Usage

create_gazepoint_heartpy_report(
  detection,
  output_dir = NULL,
  prefix = "gazepoint_heartpy"
)

Arguments

Value

A list with peaks, measures, diagnostics, and paths.

Create a compact Gazepoint methods section

Description

Generate conservative, manuscript-ready methods text from available Gazepoint workflow objects. The function reports workflow structure and audit coverage only; it does not infer emotion, stress, cognition, preference, diagnosis, mechanism, or exact temporal onset from biometric or gaze-linked signals.

Usage

create_gazepoint_methods_section(
  export_profile = NULL,
  design_audit = NULL,
  event_audit = NULL,
  condition_audit = NULL,
  decision_log = NULL,
  package_version = as.character(utils::packageVersion("gpbiometrics")),
  validation = NULL,
  include_guardrails = TRUE
)

Arguments

Value

A character vector with class "gazepoint_report_text".

Examples

log <- create_gazepoint_analysis_decision_log(study_id = "demo")
create_gazepoint_methods_section(decision_log = log)

Create a Gazepoint pipeline map

Description

Creates a lightweight tabular representation of a Gazepoint analysis pipeline. The output contains workflow nodes and directed edges that can be audited or exported as DOT/Graphviz text. This function is intended for documentation, reporting, and reproducibility only.

Usage

create_gazepoint_pipeline_map(
  steps = NULL,
  edges = NULL,
  pipeline_id = NULL,
  include_default = TRUE
)

Arguments

Value

A list with class gazepoint_pipeline_map.

Create a Gazepoint preregistration checklist

Description

Creates a structured checklist for preregistration and reviewer-readiness documentation. The checklist is descriptive only: it helps users document design, preprocessing, QC, exclusions, outcomes, and reporting decisions. It does not judge scientific validity, remove data, or make biometric, psychological, diagnostic, or clinical claims.

Usage

create_gazepoint_preregistration_checklist(
  study_id = NULL,
  include_optional = TRUE,
  custom_items = NULL
)

Arguments

Value

A data frame with class gazepoint_preregistration_checklist.

Create a Gazepoint biometrics preregistration template

Description

Creates a cautious preregistration template for Gazepoint Biometrics EDA/GSR workflows.

Usage

create_gazepoint_preregistration_template(
  study_title = "Gazepoint biometrics study",
  signal_standardization = c("within_participant_z", "range_correction", "none"),
  artifact_rules = c("kleckner_style", "custom", "none"),
  eda_min_us = 0.01,
  eda_max_us = 100,
  rapid_change_threshold = 20,
  output_file = NULL
)

Arguments

Value

A character string.

Create PsPM-style convolution GLM design matrix

Description

Create PsPM-style convolution GLM design matrix

Usage

create_gazepoint_pspm_glm_design(
  events,
  time,
  time_col = NULL,
  onset_col = "onset_time_s",
  condition_col = "condition",
  duration_col = NULL,
  response = c("scr", "canonical", "boxcar"),
  response_length_s = 20,
  include_derivative = FALSE,
  add_intercept = TRUE
)

Arguments

Value

Design matrix as data frame.

Create a time vector from NN intervals

Description

Create a time vector from NN intervals

Usage

create_gazepoint_pyhrv_time_vector(nni_ms, start_s = 0)

Arguments

Value

Numeric time vector in seconds.

Create a Gazepoint quality-control supplement section

Description

Generate a compact reviewer-facing quality-control supplement from available export-profile, design-audit, event-audit, condition-balance, and decision-log objects.

Usage

create_gazepoint_qc_supplement(
  export_profile = NULL,
  design_audit = NULL,
  event_audit = NULL,
  condition_audit = NULL,
  decision_log = NULL,
  title = "Gazepoint workflow quality-control supplement"
)

Arguments

Value

A character vector with class "gazepoint_report_text".

Create a compact Gazepoint quality dashboard object

Description

Combines audit, missingness, synchronization, and event-locked summary objects into a reviewer-friendly quality dashboard. If output_dir is supplied, core dashboard tables are exported as CSV/text files.

Usage

create_gazepoint_quality_dashboard(
  data = NULL,
  audit = NULL,
  missingness = NULL,
  alignment = NULL,
  eventlocked = NULL,
  title = "Gazepoint quality dashboard",
  output_dir = NULL
)

Arguments

Value

Object of class gazepoint_quality_dashboard.

Create a gpbiometrics release checklist

Description

Creates a conservative release checklist. If an audit table is supplied, each checklist item is linked to the current audit status. The checklist is meant to support human review before tagging or submission.

Usage

create_gazepoint_release_checklist(audit = NULL, include_optional = TRUE)

Arguments

Value

A data frame with release checklist items.

Create a Gazepoint reproducibility statement

Description

Generate a compact reproducibility statement for manuscripts, supplements, or reviewer responses.

Usage

create_gazepoint_reproducibility_statement(
  decision_log = NULL,
  package_version = as.character(utils::packageVersion("gpbiometrics")),
  repository_url = NA_character_,
  validation = NULL,
  data_statement = NA_character_,
  include_guardrails = TRUE
)

Arguments

Value

A character vector with class "gazepoint_report_text".

Create a Gazepoint sidecar metadata template

Description

Creates a simple tabular template for dataset, export, device, timing, and processing metadata. The output can be written by the user as CSV/TSV/JSON outside this function. This function does not perform full BIDS conversion.

Usage

create_gazepoint_sidecar_template(
  dataset_id = NULL,
  export_type = NULL,
  include_optional = TRUE,
  custom_fields = NULL
)

Arguments

Value

A data frame with class gazepoint_sidecar_template.

Create Gazepoint trial-level regressors for modeling

Description

Prepares a long-format trial table by joining stimulus/event design information with event-window summaries from numeric Gazepoint channels. The output is intended for downstream GLM, LMM, or mixed-model workflows.

Usage

create_gazepoint_trial_regressors(
  data,
  design,
  pre = 0,
  post = 5,
  time_col = NULL,
  event_time_col = NULL,
  event_id_col = NULL,
  signal_cols = NULL,
  subject_col = NULL,
  design_subject_col = NULL,
  carry_design_cols = NULL
)

Arguments

Value

A data frame with one row per trial/event and signal summary regressors.

Examples

dat <- data.frame(time_s = seq(0, 10, by = 1), GSR = seq(0, 1, length.out = 11))
design <- data.frame(trial = "T1", onset = 5, condition = "A")
create_gazepoint_trial_regressors(dat, design, pre = 1, post = 2)

Decompose Gazepoint GSR/EDA into tonic and phasic components

Description

Creates descriptive tonic and phasic EDA columns from Gazepoint GSR/EDA data. If vendor-provided tonic/phasic columns such as GSR_US_TONIC and GSR_US_PHASIC are available, they are used by default. Otherwise, a simple rolling-median tonic estimate is used and the phasic component is calculated as signal minus tonic. This helper is intentionally conservative and does not replace specialised biosignal-processing software.

Usage

decompose_gazepoint_eda(
  data,
  signal_col = NULL,
  tonic_col = NULL,
  phasic_col = NULL,
  time_col = NULL,
  group_cols = NULL,
  window_size = 31L,
  output_prefix = "eda",
  overwrite = FALSE
)

Arguments

Value

A data frame with added tonic, phasic, and method columns. Attributes include overview and settings.

Examples

df <- data.frame(CNT = 1:10, GSR_US = seq(1, 2, length.out = 10))
out <- decompose_gazepoint_eda(df, signal_col = "GSR_US", window_size = 3)
names(out)

Denoise EDA using a user-supplied autoencoder reconstruction model

Description

Applies a user-supplied reconstruction function or model to fixed-length EDA windows. No pretrained neural network is bundled. This function is an interoperability bridge for validated user-supplied autoencoders.

Usage

denoise_gazepoint_eda_autoencoder(
  dat,
  eda_col = "GSR_US",
  time_col = NULL,
  group_cols = NULL,
  model = NULL,
  window_samples = 128,
  output_col = NULL,
  overwrite = FALSE
)

Arguments

Value

A data frame with reconstructed signal and denoising attributes.

Denoise EDA using dependency-light Haar wavelet shrinkage

Description

Applies simple Haar wavelet soft-threshold denoising to EDA signals within optional groups. This is a dependency-light wavelet denoising helper and should not be described as an exact reproduction of stationary-wavelet artifact-removal algorithms.

Usage

denoise_gazepoint_eda_wavelet(
  dat,
  eda_col = "GSR_US",
  group_cols = NULL,
  output_col = NULL,
  levels = 3,
  threshold_multiplier = 1,
  overwrite = FALSE
)

Arguments

Value

A data frame with denoised EDA and denoising attributes.

Denoise PPG using a user-supplied autoencoder reconstruction model

Description

Applies a user-supplied reconstruction function or model to fixed-length PPG windows. No pretrained neural network is bundled. This function is an interoperability bridge for validated user-supplied autoencoders.

Usage

denoise_gazepoint_ppg_autoencoder(
  dat,
  ppg_col = "HRP",
  time_col = NULL,
  group_cols = NULL,
  model = NULL,
  window_samples = 128,
  output_col = NULL,
  overwrite = FALSE
)

Arguments

Value

A data frame with reconstructed signal and denoising attributes.

Add small uniform noise to reduce quantization overlap

Description

Adds uniform white noise with magnitude tied to hardware resolution. This is intended only for nonlinear phase-space methods that are sensitive to exact repeated values caused by coarse interval quantization.

Usage

denoise_gazepoint_quantization_noise(
  dat,
  signal_cols,
  resolution,
  group_cols = NULL,
  output_suffix = "_quantization_jittered",
  seed = NULL,
  overwrite = FALSE
)

Arguments

Value

A data frame with jittered columns and quantization-noise attributes.

Detect active Gazepoint biometric channels

Description

Detects whether GSR/EDA, heart-rate, engagement-dial, and TTL channels are present and whether they appear active. A channel can be present but inactive when validity flags are zero or the signal contains only zeros or missing values. For each signal family, summary_column identifies the primary column used for the reported minimum and maximum values.

Usage

detect_active_biometric_channels(data)

Arguments

Value

A data frame with one row per signal family.

Detect the schema of Gazepoint biometric data

Description

Detects likely biometric, timing, marker, and identifying columns in a Gazepoint Biometrics export. The function is deliberately descriptive. It reports what appears to be present and active, but it does not infer emotion, valence, or HRV from ambiguous raw columns.

Usage

detect_gazepoint_biometric_schema(data)

Arguments

Value

A list with overview, columns, time_columns, timebase, name_map, and notes.

Examples

df <- data.frame(
  CNT = 1:5,
  TIME = seq(0, by = 1 / 60, length.out = 5),
  GSR = c(100, 101, 102, 101, 100),
  HR = c(70, 71, 72, 71, 70),
  HRV = c(1, 1, 1, 1, 1)
)
detect_gazepoint_biometric_schema(df)

Detect the likely timebase of Gazepoint biometric data

Description

Inspects timing and counter columns and returns a conservative summary of the likely primary timebase. Sampling rate is estimated only when numeric timing information is available and intervals are positive.

Usage

detect_gazepoint_biometric_timebase(data, time_col = NULL, counter_col = NULL)

Arguments

Value

A list with overview, time_columns, interval_summary, and warnings.

Examples

df <- data.frame(CNT = 1:5, TIME = seq(0, by = 1 / 60, length.out = 5))
detect_gazepoint_biometric_timebase(df)

Detect likely blink or pupil-dropout samples

Description

Detects likely blink or pupil-dropout samples in Gazepoint pupil columns using transparent, rule-based criteria. The function flags non-finite values, values outside a plausible pupil range, and optionally large sample-to-sample changes. It does not infer attention, cognition, arousal, emotion, or visual processing from the pupil signal.

Usage

detect_gazepoint_blinks(
  data,
  pupil_cols = NULL,
  id_cols = NULL,
  min_pupil = 0,
  max_pupil = Inf,
  change_threshold = NULL,
  extend_samples = 0L,
  mask = TRUE,
  flag_suffix = "_blink_flag",
  clean_suffix = "_blink_clean"
)

Arguments

Value

A list with the processed data, a summary table, rule settings, and warnings. The object has class "gazepoint_blink_audit".

Examples

d <- data.frame(
  participant = rep("P01", 8),
  time = seq_len(8),
  pupil_left = c(3.1, 3.2, 0, 3.2, 8.5, 3.1, NA, 3.0)
)
detect_gazepoint_blinks(d, pupil_cols = "pupil_left")

Detect stochastic change points in noisy biometric signals

Description

Detects abrupt changes in noisy biological time series using a dependency-light stochastic rolling-window approximation. The score combines adjacent-window changes in mean and variance with a robust adaptive threshold.

Usage

detect_gazepoint_doubly_stochastic_changepoints(
  dat,
  signal_col,
  time_col = "CNT",
  group_cols = NULL,
  window_seconds = 10,
  step_seconds = 2,
  threshold_mad_multiplier = 6,
  min_distance_s = 5
)

Arguments

Details

This is not a full reproduction of any specific doubly stochastic model. It is a transparent approximation for QC and exploratory segmentation.

Value

A list with overview, score_table, changepoints, and settings.

Detect fixations and saccades in Gazepoint gaze samples

Description

Applies a transparent velocity-threshold classification to raw Gazepoint gaze coordinates. Samples are classified as fixation, saccade, unclassified, or invalid, after which fixation- and saccade-level event tables are derived.

Usage

detect_gazepoint_fixations(
  data,
  time_col = NULL,
  x_col = NULL,
  y_col = NULL,
  group_cols = NULL,
  valid_col = NULL,
  valid_values = c(1, TRUE),
  time_unit = c("seconds", "milliseconds", "microseconds", "samples"),
  sampling_rate_hz = NULL,
  coordinate_unit = c("native", "normalized", "pixels", "degrees"),
  velocity_threshold,
  min_fixation_duration_ms = 100,
  min_saccade_duration_ms = 10,
  max_gap_ms = 100,
  velocity_col = "gaze_velocity",
  class_col = "gaze_class",
  event_id_col = "gaze_event_id",
  overwrite = FALSE
)

Arguments

Details

This is an I-VT-style detector rather than an exact reproduction of a specific vendor or external-toolbox implementation. The velocity threshold must match the supplied coordinate unit and should be justified, reported, and sensitivity-checked for the recording design.

Value

An object of class "gazepoint_gaze_events" containing:

• samples: original rows with velocity, class, and event ID;

• fixations: fixation-level timing, location, and dispersion summaries;

• saccades: saccade-level timing, amplitude, direction, and velocity;

• summary: group-level sample and event counts;

• settings: complete detector settings.

References

Salvucci, D. D., and Goldberg, J. H. (2000). Identifying fixations and saccades in eye-tracking protocols. Proceedings of the Eye Tracking Research and Applications Symposium.

See Also

detect_gazepoint_saccades(), plot_gazepoint_saccade_main_sequence(), summarize_gazepoint_fixations()

Examples

gaze <- data.frame(
  time_s = seq(0, 0.9, by = 0.1),
  gaze_x = c(0, 0.01, 0.02, 0.03, 1, 1.01, 1.02, 1.03, 1.04, 1.05),
  gaze_y = 0
)

events <- detect_gazepoint_fixations(
  gaze,
  time_col = "time_s",
  x_col = "gaze_x",
  y_col = "gaze_y",
  velocity_threshold = 2,
  min_fixation_duration_ms = 100,
  min_saccade_duration_ms = 50
)

events$fixations
events$saccades

Detect long signal-dropout intervals

Description

Flags long missing, zero, constant, or low-variance runs in selected signal columns. The function is intended for quality control and audit reporting only. It does not remove samples and does not make physiological, psychological, diagnostic, or clinical claims.

Usage

detect_gazepoint_nonwear(
  data,
  signal_cols,
  group_cols = NULL,
  time_col = NULL,
  min_run_length = 10,
  zero_tolerance = 0,
  constant_tolerance = 0,
  low_variance_threshold = NULL,
  detect_missing = TRUE,
  detect_zero = TRUE,
  detect_constant = TRUE,
  detect_low_variance = TRUE
)

Arguments

Value

A list with class gazepoint_nonwear_detection, containing interval and summary tables.

Detect BioSPPy-style PPG pulse onsets

Description

Detect BioSPPy-style PPG pulse onsets

Usage

detect_gazepoint_ppg_onsets(
  data,
  signal_col = NULL,
  time_col = NULL,
  peaks = NULL,
  group_cols = NULL,
  sampling_rate_hz = NULL,
  search_seconds = 0.6
)

Arguments

Value

Data frame of onsets.

Detect HeartPy-style pulse/PPG peaks in Gazepoint exports

Description

Detect HeartPy-style pulse/PPG peaks in Gazepoint exports

Usage

detect_gazepoint_ppg_peaks(
  data,
  signal_col = NULL,
  time_col = NULL,
  group_cols = NULL,
  sampling_rate_hz = NULL,
  bpm_min = 40,
  bpm_max = 180,
  moving_average_seconds = 0.75,
  threshold_offsets = seq(-0.25, 1.25, by = 0.05),
  reconstruct_clipping = TRUE,
  enhance_peaks = FALSE,
  lowpass_hz = NULL,
  hampel = FALSE,
  high_precision = TRUE
)

Arguments

Value

A list with peaks, processed_signal, settings, and diagnostics.

Detect blink intervals from Gazepoint pupil data

Description

Identifies blink-like intervals as runs of missing, zero, non-finite, or invalid pupil samples. For binocular data, the default treats a blink as a sample where all selected pupil channels are invalid.

Usage

detect_gazepoint_pupil_blinks(
  data,
  pupil_cols = NULL,
  time_col = NULL,
  group_cols = NULL,
  validity_cols = NULL,
  invalid_values = c(0),
  nonpositive_is_missing = TRUE,
  combine = c("all", "any"),
  min_blink_samples = 1L,
  return = c("intervals", "onsets", "flags")
)

Arguments

Value

A data frame of blink intervals by default. If return = "onsets", a numeric vector of blink onset times is returned. If return = "flags", a logical vector marking blink samples is returned.

Examples

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

Detect saccades in Gazepoint gaze samples

Description

Convenience wrapper around detect_gazepoint_fixations() that returns only the saccade-level event table. Detector settings and group summaries are retained as attributes.

Usage

detect_gazepoint_saccades(...)

Arguments

Value

A data frame with class "gazepoint_detected_saccades" containing saccade timing, amplitude, direction, and velocity measures.

Examples

gaze <- data.frame(
  time_s = seq(0, 0.9, by = 0.1),
  gaze_x = c(0, 0.01, 0.02, 0.03, 1, 1.01, 1.02, 1.03, 1.04, 1.05),
  gaze_y = 0
)

detect_gazepoint_saccades(
  gaze,
  time_col = "time_s",
  x_col = "gaze_x",
  y_col = "gaze_y",
  velocity_threshold = 2,
  min_saccade_duration_ms = 50
)

Detect SCR-like events in Gazepoint GSR/EDA data

Description

Detects simple SCR-like peaks from a phasic EDA signal. If a phasic column is not supplied, the function first creates a descriptive phasic component using decompose_gazepoint_eda(). This helper is intended for exploratory quality control and descriptive summaries, not as a replacement for specialised SCR detection pipelines.

Usage

detect_gazepoint_scr_events(
  data,
  phasic_col = NULL,
  signal_col = NULL,
  time_col = NULL,
  group_cols = NULL,
  threshold = NULL,
  min_peak_distance = 10L,
  window_size = 31L
)

Arguments

Value

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

Examples

df <- data.frame(
  CNT = 1:20,
  GSR_US_PHASIC = c(rep(0, 5), 0.2, 0.8, 0.2, rep(0, 12))
)
detect_gazepoint_scr_events(df, phasic_col = "GSR_US_PHASIC", time_col = "CNT")

Detect Gazepoint SCR peaks

Description

Detects candidate skin conductance responses (SCRs) from Gazepoint EDA/GSR signals. The helper prefers a phasic channel such as GSR_US_PHASIC when available, and otherwise falls back to a conductance-like signal such as GSR_US. It returns explicit onset, peak, amplitude, rise-time, and recovery-time fields for downstream event-window summaries and statistical modelling.

Usage

detect_gazepoint_scr_peaks(
  data,
  signal_col = NULL,
  phasic_col = NULL,
  time_col = NULL,
  group_cols = NULL,
  prefer_vendor_phasic = TRUE,
  amplitude_min = 0.01,
  recovery_fraction = 0.5,
  smooth_width = 1,
  min_peak_distance = 1
)

Arguments

Details

This is a conservative R-native peak detector. It is not a replacement for full model-based EDA decomposition tools such as Ledalab, PsPM, or cvxEDA.

Value

A list with overview, peaks, group_summary, signal_summary, and settings.

Detect Gazepoint biometric time columns

Description

Detects likely timing and counter columns in Gazepoint Biometrics exports. The function reports candidate timing columns rather than assuming that any single time variable is always present or always measured in the same unit.

Usage

detect_gazepoint_time_columns(data)

Arguments

Value

A data frame with one row per detected time-related column.

Examples

detect_gazepoint_time_columns(c("CNT", "TIME_MS", "GSR", "HR"))

Detrend RRI/IBI intervals in windows

Description

Detrend RRI/IBI intervals in windows

Usage

detrend_gazepoint_rri_window(
  rri_ms,
  time_s = NULL,
  window_seconds = 60,
  method = c("median", "mean", "linear")
)

Arguments

Value

Data frame with original, trend, and detrended RRI.

Detrend a Gazepoint signal

Description

Applies a lightweight generic detrending step to any numeric Gazepoint signal, either globally or within participant/trial groups. This is useful for slow drift in channels such as EDA, pupil size, PPG baseline, or temperature.

Usage

detrend_gazepoint_signal(
  data,
  signal_col = NULL,
  time_col = NULL,
  group_cols = NULL,
  method = c("linear", "mean", "median", "loess", "none"),
  span = 0.3,
  preserve_mean = FALSE,
  suffix = "_detrended"
)

Arguments

Value

Data frame with added trend and detrended columns.

Diagnose a Gazepoint Biometrics workflow

Description

Creates a compact diagnostic readiness summary from a Gazepoint Biometrics workflow object. The function does not change or remove data. It returns a one-row decision table with pass/review/fail status and concise reasons.

Usage

diagnose_gazepoint_biometrics_workflow(
  workflow,
  require_gsr = TRUE,
  require_hr = TRUE,
  require_dial = FALSE,
  max_exclude_window_pct = 25,
  max_review_window_pct = 25
)

Arguments

Value

A one-row data frame with diagnostic status and reasons.

Diagnose whether a design is suitable for cluster-permutation analysis

Description

Performs high-level checks on the data structure and design assumptions used by the current cluster-permutation prototype.

Usage

diagnose_gazepoint_cluster_design(
  data,
  subject,
  condition,
  time,
  value = NULL,
  design = c("within", "between"),
  min_subjects = 10L
)

Arguments

Value

An object of class gazepoint_cluster_design_diagnostic.

Diagnose synchronization drift between two time bases

Description

Estimates lag and linear drift between matched timestamps or event markers. A fixed lag has a near-zero drift slope; a changing lag has a non-zero slope.

Usage

diagnose_gazepoint_sync_drift(
  reference,
  target = NULL,
  reference_time_col = NULL,
  target_time_col = NULL,
  max_pairs = NULL
)

Arguments

Value

List with summary and lag_table.

Downsample Gazepoint time-series data

Description

Aggregates selected numeric gaze or biometric signals into fixed-width time bins. Processing can be performed independently within participant, trial, session, or other user-defined groups. Only occupied bins are returned; the function does not fabricate observations for empty periods.

Usage

downsample_gazepoint_data(
  data,
  time_col,
  signal_cols = NULL,
  group_cols = NULL,
  interval,
  method = c("mean", "median", "first", "last"),
  na_rm = TRUE,
  time_value = c("start", "center", "mean"),
  origin = NULL
)

Arguments

Details

The returned object records the number of contributing source rows for each bin and stores a structured downsampling log and settings as attributes.

Value

A data frame with class "gazepoint_downsampled_data". The output contains grouping columns, the downsampled time column, aggregated signals, and n_source_rows. Attributes downsample_log and downsample_settings provide provenance information.

Examples

dat <- data.frame(
  participant = rep(c("P01", "P02"), each = 6),
  time_ms = rep(0:5, 2),
  pupil = c(3.0, 3.1, 3.2, 3.3, 3.4, 3.5,
            2.9, 3.0, 3.1, 3.2, 3.3, 3.4)
)

downsample_gazepoint_data(
  dat,
  time_col = "time_ms",
  signal_cols = "pupil",
  group_cols = "participant",
  interval = 3
)

Enhance pulse/PPG peaks using repeated local baseline removal

Description

Enhance pulse/PPG peaks using repeated local baseline removal

Usage

enhance_gazepoint_ppg_peaks(x, sampling_rate_hz, iterations = 2L)

Arguments

Value

Enhanced numeric signal.

Epoch Gazepoint SCR/EDA data around events

Description

Segments an EDA/GSR signal around event timestamps and returns event-level SCR metrics, including SCR count, maximum amplitude, mean amplitude, AUC, and baseline-corrected epoch summaries.

Usage

epoch_gazepoint_scr(
  data,
  events,
  pre,
  post,
  time_col = NULL,
  signal_col = NULL,
  event_time_col = NULL,
  event_id_col = NULL,
  event_group_cols = NULL,
  baseline_window = NULL,
  response_window = NULL,
  min_amplitude = 0.01,
  min_distance_s = 1
)

Arguments