Downloadable Software

Plod

A graphing package

Pregnant Pause Home Software Search this site


Download You may have to shift-click or right-click to be able to save it to your local drive.

But we recommend you read the instructions ...

This page was updated for Plod version 4.3.

Capsule description

Plod is a Javascript object that draws graphs. It is intended to be used to include graphs in Web pages. It draws line graphs, bar charts, and pie charts. It can produce line and bar charts with multiple "series" and can distinguish the series with different colors.

License

This software is free. But as a non-profit organization, we would appreciate a donation!

Software and documentation (this page) Copyright 2017 by Pregnant Pause.

In the following, the word "product" refers to both the software and the documentation, that is, both the plod.js file and this text file, jointly or separately.

Why we wrote Plod

I have written a number of Web pages that include statistics which are more easily understood if displayed as a graph. Originally I would use a desktop graphing program to draw these, export the results to a GIF file, and include this on the Web page. But this had several problems: The quality of these graphs was poor. The GIF files were often large, taking far more time to download than the entire text of the article. There was no easy way to adjust their size: they had to be small enough to be viewable on a low resolution screen, but then on screens with higher resolutions they looked way too small.

I wrote Plod to resolve these problems. Instead of downloading an image of the completed graph, we only download the data numbers and some control information. Plod than draws the graph on the user's screen on the fly. This gives much cleaner looking graphs, the graphs can be sized to fit the user's screen, and the download time is usually less than for a graphic image. (The data is now smaller. The Javascript does have to get downloaded. But the Javascript file is pretty small -- 14k.)

I suppose the major drawback to Plod versus the exporting-a-GIF plan is that Plod does not have all the fancy features that you might find in a desktop graphing program. We were trying to keep the program small, so we didn't want to add a lot of grandiose features.

Installation

That's it!

Using Plod

Note: These instructions assume you have a basic familiarity with HTML. It is helpful if you know something about Javascript and JSON, but I think these instructions will take you through the basics. If you need help on HTML or Javascript in general, there are plenty of sources on the Web, we don't need to repeat it here. See, for example, W3 Schools

The Basics

There are three things you have to do to include a Plod graph on a web page:

  1. Add a <script> tag to include the plod.js Javascript file.
  2. Add a <canvas> tag at the place on the page where you want to display the graph. The canvas tag must have an ID, a width, and a height. It determines where on your page the graph appears, and its size.
  3. Include Javascript to call plod.js, giving it parameters that control the type of plot and the data. This is, of course, the key part.

The Script Tag

This tells the browser where to find the Plod program. Basically, just put this:

<script type="text/javascript" src="/js/plod.js"></script>

The "src" attribute must match the path where you saved plod.js. The rest should be exactly as shown.

Normally you put the <script> tag inside your <head> tag.

The Canvas Tag

The canvas tag determines the size and placement of the graph. A basic canvas tag looks like this:

<canvas id="plod1" width="600" height="300"></canvas>

The ID can be whatever you want: I just used "plod1" here as an example. If you have multiple graphs on the same page, they must all have different IDs.

The width and height can be whatever you want. Unfortunately, you must set the height and width like this on the canvas tag. You can use CSS height and width and max-height and max-width, but this is applied after the graph is drawn with the canvas height/width. This means that the font sizes and line thicknesses are drawn using the canvas size, and then stretched or shrunk to the CSS style. Still, I routinely set max-width and max-height to percentages. This can be used to insure that the graph fits on the user's screen. For example:

<canvas id="plod1" width="600" height="300" style="max-width: 70%; max-height: 50%;"></canvas>

Because of the shrinking of font sizes, it isn't practical to set the width and height to something outrageous, like 20000, and then use the CSS to shrink it. You want the canvas size to at least be in the ballpark.

Running Plod

Somewhere on your page, include the Javascript to run Plod. The easiest way to do this is to call the Plod.run function. You pass parameters to Plod.run as a JSON object. If you don't know anything about JSON, don't panic, we'll give you instructions and examples that should show all you need to know for Plod.

The Plod.run command is connected to a canvas by the canvas ID. So the Javascript can go anywhere. I always put it directly under the canvas tag, but if you have some reason for wanting to put it elsewhere, feel free. I always embed the Javascript in the web page, but you could put it in a separate file, just like any other Javascript. The Javascript cannot run until after the canvas tag is defined, so if you write the Javascript like I do in my examples -- to fire once the script tag is hit -- then the script must come after the canvas. If you run it inside a Jquery ready function or a body onload event, this doesn't apply. If you don't know what I'm takling about, just do it like in the examples.

The simplest kind of graph is a line graph. You give the labels for the x axis, and numeric values for the y axis. Here's a simple example:

<canvas id="plod1" width="600" height="300"></canvas>
<script>
Plod.run({canvas:"plod1",x:[1,2,3,4,5],y:[0,2,6,12,20]})
</script>

The parameters to Plod are given as a JSON object. That means that they are enclosed in braces ({}), and you give them as parameter name, colon, value; with parameters separated by commas. Strings must be enclosed in quotes. Some parameters are arrays: these must be enclosed in square brackets ([]). Note that you must put parentheses and braces.

We connect the Plod.run to a canvas with the "canvas" parameter. This gives the ID of the canvas that we want to draw on. Each graph should have its own canvas. Trying to draw two graphs on the same canvas generally results in an ugly mess.

"x" gives the labels to write on the x axis, and "y" gives numeric values for the y axis. Note that y values MUST be numbers. x values can be numbers or text. Making x values text gives you flexibility: you could put [1,2,3,4,5], or you could put ["Monday","Tuesday","Wednesday","Thursday","Friday"], or whatever makes sense for this graph. x values will be evenly spaced along the x axis. Note that they are NOT necessarily spaced proportionally to numeric value. If you give [1,2,10] your graph will space these three values evenly; 10 will not be placed 10 units down. That is, Plod does not do XY plots, it does line graphs with labels on the X axis. (I hope to add XY plots in the future but we haven't gotten there yet.) If you want the equivalent of an XY plot, you have to space the x values evenly, like [1,2,3,4,5,6,7,8,9,10], or [2,4,6,8,10].

You can omit x values by putting two or more commas in a row. The omitted values will not be displayed, but space will still be allocated for them. Basically this allows you to unclutter your x axis. For example, if you had data for every year from 1970 to 2000, there may not be room to display 30 four-digit years on the screen, but there's plenty of room to draw a line connecting 50 data points. So you could give x as x:[1970,,,,1975,,,,1980,,,,1985,,,,1990,,,,1995,,,,2000].

It may be tedious counting all the commas, so if you give fewer x values than y values, Plod looks at the last two x values and assumes that the "pattern" continues. That is, it looks at the difference between the last two values and counts the number of commas between them. So for example, if you gave x:[1970,,,,1975] and then gave more than 6 y values, Plod assumes that the pattern is number, 4 commas, number plus 5, 4 commas, number plus 10, etc. Thus, if your numbers increase linearly, you only need to give the first two values, with an appropriate number of commas between them.

Note: If x labels would overlap, Plod suppresses display of some labels to prevent this. But I wouldn't rely on this, because it's hard to predict which labels will be suppressed. If you see that labels are being suppressed but it's not suppressing the ones you want, go back and blank out some of your labels.

y values are straightforward: each y value is the height above the x-axis (or below, if negative). y values must be numbers. You can skip y values just like you can skip x values. For example, suppose you have data for years 1995 to 2000, but for some reason you're missing 1997. If you just leave out 1997, the graph will be distorted. So you can give an x value for 1997 but skip the y value. For example, x:[1995,1996,1997,1998,1999,2000], y:[102,104,,103,107]. (Note that as the x values increase uniformly, you could abbreviate this to x:[1995,1996].) When Plod draws the graph, it will interpolate the missing value. Plod uses a simple linear interpolation: if there is one value missing, it assigns a value exactly half way between the preceding value and the following value. If there are two values in a row missing, it assigns the first one to 1/3 the difference and the second to 2/3 the difference, etc.

XY vs X and Y

If you prefer, instead of giving all the x's and then all the y's, you can give the points as ordered pairs. In this case, instead of declaring x and y, declare one variable, xy. Then give an array of ordered pairs. Enclose the ordered pairs in square brackets rather than parentheses, because this is Javascript. This makes a 2-dimensional Javascript array. In the above example, instead of saying x:[1,2,3,4,5] and y:[0,2,6,12,20], you could give:

<canvas id="plod1" width="600" height="300"></canvas>
<script>
Plod.run({canvas:"plod1",xy:[[1,0],[2,2],[3,6],[4,12],[5,20]]})
</script>

This gives identical results. It's just a matter of what you prefer.

So that's a simple line graph.

Multiple Series

You can have multiple lines on the same graph. To do this, you give the y values as a 2-dimensional array, like this:

<canvas id="plod2" width="600" height="300"></canvas>
<script>
Plod.run({canvas:"plod2",x:[1,2,3,4,5],
  y:[[0,2,6,12,20],[2,4,6,8,10]]})
</script>

That is, the y values for each line are given as a series of numbers in brackets, and then all the series are also enclosed in brackets. You can give any numbers of series, and each series will be used to draw one line. (There is no limit on number of series in the program, though if you go crazy and try to have a million series you'll eventually run out of memory.).

You do not necessarily have to have the same number of values in every y series. If one series is shorter than another, its line will simply end sooner. If you want one series to begin later than another, put some empty values at the beginning. For example, x:[1,2,3,4], y:[[2,4,6],[,3,6,9]]. The first series has values for x = 1, 2, and 3. The second series has values for x = 2, 3, and 4. The first series ends sooner and the second series starts later.

If you have multiple series, you probably want to make the lines different colors so you can tell them apart. For this we use the "color" parameter. Give an array of colors. You can give colors using HTML color names like "red" and "blue", or using RGB values like "#ff0000" or "#099". If you're not familiar with HTML colors, see w3schools. Each entry in the array corresponds to the matching series of y values. That is, if you have 3 series, you should give 3 colors, and the first color will be for series 1, the second for series 2, and the third for series 3. For example: color:["#f00","blue"] would make the first series red and the second series blue.

You can use color if you have only one series. Just give an array with only one value, or just give the value. e.g. color:"#f00".

You probably also want to display a legend that explains what each line is. For this you use the "legend" parameter. This is an array of strings to describe each series. Again, the legends are matched to the series in order: first legend is for the first series, second legend is for the second series, etc.

So for a more realistic example:

<canvas id="plod3" width="600" height="300"></canvas>
<script>
Plod.run({canvas:"plod3",x:["Monday","Tuesday","Wednesday","Thursday","Friday"],
  y:[[0.2,0.4,0.6,0.8,1.0],[0,0.2,-0.6,1.2,2.0]],
  color:["#f00","lightblue"],
  legend:["Estimated","Actual"]})
</script>

To use multiple series with the xy parameter, you can put multiple y-values. Instead of an ordered pair, you give an ordered triple, etc. For example, you could get the same results as the above with:

<canvas id="plod3" width="600" height="300"></canvas>
<script>
Plod.run({canvas:"plod3",
  xy:[["Monday",0.2,0],["Tuesday",0.4,0.2],["Wednesday",0.6,-0.6],["Thursday",0.8,1.2],["Friday",1.0,2.0]],
  color:["#f00","lightblue"],
  legend:["Estimated","Actual"]})
</script>

Oh, by the way, note that you can give parameters in any order, and you can string them all together on one line or break them across multiple lines. (This isn't something about Plod, this is just Javascript syntax.)

Title

You probably want to include a title or some other caption on your graph so your readers know what it's supposed to show. You can do this by simply including the text in your HTML. We saw no need to include any feature to display titles within Plod, as HTML already does this just fine.

CSS Styling

You can use CSS to apply other styles to the canvas.

"margin" works like you'd expect. You can use margin:auto to center the canvas. For this to work you must also say display:block.

I routinely apply a style like "display: block; max-width: 70%; max-height: 50%; margin: 12px auto;" This gives a little space above and below the graph, centers it, and assures that it fits on the screen.

You can use "background-color" to change the background color and "border" to apply a border. If you do this, you probably want to add some padding, because without padding Plod will draw to the very edges of the canvas.

Personally, I like the look when the graph has the same background color as the page as a whole. It gives a nice "integrated" look. But if you prefer to make it stand out, you could use a style like "background-color: #fff; padding: 20px; border:2px solid black;" Where the background-color is something other than the page background-color. Then you'd get a little padding around the graph, a border, and a different background color. You could combine these styles with centering and sizing like I mentioned above.

I'm not sure what other CSS styling, if any, would be useful.

Note that you apply CSS styling to the canvas -- either with a class or in-line styling -- and not as parameters to Plod.

<canvas id="plod3b" width="600" height="300" style="padding: 20px; border: 3px solid black; background-color: #eee"></canvas>
<script>
Plod.run({canvas:"plod3",x:["Monday","Tuesday","Wednesday","Thursday","Friday"],
  y:[[0.2,0.4,0.6,0.8,1.0],[0,0.2,-0.6,1.2,2.0]],
  color:["#f00","lightblue"],
  legend:["Estimated","Actual"]})
</script>

Oh, by the way, note that you can give parameters in any order, and you can string them all together on one line or break them across multiple lines.

Bar charts

To draw a bar chart, add the parameter plot:"bar". This changes Plod's interpretation of some things. If you have one series, you get a bar for each number, with the label displayed below it, pretty much like a line graph except with bars. (Duh.) If you have multiple series, then you get a separate set of bars for each series. The bars are ordered by x value, and within x value by series. As with line graphs, you can specify a color for each series. For example:

<canvas id="plod4" width="600" height="300"></canvas>
<script>
Plod.run({canvas:"plod4", plot:"bar",
  x:["New York","Chicago","Miami","Dallas","Denver"],
  y:[[10,15,9,4,1],[20,3,7,18,12]],
  color:["#00f","#f66"],
  legend:["Men","Women"]})
</script>

If you leave out values on a bar chart, Plod omits the bar for that label. If there is only one series, this is probably not particularly useful. If there are multiple series, than one bar will be missing from that set for that x label. This could make sense if you don't have data for that value.

Scatter Plots

To draw a scatter plot, say plot:"scatter". For scatter plots, Plod lays out x and y axes and then plots each point as a circle. For scatter plots, x values must be numbers. Each point is drawn as a circle. There is a new parameter, "radius", to specify the radius of this circle.

We expect that normally you will use the same color and radius for all points, so you just specify one of each. If you prefer, you can give a different radius and/or color for each point, by specifying multiple values within brackets as usual.

As for lines and bar charts, x and y values can be specified separately, or together with xy. If you have different radiuses and color, you can use xyr. Give an array of points, and for each point give an array that consists of x, y, radius, and color. For example, xyr:[[1,2,2,"#f00"],[3,4,3,"#0f0"]]. This gives two points for the scatter plot: one at (1,2) with radius 2 and color #f00 (red), and the other at (3,4) with radius 3 and color #0f0 (green). If you give a point with no radius and/or color, the values from the last point specified are used.

Plod can calculate the least-squares straight-line approximation to your points. Specify "trend" followed by a color, like trend:"blue".

"trend" can also be used with line graphs. If you have multiple series, the trend line is calculated for the first series only.

Example:

<canvas id="scatter1" width="600" height="300"></canvas>
<script>
Plod.run({canvas:"scatter1", plot:"scatter", trend:"#8f8",
  xyr:[[3,7,2,"#900"],[5,12],[6,9],[10,8,4],[7,7],[1,3,2,"#090"],[2,4],[4,6,,"#009"]]
})
</script>

Log Scales

Normally, both x and y scales are linear. To make a log scale, say logx:"yes" or logy:"yes". (Actually any value other than null means "yes".) For scatter plots, you can put a log scale on either or both axes. For line and bar charts, only y can have a log scale.

If you specify a step, the step is a multiplier rather than an addition. That is, for a normal linear scale, xmin:10,step:5 gives x axis labels of 10, 15, 20, etc. For a log scale, this would give x axis labels of 10, 50, 250, etc.

We should put an example here.

Pie Charts

To make a pie chart, specify plot:"pie". You can only have one series for a pie chart. Each value in that series is a slice of the pie. Plod totals all the values and then gives each an appropriate percentage of the pie. x values are used to label the slices. Legends are not used. Colors are used to determine the color of the slices.

<canvas id="plod5" width="600" height="300"></canvas>
<script>
Plod.run({canvas:"plod5", plot:"pie",
  x:["Chocolate","Vanilla","Strawberry","Mint","Other"],
  y:[35,25,15,5,10],
  color:["#bb5","#ffb","#f66","#8f8","#ccc"]})
</script>

Leaving out x or y values on a pie chart is pretty meaningless. If you leave out a y value, you don't get a slice for that value. If you leave out an x value, then a slice will have a blank label.

If you give more x/y values than colors, Plod will "recycle" the colors, starting with the first one. For example, if you gave 3 colors but 6 y-values, Plod will use color 1, color 2, color 3, then color 1 again, color 2 again, color 3 again. Note that Plod draws black lines between the slices of the pie, so you could draw a one-color pie chart, just using the lines to distinguish the pieces. Not as pretty though.

Scale

This feature is not needed very often, but it's here if you want it.

You may have noticed that Plod automatically decides what the top and bottom values for the y-axis should be, and writes some numbers down the side at (usually) convenient intervals, like "10", "20", "30", "40", "50".

By default, the y-axis starts at zero and goes to the highest number found in your data, rounded up. If you include any negative numbers in your data, than the scale starts at the smallest (that is, most negative) number.

Plod attempts to write five numbers along the side of the scale, and to make the difference between each step have only one significant digit. For example, if your data ranges from 20 to 112, Plod knows that it's going to make the y-axis start at 0, so five steps from 0 to 112 makes 22 and a fraction per step, which it rounds up to 30, and so the scale is 30, 60, 90, 120.

You can alter the smallest value shown with ymin and the largest with ymax. If your data goes below ymin or above ymax, Plod overrules your entry. Mostly this can be used if you don't want to start at zero: give the desired starting value with ymin.

Say ymin:null to start the graph at the smallest value found in your data.

Use ystep to change the difference between values on the y axis. If Plod's "one significant digit" rule gives too few or too many values, you can override it. Or Plod might calculate steps of 4, 8, 12, 16 and you think it would be "neater" if it was 5, 10, 15, 20. Etc. The ystep cannot have more than two significant digits for internal technical reasons that we should fix some day.

Complete List of Parameters

Parameter Meaning Data Type Possible values, default Example
canvas id of canvas tag string canvas:"mygraph"
plot type of chart string "line" (default), "bar", "pie", "scatter" plot:"bar"
x values for labels on x axis array of strings and/or numbers x:[1990,,1992,,1994]
y y values 1 or 2 dimensional array of numbers y:[1,2,3,4,5]
y:[[1,2,3,4,5],[2,4,6,8,10]]
xy x, y value pairs (or more) 2 dimensional array of strings and/or numbers xy:[["West",2,1],["East",2,4],["North",3,9],["South",4,16]]
color color of lines, bars, or pie slices string or array of strings Javascript color name or RGB value color:"red"
color:["#f00","green","#f3928c"]
legend text to describe line or bar array of strings legend:["Dogs","Cats"]
fontSize size of font used for axis labels and legend, in pixels number default is 12 fontSize:14
fontFace font for axis labels and legend string installed fonts, default is Arial fontFace:"Helvetica"
ymin smallest value to plot on y-axis number default is 0 ymin:100
ymax largest value to plot on y-axis number default is highest value in data ymax:500
ystep step between values displayed on y-axis number default is 1/5 of difference between max and min rounded up ystep:0.50
xmin smallest value to plot on x-axis number default is 0, only applies to scatter plots xmin:100
xmax largest value to plot on x-axis number default is highest value in data, only applies to scatter plots xmax:500
xstep step between values displayed on y-axis number default is 1/5 of difference between max and min rounded up, only applies to scatter plots xstep:0.50
lineWidth width of line for axes and line graph lines, in pixels number default is 2 lineWidth:3
radius radius of scatter plot points, in pixels number or array of numbers default is 3 radius:3
radius:[2,3,1,4,7]
gridX style for x-axis grid string "tick" (default), "line", "no" gridX:"line"
gridY style for y-axis grid string "tick" (default), "line", "no" gridY:"no"
trend color of least-squares line string default is no trend line trend:"#099"
logx if not null, x scale is logarithmic string or number only applies to scatter plots logx:"y"
logy if not null, y scale is logarithmic string or number only applies to line and scatter plots logy:"y"

Alternate Way to Give Parameters

If you prefer, you can create a Plod object and set the parameters on this object. Then call "paint(canvasid)" to tell Plod that you've supplied all the data and it can now draw the graph.

<canvas id="plod6" width="600" height="300"></canvas>
<script>
var myplod=new Plod()
myplod.plot="pie"
myplod.x=["Chocolate","Vanilla","Strawberry","Mint","Other"]
myplod.y=[35,25,15,5,10]
myplod.color=["#bb5","#ffb","#f66","#8f8","#ccc"]
myplod.paint("plod6")
</script>

The attribute names are all the same as they are with the JSON object, except that the canvas id is a parameter to the paint call rather than an attribute of Plod, for no particularly good reason.

This style is a little more verbose -- you have to keep repeating the object name. If you prefer it, cool. About the only reason I see to use it is if you wanted to create a Plod graph dynamically with a bigger, more complex Javascript function. Like if you wanted to plot a mathematical function, like cosine, or x^2-3*x+7, you could use Javascript to generate the values. Here's a little Javascript to draw a parabola.

<canvas id="plod7" width="600" height="300"></canvas>
<script>
var para=new Plod()
para.color="#f00"
para.gridX="line"
para.gridY="line"
for (var xx=0,x=-5;x<5.1;xx++,x+=0.2)
{
	if (xx%5==0) para.x[xx]=Math.floor(x+.5)
	para.y[xx]=x*x
}
para.paint("plod7")
</script>

Error Messages

There are none. If you have syntax errors, the graph just won't display. If your data doesn't make sense, you may get a goofy graph. Someday I'll do something about this. In the meantime, you can use browser tools to see any syntax errors, like IE's F12 functions.

Tech Support

We're giving this away for free so we can't promise a lot of technical support, but if you have trouble, we'll do what we can: Contact us.


Pregnant Pause Home Software Search this site

Copyright 2000,2003,2017 by Pregnant Pause
Contact us.