R: Better-Than-Graphs

plot_btg {rPref} | R Documentation

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

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

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

### 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)
    ## Not run:
    # 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")
    ## End(Not run)

[Package rPref version 1.3 Index]