Develop

Are you adept with d3/javascript/HTML/R? Do you have your own cool ideas for interactive figures? Then we encourage you to develop your own figures within the healthvis platform! It’s pretty easy and lots of fun.

We are in the process of creating a dedicated development version of this project. For now, you can follow the steps below to deploy your own figures to a local App Engine server through our framework. We’d love to add new and useful figures to the package, so please let us know how you’re doing.

All healthvis figures consist of a javascript file (.js), a CSS file (.css) for permanent style choices, and an R file (.R). There are some required elements that must appear in these files for them to be compatible with the healthvis framework. Descriptions and templates for these files appear below.

What you’ll need

git (for pulling the latest project files)
Python 2.7 (or above)
Google App Engine SDK (to launch the application locally)
R (of course), with RCurl, rjson, devtools installed.

Setting up

1. Clone the healthvis repository to your machine: https://github.com/hcorrada/healthvis
2. The appengine folder contains the files needed to run the app server, as well as the javascript and CSS files required to render an interactive figure. You will eventually place the javascript file for your function into appengine/application/static/js/ and your CSS file into appengine/application/static/css/.

The pkg folder contains the components of the R package. Your .R file will be saved under pkg/R/. We also recommend writing a unit test and saving this under pkg/inst/tests/ so that you can quickly test your figure after you make changes (more on this later). Note: when running your R function, make sure you have sourced AllClasses.R, healthvisMethods.R, zzz.R from the pkg/R directory.

File Formats

.R
Write the .R file as you would any function in R. The only extra part you need to specify is what needs to be passed to the server to create your figure. We often pass data by converting it into a JSON object using rjson, but you are free to pass data however you please. Here is a template for a generic .R file:

myfun <- function(input.a, input.b, ..., plot.title="myplot", plot=TRUE, gaeDevel=FALSE,url=NULL){

	#############################
	# R FUNCTIONALITY GOES HERE #
	#############################

	# Parameters to pass to javascript
	d3Params <- list(param1=param1,
			param2=param2,
			...)

	# Form input types and ranges/options
	varType <- c("continuous", "factor")
	
	varList <- list("count" = c(0,100), "choice" = c("A", "B", "C"))

	# Initialize healthvis object
	healthvisObj <- new("healthvis",
			plotType="my_fig",
			plotTitle=plot.title,
			varType=varType,
			varList=varList,
			d3Params=d3Params,
			gaeDevel=gaeDevel,
			url=url)
  
	if(plot){
		plot(healthvisObj)
	}
  
	return(healthvisObj)

}

First, in the definition of the function, we need the arguments plot.title, plot, gaeDevel,url. These correspond to the title of the plot, whether or not to plot the figure, whether to plot the figure on a local server ( gaeDevel=TRUE) or the live server, and whether to use a specific url. For the last two, in development you will always set gaeDevel=TRUE and url=NULL.

Next, you will write whatever it is you want to do with the inputs in R and produce the parameters you need to send to your javascript file. These are passed through d3Params, which is a list of parameters (where the names are what the object will be called on the javascript side).

Finally, we initialize the healthvis object. This object will always be of type “healthvis”. plotType will be a string decided by you that briefly indicates what your plot does. For other plots, we have used strings like “heatmap”, “iconArray”, etc. You will eventually add this name to a file on the server so that the server knows to expect plots of this type (explained later). plotTitle is simply the title of the plot (note: please make sure there is a default name, as an empty string here can cause problems).

varType, varList define the sidebar form inputs. Currently, you can have either a drop-down box of choices or a text box input. varType is a character vector containing either “continuous” for a text box input or “factor” for a drop-down box. varList is a list of the same length as varType where each name corresponds to the name of the input box to appear. In the example above, we want one text box input and one drop-down input. We have named the text box “count” and the drop-down “choice”. For a “continuous” input (here, “count”), we specify the allowed range of values (here, c(0,100)). For a “factor” input (here, “choice”), we specify the categories to appear (here, c("A","B","C")).

We pass the list of parameters (d3Params), and the gaeDevel, url options explained earlier, and the function is ready to go!

.js

Before beginning with the .js file, we need to make sure that the server is prepared for your new figure. In the R file example above, we set plotType="my_fig". To make communication possible, we need to edit appengine/application/settings.py. All you need to do is add your plotType to the supported_types array at the bottom. So in our case, the array should look like
supported_types = ['accuracy_table',...,...,'my_fig']

All javascript files must have three components to work in our framework: initialize, visualize, update. Here is a template:

function HealthvisMyfig() {

	this.w = 700;
	this.h = 500;

	this.init = function(elementId, d3Params){

	// Create your div
	this.div = d3.select('#main')...;

	// Reset width and height if embedding
	var dim = healthvis.getDimensions(this.w, this.h);
	this.w = dim.w;
	this.h = dim.h;

	// Initialize variables
	this.param1 = d3Params.param1;
	this.param2 = d3Params.param2;
	...

	};
	
	this.visualize = function(){

	// Set up your visualization area here.
	this.grid.selectAll(".row")...;

	};

	this.update = function(formdata){

	// formdata contains the current state of the sidebar form.
	// Parse it and use it to update your visualization.

	var par1 = formdata[0].value;
	var par2 = formdata[1].value;

	this.grid.transition()...;

	};
}

healthvis.register(new HealthvisMyfig());

First, make sure your file has the same name as your plotType – so this file would be called my_fig.js. We name our function as Healthvis[FIGURE_NAME]().

this.init(elementId,d3Params) is where you initialize your variables. We ask you to use the function healthvis.getDimensions(), which resets the height and width of the figure if the figure is being embedded. Most importantly, it is where the parameters passed from R are parsed and saved into convenient javascript objects. Recall that we had param1, param2 in our R code. In this.init we have simply transferred them into local variables. If you are passing a more complicated structure (such as an array), you will likely initialize it differently.

Note: please use this.init to initialize the div that you want to use via d3.select. Always use d3.select(elementId) and go from there.

Once everything is initialized, we write this.visualize() to create the initial state of the figure. This is where you would set the layout, set axes, set initial colors, etc.

Finally, the figure needs to know what to do when the form data is changed. This action is specified in this.update(formdata), where formdata is an object containing the names and current values of each form input box. this.update is run every time a form box is changed. This is where you would put your transition code.

The object is then registered, and we are ready to go!

.css

We can additionally have a .css file for any fixed stylistic choices, such as axes color and rendering, line colors, or whatever the user should not be altering. Again, make sure that your file has the same name as plotType (in our case it would be my_fig.css). This file can also remain empty if you do not wish to have any fixed styles.

Launching and Testing

If you’ve gotten here, you now know how to write each of the three necessary files and where to put them. The last step is to launch the local app server and test out your figure. To do this, simply run the Google App Engine Launcher and Add an Existing Application under the File menu. Point this to appengine/app.yaml and hit Run. NOTE: on macs, you only need to select the appenigne directory.

Once the app server is running, you can run your function in R (make sure to set gaeDevel=TRUE). We also recommend adding a unit test under pkg/inst/tests/. Name it test-devel-myFig.R (since you will only be testing locally), and check out some of the existing unit tests to get an idea of what you may want in there.

Next Steps

First of all, if something did not work or you are having difficulties, please don’t hesitate to email us.

If you’ve made it through and have a functioning healthvis figure, first of all, congrats! We would love to see it, hear about it, test it out, etc., etc. And if you are interested and willing to have this figure included in our existing package, we’d be happy to talk to you about that as well!

Happy coding!

Advertisements

One thought on “Develop

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s