Workspace · Readiness governance

Readiness Policy Design Center

Use this center after structural QC has been inspected and before a readiness rule is allowed to change the analysis cohort.

The builder is local to this documentation page. It does not upload a dataset, inspect your outcomes, infer thresholds, or filter a GazeStudy.

No policy draft generated yet.

# Choose a policy name and activate at least one justified criterion.

{
  "schema": "gazeaudit-readiness-policy-draft-v1",
  "policy_name": "",
  "thresholds": {}
}

What the generated code does

The output follows this sequence:

from gazeaudit import (
    ReadinessThresholds,
    cohort_impact_preview,
    evaluate_analysis_readiness,
)

policy = ReadinessThresholds(
    # only your active, declared criteria appear here
)

readiness = evaluate_analysis_readiness(
    study,
    policy,
    policy_name="your_policy_name",
)

print(readiness.status)
print(cohort_impact_preview(readiness))

This produces a policy-relative assessment and no-mutation cohort preview.

It does not remove rows, trials, or participants.

Understand the eight criteria before declaring them

Scope matters

Trial-level evaluation can fail:

• coordinate, timestamp, identifier, or duplicate-timestamp fractions;
• min_rows_per_trial;
• require_monotonic_time=True.

Participant-level evaluation can fail:

• the four aggregate issue fractions;
• max_flagged_trial_fraction;
• min_trials_per_participant;
• require_monotonic_time=True when any trial unit has decreasing time.

max_flagged_trial_fraction is downstream of the active trial policy. Changing the trial rules can therefore change the participant-level flagged-trial fraction even when the source table is unchanged.

Read readiness status conservatively

The status is always relative to the declared policy.

Preview before applying

Inspect:

readiness.trial_summary
readiness.participant_summary
readiness.cohort_impact

The cohort preview preserves three denominators:

• rows;
• participant × trial units;
• participant units.

Do not report only a retained percentage without stating which denominator and filter scope produced it.

Only after the policy and its cohort consequence have been justified should filtering be considered:

from gazeaudit import filter_study_by_readiness

analysis_study = filter_study_by_readiness(
    study,
    readiness,
    scope="trial",  # or "participant"; this is a separate scientific decision
)

The scope above is intentionally not selected by this builder.

Methodological guidance

Before activating a threshold, record:

1. criterion — which runtime rule is being used;
2. rationale source — preregistration, protocol, device evidence, task demand, prior validation, or sensitivity plan;
3. timing — whether the value was fixed before observing outcome results;
4. scope — trial or participant consequence;
5. cohort impact — rows/trials/participants retained under the policy;
6. alternative policies — whether nearby defensible policies materially alter the cohort or endpoint;
7. deviation — whether the final policy differs from the originally declared rule.

The Design and audit readiness policies guide develops each step.

Reporting examples

Methods

Analysis readiness was evaluated using a predeclared structural policy comprising [criteria and values]. GazeAudit first generated trial- and participant-level summaries and a no-mutation cohort-impact preview. Filtering was applied only after the declared policy and filter scope were fixed; omitted readiness criteria were not evaluated.

Results

Under the declared [policy name] policy, readiness status was [status]. Trial-level application retained [rows/trials/participants and denominators], whereas participant-level preview retained [corresponding denominators]. The analysis used the predeclared [trial/participant] scope.

Limitation

Readiness status is policy-relative and reflects the declared structural criteria only. It does not establish calibration accuracy, event-detector validity, AOI validity, missingness ignorability, or inferential robustness.

Replace every bracketed field with the actual project record.

API links

• ReadinessThresholds
• evaluate_analysis_readiness()
• cohort_impact_preview()
• readiness_policy_table()
• Analysis-readiness method pathway
• Machine-readable threshold reference

Continue from here

• Design and audit readiness policies — methodological rationale, timing, sensitivity, denominator governance, and reporting.
• Readiness policy design worked example — fully synthetic primary/alternative policy exercise.
• Analysis-readiness governance — runtime workflow, repair comparison, artifact export, and specification-space integration.
• Structural-QC triage — understand the structural evidence before turning it into a policy.