Soon after the announcement of htmlwidgets, Rich Iannone released the DiagrammeR package, which makes it easy to generate graph and flowchart diagrams using text in a Markdown-like syntax. The package is very flexible and powerful, and includes:
Creating diagrams and flowcharts using mermaid.js
Facilities for mapping R objects into graphs, diagrams, and flowcharts.
We’re very excited about the prospect of creating sophisticated diagrams using an easy to author plain-text syntax, and built some special authoring support for DiagrammeR into RStudio v0.99 (which you can download a preview release of now).
If you aren’t familiar with Graphviz, it’s a tool for rendering DOT (a plain text graph description language). DOT draws directed graphs as hierarchies. Its features include well-tuned layout algorithms for placing nodes and edge splines, edge labels, “record” shapes with “ports” for drawing data structures, and cluster layouts (see http://www.graphviz.org/pdf/dotguide.pdf for an introductory guide).
DiagrammeR can render any DOT script. For example, with the following source file (“boxes.dot”):
You can render the diagram with:
Since the diagram is an htmlwidget it can be used at the R console, within R Markdown documents, and within Shiny applications. Within RStudio you can preview a Graphviz or mermaid source file the same way you source an R script via the Preview button or the Ctrl+Shift+Enter keyboard shortcut.
This simple example only scratches the surface of what’s possible, see the DiagrammeR Graphviz documentation for more details and examples.
Support for mermaid.js in DiagrammeR enables you to create several other diagram types not supported by Graphviz. For example, here’s the code required to create a sequence diagram:
You can render the diagram with:
See the DigrammeR mermaid.js documentation for additional details.
Both of the examples above illustrating creating diagrams by direct editing of DOT and mermaid scripts. The latest version of DiagrammeR (v0.6, just released to CRAN) also includes facilities for generating diagrams from R code. This can be done in a couple of ways:
Using text substitution, whereby you create placeholders within the diagram script and substitute their values from R objects. See the documentation on Graphviz Substitution for more details.
Using the graphviz_graph function you can specify nodes and edges directly using a data frame.
Future versions of DiagrammeR are expected to include additional features to support direct generation of diagrams from R.
Diagrams created with DiagrammeR act a lot like R plots however there’s an important difference: they are rendered as HTML content rather than using an R graphics device. This has the following implications for how they can be published and re-used:
Within RStudio you can save diagrams as an image (PNG, BMP, etc.) or copy them to clipboard for re-use in other applications.
From within RStudio you can also publish diagrams to RPubs or save them as standalone web pages.
See the DiagrammeR documentation on I/O for additional details.
To get started with DiagrammeR check out the excellent collection of demos and documentation on the project website. To take advantage of the new RStudio features that support DiagrammeR you should download the latest RStudio v0.99 Preview Release.
In this series, we walk through lesser-known tips and tricks to help you work more effectively and efficiently in R Markdown. This third post focuses on features that save you time and trouble.
The RStudio IDE includes a visual markdown editor that displays changes in real-time and provides support for technical writing. This post walks through several features of visual editing mode.