Reference · Structural QC

Structural QC Issue Clinic

Use this page after audit_study_qc() returns status == "review" or when you need to interpret a row/group emitted by study_qc_diagnostics().

Structural preflight evaluates a bounded set of implemented representation conditions; it is not a complete measurement-quality or scientific-validity assessment.

The governed catalog below is the documentation authority for the five currently implemented issue families. CI regression tests bind it to the live diagnostic output so a runtime change cannot silently leave the clinic stale.

Showing all 5 issue families.

Read the layers in the right order

A structural preflight has several different outputs. They answer different questions:

Do not skip directly from status == "review" to filtering.

Minimal inspection sequence

from gazeaudit import audit_study_qc, study_qc_diagnostics

report = audit_study_qc(study)
diagnostics = study_qc_diagnostics(study)

print(report.status)
print(report.issue_codes)
print(
    diagnostics[
        [
            "diagnostic_id",
            "scope",
            "issue_code",
            "detail_code",
            "row_position",
            "participant",
            "trial",
            "timestamp",
        ]
    ]
)

Then connect each diagnostic back to the source/mapping provenance before deciding whether the condition is a valid representation, a repairable construction problem, a study-specific exclusion issue, or an unresolved limitation.

Record the decision instead of deleting the evidence

When an issue has been inspected, StudyQCDecision and build_study_qc_audit() let you bind the action and rationale to the diagnostic record.

from gazeaudit import StudyQCDecision, build_study_qc_audit

decision = StudyQCDecision(
    issue_code="timestamp_duplicate",
    action="retain after representation review",
    rationale="Rows are simultaneous channel records in the declared source representation.",
    diagnostic_ids=("D000001", "D000002"),
)

audit = build_study_qc_audit(study, decisions=(decision,))

The action above is an illustration, not a default. The correct action depends on the source representation, acquisition protocol, preprocessing history, endpoint, and study-owned decision rules.

If you change the table

A repair that changes mapped coordinates, time, participant/trial identifiers, or row order changes the canonical study representation.

After a repair:

1. preserve the pre-repair evidence if it supported an earlier analysis;
2. update the data-mapping provenance;
3. rebuild GazeStudy;
4. rerun audit_study_qc() and study_qc_diagnostics();
5. create a new decision/audit record;
6. rerun downstream analyses affected by the change.

Do not reuse old diagnostic IDs after changing the audited representation.

Interpretation and reporting

A defensible Methods statement describes what was checked and how decisions were governed, not merely that “data quality was checked.”

Structural preflight evaluated non-finite gaze coordinates and timestamps, missing canonical identifiers, duplicate participant × trial timestamps, and decreasing within-unit time. Flagged conditions were inspected against source and preprocessing provenance; any repair, retention, or exclusion decision was recorded explicitly rather than applied automatically.

A Results statement should report the observed scope and preserve the denominator. For example:

Structural preflight returned review because duplicate timestamps and non-finite coordinates were present. The affected rows/units were inspected using row/group diagnostics, and the resulting decisions were retained in the structural-QC audit record.

Replace the issue families and counts with the study’s actual record. Do not copy numerical values from synthetic examples.

If a condition remains unresolved, say so. An unresolved limitation is preferable to a fabricated repair or an unexplained exclusion.

API routes

Use the source-level API pathways for exact current signatures and source links:

• GazeStudy
• audit_study_qc()
• study_qc_diagnostics()
• build_study_qc_audit()
• Structural-QC method pathway
• Machine-readable QC issue catalog

Continue from here

• Structural-QC triage guide — step-by-step inspection, decision, repair, rerun, and reporting workflow.
• All structural-QC issues worked example — one synthetic fixture exercising all five issue families and all ten detail codes.
• Data onboarding and structural preflight — full provenance and artifact workflow.
• Analysis-readiness governance — apply researcher-declared thresholds only after structural evidence is understood.