d2: Generate D2 input text to plot objects

Description

Produces text input for D2 to make a diagram of a given object, usually rendered with SVG.

Usage

d2(x, ...)

Value

A scalar character, containing text input for D2.

Arguments

x: an object to be plotted.
...: further arguments passed to or from other methods.

Details

The D2 language is in an early stage of development (pre-v1.0), so it may be subject to changes that make it unable to use output from the current version of d2.

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.
- 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, then currently the name is not used, except as a single data frame's name. In the future, this will be used to give a name to the generated board, to make use of D2's composition features.

Examples

Run this code

# simple data.frame example
cat(d2(ChickWeight, "chick"))
# simple database example
db <- autodb(ChickWeight)
cat(d2(db))
# simple relation schemas
rschema <- synthesise(discover(ChickWeight))
cat(d2(rschema))
# simple database schema
dschema <- normalise(discover(ChickWeight))
cat(d2(dschema))
# simple relations
rel <- create(synthesise(discover(ChickWeight)))
cat(d2(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)
cat(d2(nested))

Run the code above in your browser using DataLab