Skip to main content

PENMAN notation for graphs (e.g., AMR)

Project description

Penman — a Python library for PENMAN graph notation

PyPI Version Python Support Build Status Documentation Status

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

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

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for Penman, version 0.12.0
Filename, size File type Python version Upload date Hashes
Filename, size Penman-0.12.0-py3-none-any.whl (40.6 kB) File type Wheel Python version py3 Upload date Hashes View hashes
Filename, size Penman-0.12.0.tar.gz (34.6 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page