Skip to main content

IsaNLP RST Parser: A library for parsing Rhetorical Structure Theory trees.

Project description

Python 3.10

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: GUM9.1, RST-DT
  • Russian: RRT2.1, RRGGUM-9.1
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:

    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:

    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:

    {
      '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:

    res['rst'][0].to_rs3('filename.rs3')
    

    The filename.rs3 file can be opened in RSTTool or rstWeb for visualization or editing. Illustration of En parsing

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:

    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:

    pip install git+https://github.com/iinemo/isanlp.git
    

    Then connect to the running Docker container:

    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:
    @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"
    }
    

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

isanlp_rst-3.0.1a5.tar.gz (145.8 kB view details)

Uploaded Source

Built Distribution

isanlp_rst-3.0.1a5-py3-none-any.whl (160.8 kB view details)

Uploaded Python 3

File details

Details for the file isanlp_rst-3.0.1a5.tar.gz.

File metadata

  • Download URL: isanlp_rst-3.0.1a5.tar.gz
  • Upload date:
  • Size: 145.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.11.2

File hashes

Hashes for isanlp_rst-3.0.1a5.tar.gz
Algorithm Hash digest
SHA256 6bda6a704c7f85f4e0b91b877d3be650a722f18188020c0250bb0965158618a7
MD5 51cfc14cad590761caa777a2cf493254
BLAKE2b-256 0affc062b6cf790e88ca6fb87d7d0f62ae00cb213d9ab9a8f36dd7aab5226276

See more details on using hashes here.

File details

Details for the file isanlp_rst-3.0.1a5-py3-none-any.whl.

File metadata

  • Download URL: isanlp_rst-3.0.1a5-py3-none-any.whl
  • Upload date:
  • Size: 160.8 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.11.2

File hashes

Hashes for isanlp_rst-3.0.1a5-py3-none-any.whl
Algorithm Hash digest
SHA256 dc5a8cfa51c74cad872c250aa3d22d6b2ca9dc07de56350418793731cb079ed0
MD5 adb69727b046639bf2048afee8f757cf
BLAKE2b-256 f7d46b7deb664118668a8b0653189460105002d6777da3747e9635ecae69b00d

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page