gpbiometrics 0.1.0

Overview

• Initial validated development release of gpbiometrics, an R package for importing, validating, quality-checking, preprocessing, synchronising, summarising, modelling, plotting, and reporting Gazepoint Biometrics and Gazepoint GP3 biometric exports.
• The package focuses on Gazepoint-specific biometric channels, including GSR/EDA, heart rate, interbeat intervals, pulse signal, engagement dial, TTL markers, pupil-related columns, AOI fields, and synchronisation variables.
• The current feature inventory contains 155 available user-facing helpers across 11 complete workflow domains.
• Interpretation is intentionally conservative: biometric features are treated as physiological descriptors, quality-control outputs, or analysis-ready signals, not direct labels for emotion, stress, cognition, preference, health status, or diagnosis.

Import, schema, and workflow infrastructure

• Added import helpers for single files and export folders, including import_gazepoint_biometrics(), import_gazepoint_biometric_folder(), import_gazepoint_data_summary(), and import_gazepoint_lsl_xdf().
• Added Gazepoint schema and channel-detection helpers, including check_gazepoint_biometric_columns(), detect_gazepoint_biometric_schema(), detect_gazepoint_time_columns(), detect_active_biometric_channels(), and standardise_gazepoint_biometric_names().
• Added the main workflow wrapper run_gazepoint_biometrics_workflow() and summary/diagnostic helpers, including summarise_gazepoint_biometrics_workflow() and diagnose_gazepoint_biometrics_workflow().
• Added synthetic data generation with simulate_gazepoint_biometrics() for examples, teaching, and controlled validation.

Quality control and readiness

• Added validation, missingness, sampling, signal-activity, time-reset, dropout, distributional-drift, and real-data readiness checks.
• Added run_gazepoint_biometrics_real_data_readiness() as a final readiness gate for real Gazepoint exports.
• Added exclusion-recommendation helpers for participant-level and window-level biometric quality decisions.
• Added artifact-detection helpers, including MAD-based, Kleckner-style, and SVM-feature workflows.
• Added audit_gazepoint_gsr_units() to help distinguish conductance-like and resistance-like GSR columns before downstream EDA/SCR processing.
• Added audit_gazepoint_stabilization_period() for flagging or trimming the initial electrode-stabilisation period.

Preprocessing and signal correction

• Added baseline correction, smoothing, within-unit standardisation, z-score/range correction, adaptive EMA smoothing, wavelet denoising, quantisation-noise handling, and optional autoencoder-denoising bridges.
• Added EDA/GSR unit auditing and conductance-conversion helpers.
• Added environmental and stimulus-confound controls, including correct_gazepoint_eda_temperature(), audit_gazepoint_stabilization_period(), and regress_gazepoint_pupil_luminance().
• Added both British and American spelling aliases where useful, including standardise/standardize variants.

EDA, GSR, and SCR analysis

• Added EDA/GSR quality audits, tonic/phasic summaries, SCR event and peak detection, SCR event-window summaries, nonresponder screening, threshold-sensitivity checks, and SCR multiverse workflows.
• Added SCR recovery-time extraction with extract_gazepoint_scr_recovery_times(), including half-recovery and 63 percent recovery-time summaries.
• Added advanced EDA helpers for spectral power, complexity, TVSymp-style analysis, bilateral EDA asymmetry, skin-potential analysis, AC admittance/susceptance, stochastic change-point screening, and EDA-gram-style visualisation.
• Added external EDA interoperability helpers for Ledalab, PsPM, cvxEDA, NeuroKit-style input, and DCM/CTSI-oriented bridges.
• Added run_gazepoint_automated_statistics() for exploratory group comparisons with normality screening, ANOVA/Kruskal-Wallis selection, post-hoc testing, and multiplicity correction.

Pulse, IBI, HR, HRV, and respiration

• Added HR, IBI, and HRV quality and consistency checks.
• Added HR/IBI window summaries and IBI-derived HRV feature extraction.
• Added nonlinear and geometric HRV descriptors, including RQA, fragmentation, asymmetry, FuzzyEn/CSI, RCMSE, surrogate nonlinearity testing, and IPFM-style impulse-train modelling.
• Added Gazepoint pulse beat-candidate extraction with extract_gazepoint_beats_kmeans().
• Added respiration-related helpers, including PPG-derived respiration, ECG-derived respiration PCA bridges, CEEMDAN-style respiration extraction, RSA proxy calculation, and Kalman fusion of respiration proxy streams.
• Added point-process and cardiorespiratory directionality helpers for advanced exploratory analysis.

TTL, synchronisation, windows, and model-ready data

• Added TTL event extraction and TTL alignment helpers.
• Added signal-lag estimation and synchronisation-drift diagnostics.
• Added multimodal time-window summaries and model-ready table preparation helpers for biometric, AOI-linked, and LME-style analyses.
• Added chunking and online design-optimisation decision-support helpers for advanced experimental workflows.
• Added helpers for synchronising Gazepoint Biometrics outputs with Gazepoint eye-tracking master tables.

AOI-linked biometrics and plotting

• Added AOI-linked biometric summaries, AOI-biometric model data preparation, and AOI-biometric plotting.
• Added biometric signal plots, quality plots, decomposition plots, SCR plots, multimodal timelines, activity/time-reset plots, report dashboards, SCR specification-curve plots, saccade main-sequence plots, and EDA-gram-style plots.
• Added plot-contract helpers to store plot data, settings, and interpretation metadata for reproducibility.

Reporting, feature inventory, and documentation

• Added checklist, methods-text, report-table, report-bundle, preregistration-template, and Shiny/annotator helpers.
• Added create_gazepoint_biometrics_feature_inventory() for programmatic workflow coverage checks.
• Added formatted inventory helpers, format_gazepoint_biometrics_feature_inventory() and summarise_gazepoint_biometrics_feature_inventory().
• Added a compact user-facing README and the first workflow vignette, vignettes/gpbiometrics-workflow.Rmd.
• Updated workflow documentation to use the current run_gazepoint_biometrics_workflow(path = ...) API and to export report bundles through export_gazepoint_biometrics_report_bundle().
• Added a public, fully synthetic Gazepoint-like kiosk demo dataset under inst/extdata/gazepoint_biometrics_kiosk_demo_exports/.
• The demo dataset contains 36 synthetic participants, four kiosk tasks per participant, 69,120 rows, 36 all-gaze CSV exports, task metadata, gaze/AOI fields, pupil columns, GSR/EDA, HR, IBI, pulse waveform, engagement dial, and TTL markers.
• Added data-raw/create_gazepoint_biometrics_kiosk_demo_exports.R to regenerate the synthetic demo exports reproducibly.
• Added package tests to ensure the synthetic kiosk demo remains available, importable, and schema-valid.

Interoperability and optional external methods

• Added RHRV, pyPPG, NeuroKit2, Ledalab, PsPM, cvxEDA, DCM, and CTSI-oriented preparation/export bridges.
• External-method bridges remain optional and do not make external software a hard dependency.
• Advanced bridge functions prepare or structure data for external workflows unless explicit cross-check execution is requested and available.

Validation

• Current local validation passed with:

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

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

• The workflow vignette builds during devtools::check().
• A private real-data smoke test on a local Gazepoint export folder passed import, readiness, workflow, summary, and report-bundle export checks.
• The private workflow used 6 source files, 7340 imported all-gaze rows, 70 columns, 1323 TTL events, 0 validation issues, and 3 active signal groups.
• The private report-bundle export wrote 81 files with 0 skipped items.
• Private data and private smoke-test outputs remain outside the package repository.

Interpretation safeguards

• EDA/GSR/SCR features describe electrodermal dynamics and arousal-related physiology; they do not directly infer emotion, stress, cognition, health status, or diagnosis.
• HR, IBI, HRV, pulse, and respiration-proxy features describe cardiovascular or signal-derived dynamics; they are not clinical labels.
• Pupil outputs are affected by luminance and visual context; luminance-adjusted residuals are not proof of cognitive-load-only effects.
• AOI-linked biometric summaries describe signal values during AOI exposure and do not establish emotional valence, preference, or cognitive evaluation by themselves.
• Automated statistics and advanced models are exploratory/reporting aids unless matched to a preregistered design and reviewed analytically.