Metadata-Version: 2.4
Name: gpbiometricspy
Version: 0.1.2
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: 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: 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

# gpbiometricspy

[![PyPI](https://img.shields.io/pypi/v/gpbiometricspy.svg)](https://pypi.org/project/gpbiometricspy/)
[![Python](https://img.shields.io/pypi/pyversions/gpbiometricspy.svg)](https://pypi.org/project/gpbiometricspy/)
[![GitHub release](https://img.shields.io/github/v/release/stefanosbalaskas/gpbiometricspy)](https://github.com/stefanosbalaskas/gpbiometricspy/releases/latest)
[![Tests](https://github.com/stefanosbalaskas/gpbiometricspy/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/stefanosbalaskas/gpbiometricspy/actions/workflows/tests.yml)
[![Docs](https://github.com/stefanosbalaskas/gpbiometricspy/actions/workflows/docs.yml/badge.svg?branch=main)](https://github.com/stefanosbalaskas/gpbiometricspy/actions/workflows/docs.yml)
[![CodeQL](https://github.com/stefanosbalaskas/gpbiometricspy/actions/workflows/codeql.yml/badge.svg?branch=main)](https://github.com/stefanosbalaskas/gpbiometricspy/actions/workflows/codeql.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Zenodo integration](https://img.shields.io/badge/Zenodo-enabled-1682D4?logo=zenodo&logoColor=white)](https://zenodo.org/)

`gpbiometricspy` is the Python counterpart of **gpbiometrics**, with the supplied
**gpbiometrics 2.0.0** source release frozen as its initial semantic reference.
It provides Gazepoint-native tools for importing, validating, preprocessing,
analysing, plotting, modelling, synchronising, and reporting biometric and
multimodal eye-tracking data.

| Channel | Current state |
|---|---|
| Stable release target | **0.1.2** |
| Release source | **`main` frozen at 0.1.2** |
| Frozen R semantic reference | **gpbiometrics 2.0.0** |
| Export parity | **406 / 406 implemented; 0 pending** |
| Zenodo | **GitHub integration enabled; 0.1.2 is the first DOI-producing Python release** |

## Parity status

The current development tree has reached the frozen R API contract:

- **406 / 406 R exports implemented and registered**
- **0 pending exports**
- **200+ Python parity/edge tests**
- **whole-package statement coverage ≥ 90%**
- packaged synthetic kiosk demo: **36 participants, 69,120 rows**
- frozen R reference retained: 144 R sources, 403 Rd files, 120 R test files,
  and 26 vignette/article sources

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 tests and implementation
are retained in `reference/` so parity can continue to be audited.

## Install

Install the public release from PyPI:

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

For optional integrations:

```bash
python -m pip install "gpbiometricspy[interop]"
```

For a source checkout used in package development:

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

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

## Quick start

```python
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 demo is **fully synthetic** and is intended only for examples, testing,
and reproducible workflow demonstrations.

## Documentation, examples and plots

The documentation site now exposes the package as a complete scientific workflow rather than only an API catalog:

- [Examples](https://stefanosbalaskas.github.io/gpbiometricspy/examples/) — EDA/SCR, PPG/HRV, pupil/gaze/AOI, multimodal, QC/reporting and interoperability;
- [Plot gallery](https://stefanosbalaskas.github.io/gpbiometricspy/plot-gallery/) — figures generated directly by the Python plotting API from bundled synthetic/public data;
- [Articles and tutorials](https://stefanosbalaskas.github.io/gpbiometricspy/articles/) — all 26 frozen R vignette/article companions, each backed by executable Python code;
- [API reference](https://stefanosbalaskas.github.io/gpbiometricspy/api/reference/) — all 406 exported functions.


## Deep validation layers

Beyond the 406/406 export freeze, development on `main` includes independent R↔Python golden fixtures, floor/current optional-backend interoperability CI, 26 executable Python article companions, and a privacy-preserving real-data validation CLI. See the documentation site for the distinction between API parity and deeper cross-runtime/backend evidence.

## Scientific scope

The 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/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 that the R
  package intentionally refuses;
- reproducibility, preregistration, audit trails, readiness checks, reporting,
  plots, workflow summaries, simulation and synthetic smoke testing.

## 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

The repository is connected to the Zenodo GitHub integration. The existing
`v0.1.1` release predates that connection. **`v0.1.2` is the first Python
release configured for automatic Zenodo archival and DOI registration.** The
version and concept DOI are added to the repository front after Zenodo finishes
processing the GitHub release; no DOI is pre-invented in the release source.

The frozen R semantic reference is archived independently as **gpbiometrics
2.0.0**, DOI **[10.5281/zenodo.21434608](https://doi.org/10.5281/zenodo.21434608)**.
That DOI documents the R source/provenance and must not be presented as the
Python package DOI.

Citation metadata is maintained in [`CITATION.cff`](CITATION.cff), while
Zenodo-specific archival metadata and the explicit R-reference relationship are
maintained in [`.zenodo.json`](.zenodo.json). After Zenodo processes `v0.1.2`, the resulting Python concept/version DOI is
added here and to the documentation.

## 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.
