Guides

The guides are organized by user need rather than package module. Tutorials help you learn by completing a safe workflow; how-to guides help you accomplish a concrete research task; explanation pages connect the scientific design decisions behind the API.

Decision guide

Choose a research workflow

Start from the evidence you actually have, identify the next defensible stage, and move into the relevant guide, example, method page, or API lens.

Hands-on tutorial

Use the package from data to report

Run a complete EDA/SCR analysis with real package calls, inspect every QC and processing object, save tables and figures, and learn how to substitute your own export.

Tutorial

First analysis

Go from installation to QC, generated figures, and a reproducible workflow using bundled synthetic data.

How-to

Validate a new dataset

Run schema, timing, missingness, signal, event, and provenance checks before substantive analysis.

Project setup

Research project scaffold

Create a checked raw/metadata/mappings/QC/events/derived/models/figures/reports/manifests/logs structure before private research data enter the workflow.

Metadata contract

Study metadata and data dictionary

Declare variable roles, units, clock ownership, provenance, identifiers and event semantics before source columns are standardized or analysis code depends on them.

Hands-on adaptation

Bring your own export safely

Preserve an unfamiliar CSV, preview source-to-standard column mappings, verify time and event assumptions, and export a reviewable adaptation manifest before analysis.

Reference guide

Signal and column glossary

Look up common Gazepoint-style EDA, cardiac, TTL, time, identity and fixation fields, and distinguish recorded signals from validity metadata and derived quantities.

Diagnostics

Troubleshoot a workflow

Start from the symptom, find the earliest broken assumption, preserve diagnostic evidence, and avoid patching around schema, timing, signal, event, model, or reporting failures.

How-to

Timebase and alignment

Separate nominal sampling claims from observed timing evidence and align streams without overstating synchronization accuracy.

How-to

Reporting and reproducibility

Retain the settings, QC evidence, software identity, figures, and provenance needed to reproduce and review an analysis.

Decision guide

Choose a modelling strategy

Match continuous or ordinal outcomes, grouping structures, heavy tails, random slopes, and prediction targets to the current method families.

Reference route

Browse the API

Use the domain browser when you already know the operation you need and want precise signatures rather than a workflow narrative.

Documentation map

Need	Documentation type	Start here
I do not yet know which workflow fits	Decision guide	Choose your workflow
I want to use the package end to end	Hands-on tutorial	Data to report
I want a shorter first tour	Tutorial	First analysis
I am setting up a new research project	Project setup	Research project scaffold
I need to define field roles, units, clocks and event semantics	Metadata contract	Study metadata and data dictionary
I have an unfamiliar CSV/export to adapt	Hands-on adaptation	Bring your own export safely
I know a column name but not its role	Reference guide	Signal and column glossary
Something failed or the evidence looks wrong	Diagnostics	Troubleshooting and diagnostics
I have a research task to complete	How-to	Workflow map and the guides above
I need exact function behavior	Reference	API browser
I need to understand why the workflow is structured this way	Explanation	Python-native articles
I need validation evidence	Evidence	Parity & validation and Deep validation

Choose your workflow

Choose from evidence, not from a function name. Start with what is physically recorded and what the research question requires. Move forward only when the current stage has produced enough evidence to justify the next one.

What you have now	First question	Recommended route	Evidence to retain
A new project before data intake	How will source data, mappings, QC, events, derived outputs, models and reporting evidence remain separated and traceable?	Research project scaffold, then Study metadata and data dictionary	project structure, configuration template, metadata/dictionary contract, manifests/log policy
A new or unfamiliar Gazepoint export	Can I map source columns without losing their original meaning, then verify schema, units and time?	Study metadata and data dictionary, Bring your own export safely, then Validate a new dataset and Signal/column glossary	reviewed field roles/units/clocks, source-to-standard map, schema/QC tables, source identity, timebase evidence
EDA/GSR waveform	Is the conductance signal usable before decomposition or event detection?	EDA / GSR / SCR example	unit audit, signal QC, decomposition settings, candidate-event criteria
PPG waveform or IBI/RR series	What is the source of each interval and are rejected beats visible?	PPG / HRV example	source provenance, peak/interval QC, rejection rules
Pupil, gaze, fixation or AOI fields	Which columns are measured, derived, validity-coded or interpolated?	Pupil / gaze / AOI example	validity/missingness evidence, preprocessing choices, AOI definitions
TTL/task events or multiple sensor streams	Which clock owns each timestamp and what alignment evidence exists?	Timebase and alignment then Multimodal example	event identity, clock mapping, offsets/drift, overlap and residuals
A warning, empty output, or implausible result	Which earlier assumption failed first?	Troubleshooting and diagnostics	minimal reproduction, schema/time/QC evidence, exact warning/error, settings
Analysis-ready repeated observations	What is the scientific generalisation unit and prediction target?	Choose a modelling strategy	grouping structure, holdout unit, model assumptions, uncertainty
Completed analysis	Can another researcher replay the decisions and inspect QC?	Reporting and reproducibility	software identity, settings, exclusions, figures, tables, provenance
An external analysis ecosystem	What representation and metadata does the downstream tool require?	Interoperability example	explicit conversion, version identity, retained source columns

Seven-stage decision sequence

ProjectIdentify the study unit, files, channels, events, participants/items and intended inferential target.

QualityEstablish schema, units, missingness, signal activity, timebase and provenance before deriving measures.

AnalyzeUse modality-specific processing only after the recorded source and QC evidence are explicit.

AlignResolve event identity and clock relationships before creating event-relative or multimodal quantities.

SummariseCreate analysis-ready features while retaining denominators, event coverage and QC context.

ModelMatch the design, grouping structure, prediction target and uncertainty model to the scientific question.

ReportExport results together with diagnostics, settings, provenance and replay information.

Visual checkpoints

Before analysisConfirm that recorded channels are visible and inspectable before deriving features.

Before event-locked inferenceInspect streams and event markers on an explicit shared timeline.

Stop rather than guess

Do not advance a workflow merely because a function can run. Stop and resolve the evidence gap when the timebase is ambiguous, the signal source is unknown, event coverage is incomplete, a denominator has changed silently, or the grouping structure does not support the intended generalisation. The package should make those decisions inspectable rather than conceal them behind a successful return value.

Need a concrete starting script?

Open Examples for short, verified research recipes that connect TTL events, multimodal summaries, AOI dwell and visual timeline checks.

Safe defaults

• Start from bundled synthetic/public demonstration data when learning or testing a pipeline.
• Treat metadata, QC and provenance as evidence-producing stages, not hidden preprocessing details.
• Hold out whole groups when the scientific target is generalisation to unseen groups.
• Keep conditional predictions for observed participants/items separate from population predictions for unseen levels.
• Report timing uncertainty and source identity explicitly when multimodal or cardiac measures depend on them.
• Prefer a simpler model whose assumptions you can defend over a richer model whose latent structure is weakly identified.