prase 1.0.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- prase-1.0.0/.github/workflows/wheels.yml +136 -0
- prase-1.0.0/.gitignore +16 -0
- prase-1.0.0/CMakeLists.txt +24 -0
- prase-1.0.0/LICENSE +21 -0
- prase-1.0.0/PKG-INFO +465 -0
- prase-1.0.0/README.md +445 -0
- prase-1.0.0/benchmarks/experiments.toml +272 -0
- prase-1.0.0/benchmarks/reproduce.py +442 -0
- prase-1.0.0/cpp/bindings.cpp +136 -0
- prase-1.0.0/cpp/paris.cpp +298 -0
- prase-1.0.0/cpp/paris.hpp +93 -0
- prase-1.0.0/pyproject.toml +39 -0
- prase-1.0.0/src/prase/__init__.py +32 -0
- prase-1.0.0/src/prase/__main__.py +5 -0
- prase-1.0.0/src/prase/_benchmark_manifest.toml +134 -0
- prase-1.0.0/src/prase/alignment.py +132 -0
- prase-1.0.0/src/prase/baselines.py +220 -0
- prase-1.0.0/src/prase/cli.py +118 -0
- prase-1.0.0/src/prase/config.py +284 -0
- prase-1.0.0/src/prase/datasets.py +285 -0
- prase-1.0.0/src/prase/decisions.py +107 -0
- prase-1.0.0/src/prase/embedding/__init__.py +70 -0
- prase-1.0.0/src/prase/embedding/base.py +294 -0
- prase-1.0.0/src/prase/embedding/bootea.py +370 -0
- prase-1.0.0/src/prase/embedding/common.py +261 -0
- prase-1.0.0/src/prase/embedding/gcnalign.py +197 -0
- prase-1.0.0/src/prase/embedding/imuse.py +329 -0
- prase-1.0.0/src/prase/embedding/iptranse.py +373 -0
- prase-1.0.0/src/prase/embedding/mtranse.py +121 -0
- prase-1.0.0/src/prase/embedding/multike.py +574 -0
- prase-1.0.0/src/prase/errors.py +13 -0
- prase-1.0.0/src/prase/kg.py +267 -0
- prase-1.0.0/src/prase/methods.py +76 -0
- prase-1.0.0/src/prase/metrics.py +72 -0
- prase-1.0.0/src/prase/paris/__init__.py +283 -0
- prase-1.0.0/src/prase/paris/native.py +98 -0
- prase-1.0.0/src/prase/paris/python.py +236 -0
- prase-1.0.0/src/prase/paris/state.py +137 -0
- prase-1.0.0/src/prase/pipeline.py +371 -0
- prase-1.0.0/src/prase/records.py +148 -0
- prase-1.0.0/src/prase/session.py +151 -0
- prase-1.0.0/src/prase/tsv.py +47 -0
- prase-1.0.0/tests/fixed_model.py +34 -0
- prase-1.0.0/tests/fixtures.py +59 -0
- prase-1.0.0/tests/test_benchmarks.py +120 -0
- prase-1.0.0/tests/test_data.py +261 -0
- prase-1.0.0/tests/test_embedding.py +270 -0
- prase-1.0.0/tests/test_paris.py +130 -0
- prase-1.0.0/tests/test_pipeline.py +380 -0
- prase-1.0.0/tests/test_review.py +213 -0
- prase-1.0.0/tests/test_session.py +99 -0
- prase-1.0.0/tests/wheel_smoke.py +20 -0
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
name: Build and test wheels
|
|
2
|
+
|
|
3
|
+
# Every push and pull request builds and tests the wheels and the sdist.
|
|
4
|
+
# A manual run (workflow_dispatch) also uploads them to TestPyPI.
|
|
5
|
+
# A v* tag also uploads them to PyPI and creates a GitHub Release.
|
|
6
|
+
|
|
7
|
+
on:
|
|
8
|
+
push:
|
|
9
|
+
pull_request:
|
|
10
|
+
workflow_dispatch:
|
|
11
|
+
|
|
12
|
+
permissions:
|
|
13
|
+
contents: read
|
|
14
|
+
|
|
15
|
+
jobs:
|
|
16
|
+
wheels:
|
|
17
|
+
name: Wheels (${{ matrix.os }}, ${{ matrix.arch }})
|
|
18
|
+
strategy:
|
|
19
|
+
fail-fast: false
|
|
20
|
+
matrix:
|
|
21
|
+
include:
|
|
22
|
+
- os: ubuntu-latest
|
|
23
|
+
arch: x86_64
|
|
24
|
+
- os: ubuntu-24.04-arm
|
|
25
|
+
arch: aarch64
|
|
26
|
+
- os: windows-latest
|
|
27
|
+
arch: AMD64
|
|
28
|
+
- os: macos-latest
|
|
29
|
+
arch: arm64
|
|
30
|
+
runs-on: ${{ matrix.os }}
|
|
31
|
+
steps:
|
|
32
|
+
- uses: actions/checkout@v4
|
|
33
|
+
- uses: actions/setup-python@v5
|
|
34
|
+
with:
|
|
35
|
+
python-version: "3.12"
|
|
36
|
+
- run: python -m pip install "cibuildwheel==4.3.5"
|
|
37
|
+
- run: python -m cibuildwheel --output-dir wheelhouse
|
|
38
|
+
env:
|
|
39
|
+
CIBW_ARCHS: ${{ matrix.arch }}
|
|
40
|
+
- uses: actions/upload-artifact@v4
|
|
41
|
+
with:
|
|
42
|
+
name: wheels-${{ matrix.os }}-${{ matrix.arch }}
|
|
43
|
+
path: wheelhouse/*.whl
|
|
44
|
+
|
|
45
|
+
sdist:
|
|
46
|
+
name: Source distribution
|
|
47
|
+
runs-on: ubuntu-latest
|
|
48
|
+
steps:
|
|
49
|
+
- uses: actions/checkout@v4
|
|
50
|
+
- uses: actions/setup-python@v5
|
|
51
|
+
with:
|
|
52
|
+
python-version: "3.12"
|
|
53
|
+
- run: python -m pip install build
|
|
54
|
+
- run: python -m build --sdist
|
|
55
|
+
# Install from the sdist alone, compiling the native engine, then run the tests.
|
|
56
|
+
- run: python -m pip install "$(ls dist/*.tar.gz)[rdf]"
|
|
57
|
+
- run: python tests/wheel_smoke.py
|
|
58
|
+
- run: python -m unittest discover -s tests -v
|
|
59
|
+
- uses: actions/upload-artifact@v4
|
|
60
|
+
with:
|
|
61
|
+
name: sdist
|
|
62
|
+
path: dist/*.tar.gz
|
|
63
|
+
|
|
64
|
+
check-version:
|
|
65
|
+
name: Check the release version
|
|
66
|
+
if: startsWith(github.ref, 'refs/tags/v')
|
|
67
|
+
runs-on: ubuntu-latest
|
|
68
|
+
steps:
|
|
69
|
+
- uses: actions/checkout@v4
|
|
70
|
+
- uses: actions/setup-python@v5
|
|
71
|
+
with:
|
|
72
|
+
python-version: "3.12"
|
|
73
|
+
- name: Compare the tag with the version in pyproject.toml
|
|
74
|
+
run: |
|
|
75
|
+
version=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])")
|
|
76
|
+
if [ "v$version" != "$GITHUB_REF_NAME" ]; then
|
|
77
|
+
echo "::error::Tag $GITHUB_REF_NAME does not match version $version in pyproject.toml"
|
|
78
|
+
exit 1
|
|
79
|
+
fi
|
|
80
|
+
|
|
81
|
+
publish-testpypi:
|
|
82
|
+
name: Publish to TestPyPI
|
|
83
|
+
if: github.event_name == 'workflow_dispatch'
|
|
84
|
+
needs: [wheels, sdist]
|
|
85
|
+
runs-on: ubuntu-latest
|
|
86
|
+
environment:
|
|
87
|
+
name: testpypi
|
|
88
|
+
url: https://test.pypi.org/project/prase/
|
|
89
|
+
permissions:
|
|
90
|
+
id-token: write
|
|
91
|
+
steps:
|
|
92
|
+
- uses: actions/download-artifact@v4
|
|
93
|
+
with:
|
|
94
|
+
path: dist
|
|
95
|
+
merge-multiple: true
|
|
96
|
+
- uses: pypa/gh-action-pypi-publish@release/v1
|
|
97
|
+
with:
|
|
98
|
+
repository-url: https://test.pypi.org/legacy/
|
|
99
|
+
skip-existing: true
|
|
100
|
+
|
|
101
|
+
publish-pypi:
|
|
102
|
+
name: Publish to PyPI
|
|
103
|
+
if: startsWith(github.ref, 'refs/tags/v')
|
|
104
|
+
needs: [wheels, sdist, check-version]
|
|
105
|
+
runs-on: ubuntu-latest
|
|
106
|
+
environment:
|
|
107
|
+
name: pypi
|
|
108
|
+
url: https://pypi.org/project/prase/
|
|
109
|
+
permissions:
|
|
110
|
+
id-token: write
|
|
111
|
+
steps:
|
|
112
|
+
- uses: actions/download-artifact@v4
|
|
113
|
+
with:
|
|
114
|
+
path: dist
|
|
115
|
+
merge-multiple: true
|
|
116
|
+
- uses: pypa/gh-action-pypi-publish@release/v1
|
|
117
|
+
|
|
118
|
+
github-release:
|
|
119
|
+
name: Create the GitHub Release
|
|
120
|
+
needs: publish-pypi
|
|
121
|
+
runs-on: ubuntu-latest
|
|
122
|
+
permissions:
|
|
123
|
+
contents: write
|
|
124
|
+
steps:
|
|
125
|
+
- uses: actions/download-artifact@v4
|
|
126
|
+
with:
|
|
127
|
+
path: dist
|
|
128
|
+
merge-multiple: true
|
|
129
|
+
- name: Attach the wheels and the sdist to a release for this tag
|
|
130
|
+
env:
|
|
131
|
+
GH_TOKEN: ${{ github.token }}
|
|
132
|
+
run: >-
|
|
133
|
+
gh release create "$GITHUB_REF_NAME" dist/*
|
|
134
|
+
--repo "$GITHUB_REPOSITORY"
|
|
135
|
+
--title "PRASE ${GITHUB_REF_NAME#v}"
|
|
136
|
+
--generate-notes
|
prase-1.0.0/.gitignore
ADDED
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
cmake_minimum_required(VERSION 3.18)
|
|
2
|
+
project(prase LANGUAGES NONE)
|
|
3
|
+
|
|
4
|
+
option(PRASE_BUILD_NATIVE "Build the PARIS native engine" ON)
|
|
5
|
+
if(NOT PRASE_BUILD_NATIVE)
|
|
6
|
+
return()
|
|
7
|
+
endif()
|
|
8
|
+
enable_language(CXX)
|
|
9
|
+
|
|
10
|
+
set(PYBIND11_FINDPYTHON ON)
|
|
11
|
+
find_package(Python REQUIRED COMPONENTS Interpreter Development.Module)
|
|
12
|
+
find_package(pybind11 CONFIG REQUIRED)
|
|
13
|
+
find_package(Threads REQUIRED)
|
|
14
|
+
|
|
15
|
+
pybind11_add_module(_paris NO_EXTRAS cpp/bindings.cpp cpp/paris.cpp)
|
|
16
|
+
target_compile_features(_paris PRIVATE cxx_std_17)
|
|
17
|
+
target_link_libraries(_paris PRIVATE Threads::Threads)
|
|
18
|
+
if(MSVC)
|
|
19
|
+
target_compile_options(_paris PRIVATE /fp:precise)
|
|
20
|
+
elseif(CMAKE_CXX_COMPILER_ID MATCHES "GNU|Clang")
|
|
21
|
+
target_compile_options(_paris PRIVATE -fno-fast-math -ffp-contract=off)
|
|
22
|
+
endif()
|
|
23
|
+
|
|
24
|
+
install(TARGETS _paris LIBRARY DESTINATION prase RUNTIME DESTINATION prase)
|
prase-1.0.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Zhiyuan Qi
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
prase-1.0.0/PKG-INFO
ADDED
|
@@ -0,0 +1,465 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: prase
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: Probabilistic reasoning and semantic embedding for knowledge graph alignment
|
|
5
|
+
Author: Zhiyuan Qi
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
License-File: LICENSE
|
|
8
|
+
Project-URL: Homepage, https://github.com/qizhyuan/PRASE
|
|
9
|
+
Project-URL: Repository, https://github.com/qizhyuan/PRASE
|
|
10
|
+
Requires-Python: >=3.11
|
|
11
|
+
Requires-Dist: numpy>=1.26
|
|
12
|
+
Requires-Dist: scipy>=1.11
|
|
13
|
+
Requires-Dist: huggingface_hub>=0.34
|
|
14
|
+
Provides-Extra: train
|
|
15
|
+
Requires-Dist: torch>=2.2; extra == "train"
|
|
16
|
+
Requires-Dist: rapidfuzz>=3.8; extra == "train"
|
|
17
|
+
Provides-Extra: rdf
|
|
18
|
+
Requires-Dist: rdflib>=7.1; extra == "rdf"
|
|
19
|
+
Description-Content-Type: text/markdown
|
|
20
|
+
|
|
21
|
+
# PRASE
|
|
22
|
+
|
|
23
|
+
PRASE aligns the entities of two knowledge graphs without labeled pairs. It combines probabilistic reasoning with semantic embeddings ([Qi et al., IJCAI 2021](https://www.ijcai.org/proceedings/2021/278)):
|
|
24
|
+
|
|
25
|
+
1. [PARIS](https://doi.org/10.14778/2078331.2078332) (Suchanek et al., VLDB 2011) matches entities, relations, and attributes by probabilistic reasoning over the graphs' facts and equal literals.
|
|
26
|
+
2. An embedding model trains on the confident matches, proposes counterparts for the remaining entities, and scores entity similarity.
|
|
27
|
+
3. A second PARIS pass starts from the proposed pairs and adds the embedding similarity to its evidence.
|
|
28
|
+
|
|
29
|
+
The package provides:
|
|
30
|
+
|
|
31
|
+
- PARIS reasoning with a C++ engine and a NumPy engine that give identical alignments. The PARIS authors publish their Java implementation at [dig-team/PARIS](https://github.com/dig-team/PARIS).
|
|
32
|
+
- Six embedding models in PyTorch: BootEA, GCNAlign, IMUSE, IPTransE, MTransE, and MultiKE.
|
|
33
|
+
- Pipelines built from interchangeable steps, with records of every intermediate alignment and score.
|
|
34
|
+
- Optional manual review: approved pairs stay fixed and rejected pairs are never matched.
|
|
35
|
+
- Benchmark recipes that reproduce the paper's experiments on six datasets.
|
|
36
|
+
|
|
37
|
+
The original implementation released with the IJCAI 2021 paper is on the [`legacy`](https://github.com/qizhyuan/PRASE/tree/legacy) branch.
|
|
38
|
+
|
|
39
|
+
## PRASEMap Web Application
|
|
40
|
+
|
|
41
|
+
[PRASEMap](https://prasemap.qizhy.com/) is a web application built on PRASE, first presented as a demo at
|
|
42
|
+
CIKM 2021 ([Qi et al., CIKM 2021](https://doi.org/10.1145/3459637.3481972)). In the browser you can upload
|
|
43
|
+
two graphs or choose a built-in pair, run PARIS or PRASE, and review the matches. Approved and rejected
|
|
44
|
+
pairs carry over to the next run.
|
|
45
|
+
|
|
46
|
+
## Installation
|
|
47
|
+
|
|
48
|
+
PRASE requires Python 3.11 or newer and installs from [PyPI](https://pypi.org/project/prase/):
|
|
49
|
+
|
|
50
|
+
```console
|
|
51
|
+
# PARIS, the pipelines, and the benchmark downloader.
|
|
52
|
+
python -m pip install prase
|
|
53
|
+
# PyTorch and RapidFuzz for the embedding models.
|
|
54
|
+
python -m pip install "prase[train]"
|
|
55
|
+
# RDFLib for RDF input.
|
|
56
|
+
python -m pip install "prase[rdf]"
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
The wheels for Linux (x86_64 and aarch64), Windows (x64), and macOS (Apple silicon) on Python 3.11 to 3.15 include the compiled PARIS engine. On other platforms pip builds the engine from source, which requires CMake 3.18+ and a C++17 compiler.
|
|
60
|
+
|
|
61
|
+
To install from a clone of the repository:
|
|
62
|
+
|
|
63
|
+
```console
|
|
64
|
+
git clone https://github.com/qizhyuan/PRASE.git
|
|
65
|
+
cd PRASE
|
|
66
|
+
# PARIS with the C++ engine, built from source.
|
|
67
|
+
python -m pip install .
|
|
68
|
+
# The NumPy engine alone, without building the C++ engine.
|
|
69
|
+
python -m pip install . --config-settings wheel.cmake=false
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
Embedding models train on the CPU by default. For GPU training, install the CUDA build of PyTorch that the [PyTorch installer](https://pytorch.org/get-started/locally/) selects for your system, for example:
|
|
73
|
+
|
|
74
|
+
```console
|
|
75
|
+
python -m pip install torch --index-url https://download.pytorch.org/whl/cu132
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
The examples below select the GPU with `options={"device": "cuda"}`. Run files take `device = "cuda"` in the model options, and the benchmark runner takes `--device cuda`.
|
|
79
|
+
|
|
80
|
+
## Quick Start
|
|
81
|
+
|
|
82
|
+
PARIS on two small graphs:
|
|
83
|
+
|
|
84
|
+
```python
|
|
85
|
+
from prase import KG, methods
|
|
86
|
+
|
|
87
|
+
left = KG.from_triples(
|
|
88
|
+
[("l:paris", "capital_of", "l:france")],
|
|
89
|
+
[("l:paris", "name", "Paris"), ("l:france", "name", "France")],
|
|
90
|
+
)
|
|
91
|
+
right = KG.from_triples(
|
|
92
|
+
[("r:paris", "capitalOf", "r:france")],
|
|
93
|
+
[("r:paris", "label", "Paris"), ("r:france", "label", "France")],
|
|
94
|
+
)
|
|
95
|
+
result = methods.paris().run(left, right)
|
|
96
|
+
print(result.alignment.to_ids(left, right))
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
PRASE and SE on a benchmark dataset, after [signing in to Hugging Face](#benchmarks):
|
|
100
|
+
|
|
101
|
+
```python
|
|
102
|
+
from prase import Alignment, load_benchmark, methods
|
|
103
|
+
|
|
104
|
+
# Download and verify D-W-15K-V2 on first use.
|
|
105
|
+
data = load_benchmark("D-W-15K-V2")
|
|
106
|
+
|
|
107
|
+
# PRASE: PARIS, BootEA, and PARIS again with BootEA's proposals and embeddings.
|
|
108
|
+
prase = methods.prase("bootea", options={"device": "cuda"})
|
|
109
|
+
result = prase.run(data.left, data.right, reference=data.reference())
|
|
110
|
+
print(result.scores)
|
|
111
|
+
|
|
112
|
+
# SE: GCNAlign trains on the first fold's training links and predicts the other entities.
|
|
113
|
+
fold = data.splits[0]
|
|
114
|
+
train = data.reference(fold.train)
|
|
115
|
+
se = methods.embedding_only("gcnalign", options={"device": "cuda"})
|
|
116
|
+
result = se.run(data.left, data.right, seeds=Alignment(train[:, 0], train[:, 1]),
|
|
117
|
+
reference=data.reference(fold.valid + fold.test))
|
|
118
|
+
print(result.scores)
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
## Align Your Own Graphs
|
|
122
|
+
|
|
123
|
+
Each graph consists of relation triples `head<TAB>predicate<TAB>tail` and optional attribute triples `entity<TAB>predicate<TAB>value`. A TOML run file names the inputs, the method, and the output directory:
|
|
124
|
+
|
|
125
|
+
```toml
|
|
126
|
+
# run.toml
|
|
127
|
+
[input]
|
|
128
|
+
reference = "reference.tsv" # optional pairs for evaluation
|
|
129
|
+
seeds = "seeds.tsv" # optional known pairs
|
|
130
|
+
|
|
131
|
+
[input.left]
|
|
132
|
+
relations = "left-relations.tsv"
|
|
133
|
+
attributes = "left-attributes.tsv"
|
|
134
|
+
|
|
135
|
+
[input.right]
|
|
136
|
+
relations = "right-relations.tsv"
|
|
137
|
+
attributes = "right-attributes.tsv"
|
|
138
|
+
|
|
139
|
+
[method]
|
|
140
|
+
name = "prase"
|
|
141
|
+
model = "gcnalign"
|
|
142
|
+
options = { device = "cpu" }
|
|
143
|
+
|
|
144
|
+
[output]
|
|
145
|
+
directory = "runs/my-alignment"
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
```console
|
|
149
|
+
# Align the graphs and write the results to runs/my-alignment.
|
|
150
|
+
prase run run.toml
|
|
151
|
+
# Score an alignment against the ent_links file of an OpenEA folder.
|
|
152
|
+
prase evaluate runs/my-alignment/alignment.tsv --dataset path/to/openea-folder
|
|
153
|
+
# List the embedding models.
|
|
154
|
+
prase models
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
Paths are relative to the run file. Seed and reference files have one `left<TAB>right` pair per line. Every input and method is also available in Python:
|
|
158
|
+
|
|
159
|
+
| Input | Run File | Python |
|
|
160
|
+
| --- | --- | --- |
|
|
161
|
+
| TSV triples | `relations` and `attributes` in `[input.left]` and `[input.right]` | `KG.from_tsv("left-relations.tsv", "left-attributes.tsv")` |
|
|
162
|
+
| RDF | `rdf = "left.ttl"` in `[input.left]` and `[input.right]` | `KG.from_rdf("left.ttl")` |
|
|
163
|
+
| OpenEA folder | `dataset = "path/to/folder"` in `[input]` | `load_dataset("path/to/folder")` |
|
|
164
|
+
| Benchmark dataset | `benchmark = "D-W-15K-V2"` in `[input]` | `load_benchmark("D-W-15K-V2")` |
|
|
165
|
+
|
|
166
|
+
| Method | `[method]` in a Run File | Python |
|
|
167
|
+
| --- | --- | --- |
|
|
168
|
+
| PARIS | `name = "paris"` | `methods.paris()` |
|
|
169
|
+
| PRASE | `name = "prase"`, `model = "bootea"`, `rounds = 1` | `methods.prase("bootea", rounds=1)` |
|
|
170
|
+
| SE | `name = "embedding-only"`, `model = "gcnalign"`, with `[input].seeds` | `methods.embedding_only("gcnalign")`, run with `seeds=` |
|
|
171
|
+
| STR-Match: edit similarity of names | `name = "str-match"` | `methods.name_match()` |
|
|
172
|
+
| EMB-Match: cosine of averaged name word vectors | `name = "emb-match"`, `word_vectors = "data/wiki-news-300d-1M.vec"` | `methods.name_embedding_match("data/wiki-news-300d-1M.vec")` |
|
|
173
|
+
|
|
174
|
+
The output directory holds the final alignment, the run settings, and one folder per step:
|
|
175
|
+
|
|
176
|
+
```text
|
|
177
|
+
runs/my-alignment/
|
|
178
|
+
├── alignment.tsv left ID, right ID, score
|
|
179
|
+
├── run.json settings and per-step scores
|
|
180
|
+
├── 01-paris/ alignment.tsv, predicates.tsv, step.json
|
|
181
|
+
├── 02-embed-gcnalign/ proposals.tsv, step.json with the training summary
|
|
182
|
+
└── 03-paris/ alignment.tsv, predicates.tsv, step.json
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
### Manual Review
|
|
186
|
+
|
|
187
|
+
Every method runs without review. To correct an alignment, list approved and rejected pairs in a TSV file and rerun with it into a new output directory:
|
|
188
|
+
|
|
189
|
+
```text
|
|
190
|
+
left right decision
|
|
191
|
+
http://dbpedia.org/resource/Illinois http://www.wikidata.org/entity/Q1204 approve
|
|
192
|
+
http://dbpedia.org/resource/Illinois http://www.wikidata.org/entity/Q1297 reject
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
```console
|
|
196
|
+
prase run run.toml --decisions review.tsv --output runs/my-alignment-reviewed
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
`Session` keeps the graphs indexed between PARIS runs for interactive review:
|
|
200
|
+
|
|
201
|
+
```python
|
|
202
|
+
from prase import Session, load_benchmark
|
|
203
|
+
|
|
204
|
+
data = load_benchmark("D-W-15K-V2")
|
|
205
|
+
session = Session(data.left, data.right)
|
|
206
|
+
session.run()
|
|
207
|
+
|
|
208
|
+
# PARIS matches DBpedia's Illinois to Chicago (Q1297). Illinois (Q1204) is the runner-up.
|
|
209
|
+
illinois = "http://dbpedia.org/resource/Illinois"
|
|
210
|
+
for right_id, candidate in session.candidates(illinois, limit=3):
|
|
211
|
+
print(right_id, round(candidate.score, 3))
|
|
212
|
+
|
|
213
|
+
session.approve(illinois, "http://www.wikidata.org/entity/Q1204")
|
|
214
|
+
session.fix_predicate("http://dbpedia.org/ontology/birthPlace", "http://www.wikidata.org/entity/P19")
|
|
215
|
+
session.run()
|
|
216
|
+
print(session.matches()[:5])
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
## Custom Pipelines and Models
|
|
220
|
+
|
|
221
|
+
A pipeline is a list of steps. Each step receives the current state (graphs, alignment, proposals, embeddings) and returns an updated copy. One PRASE round is `[ParisStep(), Embed(...), ParisStep()]`:
|
|
222
|
+
|
|
223
|
+
```python
|
|
224
|
+
from dataclasses import dataclass, replace
|
|
225
|
+
|
|
226
|
+
from prase import Embed, ParisConfig, ParisStep, Pipeline
|
|
227
|
+
|
|
228
|
+
|
|
229
|
+
@dataclass
|
|
230
|
+
class KeepConfident:
|
|
231
|
+
minimum: float = 0.2
|
|
232
|
+
name = "keep-confident"
|
|
233
|
+
|
|
234
|
+
def run(self, state, context):
|
|
235
|
+
alignment = state.alignment.above(self.minimum)
|
|
236
|
+
context.report(kept=len(alignment))
|
|
237
|
+
return replace(state, alignment=alignment)
|
|
238
|
+
|
|
239
|
+
|
|
240
|
+
paris = ParisConfig(iterations=10, embedding_weight=0.3)
|
|
241
|
+
pipeline = Pipeline([
|
|
242
|
+
ParisStep(paris),
|
|
243
|
+
Embed("gcnalign", options={"device": "cuda"}, seed_threshold=0.1),
|
|
244
|
+
ParisStep(paris),
|
|
245
|
+
KeepConfident(),
|
|
246
|
+
])
|
|
247
|
+
result = pipeline.run(data.left, data.right, reference=data.reference())
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
### Embedding Feedback
|
|
251
|
+
|
|
252
|
+
`Embed` trains on PARIS matches scoring at least `seed_threshold` and passes two kinds of feedback to the next `ParisStep`:
|
|
253
|
+
|
|
254
|
+
- **Proposed pairs** become starting matches. Their scores, multiplied by `proposal_weight` (default 1.0), are the starting probabilities, and PARIS replaces a pair when it finds a better counterpart.
|
|
255
|
+
- **Embeddings** enter every candidate score after the first `warmup` iterations: `(1 - embedding_weight) * structural + embedding_weight * cosine`, with `embedding_weight` defaulting to 0.2.
|
|
256
|
+
|
|
257
|
+
```python
|
|
258
|
+
ParisStep(paris, proposal_weight=0.5) # proposed pairs start at half their scores
|
|
259
|
+
ParisStep(paris, use_embeddings=False) # proposed pairs only
|
|
260
|
+
ParisStep(paris, use_proposals=False) # embedding similarity only
|
|
261
|
+
```
|
|
262
|
+
|
|
263
|
+
```toml
|
|
264
|
+
# The same settings in a run file.
|
|
265
|
+
[method]
|
|
266
|
+
name = "prase"
|
|
267
|
+
model = "bootea"
|
|
268
|
+
proposal_weight = 0.5
|
|
269
|
+
# share_embeddings = false # proposed pairs only
|
|
270
|
+
# propose = false # embedding similarity only
|
|
271
|
+
|
|
272
|
+
[method.paris]
|
|
273
|
+
embedding_weight = 0.3
|
|
274
|
+
```
|
|
275
|
+
|
|
276
|
+
### Literal Matching
|
|
277
|
+
|
|
278
|
+
PARIS starts from pairs of equal literals. A `literal_matcher` returns other scored pairs of literal indices:
|
|
279
|
+
|
|
280
|
+
```python
|
|
281
|
+
from prase import Alignment, methods
|
|
282
|
+
|
|
283
|
+
|
|
284
|
+
def casefold_literals(left, right):
|
|
285
|
+
"""Pair literals that are equal after case folding."""
|
|
286
|
+
index = {value.casefold(): j for j, value in enumerate(right.literals)}
|
|
287
|
+
return Alignment.from_pairs(
|
|
288
|
+
(i, index[value.casefold()], 1.0) for i, value in enumerate(left.literals) if value.casefold() in index
|
|
289
|
+
)
|
|
290
|
+
|
|
291
|
+
|
|
292
|
+
result = methods.paris(literal_matcher=casefold_literals).run(left, right)
|
|
293
|
+
```
|
|
294
|
+
|
|
295
|
+
### Embedding Models
|
|
296
|
+
|
|
297
|
+
An embedding model has a `name` and a method `fit(data, *, seed) -> Embeddings`. `data` holds both graphs (`data.left`, `data.right`), the seed pairs as an `(n, 2)` index array (`data.seeds`), the candidate entities of each graph (`data.candidates`), and the rejected pairs, which must not become training pairs (`data.rejected`). The optional `propose(embeddings, data) -> Alignment` chooses the proposals and should skip the rejected pairs. Without it, each candidate proposes its nearest eligible neighbor.
|
|
298
|
+
|
|
299
|
+
```python
|
|
300
|
+
# my_models.py
|
|
301
|
+
import zlib
|
|
302
|
+
|
|
303
|
+
import numpy as np
|
|
304
|
+
|
|
305
|
+
from prase import Embeddings
|
|
306
|
+
from prase.kg import entity_names
|
|
307
|
+
|
|
308
|
+
|
|
309
|
+
class NameTrigrams:
|
|
310
|
+
"""Embed each entity by the hashed character trigrams of its name."""
|
|
311
|
+
|
|
312
|
+
name = "name-trigrams"
|
|
313
|
+
|
|
314
|
+
def __init__(self, width: int = 256):
|
|
315
|
+
self.width = width
|
|
316
|
+
|
|
317
|
+
def fit(self, data, *, seed):
|
|
318
|
+
return Embeddings(self.vectors(data.left), self.vectors(data.right), "cosine")
|
|
319
|
+
|
|
320
|
+
def propose(self, embeddings, data):
|
|
321
|
+
# Propose mutual nearest neighbors instead of each entity's nearest neighbor.
|
|
322
|
+
return embeddings.reciprocal_nearest(*data.candidates, excluded=data.rejected)
|
|
323
|
+
|
|
324
|
+
def vectors(self, kg):
|
|
325
|
+
vectors = np.zeros((kg.num_entities, self.width))
|
|
326
|
+
for row, name in enumerate(entity_names(kg)):
|
|
327
|
+
text = f" {(name or '').casefold()} "
|
|
328
|
+
for start in range(len(text) - 2):
|
|
329
|
+
vectors[row, zlib.crc32(text[start:start + 3].encode()) % self.width] += 1
|
|
330
|
+
return vectors
|
|
331
|
+
```
|
|
332
|
+
|
|
333
|
+
```python
|
|
334
|
+
from my_models import NameTrigrams
|
|
335
|
+
|
|
336
|
+
result = methods.prase(NameTrigrams()).run(data.left, data.right, reference=data.reference())
|
|
337
|
+
```
|
|
338
|
+
|
|
339
|
+
### Custom Steps in Run Files
|
|
340
|
+
|
|
341
|
+
Run files list `[[steps]]` instead of `[method]` and load models and steps by import path:
|
|
342
|
+
|
|
343
|
+
```toml
|
|
344
|
+
[[steps]]
|
|
345
|
+
type = "paris"
|
|
346
|
+
|
|
347
|
+
[[steps]]
|
|
348
|
+
type = "embed"
|
|
349
|
+
model = "my_models:NameTrigrams"
|
|
350
|
+
options = { width = 512 }
|
|
351
|
+
|
|
352
|
+
[[steps]]
|
|
353
|
+
type = "paris"
|
|
354
|
+
embedding_weight = 0.3
|
|
355
|
+
|
|
356
|
+
# KeepConfident from the pipeline example, saved in my_steps.py.
|
|
357
|
+
[[steps]]
|
|
358
|
+
type = "my_steps:KeepConfident"
|
|
359
|
+
minimum = 0.2
|
|
360
|
+
```
|
|
361
|
+
|
|
362
|
+
```console
|
|
363
|
+
# Run from the folder that holds my_models.py and my_steps.py, so that Python can import them.
|
|
364
|
+
python -m prase run run.toml
|
|
365
|
+
```
|
|
366
|
+
|
|
367
|
+
[`config.py`](https://github.com/qizhyuan/PRASE/blob/main/src/prase/config.py) documents every run-file setting.
|
|
368
|
+
|
|
369
|
+
## Benchmarks
|
|
370
|
+
|
|
371
|
+
The benchmark collection [qizhy777/prase-benchmarks](https://huggingface.co/datasets/qizhy777/prase-benchmarks) contains the six datasets of the paper: EN-FR-100K-V2, EN-DE-100K-V2, D-W-100K-V2, D-Y-100K-V2, and D-W-15K-V2 from [OpenEA](https://github.com/nju-websoft/OpenEA), and MED-BBK-9K from [industry-eval-EA](https://github.com/ZihengZZH/industry-eval-EA). PRASE pins a revision of the collection and checks the SHA-256 of every file it downloads. Downloads require a Hugging Face account with read access to the collection. The `hf` command comes with PRASE:
|
|
372
|
+
|
|
373
|
+
```console
|
|
374
|
+
# Sign in with an access token from https://huggingface.co/settings/tokens.
|
|
375
|
+
hf auth login
|
|
376
|
+
# Download and verify all six datasets into the Hugging Face cache.
|
|
377
|
+
prase download
|
|
378
|
+
# Or download some of them.
|
|
379
|
+
prase download D-W-15K-V2 MED-BBK-9K
|
|
380
|
+
```
|
|
381
|
+
|
|
382
|
+
MultiKE and EMB-Match read the English FastText vectors [wiki-news-300d-1M.vec](https://fasttext.cc/docs/en/english-vectors.html):
|
|
383
|
+
|
|
384
|
+
```console
|
|
385
|
+
# Download the 682 MB archive, extract the vectors into data/, and check their SHA-256.
|
|
386
|
+
prase download --word-vectors
|
|
387
|
+
# Or extract them into another folder.
|
|
388
|
+
prase download --word-vectors --vectors-dir path/to/vectors
|
|
389
|
+
```
|
|
390
|
+
|
|
391
|
+
To fetch the vectors by hand:
|
|
392
|
+
|
|
393
|
+
```console
|
|
394
|
+
curl -O https://dl.fbaipublicfiles.com/fasttext/vectors-english/wiki-news-300d-1M.vec.zip
|
|
395
|
+
python -m zipfile -e wiki-news-300d-1M.vec.zip data
|
|
396
|
+
```
|
|
397
|
+
|
|
398
|
+
`benchmarks/reproduce.py` runs the recipes in [`benchmarks/experiments.toml`](https://github.com/qizhyuan/PRASE/blob/main/benchmarks/experiments.toml) and writes each run to `<output>/<experiment>/<dataset>/`. A run stops when its folder already holds a run, so give each reproduction a new `--output` directory and pass the same directory to `list` and `report`. The script and the recipes are in the repository:
|
|
399
|
+
|
|
400
|
+
```console
|
|
401
|
+
# Get the benchmark scripts and install PRASE with the embedding models.
|
|
402
|
+
git clone https://github.com/qizhyuan/PRASE.git
|
|
403
|
+
cd PRASE
|
|
404
|
+
python -m pip install "prase[train]"
|
|
405
|
+
# PARIS on every dataset.
|
|
406
|
+
python benchmarks/reproduce.py run --method paris --all-datasets --output runs/reproduction
|
|
407
|
+
# PRASE with BootEA and with MultiKE on every dataset.
|
|
408
|
+
python benchmarks/reproduce.py run --method prase --model bootea --all-datasets --device cuda --output runs/reproduction
|
|
409
|
+
python benchmarks/reproduce.py run --method prase --model multike --all-datasets --device cuda --word-vectors data/wiki-news-300d-1M.vec --output runs/reproduction
|
|
410
|
+
# SE: train on the benchmark folds and rank the test links.
|
|
411
|
+
python benchmarks/reproduce.py run --method se --model gcnalign --dataset D-W-15K-V2 --output runs/reproduction
|
|
412
|
+
# One recipe by name, such as PRASE-BootEA with proposed pairs only.
|
|
413
|
+
python benchmarks/reproduce.py run --experiment prase-bootea-m --all-datasets --device cuda --output runs/reproduction
|
|
414
|
+
# Every recipe and its status, including the feedback ablations, round sweeps, and name-matching baselines.
|
|
415
|
+
python benchmarks/reproduce.py list --output runs/reproduction
|
|
416
|
+
# Tabulate the completed runs.
|
|
417
|
+
python benchmarks/reproduce.py report runs/reproduction
|
|
418
|
+
# The entire suite in its own directory.
|
|
419
|
+
python benchmarks/reproduce.py run --all --device cuda --word-vectors data/wiki-news-300d-1M.vec --output runs/full-suite
|
|
420
|
+
```
|
|
421
|
+
|
|
422
|
+
### Results
|
|
423
|
+
|
|
424
|
+
F1 of the final alignment with one PRASE round, seed 0, and embedding training on an NVIDIA RTX 5090. Embedding training is not bit-for-bit reproducible, so scores vary slightly from run to run. The values in parentheses are from the paper.
|
|
425
|
+
|
|
426
|
+
| Dataset | PARIS | PRASE-BootEA | PRASE-MultiKE |
|
|
427
|
+
| --- | --- | --- | --- |
|
|
428
|
+
| EN-FR-100K-V2 | 0.933 (0.926) | 0.954 (0.954) | 0.962 (0.954) |
|
|
429
|
+
| EN-DE-100K-V2 | 0.952 (0.948) | 0.966 (0.965) | 0.977 (0.972) |
|
|
430
|
+
| D-W-100K-V2 | 0.864 (0.854) | 0.891 (0.890) | 0.868 (0.859) |
|
|
431
|
+
| D-Y-100K-V2 | 0.986 (0.983) | 0.994 (0.993) | 0.998 (0.996) |
|
|
432
|
+
| D-W-15K-V2 | 0.905 (0.897) | 0.917 (0.923) | 0.911 (0.907) |
|
|
433
|
+
| MED-BBK-9K | 0.498 (0.499) | 0.578 (0.557) | 0.728 (0.711) |
|
|
434
|
+
|
|
435
|
+
## Citation
|
|
436
|
+
|
|
437
|
+
If you use PRASE, please cite:
|
|
438
|
+
|
|
439
|
+
```bibtex
|
|
440
|
+
@inproceedings{qi2021prase,
|
|
441
|
+
title = {Unsupervised Knowledge Graph Alignment by Probabilistic Reasoning and Semantic Embedding},
|
|
442
|
+
author = {Qi, Zhiyuan and Zhang, Ziheng and Chen, Jiaoyan and Chen, Xi and Xiang, Yuejia and Zhang, Ningyu and Zheng, Yefeng},
|
|
443
|
+
booktitle = {Proceedings of the Thirtieth International Joint Conference on Artificial Intelligence},
|
|
444
|
+
publisher = {International Joint Conferences on Artificial Intelligence Organization},
|
|
445
|
+
pages = {2019--2025},
|
|
446
|
+
year = {2021},
|
|
447
|
+
doi = {10.24963/ijcai.2021/278},
|
|
448
|
+
url = {https://doi.org/10.24963/ijcai.2021/278}
|
|
449
|
+
}
|
|
450
|
+
|
|
451
|
+
@inproceedings{qi2021prasemap,
|
|
452
|
+
title = {{PRASEMap}: A Probabilistic Reasoning and Semantic Embedding based Knowledge Graph Alignment System},
|
|
453
|
+
author = {Qi, Zhiyuan and Zhang, Ziheng and Chen, Jiaoyan and Chen, Xi and Zheng, Yefeng},
|
|
454
|
+
booktitle = {Proceedings of the 30th ACM International Conference on Information \& Knowledge Management},
|
|
455
|
+
publisher = {Association for Computing Machinery},
|
|
456
|
+
pages = {4779--4783},
|
|
457
|
+
year = {2021},
|
|
458
|
+
doi = {10.1145/3459637.3481972},
|
|
459
|
+
url = {https://doi.org/10.1145/3459637.3481972}
|
|
460
|
+
}
|
|
461
|
+
```
|
|
462
|
+
|
|
463
|
+
## License
|
|
464
|
+
|
|
465
|
+
PRASE is released under the [MIT License](LICENSE).
|