UMD Javascript Plotting Utility, version 3.1

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? There are lots of reasons:

This library was written so as to be 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 (so far just scatterplots and histograms but functions are on the way). No bar charts, pie charts, etc, just basic histograms and scatter plots.


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/plots3.1.js"></script>
    
    where "location" is of course dependent on where you put the code.

  2. The only thing you have to put in your HTML is a div, with an ID:
    	<div id="mydiv"></div>
    
    Note that if you leave off the </div>, then HTML won't complain but the entire hierarchy of what's in that div will be messed up. So don't forget to close the div!!

  3. In your javascript, you create a new plot using:
    	let plot = new UMD_plot("mydiv");
    
    where "mydiv" is the id of the <div> that you put in step 2.

    All plots, whether histograms,scatter plots, or functions (or whatever is implemented) are drawn in an HTML5 canvas (<canvas>) and that is created in the constructor ("new..."). See below for details.


Version

Back to top
You can get the version from the object variable "version. So for instance, to type it out on the console, do something like this in your javascript code:
	let plot = new UMD_plot("mydiv");
	.
	.
	.
	console.log(plot.version);

Usage

Back to top
As of version 3.1, functions are not yet available, but scatterplots are, and the others will follow quickly.

To make a scatterplot, let's say you have some data you want to plot, here we will make an array called y and fill it with 100 random numbers.

	let y = [];
	for (var i=0; i<100; i++) x.push(Math.random());
If the <div> id is "divid", then we invoke a new UMD_plot object via:
	let plot = new UMD_plot("divid");
This will set up all the values and methods for plotting the function onto a canvas that will live inside the "divid" div. To plot, you do this:
	plot.plotit(options)
The variable options is a javascript object that you fill in, and it will contain things like the size of the plot in pixels, the data to plot, colors, fonts, etc. The table below will show you the available options, and the defaults.

The following lists the different ways available to show the plot

For each of these, you can specify the color, the "size" (width of line, radius of circle, or side of the box). How you do this is explained next: For example, let's say you have arrays x and y and you wanted to make a plot that connects the points with a blue line and puts open red circles of radius 3 pixels on the points, with a particular title, x-axis title, y-axis title, and make the canvas height 500 and width 600 pixels, you would have options like this:
	let plot = UMD_plot("mydiv");
	let yobj1 = {
	    data: y,
		type: "line",
		color: "blue",
		size:  0.5,
	};
	let yobj2 = {
	    data: y,
		type: "circle",
		color: "red",
		size:  3,
		fill: false
	};
	options = {
	 ydata: [yobj1,yobj2],
	 title: "this is the overall plot title",
	 xtitle: "this goes along the bottom horizontal",
	 ytitle: "this goes along the vertical to the left"
	 width: 500,
	 height: 600,
	};
	.
	.
	.
	plot.plotit(options);

Options

Back to top
Option Description Example Default
backgroundbackground color"grey" or "#A5A5A5" "white"
use_xlabelsboolean to control using x-labels (see below)truefalse
xlabelsarray of labels along x axis[0,2,4,6]n/a
titletitle string"My Title" blank
fontthis is the font used for everything"14px arial" "Courier"
font_sizesize of the font1412
font_colorcolor of all fonts"white" "black"
gridboolean to control displaying gridfalsetrue
grid_colorcolor of horizontal and vertical grid lines"black" "#d0d0d0"
xgridnumber of grid lines along x-axis45
ygridnumber of grid lines along y-axis56
widthcanvas width in pixels500400
heightcanvas height in pixels500400
xtitlehorizontal axis title string"Age"blank
ytitlevertical axis title string"Number"blank
xminhorizontal min value for displaying1 minimum x value from array
xmaxhorizontal max value for displaying1 maximum x value from array
yminvertical axis min for displaying0 maximum y value from array
ymaxvertical axis max for displaying20 minimum y value from array


Histograms

Back to top
To make a plot of a histogram, you first generate the data you want binned. You do the same constructor as before:
	let hist = UMD_plot("divid");
To make the histogram, you call the method histogram with options:
	hist.histogram(options);
The options argument is the same object that you use for scatterplot, with an additional argument that is used for histograms:
	options = {
		title : "your title",
		.
		.
		.
	    hist = {
			bins: "number of bins"
			data: "1-d array of points to bin"
			xlow: "low edge of low bin"
			xhigh: "high edge of high bin"
			color: "color of the histogram"
			fill: "boolean for fill (true) or stroke (false)" 
			stats: "boolean, true for display, false to not display"
		}
	}
Calling hist.histogram(options) will bin the histogram and pipe the arguments off to the scatterplot method for drawing.

Interactions

Back to top
Once you have called the plotit method to make the plot, a yellow button called "Control" will appear. Push it and you will see the following controls appear above the plot you've made:
On the first row you will see "Vertical scale:", and 6 buttons to push. These are all to change the vertical scale of the plot. "Auto" will find the maximum in the data and replot so that the yaxis has that value at the top, "Larger" and "Smaller" will change the scale by 10%, and "100", "10k", and "500k" are presets that might or might not be useful.

On the 2nd row, you will see text boxes to set the horizontal limits (min and max). To set these limits, type in the value and hit return. The plot is redrawn with that limit.

On the 3rd row, the "Label:" text box allows you to type in a label that you want to put on the plot, so you can label multiple plots, etc. The way you use this is to type in the label, then click on the plot somewhere, and the label is drawn there. If you don't like where the label is drawn, click on the label (on the plot) and it will disappear, then click somewhere else and it is redrawn. The "Show Data" is a button that if you click on it when it says "Enable", it enables you to mouse over the plot data and it will type out the x and y value. Once you enable this feather, the button will change to "Disable" and if you click on it again, this feature is disabled.


Testing

Back to top
If you want to see how to use plots3.1.js, just click on this
test3.html file, it will draw a gaussian with "lines", "circle", and "hist" and show you the code. Back to top
Last updated May 27, 2021 Drew Baden

All rights reserved. No part of this publication may be reproduced, distributed, or transmitted in any form or by any means, including photocopying, recording, or other electronic or mechanical methods, without the prior written permission of the publisher, except in the case of brief quotations embodied in critical reviews and certain other noncommercial uses permitted by copyright law.