*! version 0.0.0 31DEC2015
help libd3

Title

libd3 -- A utility program to compile the libd3 Mata library.

Syntax

libd3 [, replace library mosave
dir(passthru) size(passthru) complete ]

Description

libd3 is a Mata wrapper around the D3
JavaScript library. This program provides a convenience command to compile the
Mata classes/methods into a Mata library file locally. Additionally, there are
options provided to compile the classes and save them into compiled object files
(see mata mosave for additional information). When called without
arguments the classes will be compiled for the Stata session, but will not
persist without the mosave or library options. For additional
information about this package visit the project repository
http://github.com/wbuchanan/d3mata.

Options

replace option specifies that any existing instances of the
class definitions should first be dropped before recompiling. This option also
causes the program to overwrite previously save object or library files.

library an option used to create a .mlib file containing all
of the compiled classes and methods. For additional information about .mlib files
see mata mlib.

mosave an option used to save each compiled Mata class in its
own object file. See mata mosave for additional information.

dir is an option passed directly to either the mata mosave
or mata mlib commands based on either the mosave or library
options being specified.

size is an option that only affects the creation of a .mlib file.
If no value is specified, the program defaults to the maximum allowable value (2048).

complete is an option used in conjunction with the mosave or
library options and throws an error if the class definition is incomplete.
This option can be helpful to ensure the classes compile correctly on your
system before submitting an issue to the github repository.

Integration with other packages

jsonio

The jsonio package was
developed with features specifically to make it easier to use the metadata features
of Stata to generate data visualizations that include these data. For example,
to access value labels for a variable you can use the d3.json() function to
load a JSON file created by jsonio
and can access the values like:

d3.json("filepath/file.json", function(error, json) {

if (error) return console.warn(error);

var data = json.data.values,

varlabels = json["variable labels"],

valueLabels = json["value labels"],

varnames = json["variable names"];

svg.text(function(d) { return valueLabels["varname"][d];});

}

In this case, "varname" is a place holder for the variable name that
has labeled values. This function then returns the value label associated with
the individual value for that variable. For variable labels, you can just pass
the name of the variable to the varlabels array like: varlabels["varname"].

libhtml

A central part of using this class in a standalone manner is how the d3
class integrates with the libhtml
package. The libhtml package
provides Mata classes representing HTML5 DOM elements. You can use the
.printer() method of the d3 class to print all of your d3 objects inside of
a <script></script> HTML tag by calling the .setClassArgs() method of the
script class and passing the d3.printer() method to it to output your JavaScript
code between the script tags.

Additional information

For additional information on how to use this program, visit the
d3mata-examples repository.
This repository will be used to store Mata functions that make it easier to
create reusable code for generating D3js-based data visualizations.

Author

William R. Buchanan, Ph.D.

Data Scientist

Minneapolis Public Schools

William.Buchanan at mpls [dot] k12 [dot] mn [dot] us