GazeAudit uncertainty × robustness
v0.2.0 · development docs GitHub

Reference · API pathways

Look up Exact contract or terminology; reference is not a scientific recommendation. Documentation compass
Development docs · 996102e0
View source

API pathways

Use this page when you already know a public symbol and want to move from that symbol to the surrounding research context: its governed method family, practical guide, runnable example, diagnostic visual, and evidence boundary.

The page is generated from the same _data/methods.yml catalog that powers the Method explorer. It does not maintain a second method taxonomy.

Navigation, not scientific recommendation. A pathway tells you where a public function appears in the governed documentation. It does not decide whether the method, threshold, exclusion, endpoint, perturbation, or evidence claim is appropriate for a particular study.
## Jump by method family ## Deep link directly to a public symbol Each symbol below has a stable fragment identifier. Opening or sharing a symbol link lands on the method family that currently governs its documentation context.

Structural QC

GazeStudy audit_study_qc study_qc_diagnostics build_study_qc_audit

Analysis-readiness governance

ReadinessThresholds evaluate_analysis_readiness cohort_impact_preview readiness_policy_table

AOI measurement uncertainty

GaussianGazeErrorModel aoi_probabilities compare_hard_probabilistic expected_dwell

Specification-space robustness

PipelineSpace run_specs specification_curve effect_stability

Sampling-rate sensitivity

downsample_gaze sampling_sensitivity_curve

Missingness sensitivity

missingness_mask inject_missingness missingness_sensitivity_curve summarize_missingness

Spatial-error sensitivity

scale_error_model spatial_sensitivity_curve

Known-truth recovery

simulate_known_aoi_effect benchmark_known_aoi_effect ConclusionRule summarize_conclusion_recovery

Publication provenance

build_conclusion_audit_bundle verify_publication_audit_bundle render_publication_methods fingerprint

Interoperability

read_bids_eyetrack from_pymovements_gaze make_peyes_detector run_detector_backend
## Governed API routes

Preflight

Structural QC

# pathway

Is the canonical gaze table structurally safe to inspect downstream?

Detect non-finite coordinates or timestamps, missing identifiers, duplicate timestamps, and decreasing within-trial time without turning those diagnostics into a universal quality score.

Public API route

GazeStudy → audit_study_qc → study_qc_diagnostics → build_study_qc_audit
Guide Data onboarding guide Run / example Study preflight example Visual QC issue profile

Evidence boundary

Descriptive preflight; no frozen real-data outcome is assigned to this method family.

No frozen empirical case is assigned to this pathway.

Governance

Analysis-readiness governance

# pathway

What cohort consequences follow from the structural policy I declare?

Aggregate trial and participant diagnostics, preview retention consequences, compare declared policies, and preserve the policy as provenance rather than as an automatic exclusion rule.

Public API route

ReadinessThresholds → evaluate_analysis_readiness → cohort_impact_preview → readiness_policy_table
Guide Readiness guide Run / example Readiness example Visual Cohort-impact preview

Evidence boundary

Policy-relative governance; passing a policy is not a universal scientific-validity judgement.

No frozen empirical case is assigned to this pathway.

Measurement

AOI measurement uncertainty

# pathway

Would the endpoint change if gaze coordinates near AOI boundaries were not treated as exact?

Represent declared gaze-position error, estimate probabilistic AOI membership, compare it with hard assignment, and propagate measurement uncertainty into dwell or fixation endpoints.

Public API route

GaussianGazeErrorModel → aoi_probabilities → compare_hard_probabilistic → expected_dwell
Guide AOI uncertainty guide Run / example Boundary example Visual AOI probability profile

Evidence boundary

The frozen Korthals audit retained a negative paired effect under the prespecified uncertainty model.

Korthals frozen case →

Robustness

Specification-space robustness

# pathway

Does the endpoint survive other defensible analytical choices?

Declare a finite decision space, execute one common endpoint across valid specifications, and inspect sign, magnitude, and factor sensitivity without searching for a favourable pipeline.

Public API route

PipelineSpace → run_specs → specification_curve → effect_stability
Guide Specification-space guide Run / example End-to-end audit Visual Specification curve

Evidence boundary

The frozen GazeBase programme stopped at its predeclared completeness gate rather than forcing a robustness conclusion.

GazeBase frozen case →

Sensitivity

Sampling-rate sensitivity

# pathway

How much does the endpoint move as temporal sampling resolution is reduced?

Downsample by retaining existing samples nearest a declared target grid and evaluate the same endpoint across controlled sampling rates without coordinate interpolation.

Public API route

downsample_gaze → sampling_sensitivity_curve
Guide Sensitivity context Run / example Sampling example Visual Sampling sensitivity

Evidence boundary

The frozen Pedrotti/de Chambrier audit found materially degraded magnitude recovery at lower sampling rates.

Pedrotti frozen case →

Sensitivity

Missingness sensitivity

# pathway

How robust is the endpoint to controlled amounts and mechanisms of missing gaze data?

Construct declared missingness masks, apply them without hiding the perturbation mechanism, and evaluate endpoint recovery across controlled missingness families.

Public API route

missingness_mask → inject_missingness → missingness_sensitivity_curve → summarize_missingness
Guide Sensitivity context Run / example Robustness workflow Visual Missingness sensitivity

Evidence boundary

The frozen Pedrotti/de Chambrier protocol includes controlled MCAR and single-block missingness recovery.

Pedrotti frozen case →

Sensitivity

Spatial-error sensitivity

# pathway

How dependent is the endpoint on the scale of the declared gaze-error model?

Scale an explicit measurement-error model and rerun a common endpoint across controlled spatial uncertainty levels.

Public API route

scale_error_model → spatial_sensitivity_curve
Guide AOI uncertainty guide Run / example Boundary example Visual Factor sensitivity

Evidence boundary

Korthals provides frozen measurement-error propagation evidence; it is not a generic spatial-sensitivity benchmark.

Korthals measurement case →

Benchmarking

Known-truth recovery

# pathway

Can the analysis family recover a conclusion when the generating truth is known?

Simulate declared AOI effects, evaluate recovery under a predeclared conclusion rule, and compare analysis families without confusing synthetic recovery with empirical validation.

Public API route

simulate_known_aoi_effect → benchmark_known_aoi_effect → ConclusionRule → summarize_conclusion_recovery
Guide Scientific methods Run / example Audit context Visual Recovery matrix

Evidence boundary

Synthetic known-truth benchmark by design; it is not a frozen real-data case study.

No frozen empirical case is assigned to this pathway.

Evidence

Publication provenance

# pathway

Can another researcher verify exactly what was declared, run, and reported?

Bind results, rules, manifests, methods text, software metadata, and content fingerprints into deterministic publication evidence that can be verified after writing.

Public API route

build_conclusion_audit_bundle → verify_publication_audit_bundle → render_publication_methods → fingerprint
Guide Publication-audit guide Run / example Publication workflow Visual Policy trade-offs

Evidence boundary

The validation matrix shows how outcome labels remain bound to exact protocol and execution records.

Frozen validation matrix →

Integration

Interoperability

# pathway

How do I bring external eye-tracking data or detector outputs into the canonical audit workflow?

Convert supported BIDS, pymovements, pEYES, or custom adapter inputs into explicit GazeAudit contracts while keeping upstream semantics visible.

Public API route

read_bids_eyetrack → from_pymovements_gaze → make_peyes_detector → run_detector_backend
Guide Interoperability guide Run / example Canonical onboarding Visual Gaze trajectory and AOI

Evidence boundary

Interoperability is guarded by live contract CI; it is not itself a frozen empirical outcome.

No frozen empirical case is assigned to this pathway.

Source-level details

When JavaScript is available, each governed symbol above is enhanced from the deterministic API metadata artifact with:

  • the exact inspected Python signature;
  • a compact expandable parameter contract with parameter kind, annotation, requiredness, and software default;
  • the inspected return annotation;
  • a mechanically generated minimal call shape containing only required arguments;
  • function/class kind and source module;
  • repository-relative source file and first source line;
  • the first source-docstring summary;
  • a direct source link pinned to the documentation build revision;
  • copyable public-import and minimal-call snippets;
  • backlinks to every governed method pathway that uses the symbol.

The minimal call is deliberately structural. Placeholder names such as study, endpoint, or min_event_duration are not fabricated study values, and omitting an optional argument from the minimal call does not make its software default scientifically appropriate.

The static symbol, method-family, guide, example, visual, and evidence-boundary links remain available when JavaScript or metadata loading is unavailable. The generated metadata is verified against the installed package in CI, so a signature/source change cannot silently leave the checked reference stale.

For example, a direct link to run_specs is:

/docs/reference/api-pathways/#api-run-specs

That link does not make run_specs the correct tool for a study. It only resolves the symbol into its governed Specification-space robustness context, where you can inspect the guide, runnable example, specification-curve visual, and the exact evidence boundary.

For a worked exercise in reading required arguments, keyword-only requirements, returns, and minimal call shapes, continue to Generated API call contracts. For symbol → example → evidence-boundary navigation, use Function → example → evidence. For broad task-first discovery, use the Method explorer.

Documentation search

Find the right documentation

↑↓ navigateEnter openEsc close