gpbiometricspy

Scientific Python infrastructure and a Shiny application for EDA/SCR, PPG/HRV, pupil, gaze, AOI, synchronization, QC, and multimodal Gazepoint research.

Documentation · Studio · Workflow map · Browse API · Plot gallery · Citation

gpbiometricspy is scientific Python infrastructure for Gazepoint and multimodal psychophysiology workflows spanning EDA/SCR, PPG/HRV, pupil, gaze/AOI, event alignment, quality control, statistics, interoperability, and reproducible reporting. It is the Python counterpart of gpbiometrics, using the supplied gpbiometrics 2.0.0 source release as a frozen semantic reference. gpbiometricspy Studio adds a Shiny for Python application layer that calls the same public package API rather than reimplementing the scientific methods.

What you get

• Complete frozen API contract: all 406 / 406 exported R functions are implemented and registered, with 0 pending exports.
• Literal whole-package coverage: 317 scientific tests, 10,316 statements, 0 missed, and a CI floor of 100%.
• gpbiometricspy Studio: a stateful Shiny interface for intake/QC, annotation, EDA/SCR, PPG/HRV, pupil, gaze/fixation/AOI, events/alignment, multimodal analysis, statistics/modelling, and reporting/reproducibility.
• Scientific-domain navigation: the documentation groups the API into 8 research domains while preserving the complete alphabetical 406-function reference.
• Executable learning material: 26 frozen-R article/vignette companions are paired with Python workflows, examples, and generated figures.
• Reproducible public demo data: a fully synthetic kiosk dataset with 36 participants and 69,120 rows ships with the package.
• Deep validation layers: independent R↔Python golden fixtures, optional-backend interoperability CI, privacy-preserving real-data validation, Studio browser/production CI, and frozen upstream provenance.

The project deliberately distinguishes API completion from an absolute claim that independent R and Python runtimes are numerically identical in every external-library/version combination. The frozen R implementation, tests, documentation, and article sources are retained in reference/ so deeper parity can continue to be audited.

Install

Install the current public release from PyPI:

python -m pip install gpbiometricspy

For optional scientific integrations:

python -m pip install "gpbiometricspy[interop]"

For a source checkout used in package development:

python -m pip install -e ".[dev]"

Individual extras are available for heartpy, biosppy, pyhrv, neurokit, mne, lsl, bayes, stats, studio, studio-test, docs, and dev.

gpbiometricspy Studio

Studio is a repository/application layer over the public package API. In stable 0.1.3, it is included in the Python distribution with installed launch commands.

From a source checkout:

git clone https://github.com/stefanosbalaskas/gpbiometricspy.git
cd gpbiometricspy
python -m pip install -e ".[studio]"
gpbiometricspy-studio

For the synthetic-only public boundary:

gpbiometricspy-studio-public

Or run directly during development:

shiny run --reload studio/app.py

The full Studio accepts research-data files and is intended for local use or an appropriately authenticated/private deployment. The public-demo boundary removes external upload controls and independently rejects server-side external-file consumers; it is designed for the bundled synthetic dataset only. See the Studio guide and DEPLOYMENT.md.

Quick start

import gpbiometricspy as gp

# Load the public synthetic kiosk demo distributed with the package.
data = gp.load_kiosk_demo()
print(data.shape)  # (69120, ...)

# Inspect biometric signal validity / availability.
validity = gp.summarise_gazepoint_biometric_validity(data)

# Extract TTL transitions.
events = gp.extract_gazepoint_ttl_events(data)

# Example native pyHRV-style workflow from IBI values.
hrv = gp.run_gazepoint_pyhrv_style(
    nni_ms=data.loc[data["IBI"].notna(), "IBI"].head(500).to_numpy() * 1000
)

The bundled kiosk demo is fully synthetic and is intended only for examples, testing, and reproducible workflow demonstrations.

Explore the documentation

Start with the route that matches what you want to do:

• Documentation home — package overview, status, entry points, and validation story.
• gpbiometricspy Studio — application map, full/public runtime boundaries, launch commands, reproducibility and deployment.
• Workflow map — choose a path based on the signals and events you recorded.
• Browse API by scientific domain — navigate the 406-function surface by research task rather than alphabetically.
• Complete 406-function reference — exhaustive frozen export reference.
• Examples — EDA/SCR, PPG/HRV, pupil/gaze/AOI, multimodal, QC/reporting, and interoperability examples.
• Articles and tutorials — all 26 frozen R vignette/article companions, organized by scientific topic and backed by executable Python code.
• Plot gallery — figures generated directly by the Python plotting API from bundled synthetic/public data.

Scientific scope

The frozen gpbiometrics 2.0.0 parity surface covers, among other areas:

• Gazepoint biometric file/folder import, schema detection, validation, and QC;
• EDA/GSR/SCR preprocessing, artifacts, response detection, windows, habituation/recovery, spectral and nonlinear descriptors, and external bridges;
• HR/IBI/HRV/PPG processing, pyHRV-style, HeartPy-style and BioSPPy-style workflows, nonlinear HRV, RQA/geometric metrics, and respiratory proxies;
• pupil, gaze, fixation, saccade, AOI, and event-locked multimodal workflows;
• TTL alignment, synchronization drift, LSL/XDF, MNE, and BIDS-oriented bridges;
• cluster permutation testing plus explicit guardrails for designs the frozen R package intentionally refuses;
• reproducibility, preregistration, audit trails, readiness checks, reporting, plots, workflow summaries, simulation, and synthetic smoke testing.

Validation and parity

Development on main goes beyond the 406/406 export freeze. The repository includes independent R↔Python golden fixtures, floor/current optional-backend interoperability CI, executable article companions, platform/Python matrix testing, privacy-preserving real-data validation, and independent Studio unit/browser/production gates.

The current scientific development validation baseline is:

R exports:             406
Implemented exports:   406
Explicit pending:        0
Tests:                 317
Statements:         10,316
Missed:                   0
Statement coverage: 100.00%
CI coverage floor:      100%

Studio additionally runs Python 3.11/3.14 smoke tests, Chromium E2E tests, and deployment-style production/distribution checks. See VALIDATION.md and the documentation site's validation material for the distinction between API parity, executable contract coverage, application validation, and deeper cross-runtime/backend evidence.

Interpretation guardrails

gpbiometricspy preserves the conservative interpretation policy of the R package. Physiological and eye-tracking signals are measurements and derived features; they do not directly establish emotion, stress, cognition, preference, health status, or diagnosis. Pupil measurements remain sensitive to luminance and visual context, and respiration estimates derived from PPG or other surrogate channels are proxies unless independently validated.

Archival and citation

gpbiometricspy 0.1.3 is the current stable release. Its version-specific Zenodo DOI will be recorded after Zenodo ingests the GitHub release; until then the concept DOI identifies the evolving Python software record.

• Software concept DOI: 10.5281/zenodo.22150872
• Previous version DOI (0.1.2): 10.5281/zenodo.22150873
• Frozen R reference DOI: 10.5281/zenodo.21434608
• Published gpbiometrics R-package paper: 10.3390/signals7050086

For reproducible citation of analyses, cite the version DOI corresponding to the software release used. Use the concept DOI when referring to the evolving gpbiometricspy software family.

The peer-reviewed paper describing the original R package is:

Balaskas, S. gpbiometrics: An R Package for Reproducible Analysis and Reporting of Gazepoint Biometrics Exports. Signals 2026, 7, 86. https://doi.org/10.3390/signals7050086

When using gpbiometricspy, cite the Python software release used in the analysis as well. The paper above documents the original R package and its scientific/software lineage; it does not replace the Python package's version-specific software citation.

The R DOI remains separate provenance and is recorded in .zenodo.json as isDerivedFrom; it is not the Python package DOI. GitHub citation metadata are maintained in CITATION.cff.

Reference precedence

When Python and explanatory prose disagree, parity work follows:

1. frozen gpbiometrics 2.0.0 implementation;
2. frozen R tests;
3. formal Rd documentation;
4. vignettes/examples;
5. repository/site explanatory material.

See the documentation site source in docs/, the machine-readable export inventory in reference/r-export-inventory.csv, and VALIDATION.md for the current release gates.