Particle Filter Resizing

pf_resize!(state::ParticleFilterState, n_particles::Int,
           method=:multinomial; kwargs...)

Resizes a particle filter by resampling existing particles until a total of n_particles have been sampled. The resampling method can optionally be specified: :multinomial (default), :residual or :optimal.

pf_multinomial_resize!(state::ParticleFilterState, n_particles::Int;
                       kwargs...)

Resizes a particle filter through multinomial resampling (i.e. simple random resampling) of existing particles until n_particles are sampled. Each trace (i.e. particle) is resampled with probability proportional to its weight.

Keyword Arguments

• priority_fn = nothing: An optional function that maps particle weights to custom log priority scores (e.g. w -> w/2 for less aggressive pruning).
• check = :warn: Set to true to throw an error for invalid normalized weights (all NaNs or zeros), :warn to issue warnings, or false to suppress checks. In the latter two cases, zero weights will be renormalized to uniform weights for resampling.

pf_residual_resize!(state::ParticleFilterState, n_particles::Int;
                    kwargs...)

Resizes a particle filter through residual resampling of existing particles. For each particle with normalized weight $w_i$, $⌊n w_i⌋$ copies are resampled, where $n$ is n_particles. The remainder are sampled with probability proportional to $n w_i - ⌊n w_i⌋$ for each particle $i$.

Keyword Arguments

• priority_fn = nothing: An optional function that maps particle weights to custom log priority scores (e.g. w -> w/2 for less aggressive pruning).
• check = :warn: Set to true to throw an error for invalid normalized weights (all NaNs or zeros), :warn to issue warnings, or false to suppress checks. In the latter two cases, zero weights will be renormalized to uniform weights for resampling.

pf_optimal_resize!(state::ParticleFilterState, n_particles::Int;
                   kwargs...)

Resizes a particle filter through the optimal resampling algorithm for Fearnhead and Clifford [1]. This guarantees that each resampled particle is unique as long as all of the original particles are unique, while minimizing the variance of the resulting weight distribution with respect to the original weight distribution. Note that n_particles should not be greater than the current number of particles.

Keyword Arguments

• check = :warn: Set to true to throw an error for invalid normalized weights (all NaNs or zeros), :warn to issue warnings, or false to suppress checks. In the latter two cases, zero weights will be renormalized to uniform weights for resampling.

[1] Paul Fearnhead , Peter Clifford, On-Line Inference for Hidden Markov Models via Particle Filters, Journal of the Royal Statistical Society Series B: Statistical Methodology, Volume 65, Issue 4, November 2003, Pages 887–899, https://doi.org/10.1111/1467-9868.00421

pf_replicate!(state::ParticleFilterState, n_replicates::Int;
              layout=:contiguous)

Expands a particle filter by replicating each particle n_replicates times.

If layout is :contiguous, each particle's replicates will be arranged in a continguous block (e.g., replicates of the first particle will have indices 1:n_replicates).

Otherwise, if layout is :interleaved, each particle's replicates will be interleaved with the replicates of the other particles (e.g., replicates of the first particle will have indices 1:n_replicates:N*n_replicates, where N is the original number of particles).

pf_dereplicate!(state::ParticleFilterState, n_replicates::Int;
                layout=:contiguous, method=:keepfirst)

Shrinks a particle filter by retaining one out of every n_replicates particles. The total number of particles must be a multiple of n_replicates.

If layout is :contiguous, each set of replicates is assumed to be arranged in a contiguous block (e.g., the first particle will be selected out of the indices 1:n_replicates).

Otherwise, if layout is :interleaved, each set of replicates is assumed to be interleaved with others (e.g., the first particle will be selected out of the indices 1:n_replicates:N, where N is the total number of particles).

Retained particles can be selected by different methods. If method is :keepfirst, only the first particle of each set of replicates is retained, exactly reversing the effect of pf_replicate!. If method is :sample, the retained particle is sampled according to its normalized weight among the replicates.

pf_coalesce!(state::ParticleFilterState; by=get_choices)

Coalesces traces that are equivalent according to by (defaulting to get_choices). Each set of equivalent traces is replaced by a single trace with weight equal to the sum of the original weights, multiplied by the ratio of the number of coalesced traces to the number of original traces.

To ensure that coalesced traces are identical, set by to identity.

pf_introduce!(state::ParticleFilterState,
              [model::GenerativeFunction, model_args::Tuple,]
              observations::ChoiceMap, n_particles::Int)

pf_introduce!(state::ParticleFilterState,
              [model::GenerativeFunction, model_args::Tuple,]
              observations::ChoiceMap, proposal::GenerativeFunction,
              proposal_args::Tuple, n_particles::Int)

Introduce n_particles new traces into a particle filter, constrained to the provided observations. If model and model_args are omitted, then this function will use the same model and arguments as the first trace in the particle filter. A custom proposal can be used to propose choices.