Explainability
Explainers
MLExplainer
 automl.interface.mlx. MLExplainer ( model , X , y = None , task = 'classification' , target_names = None , col_types = None , selected_features = 'auto' )

A factory method that returns either an
TabularExplainer
or anTextExplainer
, depending on the type of dataset. Parameters


model ( model object ) – The model to explain. Must implement the predict method (and the predict_proba method, if the task is classification).

X ( pandas.DataFrame , List [ str ] ) – A reference dataset drawn from the same distribution as the training dataset and the future test dataset. May be the training dataset. If the dataset type is tabular it must be a pandas DataFrame. If the dataset type is text then it can be a list of str or a pandas DataFrame with a single column and col_types must be [‘text’].

y ( pandas.Series , None ) – Dataset targets for X, if available.

task ( 'clasification' , 'regression' , 'anomaly_detection' ) – The type of machine learning task performed by the model.

target_names ( List [ str ] , None ) – A list of names for the targets. If
None
anddataset_type='tabular'
, they will be inferred fromy
, if provided. Otherwise,target_names
are required. 
col_types ( List [ str ] , None ) – List of length
X.shape[1]
with string values indicating type of features. Supported types are: [‘categorical’, ‘numerical’, ‘text’]. If ‘text’, there should only be one column inX
. 
selected_features ( 'auto' , List [ str ] , None ) – List of features/tokens that have been internally selected by the model. If the model is an AutoML pipeline and set to
'auto'
, the list will be automatically populated from the model. IfNone
, all features/tokens will be used by the explainers.

TabularExplainer
 class automl.mlx.interface. TabularExplainer ( model , X , y = None , task = 'classification' , target_names = None , col_types = None , selected_features = 'auto' )

Automatic ML model explanation object.
See
MLExplainer
for argument documentation. aggregate ( explanations )

Returns an explanation that aggregates the list of precomputed explanations.
 Parameters

explanations ( List [ automl.mlx.explanation.BaseLFIExplanation ] ) – List of at least two explanations to be summarized
 Returns

An Aggregate Local Feature Importance object (ALFI)
 Return type
 configure_explain_counterfactual ( strategy = 'auto' , dice_posthoc_sparsity_algorithm = 'binary' , dice_posthoc_sparsity_param = 0.1 , stopping_threshold = 0.5 , target_name = 'target' , target_precision = None , ** kwargs )

Configure the counterfactual explainer. If a parameter is not provided, the default value will be used. Notice that it doesn’t update the pervious provided configuration. A new CFExplainer with the current configuration will be initialized.
 Parameters


strategy ( str ) –
Determines the strategy to be used to generate counterfactuals. Currently, AutoMLx supports two strategies:  If ‘auto’: ACE will be used for classification and anomaly detection,
and DiCE for regression. (Default = ‘auto’)

If ‘ace’: AutoMLx Counterfactuals Explainer will be used. this explainer uses KDTree structures to find a set of nearby and diverse counterfactuals for each sample.

If ‘dice_random’: Diverse Counterfactual Explanations tools will be used to find the counterfactuals ( https://github.com/interpretml/DiCE ). The DiCE idea is to change features’ values randomly one by one until finding the target counterfactuals. The sparsity of the discovered counterfactuals will be enhanced by doing a binary/linear search over changed features.


dice_posthoc_sparsity_algorithm ( 'binary' , 'linear' ) – Perform either linear or binary search. Only used if strategy=’dice_random’. (Default = ‘binary’)

stopping_threshold ( float between 0.5 and 1 ) – Minimum threshold for counterfactuals target class probability. Notice: Dice has an internal error and it doesn’t support for positive
stopping_threshold < 0.5
in classification/anomaly_detection. However, it works well for regression. Only used if strategy=’dice_random’. (Default = 0.5) 
dice_posthoc_sparsity_param ( float between 0 and 1 ) – Parameter for the posthoc operation on continuous features to enhance sparsity. For each feature, the
dice_posthoc_sparsity_param
quantile of Absolute Deviations is computed and if the difference betweeen query instance and counterfactual is less than this quantile, the posthoc sparsity algorithm is executed for the corresponding feature. Only used if strategy=’dice_random’. (Default = 0.1) 
target_name ( str ) – The target’s column name. (Default = ‘target’)

target_precision ( int ) – The decimal precision of target. (Default = None)

kwargs ( dict ) –
Optional parameters passed to the DiCE Data interface. Accepted parameters are as following:
 permitted_range: dict

Dictionary with feature names as keys and permitted range in list as values. Defaults to the range inferred from training data. (Default = None)
 continuous_features_precision: dict

Dictionary with feature names as keys and precisions as values. (Default = None)
 data_name: str

Dataset name. (Default = None)

 configure_explain_feature_dependence ( explanation_type = None , encoder_type = None , ** kwargs )

Configure the Feature Dependence explainer. This configuration will be used either to specify which FD explainer is selected or/and which encoder is used for ALE explanation.
 Parameters


explanation_type ( 'pdp' , 'ale' , None ) – If ‘pdp’,
explain_feature_dependence
will use the partial dependence plot (PDP) explainer. If ‘ale’, the accumulated local effects (ALE) explainer will be used instead. If None,explain_feature_dependence
will use by default ‘pdp’ if the explainer is not configured yet, otherwise it will use the mostrecently provided. 
encoder_type ( 'distance_similarity' , 'jamesstein' , None ) – The encoder type to be used for ALE to sort categorical features. If no encoder is specified (None), ALE explainer will use ‘distance_similarity’ if the explainer is not configured yet, otherwise it will use the mostrecently used.

 configure_explain_model ( ** kwargs )

Updates one or more parameters of the model explainer. If a parameter is not provided, the mostrecently provided value from the last time configure_explain_model was called will be used. If no value has been previously provided, then the defaults will be used.
 Parameters


explanation_type ( 'interventional' , 'observational' ) –
 If ‘interventional’ (default for classification & regression),

then the explanation that is computed is as faithful to the model as possible. That is, features that are ignored by the model will not be considered important. This setting should be preferred if the primary goal is to learn about the machine learning model itself. Technically, this setting is called ‘interventional’, because the method will intervene on the data distribution when assessing the importance of features.
 If ‘observational’ (default for anomaly_detection),

then the explanation that is computed is more faithful to the dataset than the model. For example, a feature that is ignored by the model may have a nonzero feature importance if it could have been used by some model to predict the target. This setting should be preferred if the model is merely a means to learn more about the relationships that exist within the data. Technically, this setting is called ‘observational’, because it observes the relationships in the data without breaking the existing data distribution.

tabulator_type ( 'permutation' , 'kernel_shap' , 'shapley' , 'shap_pi' ) –
 If ‘permutation’ (default),

then the feature importance attributions will be calculated as in the classic feature permutation importance algorithm (assuming that explanation_type is set to ‘interventional’). Technically, this measures the importance of each feature independently from all others, and therefore it runs in linear time with respect to the number of features in the dataset.
 If ‘kernel_shap’,

then the feature importance attributions will be calculated using an approximation of the Shapley value method. Until reaching the budget of the algorithm, it will look for more coalitions. The downside is not having confidence intervals.
 If ‘shapley’,

then the feature importance attributions will be calculated using the popular gametheoretic Shapley value method. Technically, this measures the importance of each feature while includes the effect of all feature interactions. As a result, it runs in exponential time with respect to the number of features in the dataset.
 If ‘shap_pi’,

then the feature importance attributions wil be calculated using an approximation of the Shapley value method. It will run in linear time; however, because of this, it may miss the effect of the interactions between some features and may therefore produce lowerquality results. Most likely, you will notice that this method yields larger confidence intervals than the other three.

If not None, the samples will be clustered or sampled according to the provided technique. sampling is a dictionary containing the information about which technique to use and the corresponding parameters. Format is described below. (Default = None)

’technique’: Can be one of ‘kdtree’, ‘dbscan’, ‘kmeans’, ‘auto’ or ‘random’.

If ‘kdtree’, also requires:

’n_clusters’: The number of clusters (leaves) in the tree.

’n_samples’: The number of samples to return.


If ‘dbscan’, also requires:

’eps’: Maximum distance between two samples to be considered in the same cluster

’min_samples’: Minimum number of samples to include in each cluster

’fast’: if True, the dataset is downsampled first then dbscan is applied to it. Suitable for large datasets.


If ‘kmeans’, also requires:

n_clusters: The number of clusters to form.


If ‘random’, also requires:

’n_samples’: Number of samples to return




confidence_interval ( dict , None ) –
If not None, the confidence intervals will be determined according to the provided technique. confidence_interval is a dictionary containing the information about which technique to use and the corresponding parameters. Format is described below. (Default = ‘studentt’)

’technique’: Can be one of ‘studentt’, ‘bootstrap’, or ‘none’

If ‘bootstrap’, can also provide:

’n_bootstrap’: (int, ‘auto[n]’) The number of bootstrap samples. Should be an integer greater than 10 or ‘auto[n]’, where n (if provided) determines how stable the bootstrap sampling procedure will be. The default value for n is 5, greater values increase the stability. Using ‘auto[n]’ provides minimum guarantees on the stability of the intervals regardless of the confidence level.

’confidence_level’: (float, int) The confidence level of the confidence intervals. Must be in (0, 100).

’n_bootstrap_data_pools’: (int) The number of bootstrap samples taken of the data set when calculating confidence intervals.




 configure_explain_model_fairness ( ** kwargs )

Updates one or more parameters of the model fairness explainer. If a parameter is not provided, the mostrecently provided value from the last time configure_explain_model was called will be used. If no value has been previously provided, then the defaults will be used.
 Parameters


explanation_type ( 'interventional' , 'observational' ) –
 If ‘interventional’ (default),

then the explanation that is computed is as faithful to the model as possible. That is, features that are ignored by the model will not be considered important. This setting should be preferred if the primary goal is to learn about the machine learning model itself. Technically, this setting is called ‘interventional’, because the method will intervene on the data distribution when assessing the importance of features.
 If ‘observational’,

then the explanation that is computed is more faithful to the dataset than the model. For example, a feature that is ignored by the model may have a nonzero feature importance if it could have been used by some model to predict the target. This setting should be preferred if the model is merely a means to learn more about the relationships that exist within the data. Technically, this setting is called ‘observational’, because it observes the relationships in the data without breaking the existing data distribution.

tabulator_type ( 'permutation' ) –
 If ‘permutation’ (only supported value currently),

then the feature importance attributions will be calculated as in the classic feature permutation importance algorithm (assuming that explanation_type is set to ‘interventional’). Technically, this measures the importance of each feature independently from all others, and therefore it runs in linear time with respect to the number of features in the dataset.

If not None, the samples will be clustered or sampled according to the provided technique. sampling is a dictionary containing the information about which technique to use and the corresponding parameters. Format is described below. (Default = None)

’technique’: Can be one of ‘kdtree’, ‘dbscan’, ‘kmeans’, ‘auto’ or ‘random’.

If ‘kdtree’, also requires:

’n_clusters’: The number of clusters (leaves) in the tree.

’n_samples’: The number of samples to return.


If ‘dbscan’, also requires:

’eps’: Maximum distance between two samples to be considered in the same cluster

’min_samples’: Minimum number of samples to include in each cluster

’fast’: if True, the dataset is downsampled first then dbscan is applied to it. Suitable for large datasets.


If ‘kmeans’, also requires:

n_clusters: The number of clusters to form.


If ‘random’, also requires:

’n_samples’: Number of samples to return




confidence_interval ( dict , None ) –
If not None, the confidence intervals will be determined according to the provided technique. confidence_interval is a dictionary containing the information about which technique to use and the corresponding parameters. Format is described below. (Default = ‘studentt’)

’technique’: Can be one of ‘studentt’, ‘bootstrap’, or ‘none’

If ‘bootstrap’, can also provide:

’n_bootstrap’: (int, ‘auto[n]’) The number of bootstrap samples. Should be an integer greater than 10 or ‘auto[n]’, where n (if provided) determines how stable the bootstrap sampling procedure will be. The default value for n is 5, greater values increase the stability. Using ‘auto[n]’ provides minimum guarantees on the stability of the intervals regardless of the confidence level.

’confidence_level’: (float, int) The confidence level of the confidence intervals. Must be in (0, 100).

’n_bootstrap_data_pools’: (int) The number of bootstrap samples taken of the data set when calculating confidence intervals.




 configure_explain_prediction ( ** kwargs )

Updates one or more parameters of the prediction explainer. If a parameter is not provided, the mostrecently provided value from the last time configure_explain_prediction was called will be used. If no value has been previously provided, then the defaults will be used.
 Parameters


explainer_type ( 'perturbation' , 'surrogate' ) –

If ‘perturbation’ (default), then the explanation(s) will be computed by perturbing the features of the indicated data instance(s) and measuring the impact on the model predictions. Values for ‘explanation_type’, ‘tabulator_type’ and ‘confidence_interval’ will be ignored unless the ‘perturbation option is selected.

If ‘surrogate’,
then the LIMEstyle explanation(s) will be computed by fitting a surrogate model to the predictions of the original model in a small region around the indicated data instance(s) and measuring the importance of the features to the interpretable surrogate model. Only recommended for advanced users


explanation_type ( 'interventional' , 'observational' ) –
Only used if
explainer_type
is ‘perturbation’.
If ‘interventional’ (default for classification & regresion), then the explanation that is computed is as faithful to the model as possible. That is, features that are ignored by the model will not be considered important. This setting should be preferred if the primary goal is to learn about the machine learning model itself. Technically, this setting is called ‘interventional’, because the method will intervene on the data distribution when assessing the importance of features.

If ‘observational’ (default for anomaly detection), then the explanation that is computed is more faithful to the dataset than the model. For example, a feature that is ignored by the model may have a nonzero feature importance if it could have been used by some model to predict the target. This setting should be preferred if the model is merely a means to learn more about the relationships that exist within the data. Technically, this setting is called ‘observational’, because it observes the relationships in the data without breaking the existing data distribution.


tabulator_type ( 'permutation' , 'kernel_shap' , 'shapley' , 'shap_pi' ) –
Only used if explainer_type is ‘perturbation’.

If ‘permutation’ (default), then the feature importance attributions will be calculated as in the classic feature permutation importance algorithm (assuming that explanation_type is set to ‘interventional’). Technically, this measures the importance of each feature independently from all others, and therefore it runs in linear time with respect to the number of features in the dataset.

If ‘kernel_shap’, then the feature importance attributions will be calculated using an approximation of the Shapley value method. Until reaching the budget of the algorithm, it will look for more coalitions. The downside is not having confidence intervals.

If ‘shapley’, then the feature importance attributions will be calculated using the popular gametheoretic Shapley value method. Technically, this measures the importance of each feature while includes the effect of all feature interactions. As a result, it runs in exponential time with respect to the number of features in the dataset.

If ‘shap_pi’, then the feature importance attributions wil be calculated using an approximation of the Shapley value method. It will run in linear time; however, because of this, it may miss the effect of the interactions between some features and may therefore produce lowerquality results. Most likely, you will notice that this method yields larger confidence intervals than the other three.


method ( 'systematic' , 'lime' ) –
Only used if explainer_type is ‘surrogate’.

If ‘systematic’, uses an Oracle AutoMLx prioprietary method that improves the quality of LIME explanations with a systematic sampling and a custom sampling weighting technique.

If ‘lime’, uses an inhouse implementation of the traditional local modelagnostic explanations (LIME) algorithm.


If not None, the samples will be clustered or sampled according to the provided technique. sampling is a dictionary containing the information about which technique to use and the corresponding parameters. Format is described below. (Default = None)

’technique’: Can be one of ‘kdtree’, ‘dbscan’, ‘kmeans’, ‘auto’ or ‘random’.

If ‘kdtree’, also requires:

’n_clusters’: The number of clusters (leaves) in the tree.

’n_samples’: The number of samples to return.


If ‘dbscan’, also requires:

’eps’: Maximum distance between two samples to be considered in the same cluster

’min_samples’: Minimum number of samples to include in each cluster

’fast’: if True, the dataset is downsampled first then dbscan is applied to it. Suitable for large datasets.


If ‘kmeans’, also requires:

n_clusters: The number of clusters to form.


If ‘random’, also requires:

’n_samples’: Number of samples to return




confidence_interval ( dict , None ) –
If not None, the confidence intervals will be determined according to the provided technique. confidence_interval is a dictionary containing the information about which technique to use and the corresponding parameters. Format is described below. (Default = ‘studentt’)

’technique’: Can be one of ‘studentt’, ‘bootstrap’, or ‘none’

If ‘bootstrap’, can also provide:

’n_bootstrap’: (int, ‘auto[n]’) The number of bootstrap samples. Should be an integer greater than 10 or ‘auto[n]’, where n (if provided) determines how stable the bootstrap sampling procedure will be. The default value for n is 5, greater values increase the stability. Using ‘auto[n]’ provides minimum guarantees on the stability of the intervals regardless of the confidence level.

’confidence_level’: (float, int) The confidence level of the confidence intervals. Must be in (0, 100).

’n_bootstrap_data_pools’: (int) The number of bootstrap samples taken of the data set when calculating confidence intervals.




 explain_counterfactual ( X , n_counterfactuals = 1 , desired_pred = 'auto' , permitted_range = None , features_to_fix = [] , features_to_vary = None , random_seed = None , ** kwargs )

Find counterfactuals by finding a minimal set of required changes that would flip the model’s decision (i.e. to get a different outcome). Currently, it supports two strategies for creating counterfactual examples. To switch between the strategies, the explainer should be configured with the appropriate strategy:

If ‘ace’: AutoMLx Counterfactuals Explainer will be used. this explainer uses KDTree structures to find a set of nearest but diverse counterfactuals per sample. This strategy only supports ‘classification’ and ‘Anomaly Detection’ tasks.

If ‘dice_random’: Diverse Counterfactual Explanations tools will be used to find the counterfactuals ( https://github.com/interpretml/DiCE ).
 Parameters


X ( pandas.DataFrame , pandas.Series ) – Dataset for which counterfactuals are to be generated.

n_counterfactuals ( int ) – Total number of counterfactuals required. It should be greater than 0. (Default = 1)

desired_pred ( 'auto' , list , int , tuple ) –
The desired outcome class or range based on the settings. (Default = ‘auto’)

If classification / Anomaly Detection:

If a list: list of desired counterfactual class for each row of query instances.

If an int: desired counterfactual class for every query instances.

If ‘auto’: default value is ‘auto’ which is the opposite outcome class of query_instances for binary classification. However, the desired_pred value is necessary for multiclass classification.


If regression:

If a list: list of tuples, where each tuple is the outcome range to generate counterfactuals in.

If a tuple: the outcome range to generate all counterfactuals in.

If ‘auto’ or int: raise an exception saying that this value is not valid for regression.



permitted_range ( dict ) – Dictionary with feature names as keys and permitted range in list as values. For numeric features, a list of two values specifying the permitted range (inclusive), and for categorical features, a list of permitted values (e.g.
permitted_range={'age': [20, 30], 'education': ['Doctorate', 'Profschool']}
). Defaults to the range inferred from training data. (Default = None) 
features_to_fix ( list ) – A list of feature names to fix. These are immutable features. (Default = [])

features_to_vary ( list ) – A list of feature names to vary. If both
features_to_vary
andfeatures_to_fix
areNone
or both are notNone
, raise an error that just one of them should beNone
. (Default = None) 
random_seed ( int ) – Random seed for reproducibility. (Default = None)

limit_steps_ls ( int ) – Defines an upper limit for the linear search step in the
dice_posthoc_sparsity_algorithm
. (Default = 10000)

 Returns

explanations – A list of
CFExplanation
objects that contains the explanation for eachquery_instance
.  Return type
 Raises

automl.utils.exception.AutoMLxValueError – If both of the
features_to_vary
andfeatures_to_fix
parameters areNone
or none of them areNone
, or ifX
length is zero.

 explain_feature_dependence ( feature_names , feature_range = 'auto' , n_feature_values = 'auto' , X = None , y = None , sampling = None , confidence_interval = 'auto' )

Computes a Feature Dependence explanation for how the model predictions depend on the specified features.
If the explainer is configured with
explanation_type == 'pdp'
, or it’s not configured yet, a Partial Dependence Plot (PDP) explanation is computed, and an individual conditional expectation explanation (ICE) in case only one feature is provided. Otherwise, compute Accumulated Local Effects (ALE) explanation. Parameters


feature_names ( list , str , None ) – A list that contains the feature names for which the explanation is to be computed, or a single feature name. For PDP, if more than four features are provided, visualizations will not be available; however, a tabular form of the explanation will still be computed. For ALE, only twofeatures explanations are supported.

feature_range ( Tuple [ float ] , 'auto' ) – Determines the range of feature values evaluated in the explanation. If ‘auto’ is provided, use the default
(0.05, 0.95)
for PDP and(0, 1)
for ALE. The feature_range should be a sorted tuple of two floats, in[0, 1]
. The range of values of the features used is determined by taking these percentiles of the marginal distribution(s) of the feature(s). (Default ‘auto’) 
n_feature_values ( int , 'auto' ) – Max number of values to include between the feature range. If a categorical feature, selects all possible categorical values. If not an int, then it must be ‘auto’, in which case the number of values will be automatically chosen based on the number of features in order to maximize the interpretability of the explanations when plotted by show_in_notebook. (Default = ‘auto’)

X ( pandas.DataFrame , None ) – An alternate dataset for which the explanation should be computed. If not provided, the dataset used to initialize the explainer will be used instead. If provided, X must have similar columns to the original dataset that was provided. (Default = None)

If not None, the dataset will be downsampled using the indicated technique in the dictionary. Format is described below.

’technique’: Can be one of ‘kdtree’, ‘random’ or ‘kmeans’.

If ‘kdtree’, also requires:

’n_samples’: it will uniformly draw n_samples samples from the leaves of each tree.


If ‘random’, also requires:

’n_samples’: Number of samples to return


If ‘kmeans’, also requires:

’n_clusters’: Number of clusters to form

’return_centroid’: A boolean flag whether to return cluster centroids

’n_samples’: if return_centroid is False, it will uniformly draw n_samples samples from the clusters.




confidence_interval ( dict , 'auto' ) – If not ‘auto’, the confidence intervals will be determined according to the provided technique. confidence_interval is a dictionary containing the information about which technique to use and the corresponding parameters. If ‘auto’, use the default ‘studentt’ for PDP, and ‘none’ for ALE. (Default ‘auto’)

 Returns

The feature dependence explanation.
 Return type
 explain_model ( n_iter = 'auto' , scoring_metric = None )

Computes a global feature importance explanation for the model and dataset.
To configure how the explanation is computed, see
configure_explain_model
. Parameters


n_iter ( 'auto' , int ) – The number of iterations used to evaluate the global importance of the model. Increasing n_iter will require a linear increase in compute; however, it will provide more accurate importance estimates, thereby decreasing the variance in repeated calls to explain_model with identical inputs and decreasing the size of the confidence intervals. If ‘auto’, it will be determined later on based on the type of explainer.

scoring_metric ( str  callable  'auto'  None ) –
 The scoring_metric to compute explanations on.


If str, it is the name of the scoring metric.

If callable, it has to have the
scoring_metric(model, X, y)
signature. 
If ‘auto’, will default to the metric used to train the model argument.

If None, will default to the last scoring metric used or ‘auto’ if no metric was used yet.


 Returns

explanation – An explanation object that contains the global explanation.
 Return type
 explain_model_fairness ( scoring_metric = None , protected_attributes = None , supplementary_features = 'auto' , n_iter = 20 , ** fairness_kwargs )

Compute a global feature importance explanation for the model and dataset according to a fairness metric.
The first call made to explain_model_fairness() has to initialize a valid fairness metric. This can be done one of two ways:

Specifying a scoring_metric str and passing protected_attributes , with any other kwargs for the initialization taken in as a ** fairness_kwargs.

Passing a fairness scorer object as scoring_metric , without setting protected_attributes or fairness_metric_kwargs .
Input values received are stored as attributes to be reused in subsequent calls. One can always override previous values used by passing in newer values to explain_model_fairness .
To avoid any possible ambiguity, cases 1 and 2 above are mutually exclusive: one cannot have protected_attributes set and use a fairness scorer object as scoring_metric and viceversa.
 Parameters


scoring_metric ( str  callable  None ) –
 The scoring_metric to compute explanations on.


If str, it is the name of the scoring metric. Supported strings are: statistical_parity, TPR, FPR, FNR, FOR, FDF, error_rate, equalized_odds, theil_index.

If callable, it has to be a model fairness metric.

If None, will default to the last scoring metric used.


protected_attributes ( pandas.Series  numpy.ndarray  list  str ) – Array of attributes or single attribute that should be treated as protected. If an attribute is protected, then all of its unique values are considered as subgroups.

supplementary_features ( pandas.DataFrame  'auto'  None ) – Array of supplementary features for each instance. Used in case one attribute in
protected_attributes
is not contained byX
(e.g. if the protected attribute is not used by the model). Default is'auto'
, default to the last supplementary_features used, or None if no call was done before. 
n_iter ( 'auto'  int , default = 20 ) – The number of iterations used to evaluate the global importance of the model. Increasing n_iter will require a linear increase in compute; however, it will provide more accurate importance estimates, thereby decreasing the variance in repeated calls to explain_model with identical inputs and decreasing the size of the confidence intervals. If ‘auto’, it will be determined later on based on the type of explainer.

fairness_kwargs ( kwargs dict ) – Any kwarg accepted by the fairness scorer’s constructor (e.g. distance_measure ).

 Returns

explanation – An explanation object that contains the global fairness explanation.
 Return type

 explain_prediction ( X , y = None , labels = 'auto' , n_iter = 'auto' )

Reports the local explanation for the given samples by providing contribution score per feature
 Parameters


X ( pandas.DataFrame , pandas.Series ) – One or more dataset rows to be explained

y ( pandas.Series ) – Dataset target for the rows of
X
. 
labels ( 'auto' , Tuple [ int ] , int ) – If ‘auto’, the explanation will be predicted for the label with the highest probability (for a classification model). Otherwise, the index or indices of specific labels can be passed to compute the explanation with respect to those labels instead.

n_iter ( 'auto' , int ) – The number of iterations used to evaluate the importance of each of the data instances. Increasing n_iter will require a linear increase in compute; however, it will provide more accurate importance estimates, thereby decreasing the variance in repeated calls to explain_prediction with identical inputs and decreasing the size of the confidence intervals. If ‘auto’, it will be determined later on based on the type of explainer.

 Returns

explanations – A list of object that contain the local feature importance explanations, one for each instance in X.
 Return type
 explore_whatif ( X , y , train = None , target_title = None , row_index = None , features = None , max_features = 32 , x_axis = None , y_axis = None , label = None , plot_type = 'scatter' , discretization = None )

Provides UI/API to explore how a sample prediction changes by modifying the sample feature values and the relationship between feature values and the model predictions.
 Parameters


X ( pd.DataFrame ) – Data to explore

y ( list , pandas.DataFrame , or numpy.ndarray ) – Ground truth labels for
X
. 
train ( pd.DataFrame , None ) – Data used to train the ML model. (Default = None)

target_title ( str , None ) – Title of the dataset’s target. (Default = None)

row_index ( int , None ) – Index of the sample to explore. If None, the first sample in
X
is selected. (Default = None) 
features ( List [ str , int ] , None ) – Feature columns to explore. (Default = None)

max_features ( int ) – Maximum number of features to make available for modification. (Default = 32)

x_axis ( str , None ) – Feature column on xaxis. If None is provided, then the first column of X is selected. (Default = None)

y_axis ( str , None ) – Feature column or model prediction column on the yaxis. If None, model prediction column is selected. (Default = None)

label ( str , None ) – Target label to explore. (Default = None)

discretization ( str , None ) – Discretization method to apply to the xaxis if continuous. Can be chosen from [‘quartile’, ‘decile’, ‘percentile’]. If the axis’s cardinality > 100, and none of these method is selected, ‘decile’ is used. (Default = None)

plot_type ( str , None ) – Visualization plot type. Could be from [‘scatter’, ‘box’, ‘bar’] if classification or [‘scatter’, ‘box’] if regression. (Default = ‘scatter’)

 Returns

UI entry point to the explore sample tool: Two widget instances, one contains select boxes, tables, and plots to explore the sample prediction. and the other one contains a menu and plotly plot to explore the relationship between feature values and the model predictions.
 Return type

ipywidgets.widgets.VBox
TextExplainer
 class automl.mlx.interface. TextExplainer ( model , X , y = None , task = 'classification' , target_names = None , selected_tokens = None )

Automatic NLP ML model explanation object.
See
MLExplainer
for argument documentation. configure_explain_model ( ** kwargs )

Used to configure the modellevel explainer’s parameters to values other than their defaults.
 Parameters


replacement ( str , None ) – The token to use when replacing tokens in the dataset. Usually this is a token that has never been seen before by the model, e.g., ‘UNTK’. If None, unimportant tokens from the dataset will be automatically determined. (default = None)

n_tokens ( int ) – The number of tokens to evaluate in depth. A heuristic procedure is used to identify, predict and rank which tokens are most likely to be important. From those, only the top n_tokens tokens will be evaluated in depth. (default = 60)

n_iter ( int ) – The number of iterations used to evaluate the importance of each of the tokens. Increasing n_iter will require a linear increase in compute; however, it will provide more accurate importance estimates, thereby decreasing the variance in repeated call to
explain_model
with identical inputs and decreasing the size of the confidence intervals. (default = 3)

 configure_explain_prediction ( explainer_type = None , ** kwargs )

Updates one or more parameters of the prediction explainer.
 Parameters

explainer_type ( 'surrogate' , None ) –

If
None
, does not modify the currently configured explainer. 
If ‘surrogate’, then the LIMEstyle explanation(s) will be computed by fitting a surrogate model to the predictions of the original model in a small region around the indicated data instance(s) and measuring the importance of the features to the interpretable surrogate model.

 explain_model ( X = None , y = None , target = None )

Identifies what tokens are most important to the model using the Text Perturbation Importance explainer.
 Parameters


X ( List [ str ] , pandas.DataFrame ) – The dataset for which the explanations are computed.

y ( numpy.ndarray , None ) – Ground truth target values for
X
(default = None). If None, unsupervised TextPI will be activated. IfX
is None, this input will be ignored and the computation will be based on the dataset provided when the explainer was initialized. 
target ( int , None ) – Indicates the target index to be explained (default = None).

 explain_prediction ( X , y = None , labels = 'auto' )

Reports the local explanation for the given samples by providing contribution score per token
 Parameters


X ( pandas.DataFrame , pandas.Series ) – One or more dataset rows to be explained

y ( pandas.Series ) – Dataset target for the rows of
X
. 
labels ( 'auto' , Tuple [ int ] , int ) – If ‘auto’, the explanation will be predicted for the label with the highest probability (for a classification model). Otherwise, the index or indices of specific labels can be passed to compute the explanation with respect to those labels instead.

 Returns

explanations – A list of object that contain the local feature importance explanations, one for each instance in
X
.  Return type
Explaination Objects
BaseLFIExplanation
 class automl.mlx.explanation. BaseLFIExplanation ( explanation , sample , inference_time = None , task = 'classification' , explanation_type = 'tabular' , target_names = None , y_prediction = None )

Wrapper class for local feature importance based explanations (e.g., LIME, Systematic local explainer, or SHAP).
 show_in_notebook ( label = 'auto' )

Return the explanation as a plotly graph object figure for the specified target label.
 to_dataframe ( labels = None )

Return the explanation in dataframe format for the specified labels. There will be at least three columns “Feature”, “Attribution”, and “Target”, but there may also be “Upper Bound” and “Lower Bound”, which corresponds to the confidence intervals for the attributions, if they are calculated by the given method.
FDExplanation
 class automl.mlx.explanation. FDExplanation ( total_preds , mean_preds , std_preds , mean_preds_lower , mean_preds_upper , partial_feature_values , samples_per_feature , feature_names , target_names , is_categorical_feature , mode = 'classification' , explanation_type = 'pdp' , feature_distribution = None , feature_distribution_percentage_column = None , feature_priority = None , feature_correlations = None )

Feature Dependence Explanation, that is, PDP, ALE and ICE. PDP supports Nfeature partial dependence, ALE supports twofeature and ICE supports only single feature. ICE is optional, and it can be computed only alongside PDP for a single feature.
 show_in_notebook ( ice = False , labels = (0,) , prefer_widescreen = True , show_distribution = True , clip_distribution = True , force_heatmap = False , centered = False , show_median = True , sampling = {'n_clusters': 50, 'n_samples': 50, 'technique': 'kdtree'} )

Creates accumulated local effects (ALE), partial dependence plot (PDP) and individual conditional expectation (ICE) visualizations for the explanation.
An AutoMLxRuntimeError is raised if trying to visualize a PDP with more than four features, an ICE explanation with more than one feature, or an ALE with two categorical features or with more than 2 features.
 Parameters


ice ( bool ) –
Determines whether or not an ICE plot or and PD plot is returned. (Default = False)
if ice == False:
Plots a partial dependence explanation for up to four feature explanations

1 feature: Generates a line graph or bar chart over the distribution of feature values evaluated.

2 features: Depending on the cardinality of the feature grid, either generates a heat map or a colored line/bar chart over the distribution of both feature values evaluated.

3 features: Uses the same encoding strategy as with 2 features; however, the third feature is encoded by plotting multiple small versions of the plot that are horizontally or vertically aligned (using row or columnfacetting) – one for plot for each value of the third feature in the grid.

4 features: Uses the same encoding strategy as with 2 features; however, the third and fourth features are encoded by plotting multiple small versions of the plot that are both horizontally and vertically algined in a grid (using rowand columnfacetting) – one plot for each unique combination of values for the third and fourth features.
elif ice == True:
Plots an ICE plot:

Numerical features: line chart

Categorical features: violin plot


labels ( tuple of int  list of int  int ) – Index(ices) of the labels (targets) to visualize. (Default = 0)

prefer_widescreen ( bool ) – If True, the shape of the returned figure will tend to be wider than it is tall when using rowor columnfacetting for 3 and 4feature PDPs. (Default = True)

show_distribution ( bool ) – If True, a histogram of the features’ value distributions (from the provided dataset) will be shown along the corresponding axis. When plotting heatmaps, the marginal distributions of the features on the xand yaxes will be shown (conditioned on the values of any features encoded using rowor columnfacets). In all other cases joint feature distributions will be displayed. (Default = True)

clip_distribution ( bool ) – If True, then portions of the feature distributions that extend beyond the domain of the feature value grid will be clipped (although they may still be viewed by zooming out). (Default = True)

force_heatmap ( bool ) – If True, and a PDP with more than 1 feature is computed, this will force a heatmap plot. If False, a heatmap is only chosen for highcardinality data. (Default = False)

centered ( bool ) – If true, ICE plots will be centered based on the first value of each sample (i.e., all values are subtracted from the first value). (Default = False)

show_median ( bool ) – If true, a median line is included in the ICE explanation plot. (Default = True)

sampling ( dict  None ) – For all datasets of nontrivial size, plotting all of the data instances in an ICE plot produces an uninterpretable explanation due to overcrowding. Plotting too many lines at once also requires substantial time to render the figure. Therefore, by default we use a spacefilling sampling technique to sample 50 random instances to plot. However, this can be configured to use any valid sampling strategy. See automl.mlx.sample_cluster.create_down_sampler for valid options. (Default = {‘technique: ‘kdtree’, ‘n_samples’: 50})

 Returns

Plotly figure object containing a line chart, bar chart, heat map, or violin plot for this feature dependence explanation.
 Return type

plotly.graph_object.figure
 to_dataframe ( ice = False , show_median = True , centered = True , sampling = {'n_clusters': 50, 'n_samples': 100, 'technique': 'kdtree'} )

Returns a pandas DataFrame representation of the PDP, ALE or ICE explanation from this FDExplanation object. ICE is optional, and it can be set to True only if a singlefeature PDP was computed.
 Parameters


ice ( bool ) –
If ice == False, the columns contain:

Each of the feature names evaluated in this PDP/ALE.

The corresponding mean prediction from the ML model for the given feature values for each target (“Mean”).

The corresponding standard deviation of the predictions from the ML model for the given feature values (“Standard Deviation”) – only applies for PDPs.

The 95% confidence interval lower bound for the prediction from the ML model for the given feature values (“Lower Bound”).

The 95% confidence interval upper bound for the prediction from the ML model for the given feature values for each target (“Upper Bound”).

The name of the current target (“Target”)
If mode == True, the columns contain:

Each of the feature names evaluated in this ICE explanation.

A column containing the names of the targets being predicted.

The index of the data instance explained in the original dataset.

The corresponding prediction from the ML model for the given feature values, target and data index.


show_median ( bool ) – Determines whether or not the median is included in the dataframe. Only used if ice == True. Adds an additional column to the dataframe that specifies whether or not the current row corresponds to a data instance (“datum”) or the median (“median”). The “Index” column will also contain 1 for all occurences of the median.

centered ( bool ) – Determines whether or not the ICE explanation is centered. Only used if ice == True.

sampling ( dict  None ) – For all datasets of nontrivial size, plotting all of the data instances in an ICE plot produces an uninterpretable explanation due to overcrowding. Plotting too many lines at once also requires substantial time to render the figure. Therefore, by default we use a spacefilling sampling technique to sample 100 random instances to plot. However, this can be configured to use any valid sampling strategy. See automl.mlx.sample_cluster.create_down_sampler for valid options.

 Returns

Pandas DataFrame representation of the PDP/ICE or ALE explanation.
 Return type
GFIExplanation
 class automl.mlx.explanation. GFIExplanation ( feature_names = None , explanations = None , scoring_metric_name = None )

Generic wrapper class for global explanation models (e.g., PermutationImportance).
 show_in_notebook ( n_features = None , mode = 'bar' , box_points = 'suspectedoutliers' )

Generates a visualization for this global perturbationbased feature attribution explanation object.
 Parameters


n_features ( int , None ) – If n_features is not None, only show the top n_features most important features.

mode ( str ) –
Visualization mode. (Default value = ‘bar’) Can be one of:

’bar’: Returns a plotly figure object that visualizes the feature attributions using a bar chart. Each bar represents the average feature attribution from each iteration. If available, confidence intervals for the mean will be included in the plot. (default)

’box_plot’: Returns a plotly figure object that visualizes the feature attributions using a box plot of the raw feature attributions from each iteration of the algorithm. The box_points parameter can be used to further configure the visualization of the data.


box_points ( str ) –
Sets the type of BoxPlot (default = ‘suspectedoutliers’)

’suspectedoutliers’: Only shows the suspected anomalies. (default)

’outliers’: Shows all the outliers.

’all’: Shows all the points.
Only used if mode = ‘box_plot’.


 Returns

A figure containing a visualization of the explanation.
 Return type

plotly.graph_objects.Figure
 to_dataframe ( n_features = None , mode = 'normal' )

Return a representation of the explanation as a dataframe. If n_features is not None, return only the top n_features most important features.
 Parameters


n_features ( int  None ) – If n_features is not None, returns only the top n_features most important features.

mode ( 'normal'  'detailed' ) – If mode == ‘detailed’ then the dataframe contains the feature attributions from each individual iteration. Otherwise it contains the mean feature attributions and their corresponding upper and lower bounds.

 Returns

explanation – The explanation as a dataframe.
 Return type
GTIExplanation
 class automl.mlx.explanation. GTIExplanation ( tokens = None , explanations = None , target = None , target_names = None )

Generic wrapper class for text global explanation models (e.g., TextPerturbationImportance).
 Parameters


tokens ( List [ str ] ) – List of token names (e.g., [‘A..’, ‘B..’, ‘C..’]).

explanations ( List [ dict ] ) –
List (tokens within an explanation) of Dictionaries (token explanation). Explanations are in the form,:
{'token': <token_value>, 'attribution': <token_importance>, 'std': <importance_standard_deviation>, 'flat_attributions': <token_importance_per_iteration>, 'target_impact_rate': <target_based_importance>, 'target_coverage_rate': <target_coverage_rate_of_token>, 'coverage_rate': <coverage_rate_of_token>, }
For example,:
[{'token': 'B', 'attribution': 0.6', 'std': 0.4, 'flat_attributions': [0.5, 0.7, 0.6], 'target_impact_rate': 0.2, 'target_coverage_rate':0.08 , 'coverage_rate':0.1, }, {'token': 'A', 'attribution': 0.4', 'std': 0.2, 'flat_attributions': [0.6, 0.35, 0.35], 'target_impact_rate': 0.3, 'target_coverage_rate':0.1 , 'coverage_rate':0.25, }, ]

target ( int ) – Indicates the target index to be explained (Default = None).

target_names ( List [ str , int ] , None ) – List of target names corresponding to the output targets of the black box model (Default = None).

 show_in_notebook ( n_tokens = None )

Generate a modellevel explanation visualization for this explanation object.
 Parameters
 Returns

A figure that shows the relative importance of the top
n_tokens
tokens. If the explanation was computed with more than one iteration, the figure will include 95% confidence intervals for the estimates of the tokens’ importance.  Return type

plotly.graph_objs.Figure
 to_dataframe ( n_tokens = None )

Return a representation of the explanation as a dataframe. If
n_tokens
is notNone
, returns only the topn_tokens
most important tokens.
BaseALFIExplanation
 class automl.mlx.explanation. BaseALFIExplanation ( explanations , target_names , task )

Aggregate Local Feature Importance Explanation object constructed from multiple Local Explanation objects.
 show_in_notebook ( labels = None , box_points = 'all' , n_features = None )

Generate a visualization summarizing all of the individual local feature importance explanations into one single aggregate explanation.
 Parameters


labels ( tuple , list , int , None ) – Label indices to visualize. If None, all of the labels that the explanation was generated for will be visualized. (Default value = None)

box_points ( str ) –
Sets the type of box plot.

’suspectedoutliers’: Only shows the suspected anomalies.

’outliers’: Shows all the outliers.

’all’: Shows all the points. (default)
Only used for tabular explanations.


n_features ( int ) – Number of features to be visualized in aggregated explanations. If
None
, all the features will be visualized. (Default value = None)

 Returns

A visualization of the explained predictions and the explanation.
 Return type

ipywidgets.widgets.Widget
ALFIExplanation
 class automl.mlx.explanation. ALFIExplanation ( explanations , target_names , task )

 show_in_notebook ( labels = None , box_points = 'all' , n_features = None )

Generate a visualization summarizing all of the individual local feature importance explanations into one single aggregate explanation.
 Parameters


labels ( tuple , list , int , None ) – Label indices to visualize. If None, all of the labels that the explanation was generated for will be visualized. (Default value = None)

box_points ( str ) –
Sets the type of box plot.

’suspectedoutliers’: Only shows the suspected anomalies.

’outliers’: Shows all the outliers.

’all’: Shows all the points. (default)
Only used for tabular explanations.


n_features ( int ) – Number of features to be visualized in aggregated explanations. If
None
, all the features will be visualized. (Default value = None)

 Returns

A visualization of the explained predictions and the explanation.
 Return type

ipywidgets.widgets.Widget
 to_dataframe ( )

Return the aggregated explanation as a DataFrame.
 Returns

The aggregated explanation as a DataFrame.
 Return type
TextALFIExplanation
 class automl.mlx.explanation. TextALFIExplanation ( explanations , target_names , task )

 show_in_notebook ( labels = None , box_points = 'all' , n_features = None )

Generate a visualization summarizing all of the individual local feature importance explanations into one single aggregate explanation.
 Parameters


labels ( tuple , list , int , None ) – Label indices to visualize. If None, all of the labels that the explanation was generated for will be visualized. (Default value = None)

box_points ( str ) –
Sets the type of box plot.

’suspectedoutliers’: Only shows the suspected anomalies.

’outliers’: Shows all the outliers.

’all’: Shows all the points. (default)
Only used for tabular explanations.


n_features ( int ) – Number of features to be visualized in aggregated explanations. If
None
, all the features will be visualized. (Default value = None)

 Returns

A visualization of the explained predictions and the explanation.
 Return type

ipywidgets.widgets.Widget
 to_dataframe ( )

Return the aggregated explanation as a DataFrame.
 Returns

The aggregated explanation as a DataFrame.
 Return type
CFExplanation
 class automl.mlx.explanation. CFExplanation ( explanation , target_name , dataset_train , m_wrapper , method , desired_pred , category_map , task = 'classification' )

Wrapper class for counterfactual explanations.
 show_in_notebook ( interactive = True )

Generate a visualization to show a counterfactual based on WhatIF explainer. Note that
show_in_notebook
can not show diverse counterfactuals and only the first counterfactual will be shown. Parameters

interactive ( bool , default=True ) – If
True
, returns a whatif explainer to explore and change the counterfactual features values. Otherwise, returns tables and model predictions related to counterfactual.  Returns

result – one widget instance containing select boxes, tables, and plots to explore the sample counterfactual. If not interactive, it doesn’t show the select boxes that allow the user to change the counterfactual features values.
 Return type

ipywidgets.widgets.VBox
 to_dataframe ( )

Return a representation of the explanation as a dataframe.
 Returns

The explanation as a dataframe.
 Return type