UMD Javascript Plotting Utility, version 2.3

Table of Contents

(End of Page)

Introduction

Back to top
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, scatter plots, and functions (more or less) 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, scatterplots, and functions, and this is what this package provides. No bar charts, pie charts, etc, just basic histograms and scatter plots (functions are made from scatterplot functions).


Version

Back to top
You can get the version by doing the following in your javascript code:
	var version = umd_show_version();
	alert(version);
or
	var version = umd_show_version();
	console.log("Version ="+version);

Access

Back to top
The code is available for download
here. There are 3 parts to using this code:
  1. In your html, preferably inside the <head> tag, include the following javascript source:
    	<script src="/location/plots2.3.js"></script>
    
    where "location" is of course dependent on where you put the code.
  2. All plots, whether histograms,scatter plots, or functions (or whatever is implemented) are drawn in an HTML5 canvas (<canvas>). The code also will use an HTML div element (<div>) to allow you to do things like click on a histogram bin and get the bin value and contents, etc (see below). So, also inside your html, you need to create a canvas and div tag, each with an id. For example:
    <canvas id="mycan"></canvas>
    <div id="mydiv"></div>
    
    The key thing here is the canvas id and div id string. Keep track of it, you will need it to instantiate the plot you want to make.
  3. Instantiate a histogram, scatter plot, or function inside your javascript source, and refer to the canvas and div id string explicitly (in the above example, "mycan" and "mydiv"). See below for details.

Usage

Back to top
Ok, so down to basics: the first step in making plots is of course to come up with the data, and you do this in your javascript code. That data will be input to a set of functions for making histograms and scatterplots. You can also input a function and have it drawn (see below).

The following shows what to do for each of the 3 objects (histograms, scatterplots, functions):

Options are an important part of this utility. The list of options is described in tables
below. They are invoked using the Javascript variable type called "literal", with the following example:
	var options = {
		opt1 : value1,
		opt2 : value2,
		opt3 : value3
	}
Options are a key part of making something presentable and doing what you want it to do (like set the horizontal or vertical limits, etc)

Functions are even easier, since you don't have to provide any data. The code uses the limits xlow and xhigh as set in the options (see below) and draws a default of 100 points, connecting them with lines (you can change the number of points, see below).

	var fopt = {
		xtitle : "x",
		ytitle : "x*exp(x)"
	};
	umd_function("mycan","Function plot",myfun,fopt);
	.
	.
	.
	//
	function myfun(x) {
		return x*Math.exp(x);
	}
If you want to draw 2 functions (same horizontal coordinates), then

Interactions

Back to top

Interactions

As described below in the options section on "active", you can interact with the plot in several ways:
  1. 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 ("active_div" see below)
  2. 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.
  3. Click and drag inside the plot. Click down selects a (x,y) coordinate, and release up selects another (x,y) coordinate. When you click up, it will then expand the plot inside the limits of your selection. Note that the code does NOT show you the coordinates when you click or release. Once the new plot is drawn, a box in the upper left that has the title "Back" can be clicked to get the previous plot back.

Options

Back to top
Option Description Example Default

Options used by both histogram and scatterplots

active_div Set to the HTML <div> element. This 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_div: "id" active_div:null
active_precision Set the precision for rounding numbers placed in the active_div 5active_precision: 3
active_exponential Output the numbers placed into active_div in exponential form active_exponential: true active_exponential: false
debugdebugging, with output to the consoledebug:true debug:false
backgroundbackground color"grey" or "#A5A5A5" default
titletitle stringtitle:"My Title" default to instantiation value
title_fontthis is the font used for all titles (main, x, y)title_font:"14px arial" title_font:"#12px Courier"
font_colorcolor of all fontsfont_color:"white" font_color: "black"
grid_colorcolor of horizontal and vertical grid linesgrid_color:"black" grid_color: "white"
xtitlehorizontal axis title stringxtitle:"Age" none
xtitle_position"left", "center", "right" (case insensitive) xtitle_position: "right" xtitle_position: "center"
widthcanvas width in pixelswidth:500 width:400
heightcanvas height in pixelsheight:500 height:400
show_statsshows stats on upper right sideshow_state:true show_state:true
gridturn grid on/off grid:false grid:true
xgridnumber of grid lines along x-axisxgrid:5 xgrid:5
ygridnumber of grid lines along y-axisygrid:5 ygrid:6
xminhorizontal min value for displayingxmin:1 minimum x value from array
xmaxhorizontal max value for displayingxmax:1 maximum x value from array
yminvertical axis min for displayingymin:0 minimum bin content
ymaxvertical axis max for displayingymax: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

xtick_unitunit for ticks and labels along x-axis xtick_unit: 0.1(xmin-xmax)/xgrid
xtick_unit_precisionnumber of decimal places to show for labels along x-axis xtick_unit_precision: 5xtick_unit_precision: 3
ytick_unitunit for ticks and labels along y-axis ytick_unit: 0.1(ymin-ymax)/ygrid
ytick_unit_precisionnumber of decimal places to show for labels along y-axis ytick_unit_precision: 5ytick_unit_precision: 3
logplot on log scale log:truelog:false
xaxis_highlightdraw x-axis in black to highlight xaxis_highlight:truexaxis_highlight:false
plot_type"points", "line", "both" (applied to previous 2), "bar" (not for log scale, and uses same color as line_color) plot_type:"line"plot_type:"points"
point_radiusradius of circle used for points point_radius:2point_radius:3
point_colorcolor of circle used for points point_color:"blue"point_color:"#4070d0"
line_colorcolor of line for plot_type="line" line_color:"blue"line_color:"black"
bar_type"open" or "closed" bars for plot_type="bar" bar_type:"closed"bar_type:"open"
overlayN see below. this is how you give multiple x/y pairs to overlay
xlabels this is an array for the labels. only input nonblanks [1,"","","","",5,""]
labelN labels a point on the scatterplot. "N" is a unique identifier label1: ["HI",500,500]

Function only Options

xlow low value of x xlow:0 min x returned by the function
xhigh high value of x xhigh:10 max x returned by the function
numpoints number of different x values to plot numpoints:200 numpoints:100

Two-Function only Options

xlow1 low value of x of 1st function xlow1:0 required
xhigh1 high value of x of 1st function xhigh1:10 required
xlow2 low value of x of 2nd function xlow1:0 =xlow1
xhigh2 high value of x of 2nd function xhigh2:10 =xhigh2
numpoints number of different x values to plot numpoints:200 numpoints:100


Overlay

Back to top
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 for a histogram, but it is different for histograms than for scatterplots.

For histograms, overlays are specified in the options object that you pass (see below). You have to provide the data, and turn the overlay option overlay option to true.

Histogram Overlay options

For histogram, 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:
OptionDescriptionExample Default
overlaylogical to turn overlays on or off (true or false) overlay:true overlay:false
overlay_type"CIRCLE","BOX","LINE","CHAR","FUNCTION" overlay_type:0 overlay_type:1
overlay_dataarray w/same number of points for scatterplots, bins for histos overlay_data: array overlay_data: null
overlay_circle_radiusfor type=CIRCLE, radius of circle overlay_circle_radius:3 overlay_circle_radius:2
overlay_circle_colorfor type=CIRCLE, color of circle overlay_circle_color:"blue" overlay_circle_color:"red"
overlay_box_fractionfor type=BOX for histograms, box width as fraction of bin overlay_box_fraction:0.5 overlay_box_fraction:0.25
overlay_box_widthfor type=BOX for scatter plots, box width in pixels overlay_box_fraction:0.5 overlay_box_fraction:0.25
overlay_box_colorfor type=BOX, color of box overlay_box_color:"green" overlay_box_color:"blue"
overlay_line_widthfor type=LINE, width of line overlay_line_width:2 overlay_line_width:1
overlay_line_colorfor type=LINE, color of line overlay_line_color:"yellow" overlay_line_color:"blue"
overlay_characterfor type=CHAR, the character you want to display overlay_character:"o" overlay_character:"*"
overlay_character_colorfor type=CHAR, color of character to display overlay_character_color:"blue" overlay_character_color:"green"
overlay_functionfor type=FUNCTION, pointer to function to display overlay_function:myfunction overlay_function: null
overlay_function_colorfor type=FUNCTION, color of function to display overlay_function_color:"blue" overlay_function_color:"green"

Scatterplot Overlay options

For scatterplots, the overlay option is how you provide any number of x/y pairs, and instructions on how to display it. This makes it easy to put as many plots or functions onto the same scatterplot as you like. You can plot a circle, a square, open or close, or a line that connect points, or provide your own character to plot.

To specify what to draw, you use the "overlayN" option where "N" is an integer and is used to differential one set of x,y from another. You don't have to worry about what "N" is, it's just a character to distinguish one overlay from another. The value for the "overlayN" option is an array that has the following form:

overlay0 : [y-values, type, color, size/char, scale]

Note that the first function you specify will be used for the limits.

So for example, say you have x1,y1 and you want to plot it as a blue line of width 1, and x2,y2 and you want to plot it as red open circles of radius 3, and x3,y3 and you want to plot it using a green "$" character, and then plot the line in red with width 1 and scaled by 0.5, you would use this syntax in the options:

overlay1 : [y1,"line","blue",1],
overlay2 : [y2,"ocircle","red",3],
overlay3 : [y3,"char","green","$"],
overlay3 : [y1,"line","red",1,0.5],
Note that if you leave out color and size, it will go to defaults (all "blue", with radius 3 for circles, 1 for line, and 4 for boxes, plus, cross, ast).


Error Bars

Back to top
(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:
OptionDescriptionExample Default
errorbar_widthWidth of the vertical error barerrorbar_width:2 errorbar_width:1
errorbar_colorcolor of the error bar errorbar_color:"green" errorbar_color:"black"
errorbar_barwidthwidth of the horizontal upper and lower bars in pixels errorbar_barwidth:0 errorbar_barwidth:5
Back to top
Copywrite Drew Baden, June 21, 2017