# gpbiometrics workflow

# Overview

This vignette gives a compact workflow for using `gpbiometrics` with Gazepoint Biometrics or Gazepoint GP3 biometric exports.

The package supports importing, schema checks, signal-quality auditing, preprocessing, feature extraction, TTL alignment, model-ready table preparation, visual diagnostics, and reproducible report generation.

The examples are not evaluated during vignette build because they require local Gazepoint export files.

# Load the package

    library(gpbiometrics)

# Built-in synthetic kiosk demo

The package includes a public synthetic Gazepoint-like demo dataset. It simulates a public-service touchscreen kiosk usability task with 36 synthetic participants and four tasks per participant.

The design crosses interface complexity (`simple` vs. `dense`) with feedback clarity (`clear` vs. `ambiguous`). The files contain 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 dataset is fully artificial and is provided for examples, tests, vignettes, and software demonstration. It is not real participant physiology.

# 1. Import Gazepoint biometric exports

For a single export file:

    dat <- import_gazepoint_biometrics("path/to/biometric_export.csv")

For a folder of exports:

    folder <- "path/to/gazepoint_exports"

    dat <- import_gazepoint_biometric_folder(folder)

For private real data, keep source exports outside the package repository.

# 2. Inspect real-data readiness

Run a readiness gate before modelling or reporting.

    readiness <- run_gazepoint_biometrics_real_data_readiness(dat)

    readiness$overview
    readiness$checks

This step makes data-quality issues explicit, including missing channels, inactive signals, time-ordering problems, TTL availability, and signal-level missingness.

# 3. Run the full workflow

The full workflow can import a folder, create diagnostic outputs, and optionally write plots and reports.

    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

# 4. EDA, GSR, and SCR examples

Common EDA and SCR tasks include unit auditing, smoothing, artifact checks, baseline correction, response-window extraction, and recovery-time estimation.

    unit_audit <- audit_gazepoint_gsr_units(dat)

    smoothed <- standardise_gazepoint_adaptive_ema(
      dat,
      signal_col = "GSR_US",
      time_col = "CNT"
    )

    scr_recovery <- extract_gazepoint_scr_recovery_times(
      dat,
      eda_col = "GSR_US",
      time_col = "CNT",
      event_onset_col = "event_onset"
    )

If ambient or body-temperature covariates are available, EDA can be adjusted for temperature:

    temperature_adjusted <- correct_gazepoint_eda_temperature(
      dat,
      eda_col = "GSR_US",
      temperature_cols = c("ambient_temperature", "body_temperature"),
      group_cols = "participant"
    )

Temperature-adjusted EDA is not “pure” cognitive or emotional EDA. It is an adjusted physiological signal that still requires conservative interpretation.

# 5. Pulse, IBI, HRV, and respiration examples

For IBI/HRV workflows:

    hrv <- extract_gazepoint_hrv_features(
      dat,
      ibi_col = "IBI",
      group_cols = "participant"
    )

    hrv_summary <- summarise_gazepoint_hrv_features(hrv)

Advanced HRV descriptors are available when signal length and quality are adequate:

    nonlinear_hrv <- extract_gazepoint_hrv_nonlinear(
      dat,
      ibi_col = "IBI",
      group_cols = "participant"
    )

    rcmse <- extract_gazepoint_hrv_rcmse(
      dat,
      ibi_col = "IBI",
      group_cols = "participant"
    )

    fuzzy_csi <- extract_gazepoint_hrv_fuzzy_csi(
      dat,
      ibi_col = "IBI",
      group_cols = "participant"
    )

For difficult Gazepoint pulse waveforms, k-means beat extraction can be used as a hardware-oriented fallback:

    beats <- extract_gazepoint_beats_kmeans(
      dat,
      pulse_col = "HRP",
      time_col = "CNT",
      group_cols = "participant"
    )

These beat candidates should be quality-checked before HRV inference.

# 6. TTL alignment and model-ready data

TTL markers and event windows can be used to align biometric signals with the experimental design.

    ttl_events <- extract_gazepoint_ttl_events(dat)

    aligned <- align_gazepoint_biometrics_to_ttl(
      dat,
      ttl_col = "TTL0",
      time_col = "CNT"
    )

    model_data <- prepare_gazepoint_biometrics_lme_data(
      dat,
      outcome_cols = c("GSR_US", "HR"),
      group_cols = c("participant", "condition"),
      time_col = "CNT"
    )

# 7. Reporting bundle

A report bundle can export tables, plots, and text summaries for reproducible documentation.

    bundle <- export_gazepoint_biometrics_report_bundle(
      workflow,
      output_dir = file.path(tempdir(), "gpbiometrics_report_bundle")
    )

# 8. Feature inventory

The package includes a feature inventory for documenting workflow coverage.

    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)

# 9. Interpretation guardrails

`gpbiometrics` follows conservative interpretation principles:

- EDA/GSR/SCR features describe electrodermal dynamics; they do not directly identify 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.
- Automated statistics and advanced models should be reviewed against the study design before confirmatory use.

# 10. Private real-data smoke tests

For private smoke tests, keep data and outputs 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
    )

    summary <- summarise_gazepoint_biometrics_workflow(workflow)
    summary

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