# 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

adding vertices of various formats to a graph

connecting them with edges

grouping them into subgraphs and clusters,

providing styling to all these elements

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

Adds a vertex to `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 section Functions

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`

.

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]
```

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.
```

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.
```

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"
```

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]
```

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.

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>
]
```

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"]
})
```

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!")`

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"
]
```

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.

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.