# 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:

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