bayesmith.diagnose.map

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

Module contract

A graph-native posterior mode, with refusals that belong to MAP.

The objective is exactly ``-log_joint(graph, values)`` over every latent in
declaration order.  It is not prior sensitivity's likelihood-only
counterfactual and deliberately does not inherit that diagnostic's three
admission rules: hierarchical priors may depend on other latents, densities
need not be diagonal Gaussians, and the likelihood alone need not anchor a
direction that the full posterior anchors legitimately.

This remains a local optimisation result.  A successful mode says nothing
about other basins, posterior mass, or funnel geometry; a Laplace diagnostic
centred here inherits those blind spots.

MapEstimate Refused NotApplicable MapResult map_estimate

MapEstimate

Defined in bayesmith.diagnose.map, line 40.

class MapEstimate(Mapping[str, jax.Array])
point: dict[str, jax.Array]
objective: float
gradient_norm: float
steps: int
verdict: ClassVar[str] = 'measured'

A converged local posterior mode and its optimisation evidence.

The object is itself a mapping, so it can be passed directly where graph
diagnostics expect ``{latent: value}``, including
``local_block(graph, names, estimate, priors=True)``.

Refused

Defined in bayesmith.diagnose.coupling, line 65.

class Refused
reason: str
verdict: ClassVar[str] = 'refused'

A diagnostic whose arithmetic cannot support a numerical verdict.

NotApplicable

Defined in bayesmith.diagnose.map, line 65.

class NotApplicable
reason: str
verdict: ClassVar[str] = 'not-applicable'

The graph contains no unknown quantity for MAP to estimate.

MapResult

Defined in bayesmith.diagnose.map, line 72.

MapResult = MapEstimate | Refused | NotApplicable

map_estimate

Defined in bayesmith.diagnose.map, line 108.

map_estimate(graph: Graph, *, at: dict[str, jax.Array] | None=None) -> MapResult

Find a local mode of the graph's complete posterior.

Args:
    graph: the declared model.  Every probabilistic term, observed mask,
        and graph-level joint prior enters through :func:`log_joint`.
    at: optional Newton starting point.  Missing latents start at their
        declared centres; keys and shapes are validated by name.

Returns:
    :class:`MapEstimate` on convergence, :class:`Refused` when the
    arithmetic or local optimisation cannot support a MAP, and
    :class:`NotApplicable` for a graph with no latents.  Every refusal
    includes an actionable alternative rather than leaking the last
    iterate as if it had converged.

Raises:
    GraphError: for a malformed ``at`` mapping or a latent with no
        real-valued continuous derivative.  Those are caller/graph
        contract errors, not optimisation verdicts.