Haghish, E. F. (2014). Applied Statistics Using Stata.

Free Online Stata Tips & Tutorials. Data Management; Stata Graphs and Graphics; Data Analysis; Stata Programming; Advanced Statistics

Updated on 30 March 2016

DOT.js : Literate Programming with Literate Graphics in R

| Introduction |     | Installation |     | Using Statax |     | Editing Statax CSS |     | Statax Package |     | Download Statax |    

Quick Tips

dot.js is a JavaScript library for rendering DOT graphics in HTML document, inclding R-HTML in RStudio and MarkDoc Package in Stata. It includes simple and intuitive syntax which can be used even by newbies. After including the dot.js in the heading of your HTML document, apply <graph> and </graph> html tags to write your DOT markups. To include the script in the document, simply copy and paste the code below in the <head> tag of your HTML document. If you are using RStudio, you can have a lot of fun with dot.js and R-HTML for generating dynamic documents with dynamic graphics!

<script type="text/javascript" src='http://haghish.com/dot/dot.js'></script>
  • This document may not get rendered correctly in Mobile browsers
  • The DOT.JS JavaScript library is very heavy. So it may take a few seconds to render the DOT graphics, based on your internet speed

E. F. Haghish
Center for Medical Biometry and Medical Informatics
University of Freiburg, Germany
haghish@imbi.uni-freiburg.de
and
Department of Mathematics and Computer Science
University of Southern Denmark
Twitter: @Haghish


Introduction

Literate programming provides a solution for reproducible documentation of source code of a software, computation, or even a statistical data analysis. Based on the application, some software allow generating graphics and appending them to the documentation within the code such as RMarkdown and RHTML in R and MarkDoc in Stata. However, both R and Stata are not capable of creating procedural graphs. For example, let's imagine that I wish to create a graph to illustrate the procedure of data analysis, beginning with cleaning the data, exploratory analysis and data visualization, hypothesis testing, interpretation, and documentation. Can you visualize this procedure in R or Stata, without proving that you are a weirdo? Such a graph can be easily created using DOT, a graph description language capable of rendering complex graphs using plain text. In this document I introduce dot.js a library which is ready to be used in any HTML document to render DOT graphics. I will also demonstrate how to use DOT inline with literate programming packages, particularly R-HTML in RStudio to develop dynamic documents that are capable of creating dynamic graphs! Note that dot.js can be used in any HTML document but for the rest of this document I will be focusing on literate programming in R to demonstrate how you can create literate dynamic graphs within your R code.

digraph G { rankdir="LR"; node[fontsize=10] graph[size="9,3"] a -> b; b -> c; c-> d; d-> e; e->f; f -> g; a [label="Raw Data"]; b [label="Cleaning data"]; c [label="Exploratory analysis"]; d [label="Hypothesis testing"]; e [label="Inference"]; f [label="Dynamic report"]; g [label="Publication"]; }
<graph>
digraph G {
    rankdir="LR";
    node[fontsize=10]
    graph[size="9,3"]
    
    a -> b; b -> c; c-> d; d-> e; e->f; f -> g;
    
    a [label="Raw Data"];
    b [label="Cleaning data"];
    c [label="Exploratory analysis"];
    d [label="Hypothesis testing"];
    e [label="Inference"];
    f [label="Dynamic report"];
    g [label="Publication"];
}
</graph>

As you can see in the code of the example above, I just created labels for each object, since each object name can be just a single word (yet, it could be Raw_data, Cleaning_data, etc). This is a very simple graph. I can change the shape and color of objects, just to show you what you can do with DOT.

digraph G { rankdir="LR"; node[fontsize=10] graph[size="9,3"] a -> b; b -> c; c-> d; d-> e; e->f; f -> g; a [shape=triangle,color=lightblue,style=filled,label="Raw Data"]; b [shape=box,color=ivory,style=filled,label="Cleaning data"]; c [shape=polygon,sides=5,color=lightsalmon,style=filled,label="Exploratory analysis"]; d [shape=hexagon,color=lightseagreen,style=filled,label="Hypothesis testing"]; e [shape=polygon,sides=7,color=orangered,style=filled,label="Inference"]; f [shape=octagon,pcolor=lightcyan,style=filled,label="Dynamic report"]; g [shape=ellipse,color=lightyellow,peripheries=4,style=filled,label="Publication"]; }
<graph>
digraph G {
    rankdir="LR";
    node[fontsize=10]
    graph[size="9,3"]
    
    a -> b; b -> c; c-> d; d-> e; e->f; f -> g;
    
    a [shape=triangle,color=lightblue,style=filled,label="Raw Data"];
    b [shape=box,color=ivory,style=filled,label="Cleaning data"];
    c [shape=polygon,sides=5,color=lightsalmon,style=filled,label="Exploratory analysis"];
    d [shape=hexagon,color=lightseagreen,style=filled,label="Hypothesis testing"];
    e [shape=polygon,sides=7,color=orangered,style=filled,label="Inference"];
    f [shape=octagon,pcolor=lightcyan,style=filled,label="Dynamic report"];
    g [shape=ellipse,color=lightyellow,peripheries=4,style=filled,label="Publication"];
}
</graph>

Installation

You may use dot.js in your HTML document or within RHTML in RStudio to create dynamic documents with dynamic graphs. In either case, you should begin with adding dot.js to the heading of your HTML document. To do so, place the following script in the heading of the document, between <head> and </head> tags.

<script type="text/javascript" src='http://haghish.com/dot/dot.js'></script>


Below are 2 templates documents for RHTML and HTML format that include the "Hello -> World" example.

DOT template for Rhtml and Knitr package

DOT plain-text HTML template

Using DOT in literate programming packages

In order to use Statax for highlighting Stata code, the code should be wrapped with a <pre> tag and sh_stata class as shown below. The <pre> tag preserves the white-space and the sh_stata class refers to the class of CSS style sheet that defines the color of each Stata syntax element.

<graph>
    graph syntax {
        ...
    }
</graph>

Editing Statax CSS

If you wish to change the colors of the syntax highlighter, you should download and install Statax manually. The Statax.css which includes the style sheet code, has a guide about each element and if you are familiar with CSS, you can create your own style sheet.

Statax Package

There is a Stata package that can convert do and ado files to HTML and highlight their syntax using Statax.js. The package is explained in details here.

  • 1- Remove the Statax.css file
  • 2- Copy any of the Daring.css, Sunset.css, or Wrangler.css files to the directory where the JavaScript files are
  • 3- Rename the new CSS file to Statax.CSS

These styles are shown below respectively:

Download Statax (JavaScript)

Statax JavaScript and CSS files can be downloaded below.

statax.zip JavaScript version 1.0