Start here

Choose the path that matches what you are trying to do. This page is intentionally task-first: it routes new users to a successful first analysis, researchers bringing their own data through a provenance-first onboarding path, experienced users to the right workflow, and reviewers or collaborators to the validation evidence behind the package.

Stable 0.1.7 Released 2026-09-21 406 / 406 frozen exports Python 3.11–3.14 Synthetic-first examples

Pick your route

New user

Run a complete first analysis

Install the package, load the bundled synthetic dataset, inspect signals, run QC, create plots, and keep a reproducible record.

New research project

Set up, define, adapt, validate, then analyze

Create a reviewable project structure, define field roles/units/clocks and event semantics, preserve and map your own export, verify measurement evidence, then enter the modality-specific workflow.

Study contract

Define variables, clocks and events explicitly

Create a reviewable metadata and data-dictionary contract that separates observed file properties from researcher-declared roles, units, provenance and event meaning.

Research workflow

Start from the data you recorded

Choose EDA/SCR, PPG/HRV, pupil/gaze/AOI, multimodal alignment, QC/reporting, or interoperability and follow the shortest defensible path.

Visual workflow

Use gpbiometricspy Studio

Work through project, quality, analysis, alignment, summarisation, modelling, and reporting in a guided application backed by the same scientific package functions.

Existing export

Adapt an unfamiliar file safely

Keep the original source intact, preview source-to-standard mappings, verify time and event assumptions, and retain an adaptation manifest before analysis.

Statistics

Choose a modelling strategy

Compare grouped predictive models with hierarchical location–scale families, robust variants, random slopes, and crossed participant–item structures.

Reviewer / auditor

Inspect validation and scientific boundaries

Trace frozen R parity, deep validation, private real-data smoke testing, measurement accountability, and explicit interpretation guardrails.

Bringing your own research data

1 · ProjectCreate the research project scaffold so source data, mappings, QC, events, derived outputs, models and reports remain distinct.

2 · DefineUse Study metadata and data dictionary to declare variable roles, units, clock ownership, identifiers, provenance and event semantics without guessing from labels.

3 · AdaptUse Bring your own export safely to preserve source names, inspect mappings and record adaptation evidence.

4 · ValidateRun new-dataset validation for schema, timing, signal activity, missingness, resets, provenance and event coverage.

5 · AnalyzeChoose the relevant signal workflow or follow the complete hands-on analysis once the required evidence is defensible.

Do not collapse these stages. A familiar column label is not a scientific definition; standardising a name is not validation; a present channel is not necessarily active; a parsed timestamp does not establish its unit or clock; and a successful model does not repair uncertain measurement provenance.

One scientific engine, several interfaces

Studio, the Python API, executable tutorials, generated figures, and documentation examples all point back to the same package implementation. The visual application is not a second statistical codebase.

The research path in one view

The same seven stages organize the homepage, Start Here, Studio, workflows, and downstream API discovery.

01ProjectImport or generate data and identify channels.

02QualityCheck schema, validity, missingness and provenance.

03AnalyzeProcess recorded signals with domain-appropriate methods.

04AlignConnect events, clocks, streams and experimental structure.

05SummariseDerive analysis-ready features while retaining QC context.

06ModelChoose guarded statistics that match the study design.

07ReportExport results, diagnostics, provenance and replay information.

graph LR
  A[Acquire / export] --> B[Ingest + schema]
  B --> C[Quality + provenance]
  C --> D[Process signals]
  D --> E[Align events / streams]
  E --> F[Summarise]
  F --> G[Model]
  G --> H[Report + archive]
  C -. fail closed .-> I[Review acquisition or preprocessing]
  E -. timing uncertainty .-> I

Default rule: do not move downstream merely because a function returns a result. Move downstream when the evidence needed for the next scientific claim has been checked and retained.

What should I read next?

Goal	Best next page	Why
Set up a new research project	Research project scaffold	Separates source data, mappings, QC, events, derived outputs, models and reports before analysis begins.
Define variable roles, units, clocks and event semantics	Study metadata and data dictionary	Creates a reviewable measurement contract before column standardisation and analysis code depend on field meaning.
Adapt an unfamiliar export	Bring your own export safely	Preserves source semantics and records mapping, schema, timing and event evidence before standardisation.
Learn by doing	First analysis	A short successful path using bundled synthetic data.
Work with a specific signal	Workflow map	Routes by EDA, PPG/HRV, pupil/gaze, events, or external tools.
See outputs before reading code	Plot gallery	Generated figures from the package's plotting surface.
Understand the design philosophy	Research pipeline blueprint	Explains why QC, provenance, processing, modelling, and reporting are separate layers.
Find a function	API browser	Domain-organized entry point to the complete 406-function reference.
Choose a hierarchical model	Modelling strategy guide	Compares the current Python-native modelling families and their boundaries.
Prepare a paper or supplement	Reporting and reproducibility	Lists the evidence worth retaining and reporting.

Three principles that prevent most workflow mistakes

1 · Measurement

Validate before transforming

Sampling rate, timebase, missingness, interval identity, event coverage, and source provenance constrain what later analyses can mean.

2 · Design

Respect the unit of generalisation

Repeated observations, participants, items, trials, and unseen groups require different validation splits and different model semantics.

3 · Reporting

Keep the evidence trail

Retain QC outputs, settings, software versions, plots, exclusions, timing evidence, and model certificates rather than only a final feature table.

Scientific boundary

The package measures, processes, audits, aligns, summarises, predicts, and models recorded signals. Those operations do not by themselves establish emotion, stress, trust, preference, cognition, diagnosis, sensor validity, reliability, or causal effects. Use the interpretation supported by the study design and measurement evidence, not the label of a software function.