API Reference#

This reference provides detailed documentation for all modules, classes, and methods in the current release of PyMC-BART.

`pymc_bart`#

class pymc_bart.BART(name: str, X: TensorLike, Y: TensorLike, m: int = 50, alpha: float = 0.95, beta: float = 2.0, response: str = 'constant', split_rules: list[str] | None = None, split_prior: ndarray[tuple[Any, ...], dtype[float64]] | None = None, **kwargs)#

Bayesian Additive Regression Tree distribution.

Distribution representing a sum over trees

Parameters#

XPyTensor Variable, Pandas/Polars DataFrame or Numpy array: The covariate matrix.
YPyTensor Variable, Pandas/Polar DataFrame/Series,or Numpy array: The response vector.
mint: Number of trees.
responsestr: How the leaf_node values are computed. Available options are constant, linear or mix. Defaults to constant. Options linear and mix are still experimental.
alphafloat: Controls the prior probability over the depth of the trees. Should be in the (0, 1) interval.
betafloat: Controls the prior probability over the number of leaves of the trees. Should be positive.
split_priorOptional[list[float]], default None.: List of positive numbers, one per column in input data. Defaults to None, all covariates have the same prior probability to be selected.
split_rulesOptional[list[str]], default None: List of SplitRule objects, one per column in input data. Allows using different split rules for different columns. Default is ContinuousSplitRule. Other options are OneHotSplitRule and SubsetSplitRule, both meant for categorical variables.

Notes#

The parameters alpha and beta parametrize the probability that a node at depth \(d \: (= 0, 1, 2,...)\) is non-terminal, given by \(\alpha(1 + d)^{-\beta}\). The default values are \(\alpha = 0.95\) and \(\beta = 2\).

This is the recommend prior by Chipman Et al. BART: Bayesian additive regression trees, link

classmethod dist(*params, **kwargs)#

Create a tensor variable corresponding to the cls distribution.

Parameters#

dist_paramsarray-like: The inputs to the RandomVariable Op.
shapeint, tuple, Variable, optional: A tuple of sizes for each dimension of the new RV.
return_next_rngbool, default False: If True, return a (next_rng, rv) tuple instead of just the random variable. The default is to discard next_rng.
**kwargs: Keyword arguments that will be forwarded to the PyTensor RV Op. Most prominently: size or dtype.

Returns#

rvTensorVariable: The created random variable tensor. If return_next_rng is True, returns a (next_rng, rv) tuple instead.

logp(x, *inputs)#

Calculate log probability.

Parameters#

x: numeric, TensorVariable: Value for which log-probability is calculated.

Returns#

TensorVariable

pymc_bart.compute_variable_importance(idata: Any, bartrv: Variable | list[Variable], X: ndarray[tuple[Any, ...], dtype[_ScalarT]], model: Model | None = None, method: str = 'VI', fixed: int = 0, samples: int = 50, random_seed: int | None = None) → dict[str, ndarray[tuple[Any, ...], dtype[_ScalarT]]]#

Estimates variable importance from the BART-posterior.

Parameters#

idataDataTree: DataTree containing a “variable_inclusion” variable in the sample_stats group.
bartrvBART Random Variable: BART variable once the model that include it has been fitted.
Xnpt.NDArray: The covariate matrix.
modelOptional[pm.Model]: The PyMC model that contains the BART variable. Only needed if the model contains multiple BART variables.
methodstr: Method used to rank variables. Available options are “VI” (default), “backward” and “backward_VI”. The R squared will be computed following this ranking. “VI” counts how many times each variable is included in the posterior distribution of trees. “backward” uses a backward search based on the R squared. “backward_VI” combines both methods with the backward search excluding the fixed number of variables with the lowest variable inclusion. “VI” is the fastest method, while “backward” is the slowest.
fixedOptional[int]: Number of variables to fix in the backward search. Defaults to None. Must be greater than 0 and less than the number of variables. Ignored if method is “VI” or “backward”.
samplesint: Number of predictions used to compute correlation for subsets of variables. Defaults to 50
random_seedOptional[int]: random_seed used to sample from the posterior. Defaults to None.

Returns#

vi_results: dictionary

pymc_bart.get_variable_inclusion(idata, X, model=None, bart_var_name=None, labels=None, to_kulprit=False)#

Get the normalized variable inclusion from BART model.

Parameters#

idataDataTree: DataTree with a variable “variable_inclusion” in sample_stats group
Xnpt.NDArray: The covariate matrix.
modelOptional[pm.Model]: The PyMC model that contains the BART variable. Only needed if the model contains multiple BART variables.
bart_var_nameOptional[str]: The name of the BART variable in the model. Only needed if the model contains multiple BART variables.
labelsOptional[list[str]]: List of the names of the covariates. If X is a DataFrame the names of the covariables will be taken from it and this argument will be ignored.
to_kulpritbool: If True, the function will return a list of list with the variables names. This list can be passed as a path to Kulprit’s project method. Defaults to False.

Returns#

VI_normnpt.NDArray: Normalized variable inclusion.
labelslist[str]: List of the names of the covariates.

pymc_bart.plot_ice(bartrv: Variable, X: ndarray[tuple[Any, ...], dtype[_ScalarT]], Y: ndarray[tuple[Any, ...], dtype[_ScalarT]] | None = None, var_idx: list[int] | None = None, var_discrete: list[int] | None = None, func: Callable | None = None, centered: bool | None = True, samples: int = 100, instances: int = 30, random_seed: int | None = None, sharey: bool = True, smooth: bool = True, grid: str = 'long', color='C0', color_mean: str = 'C0', alpha: float = 0.1, figsize: tuple[float, float] | None = None, smooth_kwargs: dict[str, Any] | None = None, ax: Axes | None = None) → list[Axes]#

Individual conditional expectation plot.

Parameters#

bartrvBART Random Variable: BART variable once the model that include it has been fitted.
Xnpt.NDArray: The covariate matrix.
YOptional[npt.NDArray], by default None.: The response vector.
var_idxOptional[list[int]], by default None.: List of the indices of the covariate for which to compute the pdp or ice.
var_discreteOptional[list[int]], by default None.: List of the indices of the covariate treated as discrete.
funcOptional[Callable], by default None.: Arbitrary function to apply to the predictions. Defaults to the identity function.
centeredbool: If True the result is centered around the partial response evaluated at the lowest value in xs_interval. Defaults to True.
samplesint: Number of posterior samples used in the predictions. Defaults to 100
instancesint: Number of instances of X to plot. Defaults to 30.
random_seedOptional[int], by default None.: Seed used to sample from the posterior. Defaults to None.
shareybool: Controls sharing of properties among y-axes. Defaults to True.
smoothbool: If True the result will be smoothed by first computing a linear interpolation of the data over a regular grid and then applying the Savitzky-Golay filter to the interpolated data. Defaults to True.
gridstr or tuple: How to arrange the subplots. Defaults to “long”, one subplot below the other. Other options are “wide”, one subplot next to each other or a tuple indicating the number of rows and columns.
colormatplotlib valid color: Color used to plot the pdp or ice. Defaults to “C0”
color_meanmatplotlib valid color: Color used to plot the mean pdp or ice. Defaults to “C0”,
alphafloat: Transparency level, should in the interval [0, 1].
figsizetuple: Figure size. If None it will be defined automatically.
smooth_kwargsdict: Additional keywords modifying the Savitzky-Golay filter. See scipy.signal.savgol_filter() for details.
axaxes: Matplotlib axes.

Returns#

axes: matplotlib axes

pymc_bart.plot_pdp(bartrv: Variable | list[Variable], X: ndarray[tuple[Any, ...], dtype[_ScalarT]], Y: ndarray[tuple[Any, ...], dtype[_ScalarT]] | None = None, xs_interval: str = 'quantiles', xs_values: int | list[float] | None = None, var_idx: list[int] | None = None, var_discrete: list[int] | None = None, func: Callable | None = None, samples: int = 200, ref_line: bool = True, random_seed: int | None = None, sharey: bool = True, smooth: bool = True, grid: str = 'long', color='C0', color_mean: str = 'C0', alpha: float = 0.1, figsize: tuple[float, float] | None = None, smooth_kwargs: dict[str, Any] | None = None, ax: Axes = None) → list[Axes]#

Partial dependence plot.

Parameters#

bartrvBART Random Variable: BART variable once the model that include it has been fitted.
Xnpt.NDArray: The covariate matrix.
YOptional[npt.NDArray], by default None.: The response vector.
xs_intervalstr: Method used to compute the values X used to evaluate the predicted function. “linear”, evenly spaced values in the range of X. “quantiles”, the evaluation is done at the specified quantiles of X. “insample”, the evaluation is done at the values of X. For discrete variables these options are ommited.
xs_valuesOptional[Union[int, list[float]]], by default None.: Values of X used to evaluate the predicted function. If xs_interval="linear" number of points in the evenly spaced grid. If xs_interval="quantiles" quantile or sequence of quantiles to compute, which must be between 0 and 1 inclusive. Ignored when xs_interval="insample".
var_idxOptional[list[int]], by default None.: List of the indices of the covariate for which to compute the pdp or ice.
var_discreteOptional[list[int]], by default None.: List of the indices of the covariate treated as discrete.
funcOptional[Callable], by default None.: Arbitrary function to apply to the ions. Defaults to the identity function.
samplesint: Number of posterior samples used in the predictions. Defaults to 200
ref_linebool: If True a reference line is plotted at the mean of the partial dependence. Defaults to True.
random_seedOptional[int], by default None.: Seed used to sample from the posterior. Defaults to None.
shareybool: Controls sharing of properties among y-axes. Defaults to True.
smoothbool: If True the result will be smoothed by first computing a linear interpolation of the data over a regular grid and then applying the Savitzky-Golay filter to the interpolated data. Defaults to True.
gridstr or tuple: How to arrange the subplots. Defaults to “long”, one subplot below the other. Other options are “wide”, one subplot next to eachother or a tuple indicating the number of rows and columns.
colormatplotlib valid color: Color used to plot the pdp or ice. Defaults to “C0”
color_meanmatplotlib valid color: Color used to plot the mean pdp or ice. Defaults to “C0”,
alphafloat: Transparency level, should in the interval [0, 1].
figsizetuple: Figure size. If None it will be defined automatically.
smooth_kwargsdict: Additional keywords modifying the Savitzky-Golay filter. See scipy.signal.savgol_filter() for details.
axaxes: Matplotlib axes.

Returns#

axes: matplotlib axes

Plot submodel’s predictions against reference-model’s predictions.

Parameters#

vi_resultsDictionary: Dictionary computed with compute_variable_importance
funcOptional[Callable], by default None.: Arbitrary function to apply to the predictions. Defaults to the identity function.
submodelsOptional[Union[list[int], np.ndarray]]: List of the indices of the submodels to plot. Defaults to None, all variables are ploted. The indices correspond to order computed by compute_variable_importance. For example submodels=[0,1] will plot the two most important variables. submodels=[1,0] is equivalent as values are sorted before use.
gridstr or tuple: How to arrange the subplots. Defaults to “long”, one subplot below the other. Other options are “wide”, one subplot next to each other or a tuple indicating the number of rows and columns.
labelsOptional[list[str]]: List of the names of the covariates.
plot_kwargsdict: Additional keyword arguments for the plot. Defaults to None. Valid keys are: - marker_scatter: matplotlib valid marker for the scatter plot - color_scatter: matplotlib valid color for the scatter plot - alpha_scatter: matplotlib valid alpha for the scatter plot - color_ref: matplotlib valid color for the 45 degree line - ls_ref: matplotlib valid linestyle for the reference line
axesaxes: Matplotlib axes.

Returns#

axes: matplotlib axes

Estimates variable importance from the BART-posterior.

Parameters#

vi_results: Dictionary: Dictionary computed with compute_variable_importance
submodelsOptional[Union[list[int], np.ndarray]]: List of the indices of the submodels to plot. Defaults to None, all variables are ploted. The indices correspond to order computed by compute_variable_importance. For example submodels=[0,1] will plot the two most important variables. submodels=[1,0] is equivalent as values are sorted before use.
labelsOptional[list[str]]: List of the names of the covariates. If X is a DataFrame the names of the covariables will be taken from it and this argument will be ignored.
plot_kwargsdict: Additional keyword arguments for the plot. Defaults to None. Valid keys are: - color_r2: matplotlib valid color for error bars - marker_r2: matplotlib valid marker for the mean R squared - marker_fc_r2: matplotlib valid marker face color for the mean R squared - ls_ref: matplotlib valid linestyle for the reference line - color_ref: matplotlib valid color for the reference line - rotation: float, rotation angle of the x-axis labels. Defaults to 0.
axaxes: Matplotlib axes.

Returns#

axes: matplotlib axes

pymc_bart.plot_variable_inclusion(idata, X, labels=None, figsize=None, plot_kwargs=None, ax=None)#

Plot normalized variable inclusion from BART model.

Parameters#

idataDataTree: DataTree containing a collection of BART_trees in sample_stats group
Xnpt.NDArray: The covariate matrix.
labelsOptional[list[str]]: List of the names of the covariates. If X is a DataFrame the names of the covariables will be taken from it and this argument will be ignored.
figsizetuple: Figure size. If None it will be defined automatically.
plot_kwargsdict: Additional keyword arguments for the plot. Defaults to None. Valid keys are: - color: matplotlib valid color for VI - marker: matplotlib valid marker for VI - ls: matplotlib valid linestyle for the VI line - rotation: float, rotation of the x-axis labels
axaxes: Matplotlib axes.

Returns#

axes: matplotlib axes

API Reference#

pymc_bart#

Parameters#

Notes#

Parameters#

Returns#

Parameters#

Returns#

Parameters#

Returns#

Parameters#

Returns#

Parameters#

Returns#

Parameters#

Returns#

Parameters#

Returns#

Parameters#

Returns#

Parameters#

Returns#

`pymc_bart`#