Skip to main content

Transition-based UCCA Parser

Project description

TUPA is a transition-based parser for Universal Conceptual Cognitive Annotation (UCCA).


  • Python 3.6


Create a Python virtual environment. For example, on Linux:

virtualenv --python=/usr/bin/python3 venv
. venv/bin/activate              # on bash
source venv/bin/activate.csh     # on csh

Install the latest release:

pip install tupa

Alternatively, install the latest code from GitHub (may be unstable):

git clone
cd tupa
pip install .

Train the parser

Having a directory with UCCA passage files (for example, the English Wiki corpus), run:

python -m tupa -t <train_dir> -d <dev_dir> -c <model_type> -m <model_filename>

The possible model types are sparse, mlp, and bilstm.

Parse a text file

Run the parser on a text file (here named example.txt) using a trained model:

python -m tupa example.txt -m <model_filename>

An xml file will be created per passage (separate by blank lines in the text file).

Pre-trained models

To download and extract a model pre-trained on the Wiki corpus, run:

curl -LO
tar xvzf ucca-bilstm-1.3.10.tar.gz

Run the parser using the model:

python -m tupa example.txt -m models/ucca-bilstm

Other languages

To get a model pre-trained on the French *20K Leagues* corpus or a model pre-trained on the German *20K Leagues* corpus, run:

curl -LO
tar xvzf ucca-bilstm-1.3.10-fr.tar.gz
curl -LO
tar xvzf ucca-bilstm-1.3.10-de.tar.gz

Run the parser on a French/German text file (separate passages by blank lines):

python -m tupa exemple.txt -m models/ucca-bilstm-fr --lang fr
python -m tupa beispiel.txt -m models/ucca-bilstm-de --lang de

Using BERT

BERT can be used instead of standard word embeddings. First, install the required dependencies:

pip install -r requirements.bert.txt

Then pass the --use-bert argument to the training command.

See the possible configuration options in (relevant options have the prefix bert).

BERT Multilingual Training

A multilingual model can be trained, to leverage cross-lingual transfer and improve results on low-resource languages:

  1. Make sure the input passage files have the lang attribute. See the script `set_lang <>`__ in the package semstr.
  2. Enable BERT by passing the --use-bert argument.
  3. Use the multilingual model by passing --bert-model=bert-base-multilingual-cased.
  4. Pass the --bert-multilingual=0 argument to enable multilingual training.

BERT Performance

Here are the average results over 3 BERT multilingual models trained on the German *20K Leagues* corpus, English Wiki corpus and only on 15 sentences from the French *20K Leagues* corpus, with the following settings:

bert-layers=-1 -2 -3 -4

The results:

description test primary F1 test remote F1 test average
German 20K Leagues 0.828 0.6723 0.824
English 20K Leagues 0.763 0.359 0.755
French 20K Leagues 0.739 0.46 0.732
English Wiki 0.789 0.581 0.784

*English *20K Leagues* corpus is used as out of domain test.

Pre-trained Models with BERT

To download and extract a multilingual model trained with the settings above, run:

curl -LO
tar xvzf bert_multilingual_layers_4_layers_pooling_weighted_align_sum.tar.gz

To run the parser using the model, use the following command. Pay attention that you need to replace [lang] with the right language symbol (fr, en, or de):

python -m tupa example.txt --lang [lang] -m bert_multilingual_layers_4_layers_pooling_weighted_align_sum




If you make use of this software, please cite the following paper:

  author    = {Hershcovich, Daniel  and  Abend, Omri  and  Rappoport, Ari},
  title     = {A Transition-Based Directed Acyclic Graph Parser for {UCCA}},
  booktitle = {Proc. of ACL},
  year      = {2017},
  pages     = {1127--1138},
  url       = {}

The version of the parser used in the paper is v1.0. To reproduce the experiments, run:

curl -L | bash

If you use the French, German or multitask models, please cite the following paper:

  author    = {Hershcovich, Daniel  and  Abend, Omri  and  Rappoport, Ari},
  title     = {Multitask Parsing Across Semantic Representations},
  booktitle = {Proc. of ACL},
  year      = {2018},
  pages     = {373--385},
  url       = {}

The version of the parser used in the paper is v1.3.3. To reproduce the experiments, run:

curl -L | bash


This package is licensed under the GPLv3 or later license (see `LICENSE.txt <LICENSE.txt>`__).

Build Status (Travis CI) Build Status (AppVeyor) Build Status (Docs) PyPI version

Project details

Download files

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

Files for TUPA, version 1.4.2
Filename, size File type Python version Upload date Hashes
Filename, size TUPA-1.4.2-py3-none-any.whl (111.2 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size TUPA-1.4.2.tar.gz (2.3 MB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page