quantulum3

这是一个Python库，用于从非结构化文本中提取数量、测量值及其单位的信息。它能够基于相似单位在GloVe向量表示中的k近邻和它们的维基百科页面来消除歧义。

这是Marco Lagi原始版本的grhawks分支的recastrodiaz分支的Python 3兼容分支。 与最新版本sklearn的兼容性基于sohrabtowfighi的分支。

用户指南

安装

pip install quantulum3

要安装用于使用或训练消歧分类器的依赖项，请使用

pip install quantulum3[classifier]

当解析器找到两个或更多匹配文本的单位时，会使用消歧分类器。

使用方法

>>> from quantulum3 import parser
>>> quants = parser.parse('我想要2升葡萄酒')
>>> quants
[Quantity(2, 'litre')]

Quantity类存储了它从中提取的原始文本表面形式，以及匹配的(开始,结束)位置：

>>> quants[0].surface
u'2升'
>>> quants[0].span
(7, 15)

value属性提供解析后的数值，unit.name属性提供解析后的单位名称：

>>> quants[0].value
2.0
>>> quants[0].unit.name
'litre'

还提供了一个内联解析器，可以在文本中嵌入解析后的数量（特别适用于调试）：

>>> print parser.inline_parse('我想要2升葡萄酒')
我想要2升 {Quantity(2, "litre")} 葡萄酒

由于解析器也能解析无量纲数字， 这个库也可以用于简单的数字提取。

>>> print parser.parse('我想要两个')
[Quantity(2, 'dimensionless')]

单位和实体

所有单位（如升）及其关联的实体（如体积）都与维基百科进行了协调：

>>> quants[0].unit
Unit(name="litre", entity=Entity("volume"), uri=https://en.wikipedia.org/wiki/Litre)

>>> quants[0].unit.entity
Entity(name="volume", uri=https://en.wikipedia.org/wiki/Volume)

这个库包含超过290个单位和75个实体。它还可以解析拼写出的数字、范围和不确定性：

>>> parser.parse('我想要一加仑啤酒')
[Quantity(1, 'gallon')]

>>> parser.parse('LHC以12.8–13.0 TeV的能量对质子束进行碰撞')
[Quantity(12.8, "teraelectronvolt"), Quantity(13, "teraelectronvolt")]

>>> quant = parser.parse('LHC以12.9±0.1 TeV的能量对质子束进行碰撞')
>>> quant[0].uncertainty
0.1

非标准单位通常没有维基百科页面。解析器仍会尝试根据它们的维度猜测其基础实体：

>>> parser.parse('声音以0.34 km/s的速度传播')[0].unit
Unit(name="kilometre per second", entity=Entity("speed"), uri=None)

导出/导入

实体、单位和数量可以导出为字典和JSON字符串：

>>> quant = parser.parse('我想要2升葡萄酒')
>>> quant[0].to_dict()
{'value': 2.0, 'unit': 'litre', "entity": "volume", 'surface': '2升', 'span': (7, 15), 'uncertainty': None, 'lang': 'en_US'}
>>> quant[0].to_json()
'{"value": 2.0, "unit": "litre", "entity": "volume", "surface": "2升", "span": [7, 15], "uncertainty": null, "lang": "en_US"}'

默认情况下，导出的字典中只包含单位/实体名称，但可以包含这些：

>>> quant = parser.parse('我想要2升葡萄酒')
>>> quant[0].to_dict(include_unit_dict=True, include_entity_dict=True)  # 同样的参数也适用于.to_json()
{'value': 2.0, 'unit': {'name': 'litre', 'surfaces': ['cubic decimetre', 'cubic decimeter', 'litre', 'liter'], 'entity': {'name': 'volume', 'dimensions': [{'base': 'length', 'power': 3}], 'uri': 'Volume'}, 'uri': 'Litre', 'symbols': ['l', 'L', 'ltr', 'ℓ'], 'dimensions': [{'base': 'decimetre', 'power': 3}], 'original_dimensions': [{'base': 'litre', 'power': 1, 'surface': '升'}], 'currency_code': None, 'lang': 'en_US'}, 'entity': 'volume', 'surface': '2升', 'span': (7, 15), 'uncertainty': None, 'lang': 'en_US'}

类似的导出语法也适用于导出Unit和Entity对象。

你可以从字典和JSON导入Entity、Unit和Quantity对象。这要求对象在导出时使用了include_unit_dict=True和include_entity_dict=True（根据需要）：

>>> quant_dict = quant[0].to_dict(include_unit_dict=True, include_entity_dict=True)
>>> quant = Quantity.from_dict(quant_dict)
>>> ent_json = "{'name': 'volume', 'dimensions': [{'base': 'length', 'power': 3}], 'uri': 'Volume'}"
>>> ent = Entity.from_json(ent_json)

消歧

如果解析器检测到歧义，一个基于歧义单位或实体的维基百科页面的分类器会尝试猜测正确的一个：

>>> parser.parse('我在这上面花了20英镑！')
[Quantity(20, "pound sterling")]

>>> parser.parse('它的重量不超过20磅')
[Quantity(20, "pound-mass")]

或者：

>>> text = '地球的平均密度约为5.5x10-3 kg/cm³'
>>> parser.parse(text)[0].unit.entity
Entity(name="density", uri=https://en.wikipedia.org/wiki/Density)

>>> text = '大气中O₂的含量为2.98e-4 kg/升'
>>> parser.parse(text)[0].unit.entity
Entity(name="concentration", uri=https://en.wikipedia.org/wiki/Concentration)

除此之外，分类器还根据所有单位表面形式在GloVe向量表示中的距离，对最相似的词进行训练。

口语版本

Quantulum类包含将它们转换为可说出单位的方法。

>>> parser.parse("给我10e9 GW，现在！")[0].to_spoken()
一百亿千兆瓦
>>> parser.inline_parse_and_expand("现在给我$1e10，还有1 TW和0.5 J！")
现在给我一百亿美元，还有一太瓦和零点五焦耳！

操作

虽然这个库内部不能操作数量，但有许多很好的选择：

• pint
• natu
• quantities

扩展

训练分类器

如果你想自己训练分类器，你需要分类器的依赖项（参见安装）。

使用命令行中的quantulum3-training，脚本quantulum3/scripts/train.py或quantulum3.classifier中的train_classifier方法来训练分类器。

quantulum3-training --lang <语言> --data <训练文件路径.json> --output <输出文件路径.joblib>

你可以向训练命令传入多个训练文件。输出格式为joblib。

要使用你的自定义模型，将训练好的模型文件路径传递给解析器：

parser = Parser.parse(<文本>, classifier_path="模型路径.joblib")

示例训练文件可以在quantulum3/_lang/<语言>/train中找到。

如果你想创建新的或不同的similars.json，安装pymagnitude。

要从向量词表示文件中提取最近邻，使用scripts/extract_vere.py。它会自动提取每个歧义单位可能表面形式的向量表示的k个最近邻。结果邻居存储在quantulum3/similars.json中，并自动包含在训练中。

提供的文件应该是.magnitude格式，因为其他格式会先在运行时转换为.magnitude文件。查看预格式化的Magnitude格式流行词嵌入和Magnitude了解更多信息。

额外单位

可以向quantulum添加额外的实体和单位以进行解析。这些将被添加到默认的单位和实体中。以下代码为示例调用：

>>> from quantulum3.load import add_custom_unit, remove_custom_unit
>>> add_custom_unit(name="schlurp", surfaces=["slp"], entity="dimensionless")
>>> parser.parse("这个极其锋利的工具精确到0.5 slp")
[Quantity(0.5, "Unit(name="schlurp", entity=Entity("dimensionless"), uri=None)")]

add_custom_unit函数的关键字参数直接转换为要创建的单位的属性。

自定义单位和实体

可以加载完全自定义的单位和实体集。这可以通过向load_custom_units和load_custom_entities函数传递文件路径列表来实现。加载自定义单位和实体将替换通常加载的默认单位和实体。

推荐使用上下文管理器来加载数量：

>>> from quantulum3 import load, parser
>>> with load.CustomQuantities(["单位文件路径.json"], ["实体文件路径.json"]):
>>>     parser.parse("这个极其锋利的工具精确到0.5 slp")

[Quantity(0.5, "Unit(name="schlurp", entity=Entity("dimensionless"), uri=None)")]

>>> # 默认单位和实体再次被加载

但也可以手动加载自定义单位和实体：

>>> from quantulum3 import load, parser

>>> load.load_custom_units(["单位文件路径.json"])
>>> load.load_custom_entities(["实体文件路径.json"])
>>> parser.parse("这个极其锋利的工具精确到0.5 slp")

[Quantity(0.5, "Unit(name="schlurp", entity=Entity("dimensionless"), uri=None)")]

移除自定义单位和实体,加载默认单位和实体

load.reset_quantities()

有关单位和实体文件格式的更多信息,请参阅下面的开发者指南。

## 开发者指南

### 添加单位和实体

完整的单位列表请参见 *units.json*,完整的实体列表请参见 *entities.json*。添加单位的标准如下:

- 该单位有(或被重定向到)维基百科页面
- 该单位在普遍使用中(例如,不包括[前公制瑞典计量单位](https://en.wikipedia.org/wiki/Swedish_units_of_measurement#Length))。

扩展这两个文件以包含感兴趣的单位/实体很容易。以下是 *entities.json* 中一个条目的示例:

```json
"speed": {
    "dimensions": [{"base": "length", "power": 1}, {"base": "time", "power": -1}],
    "URI": "https://en.wikipedia.org/wiki/Speed"
}

• 实体的名称是其键。名称必须是唯一的。
• URI是该实体的维基百科页面的名称。(即 https://en.wikipedia.org/wiki/Speed => Speed)
• dimensions是维度,一个字典列表,每个字典都有一个base(另一个实体的名称)和一个power(可以为负的整数)。

以下是 units.json 中一个条目的示例:

"metre per second": {
    "surfaces": ["metre per second", "meter per second"],
    "entity": "speed",
    "URI": "Metre_per_second",
    "dimensions": [{"base": "metre", "power": 1}, {"base": "second", "power": -1}],
    "symbols": ["mps"]
},
"year": {
    "surfaces": [ "year", "annum" ],
    "entity": "time",
    "URI": "Year",
    "dimensions": [],
    "symbols": [ "a", "y", "yr" ],
    "prefixes": [ "k", "M", "G", "T", "P", "E" ]
}

• 单位的名称是其键。名称必须是唯一的。
• URI遵循与 entities.json 中相同的方案
• surfaces是指代该单位的字符串列表。该库会处理复数形式,无需指定。
• entity是 entities.json 中一个实体的名称
• dimensions遵循与 entities.json 中相同的模式,但base是另一个单位的名称,而不是另一个实体的名称。
• symbols是该单位可能的符号和缩写列表。
• prefixes是一个可选列表。它可以包含公制和二进制前缀,并自动生成相应的单位。如果你想添加特定内容(如不同的表面),你需要为该前缀版本单独创建一个条目。

所有字段都区分大小写。

贡献

dev 构建:

如果你想贡献,请按以下步骤操作:

1. 将此项目的分支克隆到你的工作空间
2. 在开发文件夹的根目录运行 pip install -e .。
3. pip install pipenv 和 pipenv shell
4. 在项目文件夹内运行 pipenv install --dev
5. 进行你的更改
6. 从包的根目录运行 scripts/format.sh 和 scripts/build.py。
7. 使用 python3 setup.py test 测试你的更改 (可选,推送后会自动执行)
8. 提交并推送你的更改后,创建一个拉取请求

语言支持

有一个用于语言支持的分支,名为 language_support。 通过检查 _lang 子目录中的 README 文件以及 新的 _lang.en_US 子模块中给出的函数和值, 应该能够创建自己的语言子模块。 新的语言模块应该自动被调用并可用, 既可以通过解析器函数中的 lang= 关键字参数使用, 也可以在自动单元测试中使用。

除了自己的语言子模块文件夹(即 _lang.de_DE)之外,不应该需要进行任何更改。如果在实现新语言时遇到问题,请不要犹豫,打开一个问题。