Directly Interpretable Supervised Explainers

Boolean Rules via Column Generation Explainer

class aix360.algorithms.rbm.BRCG.BRCGExplainer(model)

Boolean Rule Column Generation explainer. Provides access to aix360.algorithms.rbm.boolean_rule_cg.BooleanRuleCG, which implements a directly interpretable supervised learning method for binary classification that learns a Boolean rule in disjunctive normal form (DNF) or conjunctive normal form (CNF) using column generation (CG). AIX360 implements a heuristic beam search version of BRCG that is less computationally intensive than the published integer programming version [4].

References

[1]S. Dash, O. Günlük, D. Wei, “Boolean decision rules via column generation.” Neural Information Processing Systems (NeurIPS), 2018.

Initialize a BRCGExplainer object.

Parameters:model – model to operate on, instance of aix360.algorithms.rbm.boolean_rule_cg.BooleanRuleCG
explain(*argv, **kwargs)

Return rules comprising the underlying model.

Parameters:
  • maxConj (int, optional) – Maximum number of conjunctions to show
  • prec (int, optional) – Number of decimal places to show for floating-value thresholds
Returns:

Dictionary containing

  • isCNF (bool): flag signaling whether model is CNF or DNF
  • rules (list): selected conjunctions formatted as strings

fit(X_train, Y_train, *argv, **kwargs)

Fit model to training data.

Parameters:
  • X_train (DataFrame) – Binarized features with MultiIndex column labels
  • Y_train (array) – Binary-valued target variable
Returns:

Self

Return type:

BRCGExplainer

predict(X, *argv, **kwargs)

Predict class labels.

Parameters:X (DataFrame) – Binarized features with MultiIndex column labels
Returns:y – Predicted labels
Return type:array
set_params(*argv, **kwargs)

Set parameters for the explainer.

class aix360.algorithms.rbm.boolean_rule_cg.BooleanRuleCG(lambda0=0.001, lambda1=0.001, CNF=False, iterMax=100, K=10, D=10, B=5, eps=1e-06, solver='ECOS', verbose=False, silent=False)

BooleanRuleCG is a directly interpretable supervised learning method for binary classification that learns a Boolean rule in disjunctive normal form (DNF) or conjunctive normal form (CNF) using column generation (CG). AIX360 implements a heuristic beam search version of BRCG that is less computationally intensive than the published integer programming version [#NeurIPS2018]_.

References

[2]S. Dash, O. Günlük, D. Wei, “Boolean decision rules via column generation.” Neural Information Processing Systems (NeurIPS), 2018.
Parameters:
  • lambda0 (float, optional) – Complexity - fixed cost of each clause
  • lambda1 (float, optional) – Complexity - additional cost for each literal
  • CNF (bool, optional) – CNF instead of DNF
  • iterMax (int, optional) – Column generation - maximum number of iterations
  • K (int, optional) – Column generation - maximum number of columns generated per iteration
  • D (int, optional) – Column generation - maximum degree
  • B (int, optional) – Column generation - beam search width
  • eps (float, optional) – Numerical tolerance on comparisons
  • solver (str, optional) – Linear programming - solver
  • verbose (bool, optional) – Linear programming - verboseness
  • silent (bool, optional) – Silence overall algorithm messages
compute_conjunctions(X)

Compute conjunctions of features as specified in self.z.

Parameters:X (DataFrame) – Binarized features with MultiIndex column labels
Returns:A – Conjunction values
Return type:array
explain(maxConj=None, prec=2)

Return rules comprising the model.

Parameters:
  • maxConj (int, optional) – Maximum number of conjunctions to show
  • prec (int, optional) – Number of decimal places to show for floating-value thresholds
Returns:

Dictionary containing

  • isCNF (bool): flag signaling whether model is CNF or DNF
  • rules (list): selected conjunctions formatted as strings

fit(X, y)

Fit model to training data.

Parameters:
  • X (DataFrame) – Binarized features with MultiIndex column labels
  • y (array) – Binary-valued target variable
Returns:

Self

Return type:

BooleanRuleCG

predict(X)

Predict class labels.

Parameters:X (DataFrame) – Binarized features with MultiIndex column labels
Returns:y – Predicted labels
Return type:array

Generalized Linear Rule Model Explainer

class aix360.algorithms.rbm.GLRM.GLRMExplainer(model)

Generalized Linear Rule Model explainer. Provides access to the following directly interpretable supervised learning methods:

  • Linear Rule Regression: linear regression on rule-based features [3].
  • Logistic Rule Regression: logistic regression on rule-based features [3].

References

[3](1, 2) D. Wei, S. Dash, T. Gao, O. Günlük, “Generalized linear rule models.” International Conference on Machine Learning (ICML), 2019.

Initialize a GLRMExplainer object.

Parameters:model

model to operate on. Instance of either

explain(maxCoeffs=None, highDegOnly=False, prec=2)

Return DataFrame holding model features and their coefficients.

Parameters:
  • maxCoeffs (int, optional) – Maximum number of rules/numerical features to show
  • highDegOnly (bool, optional) – Only show higher-degree rules
  • prec (int, optional) – Number of decimal places to show for floating-value thresholds
Returns:

dfExpl – Rules/numerical features and their coefficients

Return type:

DataFrame

fit(X_train, Y_train, Xstd=None)

Fit model to training data.

Parameters:
  • X_train (DataFrame) – Binarized features with MultiIndex column labels
  • Y_train (array) – Target variable
  • Xstd (DataFrame, optional) – Standardized numerical features
Returns:

Self

Return type:

GLRMExplainer

predict(X, Xstd=None)

Predict responses.

Parameters:
  • X (DataFrame) – Binarized features with MultiIndex column labels
  • Xstd (DataFrame, optional) – Standardized numerical features
Returns:

y – Predicted responses

Return type:

array

predict_proba(X, Xstd=None)

Predict probabilities of Y=1. Only available if underlying model implements predict_proba method.

Parameters:
  • X (DataFrame) – Binarized features with MultiIndex column labels
  • Xstd (DataFrame, optional) – Standardized numerical features
Returns:

p – Predicted probabilities

Return type:

array

Raises:

ValueError – if model doesn’t implement predict_proba

set_params(*argv, **kwargs)

Set parameters for the explainer.

visualize(Xorig, fb, features=None)

Plot generalized additive model component, which includes first-degree rules and linear functions of unbinarized ordinal features but excludes higher-degree rules.

Parameters:
  • Xorig (DataFrame) – Original unbinarized features
  • fb – FeatureBinarizer object used to binarize features
  • features (list, optional) – Subset of features to be plotted
class aix360.algorithms.rbm.linear_regression.LinearRuleRegression(lambda0=0.05, lambda1=0.01, useOrd=False, debias=True, K=1, iterMax=200, B=1, wLB=0.5, stopEarly=False, eps=1e-06)

Linear Rule Regression is a directly interpretable supervised learning method that performs linear regression on rule-based features.

Parameters:
  • lambda0 (float, optional) – Regularization - fixed cost of each rule
  • lambda1 (float, optional) – Regularization - additional cost of each literal in rule
  • useOrd (bool, optional) – Also use standardized numerical features
  • debias (bool, optional) – Re-fit final solution without regularization
  • K (int, optional) – Column generation - maximum number of columns generated per iteration
  • iterMax (int, optional) – Column generation - maximum number of iterations
  • B (int, optional) – Column generation - beam search width
  • wLB (float, optional) – Column generation - weight on lower bound in evaluating nodes
  • stopEarly (bool, optional) – Column generation - stop after current degree once improving column found
  • eps (float, optional) – Numerical tolerance on comparisons
compute_conjunctions(X)

Compute conjunctions of features as specified in self.z.

Parameters:X (DataFrame) – Binarized features with MultiIndex column labels
Returns:A – Feature conjunction values, shape (X.shape[0], self.z.shape[1])
Return type:array
explain(maxCoeffs=None, highDegOnly=False, prec=2)

Return DataFrame holding model features and their coefficients.

Parameters:
  • maxCoeffs (int, optional) – Maximum number of rules/numerical features to show
  • highDegOnly (bool, optional) – Only show higher-degree rules
  • prec (int, optional) – Number of decimal places to show for floating-value thresholds
Returns:

dfExpl – Rules/numerical features and their coefficients

Return type:

DataFrame

fit(X, y, Xstd=None)

Fit model to training data.

Parameters:
  • X (DataFrame) – Binarized features with MultiIndex column labels
  • y (array) – Target variable
  • Xstd (DataFrame, optional) – Standardized numerical features
Returns:

Self

Return type:

LinearRuleRegression

predict(X, Xstd=None)

Predict responses.

Parameters:
  • X (DataFrame) – Binarized features with MultiIndex column labels
  • Xstd (DataFrame, optional) – Standardized numerical features
Returns:

yhat – Predicted responses

Return type:

array

visualize(Xorig, fb, features=None)

Plot generalized additive model component, which includes first-degree rules and linear functions of unbinarized ordinal features but excludes higher-degree rules.

Parameters:
  • Xorig (DataFrame) – Original unbinarized features
  • fb – FeatureBinarizer object used to binarize features
  • features (list, optional) – Subset of features to be plotted
class aix360.algorithms.rbm.logistic_regression.LogisticRuleRegression(lambda0=0.05, lambda1=0.01, useOrd=False, debias=True, init0=False, K=1, iterMax=200, B=1, wLB=0.5, stopEarly=False, eps=1e-06, maxSolverIter=100)

Logistic Rule Regression is a directly interpretable supervised learning method that performs logistic regression on rule-based features.

Parameters:
  • lambda0 (float, optional) – Regularization - fixed cost of each rule
  • lambda1 (float, optional) – Regularization - additional cost of each literal in rule
  • useOrd (bool, optional) – Also use standardized numerical features
  • debias (bool, optional) – Re-fit final solution without regularization
  • init0 (bool, optional) – Initialize with no features
  • K (int, optional) – Column generation - maximum number of columns generated per iteration
  • iterMax (int, optional) – Column generation - maximum number of iterations
  • B (int, optional) – Column generation - beam search width
  • wLB (float, optional) – Column generation - weight on lower bound in evaluating nodes
  • stopEarly (bool, optional) – Column generation - stop after current degree once improving column found
  • eps (float, optional) – Numerical tolerance on comparisons
  • maxSolverIter – Maximum number of logistic regression solver iterations
compute_conjunctions(X)

Compute conjunctions of features as specified in self.z.

Parameters:X (DataFrame) – Binarized features with MultiIndex column labels
Returns:A – Feature conjunction values, shape (X.shape[0], self.z.shape[1])
Return type:array
explain(maxCoeffs=None, highDegOnly=False, prec=2)

Return DataFrame holding model features and their coefficients.

Parameters:
  • maxCoeffs (int, optional) – Maximum number of rules/numerical features to show
  • highDegOnly (bool, optional) – Only show higher-degree rules
  • prec (int, optional) – Number of decimal places to show for floating-value thresholds
Returns:

dfExpl – Rules/numerical features and their coefficients

Return type:

DataFrame

fit(X, y, Xstd=None)

Fit model to training data.

Parameters:
  • X (DataFrame) – Binarized features with MultiIndex column labels
  • y (array) – Target variable
  • Xstd (DataFrame, optional) – Standardized numerical features
Returns:

Self

Return type:

LogisticRuleRegression

predict(X, Xstd=None)

Predict class labels.

Parameters:
  • X (DataFrame) – Binarized features with MultiIndex column labels
  • Xstd (DataFrame, optional) – Standardized numerical features
Returns:

yhat – Predicted labels

Return type:

array

predict_proba(X, Xstd=None)

Predict probabilities of Y=1.

Parameters:
  • X (DataFrame) – Binarized features with MultiIndex column labels
  • Xstd (DataFrame, optional) – Standardized numerical features
Returns:

p – Predicted probabilities

Return type:

array

visualize(Xorig, fb, features=None)

Plot generalized additive model component, which includes first-degree rules and linear functions of unbinarized ordinal features but excludes higher-degree rules.

Parameters:
  • Xorig (DataFrame) – Original unbinarized features
  • fb – FeatureBinarizer object used to binarize features
  • features (list, optional) – Subset of features to be plotted

Teaching Explanations for Decisions (TED) Cartesian Product Explainer

class aix360.algorithms.ted.TED_Cartesian.TED_CartesianExplainer(model)

TED is an explainability framework that leverages domain-relevant explanations in the training dataset to predict both labels and explanations for new instances [#]_. This is an implementation of the simplest instantiation of TED, called the Cartesian Product.

References

[4]Michael Hind, Dennis Wei, Murray Campbell, Noel C. F. Codella, Amit Dhurandhar, Aleksandra Mojsilovic, Karthikeyan Natesan Ramamurthy, Kush R. Varshney, “TED: Teaching AI to Explain its Decisions,” AAAI /ACM Conference on Artificial Intelligence, Ethics, and Society (AIES-19), 2019.
Parameters:model (sklearn.base.BaseEstimator) – a binary estimator for classification, i.e., it implements fit and predict.
explain(X)

Use TED-enhanced classifier to provide an explanation (E) for passed instance

Parameters:X (list of ints) – features
Returns:predicted explanation [0..MaxE]
Return type:int
fit(X, Y, E)

Train a classifier based on features (X), labels (Y), and explanations (E)

Parameters:
  • X – list of features vectors
  • Y – list of labels
  • E – list of explanations
predict(X)

Use TED-enhanced classifier to provide an prediction (Y) for passed instance

Parameters:X (list of ints) – features
Returns:predicted label {0,1}
Return type:int
predict_explain(X)

Use TED-enhanced classifier to predict label (Y) and explanation (E) for passed instance

Parameters:X (list of ints) – features
Returns:
  • Y (int) – predicted label {0,1}
  • E (int) – predicted explanation [0..MaxE]
Return type:tuple
score(X_test, Y_test, E_test)

Evaluate the accuracy (Y and E) of the TED-enhanced classifier using a test dataset

Parameters:
  • X_test (list of lists) – list of feature vectors
  • Y_test (list of int) – list of labels {0, 1}
  • E_test (list of ints) – list of explanations {0, …, NumExplanations -1}
Returns:

  • YE_accuracy – the accuracy of predictions when the labels (Y) and explanations (E) are treated as a combined label
  • Y_accuracy – the prediction accuracy for labels (Y)
  • E_accuracy – the prediction accuracy of explanations (E)

Return type:

tuple

set_params(*argv, **kwargs)

Set parameters for the explainer.