[系统运维]文本标注工具之BRAT

文本标注工具之BRAT

brat是linux下的一款应用于webserver端的文本标注工具，可用于标注如下类型信息：
（1）实体：命名实体，可用于NER；
（2）关系：实体间关系，可用于关系抽取；
（3）事件：实体参与的事件；
（4）属性：事件或实体的属性，常用于知识图谱。
本文将依次介绍brat的安装、配置和基本使用。

安装

基本环境配置

【系统环境】
brat只能用于linux下，若为windows系统，请安装于linux虚拟机上。
【web环境】
官方建议使用使用Apache2进行web配置，用如下命令安装apache2：

sudo apt-get upgrade
sudo apt-get update
sudo apt-get install apache2

若是centos，请参考 https://shimo.im/docs/vVqRV2bQEzTbDNqy
安装完毕后，会在 /var 目录下生成一个www/html目录，下面bart的安装路径均在其中：

cd /var/www/html

安装流程
（1）下载brat的release版本
（2）将其挪至/var/www/html路径下，解压并重命名为brat

unzip brat-1.3p1.zip
mv brat-1.3p1 brat

（3）修改brat路径权限

sudo chmod 777 -R /var/www/html/brat

（4）进入brat目录，进行安装，并根据提示输入用户名、密码和邮箱等信息

cd /var/www/html/brat
sudo ./install.sh

（5）配置apache2.conf文件

# ubantu环境
sudo vim /etc/apache2/apache2.conf
# centos环境
sudo vim /etc/httpd/conf/httpd.conf

在文件末尾加入如下内容（注意缩进，若启动apache2服务时候报错“…the control process exited with error code…”，建议手动缩进（4下空格键））：

<Directory /var/www/html/brat>
　　AllowOverride Options Indexes FileInfo Limit
　　Require all granted
　　AddType application/xhtml+xml .xhtml
　　AddType font/ttf .ttf
　　Options +ExecCGI
　　AddHandler cgi-script .cgi
</Directory>

（6）建立Apache2和cgi模块的软链接，其具体说明可见issue #1141

cd /etc/apache2/mods-enabled
sudo ln -s ../mods-available/cgi.load

（7）brat默认不支持中文标注，因此需手动修改brat主目录**/server/src路径下的projectconfig.py**文件的第162行代码

sudo vim /var/www/html/brat/server/src/projectconfig.py

将其改为：

# n  = re.sub(r'[^a-zA-Z0-9_-]', '_', n)
n = re.sub(u'[^a-zA-Z\u4e00-\u9fa5<>,0-9_-]', '_', n)

（8）重启Apache2

# ubantu
sudo service apache2 restart
# centos
sudo systemctl restart httpd.service

访问本地brat地址，若页面正常，即安装配置无误。

brat docker

docker run --name=brat -d -p 38080:80 -v /mnt/home/share/dyz/kg-annotation/brat-data:/bratdata -v /mnt/home/share/dyz/kg-annotation/brat-cfg:/bratcfg -e BRAT_USERNAME=brat -e BRAT_PASSWORD=brat -e BRAT_EMAIL=brat@example.com cassj/brat

创建users登录用户

users.json
{
  "user1":"password"
}
## docker restart brat

使用教程

对于标注人员，主要是在前端如何浏览数据及进行标注。
主要有以下三个快捷键

tab：打开文件浏览器
键盘左：回到上一个文件
键盘右：进入下一个文件

另外，工具栏中Data项点击后可以下载到当前文件未parsing的标注数据:

Option中，浏览相关的Visual options基本不需要说明。layout density可以根据标注内容的复杂程度而定，只做文本标记可以开到Dense；Visual A… labels应该是指事件，对文本标记之间的关系是没用的。

标注

标注分点的标注和边的标注两种行为：
点的标注：通过光标框定一个文本串，选择标记类别
边的标注：按住点向外拖到目标点，如果类型允许就会为你加边。
建议打开Option，把Annotation Option改为Normal，而不是Careful。否则你完成选择之后，还需要额外点一次Ok才可以。
标注的类别选择可以由键盘快捷键完成而不需要点击，但和标记的颜色一样依赖后台的配置文件，如果发布任务的人没有给你提供快捷键，去威逼利诱他/她。

给后台管理人员的说明

添加新用户
自己去目录下找vim /var/www/html/brat/config.py
文件和内容的组织方式
数据集（称为Collection）放在**./data目录下，标注对象以文件夹下文本文件的格式组织，每个.txt文件必须相应的有一个.ann文件存储标注内容。
标注的具体格式可以在官网找到：http://brat.nlplab.org/standoff.html，这里不再多说，只提醒被标注文本以文件为单位，被视为一个大字符串，因此，一切offset**都是针对文件起始位置的。
标注相关的配置
各类配置文件都对子文件夹递归的有效，在安装目录下可以看到大量例子，因此这里只做简单说明。（但你不太应该修改全局配置）

• annotation.conf:
  除非你不使用校验工具，否则是必须有的。
  存储允许使用的各类标记。似乎分为[entities]，[relation]，[events]，[attributes]四类。
• entities:
  写出名称就可以了，不可overlap的文本边界标记。
  每一行表示一个实体名称，若需要定义层次化的实体，则在下一层实体前加入Tab键。

[entities]
# Definition of entities.
# Format is a simple list with one type per line.
Person
	Male
	Female
Organization
GPE

• relations:
  名称 Arg1:X, Arg2:Y, :Z
  其中X和Y是允许的类别（如果允许所有entities，直接写即可，另外似乎也可以自定义=X|Y）（即声明边必须给出domain）
  是可选的，包括对称性、传递性等。

每一行表示一条关系，定义了关系名称，以及关系双方的实体。
其基本的配置规则为：
a). 每一行开头为关系名称；
b). 关系名称后为空格，空格后为相关的实体信息，其格式为Arg1:实体1，Arg2:实体2，表示从实体1—>实体2的关系；
c) 若需要定义双向关系，则补充:symmetric-transitive。

[relations]

# Definition of (binary) relations.

# Format in brief: one relation per line, with first space-separated
# field giving the relation type and the rest of the line the
# comma-separated arguments in ROLE:TYPE format. The roles are
# typically "Arg1" and "Arg2".

Located            Arg1:Person, Arg2:GPE
Geographical_part  Arg1:GPE,    Arg2:GPE
Family             Arg1:Person, Arg2:Person
Employment         Arg1:Person, Arg2:GPE
Ownership          Arg1:Person, Arg2:Organization
Origin             Arg1:Organization, Arg2:GPE

Alias              Arg1:Person, Arg2:Person, <REL-TYPE>:symmetric-transitive

• events:
  可以嵌套的复杂PAS结构，具体语法结合例子和官网分析。
  每一行表示一个事件，定义了事件名称，以及事件参与方的实体信息。

其基本的配置规则为：
a) 每一行开头为事件名；
b) 事件名称后为空格，空格后为相关的实体信息，其格式为Arg1:实体1，Arg2:实体2
c) 可通过定义=实体1|实体2来将实体进行组合;
d) 每个事件，可通过正则表达式中适配符来限制某个实体的参与与否以及参与个数：？表示可参与，可不参与；* 表示可参与0次或多次；+表示至少参与一次；{2}表示必须为2个实体，其他正则表达式类似。
e) 若为层次性的事件，则可通过在上一层事件名称前添加!，以使其不参与具体标注（因此，其仅做注释性的层次化）

[events]
# Definition of events.
# Format in brief: one event per line, with first space-separated
# field giving the event type and the rest of the line the
# comma-separated arguments in ROLE:TYPE format. Arguments may be
# specified as either optional (by appending "?" to role) or repeated
# (by appending either "*" for "0 or more" or "+" for "1 or more").
# this is a macro definition, used for brevity
<POG>=Person|Organization|GPE

# the "!" before a type specifies that it cannot be used for annotation
# (hierarchy structure only.)
!Life
	Be-born   Person-Arg:Person, Place-Arg?:GPE
	Marry     Person-Arg{2}:Person, Place-Arg?:GPE
	Divorce   Person-Arg{2}:Person, Place-Arg?:GPE
	Die       Person-Arg:Person, Agent-Arg?:<POG>, Place-Arg?:GPE
!Transaction
	Transfer-ownership  Buyer-Arg:<POG>, Seller-Arg:<POG>, Artifact-Arg:Organization
	Transfer-money	Giver-Arg:<POG>, Recipient-Arg:<POG>, Beneficiary-Arg:<POG>
!Business
	Start-org  Agent-Arg?:<POG>, Org-Arg:Organization
	Merge-org  Org-Arg{2}:Organization
	End-org    Org-Arg:Organization

• attributes:
  名称 Arg:X, Value:C1|C2|C2|…
  其中Value是可选的。
  每一行表示一个属性，可依附于事件或实体对象。

其基本的配置规则为：
a) 每一行开头为属性名；
b) 事件名称后为Tab符，Tab符后为具体的属性定义，其格式一般为Arg:，表示为事件属性，EVENT可改为ENTITY表示实体属性。
c）若改行定义直接结束，表示这是个2元属性；若为多值属性，则在Arg:后需进一步补充,Value:值1|值2|值3。

[attributes]
# Definition of entity and event attributes.
# Format in brief: first tab-separated field is attribute name, second
# a set of key-value pairs. The latter must define "Arg:" which
# specifies what the attribute can attach to (typically "<EVENT>").
# If no other keys are defined, the attribute is binary (present or
# absent). If "Value:" with multiple alternatives is defined, the
# attribute can have one of the given values.
Negation     Arg:<EVENT>
Confidence   Arg:<EVENT>, Value:High|Neutral|Low

• kb_shortcuts.conf:
  为每个标记提供一个键盘快捷键，只有两列内容，第一列是键，第二列是对应的标记。

visual.conf:
影响可视化效果，分为[label]、[drawing]两部分

• label:
  给标记添加别名，如果全名无法展示，会依次尝试别名
  名称|别名1|别名2|…
  用于定义实体、关系、事件和属性等对象的显示标签，常用于显示中文标签（原始annotation.conf 文件为英文时）或防止原始各对象的名称过程而难以显示。

[labels]
### Entity types
Person | Person
Organization | Organization | Org
GPE | Geo-political entity | GPE

• drawing:
  控制显示样式，类似css，也是key-value对，有很多属性。
  名称 key1:value1, key2:value2, …
  主要应该就是改一下点的bgColor。
  如果要做更复杂的事情，比如去掉边的箭头、改成虚线等等也可以做，许多属性似乎可以在SVG上找到类似的说明。

用于定义实体、关系、事件和属性等对象的显示颜色，以在webserver标注时予以区分。

Person	bgColor:#ffccaa
Organization	bgColor:#8fb2ff
GPE	bgColor:#7fe2ff

• tools.conf:
  这个文件决定了平台可以帮助你自动完成的事以及只允许你让他帮你完成的事，包括要不要检查数据格式，如何分词，断行甚至选中的文本可以用什么搜索引擎去查询等。在配有适当外部工具的前提下，也可以自动生成基本的标注。

ana文件的基本解读
一个典型的标注好的ana结果文件如下：
T1 人名 11 13 马云
T2 地点 16 18 杭州
R1 来自 Arg1:T1 Arg2:T2
T3 人名 23 25 马云
T4 时间 0 10 1964年9月10日
T5 人名 61 63 父亲
T6 人名 81 83 马云
T7 地点 69 71 江南
T8 人名 99 101 金庸
T9 人名 129 131 马云

• 家属 T3 T5
  T10 人名 86 88 父亲
  R2 来自 Arg1:T5 Arg2:T7
• 家属 T6 T10
  每一行表示标注好的实体、关系、事件或属性对象。

对于实体对象，其共有5个字段，各字段间用空格区分，其意义依次为：
（1）编号，如T1表示编号为1的实体；
（2）实体类型，如人名;
（3）该实体在整个文本中的起始位置；
（4）该实体在整个文本中的终止位置；
（5）实体对应的文本。

值得注意的是：整个文本的顺序为各行文本的拼接（保留\n等符号），整个文本的起始位置编号为0，起始位置->终止位置采用左开右闭的对应关系（可理解为切片），如[11, 13]表示占用11、12两个位置。

对于单向关系对象，包括4个字段，其意义依次为：
（1）编号，如R1表示编号为1的关系；
（2）关系类型，如地点;
（3）关系起始实体编码，如Arg1:T1
（4）关系指向实体编码，如Arg2:T2

对于双向关系对象，也包括4个字段，其意义依次为：
（1）*号
（2）关系类型，如家属;
（3）关系起始实体编码，如T3
（4）关系指向实体编码，如T5

对ana进行解析，就可以开展下游的自然语言处理任务。