Share via

ExplanationClient Class

  • Reference

Defines the client that uploads and downloads explanations.

Create the client used to interact with explanations and run history.

Inheritance
builtins.object
ExplanationClient

Constructor

ExplanationClient(service_context, experiment_name, run_id, _run=None, datastore_name=None)

Parameters

Name Description
service_context
Required
<xref:ServiceContext>

Holder for service information.
run_id
Required
str

A GUID that represents a run.
_run
Run

A run. If passed in, other args will be ignored.

Default value: None
service_context
Required
<xref:ServiceContext>

Holder for service information.
run_id
Required
str

A GUID that represents a run.
_run
Required
Run

A run. If passed in, run_id will be ignored.
datastore_name
str

Name of the datastore to use for uploads (defaults to workspace store)

Default value: None
experiment_name
Required

Methods

download_model_explanation

Download a model explanation that has been stored in run history.
from_run

Create the client with factory method given a run.
from_run_id

Create the client with factory method given a run ID.
list_model_explanations

Return a dictionary of metadata for all model explanations available.
upload_model_explanation

Upload the model explanation information to run history.

download_model_explanation

Download a model explanation that has been stored in run history.

download_model_explanation(explanation_id=None, top_k=None, comment=None, raw=None, engineered=None)

Parameters

Name Description
explanation_id
str

If specified, tries to download the asset from the run with the given explanation ID. If unspecified, returns the most recently uploaded explanation.

Default value: None
top_k
int

If specified, limit the ordered data returned to the most important features and values. If this is the case, global_importance_values and per_class_values will contain the top k sorted values instead of the usual full list of unsorted values.

Default value: None
comment
str

A string used to filter explanations based on the strings they were uploaded with. Requires an exact match. If multiple explanations share this string, the most recent will be returned.

Default value: None
raw
bool or None

If True or False, explanations will be filtered based on whether they are raw or not. If nothing is specified, this filter will not be applied.

Default value: None
engineered
bool or None

If True or False, explanations will be filtered based on whether they are engineered or not. If nothing is specified, this filter will not be applied.

Default value: None

Returns

Type Description
<xref:interpret_community.explanation.explanation.BaseExplanation>

The explanation as it was uploaded to run history

from_run

Create the client with factory method given a run.

from_run(run, datastore_name=None)

Parameters

Name Description
cls
Required
ExplanationClient

The ExplanationClient class.
run
Required
Run

The run explanations will be attached to.
datastore_name
str

Name of the datastore to use for uploads (defaults to workspace store)

Default value: None

Returns

Type Description
ExplanationClient

An instance of the ExplanationClient.

from_run_id

Create the client with factory method given a run ID.

from_run_id(workspace, experiment_name, run_id, datastore_name=None)

Parameters

Name Description
cls
Required
ExplanationClient

The ExplanationClient class.
workspace
Required
Workspace

An object that represents a workspace.
experiment_name
Required
str

The name of an experiment.
run_id
Required
str

A GUID that represents a run.
datastore_name
str

Name of the datastore to use for uploads (defaults to workspace store)

Default value: None

Returns

Type Description
ExplanationClient

An instance of the ExplanationClient.

list_model_explanations

Return a dictionary of metadata for all model explanations available.

list_model_explanations(comment=None, raw=None, engineered=None)

Parameters

Name Description
comment
str

A string used to filter explanations based on the strings they were uploaded with. Requires an exact match.

Default value: None
raw
bool or None

If True or False, explanations will be filtered based on whether they are raw or not. If nothing is specified, this filter will not be applied.

Default value: None
engineered
bool or None

If True or False, explanations will be filtered based on whether they are engineered or not. If nothing is specified, this filter will not be applied.

Default value: None

Returns

Type Description
dict

A dictionary of explanation metadata such as id, data type, explanation method, model type, and upload time, sorted by upload time

upload_model_explanation

Upload the model explanation information to run history.

upload_model_explanation(explanation, max_num_blocks=None, block_size=None, top_k=None, comment=None, init_dataset_id=None, eval_dataset_id=None, ys_pred_dataset_id=None, ys_pred_proba_dataset_id=None, upload_datasets=False, model_id=None, true_ys=None, visualization_points=5000) -> None

Parameters

Name Description
explanation
Required
<xref:interpret_community.explanation.explanation.BaseExplanation>

The explanation information to save.
max_num_blocks
int

The maximum number of blocks to store.

Default value: None
block_size
int

The size of each block for the summary stored in artifacts storage.

Default value: None
top_k
int

Number of important features stored in the explanation. If specified, only the names and values corresponding to the top K most important features will be returned/stored. If this is the case, global_importance_values and per_class_values will contain the top k sorted values instead of the usual full list of unsorted values.

Default value: None
comment
str

An optional string to identify the explanation. The string is displayed when listing explanations, which allows identification of uploaded explanations.

Default value: None
init_dataset_id
str

The ID of the initialization (background) dataset in the Dataset service, if available. Used to link the explanation to the Dataset.

Default value: None
eval_dataset_id
str

The ID of the evaluation dataset in the Dataset service, if available. Used to link the explanation to the Dataset.

Default value: None
ys_pred_dataset_id
str

The ID of the predicted values dataset in the Dataset service, if available.

Default value: None
ys_pred_proba_dataset_id
str

The ID of the predicted probability values dataset in the Dataset service, if available.

Default value: None
upload_datasets
bool

If set to True and no dataset IDs are passed in, the evaluation dataset will be uploaded to Azure storage as a Dataset object. This will allow the explanation to be linked to the Dataset in the web view.

Default value: False
model_id
str

The MMS model ID.

Default value: None
true_ys
list | <xref:pandas.Dataframe> | ndarray

The true labels for the evaluation examples.

Default value: None
visualization_points
int or list[int]

If set to an integer, this is the upper bound on the number of points that will be available for visualization in the web UI. If set to a list of integers, these integers will be used as indices for selecting a sample of points (original data and explanations) to be visualized in the web UI. If not planning to view the explanation in the web UI, this parameter can be set to 0 and no extra computation or storage will take place.

The upper limit for either the integer or the length of the list is currently 20000 (twenty thousand). In the case that a larger integer or longer list is passed in, the function will fail. The intention is to limit the amount of data entering the web UI for performance reasons. With more evaluation, this limit may be raised.

Default value: 5000

Attributes

run

Get the run from the explanation client.

Returns

Type Description
Run

The run object.