mindspore_xai.runner

Provides explanation runner high-level APIs.

class mindspore_xai.runner.ImageClassificationRunner(summary_dir, data, network, activation_fn)

A high-level API for users to generate and store results of the explanation methods and the evaluation methods.

Update in 2020.11: Adjust the storage structure and format of the data. Summary files generated by previous version will be deprecated and will not be supported in MindInsight of current version.

Parameters

• summary_dir (str) – The directory path to save the summary files which store the generated results.

• data (tuple[Dataset, list[str]]) – Tuple of dataset and the corresponding class label list. The dataset should provides [images], [images, labels] or [images, labels, bboxes] as columns. The label list must share the exact same length and order of the network outputs.

• network (Cell) – The network(with logit outputs) to be explained.

• activation_fn (Cell) – The activation layer that transforms logits to prediction probabilities. For single label classification tasks, nn.Softmax is usually applied. As for multi-label classification tasks, nn.Sigmoid is usually be applied. Users can also pass their own customized activation_fn as long as when combining this function with network, the final output is the probability of the input.

Raises

TypeError – Be raised for any argument type problem.

Supported Platforms:

Ascend GPU

Examples

>>> from mindspore.nn import Softmax
>>> from mindspore import context, load_checkpoint, load_param_into_net
>>> from mindspore_xai.runner import ImageClassificationRunner
>>> from mindspore_xai.explanation import GuidedBackprop, Gradient
>>> from mindspore_xai.benchmark import Faithfulness
>>>
>>> context.set_context(mode=context.PYNATIVE_MODE)
>>> # The detail of AlexNet is shown in model_zoo.official.cv.alexnet.src.alexnet.py
>>> net = AlexNet(10)
>>> # Load the checkpoint
>>> param_dict = load_checkpoint("/path/to/checkpoint")
>>> load_param_into_net(net, param_dict)
[]
>>>
>>> # Prepare the dataset for explaining and evaluation.
>>> # The detail of create_dataset_cifar10 method is shown in model_zoo.official.cv.alexnet.src.dataset.py
>>>
>>> dataset = create_dataset_cifar10("/path/to/cifar/dataset", 1)
>>> labels = ['airplane', 'automobile', 'bird', 'cat', 'deer', 'dog', 'frog', 'horse', 'ship', 'truck']
>>>
>>> activation_fn = Softmax()
>>> gbp = GuidedBackprop(net)
>>> gradient = Gradient(net)
>>> explainers = [gbp, gradient]
>>> faithfulness = Faithfulness(len(labels), activation_fn, "NaiveFaithfulness")
>>> benchmarkers = [faithfulness]
>>>
>>> runner = ImageClassificationRunner("./summary_dir", (dataset, labels), net, activation_fn)
>>> runner.register_saliency(explainers=explainers, benchmarkers=benchmarkers)
>>> runner.run()

register_hierarchical_occlusion()

Register hierarchical occlusion instances.

Warning

This function can not be invoked more than once on each runner.

Note

Input images are required to be in 3 channels formats and the length of side short must be equals to or greater than 56 pixels. This function can not be invoked more than once on each runner.

Raises

• ValueError – Be raised for any data or settings’ value problem.

• RuntimeError – Be raised if the function was called already.

register_saliency(explainers, benchmarkers=None)

Register saliency explanation instances.

Warning

This function can not be invoked more than once on each runner.

Parameters

• explainers (list[Attribution]) – The explainers to be evaluated, see mindspore_xai.explanation. All explainers’ class must be distinct and their network must be the exact same instance of the runner’s network.

• benchmarkers (list[AttributionMetric], optional) – The benchmarkers for scoring the explainers, see mindspore_xai.benchmark. All benchmarkers’ class must be distinct.

Raises

• ValueError – Be raised for any data or settings’ value problem.

• TypeError – Be raised for any data or settings’ type problem.

• RuntimeError – Be raised if this function was invoked before.

register_uncertainty()

Register uncertainty instance to compute the epistemic uncertainty base on the Bayes’ theorem.

Warning

This function can not be invoked more than once on each runner.

Note

Please refer to the documentation of mindspore.nn.probability.toolbox.uncertainty_evaluation for the details. The actual output is standard deviation of the classification predictions and the corresponding 95% confidence intervals. Users have to invoke register_saliency() as well for the uncertainty results are going to be shown on the saliency map page in MindInsight. This function can not be invoked more then once on each runner.

Raises

RuntimeError – Be raised if the function was called already.

run()

Run the explain job and save the result as a summary in summary_dir.

Note

User should call register_saliency() once before running this function.

Raises

• ValueError – Be raised for any data or settings’ value problem.

• TypeError – Be raised for any data or settings’ type problem.

• RuntimeError – Be raised for any runtime problem.