gv: Generate Graphviz input text to plot objects

Description

Produces text input for Graphviz to make an HTML diagram of a given object.

Usage

gv(x, name = NA_character_, ...)

Value

A scalar character, containing text input for Graphviz.

Arguments

x: an object to be plotted.
name: a scalar character, giving the name of the object, if any. This name is used for the resulting graph, to allow for easier combining of graphs into a single diagram if required.
...: further arguments passed to or from other methods.

Details

Details of what is plotted are given in individual methods. There are expected commonalities, which are described below.

The object is expected to be one of the following:

an object whose elements have the same length. Examples would be data frames, matrices, and other objects that can represent relations, with names for the elements, and an optional name for the object itself.
a graph of sub-objects, each of which represent a relation as described above, possibly with connections between the objects, and an optional name for the graph as a whole.

Each relation is presented as a record-like shape, with the following elements:

A optional header with the relation's name, and the number of (unique) records.
A set of rows, one for each attribute in the relation. These rows have the following contents:
- the attribute names.
- a depiction of the relation's (candidate) keys. Each column represents a key, and a filled cell indicates that the attribute in that row is in that key. The keys are given in lexical order, with precedence given to keys with fewer attributes, and keys with attributes that appear earlier in the original data frame's attribute order. Default output from other package functions will thus have the primary key given first. In the future, this will be changed to always give the primary key first.
- optionally, the attribute types: specifically, the first element when passing the attribute's values into class. If the type is a container, such as a list or matrix, this can also include dimension information, and information about the contained type.
- optionally, a count of missing values. See Examples for how this interacts with container types.

Any foreign key references between relations are represented by one-way arrows, one per attribute in the foreign key.

If the object has a name, this name is attached to the resulting graph in Graphviz. This is to allow easier combination of several such graphs into a single image, if a user wishes to do so.

Examples

Run this code

# simple data.frame example
txt_df <- gv(ChickWeight, "chick")
cat(txt_df)
if (requireNamespace("DiagrammeR", quietly = TRUE)) {
  DiagrammeR::grViz(txt_df)
}
# simple database example
db <- autodb(ChickWeight)
txt_db <- gv(db)
cat(txt_db)
if (requireNamespace("DiagrammeR", quietly = TRUE)) {
  DiagrammeR::grViz(txt_db)
}
# simple relation schemas
rschema <- synthesise(discover(ChickWeight))
txt_rschema <- gv(rschema)
cat(txt_rschema)
if (requireNamespace("DiagrammeR", quietly = TRUE)) {
  DiagrammeR::grViz(txt_rschema)
}
# simple database schema
dschema <- normalise(discover(ChickWeight))
txt_dschema <- gv(dschema)
cat(txt_dschema)
DiagrammeR::grViz(txt_dschema)
# simple relations
rel <- create(synthesise(discover(ChickWeight)))
txt_rel <- gv(rel)
cat(txt_rel)
if (requireNamespace("DiagrammeR", quietly = TRUE)) {
  DiagrammeR::grViz(txt_rel)
}
# container types and missing values
nested <- data.frame(key = 1:4, nullable = c(1:3, NA))
## matrices are reported with their column count and contained type
## matrix rows only count as missing if the entire row is missing
nested$matrix <- matrix(c(1:2, NA, NA, 5:7, NA, 9:11, NA), ncol = 3)
## lists and data frames aren't checked for missing values, because it's
## unclear what should count
nested$list <- list(1L, 2:3, NULL, NA)
nested$df <- data.frame(a = c(1:3, NA), b = c(1:2, NA, NA))
## lists are reported with any common element length/type
nested$uniform_list <- list(1:2, 3:4, 5:6, 7:8)
## container type information can be nested
nested$matrix_list <- list(
  matrix(1:4, ncol = 2),
  matrix(5:8, ncol = 2),
  matrix(9:12, ncol = 2),
  matrix(13:16, ncol = 2)
)
nested$nested_list <- replicate(4, list(1:2, 3:4, 5:6), simplify = FALSE)
txt_nested <- gv(nested)
cat(txt_nested)
if (requireNamespace("DiagrammeR", quietly = TRUE)) {
  DiagrammeR::grViz(txt_nested)
}