Documentation

Documentation hub

GazeAudit documentation is organised around research tasks, not only modules. Start with the smallest runnable example, build a transparent audit route from study conditions, troubleshoot blocked execution without rewriting the scientific record, then move into structural preflight, measurement uncertainty, specification-space design, sensitivity analysis, frozen real-data case studies, peer-review revision, and reproducible publication.

Use Ctrl/Cmd + K anywhere on the site to search methods, workflows, examples, evidence pages, and reference material. Results are grouped by documentation type so the same topic can expose a Guide, Example, Reference, or Evidence authority without implying that one is scientifically preferred. Use Find information fast for the keyboard controls, filters, query patterns, and navigation boundary.

Choose by intent

Open the full Documentation compass →

Start here

Guided next step

The What should I do next? page is the static counterpart to the homepage project-stage router. It keeps the same five project stages—plan, audit, interpret, peer review, and handoff—in ordinary semantic documentation that remains useful without JavaScript.

Use it when the question is where should I go next in the documentation? rather than which scientific choice is correct? The guide deliberately stops when endpoint identity, valid denominators, reviewer timing, or study-specific justification are unclear instead of inventing a decision.

The companion project lifecycle walkthrough follows one fully synthetic endpoint from an eight-branch submitted audit into interpretation, a separately denominated post-review amendment with one valid technical failure, a separate endpoint amendment, and final handoff. It is teaching material, not empirical validation evidence.

Troubleshoot a blocked audit

Use Troubleshooting GazeAudit when execution itself is blocked: installation/import problems, source-schema mismatches, structural-QC flags, incomplete grouped-model coverage, valid specification failures, non-finite endpoints, denominator mismatches, or revision-package validation errors.

The symptom router separates invalid before execution, valid and successful, valid but technically failed, and not run states so troubleshooting cannot silently rewrite the valid denominator. The companion failed-audit recovery walkthrough follows a fully synthetic 8 declared → 7 valid → 6 initially successful audit through diagnosis, technical repair, same-branch rerun, and final reconciliation while retaining the original failure event.

If the software ran but the decision history, archive, or reporting boundary is weak, use Common audit mistakes and repairs instead. Troubleshooting is not a mechanism for choosing a more convenient scientific rule.

Reference layer

Use the Reference hub when the question is factual rather than procedural: Which public function? Which installed command? What exactly does this denominator/status term mean? Which revision built the site? Which frozen record is authoritative?

The reference layer deliberately stays separate from how-to guidance. CLI reference records the commands declared by the package, while Evidence and denominator vocabulary distinguishes actual runtime fields from audit-ledger terms such as technical_failure. The reference lookup walkthrough demonstrates that distinction on fully synthetic teaching data.

Reference pages do not choose thresholds, exclusions, endpoints, validity predicates, reviewer amendments, or conclusions. When the question becomes “what sequence should I follow?”, return to a guide or workflow.

Researcher workspace

The Researcher workspace is the project-level route when you want to connect several documentation layers without losing their scientific boundaries. It links six stages: scope the audit, inspect the governed method route, run the smallest relevant workflow, inspect visuals in context, check the evidence boundary, and preserve the publication record.

Use it as an orientation layer rather than a new source of scientific rules. The workspace does not choose thresholds, exclusions, perturbation levels, specifications, or validity claims.

Peer-review revision

If the manuscript is already in a revision round, use the Peer-review revision toolkit rather than reconstructing the route from publication pages manually. The toolkit separates clarification, analytical amendments, endpoint changes, corrections, reviewer-response records, package validation, and final editor handoff while preserving the submitted evidence layer.

For the shortest operational route, run the peer-review revision checklist before changing files, then use the revision-package quickstart to create and structurally validate the governed package with the real gazeaudit-revision-package CLI.

A valid revision package establishes structural provenance only. It does not certify scientific validity, robustness, manuscript quality, or publication readiness.

Plan an audit from study conditions

The Audit planner is the shortest route when you know which study conditions or methodological risks are relevant but do not yet know which parts of GazeAudit to combine. Select only the conditions that genuinely apply; the planner deduplicates the corresponding governed method families, explains why each method entered the route, and links directly to its guide, runnable example, diagnostic plot, and evidence boundary.

The planner is deliberately non-diagnostic. It does not choose thresholds, infer unselected risks, exclude participants, or decide whether a result is scientifically valid. A shared planner URL records navigation choices, not a scientific conclusion.

When the route is useful, preserve it as a shareable URL, a Markdown audit brief, or a deterministic JSON navigation manifest. The JSON record includes a stable schema version, selected conditions, ordered methods, API sequences, workflow handoffs, the GazeAudit release identity, and the documentation revision; it intentionally does not insert a volatile timestamp.

Explore methods by research question

The method explorer connects ten methodological questions to a compact public API route, a guide or runnable example, a diagnostic figure, and an explicit evidence boundary. Use it when you know what decision you need to defend but do not yet know which GazeAudit functions or workflow page to open.

Its evidence column is deliberately conservative: frozen real-data cases are linked only where they are substantively relevant, while synthetic known-truth benchmarks and live interoperability checks remain labelled as different evidence types.

Data onboarding

Before applying measurement or robustness methods to a new table, map its semantic columns explicitly with GazeStudy and run the structural preflight. The data onboarding guide explains how audit_study_qc() reports non-finite coordinates/timestamps, missing identifiers, duplicate within-trial timestamps, and decreasing time order without turning those diagnostics into universal exclusion rules. If preflight returns review, use the Structural QC Issue Clinic for exact issue/detail-code lookup and the Structural-QC triage guide for the inspection → decision → repair/rerun → reporting sequence.

For a single practical path that continues beyond preflight into robustness outputs and saved evidence, use First real audit with your own data.

Runnable examples

The examples use synthetic data unless a page explicitly points to a frozen real-data validation record. This keeps demonstrations runnable without private participant data while separating demonstration values from empirical claims.

• Project lifecycle walkthrough — five-stage synthetic project from declared route through audit, interpretation, peer-review amendment, separate endpoint record, and final handoff.
• Failed-audit recovery walkthrough — synthetic declared/valid/successful denominator accounting, technical failure preservation, causal repair, same-branch rerun, and reconciliation.
• Valid, invalid, and reviewable tables — learn which schema conditions fail construction and which remain visible as structural-review evidence.
• Mapping change audit — distinguish source-label changes from substantive source, unit, coordinate, grouping, and exclusion changes.
• First real audit — CSV-oriented project template with structural-QC provenance, complete specification execution, and saved robustness tables.
• python examples/study_preflight.py — inspect a deliberately flagged canonical study before downstream analysis.
• End-to-end robustness audit — canonical study → declared specification space → complete execution → stability and sensitivity diagnostics.
• Generated API call contracts — read required positional and keyword-only arguments, return annotations, and mechanically generated minimal call shapes without inventing study values.
• Example → study handoff — separate reusable workflow structure from teaching values and rebuild the analysis as a study-owned record.
• AOI boundary uncertainty — fit a gaze-error model and convert a hard boundary decision into probabilistic membership.
• Specification curve — summarise an explicit analytical decision space.
• Sampling sensitivity — perturb sampling rate and inspect endpoint stability.
• Revision-package quickstart — synthetic reviewer requests → governed revision scaffold → response/change/evidence records → structural validation.

Research workflows

Use the workflow pages when you are designing a study or analysis rather than learning one function.

• Workflow map — choose the right workflow family.
• First-study audit — canonical data → preflight → optional readiness/measurement layers → robustness → publication provenance.
• Measurement audit — validation information → error model → AOI uncertainty → endpoint propagation.
• Robustness audit — defensible choices → common endpoint → specification curve → sensitivity diagnostics.
• Reproducible publication — declared rule → audit bundle → fingerprints → methods/report output.

Real-data case studies

The case-study layer turns the frozen validation records into readable methodological walkthroughs while leaving the underlying scientific records untouched.

Conceptual articles

The articles explain why the package is structured the way it is and where its scientific boundaries sit.

• Measurement uncertainty is a modelling problem
• From one pipeline to a robustness audit
• How to read a fragile result

Reporting layer

After running an audit, use Reporting robustness without overclaiming to distinguish descriptive specification quantiles from confidence intervals, sign fractions from probabilities, and sensitivity screening from causal variance decomposition.

Frozen validation evidence

GazeAudit’s validation programme deliberately preserves different scientific outcomes. The authoritative index is the validation matrix.

These labels are protocol-bound records, not universal properties of the source datasets.

Scientific and release reference

For deeper provenance or publication operations, use the existing authoritative records:

• Reference hub — API, CLI, vocabulary, provenance, validation, citation, and release lookup.
• Scientific methods
• Validation matrix
• Citation and reuse
• Release notes 0.2.0
• GitHub Release v0.2.0
• Archived release notes 0.1.0
• Archived v0.1.0 external publication record

Need a quick answer?

Open the FAQ for installation, interpretation, versioning, and scope questions, or Troubleshooting GazeAudit when a workflow is blocked or failing.

Code-generated visual reference

The plot gallery contains 14 deterministic Matplotlib SVGs tied to executable source, including readiness, cohort-impact, repair, specification, sensitivity, AOI, and recovery diagnostics.