{"id":13737390,"url":"https://github.com/dobraczka/kiez","last_synced_at":"2026-03-02T08:32:20.070Z","repository":{"id":48042651,"uuid":"368189197","full_name":"dobraczka/kiez","owner":"dobraczka","description":"🏘️ Hubness reduced nearest neighbor search for entity alignment with knowledge graph embeddings","archived":false,"fork":false,"pushed_at":"2024-04-23T11:05:01.000Z","size":925,"stargazers_count":25,"open_issues_count":5,"forks_count":3,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-16T19:21:39.319Z","etag":null,"topics":["approximate-nearest-neighbor-search","embedding","entity-alignment","entity-resolution","hubness","knowledge-graph","knowledge-graph-embedding","nearest-neighbors"],"latest_commit_sha":null,"homepage":"https://kiez.readthedocs.io/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dobraczka.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-05-17T13:08:09.000Z","updated_at":"2025-02-27T23:10:18.000Z","dependencies_parsed_at":"2023-02-06T02:46:43.291Z","dependency_job_id":"c69ee9fc-45ff-48f6-9961-2fcbd315811a","html_url":"https://github.com/dobraczka/kiez","commit_stats":{"total_commits":137,"total_committers":3,"mean_commits":"45.666666666666664","dds":0.1021897810218978,"last_synced_commit":"d90c57fe2b307de5232b23b959cda43c1ff4ea7f"},"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dobraczka%2Fkiez","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dobraczka%2Fkiez/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dobraczka%2Fkiez/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dobraczka%2Fkiez/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dobraczka","download_url":"https://codeload.github.com/dobraczka/kiez/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249305037,"owners_count":21247955,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["approximate-nearest-neighbor-search","embedding","entity-alignment","entity-resolution","hubness","knowledge-graph","knowledge-graph-embedding","nearest-neighbors"],"created_at":"2024-08-03T03:01:46.120Z","updated_at":"2026-03-02T08:32:15.044Z","avatar_url":"https://github.com/dobraczka.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n\u003cimg src=\"https://github.com/dobraczka/kiez/raw/main/docs/kiezlogo.png\" alt=\"kiez logo\", width=200/\u003e\n\u003c/p\u003e\n\n\u003ch2 align=\"center\"\u003e \u003ca href=\"https://dbs.uni-leipzig.de/file/KIEZ_KEOD_2021_Obraczka_Rahm.pdf\"\u003ekiez\u003c/a\u003e\u003c/h2\u003e\n\n\u003cp align=\"center\"\u003e\n\u003ca href=\"https://github.com/dobraczka/kiez/actions/workflows/main.yml\"\u003e\u003cimg alt=\"Actions Status\" src=\"https://github.com/dobraczka/kiez/actions/workflows/main.yml/badge.svg?branch=main\"\u003e\u003c/a\u003e\n\u003ca href='https://kiez.readthedocs.io/en/latest/?badge=latest'\u003e\u003cimg src='https://readthedocs.org/projects/kiez/badge/?version=latest' alt='Documentation Status' /\u003e\u003c/a\u003e\n\u003ca href=\"https://pypi.org/project/kiez\"/\u003e\u003cimg alt=\"Stable python versions\" src=\"https://img.shields.io/pypi/pyversions/kiez\"\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/dobraczka/kiez/blob/main/LICENSE\"\u003e\u003cimg alt=\"License BSD3 - Clause\" src=\"https://img.shields.io/badge/license-BSD--3--Clause-blue\"\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/astral-sh/ruff\"\u003e\u003cimg alt=\"Code style: ruff\" src=\"https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\nA Python library for hubness reduced nearest neighbor search for the task of entity alignment with knowledge graph embeddings. The term kiez is a [german word](https://en.wikipedia.org/wiki/Kiez) that refers to a city neighborhood.\n\n## Hubness Reduction\nHubness is a phenomenon that arises in high-dimensional data and describes the fact that a couple of entities are nearest neighbors (NN) of many other entities, while a lot of entities are NN to no one.\nFor entity alignment with knowledge graph embeddings we rely on NN search. Hubness therefore is detrimental to our matching results.\nThis library is intended to make hubness reduction techniques available to data integration projects that rely on (knowledge graph) embeddings in their alignment process. Furthermore kiez incorporates several approximate nearest neighbor (ANN) libraries, to pair the speed advantage of approximate neighbor search with increased accuracy of hubness reduction.\n\n## Installation\nYou can install kiez via pip:\n``` bash\npip install kiez\n```\n\nIf you have a GPU you can make kiez faster by installing [faiss](https://github.com/facebookresearch/faiss) (if you do not already have it in your environment):\n\n``` bash\nconda env create -n kiez-faiss python=3.10\nconda activate kiez-faiss\nconda install -c pytorch -c nvidia faiss-gpu=1.7.4 mkl=2021 blas=1.0=mkl\npip install kiez\n```\n\nFor more information see their [installation instructions](https://github.com/facebookresearch/faiss/blob/main/INSTALL.md).\n\nYou can also get other specific libraries with e.g.:\n\n``` bash\n  pip install kiez[nmslib]\n```\n\n## Usage\nSimple nearest neighbor search for source entities in target space:\n``` python\nfrom kiez import Kiez\nimport numpy as np\n# create example data\nrng = np.random.RandomState(0)\nsource = rng.rand(100,50)\ntarget = rng.rand(100,50)\n# fit and get neighbors\nk_inst = Kiez()\nk_inst.fit(source, target)\nnn_dist, nn_ind = k_inst.kneighbors(5)\n```\nUsing (A)NN libraries and hubness reduction methods:\n``` python\nfrom kiez import Kiez\nimport numpy as np\n# create example data\nrng = np.random.RandomState(0)\nsource = rng.rand(100,50)\ntarget = rng.rand(100,50)\n# prepare algorithm and hubness reduction\nk_inst = Kiez(n_candidates=10, algorithm=\"Faiss\", hubness=\"CSLS\")\n# fit and get neighbors\nk_inst.fit(source, target)\nnn_dist, nn_ind = k_inst.kneighbors(5)\n```\n\n## Torch Support\nBeginning with version 0.5.0 torch can be used, when using `Faiss` as NN library:\n\n```python\n    from kiez import Kiez\n    import torch\n    source = torch.randn((100,10))\n    target = torch.randn((200,10))\n    k_inst = Kiez(algorithm=\"Faiss\", hubness=\"CSLS\")\n    k_inst.fit(source, target)\n    nn_dist, nn_ind = k_inst.kneighbors()\n```\n\nYou can also utilize tensor on the GPU:\n\n```python\n    k_inst = Kiez(algorithm=\"Faiss\", algorithm_kwargs={\"use_gpu\":True}, hubness=\"CSLS\")\n    k_inst.fit(source.cuda(), target.cuda())\n    nn_dist, nn_ind = k_inst.kneighbors()\n```\n\n## Documentation\nYou can find more documentation on [readthedocs](https://kiez.readthedocs.io)\n\n## Benchmark\nThe results and configurations of our experiments can be found in a seperate [benchmarking repository](https://github.com/dobraczka/kiez-benchmarking)\n\n## Citation\nIf you find this work useful you can use the following citation:\n```\n@article{obraczka2022fast,\n  title={Fast Hubness-Reduced Nearest Neighbor Search for Entity Alignment in Knowledge Graphs},\n  author={Obraczka, Daniel and Rahm, Erhard},\n  journal={SN Computer Science},\n  volume={3},\n  number={6},\n  pages={1--19},\n  year={2022},\n  publisher={Springer},\n  url={https://link.springer.com/article/10.1007/s42979-022-01417-1},\n  doi={10.1007/s42979-022-01417-1},\n}\n```\n\n## Contributing\nPRs and enhancement ideas are always welcome. If you want to build kiez locally use:\n```bash\ngit clone git@github.com:dobraczka/kiez.git\ncd kiez\npoetry install\n```\nTo run the tests (given you are in the kiez folder):\n```bash\npoetry run pytest tests\n```\n\nOr install [nox](https://github.com/theacodes/nox) and run:\n```\nnox\n```\nwhich checks all the linting as well.\n\n## License\n`kiez` is licensed under the terms of the BSD-3-Clause [license](LICENSE.txt).\nSeveral files were modified from [`scikit-hubness`](https://github.com/VarIr/scikit-hubness),\ndistributed under the same [license](external/SCIKIT_HUBNESS_LICENSE.txt).\nThe respective files contain the following tag instead of the full license text.\n\n        SPDX-License-Identifier: BSD-3-Clause\n\nThis enables machine processing of license information based on the SPDX\nLicense Identifiers that are here available: https://spdx.org/licenses/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdobraczka%2Fkiez","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdobraczka%2Fkiez","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdobraczka%2Fkiez/lists"}