A Prolog-based library for visualizing graphs that uses the GraphViz library.

1. Install SWI-Prolog.

2. Install the GraphViz library:

apt install graphviz # Debian, Ubuntu
dnf install graphviz # Fedora, Red Hat

Install this library:

swipl -g 'pack_install(prolog_graphviz)' -t halt

Once installed, modules from this library are loaded as follows:

?- [library(gv)].

The basic feature of this library is that it allows you to write to a GraphViz output file or to a GraphViz viewer by simply writing to a Prolog output stream. The following example (see example/hello.pl) shows how to write a graph consisting of one node, and open the result in a GraphViz viewer:

?- gv_view([Out0]>>format(Out0, "x [label=<Hello,<BR/>world!>,shape=diamond];\n", [])).

This opens the following image inside a GraphViz-compatible viewer:

In this example (see example/loves.pl) we write a graph that consists of a single edge:

?- gv_export('loves.svg', [Out0]>>format(Out0, "John -- Mary [label=loves];\n", [])).

This writes the following image to an SVG file. See the table in Section Output formats for a full list of supported output formats.

While you can use this library by directly writing DOT strings to an output stream, more advanced export tasks often benefit from using the library's support predicates. The most important ones are:

• dot_node/[2,3] for exporting nodes.
• dot_arc/[3,4] for exporitng (directed) arcs.
• dot_edge/[3,4] for exporting (undirected) edges.

dot_arc/4 and dot_edge/4 take a list of options that are emitted as GraphViz attributes. Option label(+or([string,list(string)])) allows (multi-line) Unicode labels to be emitted using HTML-like labels (see Section HTML-like labels).

Suppose your program returns proof trees that consist of an entailment rule label, a conclusion, and an arbitrary number of premises:

?- Proof = t(rdfs(3),∈(class,class),[t(axiom(rdfs),range(range,class),[]),
                                     t(axiom(rdfs),range(⊆,class),[])]).

The following program (see example/proof_tree.pl) exports such proof trees. Notice that this program uses the support predicates. This allows the nodes to be characterized by Prolog terms instead of DOT IDs. For most programs this results in simplified code because. Since these support predicates are idempotent, emitting the same node/edge multiple times does not accidentally change the exported graph.

:- use_module(library(apply)).
:- use_module(library(graph/gv)).
:- use_module(library(yall)).

view_proof(Proof) :-
  gv_view({Proof}/[Out0]>>export_proof(Out0, Proof), [directed(true)]).

export_proof(Out, Tree) :-
  Tree = t(Rule,Concl,Prems),
  dot_node(Out, Concl),
  dot_node(Out, Tree, [color(green),label(Rule)]),
  dot_arc(Out, Concl, Tree),
  maplist(export_subproof(Out, Tree), Prems).

export_subproof(Out, Node, Tree) :-
  Tree = t(_Rule,Concl,_Prems),
  dot_node(Out, Concl),
  dot_arc(Out, Node, Concl),
  export_proof(Out, Tree).

Since we use the predicate dot_arc/3, we must specify option directed(true) (graphs are undirected by default).

In order to open a specific proof tree, like $Proof, in a GraphViz-compatible viewer, we make the following call:

?- view_proof($Proof).

This produces the following visualization:

Suppose your program returns syntactic parse trees like the following:

?- Tree = s(np(det(the),n(cat)),vp(v(loves),np(det(the),n(dog))))

The following code exports such parse trees to SVG (see example/parse_tree.pl):

:- use_module(library(apply)).
:- use_module(library(graph/gv)).
:- use_module(library(yall)).

export_tree(Tree) :-
  gv_export('parse_tree.svg', {Tree}/[Out0]>>export_tree(Out0, Tree, _)).

export_tree(Out, Tree, Id) :-
  Tree =.. [Op|Trees],
  dot_id(Id),
  dot_node_id(Out, Id, [label(Op)]),
  maplist(export_tree(Out), Trees, Ids),
  maplist(dot_edge_id(Out, Id), Ids).

Notice that in the above program we use dot_node_id/3 instead of dot_node/3 and dot_edge_id/3 instead of dot_edge/3. The *_id versions require us to supply the DOT IDs ourselves. Arbitrary DOT IDs are generated with dot_id/1.

We can generate the visualization for the above syntax tree ($Tree), by making the following call:

?- export_tree($Tree).

This prodices the following result:

Notice that we create a new DOT ID (dot_id/1) for each node in the tree. Because of this, the two occurrences of ‘the’ can be distinguished.

Both directed and undirected graphs can be exported. By default, gv_export/[2,3] and gv_view/[1,2] export undirected graphs. Directed graphs are exported by setting the directed(true) option in gv_export/3 or gv_view/2. For undirected graphs, undirected edges are emitted with dot_edge/[3,4] and dot_edge_id/[3,4]. For directed graph, directed edges or arcs are emitted with dot_arc/[3,4] and dot_arc_id/[3,4].

Sometimes when you use this library, or any other graph export library, a graph export may come out incorrectly: it either does not compile, or it does compile but looks weird. In such cases, it is convenient to be able to print the content that is exported to the top-level for inspection by the programmer. Printing the export to the top-level can be enabled with debug(dot), and disabled by nodebug(dot) (see library debug for more information).

This section gives a full enumeration of the values that are supported by this library's options.

The followig GraphViz layout methods are supported. They can be specified with the method(+atom) option in gv_export/[2,3] and gv_view/[1,2].

The following GraphViz output formats are supported. They can be specified with the format(+atom) option in gv_export/[2,3] and gv_view/[1,2].

The DOT language supports several HTML-like facilities that allow rich labels to be printed for arcs, edges, and nodes. These can be specified by option label(+or([string,list(string)])), which takes either a string or a list of strings. In a list of strings, each string represents one line in a multi-line label.

Strings must adhere to the following BNF grammar for DOT HTML-like labels:

label : text
      | table
text : textitem
     | text textitem
textitem : string
         | <BR/>
         | <FONT> text </FONT>
         | <I> text </I>
         | <B> text </B>
         | <U> text </U>
         | <O> text </O>
         | <SUB> text </SUB>
         | <SUP> text </SUP>
         | <S> text </S>
table : [ <FONT> ] <TABLE> rows </TABLE> [ </FONT> ]
rows : row
     | rows row
     | rows <HR/> row
row: <TR> cells </TR>
cells : cell
      | cells cell
      | cells <VR/> cell
cell: <TD> label </TD>
    | <TD> <IMG/> </TD>

In addition to the above BNF grammar, tags are allowed to have attributes that are formatted similar to HTML attributes. Different tags support different sets of attributes:

• ALIGN="CENTER|LEFT|RIGHT"
• BGCOLOR="color"
• BORDER="value"
• CELLBORDER="value"
• CELLPADDING="value"
• CELLSPACING="value"
• COLOR="color"
• COLUMNS="value"
• FIXEDSIZE="FALSE|TRUE"
• GRADIENTANGLE="value"
• HEIGHT="value"
• HREF="value"
• ID="value"
• PORT="portName"
• ROWS="value"
• SIDES="value"
• STYLE="value"
• TARGET="value"
• TITLE="value"
• TOOLTIP="value"
• VALIGN="MIDDLE|BOTTOM|TOP"
• WIDTH="value"

• ALIGN="CENTER|LEFT|RIGHT"

• COLOR="color"

  Sets the color of the font of text that appears within <FONT>…</FONT>, or the border color of the table or cell within the scope of <TABLE>…</TABLE>, or <TD>…</TD>. This color can be overridden by COLOR attributes in descendents. By default, the font color is determined by the GraphViz fontcolor attribute of the corresponding node, edge or graph, and the border color is determined by the GraphViz color attribute of the corresponding node, edge or graph.

• FACE="fontname"

• POINT-SIZE="value"

• SCALE="FALSE|TRUE|WIDTH|HEIGHT|BOTH"
• SRC="value"

• ALIGN="CENTER|LEFT|RIGHT|TEXT"
• BALIGN="CENTER|LEFT|RIGHT"
• BGCOLOR="color"
• BORDER="value"
• CELLPADDING="value"
• CELLSPACING="value"
• COLOR="color"
• COLSPAN="value"
• FIXEDSIZE="FALSE|TRUE"
• GRADIENTANGLE="value"
• HEIGHT="value"
• HREF="value"
• ID="value"
• PORT="portName"
• ROWSPAN="value"
• SIDES="value"
• STYLE="value"
• TARGET="value"
• TITLE="value"
• TOOLTIP="value"
• VALIGN="MIDDLE|BOTTOM|TOP"
• WIDTH="value"