Skip to content

Getting started

This page takes you from installation to a validated, event-aware biometric workflow in a few minutes.

1. Install

python -m pip install "gpbiometricspy==0.1.8"

python -m pip install \
  "gpbiometricspy @ git+https://github.com/stefanosbalaskas/gpbiometricspy.git@main"

The package supports Python 3.11–3.14. Version 0.1.8 is the current public stable release, published on 2026-10-04 from exact source 32cafd5565bdf4a7575dcf5c5d6bb2bfbe101e5d after the protected exact-main release gates completed successfully. The immutable GitHub release and PyPI package are both public.

2. Load the packaged demo

import gpbiometricspy as gp

data = gp.load_kiosk_demo()
print(data.shape)

The bundled kiosk dataset contains 36 synthetic participants, four tasks per participant, and 69,120 Gazepoint-like rows at 60 Hz. It is designed for tutorials, smoke tests, and reproducible examples—not for substantive empirical conclusions.

3. Audit before analysing

active = gp.detect_gazepoint_active_channels(data)
validity = gp.summarise_gazepoint_biometric_validity(data)
events = gp.extract_gazepoint_ttl_events(data)

print(active)
print(validity)
print(events.head())

A useful default order is:

  1. identify available channels;
  2. validate timing and missingness;
  3. recover events/TTL markers;
  4. preprocess only the signals that passed the relevant checks;
  5. align by event, trial, or AOI;
  6. summarize and plot;
  7. retain the QC/audit outputs with the analysis.

4. Pick a domain path

EDA / SCR

Artifacts, decomposition, SCR events and summaries.

Start EDA →

PPG / HRV

Pulse detection, IBI, HRV and toolbox-style cross-checks.

Start PPG →

PPG measurement equity

Pigmentation provenance, raw signal quality, paired availability, reference agreement, and the 0.1.8 synthetic/STEP evidence path.

Audit PPG equity →

Pupil / gaze

Pupil QC, gaze/AOI summaries and saccade diagnostics.

Start gaze →

PPG / HRV versus PPG measurement equity

Use the ordinary PPG / HRV route for pulse detection, IBI provenance and variability metrics. Use the measurement-equity route when you need to keep pigmentation provenance, acquisition quality, candidate-value availability and reference agreement separate. The explanation article connects the synthetic known-truth example to the authorized STEP external-evidence run.

5. A compact physiological example

# pyHRV-style example from IBI in seconds
nni_ms = (
    data.loc[data["IBI"].notna(), "IBI"]
    .head(500)
    .to_numpy()
    * 1000
)
hrv = gp.run_gazepoint_pyhrv_style(nni_ms=nni_ms)

# HeartPy-style PPG processing
ppg = gp.process_gazepoint_ppg_heartpy_style(
    data,
    signal_col="HRP",
    time_col="TIME",
)

For the 0.1.8 measurement-equity workflow, continue with the synthetic worked example, the method specification, or the STEP external-evidence record.

6. Add optional backends only when needed

pip install "gpbiometricspy[mne,lsl]"
pip install "gpbiometricspy[heartpy,neurokit]"
pip install "gpbiometricspy[biosppy,pyhrv]"
pip install "gpbiometricspy[stats]"

The core package does not require these external toolboxes. Interoperability functions report backend/version context so that optional-tool results remain auditable.

Where to go next

Use the workflow map if you know your data modality but not the exact function family. Use the plot gallery if you want to see expected visual outputs first. Use the API reference when you already know the function name.

Interpretation guardrail

Physiological and eye-tracking measurements support signal-level and task-context analyses. They do not, by themselves, establish emotion, stress, preference, cognition, comprehension, clinical state, or diagnosis. See Interpretation guardrails.