# IsaNLP RST Parser
This library provides several versions of the Rhetorical Structure Theory (RST) parser for English and Russian. Below, you will find instructions on how to set up and run the parser either locally or using Docker.
## Performance
The parser supports multiple languages and corpora. The end-to-end performance metrics for different model versions across various corpora are as follows:
### Corpora
- **English:** GUM<sub>9.1</sub>, RST-DT
- **Russian:** RRT<sub>2.1</sub>, RRG<sub>GUM-9.1</sub>
| Tag / Version | Language | Train Data | Test Data | Seg | S | N | R | Full |
|-------------|------------|-------------|-------------|------|------|------|------|-------|
| `gumrrg` | En, Ru | GUM, RRG | GUM | 95.5 | 67.4 | 56.2 | 49.6 | 48.7 |
| | | | RRG | 97.0 | 67.1 | 54.6 | 46.5 | 45.4 |
| `rstdt` | En | RST-DT | RST-DT | 97.8 | 75.6 | 65.0 | 55.6 | 53.9 |
| `rstreebank` | Ru | RRT | RRT | 92.1 | 66.2 | 53.1 | 46.1 | 46.2 |
## Local Setup
To use the IsaNLP RST Parser locally, follow these steps:
1. **Installation:**
First, install the `isanlp` and `isanlp_rst` libraries using pip:
```bash
pip install git+https://github.com/iinemo/isanlp.git
pip install isanlp_rst
```
2. **Usage:**
Below is an example of how to run a specific version of the parser using the library:
```python
from isanlp_rst.parser import Parser
# Define the version of the model you want to use
version = 'gumrrg' # Choose from {'gumrrg', 'rstdt', 'rstreebank'}
# Initialize the parser with the desired version
parser = Parser(hf_model_name='tchewik/isanlp_rst_v3', hf_model_version=version, cuda_device=0)
# Example text for parsing
text = """
On Saturday, in the ninth edition of the T20 Men's Cricket World Cup, Team India won against South Africa by seven runs.
The final match was played at the Kensington Oval Stadium in Barbados. This marks India's second win in the T20 World Cup,
which was co-hosted by the West Indies and the USA between June 2 and June 29.
After winning the toss, India decided to bat first and scored 176 runs for the loss of seven wickets.
Virat Kohli top-scored with 76 runs, followed by Axar Patel with 47 runs. Hardik Pandya took three wickets,
and Jasprit Bumrah took two wickets.
"""
# Parse the text to obtain the RST tree
res = parser(text) # res['rst'] contains the binary discourse tree
# Display the structure of the RST tree
vars(res['rst'][0])
```
The output is an RST tree with the following structure:
```python
{
'id': 7,
'left': <isanlp.annotation_rst.DiscourseUnit at 0x7f771076add0>,
'right': <isanlp.annotation_rst.DiscourseUnit at 0x7f7750b93d30>,
'relation': 'elaboration',
'nuclearity': 'NS',
'start': 0,
'end': 336,
'text': "On Saturday, ... took two wickets .",
}
```
- **id**: Unique identifier for the discourse unit.
- **left** and **right**: Children of the current discourse unit.
- **relation**: Rhetorical relation between sub-units (e.g., "elaboration").
- **nuclearity**: Indicates nuclearity of the relation (e.g., "NS" for nucleus-satellite).
- **start** and **end**: Character offsets in the text for this discourse unit.
- **text**: Text span corresponding to this discourse unit.
3. **(Optional) Save the result in RS3 format:**
You can save the resulting RST tree in an RS3 file using the following command:
```python
res['rst'][0].to_rs3('filename.rs3')
```
The `filename.rs3` file can be opened in RSTTool or rstWeb for visualization or editing.
<img src="examples/example-image.png" alt="Illustration of En parsing" width="600">
## Docker Setup
To run the IsaNLP RST Parser using Docker, follow these steps:
1. **Run the Docker container:**
Pull and run the Docker container with the desired model version tag:
```bash
docker run --rm -p 3335:3333 --name rst_rrt tchewik/isanlp_rst:3.0-rstreebank
```
2. **Connect using the IsaNLP Python library:**
Install the `isanlp` library. The `isanlp_rst` library is not required for dockerized parsers:
```bash
pip install git+https://github.com/iinemo/isanlp.git
```
Then connect to the running Docker container:
```python
from isanlp import PipelineCommon
from isanlp.processor_remote import ProcessorRemote
# Put the container address here
address_rst = ('127.0.0.1', 3335)
ppl = PipelineCommon([
(ProcessorRemote(address_rst[0], address_rst[1], 'default'),
['text'],
{'rst': 'rst'})
])
res = ppl(text)
# res['rst'] will contain the binary discourse tree, similar to the previous example
```
## Citation
If you use the IsaNLP RST Parser in your research, please cite our work as follows:
- **For versions `gumrrg`, `rstdt`, and `rstreebank`:**
```bibtex
@inproceedings{
chistova-2024-bilingual,
title = "Bilingual Rhetorical Structure Parsing with Large Parallel Annotations",
author = "Chistova, Elena",
booktitle = "Findings of the Association for Computational Linguistics ACL 2024",
month = aug,
year = "2024",
address = "Bangkok, Thailand and virtual meeting",
publisher = "Association for Computational Linguistics",
url = "https://aclanthology.org/2024.findings-acl.577",
pages = "9689--9706"
}
```
Raw data
{
"_id": null,
"home_page": "https://github.com/tchewik/isanlp_rst",
"name": "isanlp-rst",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": null,
"author": "Elena Chistova",
"author_email": "elenachistov@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/0a/ff/c062b6cf790e88ca6fb87d7d0f62ae00cb213d9ab9a8f36dd7aab5226276/isanlp_rst-3.0.1a5.tar.gz",
"platform": null,
"description": "\n\n# IsaNLP RST Parser\n\nThis library provides several versions of the Rhetorical Structure Theory (RST) parser for English and Russian. Below, you will find instructions on how to set up and run the parser either locally or using Docker.\n\n## Performance\n\nThe parser supports multiple languages and corpora. The end-to-end performance metrics for different model versions across various corpora are as follows:\n\n### Corpora\n- **English:** GUM<sub>9.1</sub>, RST-DT\n- **Russian:** RRT<sub>2.1</sub>, RRG<sub>GUM-9.1</sub>\n\n| Tag / Version | Language | Train Data | Test Data | Seg | S | N | R | Full |\n|-------------|------------|-------------|-------------|------|------|------|------|-------|\n| `gumrrg` | En, Ru | GUM, RRG | GUM | 95.5 | 67.4 | 56.2 | 49.6 | 48.7 |\n| | | | RRG | 97.0 | 67.1 | 54.6 | 46.5 | 45.4 |\n| `rstdt` | En | RST-DT | RST-DT | 97.8 | 75.6 | 65.0 | 55.6 | 53.9 |\n| `rstreebank` | Ru | RRT | RRT | 92.1 | 66.2 | 53.1 | 46.1 | 46.2 |\n\n\n## Local Setup\n\nTo use the IsaNLP RST Parser locally, follow these steps:\n\n1. **Installation:**\n\n First, install the `isanlp` and `isanlp_rst` libraries using pip:\n\n ```bash\n pip install git+https://github.com/iinemo/isanlp.git\n pip install isanlp_rst\n ```\n\n2. **Usage:**\n\n Below is an example of how to run a specific version of the parser using the library:\n\n ```python\n from isanlp_rst.parser import Parser\n\n # Define the version of the model you want to use\n version = 'gumrrg' # Choose from {'gumrrg', 'rstdt', 'rstreebank'}\n \n # Initialize the parser with the desired version\n parser = Parser(hf_model_name='tchewik/isanlp_rst_v3', hf_model_version=version, cuda_device=0)\n\n # Example text for parsing\n text = \"\"\"\n On Saturday, in the ninth edition of the T20 Men's Cricket World Cup, Team India won against South Africa by seven runs. \n The final match was played at the Kensington Oval Stadium in Barbados. This marks India's second win in the T20 World Cup, \n which was co-hosted by the West Indies and the USA between June 2 and June 29.\n\n After winning the toss, India decided to bat first and scored 176 runs for the loss of seven wickets. \n Virat Kohli top-scored with 76 runs, followed by Axar Patel with 47 runs. Hardik Pandya took three wickets, \n and Jasprit Bumrah took two wickets.\n \"\"\"\n\n # Parse the text to obtain the RST tree\n res = parser(text) # res['rst'] contains the binary discourse tree\n\n # Display the structure of the RST tree\n vars(res['rst'][0])\n ```\n \n The output is an RST tree with the following structure:\n\n ```python\n {\n 'id': 7,\n 'left': <isanlp.annotation_rst.DiscourseUnit at 0x7f771076add0>,\n 'right': <isanlp.annotation_rst.DiscourseUnit at 0x7f7750b93d30>,\n 'relation': 'elaboration',\n 'nuclearity': 'NS',\n 'start': 0,\n 'end': 336,\n 'text': \"On Saturday, ... took two wickets .\",\n }\n ```\n\n - **id**: Unique identifier for the discourse unit.\n - **left** and **right**: Children of the current discourse unit.\n - **relation**: Rhetorical relation between sub-units (e.g., \"elaboration\").\n - **nuclearity**: Indicates nuclearity of the relation (e.g., \"NS\" for nucleus-satellite).\n - **start** and **end**: Character offsets in the text for this discourse unit.\n - **text**: Text span corresponding to this discourse unit.\n\n3. **(Optional) Save the result in RS3 format:**\n\n You can save the resulting RST tree in an RS3 file using the following command:\n\n ```python\n res['rst'][0].to_rs3('filename.rs3')\n ```\n\n The `filename.rs3` file can be opened in RSTTool or rstWeb for visualization or editing.\n <img src=\"examples/example-image.png\" alt=\"Illustration of En parsing\" width=\"600\">\n\n\n## Docker Setup\n\nTo run the IsaNLP RST Parser using Docker, follow these steps:\n\n1. **Run the Docker container:**\n\n Pull and run the Docker container with the desired model version tag:\n\n ```bash\n docker run --rm -p 3335:3333 --name rst_rrt tchewik/isanlp_rst:3.0-rstreebank\n ```\n\n2. **Connect using the IsaNLP Python library:**\n\n Install the `isanlp` library. The `isanlp_rst` library is not required for dockerized parsers:\n\n ```bash\n pip install git+https://github.com/iinemo/isanlp.git\n ```\n\n Then connect to the running Docker container:\n\n ```python\n from isanlp import PipelineCommon\n from isanlp.processor_remote import ProcessorRemote\n\n # Put the container address here\n address_rst = ('127.0.0.1', 3335)\n\n ppl = PipelineCommon([\n (ProcessorRemote(address_rst[0], address_rst[1], 'default'),\n ['text'],\n {'rst': 'rst'})\n ])\n\n res = ppl(text)\n # res['rst'] will contain the binary discourse tree, similar to the previous example\n ```\n\n \n## Citation\n\nIf you use the IsaNLP RST Parser in your research, please cite our work as follows:\n\n- **For versions `gumrrg`, `rstdt`, and `rstreebank`:** \n ```bibtex\n @inproceedings{\n chistova-2024-bilingual,\n title = \"Bilingual Rhetorical Structure Parsing with Large Parallel Annotations\",\n author = \"Chistova, Elena\",\n booktitle = \"Findings of the Association for Computational Linguistics ACL 2024\",\n month = aug,\n year = \"2024\",\n address = \"Bangkok, Thailand and virtual meeting\",\n publisher = \"Association for Computational Linguistics\",\n url = \"https://aclanthology.org/2024.findings-acl.577\",\n pages = \"9689--9706\"\n }\n ```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "IsaNLP RST Parser: A library for parsing Rhetorical Structure Theory trees.",
"version": "3.0.1a5",
"project_urls": {
"Homepage": "https://github.com/tchewik/isanlp_rst"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f7d46b7deb664118668a8b0653189460105002d6777da3747e9635ecae69b00d",
"md5": "adb69727b046639bf2048afee8f757cf",
"sha256": "dc5a8cfa51c74cad872c250aa3d22d6b2ca9dc07de56350418793731cb079ed0"
},
"downloads": -1,
"filename": "isanlp_rst-3.0.1a5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "adb69727b046639bf2048afee8f757cf",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 160812,
"upload_time": "2024-08-26T11:53:39",
"upload_time_iso_8601": "2024-08-26T11:53:39.713725Z",
"url": "https://files.pythonhosted.org/packages/f7/d4/6b7deb664118668a8b0653189460105002d6777da3747e9635ecae69b00d/isanlp_rst-3.0.1a5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0affc062b6cf790e88ca6fb87d7d0f62ae00cb213d9ab9a8f36dd7aab5226276",
"md5": "51cfc14cad590761caa777a2cf493254",
"sha256": "6bda6a704c7f85f4e0b91b877d3be650a722f18188020c0250bb0965158618a7"
},
"downloads": -1,
"filename": "isanlp_rst-3.0.1a5.tar.gz",
"has_sig": false,
"md5_digest": "51cfc14cad590761caa777a2cf493254",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 145772,
"upload_time": "2024-08-26T11:53:41",
"upload_time_iso_8601": "2024-08-26T11:53:41.471511Z",
"url": "https://files.pythonhosted.org/packages/0a/ff/c062b6cf790e88ca6fb87d7d0f62ae00cb213d9ab9a8f36dd7aab5226276/isanlp_rst-3.0.1a5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-26 11:53:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "tchewik",
"github_project": "isanlp_rst",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "isanlp-rst"
}
JSON
