Skip to content

Commit 5989b33

Browse files
yebaiclaudesunxd3
authored
Add documentation on partial specification of a multivariate variable (#2239) (#1434)
Fixes the documentation *and* the behaviour side of [TuringLang/Turing.jl#2239](TuringLang/Turing.jl#2239). A variable drawn from a multivariate distribution in a single tilde-statement (e.g. `x ~ MvNormal(...)`, `filldist`) is a **single** random variable, not a collection of i.i.d. components. Supplying only *part* of such a variable — via `predict` with a chain from a differently sized model, or `fix`/`condition` on a subset of indices — should produce an informative error. --- **Update: (sunxd3)** scoped down to documentation only, per the discussion below — the tilde-site guard, version bump, and error tests are reverted; the docstring notes on whole-variable semantics for `predict` and `fix` remain. The behaviour-side check for `predict` will follow in a separate PR via `InitFromParams`; condition/fix enforcement (if worth doing) will get its own design issue. --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Co-authored-by: Xianda Sun <sunxdt@gmail.com>
1 parent d7e84ce commit 5989b33

2 files changed

Lines changed: 24 additions & 3 deletions

File tree

ext/DynamicPPLMCMCChainsExt.jl

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -273,6 +273,16 @@ If `include_all` is `false`, the returned `Chains` will contain only those varia
273273
the samples in `chain`. This is useful when you want to sample only new variables from the posterior
274274
predictive distribution.
275275
276+
!!! warning "Variables are treated as they occur in the model"
277+
A variable drawn from a multivariate distribution in a single tilde-statement
278+
(e.g. `x ~ MvNormal(...)` or `x ~ filldist(Normal(), n)`) is a *single* random
279+
variable, not a collection of i.i.d. components. `predict` cannot fix a subset of
280+
such a variable's components while resampling the rest; if `chain` supplies only
281+
some components, the whole variable is silently resampled from the prior — the
282+
predictions will look plausible but ignore what the chain says about that variable.
283+
To treat components individually, declare them in a loop, e.g.
284+
`for i in eachindex(x); x[i] ~ Normal(); end`.
285+
276286
# Examples
277287
```jldoctest
278288
using AbstractMCMC, Distributions, DynamicPPL, Random

src/model.jl

Lines changed: 14 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -246,9 +246,11 @@ part of the variable should not be conditioned on.
246246
247247
However, note that in this case each element of the multivariate random variable must be on
248248
its own tilde-statement. In other words, if we write `m ~ MvNormal(...)`, then we cannot
249-
condition on only `m[1]`. (In principle, for some distributions this can be possible,
250-
specifically when the distribution can be factorised into independent components, like an
251-
MvNormal with a diagonal covariance matrix. However, this is not currently implemented.)
249+
condition on only `m[1]`. Attempting to do so may abort model evaluation with an unrelated
250+
`DimensionMismatch`, or the conditioning may be silently ignored, with `m` sampled afresh.
251+
(In principle, for some distributions this can be possible, specifically when the
252+
distribution can be factorised into independent components, like an MvNormal with a
253+
diagonal covariance matrix. However, this is not currently implemented.)
252254
253255
```jldoctest condition
254256
julia> @model function demo_mv(::Type{TV}=Float64) where {TV}
@@ -522,6 +524,15 @@ Return a `Model` which now treats the variables in `values` as fixed.
522524
523525
See also: [`unfix`](@ref), [`fixed`](@ref)
524526
527+
!!! warning "Fixing applies to whole variables"
528+
Variables are treated as they occur in the model. A variable drawn from a multivariate
529+
distribution in a single tilde-statement (e.g. `x ~ MvNormal(...)`) is a *single* random
530+
variable, so a subset of its components cannot be fixed independently; only fixing the
531+
variable in its entirety is supported. Attempting to fix a subset may silently collapse
532+
the variable to just the supplied components, or leave it entirely unfixed and sampled
533+
from the prior. Declare components in a loop (`x[i] ~ ...`) if you need to fix them
534+
individually.
535+
525536
# Examples
526537
## Simple univariate model
527538
```jldoctest fix

0 commit comments

Comments
 (0)