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.

Stable 0.1.4 remains immutable at its historical release evidence (557 tests · 10,316/10,316 statements · 5,575/5,594 raw branches = 99.6604%). Stable 0.1.5 freezes the larger current evidence (567 tests · 10,456/10,456 statements · 5,629/5,648 raw branches = 99.6636%) without rewriting the 0.1.4 record.

What you get

• Complete frozen API contract: all 406 / 406 exported R functions are implemented and registered, with 0 pending exports.
• Stable 0.1.5 validation: 567 tests, 10,456 statements, 0 missed, and a CI statement floor of 100%.
• Audited branch accounting: current raw branch coverage is 5,629 / 5,648 = 99.6636%; the remaining 19 arcs are frozen as reviewed structural/caller-dominated debt, with 0 unexpected, 0 stale, and 0 unaudited missing branches under CI.
• Measurement accountability: stable 0.1.5 adds metric-specific HRV/PRV agreement, retention-first SCR responsivity sensitivity, a five-stage validation ladder, and experimental topology-aware PPG morphology with conservative interpretation boundaries.
• 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.
• Installed-artifact replay validation: production browser tests exercise scientific replay from built wheel and sdist artifacts, including dataset/secondary-resource fingerprint guards, on Python 3.11 and 3.14.
• 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, structural branch-debt enforcement, 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.5, 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

Stable 0.1.5 goes beyond the original 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, branch-path auditing, and independent Studio unit/browser/production gates.

The stable 0.1.5 validation baseline is:

R exports:                  406
Implemented exports:        406
Explicit pending:             0
Tests:                      567
Statements:              10,456
Missed statements:            0
Statement coverage:      100.00%
Statement CI floor:      100.00%
Branches:             5,629/5,648
Raw branch coverage:    99.6636%
Raw branch CI floor:    99.6000%
Audited structural arcs:       19
Unexpected missing arcs:        0
Stale structural entries:       0
Unaudited branch debt:           0
Audited branch accounting: 100.0000%

Raw branch coverage remains the literal coverage.py result; the structural-debt contract does not relabel it as 100%. Instead, CI requires the exact remaining 19 missing arcs to match the reviewed structural/caller-dominated ledger, so any new or stale uncovered path fails independently of the raw percentage. The branch-audit workflow also propagates auditor failures through tee, so a non-zero coverage/debt auditor exit cannot be hidden by pipeline status.

Studio additionally runs Python 3.11/3.14 smoke tests, Chromium E2E tests, and deployment-style production/distribution checks. Stable 0.1.5 extends that evidence into installed wheel/sdist replay for high-value scientific paths and fail-closed input-fingerprint validation. 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.5 is the current stable release source. Its version-specific Zenodo DOI will be recorded only after Zenodo ingests the immutable v0.1.5 GitHub release; the concept DOI identifies the evolving Python software record.

• Version DOI (0.1.5): pending Zenodo ingestion — not yet minted
• Previous version DOI (0.1.4): 10.5281/zenodo.22515782
• Software concept DOI: 10.5281/zenodo.22150872
• Earlier version DOI (0.1.3): 10.5281/zenodo.22313884
• Earlier 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.