diff --git a/tutorials/training/source_en/advanced_use/images/xai_hoc.png b/tutorials/training/source_en/advanced_use/images/xai_hoc.png new file mode 100644 index 0000000000000000000000000000000000000000..be490bc16606c67dce39a96bb335af1d09583bc0 Binary files /dev/null and b/tutorials/training/source_en/advanced_use/images/xai_hoc.png differ diff --git a/tutorials/training/source_en/advanced_use/images/xai_hoc_index.png b/tutorials/training/source_en/advanced_use/images/xai_hoc_index.png new file mode 100644 index 0000000000000000000000000000000000000000..c8bec0336bd41ff2282630259905cdee44beb414 Binary files /dev/null and b/tutorials/training/source_en/advanced_use/images/xai_hoc_index.png differ diff --git a/tutorials/training/source_en/advanced_use/images/xai_index.png b/tutorials/training/source_en/advanced_use/images/xai_index.png index bb70bf262fed8e3bee441088d2a95df6f2c143a3..d0b10a87c216d64f1af0fcdf9192f6e666e940c7 100644 Binary files a/tutorials/training/source_en/advanced_use/images/xai_index.png and b/tutorials/training/source_en/advanced_use/images/xai_index.png differ diff --git a/tutorials/training/source_en/advanced_use/images/xai_metrix_comprehensive.png b/tutorials/training/source_en/advanced_use/images/xai_metrix_comprehensive.png index 8afba4b4ed4d7bb05d1d3995b74d21581666b331..c94c001eccdf005b36c814b0dbacb0f3dd831e7e 100644 Binary files a/tutorials/training/source_en/advanced_use/images/xai_metrix_comprehensive.png and b/tutorials/training/source_en/advanced_use/images/xai_metrix_comprehensive.png differ diff --git a/tutorials/training/source_en/advanced_use/images/xai_saliency_map.png b/tutorials/training/source_en/advanced_use/images/xai_saliency_map.png index d8577f04d815027ceeb401b3a936fac84ac75aa8..43bd72adb1ba329536ff07a950d87aa619bba27d 100644 Binary files a/tutorials/training/source_en/advanced_use/images/xai_saliency_map.png and b/tutorials/training/source_en/advanced_use/images/xai_saliency_map.png differ diff --git a/tutorials/training/source_en/advanced_use/images/xai_saliency_map_detail.png b/tutorials/training/source_en/advanced_use/images/xai_saliency_map_detail.png index eefe66391b395af0cfb54d20ef40f753b57011bd..a9df098a81a7b3aa93353e613901a7785cdc6cc2 100644 Binary files a/tutorials/training/source_en/advanced_use/images/xai_saliency_map_detail.png and b/tutorials/training/source_en/advanced_use/images/xai_saliency_map_detail.png differ diff --git a/tutorials/training/source_en/advanced_use/model_explaination.md b/tutorials/training/source_en/advanced_use/model_explaination.md index f5b14a8f8baac022abbea074fa9f385e98b08dc1..8f6c0b79af5967902efbe320b26ca244707ae8a0 100644 --- a/tutorials/training/source_en/advanced_use/model_explaination.md +++ b/tutorials/training/source_en/advanced_use/model_explaination.md @@ -1,6 +1,6 @@ # Explain Models -`Linux` `Ascend` `GPU` `Model Optimization` `Beginner` `Intermediate` `Expert` +`Linux` `Ascend` `GPU` `Model Optimization` `Beginner` `Intermediate` `Expert` `Counterfactual` @@ -15,6 +15,10 @@ - [Explanation Method Assessment](#explanation-method-assessment) - [Comprehensive Assessment](#comprehensive-assessment) - [Classification Assessment](#classification-assessment) + - [Counterfactual](#counterfactual) + - [Hierarchical Occlusion](#hierarchical-occlusion-counterfactual-hoc) + - [Restrictions](#hoc-restrictions) + - [Pages and Functions](#hoc-pages-and-functions) @@ -92,7 +96,7 @@ runner.run() ### Restrictions -- Only support CNN of image classification models, such as Lenet, Resnet, Alexnet. +- Only support image classification models, such as Lenet, Resnet, Alexnet. - Only support PyNative mode. - All instances of explanation and evaluation methods cannot be reused across runners. Explanation and evaluation methods have to be instantiated exclusively for each runner. Otherwise, errors may occur. A correct example is shown below. @@ -142,10 +146,11 @@ Operations: 1. Select the required explanation methods. Currently, we support four explanation methods. More explanation methods will be provided in the future. 2. Click **Overlay on Original Image** in the upper right corner of the page to overlay the saliency map on the original image. 3. Click different tags to display the saliency map analysis results of the model for different tags. For different classification results, the focus of the model is usually different. -4. Use the tag filtering function on the upper part of the page to filter out images with specified tags. -5. Select an image display sequence from **Sort Images By** in the upper right corner of the page. -6. Click **View Score** on the right of an explanation method. The page for assessing all explanation methods is displayed. -7. Click image you will see the higher resolution image. +4. Check prediction type checkboxes to display images with the checked tag types: TP - true positive, FN - false negative, FP - false positive. +5. Use the tag filtering function on the upper part of the page to filter out images with specified tags. +6. Select an image display sequence from **Sort Images By** in the upper right corner of the page. +7. Click **View Score** on the right of an explanation method. The page for assessing all explanation methods is displayed. +8. Click image you will see the higher resolution image. ![xai_saliency_map_detail](./images/xai_saliency_map_detail.png) @@ -162,3 +167,49 @@ The provided explanation methods are scored from different dimensions. We provid The classification assessment page provides two types of comparison. One is to compare scores of different evaluation dimensions of the same explanation method in each tag. The other is to compare scores of different explanation methods of the same evaluation dimension in each tag. ![xai_metrix_class](./images/xai_metrix_class.png) + +## Counterfactual + +Counterfactual is a relatively new ways of explaining a model's decision, which comes with various form. Currently ImageClassificationRunner provides an easy to use method called Hierarchical Occlusion Counterfactual (HOC), more counterfactual methods will be added in the future. + +### Hierarchical Occlusion Counterfactual (HOC) + +HOC is an occlusion based method, it search for the smallest possible display region that subjected to the constraint of target label's prediction confidence greater than a threshold (currently fixed at 0.5). The search process is conducted in a hierarchical manner, at the beginning, the original image was covered by it's blurred version, then search with large occlusion areas and recursively deep down into smaller areas for a more accurate result. It ends up with a area tree, each node represents a square display area and the smaller children area is fall inside the parent. The root node represents the original image, it's immediate children is the first layer of display areas. + +At the moment, ImageClassificationRunner automatically generates the number of layers (1 to 3), the sizes of occluded areas, the strides and the blur mask base on the dimensions of images. The side length of the first layer occlusion square is defined as the round down of half of the short side of the image, we cut the side length in half in every next layer. Meanwhile, the side length has to be equals to or greater than 28, otherwise, stop adding layers. The stride is the round down of 1/5 of the occluded area's side length. + +The preparation of network and data is same as the saliency explanation methods, users employ HOC by invoking register_hierarchical_occlusion() of ImageClassificiationRunner, a piece of sample code is shown below. + +```python +runner = ImageClassificationRunner(summary_dir='./summary_dir_1', network=net, activation_fn=activation_fn, data=data) +runner.register_hierarchical_occlusion() +runner.run() +``` + +Users may combine the use of register_saliency() with the same runner. + +#### HOC Restrictions + +- All restrictions from saliency explanation methods, but models must be taking 3 channels input images. +- Input image must be in RGB 3 channels format and the length of short side must be equals to or greater than 56. + +#### HOC Pages and Functions + +You can see that the 'Counterfactual Explanation' operations are enabled for those explain jobs employed HOC. Clicking it will lead you to the HOC explanation page. + +![xai_hoc_index](./images/xai_hoc_index.png) + +The HOC explanation page displays all HOC results, includes: + +- Samples with prediction confidence of any tag that greater than 0.5 and their original images. +- Prediction confidence of the target tags. +- The outcome images and their prediction confidences of each layer. + +![xai_hoc](./images/xai_hoc.png) + +Operations: + +1. Change the tag filter and sampler sorting on the left panel. Samples can be sorted by prediction confidence. +2. Browse samples or switch to next page in the sample list inside the left panel. Select a sample than it's HOC results will be shown on the other panels. +3. Change the tag of HOC result of showing on the center panel. Only tags with prediction confidence greater than 0.5 have HOC result. +4. Inspect the HOC search process on the bottom panel, select a step image then it's enlarged version will be shown on the right panel. (Notes: The occluded regions were darkened and converted to greyscale for display, but it is not the case in the actual HOC search process, only Gaussian blur is employed while brightness and saturation is not altered.) diff --git a/tutorials/training/source_zh_cn/advanced_use/images/xai_hoc.png b/tutorials/training/source_zh_cn/advanced_use/images/xai_hoc.png new file mode 100644 index 0000000000000000000000000000000000000000..ee1a451c4015c0a5fcbc1915e744f6d9bf4214ff Binary files /dev/null and b/tutorials/training/source_zh_cn/advanced_use/images/xai_hoc.png differ diff --git a/tutorials/training/source_zh_cn/advanced_use/images/xai_hoc_index.png b/tutorials/training/source_zh_cn/advanced_use/images/xai_hoc_index.png new file mode 100644 index 0000000000000000000000000000000000000000..ca6eee818f2d37ffe5677ea4e8127482cfab0a64 Binary files /dev/null and b/tutorials/training/source_zh_cn/advanced_use/images/xai_hoc_index.png differ diff --git a/tutorials/training/source_zh_cn/advanced_use/images/xai_index.png b/tutorials/training/source_zh_cn/advanced_use/images/xai_index.png index 9920e78fa3efd87c05236f2781e1a51a182f2635..31ee4cb7d7bc3f3a1a366cf5d6ee1365a29d3cbf 100644 Binary files a/tutorials/training/source_zh_cn/advanced_use/images/xai_index.png and b/tutorials/training/source_zh_cn/advanced_use/images/xai_index.png differ diff --git a/tutorials/training/source_zh_cn/advanced_use/images/xai_metrix_comprehensive.png b/tutorials/training/source_zh_cn/advanced_use/images/xai_metrix_comprehensive.png index 563059dbb4d95ca6ac7b825c92315af31cd07bc7..c266ad77f5ea2cf0e7a124e4fb60a4f133afa0a7 100644 Binary files a/tutorials/training/source_zh_cn/advanced_use/images/xai_metrix_comprehensive.png and b/tutorials/training/source_zh_cn/advanced_use/images/xai_metrix_comprehensive.png differ diff --git a/tutorials/training/source_zh_cn/advanced_use/images/xai_saliency_map.png b/tutorials/training/source_zh_cn/advanced_use/images/xai_saliency_map.png index 27587fbe0456de72d2b2ff5be2a99f797005dd82..6f9d5909f94093274d44e26cd575394f5a383692 100644 Binary files a/tutorials/training/source_zh_cn/advanced_use/images/xai_saliency_map.png and b/tutorials/training/source_zh_cn/advanced_use/images/xai_saliency_map.png differ diff --git a/tutorials/training/source_zh_cn/advanced_use/images/xai_saliency_map_detail.png b/tutorials/training/source_zh_cn/advanced_use/images/xai_saliency_map_detail.png index 66e6b1cf714f8ee7b114a1149b3e06a941574096..3247dca079922e039dd8119a3c0b4ded4584df54 100644 Binary files a/tutorials/training/source_zh_cn/advanced_use/images/xai_saliency_map_detail.png and b/tutorials/training/source_zh_cn/advanced_use/images/xai_saliency_map_detail.png differ diff --git a/tutorials/training/source_zh_cn/advanced_use/model_explaination.md b/tutorials/training/source_zh_cn/advanced_use/model_explaination.md index b89b0ad35ee8b1fc0a90601dee6618110da21e3d..5dc64b0874b750610256abfc15459cfc1221f319 100644 --- a/tutorials/training/source_zh_cn/advanced_use/model_explaination.md +++ b/tutorials/training/source_zh_cn/advanced_use/model_explaination.md @@ -1,6 +1,6 @@ # 解释模型 -`Linux` `Ascend` `GPU` `模型调优` `初级` `中级` `高级` +`Linux` `Ascend` `GPU` `模型调优` `初级` `中级` `高级` `反事实` @@ -15,6 +15,10 @@ - [解释方法评估](#解释方法评估) - [综合评估](#综合评估) - [分类评估](#分类评估) + - [反事实](#反事实) + - [基于遮掩的反事实](#基于遮掩的反事实) + - [基于遮掩的反事实使用限制](#基于遮掩的反事实使用限制) + - [基于遮掩的反事实页面及功能介绍](#基于遮掩的反事实页面及功能介绍) @@ -94,7 +98,7 @@ runner.run() - 当前只支持图片分类下的CNN网络模型，比如：Lenet、Resnet、Alexnet。 - 仅支持PyNative运行模式。 -- 所有解释方法及度量方法对象均不能被不同的ImageClassificationRunner对象重用，用户必须为每个ImageClassificationRunner对象实例化独占的解释方法及度量方法对象，否则可能会产生错误。下方是一个正确使用例子。 +- 所有解释方法及度量方法对象均不能被不同的 ImageClassificationRunner 对象重用，用户必须为每个 ImageClassificationRunner 对象实例化独占的解释方法及度量方法对象，否则可能会产生错误。下方是一个正确使用例子。 ```python gradcam = GradCAM(net, layer='layer4') @@ -142,14 +146,15 @@ runner2.run() 1. 通过界面上方的解释方法勾选需要的解释方法。 2. 通过切换界面右上方的“叠加于原图”按钮可以选择让显著图叠加于原图上显示。 3. 点击不同标签，显示模型对不同标签的显著图分析结果。对于不同的分类结果，通常模型的关注点也是不同的。 -4. 通过界面上方的标签筛选功能，筛选出指定标签图片。 -5. 通过界面右上角的图片排序改变图片显示的顺序。 -6. 点击解释方法最右边的“查看评分”，可以进入对所有解释方法评估的界面。 -7. 点击图片可查看放大图。 +4. 点选预测类型复选框, 以显示具有已选类型的标签的图片: TP - 真阳性， FN - 假阴性， FP - 假阳性。 +5. 通过界面上方的标签筛选功能，筛选出指定标签图片。 +6. 通过界面右上角的图片排序改变图片显示的顺序。 +7. 点击解释方法最右边的“查看评分”，可以进入对所有解释方法评估的界面。 +8. 点击图片可查看放大图。 ![xai_saliency_map_detail](./images/xai_saliency_map_detail.png) -### 解释方法评估 + ### 解释方法评估 #### 综合评估 @@ -162,3 +167,49 @@ runner2.run() 分类评估页提供两种形式的对比，一种是同一解释方法的不同度量维度在各个标签下的分值，一种是对于同一度量维度，不同解释方法在各个标签下的分值。 ![xai_metrix_class](./images/xai_metrix_class.png) + +## 反事实 + +反事实是一种相对新的模型解释方法，存有不同的形式。现时 ImageClassificationRunner 提供一个容易使用的，名为 '基于遮掩的反事实' (简称 'HOC') 的接口，不同的反事实功能会在将来支持。 + +### 基于遮掩的反事实 + +HOC是一种基于遮掩的反事实方法，目的是在目标标签的预测慨率高于阀值(暂固定为0.5)的约束条件下搜索出最小的图片显示区域。整个搜索是一个分层级的过程，首先把整个图片使用高斯模糊遮掩住，之后由最大的显示区块开始搜索，再深入搜索到更小的子区块以获得更精确的结果。最终我们会得到一个区块树，每一个节点代表一个正方形的显示区块，而子节点侧是在父节点范围内的更小的正方形显示区块。根节点代表了整个原始图片，而它的直接子节点就是第一层的显示区块。 + +现时 ImageClassificationRunner 会基于输入图片大小自动计算分层数量(一到三层)，显示区块大小，平移步幅及模糊遮掩图。第一层的显示区块边长为输入图片的短边的一半(向下舍入)，每下一层显示区块边长就会减半，最小为28个象素否则不会再增加下一层。平移步幅是显示区块边长的五分一(向下舍入)。 + +模型和数据集的准备跟前述的解释方法相同，用户透过调用 ImageClassificationRunner 的 register_hierarchical_occlusion() 来启用HOC，下方是一个使用例子。 + +```python +runner = ImageClassificationRunner(summary_dir='./summary_dir_1', network=net, activation_fn=activation_fn, data=data) +runner.register_hierarchical_occlusion() +runner.run() +``` + +用户可在同一个runner上配合使用 register_saliency() 。 + +#### 基于遮掩的反事实使用限制 + +- 包括所有前述的解释方法的使用限制，但只支持三通道输入的模型。 +- 图片数据必须为RGB三通道格式，短边的长度必须大于或等于56象素。 + +#### 基于遮掩的反事实页面及功能介绍 + +可以看到在解释日志列表上所有使用了HOC功能的解释日志的”反事实解释”连结已经可被点击，点击后就会进入反事实页面。 + +![xai_hoc_index](./images/xai_hoc_index.png) + +基于遮掩的反事实解释页面展示了所有搜寻到的结果，包括： + +- 所有具有预测概率大于0.5的目标标签的样本及其原始图片。 +- 目标标签的预测概率。 +- 搜索过程中每个分层的结果图及其预测概率。 + +![xai_hoc](./images/xai_hoc.png) + +界面操作： + +1. 在左方面板选择要显样本的标签筛选及排序方法，可以选择使用预测概率排序。 +2. 在左方面板的样本列表进行流览或翻页操作，当点击了一个样本图片后，相关的HOC搜索结果会于其余的面板上显示。 +3. 在中映面板选择要显的标签搜寻结果，只有预测概率大于0.5的标签才有HOC搜索结果。 +4. 在下方面板检视搜寻过程的分层结果图，当点击了一张结果图后，它的放大版本就会在右方面板上显示。 (注意: 为了区分显示，遮掩了的区域被降低了亮度及转成了灰阶，但在实际的搜索中只是使用了高斯模糊作遮掩，并没有对亮度或彩度进行调整。)