【文本标注】文本标注工具brat的使用

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

本文将依次介绍brat的安装、配置和基本使用。

1. brat的安装

1.1 基本环境配置

【系统环境】
brat只能用于linux下，若为windows系统，请安装于linux虚拟机上。

【web环境】
官方建议使用使用Apache2进行web配置，用如下命令安装apache2：

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

安装完毕后，会在 /var 目录下生成一个www/html目录，下面bart的安装路径均在其中：

cd /var/www/html

1.2 安装流程

（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文件

sudo vim /etc/apache2/apache2.conf

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

<Directory /var/www/html/brat>AllowOverride Options Indexes FileInfo LimitRequire all grantedAddType application/xhtml+xml .xhtmlAddType font/ttf .ttfOptions +ExecCGIAddHandler 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

sudo service apache2 restart

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

2. brat的基本使用

2.1 项目文件的配置

项目文件建议放在如下路径（若无，自行创建）：

cd /var/www/html/brat/data/projects

每个项目下总共有4个文件，分别为：
（1）annotation.conf 规定了项目中的所有实体、事件、关系和属性类型
（2）visual.conf 规定了annotation.conf 所有实体、事件、关系和属性类型的显示文字和颜色等配置
（3）project_name.txt 项目的语聊文本
（4）project_name.ann 标注后的结果文件

2.1.1 annotation.conf 文件的配置

（1）定义实体entities

每一行表示一个实体名称，若需要定义层次化的实体，则在下一层实体前加入Tab键。

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

（2）定义关系relations

每一行表示一条关系，定义了关系名称，以及关系双方的实体。

其基本的配置规则为：
a). 每一行开头为关系名称；
b). 关系名称后为空格，空格后为相关的实体信息，其格式为Arg1:实体1，Arg2:实体2，表示从实体1—>实体2的关系；
c) 若需要定义双向关系，则补充<REL-TYPE>: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:GPEAlias              Arg1:Person, Arg2:Person, <REL-TYPE>:symmetric-transitive

（3）定义事件events

每一行表示一个事件，定义了事件名称，以及事件参与方的实体信息。

其基本的配置规则为：
a) 每一行开头为事件名；
b) 事件名称后为空格，空格后为相关的实体信息，其格式为Arg1:实体1，Arg2:实体2
c) 可通过定义<name>=实体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.)
!LifeBe-born   Person-Arg:Person, Place-Arg?:GPEMarry     Person-Arg{2}:Person, Place-Arg?:GPEDivorce   Person-Arg{2}:Person, Place-Arg?:GPEDie       Person-Arg:Person, Agent-Arg?:<POG>, Place-Arg?:GPE
!TransactionTransfer-ownership  Buyer-Arg:<POG>, Seller-Arg:<POG>, Artifact-Arg:OrganizationTransfer-money  Giver-Arg:<POG>, Recipient-Arg:<POG>, Beneficiary-Arg:<POG>
!BusinessStart-org  Agent-Arg?:<POG>, Org-Arg:OrganizationMerge-org  Org-Arg{2}:OrganizationEnd-org    Org-Arg:Organization

（4）定义属性attributes

每一行表示一个属性，可依附于事件或实体对象。

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

2.1.2 visual.conf 文件的配置

（1）定义显示标签labels

用于定义实体、关系、事件和属性等对象的显示标签，常用于显示中文标签（原始annotation.conf 文件为英文时）或防止原始各对象的名称过程而难以显示。

其定义非常简单：

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

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

其定义非常简单：

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

2.1.3 project_name.txt 文件的配置

该文件即为需要进行标注的原始语料文件，为方便标注，一般在放入标注项目文件夹之前，建议进行文本预处理。

2.1.4 project_name.ana 文件的配置

该文件即为标注后的结果文件，随着标注过程其同步自动更新。在最开始，其为空文件。

2.2 基于webserver的文本标注

（1）访问本地brat地址；
（2）登录账号和密码；
（3）选择/var/www/html/brat/data/projects文件夹内的具体项目下的project_name.txt语料文件，开始标注；
（4）选择文本字段，弹出【实体候选框】，即可定义实体；
（5）拖动标注好的实体即可定义连接关系；
（6）双击标签，即可对标签进行修改或删除。

注意: 若显示无法加载本地文件或无法修改静态文件，一般为权限问题，修改该项目文件夹权限即可。

2.3 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进行解析，就可以开展下游的自然语言处理任务。

【Reference】：

Brat标注工具（本地）安装及使用
文本标注工具brat