Guide · Read the outputs

Understanding the audit output bundle

A useful audit should leave behind more than one preferred estimate or figure. The first real audit is designed to save the structural record, the complete specification table, and multiple descriptive views of sensitivity together.

This page explains what each output is for, what question it answers, and what it does not establish.

Explore the bundle interactively

Use the artifact map to move through the output contract before reading the detailed sections below. The ordering follows a practical review path: provenance first, then the complete specification set, then progressively more compact sensitivity views.

The explorer is a navigation and interpretation aid. It does not rank artifacts by scientific importance or replace the complete bundle. Keep the outputs together rather than retaining only the file that supports the most convenient narrative.

Run the deterministic companion first

From a repository checkout with the package installed:

python examples/first_real_audit.py --output-dir demo-audit

The no---csv path uses deterministic synthetic demonstration data. It is useful for learning the file contract and checking that the workflow executes; it is not validation evidence for a real study.

For a canonical study table:

python examples/first_real_audit.py \
  --csv path/to/my_gaze.csv \
  --output-dir analysis-output

The worked example expects the seven documented canonical columns. Its demonstration AOI, quality levels, sampling stride, and endpoint must be replaced by study-specific choices before the pattern is treated as a substantive analysis.

Output map

Treat the directory as one evidence bundle. Do not retain only the file that gives the most convenient narrative.

1. Start with study-qc/

Read structural diagnostics before interpreting robustness outputs. A structural flag is a prompt for investigation, not an automatic exclusion instruction.

The QC layer is also where explicit decisions can be tied to diagnostic IDs. That separation matters: a data-shape observation and the researcher’s response to it are different pieces of evidence.

When archiving the analysis, preserve the study and audit fingerprints alongside the decision log so later readers can tell which representation was audited.

2. Treat specifications.csv as the audit backbone

specifications.csv should contain one row per evaluated specification. This is the most important table to preserve because all downstream summaries are views of this declared result set.

Useful checks include:

• every prespecified branch is represented;
• the endpoint has the same scientific meaning in every branch;
• factor values correspond to the declared decision space;
• failures or undefined estimates are visible rather than silently removed;
• the table was not filtered after results were observed.

If the declared space changes, treat that as a new audit decision and record why it changed.

3. Read the specification curve as a map, not a test

specification-curve.csv orders the evaluated estimates so the spread and sign pattern can be inspected directly. It is useful for seeing whether a headline estimate sits inside a tight cluster or among materially different alternatives.

The curve does not make every specification equally plausible, and its empirical quantiles are not confidence intervals. Scientific interpretation still depends on why the included alternatives were defensible for the study.

Continue with the specification-space guide for design principles and the plot gallery for the code-generated visual form.

4. Use effect stability as a compact descriptive summary

effect-stability.csv compresses the declared result set into empirical stability summaries. It is useful when a reader needs a concise account of whether estimates retain direction and how broadly their magnitude varies.

Report the underlying specification count and decision space with the summary. A stability statistic without the audited alternatives that generated it is difficult to interpret.

5. Use marginal sensitivity to locate consequential choices

marginal-sensitivity.csv groups estimates by levels of declared factors. It is a screening view for questions such as:

• do estimates move systematically across a quality-policy choice?
• does a sampling decision correspond to a noticeable magnitude shift?
• are AOI alternatives associated with materially different endpoint values?

These are descriptive comparisons across the declared specification set. They are not causal variance decompositions and should not be worded as if a factor experimentally caused the observed change.

6. Use pairwise sensitivity when one-factor summaries are insufficient

pairwise-sensitivity.csv helps reveal combinations of choices whose joint pattern is not obvious from marginal summaries alone.

A strong pairwise pattern is a reason to inspect the corresponding specifications and scientific assumptions. It is not, by itself, evidence that the same interaction generalises beyond the declared audit space.

7. Connect tables to visual diagnostics

GazeAudit’s deterministic plot layer is intended to make these audit questions easier to inspect. Useful routes include:

• specification curve for the spread of declared estimates;
• sampling sensitivity when acquisition or resampling assumptions matter;
• analysis readiness for cohort-policy consequences;
• AOI boundary uncertainty for measurement sensitivity.

The public plot gallery uses deterministic synthetic demonstrations unless a figure is explicitly identified as frozen observed evidence.

8. Archive the bundle with the analysis definition

A reproducible record should preserve, together:

1. the package version or exact commit;
2. input-data identity or a privacy-safe fingerprinting strategy;
3. semantic column mappings;
4. researcher-owned QC/readiness decisions and rationales;
5. the declared specification space;
6. the processor and endpoint definitions;
7. all specification results and sensitivity summaries;
8. generated figures and manuscript-facing interpretation.

For publication packaging, continue to the reproducible publication workflow and publication audits guide.

A compact reading order

When reviewing someone else’s bundle, a defensible order is:

QC/provenance → declared choices → complete specifications → curve/stability → marginal and pairwise sensitivity → figures → manuscript wording.

That order keeps the evidence-generating decisions visible before the most polished result summary is read.