bayesmith.evaluation.evidence

Source-derived signatures and contracts. See the reference index for coverage and conventions.

Module contract

What an ``EvidenceResult`` can say about itself, and about another one.

Three reports and a gate. They are the evaluation half of R4: the assembly
lives in ``dispatch.evidence`` and decides nothing here, and nothing here
changes a number -- §2.4's rule that evaluation judges a Result and does not
modify it or choose an algorithm.

``evidence_normalization_audit``
    Every latent's prior, weighed. An evidence is defined only if each prior
    has finite mass and it is THE evidence only if each mass is one, so this
    report is where those two verdicts are filed for a Result that already
    exists. The compile-time gate refuses before assembling; this says the same
    thing about a Result someone hands you later.

``evidence_prior_sensitivity``
    ``d log Z / d log s``, in nats per e-fold of prior width. R4 REPORTS it and
    does not threshold it, and that is deliberate: no derivation for a
    criterion exists yet, and ``CRITERION_SHIFT`` -- the only prior-sensitivity
    number this package has -- is derived from a chain's MCSE of a posterior
    mean, which has nothing to do with nats of log evidence.

    **It is a different report kind from R3's ``prior_sensitivity`` and the
    difference is not bookkeeping.** R3's measures a posterior MODE
    displacement in posterior sigmas. Centre a prior on the mode and the
    displacement is zero, so R3's report PASSes -- while changing that same
    prior's WIDTH moves ``log Z`` by exactly ``-sum(log s)``. The two disagree
    on the perturbation ``Z`` is most sensitive to, and §1.4 invariant 3
    forbids two statistical objects sharing a name.

``evidence_comparability``
    Whether two ``EvidenceResult``s may be divided. Delivered as a report and
    not as a Refusal, because a ``Refusal`` cannot express it: its
    ``__post_init__`` calls ``task_kind(self.task)``, which raises for anything
    that is not one of the five Tasks, so there is no Refusal whose subject is
    a pair of Results.

Dependency direction: this module reads ``artifacts`` and ``dispatch`` and is
read by nothing in ``src``. ``tests/test_layering.py`` holds that.

EVIDENCE EVIDENCE_COMPARABILITY EVIDENCE_NORMALIZATION_AUDIT EVIDENCE_PRIOR_SENSITIVITY comparability_report normalization_audit_report prior_sensitivity_report

EVIDENCE

Defined in bayesmith.evaluation.evidence, line 422.

EVIDENCE = GateDefinition(name='evidence', version=1, requirements=(ReportRequirement(name=EVIDENCE_NORMALIZATION_AUDIT, required=True), ReportRequirement(name=EVIDENCE_PRIOR_SENSITIVITY, required=False), ReportRequirement(name=EVIDENCE_COMPARABILITY, required=False)), blocked_actions=(), remedies=(Remedy(action='declare_a_proper_normalised_prior_on_every_latent', message='p(d) is the integral of the likelihood against the prior, so a prior with infinite mass leaves it undefined and one whose mass is not one leaves it scaled. Neither affects the posterior, which is why an evidence has its own gate.'), Remedy(action='read_the_prior_sensitivity_rather_than_pass_it', message='d log Z / d log s is REPORTED and not thresholded in this release: no derivation for a criterion exists, and the posterior-mode criterion this package already has measures a different perturbation. A PASS here means the slope was measured, not that it is small.')))

EVIDENCE_COMPARABILITY

Defined in bayesmith.evaluation.evidence, line 82.

EVIDENCE_COMPARABILITY = 'evidence_comparability'

EVIDENCE_NORMALIZATION_AUDIT

Defined in bayesmith.evaluation.evidence, line 80.

EVIDENCE_NORMALIZATION_AUDIT = 'evidence_normalization_audit'

EVIDENCE_PRIOR_SENSITIVITY

Defined in bayesmith.evaluation.evidence, line 81.

EVIDENCE_PRIOR_SENSITIVITY = 'evidence_prior_sensitivity'

comparability_report

Defined in bayesmith.evaluation.evidence, line 335.

comparability_report(first: EvidenceResult, second: EvidenceResult) -> EvaluationReport

Whether these two evidences may be divided.

Comparable iff the DATA fingerprint is unchanged between them.
``MODEL_SOURCE`` and ``GRAPH_STRUCTURE`` differ by construction in any
model comparison -- that is what a model comparison IS -- so ``DATA`` is
the only slot that can be required.

Both sides are first checked against themselves. Nothing in ``_envelope``
requires a Result's ``meta.fingerprints`` to equal its ``run.fingerprints``,
and a rule reading ``meta`` on one artifact and ``run`` on the other would
compare two different bundles while looking symmetric.

normalization_audit_report

Defined in bayesmith.evaluation.evidence, line 135.

normalization_audit_report(subject: EvidenceResult, graph: Graph) -> EvaluationReport

Every latent's prior, weighed, filed against an existing Result.

PASS when every prior is proper and normalised; FAIL when one is not;
ABSTAIN when the audit could not decide one. UNVERIFIABLE is reserved for
the case where nothing could be weighed at all -- a graph with no latents
is not a model whose priors passed.

prior_sensitivity_report

Defined in bayesmith.evaluation.evidence, line 256.

prior_sensitivity_report(subject: EvidenceResult, graph: Graph, block: tuple[str, ...]) -> EvaluationReport

``d log Z / d log s`` per latent, reported and not judged.

The derivative is taken by central difference across one e-fold either
side of each declared width, which is the unit it is quoted in, so no
step size is chosen and nothing is compared against a threshold.

APPLICABLE x PASS whenever a derivative could be taken at all. R4 does not
threshold this: a criterion would need a derivation nobody has, and the
number's job here is to be READ. Filing it as a PASS with the measurement
in the findings is the honest shape -- the alternative is a threshold
invented to make the report look decisive.