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')]
>>> g.edges()
[Edge(source='b', role=':ARG0', target='d')]
>>> print(penman.encode(g, indent=3))
(b / bark-01
   :ARG0 (d / dog))
>>> print(penman.encode(g, indent=None))
(b / bark-01 :ARG0 (d / dog))

(more information)

Script Usage

$ echo "(w / want-01 :ARG0 (b / boy) :ARG1 (g / go :ARG0 b))" | penman
(w / want-01
   :ARG0 (b / boy)
   :ARG1 (g / go
            :ARG0 b))
$ echo "(w / want-01 :ARG0 (b / boy) :ARG1 (g / go :ARG0 b))" | penman --make-variables="a{i}"
(a0 / want-01
    :ARG0 (a1 / boy)
    :ARG1 (a2 / go
              :ARG0 a1))

(more information)

Demo

For a demonstration of the API usage, see the included Jupyter notebook:

• View it on GitHub: docs/api-demo.ipynb

• Run it on mybinder.org:

  (Note: clear the output before running: Cell > All Output > Clear):

PENMAN Notation

A description of the PENMAN notation can be found in the documentation. This module expands the original 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

The canonical citation for the Penman library will soon be a system demo paper for ACL 2020. Until the proceedings are published, simply 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.