Berkeley Neural Parser (benepar)

To prepare the multilingual datasets (Arabic, Basque, French, German, Hebrew, Hungarian, Korean, Polish, Swedish):

1. Prepare Raw Data:
   • Copy or symlink the various SPMRL folders (e.g., ARABIC_SPMRL, BASQUE_SPMRL) into data/raw/.
   • Arabic Alternative: If data/raw/ARABIC_SPMRL is missing, you can use LDC sources. Place Arabic Treebank Parts 1-3 (LDC2010T13, LDC2011T09, and LDC2010T08) in data/raw/atb1_v4_1, data/raw/atb_2_3.1, and data/raw/atb3_v3_2 respectively. The build script will detect these and use the alternative pipeline.
2. Environment Setup:
   • Use Python 3.
   • Install nltk.
3. Build Corpus:
   • Execute the build script from the data/spmrl directory.

Output files follow the pattern {Language}.{train|dev|test} in data/spmrl/.

cd data/spmrl && ./build_corpus.sh

To prepare the English Wall Street Journal (WSJ) corpus for parsing, follow these steps:

1. Prepare Raw Data:
   • Place Penn Treebank (LDC99T42) in data/raw/treebank_3. Ensure data/raw/treebank_3/parsed/mrg/wsj contains folders 00 through 24.
   • Place the revised Penn Treebank (LDC2015T13) in data/raw/eng_news_txt_tbnk-ptb_revised.
2. Environment Setup:
   • Use Python 3.
   • Install nltk and pytokenizations.
3. Build Corpus:
   • Execute the build script from the data/wsj directory.

Processed files are stored in data/wsj/ and include standard training/dev/test splits for both the original LDC99T42 and the revised LDC2015T13 datasets, as well as .text files for non-destructive tokenization and .retokenized files for syntactic annotations overlaid on revised tokenization.

cd data/wsj && ./build_corpus.sh

While the benepar package can use single-file checkpoints directly, it is recommended to use src/export.py to convert them into a directory. This encapsulates the tokenizer and pre-trained model config, and avoids the 3x size overhead caused by saving optimizer states.

Exporting and Compressing:

• Use src/export.py export to create a model directory.
• Use the --compress flag to adjust weights so the output can be distributed as a much smaller ZIP archive.
• Warning: When using --compress, always specify a --test-path (using data other than the development set) to verify that accuracy remains acceptable.

Verifying Exported Models: Use the test subcommand of src/export.py to verify exported models. This subcommand supports exported model directories and has slightly different flags than main.py.

# Export a checkpoint to a directory
python src/export.py export \
  --model-path models/en_bert_base_dev=*.pt \
  --output-dir=models/en_bert_base

# Export with compression and verification
python src/export.py export \
  --model-path models/en_bert_base_dev=*.pt \
  --output-dir=models/en_bert_base \
  --test-path=data/wsj/test_23.LDC99T42

# Verify an exported model
python src/export.py test --model-path benepar_en3_wsj --test-path data/wsj/test_23.LDC99T42

The recommended way to use benepar is by integrating it as a component in a spaCy pipeline. This handles tokenization and sentence segmentation automatically.

Depending on your spaCy version, the integration method differs:

• spaCy v2: Use nlp.add_pipe(benepar.BeneparComponent("model_name")).
• spaCy v3+: Use nlp.add_pipe("benepar", config={"model": "model_name"}).

Once added, constituency parsing results are accessible via the ._ extension namespace on Span and Token objects.

import benepar, spacy
nlp = spacy.load('en_core_web_md')

# For spaCy v2
if spacy.__version__.startswith('2'):
    nlp.add_pipe(benepar.BeneparComponent("benepar_en3"))
# For spaCy v3+
else:
    nlp.add_pipe("benepar", config={"model": "benepar_en3"})

doc = nlp("The time for action is now. It's never too late to do something.")
sent = list(doc.sents)[0]
print(sent._.parse_string)

SPMRL models use multilingual BERT (bert-base-multilingual-cased). Specific text processing and length constraints are required for certain languages.

Arabic

Arabic requires --text-processing arabic-translit. Because some sentences in the training/dev sets may exceed BERT's maximum sequence length, use --max-len-train and --max-len-dev to truncate them.

Hebrew

Use --text-processing hebrew for standard Hebrew characters. If your dataset uses transliterated characters, use --text-processing hebrew-translit instead.

Key arguments:

• --evalb-dir: Directory for EVALB output.
• --text-processing: Specifies the language-specific preprocessing logic.

# Example for Arabic
SPMRL_LANG=Arabic
python src/main.py train \
    --train-path data/spmrl/${SPMRL_LANG}.train \
    --dev-path data/spmrl/${SPMRL_LANG}.dev \
    --evalb-dir EVALB_SPMRL \
    --use-pretrained --pretrained-model "bert-base-multilingual-cased" \
    --use-encoder --num-layers 2 \
    --predict-tags \
    --model-path-base models/${SPMRL_LANG}_bert_base_multilingual_cased \
    --text-processing arabic-translit --max-len-train 266 --max-len-dev 494

The NLTK interface is designed for pre-tokenized datasets or pipelines that already perform tokenization and sentence splitting. For raw text, spaCy integration is strongly preferred.

To use the NLTK interface, create a benepar.Parser and pass benepar.InputSentence objects to the .parse() or .parse_sents() methods.

InputSentence Requirements:

• At least one of words or escaped_words must be provided.
• Other fields like space_after and tags are optional and will be guessed if missing.

import benepar
parser = benepar.Parser("benepar_en3")

# Single sentence
input_sentence = benepar.InputSentence(
    words=['"', 'Fly', 'safely', '.', '"'],
    space_after=[False, True, False, False, False],
    tags=['``', 'VB', 'RB', '.', "''"],
    escaped_words=['``', 'Fly', 'safely', '.', "''"],
)
tree = parser.parse(input_sentence)

# Multiple sentences
input_sentence1 = benepar.InputSentence(words=['The', 'time', 'for', 'action', 'is', 'now', '.'])
input_sentence2 = benepar.InputSentence(words=['It', "'s", 'never', 'too', 'late', 'to', 'do', 'something', '.'])
trees = parser.parse_sents([input_sentence1, input_sentence2])