skip to content

In lime 0.2.0.1's tabular explainer, which settings go on the LimeTabularExplainer constructor and which on explain_instance, and why does the split matter?

level: middleimportance: should knowfreq 14%

answer

  1. set once versus set per row
  2. training statistics fixed at construction
  3. kernel width lives on the explainer
  4. sample count and feature cap per call
  5. one seeded generator, advanced by each call

basics

~20 s

The constructor fixes everything derived from training data: kernel_width, discretisation, categorical columns, feature_selection and random_state. explain_instance takes per-row choices: num_features, num_samples, labels or top_labels, distance_metric and model_regressor. Changing a constructor setting means building a new explainer.

solid answer

~40 s

In lime 0.2.0.1, `LimeTabularExplainer(training_data, ...)` computes the training statistics once (quartile bins, means and standard deviations, category frequencies) and fixes `mode`, `categorical_features`, `discretize_continuous` and `discretizer`, `kernel_width` (`None` becomes `sqrt(columns) * 0.75`, about 3.82 for 26 columns), `feature_selection`, `sample_around_instance` and `random_state`. `explain_instance(data_row, predict_fn, labels=(1,), top_labels=None, num_features=10, num_samples=5000, distance_metric='euclidean', model_regressor=None)` holds what can vary per row. The method takes no catch-all keyword arguments, so passing `kernel_width` there raises a `TypeError`; to try another width you build another explainer. `random_state` seeds one generator that every call advances, so a seeded job is reproducible as a whole run in the same order, not call by call.

code

python · 19 lines
python
from lime.lime_tabular import LimeTabularExplainer

explainer = LimeTabularExplainer(
    X_train,                       # numpy array, 26 columns
    mode="classification",
    feature_names=feature_names,
    categorical_features=cat_idx,  # 7 integer-coded columns
    class_names=["show", "no-show"],
    kernel_width=None,             # sqrt(26) * 0.75, about 3.82
    random_state=42,
)

exp = explainer.explain_instance(
    X_score[0],
    model.predict_proba,
    num_features=8,
    num_samples=5000,
)
print(exp.as_list(label=1))

go deeper

for a junior

Recall the two lists: training data, categorical columns, discretisation, kernel width and seed on the constructor; num_features, num_samples and the labels on explain_instance.

for a middle

Explain why the split exists: the constructor computes training statistics and builds the kernel once, so kernel_width defaults to sqrt(columns) * 0.75 and cannot change per call.

for a senior

Show the batch-job consequences: one shared seeded generator, num_samples predictions per row, and constructor settings stored with the explanations so a result can be reproduced.

for a principal

Weigh how much explanation compute a nightly job can spend per row against how stable stored explanations must be, and decide who owns those settings.

## Two places to configure lime `lime.lime_tabular.LimeTabularExplainer` is configured in two places, and mixing them up is the commonest mistake when a team wires LIME into a scoring job. The **constructor** learns everything that depends on the training data and fixes how perturbations are built and weighted. The **call**, `explain_instance`, decides how much work to do for one row and what to report. In lime 0.2.0.1, the release `pip install lime` installs, the split is: | Constructor argument | Default | What it fixes | |---|---|---| | `training_data` | required | statistics: quartile bins, means, standard deviations, category frequencies | | `mode` | `"classification"` | whether `predict_fn` returns probabilities or values | | `categorical_features`, `categorical_names` | `None` | which columns are categories, and their display names | | `discretize_continuous`, `discretizer` | `True`, `'quartile'` | whether continuous columns become bins, and which bins | | `kernel_width`, `kernel` | `None`, `None` | the proximity weighting of samples | | `feature_selection` | `'auto'` | how the surrogate's features are chosen | | `sample_around_instance` | `False` | centre continuous samples on the row instead of the training mean | | `random_state` | `None` | the random generator for sampling | | `training_data_stats` | `None` | precomputed statistics for bins and category frequencies | | Call argument | Default | What it controls | |---|---|---| | `data_row`, `predict_fn` | required | the row and the model | | `labels`, `top_labels` | `(1,)`, `None` | which classes are explained | | `num_features` | `10` | the most features in the explanation | | `num_samples` | `5000` | how many perturbed rows go to the model | | `distance_metric` | `'euclidean'` | the distance the kernel weights | | `model_regressor` | `None` (a ridge regression) | the surrogate model | ## kernel_width: the default and where to change it With `kernel_width=None`, the constructor sets the width to `sqrt(number of columns) * 0.75`. For an airline's 26-feature booking no-show model that is `sqrt(26) * 0.75`, about **3.82**. The default kernel turns each sample's distance `d` into a weight `sqrt(exp(-d**2 / width**2))`. Because the width is baked into a kernel function when the explainer is built, it cannot change per row: - `explain_instance(row, predict_fn, kernel_width=2.0)` raises a `TypeError` for an unexpected keyword argument, because the method has no catch-all `**kwargs`. - To compare widths, construct one explainer per width from the same training data. How the width trades locality against stability is a question about local surrogates in general; on this package the point is that it is a constructor setting with a column-count default. ## random_state and num_samples in a batch job `random_state` accepts an integer or a numpy `RandomState`. The explainer turns it into **one** generator and shares it with its sampling and its discretiser. Two consequences follow: 1. Seeding makes a whole run reproducible when a freshly built explainer explains the same rows in the same order. 2. It does **not** make two calls on the same row identical inside one session: the first call advances the generator, so the second draws different samples. To reproduce a single explanation, rebuild the explainer with the same seed. `num_samples` is the size of the neighbourhood. lime builds that many rows (the first is the original) and passes them to `predict_fn` in **one** call, so each explanation costs `num_samples` model predictions: 5,000 by default, or 50 million for 10,000 bookings a night. Fewer samples save time and make the sampled neighbourhood noisier. `num_features` caps the explanation's length and also steers the default feature selection: forward selection at 6 or fewer, highest weights above. ## Why the split matters - Expensive work, fitting the discretiser and computing statistics, happens once, so build the explainer at job start, not per row. - Changing a constructor setting changes every explanation that follows; store those settings beside the explanations a job writes. - A per-row setting can differ between rows, which is how a team spends more samples on contested cases. ## What master has that 0.2.0.1 lacks The GitHub master branch (last commit July 2021) adds a `sampling_method` argument (`'gaussian'` or `'lhs'`) to `explain_instance`. The released 0.2.0.1 does not have it, so code copied from the repository raises a `TypeError` on the installed package. Check arguments against the installed release, not the repository.

  • Where do you change lime's surrogate model or the distance used for weighting, and what are the defaults?
    Both are per call. `model_regressor=None` becomes `Ridge(alpha=1, fit_intercept=True)` inside lime, and any scikit-learn regressor that exposes `coef_` and accepts `sample_weight` in `fit` can replace it. `distance_metric='euclidean'` is passed to scikit-learn's pairwise distances on the scaled samples.
  • What does LimeTabularExplainer's sample_around_instance change?
    Only with `discretize_continuous=False`: continuous columns are then sampled from a normal scaled by each column's training standard deviation, centred on the training mean by default or on the explained row with `sample_around_instance=True`. With discretisation on, the default, the flag has no effect, because continuous columns are sampled bin by bin.

The constructor is the lens you fit before a shoot: training statistics, kernel width and seed are chosen once, and changing them means swapping the lens, that is, building a new explainer. explain_instance is the exposure set for each shot: how many samples and how many features.

  • kernel_width can be passed to explain_instance for each row.
  • Setting random_state makes repeated calls on one row identical.
  • num_samples is fixed once on the explainer.
  • The tabular kernel width default is the same constant for every dataset.
  • sampling_method is available in the pip-installed lime.

Assumes lime 0.2.0.1, the last PyPI release (June 2020); the sampling_method argument exists only on the unreleased master branch.