Skip to content

Latest commit

 

History

History
330 lines (237 loc) · 6.53 KB

api.md

File metadata and controls

330 lines (237 loc) · 6.53 KB
Raw

API

Part of the API of DynamicPPL is defined in the more lightweight interface package AbstractPPL.jl and reexported here.

Model

Macros

A core component of DynamicPPL is the @model macro. It can be used to define probabilistic models in an intuitive way by specifying random variables and their distributions with ~ statements. These statements are rewritten by @model as calls of [internal functions](@ref model_internal) for sampling the variables and computing their log densities.

@model

One can nest models and call another model inside the model function with @submodel.

@submodel

Type

A Model can be created by calling the model function, as defined by @model.

Model

Models are callable structs.

Model()

Basic properties of a model can be accessed with getargnames, getmissings, and nameof.

nameof(::Model)
getargnames
getmissings

Evaluation

With rand one can draw samples from the prior distribution of a Model.

rand

One can also evaluate the log prior, log likelihood, and log joint probability.

logprior
loglikelihood
logjoint

LogDensityProblems.jl interface

The LogDensityProblems.jl interface is also supported by simply wrapping a Model in a DynamicPPL.LogDensityFunction:

DynamicPPL.LogDensityFunction

Condition and decondition

A Model can be conditioned on a set of observations with AbstractPPL.condition or its alias |.

|(::Model, ::Any)
condition
DynamicPPL.conditioned

Similarly, one can specify with AbstractPPL.decondition that certain, or all, random variables are not observed.

decondition

Utilities

It is possible to manually increase (or decrease) the accumulated log density from within a model function.

@addlogprob!

Return values of the model function for a collection of samples can be obtained with generated_quantities.

generated_quantities

For a chain of samples, one can compute the pointwise log-likelihoods of each observed random variable with pointwise_loglikelihoods.

pointwise_loglikelihoods

Sometimes it can be useful to extract the priors of a model. This is the possible using extract_priors.

extract_priors

NamedDist

Testing Utilities

DynamicPPL provides several demo models and helpers for testing samplers in the DynamicPPL.TestUtils submodule.

DynamicPPL.TestUtils.test_sampler
DynamicPPL.TestUtils.test_sampler_on_demo_models
DynamicPPL.TestUtils.test_sampler_continuous
DynamicPPL.TestUtils.marginal_mean_of_samples

DynamicPPL.TestUtils.DEMO_MODELS

For every demo model, one can define the true log prior, log likelihood, and log joint probabilities.

DynamicPPL.TestUtils.logprior_true
DynamicPPL.TestUtils.loglikelihood_true
DynamicPPL.TestUtils.logjoint_true

And in the case where the model includes constrained variables, it can also be useful to define

DynamicPPL.TestUtils.logprior_true_with_logabsdet_jacobian
DynamicPPL.TestUtils.logjoint_true_with_logabsdet_jacobian

Finally, the following methods can also be of use:

DynamicPPL.TestUtils.varnames
DynamicPPL.TestUtils.posterior_mean
DynamicPPL.TestUtils.setup_varinfos
DynamicPPL.TestUtils.update_values!!
DynamicPPL.TestUtils.test_values

Advanced

Variable names

Names and possibly nested indices of variables are described with AbstractPPL.VarName. They can be defined with AbstractPPL.@varname. Please see the documentation of AbstractPPL.jl for further information.

Data Structures of Variables

DynamicPPL provides different data structures for samples from the model and their log density. All of them are subtypes of AbstractVarInfo.

AbstractVarInfo

Common API

Accumulation of log-probabilities

getlogp
setlogp!!
acclogp!!
resetlogp!!

Variables and their realizations

keys
getindex
DynamicPPL.getindex_raw
push!!
empty!!
isempty

values_as

Transformations

DynamicPPL.AbstractTransformation
DynamicPPL.NoTransformation
DynamicPPL.DynamicTransformation
DynamicPPL.StaticTransformation

DynamicPPL.istrans
DynamicPPL.settrans!!
DynamicPPL.transformation
DynamicPPL.link!!
DynamicPPL.invlink!!
DynamicPPL.default_transformation
DynamicPPL.maybe_invlink_before_eval!!
DynamicPPL.reconstruct

Utils

DynamicPPL.unflatten
DynamicPPL.tonamedtuple

SimpleVarInfo

SimpleVarInfo

VarInfo

Another data structure is VarInfo.

VarInfo
TypedVarInfo

One main characteristic of VarInfo is that samples are stored in a linearized form.

link!
invlink!

set_flag!
unset_flag!
is_flagged

For Gibbs sampling the following functions were added.

setgid!
updategid!

The following functions were used for sequential Monte Carlo methods.

get_num_produce
set_num_produce!
increment_num_produce!
reset_num_produce!
setorder!
set_retained_vns_del_by_spl!

Base.empty!

Evaluation Contexts

Internally, both sampling and evaluation of log densities are performed with AbstractPPL.evaluate!!.

AbstractPPL.evaluate!!

The behaviour of a model execution can be changed with evaluation contexts that are passed as additional argument to the model function. Contexts are subtypes of AbstractPPL.AbstractContext.

SamplingContext
DefaultContext
LikelihoodContext
PriorContext
MiniBatchContext
PrefixContext

Samplers

In DynamicPPL two samplers are defined that are used to initialize unobserved random variables: SampleFromPrior which samples from the prior distribution, and SampleFromUniform which samples from a uniform distribution.

SampleFromPrior
SampleFromUniform

Additionally, a generic sampler for inference is implemented.

Sampler

The default implementation of Sampler uses the following unexported functions.

DynamicPPL.initialstep
DynamicPPL.loadstate
DynamicPPL.initialsampler

[Model-Internal Functions](@id model_internal)

tilde_assume
dot_tilde_assume

tilde_observe
dot_tilde_observe