Metadata-Version: 2.4
Name: gpbiometricspy
Version: 0.1.8
Summary: Python port of gpbiometrics 2.0.0 for Gazepoint biometric workflows
Author: Stefanos Balaskas
License-Expression: MIT
Project-URL: Homepage, https://stefanosbalaskas.github.io/gpbiometricspy/
Project-URL: Repository, https://github.com/stefanosbalaskas/gpbiometricspy
Project-URL: Documentation, https://stefanosbalaskas.github.io/gpbiometricspy/
Project-URL: RReference, https://stefanosbalaskas.github.io/gpbiometrics/
Project-URL: RReferenceDOI, https://doi.org/10.5281/zenodo.21434608
Project-URL: DOI, https://doi.org/10.5281/zenodo.22150872
Project-URL: PreviousVersionDOI, https://doi.org/10.5281/zenodo.22672823
Project-URL: Issues, https://github.com/stefanosbalaskas/gpbiometricspy/issues
Project-URL: PyPI, https://pypi.org/project/gpbiometricspy/
Keywords: gazepoint,eye-tracking,eda,gsr,hrv,ppg,physiology,pupillometry
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.26
Requires-Dist: pandas>=2.1
Requires-Dist: scipy>=1.11
Requires-Dist: matplotlib>=3.8
Provides-Extra: heartpy
Requires-Dist: heartpy>=1.2.7; extra == "heartpy"
Requires-Dist: setuptools<82,>=77; extra == "heartpy"
Provides-Extra: biosppy
Requires-Dist: biosppy>=2.2.4; extra == "biosppy"
Requires-Dist: peakutils>=1.3.4; extra == "biosppy"
Provides-Extra: pyhrv
Requires-Dist: pyhrv>=0.5.0; extra == "pyhrv"
Requires-Dist: peakutils>=1.3.4; extra == "pyhrv"
Requires-Dist: nolds<0.6.3; extra == "pyhrv"
Requires-Dist: setuptools<82,>=77; extra == "pyhrv"
Provides-Extra: neurokit
Requires-Dist: neurokit2>=0.2.13; extra == "neurokit"
Provides-Extra: mne
Requires-Dist: mne>=1.12.1; extra == "mne"
Provides-Extra: lsl
Requires-Dist: pylsl>=1.18.2; extra == "lsl"
Requires-Dist: pyxdf>=1.17.5; extra == "lsl"
Provides-Extra: bayes
Requires-Dist: pymc>=6.3; extra == "bayes"
Provides-Extra: stats
Requires-Dist: statsmodels>=0.14; extra == "stats"
Provides-Extra: interop
Requires-Dist: heartpy>=1.2.7; extra == "interop"
Requires-Dist: setuptools<82,>=77; extra == "interop"
Requires-Dist: biosppy>=2.2.4; extra == "interop"
Requires-Dist: peakutils>=1.3.4; extra == "interop"
Requires-Dist: pyhrv>=0.5.0; extra == "interop"
Requires-Dist: nolds<0.6.3; extra == "interop"
Requires-Dist: neurokit2>=0.2.13; extra == "interop"
Requires-Dist: mne>=1.12.1; extra == "interop"
Requires-Dist: pylsl>=1.18.2; extra == "interop"
Requires-Dist: pyxdf>=1.17.5; extra == "interop"
Requires-Dist: statsmodels>=0.14; extra == "interop"
Provides-Extra: studio
Requires-Dist: shiny<2,>=1.7; extra == "studio"
Provides-Extra: studio-native
Requires-Dist: shiny<2,>=1.7; extra == "studio-native"
Requires-Dist: pywebview==6.2.1; sys_platform == "win32" and extra == "studio-native"
Provides-Extra: studio-test
Requires-Dist: shiny<2,>=1.7; extra == "studio-test"
Requires-Dist: pytest-playwright<1,>=0.9; extra == "studio-test"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.6; extra == "docs"
Requires-Dist: mkdocs-material>=9.5; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.27; extra == "docs"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-cov>=5; extra == "dev"
Requires-Dist: ruff>=0.9; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=6; extra == "dev"
Dynamic: license-file

<p align="center">
  <img src="https://raw.githubusercontent.com/stefanosbalaskas/gpbiometricspy/main/docs/assets/python-suite-logo.png" width="240" alt="gpbiometricspy Python research package logo">
</p>

<h1 align="center">gpbiometricspy</h1>

<p align="center"><strong>Scientific Python workflows and a guided application for Gazepoint eye-tracking and multimodal psychophysiology.</strong></p>
<p align="center">EDA / SCR · PPG / HRV · pupil · gaze · fixation · AOI · events · synchronization · multimodal QC · modelling · reproducible reporting</p>

<p align="center">
  <a href="https://pypi.org/project/gpbiometricspy/"><img alt="PyPI" src="https://img.shields.io/pypi/v/gpbiometricspy.svg"></a>
  <a href="https://pypi.org/project/gpbiometricspy/"><img alt="Python" src="https://img.shields.io/pypi/pyversions/gpbiometricspy.svg"></a>
  <a href="https://github.com/stefanosbalaskas/gpbiometricspy/actions/workflows/tests.yml"><img alt="Tests" src="https://github.com/stefanosbalaskas/gpbiometricspy/actions/workflows/tests.yml/badge.svg?branch=main"></a>
  <a href="https://github.com/stefanosbalaskas/gpbiometricspy/actions/workflows/docs.yml"><img alt="Documentation" src="https://github.com/stefanosbalaskas/gpbiometricspy/actions/workflows/docs.yml/badge.svg?branch=main"></a>
  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-yellow.svg"></a>
  <a href="https://doi.org/10.5281/zenodo.22150872"><img alt="Concept DOI" src="https://zenodo.org/badge/DOI/10.5281/zenodo.22150872.svg"></a>
</p>

<p align="center">
  <a href="https://stefanosbalaskas.github.io/gpbiometricspy/"><strong>Website</strong></a> ·
  <a href="https://stefanosbalaskas.github.io/gpbiometricspy/start-here/"><strong>Start here</strong></a> ·
  <a href="https://stefanosbalaskas.github.io/gpbiometricspy/studio/"><strong>Studio</strong></a> ·
  <a href="https://stefanosbalaskas.github.io/gpbiometricspy/workflows/"><strong>Workflows</strong></a> ·
  <a href="https://stefanosbalaskas.github.io/gpbiometricspy/methods/"><strong>Methods</strong></a> ·
  <a href="https://stefanosbalaskas.github.io/gpbiometricspy/plot-gallery/"><strong>Plots</strong></a> ·
  <a href="https://stefanosbalaskas.github.io/gpbiometricspy/api/"><strong>API</strong></a>
</p>

---

## Start with the interface you need

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

```bash
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**:

```bash
python -m pip install gpbiometricspy
```

```python
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

```text
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](https://stefanosbalaskas.github.io/gpbiometricspy/start-here/)** or **[Workflow map](https://stefanosbalaskas.github.io/gpbiometricspy/workflows/)** 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](https://stefanosbalaskas.github.io/gpbiometricspy/guides/model-selection/)** 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](https://stefanosbalaskas.github.io/gpbiometricspy/interpretation/)** and **[Measurement accountability](https://stefanosbalaskas.github.io/gpbiometricspy/measurement-accountability/)**.

## Documentation

- **[Start here](https://stefanosbalaskas.github.io/gpbiometricspy/start-here/)** — route by research task.
- **[Studio](https://stefanosbalaskas.github.io/gpbiometricspy/studio/)** — guided visual workflow and local/public boundaries.
- **[Workflows](https://stefanosbalaskas.github.io/gpbiometricspy/workflows/)** — EDA, cardiac, eye tracking, multimodal alignment, QC and interoperability.
- **[Methods](https://stefanosbalaskas.github.io/gpbiometricspy/methods/)** — Python-native modelling and provenance methods.
- **[Plot gallery](https://stefanosbalaskas.github.io/gpbiometricspy/plot-gallery/)** — 17 deterministic figures generated in docs CI.
- **[API](https://stefanosbalaskas.github.io/gpbiometricspy/api/)** — domain-organized 406-function frozen-parity reference.
- **[Validation & trust](https://stefanosbalaskas.github.io/gpbiometricspy/deep-validation/)** — 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](https://doi.org/10.5281/zenodo.22150872)
- **0.1.5 version DOI:** [10.5281/zenodo.22672823](https://doi.org/10.5281/zenodo.22672823)
- **0.1.4 version DOI:** [10.5281/zenodo.22515782](https://doi.org/10.5281/zenodo.22515782)
- **0.1.3 version DOI:** [10.5281/zenodo.22313884](https://doi.org/10.5281/zenodo.22313884)
- **0.1.2 version DOI:** [10.5281/zenodo.22150873](https://doi.org/10.5281/zenodo.22150873)
- **Frozen R semantic-reference DOI:** [10.5281/zenodo.21434608](https://doi.org/10.5281/zenodo.21434608)
- **gpbiometrics article:** [10.3390/signals7050086](https://doi.org/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`](VALIDATION.md) and the documentation site for the complete evidence trail.
