Package 'ebm'

An object that inherits from class "interpret.glassbox._ebm._ebm.ExplainableBoostingClassifier" or "interpret.glassbox._ebm._ebm.ExplainableBoostingRegressor". For instance, the result of calling fit$copy() where fit is a fitted ebm() object.

Additional optional arguments. (Currently ignored.)

A formula of the form y ~ x1 + x2 + ....

A data frame containing the variables in the model.

Max number of bins per feature for the main effects stage. Default is 1024.

Max number of bins per feature for interaction terms. Default is 64.

Interaction terms to be included in the model. Default is 0.9. Current options include:

• Integer (1 <= interactions): Count of interactions to be automatically selected.

• Percentage (interactions < 1.0): Determine the integer count of interactions by multiplying the number of features by this percentage.

• List of numeric pairs: The pairs contain the indices of the features within each additive term. In addition to pairs, the interactions parameter accepts higher order interactions. It also accepts univariate terms which will cause the algorithm to boost the main terms at the same time as the interactions. When boosting mains at the same time as interactions, the exclude parameter should be set to "mains" and currently max_bins needs to be equal to max_interaction_bins.

Features or terms to be excluded. Default is NULL.

Validation set size. Used for early stopping during boosting, and is needed to create outer bags. Default is 0.15. Options are:

• Integer (1 <= validation_size): Count of samples to put in the validation sets.

• Percentage (validation_size < 1.0): Percentage of the data to put in the validation sets.

• 0: Turns off early stopping. Outer bags have no utility. Error bounds will

Number of outer bags. Outer bags are used to generate error bounds and help with smoothing the graphs.

Number of inner bags. Default is 0 which turns off inner bagging.

Learning rate for boosting. Deafult is 0.04.

The proportion of greedy boosting steps relative to cyclic boosting steps. A value of 0 disables greedy boosting, effectively turning it off. Default is 10.

This parameter specifies the proportion of the boosting cycles that will actively contribute to improving the model's performance. It is expressed as a logical or numeric between 0 and 1, with the default set to TRUE (1.0), meaning 100% of the cycles are expected to make forward progress. If forward progress is not achieved during a cycle, that cycle will not be wasted; instead, it will be used to update internal gain calculations related to how effective each feature is in predicting the target variable. Setting this parameter to a value less than 1.0 can be useful for preventing overfitting. Default is FALSE.

Number of initial highly regularized rounds to set the basic shape of the main effect feature graphs. Default is 500.

Number of initial highly regularized rounds to set the basic shape of the interaction effect feature graphs during fitting. Default is 100.

Total number of boosting rounds with n_terms boosting steps per round. Default is 25000.

Number of rounds with no improvement to trigger early stopping. 0 turns off early stopping and boosting will occur for exactly max_rounds. Default is 100.

Tolerance that dictates the smallest delta required to be considered an improvement which prevents the algorithm from early stopping. early_stopping_tolerance is expressed as a percentage of the early stopping metric. Negative values indicate that the individual models should be overfit before stopping. EBMs are a bagged ensemble of models. Setting the early_stopping_tolerance to zero (or even negative), allows learning to overfit each of the individual models a little, which can improve the accuracy of the ensemble as a whole. Overfitting each of the individual models reduces the bias of each model at the expense of increasing the variance (due to overfitting) of the individual models. But averaging the models in the ensemble reduces variance without much change in bias. Since the goal is to find the optimum bias-variance tradeoff for the ensemble of models—not the individual models—a small amount of overfitting of the individual models can improve the accuracy of the ensemble as a whole. Default is 1e-05.

Minimum number of samples allowed in the leaves. Default is 4.

Minimum hessian required to consider a potential split valid. Default is 0.0.

L1 regularization. Default is 0.0.

L2 regularization. Default is 0.0.

Used to limit the max output of tree leaves; <=0.0 means no constraint. Default is 0.0.

Scale factor to apply to nominal categoricals. A scale factor above 1.0 will cause the algorithm focus more on the nominal categoricals. Default is 5.0.

Minimum number of samples in order to treat a category separately. If lower than this threshold the category is combined with other categories that have low numbers of samples. Default is 10.

Used for the categorical features. This can reduce the effect of noises in categorical features, especially for categories with limited data. Default is 10.0.

Method for handling missing values during boosting. Default is "separate". The placement of the missing value bin can influence the resulting model graphs. For example, placing the bin on the "low" side may cause missing values to affect lower bins, and vice versa. This parameter does not affect the final placement of the missing bin in the model (the missing bin will remain at index 0 in the term_scores_ attribute). Possible values for missing are:

• "low": Place the missing bin on the left side of the graphs.

• "high": Place the missing bin on the right side of the graphs.

• "separate": Place the missing bin in its own leaf during each boosting step, effectively making it location-agnostic. This can lead to overfitting, especially when the proportion of missing values is small.

• "gain": Choose the best leaf for the missing value contribution at each boosting step, based on gain.

Maximum number of leaves allowed in each tree. Default is 2.

Default is NULL. This parameter allows you to specify monotonic constraints for each feature's relationship with the target variable during model fitting. However, it is generally recommended to apply monotonic constraints post-fit using the monotonize() attribute rather than setting them during the fitting process. This recommendation is based on the observation that, during fitting, the boosting algorithm may compensate for a monotone constraint on one feature by utilizing another correlated feature, potentially obscuring any monotonic violations. If you choose to define monotone constraints, monotone_constraints should be a numeric vector with a length equal to the number of features. Each element in the list corresponds to a feature and should take one of the following values:

• 0: No monotonic constraint is imposed on the corresponding feature's partial response.

• +1: The partial response of the corresponding feature should be monotonically increasing with respect to the target.

• -1: The partial response of the corresponding feature should be monotonically decreasing with respect to the target.

The objective function to optimize. Current options include:

• "auto" (try to determine automatically between "log_loss" and "rmse").

• "rmse" (root mean squared error).

• "poisson_deviance" (e.g., for counts or non-negative integers).

• "tweedie_deviance:variance_power=1.5" (e.g., for modeling total loss in insurance applications).

• "gamma_deviance" (e.g., for positive continuous response).

• "pseudo_huber:delta=1.0" (e.g., for robust regression).

• "rmse_log" ("rmse" with a log link function).

Default is "auto" which assumes "log_loss" if the response is a factor or character string and "rmse" otherwise. It's a good idea to always explicitly set this argument.

Number of jobs to run in parallel. Default is -1. Negative integers are interpreted as following joblib's formula (n_cpus + 1 + n_jobs), just like scikit-learn. For example, n_jobs = -2 means using all threads except 1.

Random state. Setting to NULL generates non-repeatable sequences. Default is 42 to remain consistent with the corresponding Python module.

Additional optional argument. (Currently ignored.)

Set of aesthetic mappings created by aes(). If specified and inherit.aes = TRUE (the default), it is combined with the default mapping at the top level of the plot. You must supply mapping if there is no plot mapping.

The data to be displayed in this layer. There are three options:

If NULL, the default, the data is inherited from the plot data as specified in the call to ggplot().

A data.frame, or other object, will override the plot data. All objects will be fortified to produce a data frame. See fortify() for which variables will be created.

A function will be called with a single argument, the plot data. The return value must be a data.frame, and will be used as the layer data. A function can be created from a formula (e.g. ~ head(.x, 10)).

The statistical transformation to use on the data for this layer, either as a ggproto Geom subclass or as a string naming the stat stripped of the stat_ prefix (e.g. "count" rather than "stat_count")

Position adjustment, either as a string naming the adjustment (e.g. "jitter" to use position_jitter), or the result of a call to a position adjustment function. Use the latter if you need to change the settings of the adjustment.

If FALSE, the default, missing values are removed with a warning. If TRUE, missing values are silently removed.

logical. Should this layer be included in the legends? NA, the default, includes if any aesthetics are mapped. FALSE never includes, and TRUE always includes. It can also be a named logical vector to finely select the aesthetics to display.

If FALSE, overrides the default aesthetics, rather than combining with them. This is most useful for helper functions that define both data and aesthetics and shouldn't inherit behaviour from the default plot specification, e.g. borders().

Other arguments passed on to layer(). These are often aesthetics, used to set an aesthetic to a fixed value, like colour = "red" or size = 3. They may also be parameters to the paired geom/stat.

Name of or path to a Python virtual environment.

Additional optional arguments. (Currently ignored.)

Additional Python packages to install alongside interpret.

Passed on to virtualenv_starter().

Whether to restart the R session after installing (note this will only occur within RStudio).

Fitted ebm objects that have been trained on similar data sets that have the same set of features.

Additional ebm objects to be merged.

A fitted ebm() object.

Character string specifying which term to plot. For interaction effect, you can supply a pair (e.g., term = c("x1", "x2")). Default is NULL which will just display the overall importance of each term.

Logocial indicating whether to display local explanations (TRUE) or global explanations (FALSE). Default is FALSE.

Data frame or matrix of samples. Unless display = "url" or full_dashboard = TRUE, then X can only contain a single row.

Optional vector of response values corresponding to X.

Optional. Either a model that can generate scores or per-sample initialization score. If samples scores it should be the same length as X.

Logical indicating whether to produce an interactive plot based on HTML. Default is FALSE. Currently, only interactive graphics (i.e., interactive = TRUE) are available for multiclass outcomes.

Integer specifying the maximum number of variable importance scores to plot. Default is NULL which corresponds to all terms in the fitted model.

Character string specifying which type of plot to construct for terms associated with categorical features. Current options are:

• geom = "bar" (or "col") uses geom_col to construct a bar chart of the scores.

• geom = "point" uses geom_point to construct a Cleveland dot plot of the term scores.

Default is "point".

Set of aesthetic mappings created by aes-related functions and/or tidy eval helpers. See example usage below.

List specifying additional arguments passed on to layer. These are often aesthetics, used to set an aesthetic to a fixed value, likecolour = "red" or size = 3. See example usage below.

Logical indicating whether or not term plots for categorical features should be flipped horzintally. Default is FALSE.

Logical indicating whether or not to also display uncertainty via error bars on the main effect plots. Default is TRUE. Not very useful unless outer_bags > 1 when calling ebm().

Numeric specifying the width of the error bars displayed in bar/ dot plots for categorical features. Default is 0.5.

Numeric between 0 and 1 specifying the level of transparency to use when displaying uncertainty in plots for continuous features. Default is 0.5.

Character string specifying the fill color to use when displaying uncertainty in plots for continuous features. Default is "grey".

Character string specifying how the results should be displayed whenever interactive = TRUE. Available options are "viewer" (e.g., RStudio viewer browser), "markdown" (e.g., for vingettes, Quarto, or Rmarkdown documents), or "url" (e.g., to print a URL which can be pasted into a browser). When display = "url", a URL for viewing the entire interpret dashboard is provided (i.e., the term and full_dashboard arguments are ignored).

Character string specifying how the results should be viewed. Current choices are "broswer", which calls utils::browseURL() to display the results in an HTML browser, or "rstudio" for displaying the results within the Viewer pane in an active RStudio session. Also works in VS Code. Default is "browser".

Logical indicating whether or not to display the full interpret dashboard. Default is FALSE. Only works when display = "viewer" or display = "url" (e.g., paste the resulting URL in your browser).

Additional optional arguments. Currently only passed onto levelplot() for heatmaps of interaction effects.

A fitted ebm object.

A data frame in which to look for variables with which to predict.

The type of prediction required. Current options include:

• "response": Returns predictions on the scale of the response variable. Thus, for a categorical outcome (i.e., binary or multiclass), a matrix of predicted probabilities is returned.

• "link": Returns predictions on the link scale. For a binary outcome with logit link, for example, this results in a vector of logits. For a multiclass outcome, this will return a matrix with one column for each class. Ignored for regression problems.

• "class": Returns a vector predicted class label for categorical outcomes.

• "terms": Returns a matrix (or list of matrices for multiclass outcomes) of the individual term contributions (e.g., the f(x)'s). Note that term contributions are on the link scale, where they are additive.

Logical indicating whether or not standard errors are required. Ignored for multiclass outcomes. Note that standard errors are only available on the link scale.

Optional. Either a model that can generate scores or per-sample initialization score. If samples scores it should be the same length as newdata.

Additional optional arguments. (Currently ignored.)

A fitted ebm object.

The number of significant digits to be passed to format() when printing.

Additional optional arguments to be passed to print.default().