Add documentation

Author: penelopeysm

docs/Project.toml

@@ -10,6 +10,7 @@ ForwardDiff = "f6369f11-7733-5829-9624-2563aa707210"
 JET = "c3a54625-cd67-489e-a8e7-0a5a0ff4e31b"
 LogDensityProblems = "6fdf6af0-433a-55f7-b3ed-c6c6e0b8df7c"
 MCMCChains = "c7f686f2-ff18-58e9-bc7b-31028e88f75d"
+MarginalLogDensities = "f0c3360a-fb8d-11e9-1194-5521fd7ee392"
 StableRNGs = "860ef19b-820b-49d6-a774-d7a799459cd3"
 
 [compat]

docs/make.jl

@@ -11,6 +11,7 @@ using Distributions
 using DocumenterMermaid
 # load MCMCChains package extension to make `predict` available
 using MCMCChains
+using MarginalLogDensities: MarginalLogDensities
 
 # Doctest setup
 DocMeta.setdocmeta!(

docs/src/api.md

@@ -123,6 +123,15 @@ The `predict` function has two main methods:
 predict
 ```
 
+## Marginalization
+
+DynamicPPL provides the `marginalize` function to marginalize out variables from a model.
+This requires `MarginalLogDensities.jl` to be loaded in your environment.
+
+```@docs
+marginalize
+```
+
 ### Basic Usage
 
 The typical workflow for posterior prediction involves:

ext/DynamicPPLMarginalLogDensitiesExt.jl

@@ -6,6 +6,51 @@ using MarginalLogDensities: MarginalLogDensities
 _to_varname(n::Symbol) = VarName{n}()
 _to_varname(n::VarName) = n
 
+"""
+    marginalize(
+        model::DynamicPPL.Model,
+        varnames::AbstractVector{<:Union{Symbol,<:VarName}},
+        getlogprob=DynamicPPL.getlogjoint,
+        method::MarginalLogDensities.AbstractMarginalizer=MarginalLogDensities.LaplaceApprox();
+        kwargs...,
+    )
+
+Construct a `MarginalLogDensities.MarginalLogDensity` object that represents the marginal
+log-density of the given `model`, after marginalizing out the variables specified in
+`varnames`.
+
+The resulting object can be called with a vector of parameter values to compute the marginal
+log-density.
+
+The `getlogprob` argument can be used to specify which kind of marginal log-density to
+compute. Its default value is `DynamicPPL.getlogjoint` which returns the marginal log-joint
+probability.
+
+By default the marginalization is performed with a Laplace approximation. Please see [the
+MarginalLogDensities.jl package](https://github.com/ElOceanografo/MarginalLogDensities.jl/)
+for other options.
+
+## Example
+
+```jldoctest
+julia> using DynamicPPL, Distributions, MarginalLogDensities
+
+julia> @model function demo()
+           x ~ Normal(1.0)
+           y ~ Normal(2.0)
+       end
+demo (generic function with 2 methods)
+
+julia> marginalized = marginalize(demo(), [:x]);
+
+julia> # The resulting callable computes the marginal log-density of `y`.
+       marginalized([1.0])
+-1.4189385332046727
+
+julia> logpdf(Normal(2.0), 1.0)
+-1.4189385332046727
+```
+"""
 function DynamicPPL.marginalize(
     model::DynamicPPL.Model,
     varnames::AbstractVector{<:Union{Symbol,<:VarName}},