graphvix v1.0.0 Graphvix.Graph

Models a directed graph that can be written to disk and displayed using Graphviz notation.

Graphs are created by

They can then be

Link to this section Summary

Functions

Group a set of vertices into a cluster in a graph

Add an edge between two vertices in a graph

Add a vertex built from a Graphvix.HTMLRecord to the graph

Add a vertex built from a Graphvix.Record to the graph

Group a set of vertices into a subgraph within a graph

Writes the graph to a .dot file and compiles it to the specified output format (defaults to .png)

Destructures the references to the ETS tables for vertices, edges, and neighbours from the Graph struct

Creates a new Graph struct

Sets a property for a vertex or edge that will apply to all vertices or edges in the graph

Adds a top-level graph property

Write a graph to file, compile it, and open the resulting image in your system’s default image viewer

Converts a graph to its representation using .dot syntax

Writes a Graph to a named file in .dot format

Link to this section Types

Link to this type digraph()
digraph() :: {:digraph, reference(), reference(), reference(), boolean()}
Link to this type t()
t() :: %Graphvix.Graph{
  digraph: digraph(),
  global_properties: keyword(),
  graph_properties: keyword(),
  subgraphs: list()
}

Link to this section Functions

Link to this function add_cluster(graph, vertex_ids, properties \\ [])

Group a set of vertices into a cluster in a graph.

In addition to the graph and the vertex ids, you can pass attributes for node and edge to apply common styling to the vertices included in the cluster, as well as the edges between two vertices both in the cluster.

The difference between a cluster and a subgraph is that a cluster can also accept attributes to style the cluster, such as a border, background color, and custom label. These attributes can be passed as top-level attributes in the final keyword list argument to the function.

Example

iex> graph = Graph.new()
iex> {graph, v1id} = Graph.add_vertex(graph, "start")
iex> {graph, v2id} = Graph.add_vertex(graph, "end")
iex> {_graph, cid} = Graph.add_cluster(
...>   graph, [v1id, v2id],
...>   color: "blue", label: "cluster0",
...>   node: [shape: "triangle"],
...>   edge: [style: "dotted"]
...> )
iex> cid
"cluster0"

In .dot notation a cluster is specified, as opposed to a subgraph, by giving the cluster an ID that begins with "cluster" as seen in the example above. Contrast with Graphvix.Graph.add_subgraph/3.

Link to this function add_edge(graph, out_from, in_to, attributes \\ [])

Add an edge between two vertices in a graph.

It takes 3 required arguments and one optional. The first argument is the graph, the second two arguments are the tail and head of the edge respectively, and the fourth, optional, argument is a list of layout attributes to apply to the edge.

The arguments for the ends of the edge can each be either the id of a vertex, or a tuple of a vertex id and a port name to attach the edge to. This second option is only valid with Record or HTMLRecord vertices.

Examples

iex> graph = Graph.new()
iex> {graph, v1id} = Graph.add_vertex(graph, "start")
iex> {graph, v2id} = Graph.add_vertex(graph, "end")
iex> {_graph, eid} = Graph.add_edge(graph, v1id, v2id, color: "green")
iex> eid
[:"$e" | 0]
Link to this function add_html_record(graph, record)

Add a vertex built from a Graphvix.HTMLRecord to the graph.

iex> graph = Graph.new()
iex> record = HTMLRecord.new([
...>   HTMLRecord.tr([
...>     HTMLRecord.td("start"),
...>     HTMLRecord.td("middle"),
...>     HTMLRecord.td("end"),
...>   ])
...> ])
iex> {_graph, rid} = Graph.add_html_record(graph, record)
iex> rid
[:"$v" | 0]

See [`Graphvix.HTMLRecord`](Graphvix.HTMLRecord.html) for details on [`Graphvix.HTMLRecord.new/2`](Graphvix.HTMLRecord.html#new/2)
and the complete module API.
Link to this function add_record(graph, record)

Add a vertex built from a Graphvix.Record to the graph.

iex> graph = Graph.new()
iex> record = Record.new(["a", "b", "c"])
iex> {_graph, rid} = Graph.add_record(graph, record)
iex> rid
[:"$v" | 0]

See [`Graphvix.Record`](Graphvix.Record.html) for details on [`Graphvix.Record.new/2`](Graphvix.Record.html#new/2)
and the complete module API.
Link to this function add_subgraph(graph, vertex_ids, properties \\ [])

Group a set of vertices into a subgraph within a graph.

In addition to the graph and the vertex ids, you can pass attributes for node and edge to apply common styling to the vertices included in the subgraph, as well as the edges between two vertices both in the subgraph.

Examples

iex> graph = Graph.new()
iex> {graph, v1id} = Graph.add_vertex(graph, "start")
iex> {graph, v2id} = Graph.add_vertex(graph, "end")
iex> {_graph, sid} = Graph.add_subgraph(
...>   graph, [v1id, v2id],
...>   node: [shape: "triangle"],
...>   edge: [style: "dotted"]
...> )
iex> sid
"subgraph0"
Link to this function add_vertex(graph, label, attributes \\ [])

Adds a vertex to graph.

The vertex’s label text is the argument label, and additional attributes can be passed in as attributes. It returns a tuple of the updated graph and the :digraph-assigned ID for the new vertex.

Examples

iex> graph = Graph.new()
iex> {_graph, vid} = Graph.add_vertex(graph, "hello", color: "blue")
iex> vid
[:"$v" | 0]
Link to this function compile(graph, filename, format \\ :png)

Writes the graph to a .dot file and compiles it to the specified output format (defaults to .png).

The following code creates the files "graph_one.dot" and "graph_one.png" in your current working directory.

iex> Graph.compile(graph, "graph_one")

This code creates the files "graph_one.dot" and "graph_one.pdf".

iex> Graph.compile(graph, "graph_one", :pdf)

filename works as expected in Elixir. Filenames beginning with / define an absolute path on your file system. Filenames otherwise define a path relative to your current working directory.

Link to this function digraph_tables(graph)

Destructures the references to the ETS tables for vertices, edges, and neighbours from the Graph struct.

Examples

iex> graph = Graph.new()
iex> Graph.digraph_tables(graph)
[
  #Reference<0.4011094290.3698196484.157076>,
  #Reference<0.4011094290.3698196484.157077>,
  #Reference<0.4011094290.3698196484.157078>
]
Link to this function new(attributes \\ [])

Creates a new Graph struct.

A Graph struct consists of an Erlang digraph record, a list of subgraphs, and two keyword lists of properties.

Examples

iex> graph = Graph.new()
iex> Graph.to_dot(graph)
~S(digraph G {

})

iex> graph = Graph.new(graph: [size: "4x4"], node: [shape: "record"])
iex> Graph.to_dot(graph)
~S(digraph G {

    size="4x4"

    node [shape="record"]

})
Link to this function set_global_properties(graph, attr_for, attrs \\ [])

Sets a property for a vertex or edge that will apply to all vertices or edges in the graph.

NB :digraph uses vertex to define the discrete points in a graph that are connected via edges, while Graphviz and DOT use the word node. Graphvix attempts to use “vertex” when the context is constructing the data for the graph, and “node” in the context of formatting and printing the graph.

Example

iex> graph = Graph.new()
iex> {graph, vid} = Graph.add_vertex(graph, "label")
iex> graph = Graph.set_global_property(graph, :node, shape: "triangle")

When the graph is drawn, the vertex whose id is vid, and any other vertices added to the graph, will have a triangle shape.

Global properties are overwritten by properties added by a subgraph or cluster:

{graph, subgraph_id} = Graph.add_subgraph(graph, [vid], shape: "hexagon")

Now when the graph is drawn the vertex vid will have a hexagon shape.

Properties written directly to a vertex or edge have the highest priority of all. The vertex created below will have a circle shape despite the global property set on graph.

{graph, vid2} = Graph.add_vertex(graph, "this is a circle!")
Link to this function set_graph_property(graph, key, value)

Adds a top-level graph property.

These attributes affect the overall layout of the graph at a high level. Use set_global_properties/3 to modify the global styling for vertices and edges.

Example

iex> graph = Graph.new()
iex> graph.graph_properties
[]
iex> graph = Graph.set_graph_property(graph, :rank_direction, "RL")
iex> graph.graph_properties
[
  rank_direction: "RL"
]
Link to this function show(graph, filename)

Write a graph to file, compile it, and open the resulting image in your system’s default image viewer.

The following code will write the contents of graph to "graph_one.dot", compile the file to "graph_one.png" and open it.

iex> Graph.show(graph, "graph_one")

filename works as expected in Elixir. Filenames beginning with / define an absolute path on your file system. Filenames otherwise define a path relative to your current working directory.

Converts a graph to its representation using .dot syntax.

Example

iex> graph = Graph.new(node: [shape: "triangle"], edge: [color: "green"], graph: [size: "4x4"])
iex> {graph, vid} = Graph.add_vertex(graph, "a")
iex> {graph, vid2} = Graph.add_vertex(graph, "b")
iex> {graph, vid3} = Graph.add_vertex(graph, "c")
iex> {graph, eid} = Graph.add_edge(graph, vid, vid2)
iex> {graph, eid2} = Graph.add_edge(graph, vid, vid3)
iex> {graph, clusterid} = Graph.add_cluster(graph, [vid, vid2])
iex> Graph.to_dot(graph)
~S(digraph G {

  size="4x4"

  node [shape="triange"]
  edge [color="green"]

  subgraph cluster0 {
    v0 [label="a"]
    v1 [label="b"]

    v0 -> v1
  }

  v2 [label="c"]

  v1 -> v2

})

For more expressive examples, see the .ex and .dot files in the examples/ directory of Graphvix’s source code.

Link to this function write(graph, filename)

Writes a Graph to a named file in .dot format

iex> Graph.write(graph, "my_graph")

will write a file named "my_graph.dot" to your current working directory.

filename works as expected in Elixir. Filenames beginning with / define an absolute path on your file system. Filenames otherwise define a path relative to your current working directory.