UMD Javascript Plotting Utility, version 2.1
Table of Contents
(End of Page)
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).
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);
The code is available for download
here.
There are 3 parts to using this code:
- In your html, preferably inside the <head> tag, include the following
javascript source:
<script src="/location/plots2.js"></script>
where "location" is of course dependent on where you put the code.
- 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.
- 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.
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):
- Histograms: make a 1-d array with data points, for example:
var x = [];
for (var i=0; i<100; i++) x.push(Math.random());
This creates a 100 long array of random variables distributed evenly between 0 and 1
(this is what Math.random() gives you). That's all you need. In making the histograms,
you will explictly give the bin information (just like the old HBOOK).
To make a histogram from this data you call umd_histogram in the following way:
umd_histogram(canvas_id,title,nbins,low_first,upper_last,data,options);
- canvas_id is the same string that is used for the id of the canvas
("mycan" as above, including the double quotes)
- title is the title string for the histogram
- nbins, low_first, upper_last are for the histogram binning
- data is the data that you want histogrammed (1-d)
- options are the options (which are optional)
- Scatterplots: make a scatter of some x,y pairs of data, for example let's make a
scatterplot of a sine wave:
var x = [];
var y = [];
for (var i=0; i<100; i++) {
x.push(i);
y.push(Math.sin(x));
}
This creates 2 arrays of length 100, where y is a function of x. Then you
make the scatterplot by calling umd_scatterplot in the following way:
umd_scatterplot(canvas_id,title,x,y,options,dy);
- canvas_id is the same string that is used for the id of the canvas
("mycan" as above, including the double quotes)
- title is the title string for the scatterplot
- x,y are for data pairs
- options are the options (which are NOT optional for scatterplots!)
- dy is the optional errors on y
- Functions: plot any desired function that is a function of
a single variable. (TBC)
function xfun(x) { return Math.sin(x)}
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
As described below in the options section on "active", you can interact with the plot in several ways:
- 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)
- 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.
- 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.
Option |
Description |
Example |
Default |
|
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 |
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 |
title | title string | title:"My Title" |
default to instantiation value |
title_font | this is the font used for all titles (main, x, y) | 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 |
grid | turn grid on/off | grid:false |
grid: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 |
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 axis min for displaying | ymin:0 |
minimum bin content |
ymax | vertical axis max for displaying | ymax:20 |
maximum bin content |
|
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 |
|
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 |
ytick_unit_precision | number of decimal places to show for labels along y-axis |
ytick_unit_precision: 5 | ytick_unit_precision: 3 |
log | plot on log scale |
log:true | log: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_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" |
line_color | color 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" |
|
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 |
|
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 |
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, 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.
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 | logical 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_data | array w/same number of points for scatterplots, bins for histos |
overlay_data: array |
overlay_data: null |
overlay_circle_radius | for type=CIRCLE, radius of circle |
overlay_circle_radius:3 |
overlay_circle_radius:2 |
overlay_circle_color | for type=CIRCLE, color of circle |
overlay_circle_color:"blue" |
overlay_circle_color:"red" |
overlay_box_fraction | for type=BOX for histograms, box width as fraction of bin |
overlay_box_fraction:0.5 |
overlay_box_fraction:0.25 |
overlay_box_width | for type=BOX for scatter plots, box width in pixels |
overlay_box_fraction:0.5 |
overlay_box_fraction:0.25 |
overlay_box_color | for type=BOX, color of box |
overlay_box_color:"green" |
overlay_box_color:"blue" |
overlay_line_width | for type=LINE, width of line |
overlay_line_width:2 |
overlay_line_width:1 |
overlay_line_color | for type=LINE, color of line |
overlay_line_color:"yellow" |
overlay_line_color:"blue" |
overlay_character | for type=CHAR, the character you want to display |
overlay_character:"o" |
overlay_character:"*" |
overlay_character_color | for type=CHAR, color of character to display |
overlay_character_color:"blue" |
overlay_character_color:"green" |
overlay_function | for type=FUNCTION, pointer to function to display |
overlay_function:myfunction |
overlay_function: null |
overlay_function_color | for type=FUNCTION, color of function to display |
overlay_function_color:"blue" |
overlay_function_color:"green" |
(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 |
Back to top
Copywrite Drew Baden, June 21, 2017