gpbiometricspy

Scientific Python workflows and a guided application for Gazepoint eye-tracking and multimodal psychophysiology.

EDA / SCR · PPG / HRV · pupil · gaze · fixation · AOI · events · synchronization · multimodal QC · modelling · reproducible reporting

Website · Start here · Studio · Workflows · Methods · Plots · API

Start with the interface you need

Studio is the guided application over the same scientific package functions used by the Python API:

python -m pip install "gpbiometricspy[studio]==0.1.8"
gpbiometricspy-studio

Use the full local/private Studio for participant files. The anonymous public demonstration is synthetic-only and blocks external uploads.

Python API:

python -m pip install gpbiometricspy

import gpbiometricspy as gp

data = gp.load_kiosk_demo()
validity = gp.summarise_gazepoint_biometric_validity(data)
events = gp.extract_gazepoint_ttl_events(data)

Optional extras cover interoperability, HeartPy, BioSPPy, pyHRV, NeuroKit2, MNE, LSL/XDF, Bayesian/statistical tooling, Studio, docs, and development.

Research path

Project intake
  → measurement + provenance checks
  → signal-specific QC and processing
  → events / AOIs / multimodal alignment
  → summaries and guarded modelling
  → reporting / certificates / reproducible replay

The package supports Gazepoint import/schema/validity, EDA/SCR, PPG and interval variability, pupil/gaze/fixation/saccade/AOI workflows, TTL/events, clock alignment and timebase provenance, multimodal summaries, design audits, cluster permutation, reporting/certificates, simulation, and MNE/LSL/XDF/external-toolbox interoperability.

For a task-first entry point use the Start here or Workflow map rather than beginning with the raw function index.

Python-native methods

Additive Python-native methods sit outside the frozen gpbiometrics 2.0.0 parity surface. Current families include Gaussian and robust Student-t hierarchical location–scale models; one-factor location, log-scale, and joint random slopes; crossed participant–item intercept, location-slope, scale-slope, and joint location + log-scale random-slope models; grouped mixed and ordinal boosting; timebase/alignment certification; cardiac-source provenance; and a PPG pigmentation / measurement-equity audit that separates signal quality, paired availability, and reference agreement.

The PPG equity workflow supports objective CIELAB/ITA-style pigmentation metadata when available and preserves subjective scales such as Fitzpatrick as subjective provenance rather than converting them into objective pigmentation, race, ethnicity, melanin or ITA. It does not apply a universal pigmentation correction and does not provide clinical SpO₂ validation.

Use the model-selection guide to add complexity only when the design and scientific question require it.

Certified release-preparation baseline

The exact current-main source qualified immediately before the 0.1.8 stable freeze is:

• commit a75eb1d73791213e6e830ff94975f632455632e2;
• frozen semantic reference gpbiometrics 2.0.0;
• 406 / 406 frozen exports implemented, 0 pending;
• exact-main tests: 12 / 12 OS × Python 3.11–3.14 lanes green;
• canonical scientific suite: 874 / 874 tests, 15,612 / 15,612 statements = 100.00%;
• raw branch coverage 7,315 / 7,334 = 99.7409%;
• exactly 19 reviewed structural arcs with 0 unexpected / 0 stale / 0 unaudited branch debt;
• audited branch accounting 7,334 / 7,334 = 100.0000%;
• docs/Pages, CodeQL, deep R↔Python parity, optional-backend interoperability, private real-data validation and release-handoff safety all green.

The STEP evidence tranche was also completed on an authorized local copy of BigIdeasLab_STEP v1.0 under the applicable PhysioNet DUA using exact scientific source dc2b539154f65061a90d360f01503108ad1fd39f. The public repository records only derived aggregate evidence and interpretation boundaries; participant-level restricted rows are not redistributed. ENCoDE remains deferred and is not claimed as empirically executed.

Stable release record

0.1.8 is being frozen from this qualified source on 4 October 2026. Public GitHub/PyPI publication remains fail-closed: the stable candidate must pass the protected pull-request and exact-main release gates before immutable v0.1.8 creation and Trusted Publishing.

Interpretation boundary

gpbiometricspy measures, processes, audits, aligns, summarizes, predicts and models recorded signals. Those operations do not by themselves establish emotion, stress, trust, preference, cognition, diagnosis, sensor validity or causal effects.

In particular, robust heavy-tailed modelling is not an artifact score; random effects/slopes are modelled heterogeneity rather than stable traits; log-scale effects are not measurement-quality scores by definition; permutation importance is predictive rather than causal; timing/cardiac certificates bind declared provenance evidence rather than proving sensor validity; and PPG pigmentation analyses must not be relabelled as generic device fairness or causal optical effects.

See Interpretation guardrails and Measurement accountability.

Documentation

• Start here — route by research task.
• Studio — guided visual workflow and local/public boundaries.
• Workflows — EDA, cardiac, eye tracking, multimodal alignment, QC and interoperability.
• Methods — Python-native modelling and provenance methods.
• Plot gallery — 17 deterministic figures generated in docs CI.
• API — domain-organized 406-function frozen-parity reference.
• Validation & trust — parity, coverage, real-data and application validation.

Citation and archival record

gpbiometricspy 0.1.8 is being frozen on 4 October 2026.

• 0.1.8 version DOI: pending genuine Zenodo ingestion of v0.1.8; no DOI is fabricated before minting
• 0.1.7 version DOI: still pending independent Zenodo verification
• 0.1.6 version DOI: still pending independent Zenodo verification
• Software concept DOI: 10.5281/zenodo.22150872
• 0.1.5 version DOI: 10.5281/zenodo.22672823
• 0.1.4 version DOI: 10.5281/zenodo.22515782
• 0.1.3 version DOI: 10.5281/zenodo.22313884
• 0.1.2 version DOI: 10.5281/zenodo.22150873
• Frozen R semantic-reference DOI: 10.5281/zenodo.21434608
• gpbiometrics article: 10.3390/signals7050086

Until Zenodo mints a genuine 0.1.8 version DOI, cite the immutable GitHub release only after v0.1.8 has actually been created. Before publication, cite the latest public stable release and the software concept DOI.

The frozen R source/tests/docs/articles remain under reference/ as the semantic reference used for parity work. See VALIDATION.md and the documentation site for the complete evidence trail.