# Sequential Monte Carlo¶

## SMCUpdater - SMC-Based Particle Updater¶

### Class Reference¶

class qinfer.smc.SMCUpdater(model, n_particles, prior, resample_a=None, resampler=None, resample_thresh=0.5, debug_resampling=False, track_resampling_divergence=False, zero_weight_policy=u'error', zero_weight_thresh=None, canonicalize=True)[source]

Bases: qinfer.distributions.Distribution

Creates a new Sequential Monte carlo updater, using the algorithm of [GFWC12].

Parameters: model (qinfer.abstract_model.Model) – Model whose parameters are to be inferred. n_particles (int) – The number of particles to be used in the particle approximation. prior (qinfer.distributions.Distribution) – A representation of the prior distribution. resampler (callable) – Specifies the resampling algorithm to be used. See Resampling Algorithms for more details. resample_thresh (float) – Specifies the threshold for $$N_{\text{ess}}$$ to decide when to resample. debug_resampling (bool) – If True, debug information will be generated on resampling performance, and will be written to the standard Python logger. track_resampling_divergence (bool) – If true, then the divergences between the pre- and post-resampling distributions are tracked and recorded in the resampling_divergences attribute. zero_weight_policy (str) – Specifies the action to be taken when the particle weights would all be set to zero by an update. One of ["ignore", "skip", "warn", "error", "reset"]. zero_weight_thresh (float) – Value to be used when testing for the zero-weight condition. canonicalize (bool) – If True, particle locations will be updated to canonical locations as described by the model class after each prior sampling and resampling.
n_particles

Returns the number of particles currently used in the sequential Monte Carlo approximation.

Return type: int
resample_count

Returns the number of times that the updater has resampled the particle approximation.

Return type: int
just_resampled

True if and only if there has been no data added since the last resampling, or if there has not yet been a resampling step.

normalization_record

Returns the normalization record.

Return type: float
log_total_likelihood

Returns the log-likelihood of all the data collected so far.

Equivalent to:

np.sum(np.log(updater.normalization_record))

Return type: float
n_ess

Estimates the effective sample size (ESS) of the current distribution over model parameters.

Return float: The effective sample size, given by $$1/\sum_i w_i^2$$.
data_record

List of outcomes given to update().

resampling_divergences

List of KL divergences between the pre- and post-resampling distributions, if that is being tracked. Otherwise, None.

reset(n_particles=None, only_params=None, reset_weights=True)[source]

Causes all particle locations and weights to be drawn fresh from the initial prior.

Parameters: n_particles (int) – Forces the size of the new particle set. If None, the size of the particle set is not changed. only_params (slice) – Resets only some of the parameters. Cannot be set if n_particles is also given. reset_weights (bool) – Resets the weights as well as the particles.
hypothetical_update(outcomes, expparams, return_likelihood=False, return_normalization=False)[source]

Produces the particle weights for the posterior of a hypothetical experiment.

Parameters: outcomes (int or an ndarray of dtype int.) – Integer index of the outcome of the hypothetical experiment. TODO: Fix this to take an array-like of ints as well. expparams – TODO weights (ndarray, shape (n_outcomes, n_expparams, n_particles)) – Weights assigned to each particle in the posterior distribution $$\Pr(\omega | d)$$.
update(outcome, expparams, check_for_resample=True)[source]

Given an experiment and an outcome of that experiment, updates the posterior distribution to reflect knowledge of that experiment.

After updating, resamples the posterior distribution if necessary.

Parameters: outcome (int) – Label for the outcome that was observed, as defined by the Model instance under study. expparams (ndarray of dtype given by the expparams_dtype property of the underlying model) – Parameters describing the experiment that was performed. check_for_resample (bool) – If True, after performing the update, the effective sample size condition will be checked and a resampling step may be performed.
batch_update(outcomes, expparams, resample_interval=5)[source]

Updates based on a batch of outcomes and experiments, rather than just one.

Parameters: outcomes (numpy.ndarray) – An array of outcomes of the experiments that were performed. expparams (numpy.ndarray) – Either a scalar or record single-index array of experiments that were performed. resample_interval (int) – Controls how often to check whether $$N_{\text{ess}}$$ falls below the resample threshold.
resample()[source]
n_rvs
sample(n=1)[source]
est_mean()[source]

Returns an estimate of the posterior mean model, given by the expectation value over the current SMC approximation of the posterior model distribution.

Return type: numpy.ndarray, shape (n_modelparams,). An array containing the an estimate of the mean model vector.
est_meanfn(fn)[source]

Returns an estimate of the expectation value of a given function $$f$$ of the model parameters, given by a sum over the current SMC approximation of the posterior distribution over models.

Here, $$f$$ is represented by a function fn that is vectorized over particles, such that f(modelparams) has shape (n_particles, k), where n_particles = modelparams.shape[0], and where k is a positive integer.

Parameters: fn (callable) – Function implementing $$f$$ in a vectorized manner. (See above.) numpy.ndarray, shape (k, ). An array containing the an estimate of the mean of $$f$$.
est_covariance_mtx()[source]

Returns an estimate of the covariance of the current posterior model distribution, given by the covariance of the current SMC approximation.

Return type: numpy.ndarray, shape (n_modelparams, n_modelparams). An array containing the estimated covariance matrix.
bayes_risk(expparams)[source]

Calculates the Bayes risk for a hypothetical experiment, assuming the quadratic loss function defined by the current model’s scale matrix (see qinfer.abstract_model.Simulatable.Q).

Parameters: expparams (ndarray of dtype given by the current model’s expparams_dtype property, and of shape (1,)) – The experiment at which to compute the Bayes risk. The Bayes risk for the current posterior distribution of the hypothetical experiment expparams.
expected_information_gain(expparams)[source]

Calculates the expected information gain for a hypothetical experiment.

Parameters: expparams (ndarray of dtype given by the current model’s expparams_dtype property, and of shape (1,)) – The experiment at which to compute expected information gain. The Bayes risk for the current posterior distribution of the hypothetical experiment expparams.
est_entropy()[source]
est_kl_divergence(other, kernel=None, delta=0.01)[source]
est_cluster_moments(cluster_opts=None)[source]
est_cluster_covs(cluster_opts=None)[source]
est_cluster_metric(cluster_opts=None)[source]

Returns an estimate of how much of the variance in the current posterior can be explained by a separation between clusters.

est_credible_region(level=0.95, return_outside=False)[source]

Returns an array containing particles inside a credible region of a given level, such that the described region has probability mass no less than the desired level.

Particles in the returned region are selected by including the highest- weight particles first until the desired credibility level is reached.

Parameters: level (float) – Crediblity level to report. return_outside (bool) – If True, the return value is a tuple of the those particles within the credible region, and the rest of the posterior particle cloud. numpy.ndarray, shape (n_credible, n_modelparams), where n_credible is the number of particles in the credible region An array of particles inside the estimated credible region.
region_est_hull(level=0.95)[source]

Estimates a credible region over models by taking the convex hull of a credible subset of particles.

Parameters: level (float) – The desired crediblity level (see SMCUpdater.est_credible_region()).
region_est_ellipsoid(level=0.95, tol=0.0001)[source]

Estimates a credible region over models by finding the minimum volume enclosing ellipse (MVEE) of a credible subset of particles.

Parameters: level (float) – The desired crediblity level (see SMCUpdater.est_credible_region()). tol (float) – The allowed error tolerance in the MVEE optimization (see mvee()).
risk(x0)[source]
posterior_marginal(idx_param=0, res=100, smoothing=0, range_min=None, range_max=None)[source]

Returns an estimate of the marginal distribution of a given model parameter, based on taking the derivative of the interpolated cdf.

Parameters: idx_param (int) – Index of parameter to be marginalized. res1 (int) – Resolution of of the axis. smoothing (float) – Standard deviation of the Gaussian kernel used to smooth; same units as parameter. range_min (float) – Minimum range of the output axis. range_max (float) – Maximum range of the output axis.
plot_posterior_marginal(idx_param=0, res=100, smoothing=0, range_min=None, range_max=None, label_xaxis=True, other_plot_args={}, true_model=None)[source]

Plots a marginal of the requested parameter.

Parameters: idx_param (int) – Index of parameter to be marginalized. res1 (int) – Resolution of of the axis. smoothing (float) – Standard deviation of the Gaussian kernel used to smooth; same units as parameter. range_min (float) – Minimum range of the output axis. range_max (float) – Maximum range of the output axis. label_xaxis (bool) – Labels the $$x$$-axis with the model parameter name given by this updater’s model. other_plot_args (dict) – Keyword arguments to be passed to matplotlib’s plot function. true_model (np.ndarray) – Plots a given model parameter vector as the “true” model for comparison.
plot_covariance(corr=False, param_slice=None, tick_labels=None, tick_params=None)[source]

Plots the covariance matrix of the posterior as a Hinton diagram.

Note

This function requires that mpltools is installed.

Parameters: corr (bool) – If True, the covariance matrix is first normalized by the outer product of the square root diagonal of the covariance matrix such that the corrleation matrix is plotted instead. param_slice (slice) – Slice of the modelparameters to be plotted. tick_labels (list) – List of tick labels for each component; by default, these are drawn from the model itself.
posterior_mesh(idx_param1=0, idx_param2=1, res1=100, res2=100, smoothing=0.01)[source]

Returns a mesh, useful for plotting, of kernel density estimation of a 2D projection of the current posterior distribution.

Parameters: idx_param1 (int) – Parameter to be treated as $$x$$ when plotting. idx_param2 (int) – Parameter to be treated as $$y$$ when plotting. res1 (int) – Resolution along the $$x$$ direction. res2 (int) – Resolution along the $$y$$ direction. smoothing (float) – Standard deviation of the Gaussian kernel used to smooth the particle approximation to the current posterior.
plot_posterior_contour(idx_param1=0, idx_param2=1, res1=100, res2=100, smoothing=0.01)[source]

Plots a contour of the kernel density estimation of a 2D projection of the current posterior distribution.

Parameters: idx_param1 (int) – Parameter to be treated as $$x$$ when plotting. idx_param2 (int) – Parameter to be treated as $$y$$ when plotting. res1 (int) – Resolution along the $$x$$ direction. res2 (int) – Resolution along the $$y$$ direction. smoothing (float) – Standard deviation of the Gaussian kernel used to smooth the particle approximation to the current posterior.