# `relatio`
A Python package to extract underlying narrative statements from text.
* "relatio" is Latin for "storytelling" (pronounced _reh-LOTT-ee-oh_).
* Motivated, described, and applied in "[Text Semantics Capture Political and Economic Narratives" (2021)](https://arxiv.org/abs/2108.01720).
* Interactive tutorial notebook is [here](https://colab.research.google.com/github/relatio-nlp/relatio/blob/master/tutorial/tutorial.ipynb).
* See [here](https://sites.google.com/view/trump-narratives/trump-tweet-archive) for graphical demo of system outputs.
## What can this package do?
1. Identify Agent-Verb-Patient (AVP) / Subject-Verb-Object (SVO) triplets in the text
- AVPs are obtained via Semantic Role Labeling.
- SVOs are obtained via Dependency Parsing.
- A concrete example of AVP/SVO extraction:
Original sentence: "Taxes kill jobs and hinder innovation."
Triplets: [('taxes', 'kill', 'jobs'), ('taxes','hinder','innovation')]
2. Group agents and patients into interpretable entities in two ways:
- Supervised classification of entities. Simply provide a list of entities and we will filter the triplets for you (e.g., ['Barack Obama', 'government', ...]).
- Unsupervised classification via clustering of entities. We represent agents and patients as text embeddings and cluster them via KMeans or HDBSCAN. The optimal number of topics is data-driven.
- A concrete example of a cluster:
Interpretable entity: "tax"
Related phrases: ['income tax', 'the tax rates', 'taxation in this country', etc.]
3. Visualize clusters and resulting narratives.
We currently support French and English out-of-the-box. You can also provide us with a custom SVO-extraction function for any language supported by spaCy.
## Installation
Runs on Linux and macOS (x86 platform) and it requires Python 3.7 (or 3.8) and pip.
It is highly recommended to use a virtual environment (or conda environment) for the installation.
```bash
# upgrade pip, wheel and setuptools
python -m pip install -U pip wheel setuptools
# install the package
python -m pip install -U relatio
```
In case you want to use Jupyter make sure that you have it installed in the current environment.
## Quickstart
Please see our hands-on tutorials:
* [Trump Tweet Archive](./tutorial/tutorial_english.ipynb)
* [Tweets of French Politicians](./tutorial/tutorial_french.ipynb)
## Team
`relatio` is brought to you by
* [Elliott Ash](elliottash.com), ETH Zurich
* [Germain Gauthier](https://pinchofdata.github.io/germaingauthier/), CREST
* [Andrei Plamada](https://www.linkedin.com/in/andreiplamada), ETH Zurich
* [Philine Widmer](https://philinew.github.io/), University of St.Gallen
with a special thanks for support of [ETH Scientific IT Services](https://sis.id.ethz.ch/).
If you are interested in contributing to the project please read the [Development Guide](./doc/Development.md).
## Disclaimer
Remember that this is a research tool :)
Raw data
{
"_id": null,
"home_page": "https://github.com/relatio-nlp/relatio",
"name": "relatio",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "NLP,narrative",
"author": "Andrei V. Plamada",
"author_email": "plamadaa@ethz.ch",
"download_url": "https://files.pythonhosted.org/packages/72/c1/1e2b310c584dc5349b64e886777dee5066798a57d492c1ea7a3dc3ffbb28/relatio-0.3.0.tar.gz",
"platform": null,
"description": "# `relatio`\n\nA Python package to extract underlying narrative statements from text. \n\n* \"relatio\" is Latin for \"storytelling\" (pronounced _reh-LOTT-ee-oh_).\n* Motivated, described, and applied in \"[Text Semantics Capture Political and Economic Narratives\" (2021)](https://arxiv.org/abs/2108.01720).\n* Interactive tutorial notebook is [here](https://colab.research.google.com/github/relatio-nlp/relatio/blob/master/tutorial/tutorial.ipynb).\n* See [here](https://sites.google.com/view/trump-narratives/trump-tweet-archive) for graphical demo of system outputs.\n\n## What can this package do?\n\n1. Identify Agent-Verb-Patient (AVP) / Subject-Verb-Object (SVO) triplets in the text\n\n - AVPs are obtained via Semantic Role Labeling.\n - SVOs are obtained via Dependency Parsing.\n - A concrete example of AVP/SVO extraction: \n \n Original sentence: \"Taxes kill jobs and hinder innovation.\"\n\n Triplets: [('taxes', 'kill', 'jobs'), ('taxes','hinder','innovation')]\n\n2. Group agents and patients into interpretable entities in two ways:\n\n - Supervised classification of entities. Simply provide a list of entities and we will filter the triplets for you (e.g., ['Barack Obama', 'government', ...]).\n - Unsupervised classification via clustering of entities. We represent agents and patients as text embeddings and cluster them via KMeans or HDBSCAN. The optimal number of topics is data-driven.\n - A concrete example of a cluster:\n\n Interpretable entity: \"tax\" \n Related phrases: ['income tax', 'the tax rates', 'taxation in this country', etc.]\n\n3. Visualize clusters and resulting narratives.\n\nWe currently support French and English out-of-the-box. You can also provide us with a custom SVO-extraction function for any language supported by spaCy.\n\n## Installation\n\nRuns on Linux and macOS (x86 platform) and it requires Python 3.7 (or 3.8) and pip. \nIt is highly recommended to use a virtual environment (or conda environment) for the installation.\n\n```bash\n# upgrade pip, wheel and setuptools\npython -m pip install -U pip wheel setuptools\n\n# install the package\npython -m pip install -U relatio\n```\n\nIn case you want to use Jupyter make sure that you have it installed in the current environment.\n\n## Quickstart \n\nPlease see our hands-on tutorials:\n* [Trump Tweet Archive](./tutorial/tutorial_english.ipynb)\n* [Tweets of French Politicians](./tutorial/tutorial_french.ipynb)\n\n## Team\n\n`relatio` is brought to you by\n\n* [Elliott Ash](elliottash.com), ETH Zurich\n* [Germain Gauthier](https://pinchofdata.github.io/germaingauthier/), CREST\n* [Andrei Plamada](https://www.linkedin.com/in/andreiplamada), ETH Zurich\n* [Philine Widmer](https://philinew.github.io/), University of St.Gallen\n\nwith a special thanks for support of [ETH Scientific IT Services](https://sis.id.ethz.ch/).\n\nIf you are interested in contributing to the project please read the [Development Guide](./doc/Development.md).\n\n## Disclaimer\n\nRemember that this is a research tool :)\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "A Python package to extract narrative statements from text",
"version": "0.3.0",
"split_keywords": [
"nlp",
"narrative"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3bc10b76648b2f6f6bc101110e6eb48d438f6771d585c179cd74bd3026e60d0e",
"md5": "40a1d0b38dd96eacedaac275241511cf",
"sha256": "745d3b6f3735c75f647115d49116f308c9ab0e1d658b2bd5bac101cd4b92b35b"
},
"downloads": -1,
"filename": "relatio-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "40a1d0b38dd96eacedaac275241511cf",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 28716,
"upload_time": "2023-04-14T15:44:25",
"upload_time_iso_8601": "2023-04-14T15:44:25.032801Z",
"url": "https://files.pythonhosted.org/packages/3b/c1/0b76648b2f6f6bc101110e6eb48d438f6771d585c179cd74bd3026e60d0e/relatio-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "72c11e2b310c584dc5349b64e886777dee5066798a57d492c1ea7a3dc3ffbb28",
"md5": "a8cc6b1232892b96740aeb4d58102eed",
"sha256": "31079e301f12e1a3f0911b3676a70b290d9b6de1c5fb823723aaaf7fe8295a57"
},
"downloads": -1,
"filename": "relatio-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "a8cc6b1232892b96740aeb4d58102eed",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 27033,
"upload_time": "2023-04-14T15:44:26",
"upload_time_iso_8601": "2023-04-14T15:44:26.984540Z",
"url": "https://files.pythonhosted.org/packages/72/c1/1e2b310c584dc5349b64e886777dee5066798a57d492c1ea7a3dc3ffbb28/relatio-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-04-14 15:44:26",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "relatio-nlp",
"github_project": "relatio",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "relatio"
}
JSON
