Local Interpretable Model-Agnostic Explanations

When building complex models, it is often difficult to explain why the model should be trusted. While global measures such as accuracy are useful, they cannot be used for explaining why a model made a specific prediction. 'lime' (a port of the 'lime' 'Python' package) is a method for explaining the outcome of black box models by fitting a local model around the point in question an perturbations of this point. The approach is described in more detail in the article by Ribeiro et al. (2016) .

Travis-CI BuildStatus AppVeyor BuildStatus CRAN_Release_Badge CRAN_Download_Badge CoverageStatus

Whose models were simply sublime,

It gave explanations for their variations,

one observation at a time.

lime-rick by Mara Averick

This is an R port of the Python lime package (https://github.com/marcotcr/lime) developed by the authors of the lime (Local Interpretable Model-agnostic Explanations) approach for black-box model explanations. All credits for the invention of the approach goes to the original developers.

The purpose of lime is to explain the predictions of black box classifiers. What this means is that for any given prediction and any given classifier it is able to determine a small set of features in the original data that has driven the outcome of the prediction. To learn more about the methodology of lime read the paper and visit the repository of the original implementation.

The lime package for R does not aim to be a line-by-line port of its Python counterpart. Instead it takes the ideas laid out in the original code and implements them in an API that is idiomatic to R.

An example

Out of the box lime supports a long range of models, e.g. those created with caret, parsnip, and mlr. Support for unsupported models are easy to achieve by adding a predict_model and model_type method for the given model.

The following shows how a random forest model is trained on the iris data set and how lime is then used to explain a set of new observations:

# Split up the data set
iris_test <- iris[1:5, 1:4]
iris_train <- iris[-(1:5), 1:4]
iris_lab <- iris[[5]][-(1:5)]
# Create Random Forest model on iris data
model <- train(iris_train, iris_lab, method = 'rf')
# Create an explainer object
explainer <- lime(iris_train, model)
# Explain new observation
explanation <- explain(iris_test, explainer, n_labels = 1, n_features = 2)
# The output is provided in a consistent tabular format and includes the
# output from the model.
#> # tibble [10 × 13]
#>    model_type case  label label_prob model_r2 model_intercept
#>    <chr>      <chr> <chr>      <dbl>    <dbl>           <dbl>
#>  1 classific… 1     seto…          1    0.340           0.263
#>  2 classific… 1     seto…          1    0.340           0.263
#>  3 classific… 2     seto…          1    0.336           0.259
#>  4 classific… 2     seto…          1    0.336           0.259
#>  5 classific… 3     seto…          1    0.361           0.258
#>  6 classific… 3     seto…          1    0.361           0.258
#>  7 classific… 4     seto…          1    0.364           0.247
#>  8 classific… 4     seto…          1    0.364           0.247
#>  9 classific… 5     seto…          1    0.343           0.256
#> 10 classific… 5     seto…          1    0.343           0.256
#> # ... with 7 more variables: model_prediction <dbl>, feature <chr>,
#> #   feature_value <dbl>, feature_weight <dbl>, feature_desc <chr>,
#> #   data <list>, prediction <list>
# And can be visualised directly

lime also supports explaining image and text models. For image explanations the relevant areas in an image can be highlighted:

explanation <- .load_image_example()

Here we see that the second most probably class is hardly true, but is due to the model picking up waxy areas of the produce and interpreting them as wax-light surface.

For text the explanation can be shown by highlighting the important words. It even includes a shiny application for interactively exploring text models:

interactive text explainer


lime is available on CRAN and can be installed using the standard approach:


To get the development version, install from GitHub instead:

# install.packages('devtools')


lime 0.4.1

  • Add build-in support for parsnip and ranger
  • Add preprocess argument to lime.data.frame to keep it in line with the other types. Use it to transform your data.frame into a new input that your model expects after permutations
  • magick is now only in suggest to cut down on heavy hard dependencies
  • explain now returns a tbl_df so you get pretty printing if you have tibble loaded
  • When plotting regression explanations of non-binned features the feature weight is now multiplied by its value
  • More consistent support for keras
  • Fix bug when xgboost was used with with default objective
  • Better errors when handling bad models
  • plot_features now has a cases argument for subsetting the data before plotting

lime 0.4

  • Add support for image explanation. The dispatch will be on paths pointing to valid image files. Image explanations can be visualised using plot_image_explanation (#35)
  • Add support for neural networks from the keras package
  • Add as_classifier() and as_regressor() for ad-hoc specification of the model type in case the heuristic implemented in lime doesn't hold. as_classifier() also lets you add/overwrite the class labels.
  • Use gower as the new default similarity measure for tabular data
  • If bin_continuous = FALSE the default behavior is now to sample from a kernel density estimation rather than assume a normal distribution.
  • Fix bug when numeric features in the training data were constant (#56)
  • Fix bug when plotting regression explanations with plot_explanations() (#60)
  • Logical columns in tabular data is now supported (#75)
  • Overhaul of plot_text_explanation() with better formatting and scrolling support for many explanations
  • All plots now show the fit of the explainer so the user can assess the quality of the explanation

lime 0.3.1

  • Added a NEWS.md file to track changes to the package.
  • Fixed bug when explaining regression models, due to drop=TRUE defaults (#33)
  • Integer features are no longer converted to numeric during permutations (#32)
  • Fix bug when working with xgboost and tabular predictions (@martinju #1)
  • Training data can now contain NA values (#8)
  • Keep ordering when plotting with plot_features() (#38)
  • Fix support for mlr by extracting predictions correctly
  • Added support for h2o (@mdancho84) (#40)
  • Throws meaningful error when all permutations have 0 similarity to original observation (#47)
  • Explaining data can now contain NA values (#45)
  • Support for Date and POSIXt columns. They will be kept constant during permutations so that lime will explain the model behaviour at the given timepoint based on the remaining features (#39).
  • Add plot_explanations() for an overview plot of a large explanation set

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.


0.4.1 by Thomas Lin Pedersen, 4 months ago


Report a bug at https://github.com/thomasp85/lime/issues

Browse source code at https://github.com/cran/lime

Authors: Thomas Lin Pedersen [cre, aut] , Michaël Benesty [aut]

Documentation:   PDF Manual  

MIT + file LICENSE license

Imports glmnet, stats, ggplot2, tools, stringi, Matrix, Rcpp, assertthat, htmlwidgets, shiny, shinythemes, methods, grDevices, gower

Suggests xgboost, testthat, mlr, h2o, text2vec, MASS, covr, knitr, rmarkdown, devtools, magick, keras, ranger

Linking to Rcpp, RcppEigen

See at CRAN