added docs to to_sampleable + removed the unnecessary macro exports

that we no longer need

Author: torfjelde

docs/src/api.md

@@ -14,18 +14,22 @@ These statements are rewritten by `@model` as calls of [internal functions](@ref
 @model
 ```
 
-One can nest models and call another model inside the model function with [`@submodel`](@ref) and [`@returned_quantities(model)`](@ref).
+One can nest models and call another model inside the model function with `left ~ to_sampleable(model)`.
+
+```@docs
+to_sampleable
+```
+
+In the past, one would instead embed sub-models using [`@submodel`](@ref), which has been deprecated since the introduction of [`to_sampleable(model)`](@ref)
 
 ```@docs
 @submodel
-@returned_quantities(model)
 ```
 
 In the context of nesting models, it's also useful to prefix the variables in sub-models to avoid variable names clashing:
 
 ```@docs
-@prefix
-DynamicPPL.prefix
+prefix
 ```
 
 ### Type
@@ -126,11 +130,10 @@ It is possible to manually increase (or decrease) the accumulated log density fr
 @addlogprob!
 ```
 
-Return values of the model function for a collection of samples can be obtained with [`@returned_quantities`](@ref).
+Return values of the model function for a collection of samples can be obtained with [`returned_quantities`](@ref).
 
 ```@docs
-@returned_quantities(model, input)
-DynamicPPL.returned_quantities
+returned_quantities
 ```
 
 For a chain of samples, one can compute the pointwise log-likelihoods of each observed random variable with [`pointwise_loglikelihoods`](@ref). Similarly, the log-densities of the priors using

src/DynamicPPL.jl

@@ -121,11 +121,11 @@ export AbstractVarInfo,
     decondition,
     fix,
     unfix,
+    prefix,
+    returned_quantities,
     # Convenience macros
     @addlogprob!,
     @submodel,
-    @returned_quantities,
-    @prefix,
     value_iterator_from_chain,
     check_model,
     check_model_and_trace,

src/compiler.jl

@@ -4,7 +4,148 @@ struct SampleableModelWrapper{M}
     model::M
 end
 
-to_sampleable(model::DynamicPPL.Model) = SampleableModelWrapper(model)
+"""
+    to_sampleable(model::Model)
+
+Return a wrapper around `model` which indicates that this model can only be sampled from.
+
+This is mainly meant to be used on the right-hand side of a `~` operator to indicate that
+the model can be sampled from but not necessarily evaluated for its log density.
+
+!!! warning
+    Note that other operations that one typically associate with expressions of the form `left ~ right`
+    such as [`condition`](@ref) or [`fix`](@ref), will also not work with `to_sampleable`.
+
+!!! warning
+    It's generally recommended to use [`prefix(::Model, input)`](@ref) when working with submodels
+    to ensure that the variables in `model` are unique and do not clash with other variables in the
+    parent model or in other submodels.
+
+# Examples
+
+## Simple example
+```jldoctest submodel-to-sampleable; setup=:(using Distributions)
+julia> @model function demo1(x)
+           x ~ Normal()
+           return 1 + abs(x)
+       end;
+
+julia> @model function demo2(x, y)
+            a ~ to_sampleable(demo1(x))
+            return y ~ Uniform(0, a)
+       end;
+```
+
+When we sample from the model `demo2(missing, 0.4)` random variable `x` will be sampled:
+```jldoctest submodel-to-sampleable
+julia> vi = VarInfo(demo2(missing, 0.4));
+
+julia> @varname(x) in keys(vi)
+true
+```
+
+Variable `a` is not tracked since it can be computed from the random variable `x` that was
+tracked when running `demo1`:
+```jldoctest submodel-to-sampleable
+julia> @varname(a) in keys(vi)
+false
+```
+
+We can check that the log joint probability of the model accumulated in `vi` is correct:
+
+```jldoctest submodel-to-sampleable
+julia> x = vi[@varname(x)];
+
+julia> getlogp(vi) ≈ logpdf(Normal(), x) + logpdf(Uniform(0, 1 + abs(x)), 0.4)
+true
+```
+
+## With prefixing
+```jldoctest submodel-to-sampleable-prefix; setup=:(using Distributions)
+julia> @model function demo1(x)
+           x ~ Normal()
+           return 1 + abs(x)
+       end;
+
+julia> @model function demo2(x, y, z)
+            a ~ to_sampleable(prefix(demo1(x), :sub1))
+            b ~ to_sampleable(prefix(demo1(y), :sub2))
+            return z ~ Uniform(-a, b)
+       end;
+```
+
+When we sample from the model `demo2(missing, missing, 0.4)` random variables `sub1.x` and
+`sub2.x` will be sampled:
+```jldoctest submodel-to-sampleable-prefix
+julia> vi = VarInfo(demo2(missing, missing, 0.4));
+
+julia> @varname(var"sub1.x") in keys(vi)
+true
+
+julia> @varname(var"sub2.x") in keys(vi)
+true
+```
+
+Variables `a` and `b` are not tracked since they can be computed from the random variables `sub1.x` and
+`sub2.x` that were tracked when running `demo1`:
+```jldoctest submodel-to-sampleable-prefix
+julia> @varname(a) in keys(vi)
+false
+
+julia> @varname(b) in keys(vi)
+false
+```
+
+We can check that the log joint probability of the model accumulated in `vi` is correct:
+
+```jldoctest submodel-to-sampleable-prefix
+julia> sub1_x = vi[@varname(var"sub1.x")];
+
+julia> sub2_x = vi[@varname(var"sub2.x")];
+
+julia> logprior = logpdf(Normal(), sub1_x) + logpdf(Normal(), sub2_x);
+
+julia> loglikelihood = logpdf(Uniform(-1 - abs(sub1_x), 1 + abs(sub2_x)), 0.4);
+
+julia> getlogp(vi) ≈ logprior + loglikelihood
+true
+```
+
+## Different ways of setting the prefix
+```jldoctest submodel-to-sampleable-prefix-alts; setup=:(using DynamicPPL, Distributions)
+julia> @model inner() = x ~ Normal()
+inner (generic function with 2 methods)
+
+julia> # When `prefix` is unspecified, no prefix is used.
+       @model submodel_noprefix() = a ~ to_sampleable(inner())
+submodel_noprefix (generic function with 2 methods)
+
+julia> @varname(x) in keys(VarInfo(submodel_noprefix()))
+true
+
+julia> # Using a static string.
+       @model submodel_prefix_string() = a ~ to_sampleable(prefix(inner(), "my prefix"))
+submodel_prefix_string (generic function with 2 methods)
+
+julia> @varname(var"my prefix.x") in keys(VarInfo(submodel_prefix_string()))
+true
+
+julia> # Using string interpolation.
+       @model submodel_prefix_interpolation() = a = to_sampleable(prefix(inner(), "\$(nameof(inner()))"))
+submodel_prefix_interpolation (generic function with 2 methods)
+
+julia> @varname(var"inner.x") in keys(VarInfo(submodel_prefix_interpolation()))
+true
+
+julia> # Or using some arbitrary expression.
+       @model submodel_prefix_expr() = a ~ to_sampleable(prefix(inner(), 1 + 2))
+submodel_prefix_expr (generic function with 2 methods)
+
+julia> @varname(var"3.x") in keys(VarInfo(submodel_prefix_expr()))
+true
+```
+"""
+to_sampleable(model::Model) = SampleableModelWrapper(model)
 
 """
     need_concretize(expr)

src/contexts.jl

@@ -322,32 +322,6 @@ function prefix(model::Model, ::Val{x}) where {x}
     return contextualize(model, PrefixContext{Symbol(x)}(model.context))
 end
 
-"""
-    @prefix(model, prefix_expr)
-
-Return `model` but with all random variables prefixed by `prefix_expr`.
-
-The result of `prefix_expr` must will be converted to a `Symbol` and used as the prefix.
-
-!!! note
-    This is effectively just a convenience macro for the method [`DynamicPPL.prefix(::Model, x)`](@ref),
-    which automatically converts the result of `prefix_expr` into a `Val` to avoid runtime overheads
-    for static prefixes. For more control over the prefixing, use the method directly.
-
-# Examples
-
-```jldoctest
-julia> @model demo() = x ~ Dirac(1)
-demo (generic function with 2 methods)
-
-julia> rand(@prefix(demo(), :my_prefix))
-(var"my_prefix.x" = 1,)
-```
-"""
-macro prefix(model, prefix_expr)
-    return :($prefix($(esc(model)), $Val{$Symbol($(esc(prefix_expr)))}()))
-end
-
 struct ConditionContext{Values,Ctx<:AbstractContext} <: AbstractContext
     values::Values
     context::Ctx

src/model.jl

@@ -1250,15 +1250,3 @@ end
 function returned_quantities(model::Model, values, keys)
     return returned_quantities(model, NamedTuple{keys}(values))
 end
-
-"""
-    @returned_quantities(model, input)
-
-Execute `model` and extract the return-values of `model` for `input`.
-
-!!! note
-    This macro is in fact a simple wrapper around the method [`DynamicPPL.returned_quantities`](@ref).
-"""
-macro returned_quantities(model_expr, input_expr)
-    return :($returned_quantities($(esc(model_expr)), $(esc(input_expr))))
-end