Workspace · Endpoint contract

Development docs · 996102e0

View source

Endpoint Definition & Handoff Center

Use this center before executing a specification space. A robustness audit is interpretable only when every valid branch estimates the same declared scientific quantity, even though preprocessing, measurement, AOI, QC, sampling, or other defensible analytical choices may vary.

This builder does not invent an endpoint. It records your endpoint declaration and generates an intentionally incomplete Python skeleton. You must implement and validate the scientific calculation yourself. No contrast, unit, aggregation, missingness rule, null value, or non-finite policy is supplied by GazeAudit.

The runtime contract behind this page is small but important: run_specs() passes (processed_object, specification) to the endpoint callable and coerces the returned value with float(...). That coercion does not itself reject NaN or infinity. If finiteness is part of your endpoint contract, enforce it explicitly.

endpoint_name Endpoint name Required Stable human-readable label for the scientific endpoint. Boundary A label identifies the endpoint but does not define its scientific meaning by itself. scientific_quantity Scientific quantity Required Plain-language statement of the quantity every valid specification must estimate. Boundary If this quantity changes across branches, the branches do not belong in one common-endpoint robustness summary. unit Unit or scale Required Unit or dimensionless scale of the returned scalar estimate. Boundary Units must be consistent across branches; software does not infer or convert scientific units. contrast_direction Contrast / direction Required Define subtraction order, comparison direction, reference category, or sign convention where relevant. Boundary Reversing a contrast changes sign and can change the scientific interpretation even when the absolute magnitude is unchanged. analysis_unit Analysis unit and aggregation Required State whether the scalar is built from samples, fixations/events, trials, participants, condition means, or another aggregation. Boundary Changing weighting or aggregation can change the estimand even when variable names remain unchanged. population_denominator Population / denominator Required Define which observations or units are eligible to contribute to the endpoint before specification-specific processing. Boundary Silent denominator changes make across-specification estimates non-comparable. missingness_policy Missing / unavailable endpoint inputs Required State how missing or unavailable inputs are represented before the endpoint calculation. Boundary Missing values must not be silently converted to zero or removed without the declared rule. nonfinite_policy Non-finite endpoint policy Required State whether NaN or infinity is considered an endpoint-contract failure and how that failure remains visible. Boundary run_specs() float-coerces endpoint outputs but does not itself reject NaN or infinity. transformation Transformation / scaling Optional Record log transforms, normalization, standardization, rate conversion, or other transformations applied to the endpoint. Boundary A transformation changes the numerical scale and must remain consistent across branches being compared. scientific_null Scientific null / reference value Optional Record the null or reference value when direction or recovery is interpreted relative to one. Boundary GazeAudit does not infer the scientifically meaningful null from the observed estimates. required_inputs Required input fields / objects Required List the processed columns, events, probabilities, durations, conditions, or model outputs the endpoint requires. Boundary A branch missing a required input is an execution/evidence problem, not permission to substitute another endpoint. interpretation_boundary Interpretation boundary Required State what the endpoint does not measure and which broader claims it cannot support on its own. Boundary Endpoint clarity constrains interpretation but does not establish construct validity.

Optional code guard Generate an explicit `np.isfinite(...)` failure guard in the Python skeleton.

Leave this unchecked if your declared non-finite policy is implemented elsewhere. Checking it is a software guard choice, not a package recommendation about your scientific endpoint.

No endpoint declaration generated yet.

Documentation-side endpoint declaration

This JSON is a descriptive project record. It is not a new GazeAudit runtime object and does not prove construct validity.

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

Python endpoint skeleton

The generated skeleton is **intentionally incomplete**. The calculation remains a `NotImplementedError` until you replace it with the prespecified endpoint implementation.

# Complete the endpoint declaration first.

The common-endpoint rule

run_specs() is designed to answer:

How does the same scientific quantity change when defensible analytical choices change?

A branch may vary:

QC policy;
detector family/parameters;
AOI representation;
missing-data handling;
sampling representation;
preprocessing;
another declared analytical decision.

But every branch sent into one robustness summary should still return the same scientific quantity, with the same:

direction/sign convention;
unit or scale;
analysis unit and aggregation logic;
scientific denominator;
endpoint transformation;
interpretive target.

If one branch estimates dwell difference and another estimates fixation-count difference, that is endpoint drift—not ordinary specification variation.

What may vary without changing the endpoint?

This depends on the scientific declaration.

For example, a robustness audit might legitimately vary AOI radius while holding the endpoint definition as:

treatment minus control proportion of eligible gaze observations assigned inside the declared AOI representation.

The measurement/operationalisation choice changes, but the high-level scientific quantity and contrast remain fixed.

By contrast, switching from that occupancy contrast to latency-to-first-fixation changes the scientific quantity and should normally be a separate audit or explicitly separate endpoint amendment.

Endpoint invariance checklist

Before calling two branches comparable, verify:

The Endpoint definition and invariance guide explains each item.

Non-finite endpoint values

The package runtime does this internally:

estimate = float(endpoint(processed, spec))

float(np.nan) and float(np.inf) are legal Python values.

Therefore:

a non-finite endpoint is not automatically rejected by run_specs();
it is not a zero/null effect;
it should remain visible in the audit record;
if your endpoint contract requires finite output, check that explicitly in your endpoint/wrapper before interpretation.

The optional builder guard can generate:

estimate = float(estimate)
if not np.isfinite(estimate):
    raise ValueError("endpoint estimate must be finite under the declared contract")

Only enable that guard when it matches the declared endpoint/execution policy.

Endpoint versus processor

Keep responsibilities distinct.

Processor

Changes the representation according to the current specification.

Examples:

filter by a declared QC policy;
run a detector;
apply a missingness rule;
choose AOI geometry;
downsample;
perform another declared transformation.

Endpoint

Consumes the processed object and returns the common scalar scientific estimate.

Do not hide undeclared preprocessing choices inside the endpoint merely because the callable has access to spec.

Endpoint versus validity rule

valid_if answers:

Is this combination scientifically admissible before execution?

The endpoint answers:

What scalar scientific quantity does this valid processed branch produce?

Do not use endpoint exceptions to implement a scientific validity rule that could have been declared transparently before execution.

Endpoint versus conclusion rule

An endpoint is the scientific estimate.

A conclusion/recovery rule is a separate mapping from estimates/evidence to a categorical decision.

Do not bake the desired conclusion threshold into the endpoint calculation unless that threshold is itself part of the declared scientific quantity.

Reporting examples

Methods

A single endpoint was defined before specification execution as [scientific quantity], expressed in [unit], with [contrast direction], [analysis-unit/aggregation rule], and [eligible denominator]. Every valid specification returned this same scalar quantity; preprocessing and measurement choices varied only through declared specification factors.

Results

Endpoint estimates were compared only across branches preserving the declared endpoint contract. [N] valid represented specifications yielded [finite/non-finite/failure accounting] under the same [endpoint name] definition.

Limitation

The robustness audit characterises variation in the declared endpoint across the represented analytical choices. It does not establish that alternative scientific endpoints, aggregation targets, constructs, or untested transformations would yield the same conclusion.

API links

Continue from here

Endpoint definition and invariance — methodological design, implementation, validation, and reporting.
Endpoint drift audit — compare acceptable specification variation with scientific endpoint changes.
Specification-space guide — declare the analytical decision space.
Results Interpretation & Reporting Center — translate the completed endpoint evidence into bounded wording.