Guide · Project starter

Start a reproducible GazeAudit project

Use this page when you already have—or are about to receive—a study table and want a clean project structure before analysis begins.

The scaffold is deliberately small. It does not prescribe thresholds, AOIs, exclusions, detector settings, perturbation levels, endpoints, or interpretation rules. Those remain study-specific scientific decisions.

The 60-second route

1. Use a project layout that makes provenance visible

A minimal study directory can look like this:

my-study/
├── data/
│   └── my_gaze.csv
├── analysis/
│   └── run_audit.py
├── decisions/
│   └── audit-decisions.md
├── environment/
│   └── requirements.txt
└── evidence/

What matters is the separation of responsibilities:

Do not publicly commit identifiable, confidential, licensed, or otherwise restricted study data merely to reproduce this folder structure. Preserve restricted inputs using the storage and access controls appropriate to your project.

2. Start from the maintained executable example

Use examples/first_real_audit.py as the starting implementation for analysis/run_audit.py.

The example already demonstrates:

• explicit CSV loading;
• fail-closed canonical-column checks;
• GazeStudy construction;
• structural-QC provenance and fingerprints;
• one finite declared PipelineSpace;
• complete specification execution;
• specification-curve, effect-stability, marginal-sensitivity, and pairwise-sensitivity outputs;
• deterministic evidence writing.

Run the unmodified deterministic demo before adapting it:

python analysis/run_audit.py --output-dir evidence/demo-audit

Then run the canonical study table:

python analysis/run_audit.py \
  --csv data/my_gaze.csv \
  --output-dir evidence/main-audit

3. Make the input contract explicit before running anything

The worked executable expects these example-level canonical columns:

A quick local schema check is useful before executing the whole audit:

import pandas as pd

frame = pd.read_csv("data/my_gaze.csv", nrows=5)
required = {
    "participant",
    "trial",
    "timestamp",
    "x",
    "y",
    "condition",
    "quality",
}
missing = sorted(required.difference(frame.columns))
if missing:
    raise SystemExit(f"Map these columns explicitly before analysis: {missing}")
print(frame.dtypes)

If your source uses different names, either rename them deliberately or construct GazeStudy with explicit semantic mappings. Do not infer column meaning from position or similar-looking labels.

4. Freeze the software identity you intend to report

For the current stable public release:

# environment/requirements.txt
gazeaudit==0.1.0

Install that environment with:

python -m pip install -r environment/requirements.txt

If the study intentionally uses development main, record the exact commit instead of describing the environment only as “latest”. The documentation site can contain features newer than the stable public release.

5. Write down researcher-owned decisions next to the code

A compact decisions/audit-decisions.md can use a simple structure:

# Audit decisions

## Study representation
- Coordinate system / units:
- Timestamp units:
- Participant / trial unit:

## Structural-QC review
- Diagnostic ID:
- Decision:
- Rationale:

## Declared analytical alternatives
- Factor:
- Levels:
- Scientific justification:

## Endpoint
- Prespecified quantity:
- Why it is held constant across specifications:

This human-readable record complements the machine-generated QC decision artifacts. It should explain why the study-specific choices were defensible, not merely repeat parameter values.

6. Replace every demonstration-specific choice before interpreting real results

The maintained example deliberately uses simple demonstration values for quality thresholds, sample stride, AOI radius, condition labels, and an occupancy-difference endpoint.

Before treating a run as your study analysis, replace them with choices that were defensible for the actual acquisition and research question.

7. Verify the evidence directory before interpretation

After a successful run, the audit directory should contain the structural-QC evidence plus the complete robustness outputs:

Preserve the whole bundle. Do not keep only the branch or summary that is easiest to report.

Empirical specification quantiles are not confidence intervals, and marginal or pairwise sensitivity summaries are not causal variance decompositions.

8. Continue only when the next layer answers a real question

Once the basic project is running:

• use data onboarding when source-column mapping or structural-QC interpretation needs more detail;
• use analysis-readiness governance when participant/trial retention rules need to be declared;
• use AOI uncertainty when gaze-position uncertainty at boundaries matters;
• use specification spaces when the analytical decision space needs to expand beyond the compact example;
• use publication audits when the final evidence package must be fingerprinted and archived.

For a linear walkthrough, continue with First real audit with your own data. For the study-level sequence, use the first-study audit workflow.