Examples

Examples

These examples are intentionally small. Demonstration datasets are synthetic unless stated otherwise; project-oriented examples are explicit about which parts must be replaced with study-specific decisions.

Choose by task

Install → verify → first import

Run a software-only smoke check from a fresh virtual environment through package identity, representative public imports, one exact signature, a CLI entry point, and a minimal environment record.

Use this when: you want to prove that the intended software environment is available before beginning a scientific workflow.

Source-level API inspection

Use GazeStudy, run_specs, and aoi_probabilities to practise reading generated signatures, following revision-pinned source links, copying public imports, and comparing website metadata with local inspect output.

Use this when: you know the symbol and want to verify the exact callable interface before moving into a research workflow.

Function → example → evidence

Start from run_specs, aoi_probabilities, and read_bids_eyetrack, then follow each symbol through the deep-linkable API pathways surface. The example shows why a linked frozen case or live contract is contextual evidence rather than a transferable scientific verdict.

Use this when: you know a public symbol and want to recover its guide, runnable example, visual, and evidence boundary without searching the site manually.

Search → contract walkthrough

Start with four ambiguous synthetic questions—run_specs NaN, reviewer-revision commands, AOI uncertainty, and robust_negative—then use grouped search results to select the documentation type that answers the actual information need.

Use this when: you know the topic but are unsure whether you need procedural guidance, runnable context, exact reference, or frozen evidence authority.

Reference lookup walkthrough

Use one fully synthetic scenario to look up declared versus valid specification counts, the actual exception behavior of run_specs(), the difference between a non-finite estimate and a null effect, exact reviewer-revision CLI syntax, and the boundary around frozen validation labels.

Use this when: you already know the research task but need to verify exactly what a public API, command, denominator term, or validation label means.

First real audit

Run one practical script on deterministic demo data or a canonical eye-tracking CSV. The script combines GazeStudy, structural-QC fingerprints, a declared 12-specification robustness space, stability/sensitivity summaries, and output writing.

Use this when: you have a project file and want a concrete operational template to adapt before moving into study-specific methods.

Valid, invalid, and reviewable tables

Use a synthetic table to see exactly which conditions stop GazeStudy construction and which conditions construct successfully but become structural-preflight review evidence.

Use this when: you need to understand the boundary between canonical schema validity and contextual structural QC before mapping your own source.

Mapping change audit

Compare before/after mapping records for source-column renames, corrected exports, timestamp conversion, coordinate conversion, changed trial semantics, and reviewer-driven exclusions.

Use this when: a canonical table or mapping has changed and you need to decide which provenance, structural-preflight, and downstream records must be rebuilt without erasing the earlier analysis history.

All structural-QC issues in one synthetic table

Exercise all five current issue families and all ten diagnostic detail-code types in one deterministic table. The example keeps row counts, group counts, issue families, and diagnostic records distinct and includes bounded Methods/Results/limitations wording.

Use this when: status == "review" is clear but you want to understand exactly how the individual issue/detail codes behave before triaging a real dataset.

Readiness policy design

Declare a synthetic primary and alternative readiness policy, reproduce their trial- and participant-scope cohort consequences, and practise reporting the policy/status/denominator without treating teaching cutoffs as recommendations.

Use this when: structural QC is understood and you need to learn how a declared readiness policy changes cohort retention before any actual filtering step.

Study preflight

Create a canonical GazeStudy, run audit_study_qc(), inspect stable issue codes, and export a compact QC table. The synthetic example deliberately contains one missing coordinate and a repeated timestamp.

Use this when: you are onboarding a new table and want a transparent structural check before measurement or robustness analysis.

Failure → repair → reconciliation

Follow an eight-branch synthetic audit from initial execution through one technical failure, one non-finite endpoint, one valid not-run branch, two same-branch repair reruns, and a reconciled current state of 6 successful / 7 valid without counting historical attempts as new scientific specifications.

Use this when: a branch has been repaired, retried, deferred, or left unresolved and you need to preserve both current results and execution history.

Declared → valid → successful

Declare eight synthetic combinations, reject two through a fixed pre-execution validity rule, preserve one valid technical failure, and report the execution summary as 5 successful / 6 valid rather than silently shrinking the denominator.

Use this when: you need to separate Cartesian declaration, scientific validity, and technical execution outcomes before interpreting a specification curve.

Endpoint drift audit

Compare nine synthetic endpoint scenarios to decide when a branch preserves the declared scientific quantity and when it changes contrast direction, unit, weighting, outcome family, missingness meaning, or temporal evidence layer.

Use this when: a specification space is technically runnable but you need to confirm that every branch still estimates the same scalar scientific endpoint.

Conclusion-rule edge cases

Exercise the exact runtime contract for conclusion recovery using fully synthetic references and estimates: no-tolerance failure, invalid thresholds, dual-tolerance AND semantics, sign rules, zero-reference behavior, recovery-threshold equality, circular-reference misuse, and execution completeness.

Use this when: a categorical reference-based recovery rule is scientifically justified and you need to understand its edge cases before applying it.

Diagnostic interpretation walkthrough

Interpret one deterministic eight-specification result table through specification ordering, effect stability, marginal sensitivity, pairwise sensitivity, reproducible plot routes, an incomplete-execution contrast, and bounded Methods/Results/limitations wording.

Use this when: the robustness analysis already ran and you need to understand what each diagnostic literally supports before writing the scientific conclusion.

End-to-end robustness audit

Run a complete 12-specification synthetic audit from GazeStudy construction through PipelineSpace, run_specs(), specification ordering, effect stability, marginal sensitivity, and pairwise interaction diagnostics.

Use this when: you want a copy-ready template showing how the main robustness pieces fit together in one executable analysis.

Failed-audit recovery

Work through a fully synthetic audit with 8 declared combinations, 7 valid specifications, and 6 initially successful executions. The example preserves one predeclared-invalid combination outside the valid denominator, records one valid technical failure, diagnoses a branch-specific processor defect, reruns the same branch after a causal technical repair, and retains both the original failure and repaired execution in history.

Use this when: a declared audit stops or returns an incomplete result and you need to distinguish scientific validity from technical execution before changing anything.

Reporting-language rewrite

Start from seven synthetic over-claims and repair them by naming the actual evidence object, preserving the correct denominator, separating runtime status from interpretation, and adding the limitation that bounds the claim.

Use this when: the analysis is complete but the manuscript sentence sounds stronger than the evidence object actually supports.

Result-pattern reporting

Compare four synthetic audit outcomes side by side: direction and magnitude both relatively stable, direction stable but magnitude materially variable, sign-changing evidence, and incomplete execution. Each pattern includes bounded Results wording and explicit claims that remain unsupported.

Use this when: you have robustness outputs but need to decide what the complete pattern actually licenses you to say before moving into manuscript prose.

Decision-to-report worked example

Use the deterministic 12-branch robustness demo to practise recording analytical choices before outcome inspection, reading the complete positive/negative/zero pattern, separating direction from magnitude, and translating the result into bounded Methods and Results language.

Use this when: you understand the code path but want to learn what a defensible interpretation and manuscript handoff look like.

Reviewer reconstruction

Read an illustrative submission archive from the perspective of a reviewer who was not involved in the analysis. The example reconstructs one endpoint, an eight-combination declared space, one invalid combination, seven valid branches, six successful estimates, and one unresolved technical failure. It then rewrites an over-strong robustness sentence so the valid denominator remains visible.

Use this when: the manuscript draft looks finished but you want to test whether the claim can actually be reconstructed from the preserved record without private lab knowledge.

Reviewer-requested reanalysis

Extend a synthetic submitted 8 / 8 robustness audit with a stricter quality threshold requested after peer review. The amendment contributes 4 / 4 separately denominated branches and demonstrates revision timing, response-letter wording, revised Results and limitations, archive layout, failed-amendment handling, and why the combined record must not be described as “12 pre-specified analyses.”

Use this when: a reviewer asks for another exclusion, threshold, sensitivity branch, measurement assumption, or endpoint and you need a concrete model for extending the record without retrospectively rewriting the submitted audit.

Revision response package

Follow three synthetic reviewer items from request to final record: a denominator clarification with no rerun, a four-branch stricter-threshold sensitivity amendment, and a different-endpoint request that is preserved outside the original denominator. The example provides response-letter wording, a response matrix, manuscript-change log, round-specific archive layout, and an outsider reconstruction test.

Use this when: the new analyses are complete but you need to ensure the response letter, revised manuscript, and archive all describe the same temporal evidence record.

Revision-package quickstart

Use the real gazeaudit-revision-package init and validate commands on a fully synthetic review round. The example creates the governed scaffold, populates the response matrix and version-change manifest, separates a post-review sensitivity amendment from a new endpoint, builds an editor-facing evidence map, preserves the 3 / 4 incomplete-amendment variant, and finishes with an outsider reconstruction check.

Use this when: you want the shortest executable path from reviewer requests to a structurally validated revision-provenance package before moving into the longer break → detect → repair exercise.

Submission-to-accepted-record worked example

Continue the same synthetic revision through the final handoff. The example keeps the submitted 8 / 8 record, reviewer-requested 4 / 4 sensitivity amendment, separate endpoint amendment, response matrix, version-change manifest, resubmission-readiness gate, editor-facing evidence map, and publication-associated archive distinct.

It also shows the incomplete amendment variant (3 successful / 4 valid) and the correction path where superseded evidence must remain visible.

Use this when: the response package is complete and you want to test whether the final manuscript can be traced back through submitted, post-review, and final evidence layers without rewriting history.

Publication and archive handoff

Continue the synthetic exercise into an illustrative archive containing decision history, source identity, structural-QC evidence, complete specification/execution records, manuscript Methods/Results wording, limitations, software/provenance records, fingerprints, and a human-readable manifest.

Use this when: the analysis and interpretation are already clear and you want a concrete model for what a coauthor, reviewer, editor, or future analyst should be able to recover from the final handoff.

Analysis readiness

Work through executable policy, cohort-impact, repair, and specification-space decisions while keeping structural diagnostics separate from scientific exclusions.

Use this when: readiness policy and its effect on the analyzable cohort are part of the audit question.

AOI boundary uncertainty

Fit GaussianGazeErrorModel, define adjacent AOIs, estimate probabilistic membership, and compare hard versus uncertainty-aware assignment.

Use this when: you want to understand the measurement-error layer before building a larger analysis.

Specification curve

Create a synthetic results table, order estimates with specification_curve(), calculate effect_stability(), and screen factor sensitivity.

Use this when: you already have one estimate per defensible analytical specification and want to understand the robustness summaries.

Sampling sensitivity

Create a canonical GazeStudy, downsample the same participant-by-trial stream to controlled target rates, and evaluate one endpoint with sampling_sensitivity_curve().

Use this when: sampling rate is a plausible source of inferential sensitivity.

Sensitivity protocol worked example

Declare one synthetic endpoint, a controlled sampling-rate grid, a seeded missingness grid, and complete plotting/reporting rules before inspecting the curves.

Use this when: you want a reusable template for the declare → execute → preserve → interpret sequence across ordered perturbation analyses rather than only a sampling-specific example.

Suggested learning path

1. Start with the first real audit when you want to adapt GazeAudit to your own canonical CSV.
2. Use the researcher audit checklist and decision-log template to replace demonstration choices with documented study-specific decisions.
3. Use the study preflight when structural onboarding itself needs closer inspection.
4. Run the end-to-end robustness audit to study the specification API in isolation.
5. If execution blocks, use Troubleshooting GazeAudit and practise the failed-audit recovery workflow before interpreting an incomplete result.
6. Use the interpret an audit result guide to check denominator, endpoint, direction, magnitude, sensitivity, and untested uncertainty in the right order.
7. Compare the four result-pattern examples before choosing bounded reporting language.
8. Work through decision-to-report to practise interpreting the deterministic 12-branch pattern without selecting a preferred branch after the fact.
9. Use common audit mistakes and repairs to diagnose a weak decision trail or incomplete evidence record.
10. Apply the manuscript readiness checklist to the draft claim and archive.
11. Work through reviewer reconstruction to practise finding denominator and reporting gaps from outside the analysis team.
12. Use the peer-review revision checklist before changing files in response to review.
13. Use the reviewer-requested amendments guide when peer review adds analytical work.
14. Work through reviewer-requested reanalysis to keep submitted and post-review denominators distinct.
15. Use the reviewer response letter guide to connect each response to timing, evidence, manuscript locations, and archive locations.
16. Work through the revision response package to audit the response letter, manuscript-change log, and revision archive together.
17. Use the version-change manifest guide to bind every material manuscript change to its rationale and evidence layer.
18. Run the revision-package quickstart to create and structurally validate the governed package with the real CLI.
19. Apply the resubmission readiness guide to the final manuscript, response package, version manifest, and evidence map.
20. Work through submission-to-accepted-record to reconstruct the complete synthetic temporal handoff.
21. Build the publication/archive handoff to practise packaging the complete record for review and preservation.
22. Run the AOI boundary example if spatial measurement uncertainty is part of the question.
23. Use sampling sensitivity when temporal resolution is part of the scientific question.
24. Run the sensitivity protocol example when you need to coordinate sampling and missingness perturbations under one fixed endpoint and reproducibility record.
25. Move to the first-study workflow when assembling the full research process.

Visual convention

Plots in these example pages are explanatory figures. When they display synthetic values, the page and figure say so explicitly. Frozen empirical validation results remain in the validation matrix and case-specific result records.

• Plot gallery — 14 deterministic code-generated figures with source links.