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

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.

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.

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.

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

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.

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

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.

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.

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)

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.

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

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

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.

Estimate lag between two Gazepoint biometric signals

Description

Estimates the time shift that maximizes the association between two recorded biometric signals within each group. This is a conservative synchronization diagnostic for inspecting whether two recorded traces show similar temporal structure at different shifts. It should not be interpreted as causal timing or true physiological latency unless the design includes appropriate event markers and independently justified signal-processing assumptions.

Usage

estimate_gazepoint_signal_lag(
  data,
  signal_x_col,
  signal_y_col,
  time_col = NULL,
  group_cols = NULL,
  max_lag = 1000,
  lag_step = NULL,
  method = c("pearson", "spearman"),
  min_complete_pairs = 20,
  use_first_difference = FALSE
)

Arguments

Value

A list with overview, lag_by_group, lag_profile, and settings.

Export a Gazepoint biometrics report bundle

Description

Exports selected report tables, text outputs, optional plot objects, and a manifest to a local output directory. This helper is intended for reproducible reporting. It does not commit files and should not be used to export private real-data outputs into a package repository.

Usage

export_gazepoint_biometrics_report_bundle(
  bundle = NULL,
  output_dir,
  prefix = "gpbiometrics_report",
  tables = NULL,
  text = NULL,
  plots = NULL,
  include_readme = TRUE,
  include_session_info = TRUE,
  overwrite = FALSE
)

Arguments

Value

A list with overview, manifest, output_dir, and settings.

Export Gazepoint IBI data for RHRV-style workflows

Description

Prepares cleaned inter-beat interval data for external HRV workflows. The helper writes simple beat tables with cumulative beat time and IBI/RR interval columns. It does not use the Gazepoint HRV column.

Usage

export_gazepoint_rhrv_input(
  data,
  ibi_col = "IBI_clean_ms",
  group_cols = NULL,
  unit = c("auto", "ms", "seconds"),
  collapse_repeated_intervals = TRUE,
  repeated_tolerance_ms = 1e-08,
  min_ibi_ms = 300,
  max_ibi_ms = 2000,
  output_dir = NULL,
  prefix = "gazepoint_rhrv"
)

Arguments

Value

A list with overview, beat_table, group_summary, manifest, and settings.

Extract heartbeat candidates from Gazepoint pulse using k-means

Description

Uses k-means clustering on the raw pulse waveform to classify likely heartbeat regions and then selects local extrema as beat candidates. This is a Gazepoint Biometrics-oriented fallback for difficult pulse waveforms, not an ECG-equivalent R-peak detector.

Usage

extract_gazepoint_beats_kmeans(
  dat,
  pulse_col = "HRP",
  time_col = "CNT",
  group_cols = NULL,
  k = 2,
  peak_polarity = c("positive", "negative"),
  min_distance_s = 0.3,
  sampling_rate = NULL,
  seed = NULL
)

Arguments

Value

A list with overview, beat_table, interval_table, timeseries, and settings.

Extract bilateral EDA asymmetry features

Description

Computes left-right electrodermal activity asymmetry descriptors from two simultaneously recorded EDA channels. The function returns row-level asymmetry time series and group-level summaries.

Usage

extract_gazepoint_bilateral_eda_asymmetry(
  dat,
  left_col,
  right_col,
  time_col = NULL,
  group_cols = NULL,
  output_prefix = "beda"
)

Arguments

Details

These descriptors quantify bilateral EDA differences only. They do not infer hemisphere activation, amygdala activity, psychopathology, emotion, stress, cognition, health status, or diagnosis.

Value

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

Extract EDA complexity features

Description

Computes dependency-light EDA complexity descriptors, including sample entropy and detrended fluctuation analysis alpha.

Usage

extract_gazepoint_eda_complexity(
  dat,
  eda_col = "GSR_US",
  group_cols = NULL,
  min_samples = 32,
  sampen_m = 2,
  sampen_r_multiplier = 0.2
)

Arguments

Value

A list with overview, features, and settings.

Extract frequency-domain EDA spectral power

Description

Computes power spectral density summaries for an EDA signal, including spectral power in the EDASymp-inspired 0.045–0.25 Hz band. This is a descriptive spectral feature and should not be interpreted as direct stress, emotion, valence, cognition, trust, preference, or diagnosis.

Usage

extract_gazepoint_eda_spectral_power(
  dat,
  eda_col = "GSR_US",
  time_col = NULL,
  group_cols = NULL,
  sampling_rate = NULL,
  band = c(0.045, 0.25),
  min_samples = 32,
  detrend = TRUE
)

Arguments

Value

A list with overview, spectral_summary, settings, and interpretation text.

Extract time-varying spectral EDA features

Description

Computes a dependency-light approximation of TVSymp-style time-varying spectral EDA power using sliding-window spectral analysis. The default band is 0.08–0.24 Hz, following the TVSymp literature. This function does not claim exact VFCDM reproduction.

Usage

extract_gazepoint_eda_tvsymp(
  dat,
  eda_col = "GSR_US",
  time_col = "CNT",
  group_cols = NULL,
  sampling_rate = NULL,
  band = c(0.08, 0.24),
  window_seconds = 60,
  step_seconds = 5,
  min_valid_fraction = 0.7,
  normalise = TRUE
)

Arguments

Value

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

Extract ECG-derived respiration using PCA

Description

Extracts an ECG-derived respiration proxy from beat-level ECG morphology features using principal component analysis. This function requires ECG-derived morphology columns, such as QRS amplitudes, widths, or sampled beat-shape features. It is not intended for HR, IBI, or PPG-only data.

Usage

extract_gazepoint_edr_pca(
  dat,
  ecg_cols,
  time_col = NULL,
  group_cols = NULL,
  n_components = 1,
  scale = TRUE,
  output_prefix = "edr_pca"
)

Arguments

Value

A list with overview, edr_timeseries, component_summary, and settings.

Extract heart-rate asymmetry features

Description

Computes dependency-light heart-rate asymmetry descriptors from IBI/RR intervals, including acceleration/deceleration proportions, signed run summaries, and Guzik-style squared-difference asymmetry.

Usage

extract_gazepoint_hrv_asymmetry(
  dat,
  ibi_col = "IBI",
  group_cols = NULL,
  zero_tolerance = 0
)

Arguments

Details

Positive IBI/RR differences are treated as decelerations because the heart period lengthens. Negative IBI/RR differences are treated as accelerations.

Value

A list with overview, features, run_table, and settings.

Extract time-domain HRV features from Gazepoint IBI intervals

Description

Computes simple time-domain HRV features from genuine IBI/RR intervals. This helper does not use the Gazepoint HRV column as an HRV outcome.

Usage

extract_gazepoint_hrv_features(
  data,
  ibi_col = "IBI_clean_ms",
  group_cols = NULL,
  unit = c("auto", "ms", "seconds"),
  min_intervals = 3,
  min_duration_s = 30,
  diff_threshold_ms = 50,
  collapse_repeated_intervals = TRUE,
  repeated_tolerance_ms = 1e-08
)

Arguments

Value

A list with overview, features, settings.

Extract heart-rate fragmentation features

Description

Computes dependency-light heart-rate fragmentation descriptors from IBI/RR intervals. Metrics include percentage of inflection points (PIP), inverse average segment length (IALS), percentage of short segments (PSS), percentage of alternation segments (PAS), and long/short segment summaries.

Usage

extract_gazepoint_hrv_fragmentation(
  dat,
  ibi_col = "IBI",
  group_cols = NULL,
  zero_tolerance = 0,
  short_segment_length = 3
)

Arguments

Details

These are fragmentation descriptors of interbeat interval dynamics. They should not be interpreted as clinical diagnoses or direct autonomic-state labels by themselves.

Value

A list with overview, features, and settings.

Extract FuzzyEn and Lorenz-plot CSI HRV features

Description

Computes fuzzy entropy and Lorenz/Poincare-derived cardiac sympathetic index style descriptors from IBI/RR intervals.

Usage

extract_gazepoint_hrv_fuzzy_csi(
  dat,
  ibi_col = "IBI",
  group_cols = NULL,
  m = 2,
  r_multiplier = 0.2,
  fuzzy_power = 2,
  min_intervals = 10
)

Arguments

Details

These outputs are nonlinear/geometric HRV descriptors. They do not infer seizure status, diagnosis, health status, emotion, stress, or cognition.

Value

A list with overview, features, and settings.

Extract geometric HRV features

Description

Computes dependency-light geometric HRV descriptors, including the HRV triangular index and an approximate TINN-style triangular interpolation width.

Usage

extract_gazepoint_hrv_geometric(
  dat,
  ibi_col = "IBI",
  group_cols = NULL,
  bin_width = NULL
)

Arguments

Value

A list with overview, features, and settings.

Extract nonlinear HRV features from IBI/RR intervals

Description

Computes dependency-light nonlinear HRV descriptors from IBI/RR intervals, including Poincare SD1/SD2, sample entropy, approximate entropy, multiscale entropy, and detrended fluctuation analysis.

Usage

extract_gazepoint_hrv_nonlinear(
  dat,
  ibi_col = "IBI",
  group_cols = NULL,
  min_intervals = 10,
  sampen_m = 2,
  sampen_r_multiplier = 0.2,
  mse_scales = 1:5
)

Arguments

Details

These are variability and complexity descriptors. They should not be interpreted as direct emotion, cognitive-load, health-status, or diagnostic labels by themselves.

Value

A list with overview, features, and settings.

Extract refined composite multiscale entropy from HRV intervals

Description

Computes refined composite multiscale entropy (RCMSE) from IBI/RR intervals. RCMSE pools template-match counts across all coarse-grained offsets at each scale, making it more stable than ordinary MSE for shorter physiological time series.

Usage

extract_gazepoint_hrv_rcmse(
  dat,
  ibi_col = "IBI",
  group_cols = NULL,
  scales = 1:10,
  m = 2,
  r_multiplier = 0.2,
  min_intervals = 20
)

Arguments

Value

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

Extract HRV recurrence quantification analysis features

Description

Computes dependency-light recurrence quantification analysis (RQA) features from IBI/RR intervals. This is intended as a compact nonlinear HRV summary and not as a clinical diagnostic tool.

Usage

extract_gazepoint_hrv_rqa(
  dat,
  ibi_col = "IBI",
  group_cols = NULL,
  embedding_dimension = 2,
  delay = 1,
  radius = NULL,
  radius_multiplier = 0.2,
  min_line_length = 2
)

Arguments

Value

A list with overview, features, and settings.

Extract PPG-derived respiration proxy signals

Description

Extracts dependency-light PPG-derived respiration proxy features from a Gazepoint pulse/PPG waveform. The function estimates respiration-modulated pulse features such as respiratory-induced intensity variability (RIIV), pulse amplitude variability (PAV), pulse width variability (PWV), and pulse-rate variability (PRV).

Usage

extract_gazepoint_pdr_signals(
  dat,
  ppg_col = "HRP",
  time_col = "CNT",
  group_cols = NULL,
  sampling_rate = NULL,
  min_peak_distance_s = 0.3,
  smooth_window = 5,
  respiration_band = c(0.1, 0.6),
  pdr_resample_rate = 4
)

Arguments

Details

These are proxy respiratory features. They should not be treated as a replacement for a respiration belt or clinical respiratory measurement.

Value

A list with overview, pulse_features, pdr_timeseries, pdr_summary, and settings.

Extract respiration proxy using a CEEMDAN-style bridge

Description

Extracts respiration-like components from PPG or ECG-derived respiratory proxy signals. If external_fun is supplied, it is used as the CEEMDAN backend. Otherwise, the function uses a dependency-light multiscale decomposition fallback and labels the result accordingly.

Usage

extract_gazepoint_respiration_ceemdan(
  dat,
  signal_col,
  time_col = "CNT",
  group_cols = NULL,
  sampling_rate = NULL,
  respiration_band = c(0.1, 0.6),
  scales = c(5, 15, 30, 60, 120),
  external_fun = NULL
)

Arguments

Details

This function does not claim to reproduce full CEEMDAN unless a validated external CEEMDAN function is supplied.

Value

A list with overview, component_table, respiration_timeseries, summary, and settings.

Extract SCR recovery times

Description

Extracts 50 percent half-recovery time (rec.t2) and 63 percent recovery time (rec.tc) for skin conductance responses from an EDA waveform and event onsets.

Usage

extract_gazepoint_scr_recovery_times(
  dat,
  eda_col = "GSR_US",
  time_col = "CNT",
  event_onset_col = NULL,
  group_cols = NULL,
  pre_onset_baseline_s = 2,
  peak_window_s = 5,
  recovery_window_s = 20
)

Arguments

Value

A list with overview, recovery_table, and settings.

Extract Gazepoint TTL marker events

Description

Extracts TTL marker events from Gazepoint Biometrics exports. The function can return either rows where TTL marker values change or all nonzero TTL rows. By default, rows are retained only when the TTL validity column is present and greater than zero. This avoids treating invalid placeholder TTL values as experimental events.

Usage

extract_gazepoint_ttl_events(
  data,
  ttl_columns = NULL,
  group_columns = NULL,
  validity_column = "TTLV",
  require_validity = TRUE,
  mode = c("changes", "nonzero"),
  include_initial = TRUE
)

Arguments

Value

A data frame of TTL events.

Filter implausible Gazepoint IBI values

Description

Flags and optionally cleans implausible inter-beat interval values. The helper is conservative and does not remove rows; instead, it returns row-level flags and a cleaned IBI column with implausible values set to NA.

Usage

filter_gazepoint_ibi_implausible(
  data,
  ibi_col = "IBI",
  time_col = NULL,
  group_cols = NULL,
  validity_col = NULL,
  unit = c("auto", "ms", "seconds"),
  min_ibi_ms = 300,
  max_ibi_ms = 2000,
  max_change_ms = 400,
  max_change_prop = 0.3,
  output_col = "IBI_clean_ms"
)

Arguments

Value

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

Flag EDA artifacts with a user-supplied SVM-style model

Description

Applies a user-supplied model or prediction function to segment-level artifact features. No pretrained model is bundled, so this function avoids pretending to reproduce any proprietary or externally trained classifier.

Usage

flag_gazepoint_artifacts_svm(
  x,
  model = NULL,
  feature_cols = NULL,
  probability_threshold = 0.5,
  ...
)

Arguments

Value

A data frame with artifact probabilities/classes where available.

Flag biometric dropouts and flatline periods

Description

Flags missing-value runs and sustained flatline runs in Gazepoint biometric signal columns. Missing dropouts are defined as consecutive missing or non-finite numeric samples. Flatline dropouts are defined as consecutive finite numeric samples that remain unchanged within a tolerance.

Usage

flag_gazepoint_biometric_dropouts(
  data,
  signal_cols = NULL,
  group_cols = NULL,
  time_col = NULL,
  min_missing_run = 5L,
  min_flatline_run = 10L,
  constant_tolerance = 0,
  prefix = "biometric_dropout"
)

Arguments

Details

The function adds row-level flags and stores a dropout summary in the returned data frame attributes. It does not remove rows.

Value

The input data frame with added logical dropout columns. The attributes dropout_summary and dropout_settings contain structured summaries.

Examples

df <- data.frame(
  CNT = 1:8,
  GSR = c(1, NA, NA, NA, 2, 2, 2, 3),
  HR = c(70, 71, 72, 73, 74, 75, 76, 77)
)
flag_gazepoint_biometric_dropouts(df, min_missing_run = 3, min_flatline_run = 3)

Flag MAD-based EDA wearable artifacts

Description

Flags dependency-light, subject-specific EDA artifact categories using robust median absolute deviation (MAD) logic. The categories are heuristic QC labels: step artifacts, needle artifacts, flatline artifacts, and wall artifacts.

Usage

flag_gazepoint_mad_artifacts(
  dat,
  eda_col = "GSR_US",
  time_col = NULL,
  group_cols = NULL,
  mad_multiplier = 8,
  flatline_tolerance = 1e-06,
  flatline_min_run = 5,
  wall_abs_change = NULL,
  output_prefix = "mad"
)

Arguments

Value

A data frame with artifact flags and artifact-summary attributes.

Flag EDA artifacts using transparent Kleckner-style heuristics

Description

Applies simple transparent EDA artifact flags: non-finite values, physiological range violations, rapid percent change per second, and transitional padding around flagged samples.

Usage

flag_kleckner_eda_artifacts(
  dat,
  eda_col = "GSR_US",
  time_col = NULL,
  group_cols = NULL,
  min_us = 0.01,
  max_us = 100,
  max_abs_percent_change_per_second = 20,
  transition_padding = 1,
  output_prefix = "kleckner"
)

Arguments

Details

This helper is Kleckner-style rather than a claim of exact reproduction of every rule in a specific external implementation.

Value

A data frame with artifact flag columns and summary attributes.

Format the gpbiometrics feature inventory for users

Description

Adds user-facing labels and interpretation metadata to the package feature inventory. This helper is intentionally non-breaking: it does not replace the core inventory object returned by create_gazepoint_biometrics_feature_inventory().

Usage

format_gazepoint_biometrics_feature_inventory(
  inventory = NULL,
  include_internal = FALSE,
  sort = TRUE
)

Arguments

Value

A data frame with polished user-facing inventory columns.

Fuse respiration proxies using a Kalman filter

Description

Fuses two respiration proxy streams, such as PPG-derived respiration and ECG-derived respiration, using a transparent one-dimensional Kalman filter. This is a linear Kalman fusion helper. It is not an extended Kalman filter unless the user supplies nonlinear state/measurement logic externally.

Usage

fuse_gazepoint_respiration_kalman(
  dat,
  primary_col,
  secondary_col,
  time_col = NULL,
  group_cols = NULL,
  process_var = 0.01,
  primary_var = 0.05,
  secondary_var = 0.05,
  output_col = "respiration_kalman_fused"
)

Arguments

Value

A data frame with fused respiration output and Kalman attributes.

Extract stored plot data

Description

Extract stored plot data

Usage

get_gazepoint_plot_data(plot)

Arguments

Value

A data frame.

Extract stored plot settings

Description

Extract stored plot settings

Usage

get_gazepoint_plot_settings(plot)

Arguments

Value

A list.

Import a folder of Gazepoint Biometrics exports

Description

Reads rectangular Gazepoint CSV exports from a folder and combines files that contain at least one known Gazepoint Biometrics column. This function is designed for all-gaze and fixation-style exports. Multi-section Gazepoint Data Summary files should be parsed separately.

Usage

import_gazepoint_biometric_folder(
  path,
  pattern = "\\.csv$",
  recursive = FALSE,
  include_fixations = TRUE,
  include_all_gaze = TRUE,
  include_other_csv = FALSE,
  na = c("", "NA", "NaN")
)

Arguments

Value

A data frame with all imported rows combined. The output includes a source_file column and has class "gazepoint_biometrics_folder".

Import a Gazepoint Biometrics export

Description

Reads a Gazepoint CSV export containing biometric columns such as GSR, heart rate, interbeat interval, pulse signal, engagement dial, and TTL synchronization fields. The function is conservative: it preserves original column names, removes only empty trailing columns, and attaches a basic biometric-column summary as an attribute.

Usage

import_gazepoint_biometrics(file, na = c("", "NA", "NaN"))

Arguments

Value

A data frame with Gazepoint export columns preserved. The returned object has class "gazepoint_biometrics" and an attribute named "biometric_columns".

Import a Gazepoint Data Summary export

Description

Reads a multi-section Data_Summary_export_*.csv file produced by Gazepoint Analysis. These files are not ordinary rectangular CSV files. They contain metadata followed by sections such as ⁠AOI Summary⁠ and ⁠AOI Statistics (for each user)⁠. The latter may include AOI-level biometric summaries such as average dial value, average GSR, average heart rate, average interbeat interval, and pupil diameter.

Usage

import_gazepoint_data_summary(file)

Arguments

Value

A list with metadata, aoi_summary, and aoi_statistics data frames. The returned object has class "gazepoint_data_summary".

Import Gazepoint-related streams from an LSL/XDF file

Description

Reads an XDF file through the optional Python pyxdf package via reticulate. This supports high-end LSL workflows without making Python a hard dependency of gpbiometrics.

Usage

import_gazepoint_lsl_xdf(
  path,
  stream_name_pattern = "Gazepoint|GP3|GSR|EDA|Biometric|TTL|Pupil|Gaze",
  include_all_streams = FALSE,
  flatten = TRUE,
  pyxdf_module = "pyxdf"
)

Arguments

Value

A list with overview, streams, header, and settings.

Join Gazepoint Biometrics data to gp3tools-style eye-tracking data

Description

Compatibility wrapper for join_gazepoint_biometrics_to_master(). This alias is provided for users who work with a gp3tools master table and want an explicit gp3tools-facing function name. The implementation delegates to the canonical biometric-to-master join helper.

Usage

join_gazepoint_biometrics_to_gp3tools(biometrics, gp3tools_master, ...)

Arguments

Value

The output of join_gazepoint_biometrics_to_master().

Examples

biometrics <- data.frame(USER = rep("P1", 3), CNT = 1:3, HR = c(70, 71, 72))
master <- data.frame(USER = rep("P1", 3), CNT = 1:3, AOI = c("A", "B", "A"))
join_gazepoint_biometrics_to_gp3tools(
  biometrics,
  master,
  by = c("USER", "CNT")
)

Join Gazepoint Biometrics to a master table

Description

Convenience wrapper around sync_gazepoint_biometrics_with_gaze() for joining biometric data to a gp3tools-style master table or any other analysis-ready gaze table.

Usage

join_gazepoint_biometrics_to_master(master, biometrics, by, all_x = TRUE)

Arguments

Value

A data frame with biometric columns joined to the master table.

Model EDA events as a dependency-light point process

Description

Creates event-time, inter-event interval, and inverse-Gaussian-style summary tables for EDA/SCR events. Events can be supplied directly through an event column or derived from positive EDA-derivative bursts.

Usage

model_gazepoint_eda_point_process(
  dat,
  eda_col = "GSR_US",
  time_col = "CNT",
  group_cols = NULL,
  event_time_col = NULL,
  event_indicator_col = NULL,
  derivative_mad_multiplier = 6,
  min_event_distance_s = 1
)

Arguments

Details

This function is a compact point-process summary/model-preparation helper. It does not fit a full latent sympathetic state-space model.

Value

A list with overview, event_table, interval_table, process_summary, and settings.

Model heartbeats as a dependency-light point process

Description

Creates beat-time, interbeat interval, and inverse-Gaussian-style summary tables from IBI/RR intervals. This is a compact point-process model-preparation helper, not a full adaptive Bayesian heartbeat filter.

Usage

model_gazepoint_hr_point_process(
  dat,
  ibi_col = "IBI",
  time_col = NULL,
  beat_time_col = NULL,
  group_cols = NULL,
  ibi_units = c("auto", "seconds", "milliseconds")
)

Arguments

Value

A list with overview, beat_table, interval_table, process_summary, and settings.

Model heartbeat timing using an IPFM-style impulse train

Description

Builds an impulse-train representation of heartbeat timing from IBI/RR intervals or beat times and computes a simple spectrum of the resulting impulse train. This is an IPFM-style model-preparation helper, not a perfect reconstruction of sinoatrial-node physiology.

Usage

model_gazepoint_hrv_ipfm(
  dat,
  ibi_col = "IBI",
  beat_time_col = NULL,
  group_cols = NULL,
  ibi_units = c("auto", "seconds", "milliseconds"),
  output_sampling_rate = 4,
  max_frequency = 0.5
)

Arguments

Value

A list with overview, beat_table, impulse_table, spectrum_table, summary, and settings.

Optimise subject-specific cvxEDA slow time constant

Description

Performs a dependency-light grid search over the slow Bateman impulse-response time constant used in cvxEDA-style EDA decomposition workflows. The default fast time constant is fixed at 0.7 seconds and the slow time constant is searched between 2 and 4 seconds. This function does not run the original cvxEDA optimisation; it provides a subject-specific tau-selection bridge for downstream cvxEDA-style workflows.

Usage

optimize_gazepoint_cvxeda_tau(
  dat,
  eda_col = "GSR_US",
  time_col = "CNT",
  group_cols = NULL,
  tau0_grid = seq(2, 4, by = 0.25),
  tau1 = 0.7,
  sampling_rate = NULL,
  ridge_lambda = 0.01,
  max_irf_seconds = 20
)

Arguments

Value

A list with overview, best_tau, optimization_table, and settings.

Plot AOI-linked biometric summaries

Description

Plots AOI-biometric summary values as a ggplot object.

Usage

plot_gazepoint_aoi_biometrics(
  x,
  value_col = "mean_value",
  aoi_col = "aoi_label",
  signal_col = "signal",
  group_col = NULL,
  plot_type = c("boxplot", "point", "line"),
  title = NULL
)

Arguments

Value

A ggplot object with plot data stored in attributes.

Plot Gazepoint biometric quality indicators

Description

Plots and summarises biometric quality indicators such as dropout flags, validity flags, missingness flags, and quality/audit flags. When no explicit quality columns are available, the function can derive missingness indicators from detected biometric signal columns.

Usage

plot_gazepoint_biometric_quality(
  data,
  quality_cols = NULL,
  signal_cols = NULL,
  time_col = NULL,
  group_col = NULL,
  dropout_prefix = "biometric_dropout",
  max_points = 5000L,
  main = NULL,
  plot = TRUE,
  ...
)

Arguments

Value

A list with overview, quality_summary, group_summary, plot_data, and settings.

Examples

df <- data.frame(
  CNT = 1:5,
  GSR = c(1, NA, 1.2, 1.1, NA),
  HR_valid = c(1, 1, 0, 1, 1)
)
plot_gazepoint_biometric_quality(df, signal_cols = "GSR", plot = FALSE)

Create a lightweight Gazepoint biometric QC plot dashboard

Description

Creates a lightweight dashboard object containing QC plots for signal activity and time-reset diagnostics. This is a structured list of ggplot objects, not a Shiny application. The dashboard is intended for report preparation and manual QC review.

Usage

plot_gazepoint_biometric_report_dashboard(
  data = NULL,
  signal_activity = NULL,
  time_resets = NULL,
  signal_cols = NULL,
  group_cols = NULL,
  time_col = NULL,
  include_signal_activity = TRUE,
  include_time_resets = TRUE,
  max_groups = 30,
  continue_on_error = TRUE,
  title_prefix = "Gazepoint biometric QC"
)

Arguments

Value

A list with overview, plots, errors, inputs, and settings.

Plot Gazepoint biometric signal time series

Description

Plots one or more Gazepoint biometric signals using base R graphics and returns the plotted data and signal summary. The helper is intentionally descriptive and does not infer emotional valence, cognition, or HRV from raw biometric columns.

Usage

plot_gazepoint_biometric_signals(
  data,
  signal_cols = NULL,
  time_col = NULL,
  group_col = NULL,
  max_points = 5000L,
  standardize = FALSE,
  type = c("line", "points", "both"),
  main = NULL,
  xlab = NULL,
  ylab = NULL,
  legend = TRUE,
  plot = TRUE,
  ...
)

Arguments

Value

A list with overview, plot_data, signal_summary, 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)
)
plot_gazepoint_biometric_signals(df, time_col = "CNT", plot = FALSE)

Plot Gazepoint EDA decomposition channels

Description

Plots available EDA/GSR decomposition channels, typically GSR_US, GSR_US_TONIC, and GSR_US_PHASIC, as a ggplot object.

Usage

plot_gazepoint_eda_decomposition(
  data,
  time_col = NULL,
  signal_cols = NULL,
  group_cols = NULL,
  standardise = FALSE,
  max_points = 5000,
  title = NULL
)

Arguments

Value

A ggplot object with plot data stored in attributes.

Plot an EDA-gram-style time-frequency representation

Description

Creates a dependency-light EDA-gram-style representation using sliding-window spectral power. This is inspired by EDA-gram visualisations, but it does not implement a full sparse dictionary decomposition unless such a model is supplied externally.

Usage

plot_gazepoint_eda_gram(
  dat,
  eda_col = "GSR_US",
  time_col = "CNT",
  group_cols = NULL,
  group_id_to_plot = NULL,
  sampling_rate = NULL,
  window_seconds = 30,
  step_seconds = 5,
  frequency_range = c(0.01, 0.5),
  frequency_bins = 64,
  log_power = TRUE,
  plot = TRUE,
  main = "EDA-gram"
)

Arguments

Value

Invisibly returns a list with overview, gram_table, plot_matrix, and settings.

Plot multimodal Gazepoint biometric timelines

Description

Creates a conservative timeline plot for one or more biometric channels. The plot is intended for inspection, synchronization checks, and reporting support. It does not interpret electrodermal activity as emotional valence.

Usage

plot_gazepoint_multimodal_timeline(
  data,
  time_col = NULL,
  signal_cols = NULL,
  group_cols = NULL,
  participant_col = NULL,
  stimulus_col = NULL,
  trial_col = NULL,
  event_time_col = NULL,
  event_col = NULL,
  standardise = TRUE,
  show_event_markers = TRUE,
  title = NULL
)

Arguments

Value

A ggplot object with the long plotting data stored in the plot_data attribute and settings stored in the settings attribute.

Plot Gazepoint saccade main-sequence diagnostics

Description

Plots saccade amplitude against peak velocity. The function expects saccade-level amplitude and peak-velocity columns. If raw sample-level data are supplied, users should first derive saccade-level kinematics with a validated fixation/saccade detector.

Usage

plot_gazepoint_saccade_main_sequence(
  dat,
  amplitude_col = NULL,
  peak_velocity_col = NULL,
  group_col = NULL,
  log_axes = TRUE,
  add_smoother = TRUE,
  main = "Gazepoint saccade main-sequence diagnostic"
)

Arguments

Value

Invisibly returns the plotted data and settings.

Plot Gazepoint SCR events on an EDA signal

Description

Plots an EDA/GSR signal with detected SCR peak markers and optional event onsets from SCR event-window summaries or event tables.

Usage

plot_gazepoint_scr_events(
  data,
  scr_peaks,
  event_windows = NULL,
  events = NULL,
  time_col = NULL,
  signal_col = NULL,
  phasic_col = NULL,
  group_cols = NULL,
  show_events = TRUE,
  max_points = 5000,
  title = NULL
)

Arguments

Value

A ggplot object with plot data stored in attributes.

Plot an SCR specification curve

Description

Plots a specification-curve style display from the output of run_gazepoint_scr_multiverse() or from a compatible data frame.

Usage

plot_gazepoint_scr_specification_curve(
  x,
  estimate_col = NULL,
  specification_col = "specification_id",
  add_zero_line = TRUE,
  main = "SCR specification curve"
)

Arguments

Value

Invisibly returns a list with plot data and settings.

Plot Gazepoint biometric signal activity

Description

Plots signal-activity summaries produced by audit_gazepoint_signal_activity(), or computes them from a biometric data frame. The plot is intended for quality-control review of signal availability, missingness, zero activity, and basic activity status. It does not infer emotion, valence, cognition, preference, trust, or physiological diagnosis.

Usage

plot_gazepoint_signal_activity(
  data,
  signal_cols = NULL,
  group_cols = NULL,
  metric = c("active_signal", "nonzero_prop", "missing_prop", "n_unique_finite"),
  max_groups = 30,
  title = NULL
)

Arguments

Value

A ggplot object with the package plot contract attached.

Plot Gazepoint time resets and time-order flags

Description

Plots row-level time/counter progression and flags from audit_gazepoint_time_resets(), or computes them from a biometric data frame. The plot is intended for synchronization and file-structure QC. It does not establish causal timing or true physiological latency.

Usage

plot_gazepoint_time_resets(
  data,
  time_col = NULL,
  group_cols = NULL,
  max_groups = 30,
  title = NULL
)

Arguments

Value

A ggplot object with the package plot contract attached.

Prepare AOI-biometric model data

Description

Converts AOI-biometric summaries into a modelling-ready table for GLM/LMM/GLMM workflows.

Usage

prepare_gazepoint_aoi_biometrics_model_data(
  x,
  outcome_col = "mean_value",
  predictor_cols = c("aoi_label", "signal"),
  factor_cols = c("aoi_label", "signal"),
  numeric_cols = NULL,
  group_cols = NULL,
  drop_missing_outcome = TRUE,
  min_rows = NULL,
  standardise_outcome = FALSE,
  standardise_within = c("signal", "all")
)

Arguments

Value

A list with overview, model_data, variable_summary, model_formulas, and settings.

Prepare EDA artifact-classifier segment features

Description

Creates segment-level features that can be passed to a user-supplied artifact classifier such as an SVM. No pretrained classifier is bundled.

Usage

prepare_gazepoint_artifact_svm_features(
  dat,
  eda_col = "GSR_US",
  time_col = NULL,
  group_cols = NULL,
  segment_seconds = 5,
  samples_per_segment = NULL,
  sampling_rate = NULL
)

Arguments

Value

A segment-level feature data frame.

Prepare Gazepoint biometric summaries for mixed-model analysis

Description

Prepares biometric window-level or event-level summaries for downstream mixed-model analysis. This helper does not fit a model. It checks variables, optionally baseline-corrects the selected outcome, optionally scales numeric predictors, converts grouping/factor variables, flags complete cases, and returns a conservative model formula.

Usage

prepare_gazepoint_biometrics_lme_data(
  data,
  outcome_col,
  fixed_effect_cols = NULL,
  condition_cols = NULL,
  covariate_cols = NULL,
  random_effect_cols = NULL,
  participant_col = NULL,
  stimulus_col = NULL,
  trial_col = NULL,
  window_col = NULL,
  baseline_col = NULL,
  baseline_correct = FALSE,
  factor_cols = NULL,
  continuous_cols = NULL,
  scale_continuous = FALSE,
  include_window = TRUE,
  drop_missing = TRUE,
  min_rows = 10
)

Arguments

Value

A list with overview, data, model_data, model_formula, variable_summary, and settings.

Prepare Gazepoint EDA data for CTSI sparse deconvolution workflows

Description

Prepares signal, event, and configuration tables for downstream continuous-time system identification (CTSI) sparse EDA deconvolution workflows. This function does not implement the full Amin-Faghih CTSI solver in R. It creates reproducible input objects and optional CSV files for external CTSI implementations.

Usage

prepare_gazepoint_ctsi_input(
  dat,
  eda_col = "GSR_US",
  time_col = "CNT",
  group_cols = NULL,
  event_onset_col = NULL,
  event_name_col = NULL,
  sampling_rate = NULL,
  tau0_range = c(2, 4),
  tau1_range = c(0.5, 1),
  sparsity_grid = c(0.001, 0.01, 0.1, 1),
  output_dir = NULL,
  prefix = "gazepoint_ctsi"
)

Arguments

Value

A list with overview, signal_table, event_table, ctsi_config, ctsi_notes, written_files, and settings.

Prepare Gazepoint EDA input for external cvxEDA-style workflows

Description

Prepares a clean Gazepoint EDA/conductance time-series table that can be exported for external cvxEDA-style workflows. This function does not run a native cvxEDA solver and does not attempt to reproduce cvxEDA internally.

Usage

prepare_gazepoint_cvxeda_input(
  data,
  eda_col = NULL,
  time_col = NULL,
  group_cols = NULL,
  sampling_rate = NULL,
  time_unit = c("auto", "ms", "seconds", "samples"),
  convert_resistance_to_us = FALSE,
  min_finite_prop = 0.5,
  output_dir = NULL,
  prefix = "gazepoint_cvxeda"
)

Arguments

Value

A list with overview, signal_table, group_summary, manifest, and settings.

Prepare Gazepoint EDA input for external Ledalab-style workflows

Description

Prepares a clean Gazepoint EDA/conductance time-series table that can be exported for external Ledalab-style workflows. This function does not run Ledalab and does not attempt to reproduce Ledalab internally.

Usage

prepare_gazepoint_ledalab_input(
  data,
  eda_col = NULL,
  time_col = NULL,
  group_cols = NULL,
  sampling_rate = NULL,
  time_unit = c("auto", "ms", "seconds", "samples"),
  convert_resistance_to_us = FALSE,
  min_finite_prop = 0.5,
  output_dir = NULL,
  prefix = "gazepoint_ledalab"
)

Arguments

Value

A list with overview, signal_table, group_summary, manifest, and settings.

Prepare Gazepoint multimodal model data

Description

Creates a model-ready table from Gazepoint biometric window summaries and, optionally, eye-tracking summaries produced by gp3tools or another workflow. The function is intentionally conservative: it does not fit a model, impute missing values, or remove rows automatically.

Usage

prepare_gazepoint_multimodal_model_data(
  biometrics,
  eye_tracking = NULL,
  group_columns = NULL,
  biometric_is_summarised = FALSE,
  by = NULL,
  all = FALSE
)

Arguments

Value

A data frame with class "gazepoint_multimodal_model_data" and a "model_data_summary" attribute.

Prepare Gazepoint EDA input for NeuroKit2-style workflows

Description

Prepares EDA/GSR signal tables for optional external NeuroKit2 processing. This helper does not require Python or NeuroKit2.

Usage

prepare_gazepoint_neurokit_eda_input(
  data,
  eda_col = "GSR_US",
  time_col = NULL,
  group_cols = NULL,
  sampling_rate = NULL,
  output_dir = NULL,
  prefix = "gazepoint_neurokit_eda"
)

Arguments

Value

A list with overview, eda_table, group_summary, manifest, and settings.

Prepare Gazepoint EDA data for PsPM DCM workflows

Description

Prepares Gazepoint EDA data and event metadata for downstream PsPM dynamic causal modelling workflows. This function does not run PsPM or invert a DCM model in R. It creates structured input tables and notes for MATLAB/PsPM.

Usage

prepare_gazepoint_pspm_dcm_input(
  dat,
  eda_col = "GSR_US",
  time_col = "CNT",
  event_onset_col = NULL,
  event_duration_col = NULL,
  event_name_col = NULL,
  participant_col = NULL,
  session_col = NULL,
  sampling_rate = NULL,
  output_dir = NULL,
  prefix = "gazepoint_pspm_dcm"
)

Arguments

Value

A list with overview, signal_table, event_table, pspm_notes, written_files, and settings.

Prepare Gazepoint EDA input for external PsPM-style workflows

Description

Prepares a clean Gazepoint EDA/conductance time-series table that can be exported for external PsPM-style workflows. This function does not run PsPM and does not attempt to reproduce PsPM internally.

Usage

prepare_gazepoint_pspm_input(
  data,
  eda_col = NULL,
  time_col = NULL,
  group_cols = NULL,
  sampling_rate = NULL,
  time_unit = c("auto", "ms", "seconds", "samples"),
  convert_resistance_to_us = FALSE,
  min_finite_prop = 0.5,
  output_dir = NULL,
  prefix = "gazepoint_pspm"
)

Arguments

Value

A list with overview, signal_table, group_summary, manifest, and settings.

Prepare Gazepoint HRP/PPG waveform input for pyPPG

Description

Prepares a Gazepoint heart-rate pulse waveform column, usually HRP, as a lightweight input table for optional pyPPG workflows. This helper does not call Python, does not require pyPPG, and does not derive HRV features. It only prepares waveform values, timing information when available, and conservative group-level summaries for interoperability review.

Usage

prepare_gazepoint_pyppg_input(
  data,
  ppg_col = NULL,
  time_col = NULL,
  group_cols = NULL,
  sampling_rate = NULL,
  time_unit = c("auto", "ms", "seconds", "samples"),
  min_finite_prop = 0.5,
  output_dir = NULL,
  prefix = "gazepoint_pyppg"
)

Arguments

Value

A list with overview, waveform_table, group_summary, manifest, and settings.

Prepare Gazepoint IBI/RR data for RHRV

Description

Backward-compatible alias for export_gazepoint_rhrv_input(). This helper prepares analysis-ready inter-beat interval input for optional RHRV workflows. It does not call RHRV and does not derive HRV from Gazepoint's raw HRV field. HRV features should be derived from genuine IBI/RR intervals.

Usage

prepare_gazepoint_rhrv_input(
  data,
  ibi_col = "IBI_clean_ms",
  group_cols = NULL,
  unit = c("auto", "ms", "seconds"),
  collapse_repeated_intervals = TRUE,
  repeated_tolerance_ms = 1e-08,
  min_ibi_ms = 300,
  max_ibi_ms = 2000,
  output_dir = NULL,
  prefix = "gazepoint_rhrv"
)

Arguments

Value

A list returned by export_gazepoint_rhrv_input().

Prepare Gazepoint SCR hurdle-model data

Description

Converts SCR event-window summaries into model-ready data for two-part electrodermal-response analyses: a binary response/no-response component and a positive-amplitude component among response events.

Usage

prepare_gazepoint_scr_hurdle_model_data(
  scr_event_windows,
  response_col = "response_flag",
  amplitude_col = "scr_amplitude",
  latency_col = "scr_latency",
  rise_time_col = "scr_rise_time",
  recovery_time_col = "scr_recovery_time",
  predictor_cols = NULL,
  factor_cols = NULL,
  numeric_cols = NULL,
  group_cols = NULL,
  event_id_col = "event_id",
  amplitude_transform = c("none", "log", "log1p"),
  amplitude_offset = 1e-06,
  drop_missing_predictors = TRUE
)

Arguments

Value

A list with overview, response_model_data, amplitude_model_data, variable_summary, model_formulas, and settings.

Recommend Gazepoint biometric exclusions

Description

Creates window-level and participant-level exclusion recommendations from Gazepoint biometric usable-sample summaries. The function does not remove data. It only creates transparent keep, review, or exclude recommendations.

Usage

recommend_gazepoint_biometric_exclusions(
  data,
  group_columns = NULL,
  data_is_window_summary = FALSE,
  participant_column = NULL,
  gsr_min_usable_pct = 50,
  hr_min_usable_pct = 50,
  dial_min_usable_pct = 50,
  require_gsr = TRUE,
  require_hr = TRUE,
  require_dial = FALSE
)

Arguments

Value

A list with overview, window_recommendations, participant_recommendations, and settings.

Regress stimulus luminance from pupil diameter

Description

Regresses continuous pupil diameter on frame-wise or sample-wise stimulus luminance and returns a luminance-adjusted pupil series. This controls a major visual confound but does not prove that residual pupil changes are cognitive-load-only effects.

Usage

regress_gazepoint_pupil_luminance(
  dat,
  pupil_col,
  luminance_col,
  group_cols = NULL,
  time_col = NULL,
  output_col = "pupil_luminance_adjusted",
  fitted_col = "pupil_luminance_fitted",
  include_quadratic = TRUE,
  model_by_group = TRUE,
  add_intercept_mean = TRUE
)

Arguments

Value

A data frame with luminance-adjusted pupil columns and attributes.

Run automated exploratory statistics for Gazepoint feature tables

Description

Runs simple exploratory group comparisons for numeric feature columns. The function selects one-way ANOVA when all groups pass Shapiro-Wilk checks and Kruskal-Wallis otherwise. It also performs pairwise post-hoc tests with multiplicity correction.

Usage

run_gazepoint_automated_statistics(
  dat,
  outcome_cols,
  group_col,
  alpha = 0.05,
  p_adjust_method = "holm",
  normality_alpha = 0.05,
  min_group_n = 3
)

Arguments

Details

This is an exploratory reporting helper. It is not a substitute for a preregistered statistical model or expert review of study design.

Value

A list with overview, test_table, posthoc_table, normality_table, and settings.

Run a final real-data readiness gate for Gazepoint biometrics data

Description

Provides conservative pass/warn/fail checks before using real Gazepoint Biometrics exports for analysis or reporting. The function checks basic row count, signal availability, missingness, time ordering, TTL availability, and HRV/IBI caution status. It does not certify data quality or infer emotional states.

Usage

run_gazepoint_biometrics_real_data_readiness(
  data = NULL,
  workflow_result = NULL,
  min_rows = 100,
  min_active_signal_count = 1,
  max_missing_prop = 0.5,
  required_signal_cols = NULL,
  require_gsr_us_preferred = TRUE,
  require_ibi_for_hrv = FALSE,
  time_col = NULL,
  ttl_cols = NULL
)

Arguments

Value

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

Run a Gazepoint Biometrics workflow

Description

Runs a compact end-to-end workflow for Gazepoint Biometrics exports. The workflow imports rectangular all-gaze/fixation-style CSV exports from a folder, validates biometric columns, detects active channels, audits missingness, signal quality, sampling/timing, optionally creates window-level summaries, creates optional biometric exclusion recommendations, extracts optional TTL marker events, and produces checklist and methods-text outputs.

Usage

run_gazepoint_biometrics_workflow(
  path,
  group_columns = NULL,
  recursive = FALSE,
  include_fixations = FALSE,
  include_all_gaze = TRUE,
  include_other_csv = FALSE,
  require_active_signal = TRUE,
  create_exclusion_recommendations = TRUE,
  gsr_min_usable_pct = 50,
  hr_min_usable_pct = 50,
  dial_min_usable_pct = 50,
  extract_ttl_events = TRUE,
  ttl_event_mode = c("changes", "nonzero"),
  audit_sampling = TRUE,
  sampling_group_columns = NULL,
  sampling_time_column = NULL,
  sampling_time_unit = c("samples", "seconds", "milliseconds", "microseconds"),
  expected_sampling_rate_hz = 60
)

Arguments

Value

A list with imported data, validation outputs, missingness summaries, quality audits, sampling/timing audits, optional window summaries, optional exclusion recommendations, optional TTL events, checklist, and methods text. The object has class "gazepoint_biometrics_workflow".

Run a six-phase Gazepoint EDA/GSR analysis pipeline

Description

Runs a conservative six-phase Gazepoint EDA/GSR workflow using native gpbiometrics helpers where possible. The function imports or accepts data, audits signal quality, prepares preprocessing outputs, creates optional external-method bridge inputs, prepares synchronization/model-formatting outputs, attaches model templates, and generates reporting outputs.

Usage

run_gazepoint_eda_analysis_pipeline(
  data = NULL,
  path = NULL,
  eda_col = NULL,
  time_col = NULL,
  group_cols = NULL,
  signal_cols = NULL,
  sampling_rate = NULL,
  baseline_window = NULL,
  event_windows = NULL,
  event_data = NULL,
  lag_signal_pair = NULL,
  convert_resistance_to_us = FALSE,
  prepare_external_bridges = TRUE,
  bridge_methods = c("neurokit", "cvxeda", "ledalab", "pspm"),
  prepare_model_data = TRUE,
  create_reports = TRUE,
  output_dir = NULL,
  prefix = "gazepoint_eda_pipeline",
  continue_on_error = TRUE
)

Arguments

Details

The function does not fit brms or lme4 models, does not run external software, and does not infer emotion, valence, stress, trust, preference, cognition, or diagnosis.

Value

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

Optionally run a NeuroKit2 EDA cross-check

Description

Optionally calls Python/NeuroKit2 on prepared EDA input. By default, execute = FALSE, so no external dependency is required.

Usage

run_gazepoint_neurokit_eda_crosscheck(
  data,
  eda_col = "GSR_US",
  time_col = NULL,
  group_cols = NULL,
  sampling_rate = NULL,
  execute = FALSE,
  python = "python",
  output_dir = tempdir(),
  prefix = "gazepoint_neurokit_crosscheck",
  keep_files = FALSE
)

Arguments

Value

A list with overview, prepared_input, crosscheck_summary, manifest, and settings.

Run blockwise online design optimization decision support

Description

Provides a safe, dependency-light decision-support/simulation helper for online design optimization. The function recommends the next condition by combining expected model-discrimination utility with optional exploration and balancing penalties.

Usage

run_gazepoint_online_design_optimization(
  candidate_table,
  condition_col = "condition",
  utility_col = "expected_utility",
  block_col = NULL,
  cost_col = NULL,
  previous_assignments = NULL,
  exploration_weight = 0.1,
  balance_weight = 0.1,
  maximise = TRUE
)

Arguments

Details

This function does not control stimulus presentation software and should not be used as autonomous real-time experiment control without separate ethical, preregistration, and software-integration review.

Value

A list with overview, ranked_candidates, recommendation, assignment_summary, and settings.

Run a multiverse of SCR scoring specifications

Description

Scores SCR amplitudes across multiple latency windows, thresholds, baseline methods, and response metrics. Optionally applies a user-supplied model function to each specification. This supports transparent sensitivity analysis and specification-curve style reporting.

Usage

run_gazepoint_scr_multiverse(
  dat,
  signal_col = "GSR_US",
  time_col = "time",
  trial_cols = NULL,
  condition_col = NULL,
  participant_col = NULL,
  event_time_col = NULL,
  latency_windows = list(c(1, 3), c(1, 4), c(1, 5)),
  thresholds = c(0.01, 0.05),
  baseline_methods = c("median", "mean"),
  baseline_window = c(-1, 0),
  response_metrics = c("max_minus_baseline"),
  model_function = NULL
)

Arguments

Value

A list with specification grid, scored trials, optional model results, and robustness overview.

Run Gazepoint SCR threshold sensitivity checks

Description

Re-runs SCR peak detection across combinations of amplitude thresholds and minimum peak-distance settings. Optionally, it also carries each peak-detection result through SCR event-window summaries so users can see how preprocessing choices affect event-level response rates.

Usage

run_gazepoint_scr_threshold_sensitivity(
  data,
  phasic_col = NULL,
  signal_col = NULL,
  time_col = NULL,
  group_cols = NULL,
  amplitude_min_values = c(0.005, 0.01, 0.02, 0.03),
  min_peak_distance_values = c(1, 5, 10, 20, 30),
  recovery_fraction = 0.5,
  smooth_width = 1,
  events = NULL,
  event_time_col = NULL,
  event_id_col = NULL,
  event_label_col = NULL,
  ttl_cols = NULL,
  ttl_valid_col = NULL,
  event_detection = c("rising", "active"),
  analysis_window = c(0, 6),
  response_window = c(1, 4),
  peak_selection = c("largest_amplitude", "first_peak"),
  collapse_simultaneous_events = FALSE,
  include_event_windows = TRUE,
  keep_objects = FALSE
)

Arguments

Value

A list with overview, sensitivity_grid, peak_group_summary, event_window_summary, optional objects, and settings.

Launch a lightweight gpbiometrics Shiny dashboard

Description

Launches an optional local Shiny interface for inspecting a Gazepoint Biometrics CSV file. Shiny is optional and is not required to use the package.

Usage

run_gpbiometrics_shiny()

Value

A Shiny application object, launched for interactive use.

Launch a lightweight gpbiometrics Shiny peak/artifact annotator

Description

Launches a local Shiny app for manual EDA peak/artifact annotation. The app lets users upload a Gazepoint CSV, inspect a selected signal, enter manual peak/artifact intervals, and download annotation CSVs.

Usage

run_gpbiometrics_shiny_annotator()

Details

This is an optional local GUI helper. It does not replace automated scoring or infer emotion, stress, cognition, trust, preference, or diagnosis.

Value

A Shiny application object, launched for interactive use.

Screen Gazepoint EDA/SCR nonresponders

Description

Screens groups, usually participants, for low or absent SCR responding using either SCR event-window summaries or SCR peak-detection outputs. The helper reports candidate nonresponders under explicit, user-controlled criteria.

Usage

screen_gazepoint_eda_nonresponders(
  x,
  group_cols = NULL,
  response_col = "response_flag",
  amplitude_col = "scr_amplitude",
  min_events = 1,
  min_response_events = 1,
  min_response_rate = 0.05,
  min_detected_peaks = 1
)

Arguments

Value

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

Simulate Gazepoint-style biometric signals

Description

Generates synthetic Gazepoint-style EDA, PPG, HR, IBI, and TTL-like signals with known ground-truth events. This is intended for teaching, examples, unit tests, and model-validation workflows. It does not generate real participant physiology.

Usage

simulate_gazepoint_biometrics(
  n_seconds = 120,
  sampling_rate = 60,
  participant_id = "sim_p1",
  scr_onsets = NULL,
  scr_rate_per_min = 4,
  pulse_rate_bpm = 72,
  respiration_rate_bpm = 15,
  eda_noise_sd = 0.01,
  ppg_noise_sd = 0.02,
  include_ttl = TRUE,
  seed = NULL
)

Arguments

Value

A list with overview, data, ground_truth, and settings.

Smooth a Gazepoint biometric signal

Description

Adds a simple centered moving-average smoothing column to a Gazepoint Biometrics table. This is intentionally conservative and dependency-free. It does not replace specialised biosignal preprocessing libraries.

Usage

smooth_gazepoint_biometrics(
  data,
  value_column,
  window = 5L,
  output_column = NULL,
  na_rm = TRUE
)

Arguments

Value

A data frame with the added smoothed column.

Adaptive EMA normalization for non-stationary EDA

Description

Applies dependency-light adaptive normalization using an exponential moving average center and robust local scale after IQR-based outlier screening. This preserves local dynamics more than whole-session z-scoring, but it is still a preprocessing transformation and not an emotion/stress classifier.

Usage

standardise_gazepoint_adaptive_ema(
  dat,
  signal_col = "GSR_US",
  group_cols = NULL,
  time_col = NULL,
  alpha = 0.05,
  iqr_multiplier = 1.5,
  suffix = "_adaptive_ema",
  center_suffix = "_ema_center",
  scale_suffix = "_ema_scale",
  min_scale = 1e-08,
  overwrite = FALSE
)

standardize_gazepoint_adaptive_ema(
  dat,
  signal_col = "GSR_US",
  group_cols = NULL,
  time_col = NULL,
  alpha = 0.05,
  iqr_multiplier = 1.5,
  suffix = "_adaptive_ema",
  center_suffix = "_ema_center",
  scale_suffix = "_ema_scale",
  min_scale = 1e-08,
  overwrite = FALSE
)

Arguments