Data Structures and Utilities

The state of a particle filter is represented by a ParticleFilterState, which stores a set of traces (representing particles) and their associated (unnormalized) weights:

Gen.ParticleFilterState — Type

ParticleFilterState

A data structure that represents the current state of a particle filter.

source

The following functions can be used to access the traces and weights:

Gen.get_traces — Function

traces = get_traces(state::ParticleFilterState)

Return the vector of traces in the current state, one for each particle.

Gen.get_log_weights — Function

log_weights = get_log_weights(state::ParticleFilterState)

Return the vector of log weights for the current state, one for each particle.

The weights are not normalized, and are in log-space.

GenParticleFilters.get_log_norm_weights — Function

get_log_norm_weights(state::ParticleFilterState)

Return the vector of normalized log weights for the current state, one for each particle.

source

GenParticleFilters.get_norm_weights — Function

get_norm_weights(state::ParticleFilterState)

Return the vector of normalized weights for the current state, one for each particle.

source

Users can also sample traces from the particle filter, with probability proportional to their weights:

Gen.sample_unweighted_traces — Function

traces::Vector = sample_unweighted_traces(state::ParticleFilterState, num_samples::Int)

Sample a vector of num_samples traces from the weighted collection of traces in the given particle filter state.

To enable parallelism and block-wise operations, users can index into a ParticleFilterState to obtain a ParticleFilterSubState:

GenParticleFilters.ParticleFilterSubState — Type

ParticleFilterSubState

A data structure that represents a view into a subset of traces in a particle filter. If state is a ParticleFilterState, then state[idxs] or view(state, idxs) can be used to construct a ParticleFilterSubState which only contains the traces at the specified idxs.

source

Aside from resizing, all particle filtering operations that can be applied to a ParticleFilterState can also be applied to a ParticleFilterSubState.

Diagnostics

Several functions are provided to compute particle filter diagnostics.

Gen.effective_sample_size — Function

effective_sample_size(state::ParticleFilterState)

Computes the effective sample size of the particles in the filter.

source

GenParticleFilters.get_ess — Function

get_ess(state::ParticleFilterState)

Alias for effective_sample_size. Computes the effective sample size.

source

Gen.log_ml_estimate — Function

estimate = log_ml_estimate(state::ParticleFilterState)

Return the particle filter's current estimate of the log marginal likelihood.

GenParticleFilters.get_lml_est — Function

get_lml_est(state::ParticleFilterState)

Alias for log_ml_estimate. Returns the particle filter's current estimate of the log marginal likelihood.

source

Statistics

The following methods for computing summary statistics are also provided.

Statistics.mean — Method

mean(state::ParticleFilterState[, addr])

Returns the weighted empirical mean for a particular trace address addr. If addr is not provided, returns the empirical mean of the return value associated with each trace in the particle filter.

source

Statistics.mean — Method

mean(f::Function, state::ParticleFilterState[, addrs...])

Returns the weighted empirical mean of a function f applied to the values at one or more trace addresses addrs, where f takes in a number of arguments equal to the number of addresses.

If no addresses are provided, f is applied to the return value of each trace.

source

Statistics.var — Method

var(state::ParticleFilterState[, addr])

Returns the empirical variance for a particular trace address addr. If addr is not provided, returns the empirical variance of the return value associated with each trace in the particle filter.

source

Statistics.var — Method

var(f::Function, state::ParticleFilterState[, addrs...])

Returns the empirical variance of a function f applied to the values at one or more trace addresses addrs, where f takes in a number of arguments equal to the number of addresses.

If no addresses are provided, f is applied to the return value of each trace.

source

StatsBase.proportionmap — Method

proportionmap(state::ParticleFilterState[, addr])

Returns a dictionary mapping each unique value at a trace address addr to its proportion (i.e. sum of normalized weights) in the particle filter. If addr is not provided, returns the proportions of each possible return value.

source

StatsBase.proportionmap — Method

proportionmap(f::Function, state::ParticleFilterState[, addrs...])

Applies f to the values at one or more trace addresses addrs, then returns a dictionary mapping each unique value to its proportion (i.e. sum of normalized weights) in the particle filter.

If no addresses are provided, f is applied to the return value of each trace.

source

Stratification

To support the use of stratified sampling, the choiceproduct method can be used to conveniently generate a list of choicemap strata:

GenParticleFilters.choiceproduct — Function

choiceproduct((addr, vals))
choiceproduct((addr, vals), choices::Tuple...)
choiceproduct(choices::Dict)

Returns an iterator over ChoiceMaps given a tuple or sequence of tuples of the form (addr, vals), where addr specifies a choice address, and vals specifies a list of values for that address.

If multiple tuples are provided, the iterator will be a Cartesian product over the (addr, vals) pairs, where each resulting ChoiceMap contains all specified addresses. Instead of specifying multiple tuples, a dictionary mapping addresses to values can also be provided.

Examples

This function can be used to conveniently generate ChoiceMaps for stratified sampling. For example, we can use choiceproduct instead of manually constructing a list of strata:

# Manual construction
strata = [choicemap((:a,  1), (:b,  3)), choicemap((:a,  2), (:b,  3))]
# Using choiceproduct
strata = choiceproduct((:a, [1, 2]), (:b, [3]))

source