# Chinese Whispers for Python
This is an implementation of the [Chinese Whispers](https://doi.org/10.3115/1654758.1654774) clustering algorithm in Python. Since this library is based on [NetworkX](https://networkx.github.io/), it is simple to use.
[![Unit Tests][github_tests_badge]][github_tests_link] [![Read the Docs][rtfd_badge]][rtfd_link] [![PyPI Version][pypi_badge]][pypi_link] [![Conda Version][conda_badge]][conda_link]
[github_tests_badge]: https://github.com/nlpub/chinese-whispers/workflows/Unit%20Tests/badge.svg?branch=master
[github_tests_link]: https://github.com/nlpub/chinese-whispers/actions?query=workflow%3A%22Unit+Tests%22
[rtfd_badge]: https://readthedocs.org/projects/chinese-whispers/badge/
[rtfd_link]: https://chinese-whispers.readthedocs.io/
[pypi_badge]: https://badge.fury.io/py/chinese-whispers.svg
[pypi_link]: https://pypi.python.org/pypi/chinese-whispers
[conda_badge]: https://img.shields.io/conda/vn/conda-forge/chinese-whispers.svg
[conda_link]: https://anaconda.org/conda-forge/chinese-whispers
## Installation
- [pip](https://pip.pypa.io/): `pip install chinese-whispers`
- [Anaconda](https://docs.conda.io/en/latest/): `conda install -c conda-forge chinese-whispers`
- [Mamba](https://mamba.readthedocs.io/): `mamba install -c conda-forge chinese-whispers`
## Usage
Given a NetworkX graph `G`, this library can [cluster](https://en.wikipedia.org/wiki/Cluster_analysis) it using the following code:
```python
from chinese_whispers import chinese_whispers
chinese_whispers(G, weighting='top', iterations=20)
```
As the result, each node of the input graph is provided with the `label` attribute that stores the cluster label.
The library also offers a convenient command-line interface (CLI) for clustering graphs represented in the ABC tab-separated format (source`\t`target`\t`weight).
```shell
# Write karate_club.tsv (just as example)
python3 -c 'import networkx as nx; nx.write_weighted_edgelist(nx.karate_club_graph(), "karate_club.tsv", delimiter="\t")'
# Using as CLI
chinese-whispers karate_club.tsv
# Using as module (same CLI as above)
python3 -mchinese_whispers karate_club.tsv
```
A more complete usage example is available in the [example notebook](https://github.com/nlpub/chinese-whispers/blob/master/example.ipynb) and at <https://nlpub.github.io/chinese-whispers/>.
In case you require higher performance, please consider our Java implementation that also includes other graph clustering algorithms: <https://github.com/nlpub/watset-java>.
## Citation
* [Ustalov, D.](https://github.com/dustalov), [Panchenko, A.](https://github.com/alexanderpanchenko), [Biemann, C.](https://www.inf.uni-hamburg.de/en/inst/ab/lt/people/chris-biemann.html), [Ponzetto, S.P.](https://www.uni-mannheim.de/dws/people/professors/prof-dr-simone-paolo-ponzetto/): [Watset: Local-Global Graph Clustering with Applications in Sense and Frame Induction](https://doi.org/10.1162/COLI_a_00354). Computational Linguistics 45(3), 423–479 (2019)
```bibtex
@article{Ustalov:19:cl,
author = {Ustalov, Dmitry and Panchenko, Alexander and Biemann, Chris and Ponzetto, Simone Paolo},
title = {{Watset: Local-Global Graph Clustering with Applications in Sense and Frame Induction}},
journal = {Computational Linguistics},
year = {2019},
volume = {45},
number = {3},
pages = {423--479},
doi = {10.1162/COLI_a_00354},
publisher = {MIT Press},
issn = {0891-2017},
language = {english},
}
```
## Copyright
Copyright (c) 2018–2023 [Dmitry Ustalov](https://github.com/dustalov). See [LICENSE](LICENSE) for details.
Raw data
{
"_id": null,
"home_page": "",
"name": "chinese-whispers",
"maintainer": "",
"docs_url": null,
"requires_python": "~=3.8",
"maintainer_email": "",
"keywords": "graph clustering,unsupervised learning,chinese whispers,cluster analysis",
"author": "Dmitry Ustalov",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/b2/20/df6df4981f937d99934bb18823d646219335ae38e399f09d96bc24f84ff1/chinese_whispers-0.8.2.post2.tar.gz",
"platform": null,
"description": "# Chinese Whispers for Python\n\nThis is an implementation of the [Chinese Whispers](https://doi.org/10.3115/1654758.1654774) clustering algorithm in Python. Since this library is based on [NetworkX](https://networkx.github.io/), it is simple to use.\n\n[![Unit Tests][github_tests_badge]][github_tests_link] [![Read the Docs][rtfd_badge]][rtfd_link] [![PyPI Version][pypi_badge]][pypi_link] [![Conda Version][conda_badge]][conda_link]\n\n[github_tests_badge]: https://github.com/nlpub/chinese-whispers/workflows/Unit%20Tests/badge.svg?branch=master\n[github_tests_link]: https://github.com/nlpub/chinese-whispers/actions?query=workflow%3A%22Unit+Tests%22\n[rtfd_badge]: https://readthedocs.org/projects/chinese-whispers/badge/\n[rtfd_link]: https://chinese-whispers.readthedocs.io/\n[pypi_badge]: https://badge.fury.io/py/chinese-whispers.svg\n[pypi_link]: https://pypi.python.org/pypi/chinese-whispers\n[conda_badge]: https://img.shields.io/conda/vn/conda-forge/chinese-whispers.svg\n[conda_link]: https://anaconda.org/conda-forge/chinese-whispers\n\n## Installation\n\n- [pip](https://pip.pypa.io/): `pip install chinese-whispers`\n- [Anaconda](https://docs.conda.io/en/latest/): `conda install -c conda-forge chinese-whispers`\n- [Mamba](https://mamba.readthedocs.io/): `mamba install -c conda-forge chinese-whispers`\n\n## Usage\n\nGiven a NetworkX graph `G`, this library can [cluster](https://en.wikipedia.org/wiki/Cluster_analysis) it using the following code:\n\n```python\nfrom chinese_whispers import chinese_whispers\nchinese_whispers(G, weighting='top', iterations=20)\n```\n\nAs the result, each node of the input graph is provided with the `label` attribute that stores the cluster label.\n\nThe library also offers a convenient command-line interface (CLI) for clustering graphs represented in the ABC tab-separated format (source`\\t`target`\\t`weight).\n\n```shell\n# Write karate_club.tsv (just as example)\npython3 -c 'import networkx as nx; nx.write_weighted_edgelist(nx.karate_club_graph(), \"karate_club.tsv\", delimiter=\"\\t\")'\n\n# Using as CLI\nchinese-whispers karate_club.tsv\n\n# Using as module (same CLI as above)\npython3 -mchinese_whispers karate_club.tsv\n```\n\nA more complete usage example is available in the [example notebook](https://github.com/nlpub/chinese-whispers/blob/master/example.ipynb) and at <https://nlpub.github.io/chinese-whispers/>.\n\nIn case you require higher performance, please consider our Java implementation that also includes other graph clustering algorithms: <https://github.com/nlpub/watset-java>.\n\n## Citation\n\n* [Ustalov, D.](https://github.com/dustalov), [Panchenko, A.](https://github.com/alexanderpanchenko), [Biemann, C.](https://www.inf.uni-hamburg.de/en/inst/ab/lt/people/chris-biemann.html), [Ponzetto, S.P.](https://www.uni-mannheim.de/dws/people/professors/prof-dr-simone-paolo-ponzetto/): [Watset: Local-Global Graph Clustering with Applications in Sense and Frame Induction](https://doi.org/10.1162/COLI_a_00354). Computational Linguistics 45(3), 423–479 (2019)\n\n```bibtex\n@article{Ustalov:19:cl,\n author = {Ustalov, Dmitry and Panchenko, Alexander and Biemann, Chris and Ponzetto, Simone Paolo},\n title = {{Watset: Local-Global Graph Clustering with Applications in Sense and Frame Induction}},\n journal = {Computational Linguistics},\n year = {2019},\n volume = {45},\n number = {3},\n pages = {423--479},\n doi = {10.1162/COLI_a_00354},\n publisher = {MIT Press},\n issn = {0891-2017},\n language = {english},\n}\n```\n\n## Copyright\n\nCopyright (c) 2018–2023 [Dmitry Ustalov](https://github.com/dustalov). See [LICENSE](LICENSE) for details.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "An implementation of the Chinese Whispers clustering algorithm.",
"version": "0.8.2.post2",
"project_urls": {
"Documentation": "https://chinese-whispers.readthedocs.io",
"Download": "https://pypi.org/project/chinese-whispers/#files",
"Homepage": "https://github.com/nlpub/chinese-whispers",
"Repository": "https://github.com/nlpub/chinese-whispers"
},
"split_keywords": [
"graph clustering",
"unsupervised learning",
"chinese whispers",
"cluster analysis"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4c83d5a27b20bc01f27444d6ff529a665e53d44f1661910196032dce23cca67e",
"md5": "1d12b33611234a3f68aa46cfd399264a",
"sha256": "9fec02158bbd148b109ed297f8e143ce6b8cdadcfbcbfcbf6a83af698bcd9529"
},
"downloads": -1,
"filename": "chinese_whispers-0.8.2.post2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1d12b33611234a3f68aa46cfd399264a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "~=3.8",
"size": 8880,
"upload_time": "2023-09-05T19:40:58",
"upload_time_iso_8601": "2023-09-05T19:40:58.309552Z",
"url": "https://files.pythonhosted.org/packages/4c/83/d5a27b20bc01f27444d6ff529a665e53d44f1661910196032dce23cca67e/chinese_whispers-0.8.2.post2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b220df6df4981f937d99934bb18823d646219335ae38e399f09d96bc24f84ff1",
"md5": "319bb71add5ac58a3137a6afc37d8efa",
"sha256": "a54e7235795dae199cadb7b94489e77f3cf6331980f6bb8e8439dd732587b1f6"
},
"downloads": -1,
"filename": "chinese_whispers-0.8.2.post2.tar.gz",
"has_sig": false,
"md5_digest": "319bb71add5ac58a3137a6afc37d8efa",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "~=3.8",
"size": 7856,
"upload_time": "2023-09-05T19:40:59",
"upload_time_iso_8601": "2023-09-05T19:40:59.898959Z",
"url": "https://files.pythonhosted.org/packages/b2/20/df6df4981f937d99934bb18823d646219335ae38e399f09d96bc24f84ff1/chinese_whispers-0.8.2.post2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-09-05 19:40:59",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "nlpub",
"github_project": "chinese-whispers",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "chinese-whispers"
}
JSON
