gpbiometrics

gpbiometrics provides reproducible tools for importing, checking, preprocessing, summarising, modelling, and reporting Gazepoint Biometrics and Gazepoint GP3 biometric exports. It is designed for researchers working with electrodermal activity, pulse/heart-rate channels, interbeat intervals, TTL markers, stimulus/event timing, and multimodal Gazepoint workflows.

The package focuses on transparent preprocessing, quality control, analysis-ready tables, reporting outputs, and conservative physiological interpretation. It does not infer emotion, stress, cognition, preference, health status, or diagnosis directly from biometric signals.

When to use gpbiometrics

Use gpbiometrics when you need to:

import Gazepoint biometric exports from a file or folder;
inspect signal availability, missingness, time ordering, and TTL markers;
prepare EDA/GSR, SCR, HR, IBI, HRV, PPG, pupil, and multimodal features;
align biometric signals with experimental windows or TTL events;
create model-ready tables for GLM, mixed-model, or Bayesian workflows;
export reproducible report bundles and readiness summaries;
run optional advanced signal-processing and interoperability checks.

Installation

# Install from the local package folder during development
# install.packages("devtools")
devtools::load_all()

After release, installation can use the package source or repository location selected by the maintainer.

Quick start

library(gpbiometrics)

folder <- "path/to/gazepoint_exports"

dat <- import_gazepoint_biometric_folder(folder)

readiness <- run_gazepoint_biometrics_real_data_readiness(dat)

workflow <- run_gazepoint_biometrics_workflow(
  path = folder,
  include_all_gaze = TRUE,
  include_fixations = FALSE,
  include_other_csv = FALSE,
  expected_sampling_rate_hz = 60
)

summary <- summarise_gazepoint_biometrics_workflow(workflow)
summary

For private real data, keep source exports and generated smoke-test outputs outside the package repository.

Built-in synthetic kiosk demo

gpbiometrics includes a public, fully synthetic Gazepoint-like demo dataset for examples, vignettes, and reproducible workflow checks. The dataset simulates a public-service touchscreen kiosk task and is not derived from real participants.

The synthetic design contains 36 participants, four kiosk tasks per participant, 60 Hz sampling, and 69,120 rows. The task design crosses interface complexity (simple vs. dense) with feedback clarity (clear vs. ambiguous). The exports include gaze, AOI labels, pupil diameter, GSR/EDA, HR, IBI, pulse waveform, engagement dial, TTL markers, and task metadata.

demo_dir <- system.file(
  "extdata",
  "gazepoint_biometrics_kiosk_demo_exports",
  package = "gpbiometrics"
)

workflow <- run_gazepoint_biometrics_workflow(
  path = demo_dir,
  include_all_gaze = TRUE,
  include_fixations = FALSE,
  include_other_csv = FALSE,
  expected_sampling_rate_hz = 60
)

summarise_gazepoint_biometrics_workflow(workflow)

The synthetic kiosk data are intended for package demonstration only. They should not be interpreted as real physiology, emotion, stress, cognition, health status, or diagnosis.

Main workflow

A typical workflow is:

Import exports
  -> inspect schema and signal availability
  -> audit quality, timing, TTL markers, and missingness
  -> preprocess EDA / pulse / IBI / pupil channels
  -> extract SCR, HRV, respiration, AOI, or multimodal features
  -> create analysis-ready windows or model tables
  -> export tables, plots, and report bundles

The package is intentionally modular: users can run the full workflow or call individual helpers for a specific signal, window, or quality-control task.

Core function map

Task	Main helpers
Import Gazepoint biometric files	`import_gazepoint_biometrics()`, `import_gazepoint_biometric_folder()`, `import_gazepoint_data_summary()`
Diagnose workflow readiness	`diagnose_gazepoint_biometrics_workflow()`, `run_gazepoint_biometrics_real_data_readiness()`
Run full workflow	`run_gazepoint_biometrics_workflow()`, `summarise_gazepoint_biometrics_workflow()`
Export report outputs	`create_gazepoint_biometrics_report()`, `export_gazepoint_biometrics_report_bundle()`
Inspect package coverage	`create_gazepoint_biometrics_feature_inventory()`, `gpbiometrics_feature_inventory_table()`
Plot report dashboard	`plot_gazepoint_biometric_report_dashboard()`

EDA, GSR, and SCR tools

gpbiometrics includes tools for EDA/GSR preprocessing, artifact checks, SCR detection, threshold sensitivity, baseline correction, response windows, multiverse checks, and report-ready summaries.

Representative helpers include:

audit_gazepoint_gsr_units()
standardise_gazepoint_adaptive_ema()
classify_gazepoint_scr_intervals()
flag_kleckner_eda_artifacts()
run_gazepoint_scr_multiverse()
extract_gazepoint_scr_recovery_times()
correct_gazepoint_eda_temperature()

Specialised EDA helpers are also available for bilateral EDA asymmetry, skin-potential recordings, AC EDA admittance/susceptance, EDA-gram-style visualisation, cvxEDA/PsPM/Ledalab/cvxEDA-style bridges, and CTSI input preparation. These are optional method-specific helpers and should only be used when the required signal type is actually present.

Pulse, IBI, HR, HRV, and respiration tools

The package supports pulse and heartbeat workflows, including IBI/HR summaries, HRV features, nonlinear descriptors, respiration proxies, point-process summaries, and advanced signal-processing bridges.

Representative helpers include:

extract_gazepoint_hrv_features()
summarise_gazepoint_hrv_features()
prepare_gazepoint_rhrv_input()
extract_gazepoint_hrv_nonlinear()
extract_gazepoint_hrv_rqa()
extract_gazepoint_hrv_geometric()
extract_gazepoint_hrv_rcmse()
extract_gazepoint_hrv_fuzzy_csi()
model_gazepoint_hrv_ipfm()
extract_gazepoint_beats_kmeans()

Respiration-related helpers include PPG-derived respiration, ECG-derived respiration PCA bridges, CEEMDAN-style respiration extraction, RSA proxies, and Kalman fusion of multiple respiration proxy streams. These outputs are signal-derived respiratory proxies, not replacements for direct respiratory-belt recordings unless externally validated.

Timing, TTL, windows, and multimodal alignment

Gazepoint biometric exports are often used together with stimulus timing, TTL markers, AOIs, and event windows. gpbiometrics provides tools for alignment, chunking, and model-ready table creation.

extract_gazepoint_ttl_events()
align_gazepoint_biometrics_to_ttl()
chunk_gazepoint_biometrics()
prepare_gazepoint_biometrics_lme_data()
plot_gazepoint_multimodal_timeline()

Quality control and reporting

The package emphasises explicit quality-control outputs rather than silent deletion or hidden preprocessing. Readiness checks and report bundles help users document what was inspected, what was retained, and what requires caution.

run_gazepoint_biometrics_real_data_readiness()
export_gazepoint_biometrics_report_bundle()
create_gazepoint_biometrics_report_tables()
plot_gazepoint_biometric_report_dashboard()
create_gazepoint_preregistration_template()

Advanced optional methods

Advanced helpers are included for specialised workflows such as:

artifact SVM feature preparation;
optional autoencoder denoising bridges;
wavelet and adaptive smoothing;
entropy, RQA, FuzzyEn, RCMSE, and Lorenz/Poincare-style HRV descriptors;
point-process summaries for EDA and heartbeat timing;
Granger-style cardiorespiratory directionality;
EDA-gram-style visualisation;
AC EDA, skin potential, and bilateral EDA modality support;
online design-optimisation decision support;
surrogate nonlinearity testing;
synthetic biometric signal simulation.

These tools are intended for advanced users who understand the data requirements and assumptions of each method. Several functions are interoperability bridges or dependency-light approximations, not complete reimplementations of external modelling frameworks.

Interpretation guardrails

Biometric signals require conservative interpretation.

EDA/GSR/SCR features describe electrodermal activity and arousal-related physiology; they do not directly identify emotion, stress, preference, cognition, or diagnosis.
HR, IBI, HRV, PPG, and respiration-proxy features describe cardiovascular or signal-derived dynamics; they do not directly identify psychological or clinical states.
Pupil features are strongly affected by luminance and visual context; luminance-adjusted residuals are not proof of cognitive-load-only effects.
Eye-tracking or AOI timing features describe visual allocation and timing; they do not directly prove attention quality, scrutiny, or comprehension.
Advanced models, bridges, and automated statistics should be reviewed against the experimental design before confirmatory use.

Feature inventory

The package includes a programmatic inventory of available functions.

inventory <- create_gazepoint_biometrics_feature_inventory()
formatted_inventory <- format_gazepoint_biometrics_feature_inventory(inventory)
inventory_summary <- summarise_gazepoint_biometrics_feature_inventory(formatted_inventory)

inventory$overview
inventory_summary$domain_summary
head(formatted_inventory)

This is useful for checking which workflows are available and for documenting package coverage in reports or manuscripts.

Private real-data workflow

For private Gazepoint exports, keep raw data outside the package repository.

private_folder <- "path/to/private_gazepoint_exports"
private_output <- file.path(tempdir(), "gpbiometrics_real_check")

workflow <- run_gazepoint_biometrics_workflow(
  path = private_folder,
  include_all_gaze = TRUE,
  include_fixations = FALSE,
  include_other_csv = FALSE,
  expected_sampling_rate_hz = 60
)

summarise_gazepoint_biometrics_workflow(workflow)

export_gazepoint_biometrics_report_bundle(
  workflow,
  output_dir = private_output
)

Do not commit private Gazepoint exports or private smoke-test outputs.

Validation status

Current local validation after the advanced development branches:

devtools::test()
# FAIL 0 | WARN 0 | SKIP 0 | PASS 1649

devtools::check()
# 0 errors | 0 warnings | 0 notes

The recurring Quarto/TMPDIR message can appear during local checks. It is treated as harmless only when the final R CMD check summary reports 0 errors, 0 warnings, and 0 notes.

Citation

If you use gpbiometrics, cite the package version, repository or archive DOI if available, and the specific Gazepoint hardware/software context used in your study. Also cite the original methodological sources for specialised analyses such as cvxEDA, Ledalab, PsPM, RHRV, entropy, point-process, or signal-decomposition methods when those helpers are used.

If you use gpbiometrics, please cite the package with:

citation("gpbiometrics")

The archived software release is available at DOI: 10.5281/zenodo.20836725.

mirror server hosted at Truenetwork, Russian Federation.