UMD Javascript Plotting Utility

Introduction
Version
Version
Interactions
Options

Common Options
Histogram only Options
Scatter Plot only Options

Overlay
Error Bars

Introduction

There are many ways to make scatter plots, graphs, bar charts, pie charts, etc in javascript. Google developers have a wonderful set of free javascript sources that you can use called Google Charts that are quite powerful, and SitePoint has a whole page of javascript libraries for this purpose.

So why develop yet another? Partly because I can, that is, to learn now. But also because any most of the libraries have to be downloaded, so you need to always have the internet, and good access at that. Because any library that is supported by companies like Google grow to be large and complex and easy to use unless you want to do something they haven't intended. Because the documentation is not all that great (like much documentation, it's written by the developers for the developers, and not for the users as much). Because for science purposes (which is what I am pursuing), we don't need fancy bar charts, etc, we just need histograms and scatter plots, whereas other libraries are of course comprehensive, and very useful for other things (like business and administration). And so on. Anyway, the UMD Javascript plotting libraries are pretty easy to use, sort of modeled on the Google Charts, lightweight, and downloadable so you don't need to access it over the internet.

What is usually the case in science is that we need histograms, and scatterplots, and this is what this package provides. No bar charts, pie charts, etc, just basic histograms and scatter plots (functions are next).

Version

You can get the version by doing the following in your javascript code:

	var version = umd_show_version();
	alert(version);

	var version = umd_show_version();
	console.log("Version ="+version);

Access and Usage

The code is available for download here. To use, you have to place something like the following inside your HTML code, preferably inside the <head> tag, like this:

<head>
o
o
o
<meta name="apple-mobile-web-app-capable" content="yes" />
<meta name="apple-mobile-web-app-status-bar-style" content="default" />
<script src="plots.js"></script>

...or wherever you want to store the plot script.

All plots, whether histograms or scatter plots, are drawn in an HTML5 canvas. So to use the utility, you have to following 1 basic rule: you have to instantiate a canvas in HTML before your javascript. For instance, the following might be what you would do:

<canvas id="mycan"></canvas>
<script src="myscript.js"></script>

The key thing here is that canvas id. Keep track of it, you will need it to instantiate the plot you want to make.

Inside your javascript, you need to first instantiate, then draw. For example, imagine you want to make a histogram from a 1-dimensional array of numbers representing the ages of a sample population. For example:

	var xdata = [];
	//
	// then fill the data somehow
	//

Inside your javascript, you instantiate a new histogram with the following arguments:

	var histo = new umd_histogram(canvas_id,title,nbins,low_first,upper_last);

Then you set up a bunch of options:

	var options = {
		opt1 : value1,
		opt2 : value2,
		opt3 : value3
	}

And then you make the plot using the following syntax:

	histo.plot(xdata,options);

Note that the options are just that - optional, if you don't include them then you get a default minimal set, so the command

	histo.plot(xdata);

is perfectly ok.

So to put it all together,you might do the following:

	//
	// make and array of ages, and fill it somehow
	//
	var xdata = [];
	//
	// "book" a histogram with the following arguments:
	//		canvas id
	//		histogram title
	//		number of bins
	//		low edge of 1st bin
	//		upper edge of last bin
	//
	// so here, "mycan" matches the canvas id in the <canvas> tag, followed by
	// the title, and the histogram will have 20 bins between 0 and 80
	//
	var h1 = new umd_histogram("mycan","Age Distribution Histogram",20,0,80);
	var hopt = {
		xtitle : "Age",
		ytitle : "Number"
	};
	h1.plot(xdata,hopt);

The utility will make the histogram and display it inside the canvas.

Summary

For histograms, instantiate via:

	var h1 = new umd_histo(canvas_id,histogram_title,number_bins,low_first,high_last);

and plot via

	h1.plot(data,<options>);

where <options> are optional, described below, and data is a 1-dimensional array of numbers you want to have histogrammed.

For scatter plots, instantiate via:

	var s1 = new umd_scatterplot(canvas_id,scatterplot_title);
	s1.plot(datax,datay,<options>);

where <options> are optional, described below, and datax and datay are the x-y pair data, each a 1-dimensional array, for the scatterplot.

Interactions

As described below in the options section on "active", you can interact with the plot in two ways get the actual data:

Click on the data point for scatter plot, or histogram box for histogram, and it will type out the value of the data in the div below
Each plot will have a title that you give it, and it will be displayed inside a white box just above and to the left of the plot. Click anywhere inside the white box and it will dump all of the data into the div your provide. Subsequent clicking will toggle the dump on/off.

Options

Option	Description	Example	Default
Options used by both histogram and scatterplots
active	Allows you to click to on histogram box to read out data points. Also there's a white box in the upper left corner, click to read out all data points.	active:true	active:false
active_div	HTML <div> element. You have to add this to your HTML after you give the canvas, e.g.
active_precision	Set the precision for rounding numbers placed in the active_div	5	active_precision: 3
active_exponential	Output the numbers placed into active_div in exponential form	active_exponential: true	active_exponential: false
debug	debugging, with output to the console	debug:true	debug:false
background	background color	"grey" or "#A5A5A5"	default
border	histogram border (drawn in black)	border:true	border:false
title	title string	title:"My Title"	default to instantiation value
title_font	title font	title_font:"14px arial"	title_font:"#12px Courier"
xtitle	horizontal axis title string	xtitle:"Age"	none
xtitle_position	"left", "center", "right" (case insensitive)	xtitle_position: "right"	xtitle_position: "center"
width	canvas width in pixels	width:500	width:400
height	canvas height in pixels	height:500	height:400
show_stats	shows stats on upper right side	show_state:true	show_state:true
xgrid	number of grid lines along x-axis	xgrid:5	xgrid:5
ygrid	number of grid lines along y-axis	ygrid:5	ygrid:6
ymax	vertical axis max for displaying	ymax:20	maximum bin content
Histogram only Options
normalize	normalize area under histogram	normalize:1	not enabled
hist_color	color of histogram rectange for displaying	hist_color:"yellow"	hist_color:"#4070d0"
r_fract	fraction of bin taken up by histogram rectangle	r_fract:1	r_fract:0.9
f_labels	1/fraction of all bins that have a label	f_label:4	f_label:5
Scatter Plot only Options
xmin	horizontal min value for displaying	xmin:1	minimum x value from array
xmax	horizontal max value for displaying	xmax:1	maximum x value from array
ymin	vertical min value for displaying	ymin:1	minimum y value from array
xtick_unit	unit for ticks and labels along x-axis	xtick_unit: 0.1	(xmin-xmax)/xgrid
xtick_unit_precision	number of decimal places to show for labels along x-axis	xtick_unit_precision: 5	xtick_unit_precision: 3
ytick_unit	unit for ticks and labels along y-axis	ytick_unit: 0.1	(ymin-ymax)/ygrid
point_radius	radius of circle used for points	point_radius:2	point_radius:3
point_color	color of circle used for points	point_color:"blue"	point_color:"#4070d0"
log	plot on log scale	log:true	log:false
plot_type	"points", "line", "both"	plot_type:"line"	plot_type:"points"

Overlay

Often, you might want to make a histogram and then overlay a plot of data on top of it. This is quite easy to do here.

For both histograms and scatter plots, after you invoke the .plot method, you can then invoke .overlay, and provide new data and options as arguments. For instance, to overlay a function on top of a histogram, you might do something like this:

	.
	.
	.
	var h = new umd_histogram("mydif","Title",nbins,xlow,xhigh);
	var hdata = [];
	var hopts = {
		opt1 : value,
		opt2 : value,
		.
		.
		.
	}
	h.plot(h,hopts);
	//
	// now add data on top
	//
	var ydata = [];
	for (var i=0; i<n; i++) ydata.push(...);		// this fills ydata
	var overlay_options = {
		o_opt1 : value,
		o_opt2 : value
		.
		.
		.
	}
	h.overlay(ydata,overlay_options);

What the code will do is take the ydata values, and assume a 1:1 correspondence with this histogram bins, and plot the data on top. Note that this is ok, because you've specified the number of bins, and the bin edges, so you should be able to figure out what bin number goes with what "ydata[i]" value. The code will overlay 1 point on top of each bin.

For scatter plots, it's much the same thing, only here you give it 2 arrays, x and y, and options, like this:

	.
	.
	.
	var x_overlay = [];
	var y_overlay = [];
	.
	// fill x_overlay and y_overlay
	.
	s.overlay(x_overlay,y_overlay,overlay_options);

For scatter plots, the x_overlay and y_overlay pair do not have to have the same array length or be related to the original scatter plot x/y pair. The code just overlays the plots.

Overlay options

For histogram or scatter plot overlays, you can plot a circle, a square, connect points with lines, or provide your own character to plot. The following options describe how to do this:

Option	Description	Example	Default
overlay_type	0=circle,1=box,2=line,3=custom	overlay_type:1	overlay_type:0
overlay_circle_radius	for type=0 (circle), radius of circle	overlay_circle_radius:3	overlay_circle_radius:1
overlay_circle_color	for type=0 (circle), color of circle	overlay_circle_color:"blue"	overlay_circle_color:"red"
overlay_box_fraction	for type=1 (rectangle) histograms, box width as fraction of bin	overlay_box_fraction:0.5	overlay_box_fraction:0.25
overlay_box_width	for type=1 (rectangle) scatter plots, box width in pixels	overlay_box_fraction:0.5	overlay_box_fraction:0.25
overlay_box_color	for type=1 (rectangle), color of box	overlay_box_color:"green"	overlay_box_color:"blue"
overlay_line_width	for type=2 (line), width of line	overlay_line_width:1	overlay_line_width:2
overlay_line_color	for type=2 (line), color of line	overlay_line_color:"yellow"	overlay_line_color:"blue"
overlay_character	for type=3 (custom), the character you want to display	overlay_character:"o"	overlay_character:"*"
overlay_character_color	for type=3 (custom), color of character to display	overlay_character_color:"blue"	overlay_character_color:"green"

Error Bars

(Scatter plots only as of May 9, 2017)

We often want to also see the error bars. Do to this, all you have to do is fill an array of values that contain the error bar, and call via:

	sc = new umd_scatterplot(....)
	var xdata = [];
	var ydata = [];
	.
	.
	sc.plot(xdata,ydata,...);

	var errors = [];
	.
	.
	.
	sc.errorbars(errors,options)

The array "errors" should be in phase with the array "xdata" and "ydata" as in the above example, so that the value at "xdata[i]" will be "ydata[i] +- errors[i]". This means that the error bars will be symmetric about the "ydata" value, and the value in "errors" causes a bar to be drawn with equal distance on both above and below the data point.

Error bar options

The only options at this time (5/8/17) are the errorbar width (width of the vertical error bar), the color, and the width of the horizontal top and bottom of the bar:

Option	Description	Example	Default
errorbar_width	Width of the vertical error bar	errorbar_width:2	errorbar_width:1
errorbar_color	color of the error bar	errorbar_color:"green"	errorbar_color:"black"
errorbar_barwidth	width of the horizontal upper and lower bars in pixels	errorbar_barwidth:0	errorbar_barwidth:5

Copywrite Drew Baden, May 8, 2017

Table of Contents

Introduction

Version

Access and Usage

Summary

Interactions

Interactions

Options

Options used by both histogram and scatterplots

Histogram only Options

Scatter Plot only Options

Overlay

Overlay options

Error Bars

Error bar options