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/plots2.3.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 |
The following shows what to do for each of the 3 objects (histograms, scatterplots, functions):
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);
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,options,dy);
function xfun(x) { return Math.sin(x)}
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 |
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 | 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" |
font_color | color of all fonts | font_color:"white" | font_color: "black" |
grid_color | color of horizontal and vertical grid lines | grid_color:"black" | grid_color: "white" |
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 |
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_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 |
xaxis_highlight | draw x-axis in black to highlight | xaxis_highlight:true | xaxis_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_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" |
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 |
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.
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" |
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 |
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 |