arviz_stats.bfmi

Contents

arviz_stats.bfmi#

arviz_stats.bfmi(data, sample_dims=None, group='sample_stats', var_names='energy', filter_vars=None, coords=None, **kwargs)[source]#

Calculate the estimated Bayesian fraction of missing information (BFMI).

BFMI quantifies how well momentum resampling matches the marginal energy distribution as explained in [1]. As a rule of thumb, BFMI values smaller than 0.3 are indicative of poor sampling.

See the EABM chapter on MCMC diagnostic of gradient-based algorithms for more details.

Parameters:
dataarray_like, xarray.DataArray, xarray.Dataset, xarray.DataTree, DataArrayGroupBy, DatasetGroupBy, or idata-like

Input data. It will have different pre-processing applied to it depending on its type:

  • array-like: call array layer within arviz-stats.

  • xarray object: apply dimension aware function to all relevant subsets

  • others: passed to arviz_base.convert_to_dataset

sample_dimsiterable of hashable, optional

Dimensions to be considered sample dimensions and are to be reduced. Default rcParams["data.sample_dims"].

grouphashable, default “sample_stats”

Group on which to compute the BFMI.

var_namesstr or list of str, optional

Names of the variables for which the BFMI should be computed. Defaults to “energy”.

filter_vars{None, “like”, “regex”}, default None
coordsdict, optional

Dictionary of dimension/index names to coordinate values defining a subset of the data for which to perform the computation.

**kwargsany, optional

Forwarded to the array or dataarray interface for additional options.

Returns:
ndarray, xarray.DataArray, xarray.Dataset, xarray.DataTree

Requested BFMI summary of the provided input

References

[1]

Betancourt. Diagnosing Suboptimal Cotangent Disintegrations in Hamiltonian Monte Carlo. (2016) https://arxiv.org/abs/1604.00695

Examples

Compute the BFMI for the ‘radon’ example:

In [1]: from arviz_base import load_arviz_data
   ...: import arviz_stats as azs
   ...: data = load_arviz_data('radon')
   ...: azs.bfmi(data)
   ...: 
Out[1]: 
<xarray.DataTree 'sample_stats'>
Group: /sample_stats
    Dimensions:  (chain: 4)
    Coordinates:
      * chain    (chain) int64 32B 0 1 2 3
    Data variables:
        energy   (chain) float64 32B 0.7294 0.6772 0.6553 0.7193
Contents