Data map (#50)

data map commit with image and README update

Co-authored-by: wanglijie <wanglijie@baidu.com>

.pre-commit-config.yaml

@@ -24,4 +24,5 @@ repos:
         files: \.md$
     -   id: forbid-tabs
         files: \.md$
-    -   id: remove-tabs
+    -   id: remove-tabs
+        exclude: (\.tsv)$

README.md

@@ -14,26 +14,34 @@
 <h4 align="center">
   <a href=#安装> 安装 </a> |
   <a href=#快速开始> 快速开始 </a>|
-  <a href=#可信分析功能> 可信分析功能 </a> |
-  <a href=#可信增强功能> 可信增强功能 </a> |
+  <a href=#可信分析> 可信分析 </a> |
+  <a href=#可信增强> 可信增强 </a> |
   <a href=#应用案例> 应用案例 </a> |
   <a href=#评测榜单> 评测榜单 </a> |
   <a href=#学术文献> 学术文献 </a>
 </h4>
 
 **TrustAI**是基于深度学习平台『飞桨』([PaddlePaddle](https://github.com/PaddlePaddle/Paddle))开发的集可信分析和增强于一体的可信AI工具集，助力NLP开发者提升深度学习模型效果和可信度，推动模型安全、可靠的落地于应用。
 
+<p align="center">
+<img align="center" src="./imgs/framework.png", width=500><br>
+图 TrustAI提供能力概览
+</p>
 
 ## News 📢
+* 🔥 2022.12.27 TrustAI发布数据地图绘制能力，欢迎大家使用。
 * 🔥 2022.10.30 [可解释评测数据集](https://www.luge.ai/#/luge/task/taskDetail?taskId=15)入驻千言，部分数据提供人工标注证据，欢迎大家使用。
 * 🔥 2022.8.29 [PaddleNLP分类系统](https://github.com/PaddlePaddle/PaddleNLP/tree/develop/applications/text_classification)已经接入TrustAI能力，欢迎大家试用。
 * 🔥 2022.8.20 TrustAI[发布](https://mp.weixin.qq.com/s/Ph3uzbUEUj1K7UALdM6OCA)可信增强能力及应用案例。
 * 🎉 2022.5.20 TrustAI首次[发布](https://mp.weixin.qq.com/s/AqYReKRnki9TwI5huY1f5Q)！
 
-## <p id="可信分析功能">👏可信分析功能</p>
-TrustAI提供特征级证据和实例级证据分析方法，全方位解释模型的预测，帮助开发者了解模型预测机制，以及协助使用者基于证据做出正确决策。
+## <p id="可信分析">可信分析</p>
+TrustAI提供证据分析和数据分析能力。
 
-### 特征级证据分析
+### 证据分析
+证据分析提供模型预测依赖的证据。TrustAI从特征级和实例级两种维度提供证据分析方法，全方位解释模型的预测，帮助开发者了解模型预测机制，以及协助使用者基于证据做出正确决策。
+
+#### 特征级证据分析
 
 根据模型预测结果，从输入文本中提取模型预测所依赖的证据，即输入文本中支持模型预测的若干重要词。
 
@@ -45,7 +53,7 @@ TrustAI提供特征级证据和实例级证据分析方法，全方位解释模
 
 关于方法更多详细内容可参考 - [特征级证据分析文档](./trustai/interpretation/token_level/README.md)
 
-### 实例级证据分析
+#### 实例级证据分析
 
 
 从训练数据中找出对当前预测文本影响较大的若干训练样本作为模型预测依赖证据。
@@ -59,46 +67,79 @@ TrustAI提供特征级证据和实例级证据分析方法，全方位解释模
 
 关于方法更多详细内容可参考 - [实例级证据分析文档](./trustai/interpretation/example_level/README.md)
 
-## <p id="可信增强功能">💥可信增强功能</p>
+### 数据分析
+数据分析能力旨在根据训练、预测信号绘制数据地图（见下图），并结合证据分析识别数据缺陷。当前，TrustAI针对三种数据缺陷提供了识别方法，三种缺陷分别是数据标注错误、数据标注不足（也称为数据覆盖不足）、数据分布偏置。
+
+<p align="center">
+<img align="center" src="./imgs/data_map_main.png", width=400><br>
+图 基于训练信号绘制的训练数据地图
+</p>
+
+#### 数据标注错误识别
+TrustAI提供了标注错误数据（即脏数据）自动识别功能，帮助降低人工检查数据的成本。
+
+如下图所示，在两个公开数据集上，TrustAI自动识别的标注错误数据比例远高于随机选择策略。
+
+<p align="center">
+<img align="center" src="./imgs/dirty_analysis.png", width=400><br>
+图 不同策略的标注错误数据识别效果
+</p>
 
-基于对模型预测依赖证据的分析，TrustAI提供了模型缺陷识别和对应的优化方案，即可信增强功能。当前，从训练数据和训练机制优化角度，TrustAI开源了针对3种数据缺陷的识别方案和优化方案，希望能够帮助开发者以最小成本解决训练数据缺陷问题。同时，TrustAI开源了一种基于证据指导的预测机制优化方案，用来解决长文本理解问题。
+应用示例见AI Studio - [训练数据中标注错误数据自动识别示例](https://aistudio.baidu.com/aistudio/projectdetail/4434058)
 
-### 训练数据中脏数据自动识别
+#### 数据覆盖不足识别
+训练数据覆盖不足会导致模型在对应的测试数据上表现不好。基于实例级证据分析方法，TrustAI可识别训练数据覆盖不足的测试数据（这些数据构成的集合称为目标集），模型在目标集上效果降低20%左右。
+
+<p align="center">
+<img align="center" src="./imgs/覆盖不足识别.png", width=400><br>
+图 模型在全部测试数据和覆盖不足测试数据上的效果
+</p>
 
+应用示例见AI Studio - [训练数据覆盖不足识别示例](https://aistudio.baidu.com/aistudio/projectdetail/4434403)
 
-TrustAI提供了脏数据（即标注质量差的数据）自动识别功能，帮助降低人工检查数据的成本。
+#### 数据分布偏置识别
+神经网络模型会利用数据集中的偏置做预测，这会导致模型没有学会理解语言，鲁棒性差。TrustAI提供了基于统计的偏置识别和基于模型的偏置识别。
 
-如下图所示，在两个公开数据集上，TrustAI自动识别的脏数据比例远高于随机选择策略。
+基于统计的偏置识别，见[偏置识别](https://github.com/PaddlePaddle/TrustAI/tree/data_map/tutorials/data_bias_identification)
+
+基于模型的偏置识别，待开源。
+
+## <p id="可信增强">可信增强</p>
+
+TrustAI提供了针对识别缺陷的优化方案，即可信增强功能。当前，从训练数据和训练机制优化角度，TrustAI开源了针对3种数据缺陷的优化方案，希望能够帮助开发者以最小成本解决训练数据缺陷问题。同时，TrustAI开源了一种基于证据指导的预测机制优化方案，用来解决长文本理解问题。
+
+### 针对数据标注错误的数据清洗
+从训练数据角度，直接对TrustAI识别的标注错误数据进行人工修正，效果如下图所示。
 
 <p align="center">
-<img align="center" src="./imgs/dirty_analysis.png", width=400><br>
-图1 不同策略的脏数据识别效果
+<img align="center" src="./imgs/paddlenlp脏数据识别及修正.png", width=700><br>
+图 在三个常见分类任务上针对标注错误的数据清洗效果
 </p>
 
-应用示例见AI Studio - [训练数据中脏数据自动识别示例](https://aistudio.baidu.com/aistudio/projectdetail/4434058)
+从训练机制角度，TrustAI也提供了缓解脏数据影响的策略，待开源。
 
-### 训练数据覆盖不足识别及有效数据增强
 
-训练数据覆盖不足会导致模型在对应的测试数据上表现不好。基于实例级证据分析方法，TrustAI可识别训练数据覆盖不足的测试数据（这些数据构成的集合称为目标集），模型在目标集上效果降低20%左右。进一步地，为降低标注成本，TrustAI提供有效数据选择策略，即从未标注数据中选择可以提高训练数据覆盖度和模型效果的数据进行标注。
+### 针对数据覆盖不足的有效数据增强
+针对训练数据覆盖不足常见做法是补充数据。为降低标注成本，TrustAI提供了有效数据增强策略，即从未标注数据中选择可以提高训练数据覆盖度和模型效果的数据进行标注。
 
 如下图所示，在两个公开数据集上，TrustAI提供的有效数据增强策略对模型在目标数据上的效果提升远高于随机选择策略。
 
 <p align="center">
 <img align="center" src="./imgs/sparse_analysis.png", width=400><br>
-图2 目标集提升的效果
+图 目标集提升的效果
 </p>
 
-应用示例见AI Studio - [训练数据覆盖不足识别及有效数据增强示例](https://aistudio.baidu.com/aistudio/projectdetail/4434403)
+应用示例见AI Studio - [针对训练数据覆盖不足的有效数据增强示例](https://aistudio.baidu.com/aistudio/projectdetail/4434403)
 
 
-### 训练数据分布偏置识别及偏置缓解
-神经网络模型会利用数据集中的偏置做预测，这会导致模型没有学会理解语言，鲁棒性差。TrustAI提供了分布修正和权重修正两种策略，在不需要人工介入的条件下，有效缓解数据偏置对模型训练的影响。
+### 针对数据分布偏置的偏置消除
+TrustAI提供了分布修正和权重修正两种策略，在不需要人工介入的条件下，有效缓解数据偏置对模型训练的影响。
 
 如下图所示，在两个公开的鲁棒性数据集上，TrustAI的权重修正和分布修正策略分别取得明显提升。
 
 <p align="center">
 <img align="center" src="./imgs/bias_correction.png", width=400><br>
-图3 偏置修正后模型在鲁棒性数据集上的效果
+图 偏置修正后模型在鲁棒性数据集上的效果
 </p>
 
 应用示例见AI Studio - [数据分布偏置缓解策略-数据权重修正示例](https://aistudio.baidu.com/aistudio/projectdetail/4434616)和[数据分布偏置缓解策略-数据分布修正示例](https://aistudio.baidu.com/aistudio/projectdetail/4434652)
@@ -110,7 +151,7 @@ TrustAI提供了脏数据（即标注质量差的数据）自动识别功能，
 
 <p align="center">
 <img align="center" src="./imgs/redundancy_removal.png", width=400><br>
-图4 证据识别及基于证据预测的两阶段策略在阅读理解任务上的效果
+图 证据识别及基于证据预测的两阶段策略在阅读理解任务上的效果
 </p>
 
 应用示例见AI Studio - [证据识别及基于证据的预测示例-中文阅读理解任务](https://aistudio.baidu.com/aistudio/projectdetail/4525331)
@@ -206,7 +247,7 @@ result = interpreter(model_inputs)
 关于接口使用的更多样例见[examples目录](./examples)
 
 
-## <p id="应用案例">🚀应用案例</p>
+## <p id="应用案例">应用案例</p>
 
 </details>
 

tutorials/data_map/README.md

@@ -0,0 +1,108 @@
+# 基于训练信号的数据地图绘制 Dataset Cartography with Training Dynamics
+
+## 方法介绍
+现有工作表明，可以使用训练数据在训练过程中的信号绘制数据地图；根据信号特征划分数据，不同数据区域具有不同特点，如难学、标注错误等。通过绘制数据地图，可以帮助开发者更好地了解训练数据。
+
+TrustAI提供了"训练信号收集 -> 数据地图绘制"方案。首先，收集每条训练数据在训练过程中不同step下的训练信号；然后，根据得到的统计信号，基于指定的信号维度绘制数据地图。
+
+注：开发者可访问[ AI Studio示例 ](https://aistudio.baidu.com/aistudio/projectdetail/5307701)快速体验本案例。
+
+## 实验步骤
+我们以相似度计算任务LCQMC数据集上的模拟实验为例，介绍该方案实现步骤和效果。
+
+
+**Step 1**：从LCQMC训练集中随机抽取100条数据作为训练数据样例。训练集文件为.tsv格式，内容如下
+
+```shell
+# tsv格式数据，一行一条训练数据，不同字段用tab分隔，各字段如下介绍:
+[
+    "text_a" : xxx,              // 训练数据文本a
+    "text_b" : xxx,              // 训练数据文本b
+    "label" : xxx,               // 训练数据对应的label
+    "s_label" : xxx,             // 训练数据的构造label （可省略）
+]
+```
+注: ``s_label``可省，为用户构造的label，如构造脏数据。
+
+基于ERNIE-3.0-base-zh在新训练集`sample_100.tsv`上微调得到基线模型，运行命令如下所示：
+
+```shell
+# 训练模型并收集训练信号
+sh run_train_pointwise.sh
+```
+所有训练数据的训练信号按训练step保存在`outputs`路径下。
+
+注: 训练信号的收集代码可参考代码`train_pointwise.py`中Lines 199-218，用户可根据自己模型代码进行修改。收集的训练信号如下（用户可自行设计更多信号进行收集）：
+
+```shell
+# .jsonl 格式数据
+[
+    {'id' : xxx,                // 训练数据的id
+     'label' : xxx,             // 训练数据对应的label
+     'pred_label' : xxx,        // 训练数据的预测label
+     'correct' : xxx,           // 训练数据是否被预测正确
+     'loss' : xxx,              // 训练数据当前的loss
+     'probs' : [xxx, xxx],      // 训练数据在当前每个类下的预测概率(one-hot形式)
+     'label_probs' : xxx        // 训练数据在label类别下的预测概率
+     }  
+    ... ...
+]
+```
+
+**Step 2**：训练信号处理，即基于不同训练steps收集到的信号计算整体信号，如基于不同steps得到的预测概率计算整体平均预测概率。
+
+```shell
+# 训练信号处理
+python -u sample_stat_summary.py
+```
+产出数据保存在`outputs`路径下。
+
+<details>
+    <summary> 训练信号详细信息 </summary>
+
+```shell
+# tsv 格式数据，一行保存一条训练数据的所有训练信号，信号之间用tab进行分隔，各信号如下表示:
+[
+    "id" : xxx,                  // 训练数据的id
+    "label" : xxx,               // 训练数据对应的label
+    "s_label" : xxx,             // 训练数据的构造label，数据地图绘制允许标记困难数据(s_label = 1)和构造脏数据(s_label = 2)
+    "correct_times" : xxx,       // 总共预测正确的次数  
+    "correct_ratio" : xxx,       // 预测正确次数占比
+    "avg_probs" : xxx,           // 多次预测的置信度的平均数
+    "label_var" : xxx,           // 多次预测的置信度的方差
+    "max_label_probs" : xxx,     // 多次预测的置信度的最大值
+    "min_label_probs" : xxx,     // 多次预测的置信度的最小值
+    "forgetting_times" : xxx,    // 多次预测反映出的，模型对本数据的遗忘次数（之前预测对了，后来又错了）
+    "learnt_times" : xxx,        // 多次预测反映出的，模型对本数据的学会次数（之前预测错了，后来又对了）
+    "first_forget" : xxx,        // 多次预测中，第一次遗忘本数据  
+    "first_learn" : xxx,         // 多次预测中，第一次学会本数据  
+]
+```
+</details>
+
+**Step 3**：基于产出的训练信号，选择两个信号作为数据地图的主要维度（默认为平均置信度与置信方差），并选择其他信号（如正确比例、正确次数、遗忘次数、学习次数等）以颜色、形状等进行区别绘制数据地图。
+
+```shell
+# 数据地图绘制
+python -u plot_map.py
+
+# 参数选择
+attr1: str类型， 默认值为"avg_probs"，选择一个信号作为数据地图的纵轴
+attr2: str类型， 默认值为"label_var"，选择一个信号作为数据地图的横轴
+criterion: str类型，默认值为空，选择一个训练信号作为数据筛选依据，仅满足条件的数据会被绘制在地图上
+threshold: float类型，默认值0，与criterion一同使用，为选择的训练信号设置阈值，筛选数据
+use_f_times: float类型，默认值-1，使用forgotten_times并选择所有遗忘次数不小于use_f_times的样本
+use_l_times: float类型，默认值-1，使用learnt_times并选择所有遗忘次数不小于use_l_times的样本
+
+# 数据地图样例
+python -u plot_map.py                                               # 图1左
+python -u plot_map.py --criterion forgetting_times --threshold 1    # 图1中
+python -u plot_map.py --use_l_times 0                               # 图1右
+```
+
+<p align="center">
+<img align="center" src="../../imgs/data_map_normal.png", width=300>
+<img align="center" src="../../imgs/data_map_criterion.png", width=300>
+<img align="center" src="../../imgs/data_map_lt.png", width=300><br>
+图1 数据地图样例。左: 默认参数设置的数据地图；中：指定criterion为forgetting_times，threshold为1的数据绘制地图；右：使用learnt_times(use_l_times=0)区分数据的颜色，其中左上和左下角数据分别使用correct_times做进一步区分。此数据地图根据全量LCQMC数据的训练信号绘制，而非提供的100条样例。
+</p>