Workspace · Robustness declaration

Development docs · 996102e0

View source

Specification Space Declaration Center

Use this center after the endpoint is declared and before specification estimates are visible.

This builder records a decision space; it does not decide which alternatives are scientifically defensible. Factors, levels, invalid combinations, and timing remain researcher-owned. The browser computes only the Cartesian declared count. It never invents a valid-specification count or a scientific validity predicate.

Before using this page, define the common endpoint in the Endpoint Definition & Handoff Center.

Declaration context

space_name Specification-space name Required Stable project label for the declared analytical decision space. Boundary A name identifies the space but does not justify any factor or level. scientific_question Robustness question Required State what uncertainty or analytical-decision question the specification space is intended to examine. Boundary The space should answer a declared robustness question rather than search for a favourable result. endpoint_reference Endpoint declaration reference Required Link or project identifier for the endpoint declaration shared by every valid specification. Boundary Referencing an endpoint record does not prove every processor branch actually preserves it. decision_timing Decision timing Required Record when the factor set, levels, and validity rules were fixed relative to outcome inspection. Boundary Post-result or reviewer-requested additions must remain temporally visible. validity_rule Pre-execution validity rule Optional Describe any combinations that must be rejected before execution and why. Boundary Outcome-informed rejection after estimates are visible must not be rewritten as a predeclared validity rule. reference_specification Reference specification Optional Record a prespecified reference branch when the study uses one for orientation or comparison. Boundary A reference specification is not automatically scientifically superior to the other valid branches. failure_policy Execution-failure policy Required State how valid branches that raise, return unavailable inputs, or yield non-finite endpoints remain visible in the audit. Boundary Valid technical failures must not silently disappear from the valid denominator. interpretation_boundary Interpretation boundary Required State which decisions or uncertainty dimensions are outside the declared space. Boundary Stability inside the declared space cannot be generalized automatically to choices that were never represented.

Declared factors

Each factor needs a unique name, an explicit value type, at least one level, and a study-specific rationale.

Factor 1

Factor name Level type Levels — one per line Scientific rationale

Pre-execution validity

Validity-rule mode

If some combinations are invalid, describe the rule in the declaration-context field above. The generated Python will contain a NotImplementedError validity stub rather than guessing the predicate.

No specification declaration generated yet.

Declaration record

This JSON is documentation-side provenance. It records the declared factor space and timing; it does not certify that the factors or levels are scientifically defensible.

{
  "schema": "gazeaudit-specification-declaration-v1"
}

PipelineSpace skeleton

Factor levels are emitted exactly as declared. When a pre-execution validity predicate is required, the generated function intentionally remains unimplemented.

# Complete the specification declaration first.

Declared, valid, and successful are different denominators

Declared

The Cartesian product represented by PipelineSpace.size.

For factors with 2 × 2 × 3 levels:

declared combinations = 12

The browser can calculate this from your factor declaration.

Valid

The subset that survives a scientific valid_if rule fixed before execution.

If validity exclusions exist, this center deliberately reports the valid count as unknown until the predicate is actually implemented and enumerated.

Successful

Valid branches that complete the processor/endpoint execution contract.

Technical failures remain part of the valid denominator even though they do not yield a normal endpoint row.

Do not rewrite:

6 successful / 7 valid

as:

6 / 6

What belongs in a factor?

A factor should represent a scientifically defensible analytical or measurement decision whose consequences you intend to audit.

Examples can include:

detector family;
declared detector parameter;
QC/readiness policy;
missingness handling rule;
AOI representation;
spatial-error model;
sample-retention or sampling representation;
another preprocessing decision.

A factor should not be included merely because the software can vary it.

What belongs in a level?

Every level should have a rationale independent of the observed endpoint.

Good evidence sources can include:

protocol;
preregistration;
device or method validation;
established analysis alternatives;
reviewer-requested sensitivity, labelled with its timing;
deliberately bounded sensitivity values.

Do not populate a dense grid simply to search for a favourable estimate.

Unique factor names matter

PipelineSpace.add_choice(name, values) stores factor choices by name.

This builder requires unique names so a later factor cannot silently replace the declaration of an earlier factor in the generated skeleton.

Use names that remain meaningful in exported tables and manuscript provenance.

Validity rules belong before execution

Use valid_if for combinations known to be scientifically inadmissible before the endpoint is evaluated.

Examples:

one detector parameter exists only for a particular detector family;
a preprocessing mode is incompatible with a declared representation;
a model choice requires an input that another declared branch does not produce by design.

Do not use valid_if to discard branches because:

the estimate is surprising;
the sign is inconvenient;
the p-value is unattractive;
execution failed technically;
the endpoint was non-finite.

Those are different evidence states.

Reference specification is optional

A study may define one reference pipeline for orientation, comparison, or legacy continuity.

A reference branch is not automatically:

the truth;
the scientifically best branch;
the branch that should receive more interpretive weight.

Robustness summaries should still account for the complete valid represented space.

Failure policy must be declared separately

Before execution, decide how to preserve:

processor exceptions;
endpoint exceptions;
missing required endpoint inputs;
non-finite endpoints;
branches that were never run.

GazeAudit core run_specs() propagates exceptions. If your project uses an audited wrapper/ledger to continue other branches, retain the original failure event and the valid denominator.

Timing must remain visible

Classify the declaration honestly:

preregistered;
fixed before outcome inspection;
post hoc sensitivity;
reviewer-requested amendment;
correction.

A later factor or level can be scientifically useful while still being temporally distinct from the submitted decision space.

Reporting examples

Methods

We declared a specification space before endpoint inspection comprising [factor names] with [levels and rationale]. The Cartesian space contained [N] combinations. [All combinations were admissible / a pre-execution validity rule excluded X combinations for stated scientific reasons], yielding [V] valid specifications. Every valid branch targeted the same endpoint declaration, [endpoint reference].

Results

[S] of [V] valid specifications successfully produced the declared endpoint. [Technical failure / non-finite / not-run accounting] remained visible in the valid denominator. Estimates were summarised across the represented valid branches without selecting a preferred pipeline after outcome inspection.

Limitation

The audit covers only the declared factors and levels. Stability within this space does not establish robustness to analytical, measurement, endpoint, or population choices that were not represented.

API links

Continue from here

Specification-space declaration and validity — methodological design, denominator governance, timing, and failure accounting.
Declared → valid → successful — fully synthetic denominator exercise.
Endpoint Definition & Handoff Center — define the scalar quantity shared across branches.
Specification-space guide — execute and interpret the declared space.
Results Interpretation & Reporting Center — translate completed evidence into bounded claims.