:rocket: SuPar

A Python package designed for structured prediction, including reproductions of many state-of-the-art syntactic/semantic parsers (with pretrained models for more than 19 languages),

Dependency Parser
- Biaffine (Dozat and Manning, 2017)
- CRF/CRF2o (Zhang et al., 2020a)
Constituency Parser
- CRF (Zhang et al., 2020b)
- AttachJuxtapose (Yang and Deng, 2020)
- TetraTagging (Kitaev and Klein, 2020)
Semantic Dependency Parser
- Biaffine (Dozat and Manning, 2018)
- MFVI/LBP (Wang et al, 2019)

and highly-parallelized implementations of several well-known structured prediction algorithms.[^1]

Chain:
- LinearChainCRF (Lafferty et al., 2001)
- SemiMarkovCRF (Sarawagi et al., 2004)
Tree
- MatrixTree (Koo et al., 2007; Ma and Hovy, 2017)
- DependencyCRF (Eisner et al., 2000; Zhang et al., 2020)
- Dependency2oCRF (McDonald et al., 2006; Zhang et al., 2020)
- ConstituencyCRF (Stern et al. 2017; Zhang et al., 2020b)
- BiLexicalizedConstituencyCRF (Eisner et al. 1999; Yang et al., 2021)

Installation

You can install SuPar via pip:

$ pip install -U supar

or from source directly:

$ pip install -U git+https://github.com/yzhangcs/parser

The following requirements should be satisfied:

python: >= 3.8
pytorch: >= 1.8
transformers: >= 4.0

Usage

You can download the pretrained model and parse sentences with just a few lines of code:

>>> from supar import Parser
# if the gpu device is available
# >>> torch.cuda.set_device('cuda:0')  
>>> parser = Parser.load('dep-biaffine-en')
>>> dataset = parser.predict('I saw Sarah with a telescope.', lang='en', prob=True, verbose=False)

By default, we use stanza internally to tokenize plain texts for parsing. You only need to specify the language code lang for tokenization.

The call to parser.predict will return an instance of supar.utils.Dataset containing the predicted results. You can either access each sentence held in dataset or an individual field of all results. Probabilities can be returned along with the results if prob=True.

>>> dataset[0]
1       I       _       _       _       _       2       nsubj   _       _
2       saw     _       _       _       _       0       root    _       _
3       Sarah   _       _       _       _       2       dobj    _       _
4       with    _       _       _       _       2       prep    _       _
5       a       _       _       _       _       6       det     _       _
6       telescope       _       _       _       _       4       pobj    _       _
7       .       _       _       _       _       2       punct   _       _

>>> print(f"arcs:  {dataset.arcs[0]}\n"
          f"rels:  {dataset.rels[0]}\n"
          f"probs: {dataset.probs[0].gather(1,torch.tensor(dataset.arcs[0]).unsqueeze(1)).squeeze(-1)}")
arcs:  [2, 0, 2, 2, 6, 4, 2]
rels:  ['nsubj', 'root', 'dobj', 'prep', 'det', 'pobj', 'punct']
probs: tensor([1.0000, 0.9999, 0.9966, 0.8944, 1.0000, 1.0000, 0.9999])

SuPar also supports parsing from tokenized sentences or from file. For BiLSTM-based semantic dependency parsing models, lemmas and POS tags are needed.

>>> import os
>>> import tempfile
# if the gpu device is available
# >>> torch.cuda.set_device('cuda:0')  
>>> dep = Parser.load('dep-biaffine-en')
>>> dep.predict(['I', 'saw', 'Sarah', 'with', 'a', 'telescope', '.'], verbose=False)[0]
1       I       _       _       _       _       2       nsubj   _       _
2       saw     _       _       _       _       0       root    _       _
3       Sarah   _       _       _       _       2       dobj    _       _
4       with    _       _       _       _       2       prep    _       _
5       a       _       _       _       _       6       det     _       _
6       telescope       _       _       _       _       4       pobj    _       _
7       .       _       _       _       _       2       punct   _       _

>>> path = os.path.join(tempfile.mkdtemp(), 'data.conllx')
>>> with open(path, 'w') as f:
...     f.write('''# text = But I found the location wonderful and the neighbors very kind.
1\tBut\t_\t_\t_\t_\t_\t_\t_\t_
2\tI\t_\t_\t_\t_\t_\t_\t_\t_
3\tfound\t_\t_\t_\t_\t_\t_\t_\t_
4\tthe\t_\t_\t_\t_\t_\t_\t_\t_
5\tlocation\t_\t_\t_\t_\t_\t_\t_\t_
6\twonderful\t_\t_\t_\t_\t_\t_\t_\t_
7\tand\t_\t_\t_\t_\t_\t_\t_\t_
7.1\tfound\t_\t_\t_\t_\t_\t_\t_\t_
8\tthe\t_\t_\t_\t_\t_\t_\t_\t_
9\tneighbors\t_\t_\t_\t_\t_\t_\t_\t_
10\tvery\t_\t_\t_\t_\t_\t_\t_\t_
11\tkind\t_\t_\t_\t_\t_\t_\t_\t_
12\t.\t_\t_\t_\t_\t_\t_\t_\t_

''')
...
>>> dep.predict(path, pred='pred.conllx', verbose=False)[0]
# text = But I found the location wonderful and the neighbors very kind.
1       But     _       _       _       _       3       cc      _       _
2       I       _       _       _       _       3       nsubj   _       _
3       found   _       _       _       _       0       root    _       _
4       the     _       _       _       _       5       det     _       _
5       location        _       _       _       _       6       nsubj   _       _
6       wonderful       _       _       _       _       3       xcomp   _       _
7       and     _       _       _       _       6       cc      _       _
7.1     found   _       _       _       _       _       _       _       _
8       the     _       _       _       _       9       det     _       _
9       neighbors       _       _       _       _       11      dep     _       _
10      very    _       _       _       _       11      advmod  _       _
11      kind    _       _       _       _       6       conj    _       _
12      .       _       _       _       _       3       punct   _       _

>>> con = Parser.load('con-crf-en')
>>> con.predict(['I', 'saw', 'Sarah', 'with', 'a', 'telescope', '.'], verbose=False)[0].pretty_print()
              TOP                       
               |                         
               S                        
  _____________|______________________   
 |             VP                     | 
 |    _________|____                  |  
 |   |    |         PP                | 
 |   |    |     ____|___              |  
 NP  |    NP   |        NP            | 
 |   |    |    |     ___|______       |  
 _   _    _    _    _          _      _ 
 |   |    |    |    |          |      |  
 I  saw Sarah with  a      telescope  . 

>>> sdp = Parser.load('sdp-biaffine-en')
>>> sdp.predict([[('I','I','PRP'), ('saw','see','VBD'), ('Sarah','Sarah','NNP'), ('with','with','IN'),
                  ('a','a','DT'), ('telescope','telescope','NN'), ('.','_','.')]],
                verbose=False)[0]
1       I       I       PRP     _       _       _       _       2:ARG1  _
2       saw     see     VBD     _       _       _       _       0:root|4:ARG1   _
3       Sarah   Sarah   NNP     _       _       _       _       2:ARG2  _
4       with    with    IN      _       _       _       _       _       _
5       a       a       DT      _       _       _       _       _       _
6       telescope       telescope       NN      _       _       _       _       4:ARG2|5:BV     _
7       .       _       .       _       _       _       _       _       _

Training

To train a model from scratch, it is preferred to use the command-line option, which is more flexible and customizable. Below is an example of training Biaffine Dependency Parser:

$ python -m supar.cmds.dep.biaffine train -b -d 0 -c dep-biaffine-en -p model -f char

Alternatively, SuPar provides some equivalent command entry points registered in setup.py: dep-biaffine, dep-crf2o, con-crf and sdp-biaffine, etc.

$ dep-biaffine train -b -d 0 -c dep-biaffine-en -p model -f char

To accommodate large models, distributed training is also supported:

$ python -m supar.cmds.dep.biaffine train -b -c dep-biaffine-en -d 0,1,2,3 -p model -f char

You can consult the PyTorch documentation and tutorials for more details.

Evaluation

The evaluation process resembles prediction:

# if the gpu device is available
# >>> torch.cuda.set_device('cuda:0')  
>>> Parser.load('dep-biaffine-en').evaluate('ptb/test.conllx', verbose=False)
loss: 0.2393 - UCM: 60.51% LCM: 50.37% UAS: 96.01% LAS: 94.41%

See examples for more instructions on training and evaluation.

Performance

SuPar provides pretrained models for English, Chinese and 17 other languages. The tables below list the performance and parsing speed of pretrained models for different tasks. All results are tested on the machine with Intel(R) Xeon(R) CPU E5-2650 v4 @ 2.20GHz and Nvidia GeForce GTX 1080 Ti GPU.

Dependency Parsing

English and Chinese dependency parsing models are trained on PTB and CTB7 respectively. For each parser, we provide pretrained models that take BiLSTM as encoder. We also provide models trained by finetuning pretrained language models from Huggingface Transformers. We use robert-large for English and hfl/chinese-electra-180g-large-discriminator for Chinese. During evaluation, punctuation is ignored in all metrics for PTB.

Name	UAS	LAS	Sents/s
`dep-biaffine-en`	96.01	94.41	1831.91
`dep-crf2o-en`	96.07	94.51	531.59
`dep-biaffine-roberta-en`	97.33	95.86	271.80
`dep-biaffine-zh`	88.64	85.47	1180.57
`dep-crf2o-zh`	89.22	86.15	237.40
`dep-biaffine-electra-zh`	92.45	89.55	160.56

The multilingual dependency parsing model, named dep-biaffine-xlmr, is trained on merged 12 selected treebanks from Universal Dependencies (UD) v2.3 dataset by finetuning xlm-roberta-large. The following table lists results of each treebank. Languages are represented by ISO 639-1 Language Codes.

Language	UAS	LAS	Sents/s
`bg`	96.95	94.24	343.96
`ca`	95.57	94.20	184.88
`cs`	95.79	93.83	245.68
`de`	89.74	85.59	283.53
`en`	93.37	91.27	269.16
`es`	94.78	93.29	192.00
`fr`	94.56	91.90	219.35
`it`	96.29	94.47	254.82
`nl`	96.04	93.76	268.57
`no`	95.64	94.45	318.00
`ro`	94.59	89.79	216.45
`ru`	96.37	95.24	243.56