dygiepp: span-based information extraction on a stack that no longer installs

What the paper actually contributes, and what the code is

DyGIE++ implements the model described in the paper Entity, Relation, and Event Extraction with Contextualized Span Representations. The description in the repository is short and precise: a span-based system for named entity, relation, and event extraction.

The word span is the whole point. A token-level classifier labels each token and then aggregates, which loses information whenever a mention spans several tokens and the decision depends on the mention as a unit. A span-based system enumerates candidate spans first and represents each one in the context of the document, so a multi-word entity is represented by one vector rather than by a bag of token vectors.

For relation and event extraction, that representation is what makes the harder tasks possible. Relations are between two mentions, and events are anchored in a trigger with argument mentions, so a model that already holds a vector per mention has something to compose over. The paper's contribution is that those span representations are contextualized, learned jointly with the task rather than fixed in advance.

The repository is the implementation. There is a dygie/ package holding the model code, a training_config/ directory for the model configurations, scripts/ for data download and preprocessing, doc/ with the data, model and config documentation, notebooks/. The MIT licence applies, and the last push was on 2026-07-05, with no GitHub releases.

The install the documentation tells you not to use

This is the first thing any reader needs to know, and the README puts it at the top of the updates section with an October 2023 date.

AllenNLP, on which DyGIE++ is built, has been archived and is not actively maintained. Due to changes to various software packages and the unavailability of older versions, following the instructions under dependencies now raises errors when trying to install DyGIE++. The author's own words are that they do not have the bandwidth to get things updated, and a pull request to update the relevant dependencies and get things working again is welcome.

The Dependencies section repeats the warning in bold. These directions no longer work, because Python 3.7 is no longer available from conda and AllenNLP is no longer actively maintained, causing some dependencies to break.

The instructions themselves are the standard research reproduction recipe:

conda create --name dygiepp python=3.7
pip install -r requirements.txt
conda develop .   # Adds DyGIE to your PYTHONPATH

Three things in there are individually dated. Python 3.7 is end of life and gone from the conda channels. AllenNLP is pinned at 1.1.0 in the requirements file along with allennlp_models at the same version, and it depends on a chain of older scientific packages. And the requirements list itself mixes eras, with pandas at 0.25.2 and beautifulsoup4 at 4.8.1, while Optuna is specified loosely at 2.1.0 or later.

The requirements file also shows what the project does beyond the model. There is a modeling section, a data munging section with pandas, beautifulsoup4, lxml and python-Levenshtein, and an Optuna dependency for hyperparameter search. The library also relies on AllenNLP shell commands to kick off training, evaluation and testing, which means the command line you use is AllenNLP's, not the project's own.

Pretrained models and the MECHANIC dataset

The reason many people come to this repository is not the training code but the model collection.

The April 2021 update added data and models for the MECHANIC dataset, presented in the NAACL 2021 paper on extracting a knowledge base of mechanisms from COVID-19 papers. The dataset is a zip file, and two models are published, a coarse one and a granular one, both as tarballs.

The data is also obtainable through a script, and running bash scripts/data/get_mechanic.sh puts it in data/mechanic. The model files are then moved into the pretrained folder, and predictions follow the AllenNLP predict pattern:

allennlp predict \
  pretrained/mechanic-coarse.tar.gz \
  data/mechanic/coarse/test.json \
  --predictor dygie \
  --include-package dygie \
  --use-dataset-reader \
  --output-file predictions/covid-coarse.jsonl \
  --cuda-device 0 \
  --silent

The argument list is worth reading as a specification of the interface. The predictor is dygie, the package has to be included so the model class can be resolved at load time, the dataset reader is required, and the output is JSON lines with one prediction per line. The cuda-device argument selects the GPU.

There is a broader collection of pretrained models, and the project solicits contributions to it. If you have a DyGIE model trained on a new dataset, you can upload it through a form and the author will add it to the collection.

Other datasets flow through the same scripts directory, with the Dockerfile downloading data for SciERC, GENIA and ChemProt, and preparing the ACE05 event data with a separate conda environment and a CoreNLP install that requires Java 1.8 or newer.

The Docker image, and the warning attached to it

There is a Dockerfile, and the author is careful about how much he claims for it.

It is based on the Pytorch + CUDA + CUDNN base image for a full-stack GPU install, and it creates two conda environments, dygiepp for modeling and ace-event-preprocess for ACE05 event preprocessing. The image fixes the NVIDIA GPG keys for the CUDA repository, installs wget, gcc, make and sqlite3, and installs jsonnet from conda-forge rather than pip because of a conflict.

The build command is docker build with the tag dygiepp:dev and the repository directory as its argument, and the run command needs the GPU flags and a mount of the project directory, with --gpus all, --ipc=host, a volume mapping the project directory to /dygiepp/ and a container named dygiepp.

One thing to notice. The Dockerfile is based on pytorch/pytorch:1.6.0-cuda10.1-cudnn7-devel, a stack from before the CUDA 11 transition, so the host needs the old NVIDIA driver libraries or the container will not start. And the image name in the run command is dygiep:dev, a typo for dygiepp, so the command as printed would not find the image you just built.

The author flags the first caveat and more: the Dockerfile was added in a pull request from a contributor, and it has not been tested, so it is not officially supported, and more pull requests are welcome.

The image is also heavy by design. By default the build downloads datasets and dependencies for all tasks, which takes a long time and produces a large image, and the guidance is to comment out the task sections you do not need in the Dockerfile before building. That is a reasonable instruction and also an admission that the image is not a practical way to try the project.

The ipc=host flag on the run command is there for a reason too, since shared memory is what PyTorch's data loader needs,.

The project status section, and a warning about coreference

The project status section explains the branch history and the maintenance reality.

The branch that used to be named allennlp-v1 has been made the new master, and it is compatible with the new version of AllenNLP with a simplified model configuration process, and the author recommends using it for all future work. The older code remains on a branch called emnlp-2019 for anyone who needs it.

Then the honest part. The author does not have the bandwidth to add additional features, but asks for issues in three specific areas: reproducing the results reported in the README, making predictions on a new dataset using pretrained models, and training your own model on a new dataset. There is a list of ideas in doc/contributions.md for anyone who wants to pick one up.

The training section opens with a warning that is easy to miss and expensive to hit. The coreference code will break on sentence, and the sentence is cut off in the copy of the documentation available here, so the condition under which it breaks is not fully specified.

Coreference is the part of an information extraction pipeline that most often needs a model, and a span-based relation and event extractor is exactly the kind of system that sits downstream of coreference resolution. A broken coreference stage is a real obstacle for anyone who wants to run the full pipeline rather than use a pretrained model on a prepared dataset.

The issue guidelines are unusually specific for a research repository. You are asked to confirm a Conda environment set up exactly as in the Dependencies section, because the author can only offer support if you are running inside that environment, to specify the download and preprocessing commands you used, to share the command that caused the issue, to attach a minimal example of the data, and to include the full error message.

The extra features that came from contributors

Two additions from 2021 are worth knowing about because they change what you can do with the code without retraining anything.

The first is a script to convert BRAT-formatted annotations into DyGIE format, which is documented in the data documentation. BRAT is a widely used annotation format in the biomedical NLP world, and conversion scripts are how a research codebase becomes usable on a new corpus. Without one, every new dataset meant hand-writing a converter.

The second is SpaCy bindings for DyGIE entity and relation extraction, documented in a section of its own. SpaCy is the dominant Python NLP library, and bindings that expose a research model through a familiar API are often the difference between a model that gets used and one that gets cited. The event extraction path is not covered by the bindings, which matches the shape of the library.

The coreference warning and the coreference-dependent nature of the pipeline make the first addition more interesting than it looks. If you are bringing your own annotated data, the BRAT converter is probably the path of least resistance, and the SpaCy bindings are how you would get the entity and relation output into an existing NLP pipeline without reimplementing the model call.

The repository also has a TODO.md at the root and a doc/ folder with the data, model implementation and debugging, and model configuration documentation, and the model configuration process is described as simplified on the current branch.

Where DyGIE++ is the wrong choice

The first case is a new production system. The framework it depends on is archived, the documented environment does not install, and the pinned Python version is long gone from the package channels. Reproducing a paper result is a legitimate goal and a bounded task. Building a service on top of that is neither.

The second case is a team that wants entity, relation and event extraction today. There is a maintained ecosystem of transformer-based extraction tooling with current models and current documentation, and a span-based architecture from 2019 has to compete with it on results as well as on engineering. The DyGIE++ contribution is conceptual, the idea that mentions should be represented as units in context, and that idea has been absorbed into newer work. A team starting fresh is better served by a model with a maintained implementation.

The third case is anyone who needs coreference, because the coreference code is documented as broken and the condition is not fully spelled out in the visible README.

The alternative worth comparing is a modern Hugging Face token classification pipeline with a mention-aware head, or an instruction-tuned extractor run over documents. The difference in approach is instructive. DyGIE++ is a structured prediction system with a fixed output schema of entities, relations and events, trained on a specific corpus with a specific label set, and it produces structured output directly. A prompt-based extractor is a general text transformation that you point at a task description and get structured output back, with no training and no fixed label set, and its accuracy depends on the model and the prompt rather than on a corpus.

For a research reproduction, a paper reading group, or a baseline to compare a new idea against, this repository is still a legitimate and specific artifact. For anything else, the archived dependency is the deciding fact, and the author says so himself.

Editorial conclusion

dygiepp fits a researcher who wants to reproduce the span-based extraction paper, reuse its pretrained models, or study contextualized span representations as a technique, since the code, the model configs and the data scripts are all present and the project explains what it does in detail. It is the wrong choice for a new production system, because the documented environment no longer installs and the underlying framework is archived. Before you plan on running it, read the October 2023 update and try the install yourself, expect to pin older packages or rebuild the environment, and treat the pretrained model collection as the more likely reason to use this repository than the training code.

Frequently asked questions

Official sources

1. dwadden/dygiepp on GitHub
2. Issues
3. License: MIT
4. README