arviz_stats.ess

Contents

arviz_stats.ess#

arviz_stats.ess(data, sample_dims=None, group='posterior', var_names=None, filter_vars=None, coords=None, method='bulk', relative=False, prob=None, chain_axis=0, draw_axis=1)[source]#

Estimate the effective sample size (ess).

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 “posterior”

Group on which to compute the ESS.

var_namesstr or list of str, optional

Names of the variables for which the ess should be computed.

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.

methodstr, default “bulk”

Valid methods are:

  • “bulk”

  • “tail” # prob, optional

  • “quantile” # prob

  • “mean” (old ess)

  • “sd”

  • “median”

  • “mad” (mean absolute deviance)

  • “z_scale”

  • “folded”

  • “identity”

  • “local” # prob

relativebool

Return relative ess ress = ess / n

probfloat, or tuple of two floats, optional

Probability value for “tail”, “quantile” or “local” ess functions.

chain_axis, draw_axisint, optional

Integer indicators of the axis that correspond to the chain and the draw dimension. chain_axis can be None.

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

Requested ESS summary of the provided input

See also

arviz.rhat

Compute estimate of rank normalized split R-hat for a set of traces.

arviz.mcse

Calculate Markov Chain Standard Error statistic.

plot_ess

Plot quantile, local or evolution of effective sample sizes (ESS).

arviz.summary

Create a data frame with summary statistics.

Examples

Calculate the effective_sample_size using the default arguments:

In [1]: from arviz_base import load_arviz_data
   ...: import arviz_stats as azs
   ...: data = load_arviz_data('non_centered_eight')
   ...: azs.ess(data)
   ...: 
Out[1]: 
<xarray.DataTree 'posterior'>
Group: /posterior
    Dimensions:  (school: 8)
    Coordinates:
      * school   (school) <U16 512B 'Choate' 'Deerfield' ... 'Mt. Hermon'
    Data variables:
        mu       float64 8B 1.65e+03
        theta_t  (school) float64 64B 2.058e+03 2.51e+03 ... 2.455e+03 2.757e+03
        tau      float64 8B 1.115e+03
        theta    (school) float64 64B 1.942e+03 2.199e+03 ... 2.079e+03 2.106e+03

Calculate ess for a subset of the variables

In [2]: azs.ess(data, relative=True, var_names=["mu", "theta_t"])
Out[2]: 
<xarray.DataTree 'posterior'>
Group: /posterior
    Dimensions:  (school: 8)
    Coordinates:
      * school   (school) <U16 512B 'Choate' 'Deerfield' ... 'Mt. Hermon'
    Data variables:
        mu       float64 8B 0.8252
        theta_t  (school) float64 64B 1.029 1.255 1.14 1.106 ... 1.198 1.228 1.378

Calculate ess using the “tail” method, leaving the prob at its default value.

In [3]: azs.ess(data, method="tail")
Out[3]: 
<xarray.DataTree 'posterior'>
Group: /posterior
    Dimensions:  (school: 8)
    Coordinates:
      * school   (school) <U16 512B 'Choate' 'Deerfield' ... 'Mt. Hermon'
    Data variables:
        mu       float64 8B 1.06e+03
        theta_t  (school) float64 64B 1.535e+03 1.437e+03 ... 1.517e+03 1.486e+03
        tau      float64 8B 868.1
        theta    (school) float64 64B 1.772e+03 1.601e+03 ... 1.432e+03 1.594e+03
Contents