Max-Margin Markov Graph Models for WordNet (EMNLP 2018)
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
LICENSE main scripts explained Oct 8, 2018 first commit - untested code Oct 2, 2018 first commit - untested code Oct 2, 2018 first commit - untested code Oct 2, 2018 pretraining tested Oct 2, 2018 first commit - untested code Oct 2, 2018 first commit - untested code Oct 2, 2018 pretraining tested Oct 2, 2018 pretraining tested Oct 2, 2018


October 8: most of the code is here and documented. All parts are validated.

This repository contains code for Max-Margin Markov Graph Models (M3GMs) as described in the paper:

Yuval Pinter and Jacob Eisenstein. Predicting Semantic Relations using Global Graph Properties. EMNLP 2018.

(Stay tuned for official conference PDF and bibtex, around October 30.)

Code Requirements

The project was written and tested in Python 3.6. Some packages needed to run it include:

  • dynet 2.0
  • scipy
  • tqdm
  • nltk - with the wordnet corpus available

Write me, or open an issue, if you find more blocking dependencies!


The eventual goal of training an M3GM model and replicating the results from the paper runs through a number of intermediate steps. Here is the hopefully full linearized flowchart, with some detailed descriptions in following sections:

  1. Create a pickled WordNet prediction dataset in sparse matrix format, using To use our exact dataset, obtain the distibution of WN18RR here and point the script at the text version.
  2. Obtain synset embeddings. These can be AutoExtend-based ones, which map directly to synsets, or any downloadable word embeddings which can then be averaged across synset lexemes, such as those from FastText.
  3. If your embeddings are word-level, synsetify them using Run it without parameters to see usage.
  4. Train an association model (for baseline results or for training an M3GM on top) using Demo command (for the result from the paper) given below.
  5. Train an M3GM using Demo command (for results from the paper) given below.
  6. If so inclined, tune the alpha_r parameters using You will need to do some math later to translate into results comparable to those in the paper.

Disclaimer: some of the code here takes a while to run. Any suggestions for improving any of the calculations, or for getting things to run on GPUs for that matter, will be most appreciated.

Association Models

This script trains a local association model using one of several models (see paper for details): Bilinear, TransE, Diag-R1 ("diagonal + rank-1 matrix"), DistMult. Be sure to keep record of the embedding dimension used (no need to provide the dimension as an argument if initializing from an a pre-trained file) and of the association algorithm (--assoc-mode), as these will be necessary for downstream M3GM training.

One parameter you may want to add depending on your target setup is --rule-override, which trains modules for all relations, including the four symmetric ones (in WordNet). It would also evaluate on trained modules in symmetric relations, rather than with a (high-accuracy) rule-based system. The default behavior, without this parameter, is training said modules once every five epochs, as it helps with synset embeddings tuning.

The --early-stopping method used is: for each dev epoch, if its MRR score is lower than both of the last two epochs, halt and return the best model so far.


  • the auto-generated log file (avoid using --no-log) will output many, many scores and their components for every single instance encountered.
  • --model-out is readable both by this code for test mode, and by downstream M3GM trainer (--model param).

Demo command

python --input data/wn18rr.pkl --embeddings data/ft-embs-all-lower.vec --model-out models/pret_transE --nll --assoc-mode transE --neg-samp 10 --early-stopping --eval-dev

Max-Margin Markov Graph Models

The most powerful use case for M3GM is when we've trained a good association model, and augment it with weights for combinatorial graph features by way of M3GM training. It is best if the association weights, as well as the word embeddings, are frozen from this point on, using the --no-assoc-bp parameter. If we believe some of them to be bad, they can later be weighted down using the post-processor, which computes a best-performing association component weight for each relation. --model-only-init is a related parameter, which ensures that the M3GM component is trained over the data (makes more sense when considering that there's also an --ergm-model input parameter which can be used for picking up training from a saved point).

A prerequesite for this code to run in the common mode is that both --emb-size and assoc-mode are set to the same values that the association model was trained with.


  • the auto-generated log file (avoid using --no-log) will output ERGM scores for all instances and negative samples in training phase, and all cases of re-ranking in the development data traversals.
  • --model-out will save the model in a four-file format that can later be read by both this script and the test-mode code (TODO).
  • --rerank-out provides an input file for It includes all to-be-reranked lists from the dev set and scores from both association and graph components, as well as flags for the true instances.

Demo command

python --input data/wn18rr.pkl --emb-size 300 --model models/pret_transE-ep-14 --model-only-init --assoc-mode transE --eval-dev --no-assoc-bp --epochs 3 --neg-samp 10 --regularize 0.01 --rand-all --skip-symmetrics --model-out models/from_pret_trE-3eps --rerank-out from_pret_trE-3eps.txt

Model Development

A good entry point to try and play with the ERGM features underlying M3GM would be Be sure to enter them into the cache and feature set in so they can have weights trained for them.

Running the dataset creation code with the --no-symmetrics flag would result in a dataset we called WN18RSR when working on this research. It contains only the seven asymmetric, nonreciprocal relations. All model results on it are abysmal, but you're welcome to try :)

Repo-level TODOs

  • Add exploration Notebook for WordNet (WN) structure
  • Add mapping of Synset codes from WN 1.6 all the way to 3.0.
  • Move non-script code into lib directory
  • Remove dy.parameter() calls (deprecated in dynet 2.0.4)
  • Turn any remaining TODOs from here into repo issues