diff --git a/docs/make.jl b/docs/make.jl index 66cc690f0..c69b72fb8 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -9,16 +9,20 @@ using DynamicPPL: AbstractPPL # consistent with that. using Distributions using DocumenterMermaid +# load MCMCChains package extension to make `predict` available +using MCMCChains # Doctest setup -DocMeta.setdocmeta!(DynamicPPL, :DocTestSetup, :(using DynamicPPL); recursive=true) +DocMeta.setdocmeta!( + DynamicPPL, :DocTestSetup, :(using DynamicPPL, MCMCChains); recursive=true +) makedocs(; sitename="DynamicPPL", # The API index.html page is fairly large, and violates the default HTML page size # threshold of 200KiB, so we double that. format=Documenter.HTML(; size_threshold=2^10 * 400), - modules=[DynamicPPL], + modules=[DynamicPPL, Base.get_extension(DynamicPPL, :DynamicPPLMCMCChainsExt)], pages=[ "Home" => "index.md", "API" => "api.md", "Internals" => ["internals/varinfo.md"] ], diff --git a/docs/src/api.md b/docs/src/api.md index 35baa558c..9c8249c97 100644 --- a/docs/src/api.md +++ b/docs/src/api.md @@ -104,6 +104,32 @@ Similarly, we can [`unfix`](@ref) variables, i.e. return them to their original unfix ``` +## Predicting + +DynamicPPL provides functionality for generating samples from the posterior predictive distribution through the `predict` function. This allows you to use posterior parameter samples to generate predictions for unobserved data points. + +The `predict` function has two main methods: + + 1. For `AbstractVector{<:AbstractVarInfo}` - useful when you have a collection of `VarInfo` objects representing posterior samples. + 2. For `MCMCChains.Chains` (only available when `MCMCChains.jl` is loaded) - useful when you have posterior samples in the form of an `MCMCChains.Chains` object. + +```@docs +predict +``` + +### Basic Usage + +The typical workflow for posterior prediction involves: + + 1. Fitting a model to observed data to obtain posterior samples + 2. Creating a new model instance with some variables marked as missing (unobserved) + 3. Using `predict` to generate samples for these missing variables based on the posterior parameter samples + +When using `predict` with `MCMCChains.Chains`, you can control which variables are included in the output with the `include_all` parameter: + + - `include_all=false` (default): Include only newly predicted variables + - `include_all=true`: Include both parameters from the original chain and predicted variables + ## Models within models One can include models and call another model inside the model function with `left ~ to_submodel(model)`. diff --git a/src/DynamicPPL.jl b/src/DynamicPPL.jl index ed0803b25..50fe0edc7 100644 --- a/src/DynamicPPL.jl +++ b/src/DynamicPPL.jl @@ -115,6 +115,7 @@ export AbstractVarInfo, decondition, fix, unfix, + predict, prefix, returned, to_submodel,