Introduction | Back to top |
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 |
var version = umd_show_version(); alert(version);or
var version = umd_show_version();
console.log("Version ="+version);
Access | Back to top |
<script src="/location/plots.js"></script>where "location" is of course dependent on where you put the code.
<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.
Usage | Back to top |
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).
function xfun(x) { return Math.sin(x)}
var histo = new umd_histogram(canvas_id,title,nbins,low_first,upper_last);
var histo = new umd_histogram("mycan","Higgs Mass",50,100,150);
will "book" a histogram of your data with the title "Higgs Mass", 50 bins between
100 and 150, and display it in the canvas with id="mycan".
var scplot = new umd_scatterplot(canvas_id,title);will "book" a scatterplot with the same arguments as above but of course no bin information
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)
histo.plot(x,options);
scplot.plot(x,y,options);
umd_function(canvas_id,title,function_name,options);
So to put it all together, the following javascript is what you might write to make a histogram of some data:
//
// make and array of ages, and fill it somehow
//
var xdata = [];
.
. fill the array...
.
//
// "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.
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 |
Options | Back to top |
| 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 |
| 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 |
| ymin | vertical axis min for displaying | ymin:0 | minimum bin content |
| 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 |
| ytick_unit_precision | number of decimal places to show for labels along y-axis | ytick_unit_precision: 5 | ytick_unit_precision: 3 |
| 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" |
| log | plot on log scale | log:true | log:false |
| plot_type | "points", "line", "both" | plot_type:"line" | plot_type:"points" |
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 |
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.
| 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 | Back to top |
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.
| 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 |