Metadata-Version: 2.4
Name: gpbiometricspy
Version: 0.1.0
Summary: Python port of gpbiometrics 2.0.0 for Gazepoint biometric workflows
Author: Stefanos Balaskas
License-Expression: MIT
Project-URL: Homepage, https://github.com/stefanosbalaskas/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: 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"
Provides-Extra: biosppy
Requires-Dist: biosppy>=2.2.4; extra == "biosppy"
Provides-Extra: pyhrv
Requires-Dist: pyhrv>=0.5.0; 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: biosppy>=2.2.4; extra == "interop"
Requires-Dist: pyhrv>=0.5.0; 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/)


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

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

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

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