metAMoRphosED: the AMR editor

• metAMoRphosED is a graphical editor for easily editing Abstract Meaning Representation graphs (AMRs). metAMoRphosED displays the graph in a graphical format and allows adding/deleting instances, edges, attributes and comments in a simple way.
• metAMoRphosED makes it possible to add a graph to an existing graph.
• metAMoRphosED reads and writes AMR-files in(to) "PENMAN" format. For examples of this format, visit the AMR guidelines and the corpora released by by LDC (https://catalog.ldc.upenn.edu/LDC2020T02).
• metAMoRphosED runs as a local Web server, an internet browser must be used to navigate through the sentences and modifiy them. If the edited file is under git version control, every modification is automatically committed to the local repository.
• metAMoRphosED can be started in comparison mode in order to compare two AMR files (e.g. a gold file and a predicted file, see section AMR file comparison).
• metAMoRphosED allows text-grounded annotatation of coreferences in AMR graphs. See coref/README.md for more information.
• metAMoRphosED allows download of the displayed graphs as SVG or export of all graphs in either SVG, PDF or PNG format.
• metAMoRphosED provides a script to calculate inter-annotator agreement (see section Inter-annotator agreement).
• metAMoRphosED comes with an docker image (for editing and comparing only, see section Docker).

Current version 4.6.3 (see CHANGES.md)

TL;DR

• if you're updating from version up to 4.0.0: the file server.py has been renamed to metamorphosed_server.py, also install the additional packages:

pip install rdflib==7.0.0 oxrdflib==0.3.7

or

uv add rdflib==7.0.0 oxrdflib==0.3.7

• if you are updating from versions up to 3.3.0, please install an additional packages:

pip install smatchpp==1.7.0 rdflib==7.0.0 oxrdflib==0.3.7

or

uv add smatchpp==1.7.0 rdflib==7.0.0 oxrdflib==0.3.7

installation

using uv

sudo apt install libffi-dev
uv sync
git submodule update --init
pushd propbank-frames/frames
  git checkout ad2bafa4c9c9c58cc1bc89
  wget https://raw.githubusercontent.com/propbank/propbank-frames/development/frames/AMR-UMR-91-rolesets.xml
popd
./metamorphosed/installJQ.py

Linux

python 3.10

apt install graphviz
python3 -m venv VENV
source VENV/bin/activate
pip install -r requirements.txt
git submodule update --init
pushd propbank-frames/frames
  git checkout ad2bafa4c9c9c58cc1bc89
  wget https://raw.githubusercontent.com/propbank/propbank-frames/development/frames/AMR-UMR-91-rolesets.xml
popd
./metamorphosed/installJQ.py

Mac

brew install graphviz
python3 -m venv VENV
source VENV/bin/activate
pip install -r requirements.txt
git submodule update --init
pushd propbank-frames;  git checkout ad2bafa4c9c9c58cc1bc89; popd
./metamorphosed/installJQ.py

Note: For the PropBank frames, we need currently this intermediary version since the main and release-v3.4.1 branches do not contain the definition of roles like be-located-at-91.

The script ./metamorphosed/installJQ.py installs the following into metamorphosed/gui/lib also needed:

• graphviz (see above sudo apt install graphviz)
• https://code.jquery.com/jquery-3.6.0.min.js
• https://cdnjs.cloudflare.com/ajax/libs/jquery-modal/0.9.2/jquery.modal.min.js
• https://cdnjs.cloudflare.com/ajax/libs/jquery-modal/0.9.2/jquery.modal.min.css
• https://jqueryui.com/resources/download/jquery-ui-1.13.2.zip

tests

pytest unittests.py -vv [-k testname] [-s]

For more complete testing use tox:

• with uv

uv add tox
uv run tox

• else

pip install -r requirements-test.txt
tox

run

<install-path>/metamorphosed_server.py -f <amr-file> \
	[-p <port>] \
	[--relations <relations.txt>]
	[--concepts <concepts.txt>]
	[--pbframes <propbank-frames-dir>]
	[--constraints <constraints.yml>]
        [--reifications <reification-table.txt]
        [--readonly]
        [--author 'Name <mail@example.com>']
        [--compare <amr-file2>]
        [--smatchpp]

Use our internet browser as GUI: https://localhost:<port>

• The relations.txt file must contain all the relations which are valid in the AMR graphs, the editor will show a warning for each relation found in a graph which is not mentioned in this file. The relations will also be used for autocompletion. The file metamorphosed/data/relations.txt is used as default value.
• If --concepts concepts.txt is given, the concepts will be used for autocompletion.
• The option --reifications loads a table with relations which can be reified (default: metamorphosed/data/reification-able.txt)
• propbank-frames-dir is the frames directory within the directory where https://github.com/propbank/propbank-frames has been cloned.
• If the edited file is under git version control, every click on save will create a git commit. In order to use a different user name, specify the user with --author 'Name <mail@example.com>'.
• constraints.yml a file which defines predicate and object constraints (i.e. no other predicate and object is allowed in a given context. E.g.:

subjects:
  # name-instances must only have :opN predicates, which have quoted strings as objects (initial _ indicates that the predicated or object is a regex
  name:
    _:op\d:
      - _".*"

  # date-entity instances must only have :month, :day and :year predicates with integer values as objects
  date-entity:
    :month:
      - _\d\d?
    :day:
      - _\d\d?
    :year:
      - _\d\d\d\d

  # (Non AMR) a hotel instances can only have :lieu relation to an address instance or a :starts relation to a hotelclass instance
  hotel:
    :lieu :
      - address
    :stars:
      - hotelclass

  # an and instance dan only have :op1 and :op2 predicates with any object
  and:
    _:op\d:


# constraints for predicates and objects, independent of the subject
predicates:
  :location:
     - city
     - country
  :wiki:
     - _"Q\d+"

  :quant:
     - _\d+
     - _\d\.\d+

A predicate with an initial _ means that the predicate is interpreted as a regex. for example

subjects:
...
  and:
    _:op\d:

means that an instance of the class and may have predicates which match the regex :op\d (":op" followoed by a digit)

Objects with initial _ means that the object of the predicate is not an instance of a class but a literal which matches the regex. E.g.

predicates:
  :wiki:
     - _"Q\d+"

  :quant:
     - _\d+

means that the predicate :wiki (starting at any subject) must have a string literal as object which matches "Q\d+" (including the quotes!). The objects of all predicates :quant must match \d+, i.e. an integer

Note: relations.txt and constraints.yml must not be modified in order to not break the unitary tests. Please use a personalised file.

Docker

Editing and comparing AMR-files can be used by metAMoRphosEd in a docker image

• get current docker image

docker pull jheinecke/metamorphosed:latest

• run the docker container. The AMR files youd want to edit/compare must all be in the same directory and specified in dockers --volume option:

docker run --rm -d -t --name metamorphosed \
	-p 4567:4567 \
	--volume <absolute/path/to/directory/with/you/files>:/data
	--env AMRFILE=<yourfile>
	--env COMPAREWITH="<second-annotator-file> <third-annotator-file>"
	jheinecke/metamorphosed:latest

the option --env COMPAREWITH=... must only be used if you want to compare files

Validate AMR files

The script amrdoc.py can check whether concepts (with an suffixe line -01) are well defined in PropBank and that all used :ARGn relations are defined for a given concept. If a list of valid relations in given, it will detect relations in the AMR file which are not defined.

./validate.py --validate \
	--rels <relations.txt> \
	--pbframes <propbank-frames-dir> \
	--constraintes <constraints.yml> \
	amrfile.txt

If necessary, adapt a copy of constraints.yml to your needs.

Editing

Start the server with an AMR file. The file must have the same format as the official AMR distribution, e.g.:

# ::id a sentence id
# ::snt the sentence in plain text
(.... AMR graph in PENMAN notation)

# ::id following id
...

After a sentence an empty line must follow. If you start annotating new sentence, the initial PENMAN format must be at least an empty pair of parentheses: ()

Once the server is up and running click on one of the navigation buttons to load a sentence (first, preceding, next, last) or enter a sentence number and lick read sentence. The sentence is shown in PENMAN format and in a graphical visualisation.

If the file being edited is under git control, it will be saved under the same name followed by git add/git commit. Else it is saved using an additional .2 file suffix. If the edited file is not git controlled and if the file with suffix .2 exists already, the server exits with an error message. In this case rename the .2 file and edit the renamed file.

The graph can be extended/modified by the functions in the Add concept/edges/names field: fill in the fields and hit the add button

• adding new instances /concepts
• adding relations (like :ARG0 or :location between to instances. If the preceded by /, the following will be interpreted as a conceptname, so a new instances of this concept will be created first and than used for the new relation. The prefix // first tries to find an existing instance of this concept to be used, if this cannot be found, a new instance is created.
• define which instance is the top instance (appears on top in the PENMAN notation)
• add a relation and a literal (like :quant 200)
• add a name instance and :op1 etc. to strings