# 文本分类任务doccano使用指南
**目录**
* [1. 安装](#安装)
* [2. 项目创建](#项目创建)
* [3. 数据上传](#数据上传)
* [4. 标签构建](#标签构建)
* [5. 任务标注](#任务标注)
* [6. 数据导出](#数据导出)
* [7. 数据转换](#数据转换)
## 1. 安装
**以下标注示例用到的环境配置：**
- Python 3.8+
- doccano 1.6.2
在终端(terminal)使用pip安装doccano：
```shell
pip install doccano==1.6.2
```
安装完成后，运行以下命令行：
```shell
# Initialize database.
doccano init
# Create a super user.
doccano createuser --username admin --password pass
# Start a web server.
doccano webserver --port 8000
```
在新的终端(terminal)运行如下命令行：
```shell
# Start the task queue to handle file upload/download.
doccano task
```
在浏览器打开[http://127.0.0.1:8000/](http://127.0.0.1:8000/)，输入用户名和密码登录，开始使用doccano进行标注。doccano支持中文版本，可以点击右上角选择ZH(中文)。
doccano还支持PostgreSQL、Docker、Docker Compose等安装方式，详情请参考[doccano官方文档](https://github.com/doccano/doccano) 完成doccano的安装与初始配置。
## 2. 项目创建
文本分类支持多分类、多标签、层次分类三种类型的文本分类任务。
点击创建（Create）开始创建一个新的项目，选择文本分类，然后填写项目名称、描述、Tags等项目信息。如果是多分类任务或者是单路径层次分类任务，勾选 `Allow single label` ，勾选后标签标注只允许选择一个标签进行标注。点击创建成功创建一个doccano项目。
## 3. 数据上传
点击数据集-操作-导入数据集，开始导入本地待标注数据集：
doccano支持`TextFile`、`TextLine`、`JSONL`和`CoNLL`四种数据上传格式，文本分类本地数据集定制训练中**统一使用TextLine**这一文件格式，即上传的文件需要为txt等格式，且在数据标注时，该文件的每一行待标注文本显示为一页内容。
上传的文件为txt等格式，每一行为一条待标注文本，示例:
```text
黑苦荞茶的功效与作用及食用方法
交界痣会凸起吗
检查是否能怀孕挂什么科
鱼油怎么吃咬破吃还是直接咽下去
幼儿挑食的生理原因是
...
```
上传数据类型**选择TextLine**，选择待标注文本或拖拽文本导入doccano项目中，点击导入，导入待标注数据集。
## 4. 标签构建
点击标签-操作-创建标签，开始添加分类类别标签：
填入分类类别标签，选择标签颜色，建议不同标签选择不同颜色，最后点击保存或保存并添加下一个，保存标签：
文本分类标签构建示例：
**NOTE:**
我们默认层次分类标签不同层的标签之间具有关联性，以下图为例一个样本具有标签美短虎斑，我们默认还包含美国短毛猫和猫两个标签。
对于层次分类任务的分类标签我们建议使用标签层次结构中**叶结点标签路径作为标签**，以上图的标签结构为例，我们建议使用`##`作为分隔符，分隔不同层之间的标签：
## 5. 任务标注
标注示例，选择对应的分类类别标签，输入回车（Enter）键确认：
## 6. 数据导出
选择数据集-操作-导出数据集，将标注好的数据导出，我们默认所有数据集已经标注完成且正确：
选择导出的文件类型为``JSONL``，导出数据：
导出数据示例：
```text
{"id": 23, "data": "黑苦荞茶的功效与作用及食用方法", "label": ["功效作用"]}
{"id": 24, "data": "交界痣会凸起吗", "label": ["疾病表述"]}
{"id": 25, "data": "检查是否能怀孕挂什么科", "label": ["就医建议"]}
{"id": 26, "data": "鱼油怎么吃咬破吃还是直接咽下去", "label": ["其他"]}
{"id": 27, "data": "幼儿挑食的生理原因是", "label": ["病因分析"]}
```
标注数据保存在同一个文本文件中，每条样例占一行且存储为``jsonl``格式，其包含以下字段
- ``id``: 样本在数据集中的唯一标识ID。
- ``data``: 原始文本数据。
- ``label``: 文本对应类别标签。
## 7.数据转换
该章节详细说明如何通过`doccano.py`脚本对doccano平台导出的标注数据进行转换，一键生成训练/验证/测试集。当标注完成后，在 doccano 平台上导出 `JSON` 形式的文件，并将其重命名为 `doccano.jsonl`。
### 7.1 多分类任务
通过 [doccano.py](./doccano.py) 脚本进行数据形式转换，然后便可以按照[多分类文本任务指南](multi_class/README.md)中固定格式进行相应模型训练。
数据标注转化运行：
```shell
python doccano.py \
--doccano_file doccano.jsonl \
--save_dir ./data \
--splits 0.8 0.1 0.1 \
--task_type "multi_class"
```
稀疏数据识别出的有效标注请增加配置参数`--valid`，脏数据清洗的标注数据（文本中有脏数据标签）请增加配置参数`--dirty`，更多稀疏数据识别和脏数据清洗详见[多分类训练评估与模型优化指南](multi_class/analysis/README.md)
### 7.2 多标签任务
通过 [doccano.py](./doccano.py) 脚本进行数据形式转换，然后便可以按照[多标签文本分类任务指南](multi_label/README.md)中固定格式进行相应模型训练。
数据标注转化运行：
```shell
python doccano.py \
--doccano_file doccano.jsonl \
--save_dir ./data \
--splits 0.8 0.1 0.1 \
--task_type "multi_label"
```
稀疏数据识别出的有效标注请增加配置参数`--valid`，脏数据清洗的标注数据（文本中有脏数据标签）请增加配置参数`--dirty`，更多稀疏数据识别和脏数据清洗详见[多标签训练评估与模型优化指南](multi_label/analysis/README.md)
### 7.3 层次分类任务
通过 [doccano.py](./doccano.py) 脚本进行数据形式转换，然后便可以按照[层次文本分类任务指南](hierarchical/README.md)中固定格式进行相应模型训练。
数据标注转化运行：
```shell
python doccano.py \
--doccano_file doccano.jsonl \
--save_dir ./data \
--splits 0.8 0.2 \
--task_type "hierarchical"
```
稀疏数据识别出的有效标注请增加配置参数`--valid`，脏数据清洗的标注数据（文本中有脏数据标签）请增加配置参数`--dirty`，更多稀疏数据识别和脏数据清洗详见[层次分类训练评估与模型优化指南](hierarchical/analysis/README.md)
可配置参数说明：
- ``doccano_file``: 从doccano导出的数据标注文件。
- ``save_dir``: 训练数据的保存目录，默认存储在``data``目录下。
- ``splits``: 划分数据集时训练集、验证集所占的比例。默认为[0.8, 0.2]表示按照``8:2``的比例将数据划分为训练集、验证集。
- ``task_type``: 可选，选择任务类型,有多分类，多标签，层次分类三种类型的任务。
- ``is_shuffle``: 是否对数据集进行随机打散，默认为True。
- ``seed``: 随机种子，默认为1000.
- ``separator``: 不同层标签之间的分隔符，该参数只对层次文本分类任务有效。默认为"##"。
- ``valid``: 是否为稀疏数据筛选的有效标注数据，默认为False.
- ``dirty``: 是否为脏数据清洗策略标注数据，默认为False.
转化后的doccano标注数据目录结构如下：
```text
data/
├── train.txt # 训练数据集文件
├── dev.txt # 开发数据集文件
├── test.txt # 测试训练集文件（可选，数据划分为 train/dev/test 数据集）
├── label.txt # 分类标签文件
└── data.txt # 待预测数据文件
```
备注：
- 默认情况下 [doccano.py](./doccano.py) 脚本会按照比例将数据划分成train/dev 数据集，也可以划分为 train/dev/test 数据集。
- 脚本会自动生成data.txt，如果数据划分为 train/dev/test 数据集，data.txt则为test数据集无标签数据；如果数据划分为 train/dev 数据集，data.txt为无标签数据。**如果有未标注数据，则用未标注数据文件替换data.txt**
- 每次执行 [doccano.py](./doccano.py) 脚本，将会覆盖已有的同名数据文件
- 对于从doccano导出的文件，默认文件中的每条数据都是经过人工正确标注的。
## References
- **[doccano](https://github.com/doccano/doccano)**
