Marginals

Marginal(data, is_clamped::Bool, is_initial::Bool)
Marginal(data, is_clamped::Bool, is_initial::Bool, annotations::AnnotationDict)
Marginal(data, is_clamped::Bool, is_initial::Bool, annotations::AnnotationDict, logscale)

A marginal, the belief about a variable or a cluster of a factor node's variables: its data, usually a distribution, with the flags and the metadata the engine tracks for it.

Arguments

• data: the marginal itself, usually a distribution; the joint of a cluster may be a FactorizedCluster, and a marginal with a missing input is missing;
• is_clamped: whether the marginal comes from constants and observations alone. A clamped value is the result of computations on constants and observations alone: it never

changes during inference.

• is_initial: whether the marginal was set before inference or computed from initial values only. An initial value was set before inference, with ReactiveMP.set_initial_message! or

ReactiveMP.set_initial_marginal!, or computed from clamped and initial values only, at least one of them initial.

• annotations: the ReactiveMP.AnnotationDict of optional metadata. By default the engine's shared empty annotations, which nothing may write to: a marginal meant to be annotated is given its own AnnotationDict();
• logscale: the log scale of the product of messages the marginal was formed from (see getlogscale), or nothing, the default.

The statistics of the data are forwarded: mean, median, mode, var, std, cov, invcov, precision, entropy, params, mean_cov, mean_var, mean_invcov, mean_precision, weightedmean and its variants, shape, scale, rate, probvec, logdetcov, length, ndims, size, pdf and logpdf.

== compares the data and the is_clamped and is_initial flags, not the annotations or the log scale: those describe how a value was computed, not the belief it holds. Compare getannotations and getlogscale explicitly where they matter.

Examples

julia> marginal = Marginal(Gamma(10.0, 2.0), false, true)
Marginal(Distributions.Gamma{Float64}(α=10.0, θ=2.0))

julia> mean(marginal)
20.0

julia> is_clamped(marginal), is_initial(marginal)
(false, true)

See also Message, as_marginal.

getdata(marginal::Marginal)

The data of marginal, usually a distribution, or missing.

is_clamped(marginal::Marginal) -> Bool

Whether marginal comes from constants and observations alone. A clamped value is the result of computations on constants and observations alone: it never changes during inference.

is_initial(marginal::Marginal) -> Bool

Whether marginal was set before inference or computed from initial values only. An initial value was set before inference, with ReactiveMP.set_initial_message! or ReactiveMP.set_initial_marginal!, or computed from clamped and initial values only, at least one of them initial.

getannotations(marginal::Marginal) -> AnnotationDict

The ReactiveMP.AnnotationDict of marginal: a variable's marginal keeps the annotations of the product it was formed from; the joint marginal of a cluster has none. Where nothing may write to it, it is the shared, frozen empty value, which cannot be annotated afterwards.

getlogscale(marginal::Marginal)

The log scale of marginal: that of the product of the messages a random variable formed it from, a number or an UndefinedLogScale saying why it is not known. For a variable's marginal in a tree-shaped model inferred exactly by belief propagation, it is the log evidence of the data.

A data variable's marginal, an observation, has log scale zero, and so does a constant's.

Throws

• ArgumentError where the marginal carries no log scale: when log scales are not tracked, and always for an initial marginal set with ReactiveMP.set_initial_marginal! and for the joint marginal of a factor node's cluster, which carry none even with logscales = true.

as_marginal(message::Message) -> Marginal
as_marginal(marginal::Marginal) -> Marginal

A message as a Marginal, with its flags, annotations and log scale, its data in its public type: an efficient working type such as WishartFast becomes the type users expect (public_equivalent). A marginal is returned as it is. A variable forms its marginal from the product of its messages with it.

ReactiveMP.skip_initial()

The stream operator that drops initial values, those ReactiveMP.set_initial_marginal! and ReactiveMP.set_initial_message! seed, so that what follows only sees computed ones: get_stream_of_marginals(v) |> skip_initial(). The engine's free energy streams use it.

MarginalMapping

What computes the joint marginal of one cluster of a factor node, called with the latest messages and marginals the node's marginal rule depends on. A node builds one for each joint cluster at activation.

A call returns a missing marginal, and runs no rule, when an input is missing, or a static input folded into the node's function is data observed as missing. Otherwise it resolves the marginal rule with find_marginal_rule under the node's algorithm, checks it against the ReactiveMP.EngineDiagnostics and the services the node's context supplies (check_services), and runs it. Where no rule matches, it throws a RuleNotFoundError: a rule fallback does not apply to a marginal.

The marginal is clamped when every input is, and initial when it is not clamped and every input is clamped or initial. It carries no annotations and no log scale.

The callbacks receive ReactiveMP.BeforeMarginalRuleCallEvent and ReactiveMP.AfterMarginalRuleCallEvent around each call, the latter also for a missing marginal.

MarginalObservable()

The stream of a variable's marginals, or of a factor node's joint marginal of a cluster. Every subscriber shares one upstream subscription, and the latest marginal is kept, so Rocket.getrecent returns it and a late subscriber receives it at once.

The stream is lazy: activation connects it to its source. Before that, ReactiveMP.set_initial_marginal! can seed it with an initial marginal, which is what a rule reads before any marginal has been computed.

See also ReactiveMP.MessageObservable, ReactiveMP.get_stream_of_marginals.