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 toplot_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