Conditional latent states
This example simulates a hidden Markov chain with two states and a continuous observation at each step. The transition matrix favors staying in the current state. Each state has its own normal emission mean, with a shared known observation scale. The model sums over the latent path when evaluating its density. Afterward, a conditional-latent query recovers state probabilities at supplied values of the continuous parameters; no statistical fit runs in this documentation build.
Data
A seeded random number generator makes the simulated observations reproducible. The state sequence is retained only as a diagnostic because it is known in this simulated dataset. The inference query receives the observations, not the generating states.
using ReactiveKernelsPPL, Random, AlgebraOfVega
using ReactiveKernelsDistributionKernels.DistributionKernelSources: normal_hmm_logdensity
using Main.Tutorials
rng = Xoshiro(2019)
transition = [0.90 0.10; 0.10 0.90]
means = [0.0, 2.0]
noise = 0.7
steps = 40
states = zeros(Int, steps)
states[1] = rand(rng, 1:length(means))
for t in 2:steps
states[t] = min(searchsortedfirst(
cumsum(transition[states[t - 1], :]), rand(rng)), length(means))
end
y = means[states] + noise * randn(rng, steps)
(; observations=y, generating_states=states)(observations = [2.9510187584632144, 1.775316939962112, 1.5360756716797328, 0.5739705975360772, -0.2701929059801814, -0.09058912705455843, 0.2812038271921625, 0.8189100049294072, -0.3394254170631455, 1.2460492347059737, -0.5580119064497399, 0.8987289934632221, 0.19100414282146347, 1.5000753915155707, 2.5696032952644834, 2.51934532845023, 1.48566105068962, 2.2746624717581287, 2.222521732491672, 3.1322902585615084, 0.7519081780887862, 2.032408273994601, 2.588534294122516, 1.5995248769947934, 2.298057783450636, 2.719127723264054, 1.1144178495852093, 1.9529959320555847, 1.63934342337016, 1.9977263502470923, 2.3515844363874043, 1.2978959484677108, 1.0091353063700674, 1.8925558089505086, 1.0697725596397247, -0.3820779151644963, -0.41639130398798846, -0.7357860191261463, 0.49074471212981347, 1.1858029174583589], generating_states = [2, 2, 2, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 1, 1, 1, 1, 2])
The observation scale allows the emission distributions to overlap. A single observation can therefore leave uncertainty about its state even when the transition matrix and emission means are known. Neighboring observations provide further information through the transition model. The example keeps those parameters fixed at their generating values so that this conditional uncertainty is separate from uncertainty about the parameters themselves.
Model
Each transition row has a Dirichlet prior. The emission means have normal priors. The distribution kernel used for the observations evaluates the marginalized hidden Markov likelihood, with a uniform initial-state distribution. The state count, prior settings and observation scale enter through the model binding.
model = @rkppl begin
eachrow(T[1:K, 1:K]) .~ Dirichlet(concentration)
m[1:K] .~ Normal.(mean_prior, mean_scale)
y ~ LogDensity(normal_hmm_logdensity, m, noise, T, initial)
end
K = length(means)
bound = model(;
K, concentration=ones(K) ./ K,
mean_prior=means, mean_scale=1.0, noise,
initial=ones(K) ./ K,
) | (; y)
built = build_kernel(bound)
u = unconstrain(built.layout, (; T=transition, m=means))
target = prepare_query(built, bound, :sampler)
target(u)-55.618989711294844
The sampler-facing vector contains continuous transition and emission parameters. It does not contain a discrete coordinate for every step. Summing out the path preserves a continuous density for those parameters while retaining a separate query for the conditional states.
The generated model view shows the program used for these queries. Its dependency graph and generated expressions come from the built model rather than a second authored representation of the hidden Markov calculation.
Tutorials.html(model_view(built; bound))Conditional probabilities
Prepare the discrete-latent query once, then evaluate it at the unconstrained parameter vector. The returned response field contains probabilities for every step and state, together with the filtered and transition quantities used for path draws.
latents = prepare_discrete_latents(built, bound)
posterior = latents(u).y
probabilities = posterior.probabilities
most_probable = [argmax(probabilities[t, :]) for t in eachindex(y)]
(; probabilities, most_probable)(probabilities = [5.14701078387082e-5 0.9999485298921605; 0.004153215975011201 0.9958467840249882; 0.09049302065362347 0.909506979346377; 0.863227089018758 0.13677291098124036; 0.9991680860928722 0.0008319139071298684; 0.9998346959118645 0.00016530408813444884; 0.9990198660643175 0.0009801339356837677; 0.9937370242556375 0.006262975744369212; 0.9997179582119696 0.000282041788035842; 0.9670236830530836 0.032976316946925724; 0.9997491910114363 0.00025080898856862956; 0.9718336138292235 0.028166386170777796; 0.9488632772962925 0.05113672270371205; 0.10931374953602258 0.8906862504639809; 0.00019875052659222112 0.9998012494734101; 2.8886421482025718e-5 0.9999711135785219; 0.0017105079130890213 0.9982894920869114; 7.767878992768955e-5 0.9999223212100758; 8.459262944143889e-5 0.9999154073705655; 7.567350976110723e-6 0.9999924326490278; 0.03333825094604854 0.9666617490539613; 0.000663362742668214 0.9993366372573439; 2.156734547700074e-5 0.9999784326545403; 0.0010743460569906768 0.9989256539430263; 6.710801221058402e-5 0.9999328919878094; 1.811328921830911e-5 0.9999818867108036; 0.007851874841121681 0.9921481251588985; 0.0004376214785625637 0.9995623785214552; 0.0009528224744978781 0.9990471775255114; 0.00022766871588341187 0.9997723312841268; 9.105690193681896e-5 0.9999089430980772; 0.010073376819529271 0.9899266231804815; 0.028409337599292723 0.9715906624007193; 0.024585691499900753 0.9754143085001014; 0.44207550947225704 0.5579244905277488; 0.9980015851234422 0.0019984148765647674; 0.999955735931146 4.426406886305346e-5; 0.9999691863035335 3.081369647070823e-5; 0.9753668933444372 0.024633106655565416; 0.7895840929167782 0.21041590708322433], most_probable = [2, 2, 2, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 1, 1, 1, 1, 1])
These are conditional state probabilities given the complete observation sequence and the supplied parameter values. They are not probabilities averaged over a posterior distribution of transition matrices or emission means. An application with parameter draws can evaluate the same prepared query at those draws and combine the results using the averaging appropriate to its inference task.
The figure follows the probability of the second state across the sequence. Values between the extremes expose remaining state uncertainty. Abrupt changes can correspond to evidence for a transition, while observations near the overlap of the emission distributions can leave a less certain assignment. The figure is generated from the returned probability matrix.
plot = data((; step=collect(eachindex(y)), probability=probabilities[:, 2])) *
mapping(:step => "Sequence step (index)",
:probability => "Conditional probability of state 2") *
visual(Lines; color="#2a78d6")
Tutorials.figure(plot, "conditional-states",
"Conditional probability of state 2 given the complete observation sequence and the supplied transition and emission parameters.")Diagnostics
Each row must be a probability distribution. Check normalization, finiteness and nonnegativity before interpreting its largest entry. The displayed row-sum error quantifies the normalization check; the assertions make the build fail if the returned object violates the probability contract.
row_sum_error = maximum(abs, vec(sum(probabilities; dims=2)) .- 1)
minimum_probability = minimum(probabilities)
@assert all(isfinite, probabilities)
@assert minimum_probability >= 0
@assert row_sum_error < 1e-12
(; row_sum_error, minimum_probability)(row_sum_error = 2.19824158875781e-14, minimum_probability = 7.567350976110723e-6)
A conditional draw samples an entire path, preserving dependencies between steps. Drawing each state's marginal independently would generally produce a different distribution over paths. The API therefore exposes a path-draw operation alongside the probability query.
path = discrete_latent_draws(latents, u, Xoshiro(1)).y
@assert length(path) == length(y)
@assert all(s -> 1 <= s <= K, path)
(; path, valid_states=all(s -> 1 <= s <= K, path))(path = [2, 2, 2, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 1, 2, 2, 2, 2, 2, 2, 2, 1, 1, 1, 1, 1, 1], valid_states = true)
A modal state at each step is a collection of marginal decisions. It need not be the most probable complete path, and it need not equal a sampled path. The two outputs answer different questions. Likewise, matching the generating states in this simulated dataset would not establish calibration across datasets; that would require a separate simulation study with an explicit design.
Query lifetime
The prepared query is reusable for parameter vectors with the same layout. A changed observation sequence requires a compatible new binding and query preparation. Keep the layout attached to the built model: constructing a vector from an assumed parameter order risks evaluating a valid numerical vector with the wrong interpretation.
The probabilistic-graph guide explains this binding and coordinate boundary. The scan guide introduces sequential recurrences at the core graph level, while the PPL reference documents the conditional-latent result and path-draw interfaces. Distribution-specific latent queries may return different structures; use the contract of the selected observation distribution.
Tutorials.receipt("discrete-latents"; checks=(
row_sum_error, minimum_probability,
valid_states=all(s -> 1 <= s <= K, path),
))State labels
State labels identify rows and columns of the transition matrix and entries of the emission-mean vector. The probability column selected for the figure uses that same ordering. Relabeling states consistently leaves the observation model unchanged but changes which label appears on the plotted column. Keep this correspondence when combining results across parameter draws; an inconsistent permutation would average probabilities for different states.
This example avoids that ambiguity by evaluating a single supplied parameter point with named generating values. The retained simulated path helps explain the data construction, but the normalization and path-validity diagnostics do not depend on recovering that particular random path. They check the conditional-query contract on its own terms.
Reproduce
The seed and supplied parameters appear above. Run these shell commands from the repository root.
julia --project=docs docs/instantiate.jl
julia --project=docs docs/make.jlDownload the <a href="./receipts/discrete-latents.toml" download>execution receipt</a>. The research README describes the location of historical experiments.