| Pregnant Pause Home | Software | Search this site |
But we recommend you read the instructions ...
Software and documentation (this page) Copyright 2000 by Pregnant Pause.
In the following, the word "product" refers to both the software and the documentation, that is, both the Plod.class file and this text file, jointly or separately.
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, but the applet does have to get downloaded.)
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 applet small, so we didn't want to add a lot of grandiose features. Even with the limited set of options, Plod is more complex than most applets I've seen.
Like any applet, you include this on your Web page by writing an <applet> tag. This must include the name of the program, the directory in which it is stored on your Web server, and the height and width that it should take on your Web page. Assuming you placed the Plod.class file in a directory called "/java", your applet tag would look like this:
Note: Some older browsers do not recognize sizes given as percentages.
Then you must give the data for your graph. By default, Plod draws a line graph. The data is given in <param> tags.
At a minimum, you must give a list of values to use as labels along the x-axis (the horizontal axis), and a list of numbers to use as values for the plotted points. Labels (x-values) are given with the "name" parameter and y-values with the "y" parameter. Each is given as a list separated by commas.
For example, suppose you want to draw a graph of the cookie sales of your Girl Scout troup. Let's say that in 1995 you sold 120 boxes, in 1996 you sold 135, in 1997 you sold 90, and in 1998 you sold 150. You could draw this graph with the following:
Note: 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.)
This gives:
Graph 2:Cookie Sales, with color
Plod recognizes the following color names: red, green, blue, yellow, purple, cyan, white, gray, black. You can precede any of these names with "light" or "dark" to get a slightly different shade, like "lightred" or "darkgreen". (Note there is no space or other separate between the "light" or "dark" and the basic color name.) Lest you wonder: "lightwhite" is the same as white (it don't get any lighter), and likewise "darkblack" is just black. "darkwhite" is a very light gray; "lightblack" is a very dark gray.
You can also give the color as a six-hexadecimal-digit RGB (red-green-blue) value: The first two digits are the amount of red, the next two are the amount of green, and the last two are the amount of blue. Thus "ff0000" is bright red and "ffddcc" is a pinkish-tan (the background color of this page). This is the same way you express RGB values in HTML, except that the initial "#" sign is not used. (Probably a mistake, but Plod version 1 didn't allow for color names, only RGB values, so an identifier wasn't needed.) If you don't understand this paragraph, don't worry about it, just use the color names.
By the way, you might try making the background color the same as the background color of your Web page. I think this gives a nice "integrated" effect.
To continue our cookie sales example, suppose you want to plot the sales of mint rounds and oatmeal cookies separately:
This gives the following:
Graph 3: Cookie Sales, with Multiple Series
which gives:
Graph 4: Cookie Sales, bar chart
If we give multiple series, than we get grouped bars. If we take Graph 3 above and change nothing except to add the "plot=bar", we get:
Graph 5: Cookie Sales, bar chart with multiple series
Note: Plod defaults to drawing a line chart. If you want to state this explicitly, write:
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, usually rounded up to make a nice round number at the top of the scale. If you include any negative numbers in your data, than the scale starts at the smallest (that is, most negative) number.
A technical detail in case you're wondering: 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 top, bottom, or step with the "yscale" param. The value consists of three numbers: The first is the lowest value to show on the scale, the second is the highest, and the third is the step. The lowest can be the special value "min", which means to use the lowest value found in the data, whatever that may be. Likewise the highest can be "max" to use the highest value. The step can be "step" to let Plod compute the step itself (by its normal rules). However, if you have any data points which fall outside the range you have given, Plod adjusts the range to include them. In other words, by specifying low and high points you can give more blank space above or below the graph -- probably because you just didn't like the way it rounded -- or you can override the normal behavior of starting at zero, as long as all your data is above (or all below) zero. You can also adjust the step if you don't like the automatically-generated step value.
The main use for this feature is to override the automatic zero base or to adjust the step value.
For example, suppose we want to draw a pie chart showing the relative sales of mints, oatmeals, and other. We could write this:
Graph 6: Cookie Sales, pie chart
Labels, on the other hand, are seen purely as text. If you enter numbers, they are simply taken as a string of digits. Thus, your labels might be "1995", "1996", and "1997"; or they might be "Jan", "Feb", and "Mar"; or "Dogs", "Cats", and "Hamsters". Numeric labels usually make sense on line graphs. Text labels often make sense on bar charts and pie charts.
(Note: "prunelabel" also has an "az" option to include only the first and last labels. This isn't normally useful if you're typing in the label list manually. It was included for users who create their Plod parameters with a program.)
In either case, Plod should properly line data points up over the "unlabeled" years.
Making all labels text is generally good and flexible, but note that even if you enter numbers, Plod always spaces them out evenly: it does not adjust the space depending on the difference between the numbers. This can lead to a problem on line graphs: Suppose you are drawing a graph and you have data for 1994, 1995, 1996, and 1999, but none for 1997 or 1998. You could write:
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 label.
Leaving out data points on a pie chart is pretty meaningless. I'm not sure what it does, probably nothing useful.
If you have multiple series, you may have data for one that starts sooner or ends later than others. For example, you might have one set of data starting in 1950 but for another your oldest data is 1955. In this case, simply indicate missing data points at the start of the "later" series by beginning the list with commas, one comma for each missing value. On a line graph, the line for this series will not start until the column containing the first data point. Likewise, a series with missing points at the end will stop before reaching the right edge of the graph. On bar charts, the column is simply left out, just like it would be if it occurred in the middle of the series.
Using Plod (Parameters)
Note: These instructions assume you have a basic familiarity with HTML. It is helpful if you know something about including applets in HTML pages, but I think these instructions will take you through the basics. If you need help on HTML or applets in general, there are plenty of sources on the Web, we don't need to repeat it here. See, for example,
Getting Started With HTML and
HTML 3.2: Applets.The Basics
Plod is more complex than most applets, and so has more options and parameters than you may be used to seeing. But bear with us, we think they're fairly straight-forward.
<applet code=Plod.class codebase="/java" width=400 height=200>
The height and width can be given as a number of pixels, or as a percentage of the screen dimensions. To indicate that it's a percentage, just put a percent sign (%) after the number.
<applet code=Plod.class codebase="/java" width=400 height=200>
<param name=label value="1995,1996,1997,1998">
<param name=y value="120,135,90,150">
</applet>
This gives the following results:
Graph 1: Cookie SalesColor
You can change the background color of your graph with the "bgcolor" parameter. You can change the color of the line that is drawn with the "color" parameter. For example, to make the background yellow and the plotted line blue, we would write:
<applet code=Plod.class codebase="/java" width=400 height=200>
<param name=bgcolor value="yellow">
<param name=color value="blue">
<param name=label value="1995,1996,1997,1998">
<param name=y value="120,135,90,150">
</applet>
Multiple Series
You can include multiple series in your graph. That is, you can plot more than one line on the same graph. To do this, include a param of "y1" with the y values for the second line, "y2" for the third line, etc. You can go up to "y5". You should usually give each series a different color so the reader can tell them apart. You do this by specifying "color1", "color2", etc. To let the reader know which color is which, you probably want to add a "Legend". To do this, give each series a name to place on the legend. Use the "legend" param to give a name to "y", "legend1" to give a name to "y1", etc.
<applet code=Plod.class codebase="/java" width=400 height=200>
<param name=bgcolor value="yellow">
<param name=label value="1995,1996,1997,1998">
<param name=legend value="Total">
<param name=y value="120,135,90,150">
<param name=color value="blue">
<param name=legend1 value="Mint rounds">
<param name=y1 value="40,45,30,80">
<param name=color1 value="darkgreen">
<param name=legend2 value="Oatmeal">
<param name=y2 value="15,15,10,20">
<param name=color2 value="red">
</applet>
By the way, the order in which you write the <param> tags does not matter.Bar charts
To draw a bar chart, add
<param name=plot value=bar>
The labels, data, colors, and legends are specified just like for line graphs. Instead of plotting a line connecting a series of points, we draw a series of bars. We can turn our cookie sale line chart into a bar chart just by adding the "plot=bar". Here's Graph 2 with nothing changed except that we turn it into a bar chart:
<applet code=Plod.class codebase="/java" width=400 height=200>
<param name=plot value="bar">
<param name=bgcolor value="yellow">
<param name=color value="darkgreen">
<param name=label value="1995,1996,1997,1998">
<param name=y value="120,135,90,150">
</applet>
<param name=plot value=line>
Scale
This feature is not needed very often, but it's here if you want it.Pie charts
To draw a pie chart, specify
<param name=plot value=pie>
A pie chart can only have one series, given as "y". (If you give additional series, they are ignored.) Instead of representing height, the values then represent the relative sizes of the slices of the pie. Each value will, in effect, be converted to a percentage of the total. (It is not necessary for them to add up to 100 or any other particular total.) The labels are used to label each slice of the pie. You specify the colors of the slices with the "color" param: for a pie, you write a list of colors separated by commas. If you give fewer colors than there are data points, then after Plod uses the last color in the list, it goes back to the beginning and starts through the list again. Note: Be careful that you don't make the first slice and the last slice the same color -- it won't be possible to tell where the dividing line is.
<applet code=Plod.class codebase="/java" width=400 height=200>
<param name=plot value="pie">
<param name=bgcolor value="yellow">
<param name=label value="Mints,Oatmeal,Other">
<param name=y value="80,20,50">
<param name=color value="darkgreen,red,blue">
</applet>
Which gives:Font
You can change the font used to draw the various text on the graph with the "font" param. Give a font name, two commas, and a font size in points. (The two commas are because we are reserving space to someday add a "font style", like bold or italics. But we haven't done that yet.). For example:
<param name=font value="TimesRoman,,14">
Some details on labels and y-values
Plod views y-values as numbers. These are plotted proportionate to their value, that is, "2" will be twice as far up the graph as "1" on a line chart or bar chart, or take twice as much space on a pie chart. (Hopefully what you would expect when plotting numbers on a graph.) They may include decimal places. For line and bar charts, they may be positive or negative. (For pie charts, negative numbers make little sense.)Missing points and interpolation
If you have many data points, the labels along your x-axis may get crowded. They may even start writing over each other. To avoid this, simply leave out some of the labels, but include the comma to indicate that a label has been omitted. For example, if you have data points for every year from 1970 to 1990, that makes 30 labels, probably too much to be drawn neatly. Instead you could write:
<param name=label value="1970,,,,,1975,,,,,1980,,,,,1985,,,,,1990">
If you prefer, you can tell Plod to remove the extra labels for you with the "prunelabel" parameter. The default value for prunelabel is "no". Write "fit" to cause Plod to exclude overlapping labels:
<param name=prunelabel value=fit>
There are pros and cons to excluding labels manually versus using "fit": If you omit the labels yourself, you can make a selection that makes sense, like the above example, where we included years that were multiples of 5. If you leave it up to Plod and "fit", you might get an odd list like "1970,,,,1974,,,,,1979,,,1983,,,,,1987". On the other hand, when you type in your parameters, you don't normally know what the user's screen resolution is: a set of labels that looks great at 1200x1000 may be crowded or overlapping at 800x600. "fit" is calculated based on what is actually appearing on the user's screen, so it automatically adjusts for window size and screen resolution.
<param name=label value="1994,1995,1996,1999">
<param name=y value="10,20,30,60">
But this puts just as much space between 1996 and 1999 as it does between 1995 and 1996. Even though the numbers here represent a steady trend -- increasing by about 10 per year -- this will give a misleadingly steap climb between 1996 and 1999, because the change for three years is compressed into the same amount of space as prior points gave for one year. To avoid this, you should include labels for the missing years, even though you don't have any data for them.
Then omit y values for these data points. Just like for omitted labels, simply put two commas in a row to indicate a missing y value. (Or more than two commas to indicate multiple missing values.) Plod interpolates for any missing points. That is, if you leave out one point, it assumes that that value was exactly half-way between the values on either side. If you leave out two points, it assumes that the first is 1/3 of the way between and the second is 2/3. Etc.Grid
You can add a grid to the plot with the "grid" parameter. You specify whether to draw grid lines separately for the x and y directions. For each, you can write "no", for no grid, "tick" for small tick marks, or "line", for lines extending the entire height or width of the graph. x comes first, then y, separated by a comma. Example:
<param name=grid value="tick,line">
Printing
When the reader prints a Web page that includes a Plod graph, the graph may not print. Some older browsers do not print out applets. The newer browsers print them quite nicely.Tech Support
Contact us.
| Pregnant Pause Home | Software | Search this site |
Copyright 2000,2003 by Pregnant Pause