D3js graphs from Stata

[wbuchanan]

Creating D3js data visualizations in Stata just got a little bit easier. If you go to the libd3 Mata library repository, you'll find an object oriented D3js wrapper written in Mata with a few utility functions. In addition to implementing all of the methods/functions in the D3js library (to the best of my knowledge at least), the library includes functions that allow users to store their own JavaScript code; static members to make it a bit easier to insert newline characters/spaces, JavaScript style indents; print methods that attempt to "pretty" print the JavaScript code; and an undo method that allows you to roll back the object to its immediately prior state (e.g., if you pass some arguments and decide you didn't need it you can call .undo() to revert the object back to its state prior to current unwanted state). Additionally, with few exceptions, you can generally take existing D3js code and have a working and parameterized version of the existing code without too much additional effort

// d3.svg.axis() won't work directly

// Create a d3 object
x = d3()

// Now create the equivalent from above
x.init().svg().axis()

You can find a working example of a graph created with a Mata function called d3scatterTip at http://wbuchanan.github.io/d3mata-examples/.

If you're interested in testing/using this, you'll also need the libhtml Mata library to create HTML tag objects. The libhtml Mata library contains class definitions for all of the HTML5 defined tags, with corresponding accessors to tag specific attributes and global attributes. If you find any bugs/issues with any of this, please submit an issue to the corresponding GitHub repository so I can keep track of things a bit more easily and consistently.

[wbuchanan]

Anyone interested should now be able to download/compile the code locally using:

net inst libhtml, from("http://wbuchanan.github.io/matahtml")
net inst libd3, from("http://wbuchanan.github.io/d3mata")

For help compiling the Mata code from either package, there is a corresponding .ado and help file:

h libhtml
h libd3

Which are helper commands that do the compilation for you with options that you can pass to either program.

[ericmelse]

Dear William,

Note that when I run:
net inst libhtml, from("http://wbuchanan.github.io/matahtml")
an error is returned:
package file too long
could not load libhtml.pkg from http://wbuchanan.github.io/matahtml/

Possibly easily solved.

Best regards,
Eric Melse

[wbuchanan]

Eric Melse thanks for pointing this out. I hadn't run into this type of an error previously, so I'll probably add something to libhtml.ado to download the files and/or look into whether or not there is an alternate method of writing the .pkg file. I'll post a follow up once I do that but there should be something before the end of the day.

[wbuchanan]

Hi ericmelse,

The issue should be all set now. The new .pkg file only installs the .ado and .sthlp files. There is a new parameter in libhtml.ado that I need to add to the documentation named src which takes a string where the mata source will be downloaded.

[ericmelse]

Indeed, the installation problem has been solved !

[wbuchanan]

I just pushed an update to the style class object in the libhtml mata library. There is only one difference, but it is something that can help to keep the code base a bit cleaner. Previously the .setClassArgs() method of the style class only accepted a string and would print those values to the final HTML document. Now, the method first tests whether or not the string passed to the method is a file and if so, it will read the file and print the file contents within the style HTML element tags. I'll probably make a similar change to the script class as well to further encapsulate the D3js functionality from the construction of the HTML document. As time permits, I'm going to try building out a struct that will allow people to create an HTML template with the ability to insert/remove elements from the DOM. One of the biggest challenges with this is trying to work through nesting rules and/or creating a flexible enough structure to store the elements in a way that permits nesting them easily. I'm going to see if I can coerce a transmorphic matrix into accepting any of these objects as scalars, in which case elements could be inserted/removed using column indices and row indices would provide the overall flow of the elements across the document. If anyone has any thoughts/ideas on how to do this I'd love to hear other thoughts/potential approaches.

[wbuchanan]

New example available and created a landing page for the project.

d3splom using /Applications/Stata/ado/base/a/auto.dta, out("`c(pwd)'/splomExample/") file("auto.json") vln("varnames") style("/Users/billy/Desktop/Programs/StataPrograms/d/d3/examples/splomExample/splom.css") om("make, foreign rep78") pal("category10") col("obj_function(d) { return d[rep78]; }")

Like the previous examples, this requires the most current version of the jsonio package. You can see an example of the graph here. The graph is a generalization of this graph created by Mike Bostock which is a scatterplot matrix that includes brushing and linking. If you're not familiar, brushing and linking is an interaction technique that allows you to select a subset of observations by clicking and dragging in the graph area (e.g., the brush) and performs the same action on the selected data in any other graphs/objects (e.g., linking). In this case, you can brush to select a subset of points from the auto.dta dataset which will suppress the colors of non-selected points in the other cells of the scatterplot matrix.

The example repository can be found at https://github.com/wbuchanan/d3mata-examples. Unlike the previous example, this example helps to show how others can develop their own functions (in Stata or Mata) and use that modularity to more easily generate graph components.