mindspore_xai.benchmark

预定义的XAI指标。

class mindspore_xai.benchmark.ClassSensitivity[源代码]

类敏感度（ClassSensitivity）用于度量归因类的解释器。

合理的归因类解释器应为不同标签生成不同的热力图，特别是对”高置信度”和”低置信度”的标签，类敏感度通过计算这两种标签之间的热力图相关性来评估解释器，类敏感度较好的解释器将获得较低的相关性分数。而为了使评估结果直观，返回的分数将取相关性的负值并归一化。

支持平台：: Ascend GPU

evaluate(explainer, inputs)[源代码]

评估解释器的类敏感度。

Note

目前，每个调用仅支持单个样本（ \(N=1\) ）。

参数：

explainer (Explainer) - 要评估的解释器，请参见 mindspore_xai.explainer 。
inputs (Tensor) - 数据样本，shape为 \((N, C, H, W)\) 的4D Tensor。

返回：

numpy.ndarray，shape为 \((N,)\) 的1D数组，为 explainer 的类敏感度评估结果。

异常：

TypeError - 参数或输入类型错误。
ValueError - \(N\) 不是1。

样例：

>>> import numpy as np
>>> import mindspore as ms
>>> from mindspore import set_context, PYNATIVE_MODE
>>> from mindspore_xai.benchmark import ClassSensitivity
>>> from mindspore_xai.explainer import Gradient
>>>
>>> set_context(mode=PYNATIVE_MODE)
>>> # The detail of LeNet5 is shown in model_zoo.official.cv.lenet.src.lenet.py
>>> net = LeNet5(10, num_channel=3)
>>> # prepare your explainer to be evaluated, e.g., Gradient.
>>> gradient = Gradient(net)
>>> input_x = ms.Tensor(np.random.rand(1, 3, 32, 32), ms.float32)
>>> class_sensitivity = ClassSensitivity()
>>> res = class_sensitivity.evaluate(gradient, input_x)
>>> print(res.shape)
(1,)

class mindspore_xai.benchmark.Faithfulness(num_labels, activation_fn, metric='NaiveFaithfulness')[源代码]

评估XAI解释的忠实度（Faithfulness）。

支持三个量化指标：”NaiveFaithfulness”，”DeletionAUC” 和 “InsertionAUC”。

“NaiveFaithfulness”指标是通过修改原始图像上的像素来创建一系列扰动图像，把这些图像输入模型會令预测概率下降，而在概率下降和热力图数值两者之间的相关性便是忠实度数值，最后我们会归一化相关性，使它们在[0, 1]的范围内。

“DeletionAUC”指标是通过将原始图像的像素累积地修改为基本数值，例如用一个常数，来创建一系列扰动图像，扰动会從高显著值的像素開始再到低显著值的像素，并将这些图像按顺序输入到模型，从而得到输出概率的下降曲线，”DeletionAUC”为该曲线下的面积。

“InsertionAUC”指标是通过将原始图像的像素累积地插入参考图像，例如用黑色图像，来创建一系列扰动图像，插入会从高显着值的像素开始再到低显着值的像素，并将这些图像按顺序输入到模型，从而得到输出概率的增长曲线，”InsertionAUC”为该曲线下的面积。

对于这三个指标，值越高表示忠诚度越高。

参数：

num_labels (int) - 标签的数量。
activation_fn (Cell) - 将logits转换为预测概率的激活层。单标签分类任务通常使用 nn.Softmax ，而多标签分类任务较常使用 nn.Sigmoid 。用户也可以将自定义的 activation_fn 与网络结合，而最终的输出便是输入的概率。
metric (str, 可选) - 量化忠诚度的特定指标。可选项：”DeletionAUC”，”InsertionAUC”，”NaiveFaithfulness”。默认值：”NaiveFaithfulness”。

异常：

TypeError - 参数或输入类型错误。

支持平台：: Ascend GPU

evaluate(explainer, inputs, targets, saliency=None)[源代码]

评估解释器的忠诚度。

Note

目前，每个调用仅支持单个样本（ \(N=1\) ）。

参数：

explainer (Explainer) - 要评估的解释器，请参见 mindspore_xai.explainer 。
inputs (Tensor) - 数据样本，shape为 \((N, C, H, W)\) 的4D Tensor。
targets (Tensor, int) - 目标分类，1D/Scalar Tensor或integer。如果 targets 是1D Tensor，其长度应为 \(N\) 。
saliency (Tensor, 可选) - 要评估的热力图，shape为 \((N, 1, H, W)\) 的4D Tensor。如果设置为 None ，解析后的 explainer 将生成具有 inputs 和 targets 的热力图，并继续评估。默认值：None。

返回：

numpy.ndarray，shape为 \((N,)\) 的1D数组，为 explainer 的忠实度评估结果。

异常：

TypeError - 参数或输入类型错误。
ValueError - \(N\) 不是1。

样例：

>>> import numpy as np
>>> import mindspore as ms
>>> from mindspore import nn, set_context, PYNATIVE_MODE
>>> from mindspore_xai.benchmark import Faithfulness
>>> from mindspore_xai.explainer import Gradient
>>>
>>> set_context(mode=PYNATIVE_MODE)
>>> # init a `Faithfulness` object
>>> num_labels = 10
>>> metric = "InsertionAUC"
>>> activation_fn = nn.Softmax()
>>> faithfulness = Faithfulness(num_labels, activation_fn, metric)
>>> # The detail of LeNet5 is shown in model_zoo.official.cv.lenet.src.lenet.py
>>> net = LeNet5(10, num_channel=3)
>>> gradient = Gradient(net)
>>> inputs = ms.Tensor(np.random.rand(1, 3, 32, 32), ms.float32)
>>> targets = 5
>>> # usage 1: input the explainer and the data to be explained,
>>> # faithfulness is a Faithfulness instance
>>> res = faithfulness.evaluate(gradient, inputs, targets)
>>> print(res.shape)
(1,)
>>> # usage 2: input the generated saliency map
>>> saliency = gradient(inputs, targets)
>>> res = faithfulness.evaluate(gradient, inputs, targets, saliency)
>>> print(res.shape)
(1,)

class mindspore_xai.benchmark.Localization(num_labels, metric='PointingGame')[源代码]

评估XAI方法的定位性（Localization）能力。

支持两个量化指标：”PointingGame” 和 “IoSR”（显著区域的相交）。

“PointingGame”指标会计算热力图峰值位置位于边界框内的比例。具体来说，如果单个样本的热力图的峰值位置位于边界框内，结果为1，否则为0。

“IoSR”指标是边界框和显着区域的相交面积除以显着区域面积。显着区域是指显着值高于 \(\theta * \max{saliency}\)。

参数：

num_labels （int） - 数据集中的类数。
metric （str，可选） - 计算定位性能力的特定指标。可选项：”PointingGame”和”IoSR”。默认值：”PointingGame”。

异常：

TypeError - 参数或输入类型错误。

支持平台：: Ascend GPU

evaluate(explainer, inputs, targets, saliency=None, mask=None)[源代码]

评估解释器的定位性。

Note

目前，每个调用仅支持单个样本（ \(N=1\) ）。

参数：

explainer (Explainer) - 要评估的解释器，请参见 mindspore_xai.explainer 。
inputs (Tensor) - 数据样本，shape为 \((N, C, H, W)\) 的4D Tensor。
targets (Tensor, int) - 目标分类，1D/Scalar Tensor或integer。如果 targets 是1D Tensor，其长度应为 \(N\) 。
saliency (Tensor, 可选) - 要评估的热力图，shape为 \((N, 1, H, W)\) 的4D Tensor。如果设置为 None ，解析后的 explainer 将生成具有 inputs 和 targets 的热力图，并继续评估。默认值： None 。
mask (Tensor,numpy.ndarray) - 基于 targets 给于 inputs 的ground truth边界框/掩码，4D Tensor或shape为 \((N, 1, H, W)\) 的 numpy.ndarray 。默认值： None 。

返回：

numpy.ndarray，shape为 \((N,)\) 的1D数组，为 explainer 的定位性评估结果。

异常：

TypeError - 参数或输入类型错误。
ValueError - \((N,)\) 不是1。

样例：

>>> import numpy as np
>>> import mindspore as ms
>>> from mindspore import set_context, PYNATIVE_MODE
>>> from mindspore_xai.explainer import Gradient
>>> from mindspore_xai.benchmark import Localization
>>>
>>> set_context(mode=PYNATIVE_MODE)
>>> num_labels = 10
>>> localization = Localization(num_labels, "PointingGame")
>>>
>>> # The detail of LeNet5 is shown in model_zoo.official.cv.lenet.src.lenet.py
>>> net = LeNet5(10, num_channel=3)
>>> gradient = Gradient(net)
>>> inputs = ms.Tensor(np.random.rand(1, 3, 32, 32), ms.float32)
>>> masks = np.zeros([1, 1, 32, 32])
>>> masks[:, :, 10: 20, 10: 20] = 1
>>> targets = 5
>>> # usage 1: input the explainer and the data to be explained,
>>> # localization is a Localization instance
>>> res = localization.evaluate(gradient, inputs, targets, mask=masks)
>>> print(res.shape)
(1,)
>>> # usage 2: input the generated saliency map
>>> saliency = gradient(inputs, targets)
>>> res = localization.evaluate(gradient, inputs, targets, saliency, mask=masks)
>>> print(res.shape)
(1,)

class mindspore_xai.benchmark.Robustness(num_labels, activation_fn)[源代码]

鲁棒性 (Robustness) 通过添加随机噪音来扰动输入，并从扰动中选择最大灵敏度作为评估分数。

参数：

num_labels (int) - 数据集中的类数。
activation_fn (Cell) - 将logits转换为预测概率的激活层。单标签分类任务通常使用 nn.Softmax ，而多标签分类任务较常使用 nn.Sigmoid 。用户也可以将自定义的 activation_fn 与网络结合，最终的输出便是输入的概率。

异常：

TypeError - 参数或输入类型错误。

支持平台：: Ascend GPU

evaluate(explainer, inputs, targets, saliency=None)[源代码]

评估解释器的鲁棒性。

Note

目前，每个调用仅支持单个样本（ \(N=1\) ）。

参数：

explainer (Explainer) - 要评估的解释器，请参见 mindspore_xai.explainer 。
inputs (Tensor) - 数据样本，shape为 \((N, C, H, W)\) 的4D Tensor。
targets (Tensor, int) - 目标分类，1D/Scalar Tensor或integer。如果 targets 是1D Tensor，其长度应为 \(N\)。
saliency (Tensor, 可选) - 要评估的热力图，shape为 \((N, 1, H, W)\) 的4D Tensor。如果设置为 None ，解析后的 explainer 将生成具有 inputs 和 targets 的热力图，并继续评估。默认值： None 。

返回：

numpy.ndarray，shape为 \((N,)\) 的1D数组，为 explainer 的鲁棒性评估结果。

异常：

TypeError - 参数或输入类型错误。
ValueError - \(N\) 不是1。

样例：

>>> import numpy as np
>>> import mindspore as ms
>>> from mindspore import nn, set_context, PYNATIVE_MODE
>>> from mindspore_xai.explainer import Gradient
>>> from mindspore_xai.benchmark import Robustness
>>>
>>> set_context(mode=PYNATIVE_MODE)
>>> # Initialize a Robustness benchmarker passing num_labels of the dataset.
>>> num_labels = 10
>>> activation_fn = nn.Softmax()
>>> robustness = Robustness(num_labels, activation_fn)
>>>
>>> # The detail of LeNet5 is shown in model_zoo.official.cv.lenet.src.lenet.py
>>> net = LeNet5(10, num_channel=3)
>>> # prepare your explainer to be evaluated, e.g., Gradient.
>>> gradient = Gradient(net)
>>> input_x = ms.Tensor(np.random.rand(1, 3, 32, 32), ms.float32)
>>> target_label = ms.Tensor([0], ms.int32)
>>> # robustness is a Robustness instance
>>> res = robustness.evaluate(gradient, input_x, target_label)
>>> print(res.shape)
(1,)