API Reference#

This reference provides detailed documentation for user functions in the current release of kulprit.

kulprit#

Kulprit.

Kullback-Leibler projections for Bayesian model selection.

class kulprit.ProjectionPredictive(model, idata=None)[source]#

Projection Predictive class from which we perform the model selection procedure.

compare(plot=True, min_model_size=0, legend=True, title=True, figsize=None, plot_kwargs=None)[source]#

Compare the ELPD of the projected models along the search path.

Parameters:#

plotbool

Plot the results of the comparison. Defaults to True

legendbool

Add legend to figure. Defaults to True.

titlebool

Show a tittle with a description of how to interpret the plot. Defaults to True.

figsizetuple

If None, size is (10, num of submodels) inches

plot_kwargsdict

Optional arguments for plot elements. Currently accepts ‘color_elpd’, ‘marker_elpd’,

‘marker_fc_elpd’, ‘color_dse’, ‘marker_dse’, ‘ls_reference’, ‘color_ls_reference’, ‘xlabel_rotation’.

Returns:#

cmpelpd_info

tuples of index, elpd_loo point estimate and standard error for each submodel The index -1 corresponds to the reference model.

axes : matplotlib_axes or bokeh_figure

plot_densities(var_names=None, submodels=None, include_reference=True, labels='formula', kind='density', figsize=None, plot_kwargs=None)[source]#

Compare the projected posterior densities of the submodels

Parameters:#

var_nameslist of str, optional

List of variables to plot.

submodelslist of int, optional

List of submodels to plot, 0 is intercept-only model and the largest valid integer is the total number of variables in reference model. If None, all submodels are plotted.

include_referencebool

Whether to include the reference model in the plot. Defaults to True.

labelsstr

If “formula”, the labels are the formulas of the submodels. If “size”, the number of covariates in the submodels.

figsizetuple

Figure size. If None it will be defined automatically.

plot_kwargsdict

Dictionary passed to ArviZ’s plot_density function (if kind density) or to plot_forest (if kind forest).

Returns:#

axes : matplotlib_axes or bokeh_figure

project(max_terms=None, path='forward', num_samples=100, tolerance=0.01, early_stop=False)[source]#

Perform model projection.

If max_terms is not provided, then the search path runs from the intercept-only model up to but not including the full model.

Parameters:#

max_termsint

The number of parameters of the largest submodel in the search path, not including the intercept term.

pathstr or list

The search method to employ, either “forward” for a forward search, or “l1” for a L1-regularized search path. If a nested list of terms is provided, model with those terms will be projected directly.

num_samplesint

The number of samples to draw from the posterior predictive distribution for the projection procedure. Defaults to 100.

tolerancefloat

The tolerance for the optimization procedure. Defaults to 0.01

early_stopbool or str

Whether to stop the search when the difference in ELPD between the submodel and the reference model is small. There are two criteria, “mean” and “se”. The “mean” criterion stops the search when the difference in ELPD is smaller than 4. The “se” criterion stops the search when the ELPD of the submodel is within one standard error of the reference model. Defaults to False.

submodels(index)[source]#

Return submodels by index

Parameters:

index (int or list of int) – The index or indices of the submodels to return. If a list of indices is provided, the submodels will be returned in the order of the list.

Returns:

The submodels corresponding to the provided indices

Return type:

list of SubModel

kulprit.plots#

Top-level plotting module.

kulprit.plots.plot_compare(elpd_info, label_terms=None, legend=True, title=True, figsize=None, plot_kwargs=None)[source]#

Plot model comparison.

Parameters:#

cmp_dfpd.DataFrame

Dataframe containing the comparison data. Should have columns elpd_loo and elpd_diff containing the ELPD values and the differences to the reference model.

label_termslist

List of the labels for the submodels.

legendbool

Flag for plotting the legend, default True.

titlebool

Flag for plotting the title, default True.

figsizetuple

Figure size. If None it will be defined automatically.

plot_kwargs : dict