omnixai.explainers.tabular.specific package

ig

The integrated-gradient explainer for tabular data.

linear

The explainable linear models.

decision_tree

The explainable tree-based models.

shap_tree

The tree-specific SHAP explainer for tabular data.

omnixai.explainers.tabular.specific.ig module

The integrated-gradient explainer for tabular data.

class omnixai.explainers.tabular.specific.ig.IntegratedGradient

Bases: object

The class for computing integrated gradients. It can handle both tabular and image data.

static compute_integrated_gradients(model, inp, baseline, output_index, steps=50)

Computes integrated gradients given the model and the inputs. The model should be either tf.keras.Model or torch.nn.Module.

Parameters
  • model – The model, e.g., a tf.keras.Model or a torch.nn.Module.

  • inp – The input instances to explain.

  • baseline – The baselines to compare with.

  • output_indexNone for regression or the label index for classification.

  • steps – The number of steps when computing integrated gradients.

Returns

The integrated gradients.

Return type

np.ndarray

class omnixai.explainers.tabular.specific.ig.IntegratedGradientTabular(training_data, model, preprocess_function=None, mode='classification', **kwargs)

Bases: TabularExplainer, IntegratedGradient

The integrated-gradient explainer for tabular data. It only supports continuous-valued features. If using this explainer, please cite the original work: https://github.com/ankurtaly/Integrated-Gradients.

Parameters
  • training_data (Tabular) – The data used to construct baselines. training_data can be the training dataset for training the machine learning model. If the training dataset is large, training_data can be its subset by applying omnixai.sampler.tabular.Sampler.subsample.

  • model – The ML model to explain, whose type can be tf.keras.Model or torch.nn.Module. When the model is for classification, the outputs of the model are the class probabilities or logits. When the model is for regression, the outputs of the model are the estimated values.

  • preprocess_function (Optional[Callable]) – The pre-processing function that converts the raw input data into the inputs of model.

  • mode (str) – The task type, e.g., classification or regression.

  • kwargs – Additional parameters to initialize the IG explainer, e.g., num_random_trials – the number of trials in generating baselines (when num_random_trials is negative, the baseline will be the mean of training_data).

explanation_type = 'local'
alias = ['ig', 'integrated_gradient']
explain(X, y=None, baseline=None, **kwargs)

Generates the explanations for the input instances.

Parameters
  • X – A batch of input instances. When X is pd.DataFrame or np.ndarray, X will be converted into Tabular automatically.

  • y – A batch of labels to explain. For regression, y is ignored. For classification, the top predicted label of each input instance will be explained when y = None.

  • baseline – The baselines for computing integrated gradients. When it is None, the baselines will be automatically generated by IntegratedGradientTabular._sample_baseline.

  • kwargs – Additional parameters, e.g., steps for IntegratedGradient.compute_integrated_gradients.

Return type

FeatureImportance

Returns

The explanations for all the input instances.

save(directory, filename=None, **kwargs)

Saves the initialized explainer.

Parameters
  • directory (str) – The folder for the dumped explainer.

  • filename (Optional[str]) – The filename (the explainer class name if it is None).

omnixai.explainers.tabular.specific.linear module

The explainable linear models.

class omnixai.explainers.tabular.specific.linear.LinearBase(mode='classification', cate_encoder=<omnixai.preprocessing.encode.OneHot object>, cont_encoder=<omnixai.preprocessing.normalize.Standard object>, target_encoder=<omnixai.preprocessing.encode.LabelEncoder object>, **kwargs)

Bases: SklearnBase

The base class for explainable linear models, e.g., linear regression and linear classification (logistic regression).

Parameters
  • mode (str) – The task type, e.g., classification or regression.

  • cate_encoder (TransformBase) – The encoder for categorical features, e.g., OneHot, Ordinal.

  • cont_encoder (TransformBase) – The encoder for continuous-valued features, e.g., Identity, Standard, MinMax, Scale.

  • target_encoder (TransformBase) – The encoder for targets/labels, e.g., Identity for regression, LabelEncoder for classification.

explanation_type = 'both'
fit(training_data, train_size=0.8, **kwargs)

Trains the model with the training dataset.

Parameters
  • training_data (Tabular) – The training dataset.

  • train_size (float) – The proportion of the training samples used in train-test splitting.

Return type

None

explain(X, y=None, **kwargs)

Generates the explanations for the input instances. The explanations are either global or local. Global explanations are the linear coefficients. Local explanations are the feature importance scores of the input instances.

Parameters
  • X (Tabular) – A batch of input instances. Global explanations are generated if X is None.

  • y (Optional[List]) – A batch of labels to explain. For regression, y is ignored. For classification, the top predicted label of each input instance will be explained when y = None.

  • kwargs – Not used.

Return type

LinearExplanation

class omnixai.explainers.tabular.specific.linear.LinearRegression(cate_encoder=<omnixai.preprocessing.encode.OneHot object>, cont_encoder=<omnixai.preprocessing.normalize.Standard object>, target_encoder=<omnixai.preprocessing.base.Identity object>, **kwargs)

Bases: LinearBase

The linear regression model based on Lasso.

Parameters
  • cate_encoder (TransformBase) – The encoder for categorical features, e.g., OneHot, Ordinal.

  • cont_encoder (TransformBase) – The encoder for continuous-valued features, e.g., Identity, Standard, MinMax, Scale.

  • target_encoder (TransformBase) – The encoder for targets/labels, e.g., Identity for regression.

alias = ['linear_regression']
class omnixai.explainers.tabular.specific.linear.LogisticRegression(cate_encoder=<omnixai.preprocessing.encode.OneHot object>, cont_encoder=<omnixai.preprocessing.normalize.Standard object>, target_encoder=<omnixai.preprocessing.encode.LabelEncoder object>, **kwargs)

Bases: LinearBase

The logistic regression model.

Parameters
  • cate_encoder (TransformBase) – The encoder for categorical features, e.g., OneHot, Ordinal.

  • cont_encoder (TransformBase) – The encoder for continuous-valued features, e.g., Identity, Standard, MinMax, Scale.

  • target_encoder (TransformBase) – The encoder for targets/labels, e.g., LabelEncoder for classification.

alias = ['logistic_regression']

omnixai.explainers.tabular.specific.decision_tree module

The explainable tree-based models.

class omnixai.explainers.tabular.specific.decision_tree.TreeBase(mode='classification', cate_encoder=<omnixai.preprocessing.encode.OneHot object>, cont_encoder=<omnixai.preprocessing.base.Identity object>, target_encoder=<omnixai.preprocessing.encode.LabelEncoder object>, **kwargs)

Bases: SklearnBase

The base class for explainable tree models, e.g., decision trees, random forests, xgboost.

Parameters
  • mode (str) – The task type, e.g., classification or regression.

  • cate_encoder (TransformBase) – The encoder for categorical features, e.g., OneHot, Ordinal.

  • cont_encoder (TransformBase) – The encoder for continuous-valued features, e.g., Identity, Standard, MinMax, Scale.

  • target_encoder (TransformBase) – The encoder for targets/labels, e.g., Identity for regression, LabelEncoder for classification.

explanation_type = 'both'
fit(training_data, train_size=0.8, **kwargs)

Trains the model with the training dataset.

Parameters
  • training_data (Tabular) – The training dataset.

  • train_size (float) – The proportion of the training samples used in train-test splitting.

Return type

None

explain(X=None, y=None, **kwargs)

Generates the explanations for the input instances. The explanations are either global or local. Global explanations are the tree structure. Local explanations are the decision paths of the input instances.

Parameters
  • X (Optional[Tabular]) – A batch of input instances. Global explanations are generated if X is None.

  • y (Optional[List]) – A batch of labels to explain. For regression, y is ignored. For classification, the top predicted label for each input instance will be explained when y = None.

Return type

TreeExplanation

class omnixai.explainers.tabular.specific.decision_tree.TreeRegressor(cate_encoder=<omnixai.preprocessing.encode.OneHot object>, cont_encoder=<omnixai.preprocessing.base.Identity object>, target_encoder=<omnixai.preprocessing.base.Identity object>, **kwargs)

Bases: TreeBase

The tree regressor based on sklearn.tree.DecisionTreeRegressor.

Parameters
  • cate_encoder (TransformBase) – The encoder for categorical features, e.g., OneHot, Ordinal.

  • cont_encoder (TransformBase) – The encoder for continuous-valued features, e.g., Identity, Standard, MinMax, Scale.

  • target_encoder (TransformBase) – The encoder for targets/labels, e.g., Identity for regression.

alias = ['tree_regressor']
class omnixai.explainers.tabular.specific.decision_tree.TreeClassifier(cate_encoder=<omnixai.preprocessing.encode.OneHot object>, cont_encoder=<omnixai.preprocessing.base.Identity object>, target_encoder=<omnixai.preprocessing.encode.LabelEncoder object>, **kwargs)

Bases: TreeBase

The tree classifier based on sklearn.tree.DecisionTreeClassifier.

Parameters
  • cate_encoder (TransformBase) – The encoder for categorical features, e.g., OneHot, Ordinal.

  • cont_encoder (TransformBase) – The encoder for continuous-valued features, e.g., Identity, Standard, MinMax, Scale.

  • target_encoder (TransformBase) – The encoder for targets/labels, e.g., LabelEncoder for classification.

alias = ['tree_classifier']

omnixai.explainers.tabular.specific.shap_tree module

The tree-specific SHAP explainer for tabular data.

class omnixai.explainers.tabular.specific.shap_tree.ShapTreeTabular(mode='classification', model=None, cate_encoder=<omnixai.preprocessing.encode.OneHot object>, cont_encoder=<omnixai.preprocessing.base.Identity object>, target_encoder=<omnixai.preprocessing.encode.LabelEncoder object>, **kwargs)

Bases: SklearnBase

The tree-specific SHAP explainer for tabular data. If using this explainer, please cite the original work: https://github.com/slundberg/shap.

Parameters
  • mode (str) – The task type, e.g. classification or regression.

  • model (Optional[Any]) – The tree-based models, e.g., scikit-learn decision trees, xgboost.

  • cate_encoder (TransformBase) – The encoder for categorical features, e.g., OneHot, Ordinal.

  • cont_encoder (TransformBase) – The encoder for continuous-valued features, e.g., Identity, Standard, MinMax, Scale.

  • target_encoder (TransformBase) – The encoder for targets/labels, e.g., LabelEncoder for classification.

  • kwargs – Additional parameters.

explanation_type = 'local'
alias = ['shap_tree']
fit(training_data, train_size=0.8, **kwargs)

Trains the model with the training dataset.

Parameters
  • training_data (Tabular) – The training dataset.

  • train_size (float) – The proportion of the training samples used in train-test splitting.

explain(X, y=None, **kwargs)

Generates the feature-importance explanations for the input instances.

Parameters
  • X (Tabular) – A batch of input instances.

  • y (Optional[List]) – A batch of labels to explain. For regression, y is ignored. For classification, the top predicted label for each input instance will be explained when y = None.

  • kwargs – Not used.

Return type

FeatureImportance