rPref (version 1.3)

plot_btg: Better-Than-Graphs

Description

Returns/plots a Hasse diagram of a preference order (also called the Better-Than-Graph, short BTG) on a given data set. Ploting within R relies on the igraph package or the Rgraphviz package. Alternatively, a dot file for an external graphviz/dot interpreter can be generated.

Usage

plot_btg(df, pref, labels = 1:nrow(df), flip.edges = FALSE,
  levelwise = TRUE, use_dot = "Rgraphviz" %in%
  rownames(installed.packages()))
get_btg(df, pref, flip.edges = FALSE, use_dot = "Rgraphviz" %in%
  rownames(installed.packages()))
get_btg_dot(df, pref, labels = 1:nrow(df), flip.edges = FALSE,
  levelwise = TRUE, file = NULL)

Arguments

df

A data frame.

pref

A preference on the columns of df, see psel for details.

labels

(optional) Labels for the vertices. Default values are the row indices.

flip.edges

(optional) Flips the orientation of edges, if TRUE than arrows point from worse nodes to better nodes.

levelwise

(optional) Only relevant is the dot layouter is used. If TRUE, all tuples from the same level are placed on one row. If FALSE, the row arrangement is subject to the dot layouter.

use_dot

(optional) If TRUE, the dot layouter from Rgraphviz is used. If FALSE, igraph is used. By default this is TRUE iff Rgraphviz is available.

file

(optional) If specified, then get_btg_dot writes the graph specification to given file path. If not specified, the graph specification is returned as a string.

BTGs with igraph

If used with use_dot = FALSE, the function get_btg returns a list l with the following list entries:

l$graph

An igraph object, created with the igraph package.

l$layout

A typical Hasse diagram layout for plotting the graph, also created with igraph.

To plot the resulting graph returned from get_btg, use the plot function as follows:

plot(l$graph, layout = l$layout)

For more details, see igraph.plotting.

BTGs with Rgraphviz

If used with use_dot = FALSE, the function get_btg returns a graphNEL object from the graph-package (Rgraphviz is build on top of that package). This object can also be plotted using plot(...).

Direct Plotting

In both cases (wheter Rgraphviz is used or not), the function plot_btg directly plots the Better-Than-Graph. There is an additional parameter labels, specifying the node labels. The default are the row numbers (not the rownames of the data frame), ranging from "1" to as.character(nrow(df)).

Dot (Graphviz) String Output

The function get_btg_dot produces the source code of the Better-Than-Graph in the dot language of the Graphviz software. This is useful for an external dot interpreter. Depending on the file parameter the output is either written to a file (if a file path is given) or returned as a string (if file = NULL).

Additional Parameters

By default, the directed edges in the diagram point from better to worse nodes w.r.t. the preference. This means an arrow can be read as "is better than". If flip.edges = TRUE is set, then the arrows point from worse nodes to better nodes ("is worse than"). In any case, the better nodes are plotted at the top and the worse nodes at the bottom of the diagram.

If Rgraphviz is used for plot_btg and for get_btg_dot, the option levelwise controls if all nodes of the same level are placed in one row. If this parameter is FALSE, then the vertical arrangement is subject to the dot layouter.

Details

The Hasse diagram of a preference visualizes all the better-than-relationships on a given data set. All edges which can be retrieved by transitivity of the order are omitted in the graph.

The functions get_btg and plot_btg either use the igraph package (if use_dot = FALSE) or the dot layouter from the Rgraphviz package (if use_dot = TRUE). If Rgraphviz is available it is used by default, otherwise the igraph Package is used. Note that Rgraphviz is only available on BioConductor and not on CRAN.

The dot layouter from Rgraphviz is more appropriate for Better-Than-Graphs than the igraph layouter, as all edges will be directed in the same direction (rank based ordering). Using levelwise = TRUE (the default), all tuples of the same level are placed on the same row.

Examples

# pick a small data set and create preference and BTG 
df <- mtcars[1:10,]
pref <- high(mpg) * low(wt)

# directly plot the BTG with row numbers as labels
# uses Rgraphviz if available and igraph otherwise
plot_btg(df, pref) 

# plot the graph with labels with relevant values
labels <- paste0(df$mpg, "; ", df$wt)
plot_btg(df, pref, labels)
     
# show lattice structure of 3-dimensional Pareto preference
df <- merge(merge(data.frame(x = 1:3), data.frame(y = 1:3)), data.frame(z = 1:2))
labels <- paste0(df$x, ",", df$y, ",", df$z)
plot_btg(df, low(x) * low(y) * low(z), labels)
     
# Create a graph with external Graphviz (requires installed Graphviz)
if (FALSE) {
# creates tmpgraph.dot in the current working directoy
get_btg_dot(df, pref, labels, file = "tmpgraph.dot")
# convert to diagram tmpgraph.png using Graphviz
shell(paste0('"C:/Program Files (x86)/Graphviz2.38/bin/dot.exe"',
             ' -Tpng tmpgraph.dot -o tmpgraph.png'))
# open resulting image
shell("tmpgraph.png")}