
# gpbiometrics

[![R-CMD-check](https://github.com/stefanosbalaskas/gpbiometrics/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/stefanosbalaskas/gpbiometrics/actions/workflows/R-CMD-check.yaml)
[![DOI](https://zenodo.org/badge/1279519183.svg)](https://doi.org/10.5281/zenodo.20836724)

`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

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

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

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

``` text
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:

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

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

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

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

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

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

``` text
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:

``` r
citation("gpbiometrics")
```

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