GazeAudit uncertainty × robustness
v0.2.0 · development docs GitHub

Researcher workspace

Development docs · 996102e0
View source

Researcher workspace

Use this page as the project-level map for GazeAudit. It connects the planner, method catalog, runnable documentation, visual diagnostics, empirical evidence, result interpretation, peer-review revision, and publication tooling without turning any of them into an automatic scientific decision system.

Have data Start with my gaze CSV

Map the table, run structural preflight, declare alternatives, and save the complete audit bundle.

First real audit → Design Plan an audit

Translate study conditions into governed method families and preserve a deterministic navigation record.

Open planner → Choose method Answer one methodological question

Move from a research question to the smallest public API, guide, example, plot, and evidence boundary.

Explore methods → Report Prepare the publication record

Bind decisions, outputs, fingerprints, provenance, interpretation limits, and review-stage amendments into an auditable archive.

Publication workflow →
Navigation is not judgement. Thresholds, exclusions, perturbations, endpoints, and validity claims remain researcher-owned scientific decisions.
Trace the audit record →

The shortest practical route

01 · RepresentMap the study explicitlyGazeStudy(frame)
02 · InspectRun structural preflightbuild_study_qc_audit()
03 · Stress-testRun declared alternativesrun_specs()
04 · PreserveSave evidence + provenanceanalysis-output/

For a first study, this route is usually more useful than trying to learn the whole package at once. Run the first real audit guide end to end, inspect the bundle it produces, then add readiness, measurement-uncertainty, or publication layers only when they answer a real study-specific question.

If you need to see how those stages become one reviewable scientific record, use the audit record map. It links study inputs and researcher-owned decisions to QC, specification execution, robustness summaries, provenance, fingerprints, and manuscript/archive claims.

Already have completed robustness outputs? Use Interpret an audit result to check the declared denominator, endpoint consistency, direction, magnitude, descriptive sensitivity, and untested uncertainty in that order. Then compare the four synthetic result-pattern reporting examples before choosing manuscript wording.
Revising after peer review? Use the manuscript review path for the interpretation → draft → reconstruction → amendment → archive sequence. If a reviewer requests new analytical work, preserve the submitted record and continue with reviewer-requested amendments and the worked reanalysis example rather than rewriting the original declaration.
Before execution, preserve the decisions that GazeAudit cannot make for you. Use the researcher audit checklist to review scientific ownership points, then copy the audit decision log template into the study repository. Record later amendments instead of rewriting the original declaration.
What you preserve

The audit is a bundle, not one preferred result.

The practical workflow keeps the complete specification table, robustness summaries, structural-QC record, and researcher decisions together so collaborators can reconstruct what was declared and what changed.

analysis-output/study-qc/ analysis-output/specifications.csv analysis-output/specification-curve.csv analysis-output/effect-stability.csv analysis-output/marginal-sensitivity.csv analysis-output/pairwise-sensitivity.csv
Before interpretation

Check the scientific ownership points.

  • Coordinate system and units are documented.
  • QC flags have explicit researcher decisions where needed.
  • The alternative specifications were defensible before result inspection.
  • The scientific endpoint is held constant across branches.
  • Empirical robustness summaries are not presented as confidence intervals.
  • The exact GazeAudit release or commit is recorded.

Open the full researcher checklist →

Keep navigation and judgement separate. GazeAudit can help you make a decision trail explicit. It does not decide which thresholds, exclusions, perturbation levels, specifications, or validity claims are scientifically justified for your study.
Already have a gaze file? Use the first real audit guide for the practical CSV → preflight → robustness → saved evidence path, or run the companion executable example first.

1. Scope the audit

Start with the Audit planner when you know the study conditions that matter but have not yet assembled a method route. Select only conditions that genuinely apply. The planner deduplicates the corresponding governed method families and explains why each one entered the route.

When the route is useful, preserve it in one of three forms:

  • shareable URL — retains the selected planner conditions;
  • Markdown audit brief — a human-readable handoff for collaborators, protocols, or manuscript notes;
  • JSON navigation manifest — a deterministic machine-readable record with schema_version, selected conditions, ordered methods, API sequences, workflow handoffs, release identity, and documentation revision.

The export contains no inferred diagnosis and no timestamp-derived nondeterminism. Researcher-owned thresholds, exclusions, assumptions, and validity judgements remain outside the navigation artifact.

2. Inspect the governed method route

Use the Method explorer when the methodological question is clear. Each of the ten method families connects the research question to:

  • a compact public API sequence;
  • a task-oriented guide;
  • a runnable example or workflow;
  • a governed diagnostic plot;
  • an explicit evidence boundary.

This is the best place to check whether a frozen real-data case is genuinely relevant or whether the available evidence is instead synthetic, interoperability-focused, or descriptive.

3. Run the smallest relevant workflow

Prefer the smallest executable path that answers the methodological question before combining multiple audit layers.

Need Start here Continue with
Apply GazeAudit to your own canonical CSV First real audit First-study workflow
Declare researcher-owned decisions Researcher checklist Decision log template
Structural preflight Study preflight Data onboarding
Readiness governance Analysis-readiness example Readiness guide
AOI measurement uncertainty AOI boundary example Measurement audit
Alternative analytical choices End-to-end robustness audit Robustness workflow
Interpret completed robustness outputs Interpret an audit result Result-pattern examples
Interpret a robustness pattern Decision-to-report example Reporting guide
Sampling sensitivity Sampling example Specification-space guide
Manuscript/reviewer reconstruction Manuscript review path Reviewer reconstruction
Peer-review revision / reanalysis Reviewer amendments Reanalysis example
Publication evidence Publication workflow Publication-audit guide

4. Inspect visuals in context

The Plot gallery contains fourteen deterministic code-generated figures. Every plot now exposes the methodological question it answers, a stable shareable anchor, its governed method families, and a practical Continue with route.

Synthetic gallery figures demonstrate APIs and reporting patterns. They are not additional validation evidence. Use the case-study layer for empirical validation records.

5. Check the evidence boundary

The Case studies expose three deliberately different frozen outcomes:

Case Frozen outcome Boundary
GazeBase multi-detector audit incomplete A predeclared completeness gate was not satisfied.
Korthals target-tracking AOI robust_negative The negative paired effect survived the frozen uncertainty model.
Pedrotti/de Chambrier sampling + missingness materially_fragile Magnitude recovery changed materially under the frozen perturbation protocol.

These are protocol-bound records. Do not transfer a case-study label to a new dataset simply because the same method family is used.

6. Interpret before writing the publication claim

Before reducing the audit to a manuscript sentence, check:

  1. whether every declared valid branch is accounted for;
  2. whether every branch estimates the same scientific endpoint;
  3. whether direction changes across the declared space;
  4. whether magnitude changes enough to alter substantive interpretation;
  5. which declared factors align descriptively with the variation;
  6. which plausible uncertainty dimensions remain untested.

The interpretation guide turns those checks into a practical decision path. The result-pattern example shows why stable sign, stable magnitude, sign-changing evidence, and incomplete execution require different wording.

7. Preserve the publication and revision record

Before writing the final methods or results text, record:

  1. the GazeAudit release or exact commit;
  2. the planner route or rationale for the selected method families;
  3. researcher-declared thresholds, perturbation levels, and specifications;
  4. generated outputs and fingerprints;
  5. the interpretation boundary used in reporting;
  6. any reviewer-requested amendments, their timing, and their separate execution denominators.

Then use the manuscript review path, reproducible-publication workflow, and reporting guide to keep submitted evidence, post-review extensions, robustness summaries, confidence intervals, causal claims, and researcher judgement distinct.

Fast routes

Documentation search

Find the right documentation

↑↓ navigateEnter openEsc close