Penman — a Python library for PENMAN graph notation

This package models graphs encoded in PENMAN notation (e.g., AMR), such as the following for the boy wants to go:

(w / want-01
   :ARG0 (b / boy)
   :ARG1 (g / go
            :ARG0 b))

The Penman package may be used as a Python library or as a script.

Features

• Read and write PENMAN-serialized graphs or triple conjunctions
• Read metadata in comments (e.g., # ::id 1234)
• Read surface alignments (e.g., foo~e.1,2)
• Inspect and manipulate the graph or tree structures
• Customize graphs for writing:
  • Adjust indentation and compactness
  • Select a new top node
  • Rearrange edges
  • Restructure the tree shape
  • Relabel node variables
• Transform the graph
  • Canonicalize roles
  • Reify and dereify edges
  • Reify attributes
  • Embed the tree structure with additional TOP triples
• AMR model: role inventory and transformations
• Check graphs for model compliance
• Tested (but not yet 100% coverage)
• Documented (see the documentation)

Library Usage

>>> import penman
>>> g = penman.decode('(b / bark-01 :ARG0 (d / dog))')
>>> g.triples
[('b', ':instance', 'bark-01'), ('b', ':ARG0', 'd'), ('d', ':instance', 'dog')]
>>> print(penman.encode(g))
(b / bark-01
   :ARG0 (d / dog))
>>> print(penman.encode(g, top='d', indent=6))
(d / dog
      :ARG0-of (b / bark-01))
>>> print(penman.encode(g, indent=False))
(b / bark-01 :ARG0 (d / dog))

(more information)

Script Usage

$ penman --help
usage: penman [-h] [-V] [-v] [-q] [--model FILE | --amr] [--check]
              [--indent N] [--compact] [--triples] [--make-variables FMT]
              [--rearrange KEY] [--reconfigure KEY] [--canonicalize-roles]
              [--reify-edges] [--dereify-edges] [--reify-attributes]
              [--indicate-branches]
              [FILE [FILE ...]]

Read and write graphs in the PENMAN notation.

positional arguments:
  FILE                  read graphs from FILEs instead of stdin

optional arguments:
  -h, --help            show this help message and exit
  -V, --version         show program's version number and exit
  -v, --verbose         increase verbosity
  -q, --quiet           suppress output on <stdout> and <stderr>
  --model FILE          JSON model file describing the semantic model
  --amr                 use the AMR model
  --check               check graphs for compliance with the model

formatting options:
  --indent N            indent N spaces per level ("no" for no newlines)
  --compact             compactly print node attributes on one line
  --triples             print graphs as triple conjunctions

normalization options:
  --make-variables FMT  recreate node variables with FMT (e.g.: '{prefix}{j}')
  --rearrange KEY       reorder the branches of the tree
  --reconfigure KEY     reconfigure the graph layout with reordered triples
  --canonicalize-roles  canonicalize role forms
  --reify-edges         reify all eligible edges
  --dereify-edges       dereify all eligible edges
  --reify-attributes    reify all attributes
  --indicate-branches   insert triples to indicate tree structure

$ penman <<< "(w / want-01 :ARG0 (b / boy) :ARG1 (g / go :ARG0 b))"
(w / want-01
   :ARG0 (b / boy)
   :ARG1 (g / go
            :ARG0 b))

(more information)

Demo

For a demonstration of the API usage, see the included Jupyter notebook at docs/api-demo.ipynb. To run it interactively, ensure Penman is installed and run it with jupyter-notebook. For example, check out this repository and run the following from the project's root directory:

$ python3 -m venv demo
$ source demo/bin/activate
(demo) $ pip install . jupyter
(demo) $ jupyter-notebook demo/api-demo.ipynb

PENMAN Notation

A description of the PENMAN notation can be found in the documentation. See also Nathan Schneider's PEG for AMR.

This module expands the notation slightly to allow for untyped nodes (e.g., (x)) and anonymous relations (e.g., (x : (y))). It also accommodates slightly malformed graphs as well as surface alignments.

Citation

There is not (yet) a canonical citation for the Penman library, so putting https://github.com/goodmami/penman in a footnote is sufficient. If you are referring to the graph transformation/normalization work or prefer an academic citation, please use the following:

@inproceedings{Goodman:2019,
  title     = "{AMR} Normalization for Fairer Evaluation",
  author    = "Goodman, Michael Wayne",
  booktitle = "Proceedings of the 33rd Pacific Asia Conference on Language, Information, and Computation",
  year      = "2019",
  pages     = "47--56",
  address   = "Hakodate"
}

Disclaimer

This project is not affiliated with ISI, the PENMAN project, or the AMR project.