1Chart(3) User Contributed Perl Documentation Chart(3)
2
6 Chart - a series of charting modules
7
9 use Chart::type; (type is one of: Points, Lines, Bars, LinesPoints, Composite,
10 StackedBars, Mountain, Pie, HorizontalBars, Split, ErrorBars, Pareto, Direction)
11 $obj = Chart::type->new;
13 $obj = Chart::type->new ( $png_width, $png_height );
14 $obj->set ( $key_1, $val_1, ... ,$key_n, $val_n );
16 $obj->set ( $key_1 => $val_1,
17 ...
18 $key_n => $val_n );
19 $obj->set ( %hash );
20 # GIFgraph.pm-style API to produce png formatted charts
22 @data = ( \@x_tick_labels, \@dataset1, ... , \@dataset_n );
23 $obj->png ( "filename", \@data );
24 $obj->png ( $filehandle, \@data );
25 $obj->png ( FILEHANDLE, \@data );
26 $obj->cgi_png ( \@data );
27 # Graph.pm-style API
29 $obj->add_pt ($label, $val_1, ... , $val_n);
30 $obj->add_dataset ($val_1, ... , $val_n);
31 $obj->png ( "filename" );
32 $obj->png ( $filehandle );
33 $obj->png ( FILEHANDLE );
34 $obj->cgi_png ();
35 The similar functions are available for j-peg
37 # Retrieve image map information
39 $obj->set ( 'imagemap' => 'true' );
40 $imagemap_ref = $obj->imagemap_dump ();
41
43 These man-pages give you the most important information about Chart.
44 There is also a complete documentation (Documentation.pdf) within the
45 Chart package. Look at it to get more information. This module is an
46 attempt to build a general purpose graphing module that is easily
47 modified and expanded. I borrowed most of the API from Martien
48 Verbruggen's GIFgraph module. I liked most of GIFgraph, but I thought
49 it was to difficult to modify, and it was missing a few things that I
50 needed, most notably legends. So I decided to write a new module from
51 scratch, and I've designed it from the bottom up to be easy to modify.
52 Like GIFgraph, Chart uses Lincoln Stein's GD module for all of its
53 graphics primitives calls.
54 use-ing Chart
56 Okay, so you caught me. There's really no Chart::type module. All of
57 the different chart types (Points, Lines, Bars, LinesPoints, Composite,
58 StackedBars, Pie, Pareto, HorizontalBars, Split, ErrorBars, Direction
59 and Mountain so far) are classes by themselves, each inheriting a bunch
60 of methods from the Chart::Base class. Simply replace the word type
61 with the type of chart you want and you're on your way. For example,
62 use Chart::Lines;
64 would invoke the lines module.
66 Getting an object
68 The new method can either be called without arguments, in which case it
69 returns an object with the default image size (400x300 pixels), or you
70 can specify the width and height of the image. Just remember to
71 replace type with the type of graph you want. For example,
72 $obj = Chart::Bars->new (600,400);
74 would return a Chart::Bars object containing a 600x400 pixel image.
76 New also initializes most of the default variables, which you can
77 subsequently change with the set method.
78 Setting different options
80 This is where the fun begins. Set looks for a hash of keys and values.
81 You can pass it a hash that you've already constructed, like
82 %hash = ('title' => 'Foo Bar');
84 $obj->set (%hash);
85 or you can try just constructing the hash inside the set call, like
87 $obj->set ('title' => 'Foo Bar');
89 The following are all of the currently supported options:
91 'transparent'
93 Makes the background of the image transparent if set to 'true'.
94 Useful for making web page images. Default is 'false'.
95 'png_border'
97 Sets the number of pixels used as a border between the graph and
98 the edges of the png/j-peg. Defaults to 10.
99 'graph_border'
101 Sets the number of pixels used as a border between the title/labels
102 and the actual graph within the png. Defaults to 10.
103 'text_space'
105 Sets the amount of space left on the sides of text, to make it more
106 readable. Defaults to 2.
107 'title'
109 Tells GD graph what to use for the title of the graph. If empty,
110 no title is drawn. It recognizes '\n' as a newline, and acts
111 accordingly. Remember, if you want to use normal quotation marks
112 instead of single quotation marks then you have to quote "\\n".
113 Default is empty.
114 'sub_title'
116 Write a sub-title under the title in smaller letters.
117 'x_label'
119 Tells Chart what to use for the x-axis label. If empty, no label
120 is drawn. Default is empty.
121 'y_label', 'y_label2'
123 Tells Chart what to use for the y-axis labels. If empty, no label
124 is drawn. Default is empty.
125 'legend'
127 Specifies the placement of the legend. Valid values are 'left',
128 'right', 'top', 'bottom'. Setting this to 'none' tells chart not
129 to draw a legend. Default is 'right'.
130 'legend_labels'
132 Sets the values for the labels for the different data sets. Should
133 be assigned a reference to an array of labels. For example,
134 @labels = ('foo', 'bar');
136 $obj->set ('legend_labels' => \@labels);
137 Default is empty, in which case 'Dataset 1', 'Dataset 2', etc. are
139 used as the labels.
140 'tick_len'
142 Sets the length of the x- and y-ticks in pixels. Default is 4.
143 'x_ticks'
145 Specifies how to draw the x-tick labels. Valid values are
146 'normal', 'staggered' (staggers the labels vertically), and
147 'vertical' (the labels are draw upwards). Default is 'normal'.
148 'xy_plot'
150 Forces Chart to plot a x-y-graph, which means, that the x-axis is
151 also numeric if set to 'true'. Very useful for mathematical graphs.
152 Works for Lines, Points, LinesPoints and ErrorBars. Split makes
153 always a xy_plot. Defaults to 'false'.
154 'min_y_ticks'
156 Sets the minimum number of y_ticks to draw when generating a scale.
157 Default is 6, The minimum is 2.
158 'max_y_ticks'
160 Sets the maximum number of y_ticks to draw when generating a scale.
161 Default is 100. This limit is used to avoid plotting an
162 unreasonable large number of ticks if non-round values are used for
163 the min_val and max_val.
164 The value for 'max_y_ticks' should be at least 5 times larger than
166 'min_y_ticks'.
167 'max_x_ticks', 'min_x_ticks'
169 Work similar as 'max_y_ticks' and 'min_y_ticks'. Of course, only
170 for a xy_plot.
171 'integer_ticks_only'
173 Specifies how to draw the x- and y-ticks: as floating point
174 ('false', '0') or as integer numbers ('true', 1). Default: 'false'
175 'skip_int_ticks'
177 If 'integer_ticks_only' was set to 'true' the labels and ticks will
178 be drawn every nth tick. Of course in horizontalBars it affects the
179 x-axis. Default to 1, no skipping.
180 'precision'
182 Sets the number of numerals after the decimal point. Affects in
183 most cases the y-axis. But also the x-axis if 'xy_plot' was set and
184 also the labels in a pie chart. Defaults to 3.
185 'max_val'
187 Sets the maximum y-value on the graph, overriding the normal auto-
188 scaling. Default is undef.
189 'min_val'
191 Sets the minimum y-value on the graph, overriding the normal auto-
192 scaling. Default is undef.
193 Caution should be used when setting 'max_val' and 'min_val' to
195 floating point or non-round numbers. This is because the scale must
196 start & end on a tick, ticks must have round-number intervals, and
197 include round numbers.
198 Example: Suppose your data set has a range of 35-114 units. If you
200 specify them as the 'min_val' & 'max_val', the y_axis will be
201 plotted with 80 ticks every 1 unit.. If no 'min_val' & 'max_val',
202 the system will auto scale the range to 30-120 with 10 ticks every
203 10 units.
204 If the 'min_val' & 'max_val' are specified to excessive precision,
206 they may be overridden by the system, plotting a maximum
207 'max_y_ticks' ticks.
208 'include_zero'
210 If 'true', forces the y-axis to include zero if it is not in the
211 dataset range. Default is 'false'.
212 In general, it is better to use this, than to set the 'min_val' if
214 that is all you want to achieve.
215 'pt_size'
217 Sets the radius of the points (for Chart::Points, etc.) in pixels.
218 Default is 18.
219 'brush_size'
221 Sets the width of the lines (for Chart::Lines, etc.) in pixels.
222 Default is 6.
223 'brushStyle'
225 Sets the shape of points for Chart::Points, Chart::LinesPoints.
226 The possibilities are 'FilledCircle', 'circle', 'donut',
227 'OpenCircle', 'fatPlus', 'triangle', 'upsidedownTriangle',
228 'square', 'hollowSquare', 'OpenRectangle', 'FilledDiamond',
229 'OpenDiamond', 'Star', 'OpenStar'. Default: 'FilledCircle
230 'skip_x_ticks'
232 Sets the number of x-ticks and x-tick labels to skip. (ie. if
233 'skip_x_ticks' was set to 4, Chart would draw every 4th x-tick and
234 x-tick label). Default is undef.
235 'custom_x_ticks'
237 Used in points, lines, linespoints, errorbars and bars charts, this
238 option allows you to you to specify exactly which x-ticks and
239 x-tick labels should be drawn. It should be assigned a reference
240 to an array of desired ticks. Just remember that I'm counting from
241 the 0th element of the array. (ie., if 'custom_x_ticks' is
242 assigned [0,3,4], then the 0th, 3rd, and 4th x-ticks will be
243 displayed)
244 'f_x_tick'
246 Needs a reference to a function which uses the x-tick labels
247 generated by the '@data[0]' as the argument. The result of this
248 function can reformat the labels. For instance
249 $obj -> set ('f_x_tick' => \&formatter );
251 An example for the function formatter: x labels are seconds since
253 an event. The referenced function can transform this seconds to
254 hour, minutes and seconds.
255 'f_y_tick'
257 The same situation as for 'f_x_tick' but now used for y labels.
258 'colors'
260 This option lets you control the colors the chart will use. It
261 takes a reference to a hash. The hash should contain keys mapped
262 to references to arrays of rgb values. For instance,
263 $obj->set('colors' => {'background' => [255,255,255]});
265 sets the background color to white (which is the default). Valid
267 keys for this hash are
268 'background' (background color for the png)
270 'title' (color of the title)
271 'text' (all the text in the chart)
272 'x_label' (color of the x-axis label)
273 'y_label' (color of the first y axis label)
274 'y_label2' (color of the second y axis label)
275 'grid_lines' (color of the grid lines)
276 'x_grid_lines' (color of the x grid lines - for x axis ticks)
277 'y_grid_lines' (color of the y grid lines - for to left y axis ticks)
278 'y2_grid_lines' (color of the y2 grid lines - for right y axis ticks)
279 'dataset0'..'dataset63' (the different datasets)
280 'misc' (everything else, ie. ticks, box around the legend)
281 NB. For composite charts, there is a limit of 8 datasets per
283 component. The colors for 'dataset8' through 'dataset15' become
284 the colors for 'dataset0' through 'dataset7' for the second
285 component chart.
286 'title_font'
288 This option changes the font of the title. The key has to be a GD
289 font. eg. GD::Font->Large
290 'label_font'
292 This option changes the font of the labels. The key has to be a GD
293 font.
294 'legend_font'
296 This option changes the font of the text in the legend. The key
297 has to be a GD font.
298 'tick_label_font'
300 This is the font for the tick labels. It also needs a GD font
301 object as an argument.
302 'grey_background'
304 Puts a nice soft grey background on the actual data plot when set
305 to 'true'. Default is 'true'.
306 'y_axes'
308 Tells Chart where to place the y-axis. Has no effect on Composite
309 and Pie. Valid values are 'left', 'right' and 'both'. Defaults to
310 'left'.
311 'x_grid_lines'
313 Draws grid lines matching up to x ticks if set to 'true'. Default
314 is false.
315 'y_grid_lines'
317 Draws grid lines matching up to y ticks if set to 'true'. Default
318 is false.
319 'grid_lines'
321 Draws grid lines matching up to x and y ticks.
322 'spaced_bars'
324 Leaves space between the groups of bars at each data point when set
325 to 'true'. This just makes it easier to read a bar chart. Default
326 is 'true'.
327 'imagemap'
329 Lets Chart know you're going to ask for information about the
330 placement of the data for use in creating an image map from the
331 png. This information can be retrieved using the imagemap_dump()
332 method. NB. that the imagemap_dump() method cannot be called until
333 after the Chart has been generated (ie. using the png() or
334 cgi_png() methods).
335 'sort'
337 In a xy-plot, the data will be sorted ascending if set to 'true'.
338 (Should be set if the data isn't sorted, especially in Lines, Split
339 and LinesPoints) In a Pareto Chart the data will be sorted
340 descending. Defaults to 'false'.
341 'composite_info'
343 This option is only used for composite charts. It contains the
344 information about which types to use for the two component charts,
345 and which datasets belong to which component chart. It should be a
346 reference to an array of array references, containing information
347 like the following
348 $obj->set ('composite_info' => [ ['Bars', [1,2]],
350 ['Lines', [3,4] ] ]);
351 This example would set the two component charts to be a bar chart
353 and a line chart. It would use the first two data sets for the bar
354 chart (note that the numbering starts at 1, not zero like most of
355 the other numbered things in Chart), and the second two data sets
356 for the line chart. The default is undef.
357 NB. Chart::Composite can only do two component charts.
359 'min_val1', 'min_val2'
361 Only for composite charts, these options specify the minimum
362 y-value for the first and second components respectively. Both
363 default to undef.
364 'max_val1', 'max_val2'
366 Only for composite charts, these options specify the maximum
367 y-value for the first and second components respectively. Both
368 default to undef.
369 'ylabel2'
371 The label for the right y-axis (the second component chart) on a
372 composite chart. Default is undef.
373 'y_ticks1', 'y_ticks2'
375 The number of y ticks to use on the first and second y-axis on a
376 composite chart. Please note that if you just set the 'y_ticks'
377 option, both axes will use that number of y ticks. Both default to
378 undef.
379 'f_y_ticks1', 'f_y_ticks2'
381 Only for composite charts, needs a reference to a function which
382 has one argument and has to return a string which labels the first
383 resp. second y axis. Both default to undef.
384 'same_y_axes'
386 Forces both component charts in a composite chart to use the same
387 maximum and minimum y-values if set to 'true'. This helps to keep
388 the composite charts from being too confusing. Default is undef.
389 'no_cache'
391 Adds Pragma: no-cache to the http header. Be careful with this
392 one, as Netscape 4.5 is unfriendly with POST using this method.
393 'legend_example_size'
395 Sets the length of the example line in the legend in pixels.
396 Defaults to 20.
397 'same_error'
399 This is a option only for ErrorBars. It tells chart that you want
400 use the same error value of a data point if set to 'true'. Look at
401 the documentation to see how the module ErrorBars works. Default:
402 'false'.
403 'skip_y_ticks'
405 Does the same for the y-axis at a HorizontalBars chart as
406 'skip_x_ticks' does for other charts. Defaults to 1.
407 'label_values'
409 Tells a pie chart what labels to draw beside the pie. Valid values
410 are 'percent', 'value', 'both' and 'none'. Defaults to 'percent'.
411 'legend_label_values'
413 Tells a pie chart what labels to draw in the legend. Valid values
414 are 'percent', 'value', 'both' and 'none'. Defaults to 'value'.
415 'start'
417 Required value for a split chart. Sets the start value of the first
418 interval. If the x coordinate of the first data point is zero, you
419 should 'set' to zero. Default is 'undef'.
420 'interval'
422 Also a required value for a split chart. It sets the interval of
423 one line to plot. Defaults 'undef'.
424 'interval_ticks'
426 Sets the number of ticks for the x-axis of a Split chart. Defaults
427 to 5.
428 'scale'
430 Every y-value of a split chart will be multiplied with that value,
431 but the scale won't change. Which means that split allows one to
432 overdraw certain rows! Only useful if you want to give prominence
433 to the maximal amplitudes of the data. Defaults to 1.
434 'point'
436 Indicates to draw points in a direction chart. 'true' or 'false'
437 possible. Defaults to 'true'.
438 'line'
440 If you turn this option to 'true', then direction will connect the
441 points with lines. Defaults to 'false'.
442 'arrow'
444 This is also an option for the direction module. If set to 'true',
445 chart will draw a arrow from the center to the point. Defaults to
446 'false'.
447 'angle_interval'
449 This option tells direction, how many angle lines should be drawn.
450 The default value is 30, which means that a line will be drawn
451 every 30 degrees. Valid Values are: 0, 5, 10, 15, 20, 30, 45 and
452 60. If you choose 0, direction will draw no line.
453 'min_circles'
455 Sets the minimum number of circles when generating a scale for
456 direction. Default is 4, minimum is 2.
457 'max_circles'
459 Sets the maximum number of circles when generating a scale for
460 direction. Default is 100. This limit is used to avoid plotting
461 an unreasonable large number of ticks if non-round values are used
462 for the min_val and max_val.
463 'pairs'
465 Only used for direction how to handle more datasets.
466 If 'pairs' is set to 'true',
467 Chart uses the first dataset as a set of degrees and
468 the second dataset as a set of values.
469 Then, the third set is a set of degrees and the
470 fourth a set of values \dots. \\
471 If 'pairs' is set to 'false',
472 Chart uses the first dataset as a set of angels
473 and all following datasets as sets of values.
474 Defaults to 'false'.
475 Sets the maximum number of circles when generating a scale for
477 direction. Default is 100. This limit is used to avoid plotting
478 an unreasonable large number of ticks if non-round values are used
479 for the min_val and max_val.
480 GIFgraph.pm-style API
482 Sending the image to a file
483 Invoking the png method causes the graph to be plotted and saved to
484 a file. It takes the name of the output file and a reference to
485 the data as arguments. For example,
486 $obj->png ("foo.png", \@data);
488 would plot the data in @data, and the save the image to foo.png.
490 Of course, this then beggars the question "What should @data look
491 like?". Well, just like GIFgraph, @data should contain references
492 to arrays of data, with the first array reference pointing to an
493 array of x-tick labels. For example,
494 @data = ( [ 'foo', 'bar', 'junk' ],
496 [ 30.2, 23.5, 92.1 ] );
497 would set up a graph with one dataset, and three data points in
499 that set. In general, the @data array should look something like
500 @data = ( \@x_tick_labels, \@dataset1, ... , \@dataset_n );
502 And no worries, I make my own internal copy of the data, so that it
504 doesn't mess with yours.
505 CGI and Chart
507 Okay, so you're probably thinking, "Do I always have to save these
508 images to disk? What if I want to use Chart to create dynamic
509 images for my web site?" Well, here's the answer to that.
510 $obj->cgi_png ( \@data );
512 The cgi_png method will print the chart, along with the appropriate
514 http header, to stdout, allowing you to call chart-generating
515 scripts directly from your html pages (ie. with a <lt>img
516 src=image.pl<gt> HTML tag). The @data array should be set up the
517 same way as for the normal png method.
518 Graph.pm-style API
520 You might ask, "But what if I just want to add a few points to the
521 graph, and then display it, without all those references to
522 references?". Well, friend, the solution is simple. Borrowing the
523 add_pt idea from Matt Kruse's Graph module, you simply make a few calls
524 to the add_pt method, like so:
525 $obj->add_pt ('foo', 30, 25);
527 $obj->add_pt ('bar', 16, 32);
528 Or, if you want to be able to add entire datasets, simply use the
530 add_dataset method:
531 $obj->add_dataset ('foo', 'bar');
533 $obj->add_dataset (30, 16);
534 $obj->add_dataset (25, 32);
535 These methods check to make sure that the points and datasets you are
537 adding are the same size as the ones already there. So, if you have
538 two datasets currently stored, and try to add a data point with three
539 different values, it will carp (per the Carp module) an error message.
540 Similarly, if you try to add a dataset with 4 data points, and all the
541 other datasets have 3 data points, it will carp an error message.
542 Don't forget, when using this API, that I treat the first dataset as a
544 series of x-tick labels. So, in the above examples, the graph would
545 have two x-ticks, labeled 'foo' and 'bar', each with two data points.
546 Pie and ErrorBars handle it different, look at the documentation to see
547 how it works.
548 Adding a datafile
550 You can also add a complete datafile to a chart object. Just use
551 the add_datafile() method.
552 $obj->add_datafile('file', 'set' or 'pt');
554 file can be the name of the data file or a filehandle. 'set' or
556 'pt is the type of the datafile. If the parameter is 'set' then
557 each line in the data file has to be a complete data set. The value
558 of the set has to be separated by white spaces. For example the
559 file looks like this:
560 'foo' 'bar'
562 30 16
563 25 32
564 If the parameter is 'pt', one line has to include all values of one
566 data point separated by white spaces. For example:
567 'foo' 30 25
569 'bar' 16 32
570 Clearing the data
572 A simple call to the clear_data method empties any values that may
573 have been entered.
574 $obj->clear_data ();
576 Getting a copy of the data
578 If you want a copy of the data that has been added so far, make a
579 call to the get_data method like so:
580 $dataref = $obj->get_data;
582 It returns (you guessed it!) a reference to an array of references
584 to datasets. So the x-tick labels would be stored as
585 @x_labels = @{$dataref->[0]};
587 Sending the image to a file
589 If you just want to print this chart to a file, all you have to do
590 is pass the name of the file to the png() method.
591 $obj->png ("foo.png");
593 Sending the image to a filehandle
595 If you want to do something else with the image, you can also pass
596 a filehandle (either a typeglob or a FileHandle object) to png, and
597 it will print directly to that.
598 $obj->png ($filehandle);
600 $obj->png (FILEHANDLE);
601 CGI and Chart
603 Okay, so you're probably thinking (again), "Do I always have to
604 save these images to disk? What if I want to use Chart to create
605 dynamic images for my web site?" Well, here's the answer to that.
606 $obj->cgi_png ();
608 The cgi_png method will print the chart, along with the appropriate
610 http header, to stdout, allowing you to call chart-generating
611 scripts directly from your html pages (ie. with a <lt>img
612 src=image.pl<gt> HTML tag).
613 Produce a png image as a scalar
615 Like scalar_jpeg() the image is produced as a scalar so that the
616 programmer-user can do whatever the heck s/he wants to with it:
617 $obj-scalar_png($dataref)
619 Produce a jpeg image as a scalar
621 Like scalar_png() the image is produced as a scalar so that the
622 programmer-user can do whatever the heck s/he wants to with it:
623 $obj-scalar_jpeg($dataref)
625 Imagemap Support
627 Chart can also return the pixel positioning information so that you can
628 create image maps from the pngs Chart generates. Simply set the
629 'imagemap' option to 'true' before you generate the png, then call the
630 imagemap_dump() method afterwards to retrieve the information. You
631 will be returned a data structure almost identical to the @data array
632 described above to pass the data into Chart.
633 $imagemap_data = $obj->imagemap_dump ();
635 Instead of single data values, you will be passed references to arrays
637 of pixel information. For Bars, HorizontalBars and StackedBars charts,
638 the arrays will contain two x-y pairs (specifying the upper left and
639 lower right corner of the bar), like so
640 ( $x1, $y1, $x2, $y2 ) = @{ $imagemap_data->[$dataset][$datapoint] };
642 For Lines, Points, ErrorBars, Split and LinesPoints, the arrays will
644 contain a single x-y pair (specifying the center of the point), like so
645 ( $x, $y ) = @{ $imagemap_data->[$dataset][$datapoint] };
647 A few caveats apply here. First of all, GD treats the upper-left
649 corner of the png as the (0,0) point, so positive y values are measured
650 from the top of the png, not the bottom. Second, these values will
651 most likely contain long decimal values. GD, of course, has to
652 truncate these to single pixel values. Since I don't know how GD does
653 it, I can't truncate it the same way he does. In a worst-case
654 scenario, this will result in an error of one pixel on your imagemap.
655 If this is really an issue, your only option is to either experiment
656 with it, or to contact Lincoln Stein and ask him. Third, please
657 remember that the 0th dataset will be empty, since that's the place in
658 the @data array for the data point labels.
659
661 • Add some 3-D graphs. Include True Type Fonts
662
664 Probably quite a few, since it's been completely rewritten. As usual,
665 please mail me with any bugs, patches, suggestions, comments, flames,
666 death threats, etc.
667
669 David Bonner (dbonner@cs.bu.edu)
670
672 Chart Group (Chart@fs.wettzell.de)
673
675 Copyright(c) 1997-1998 by David Bonner, 1999 by Peter Clark, 2001 by
676 the Chart group at BKG-Wettzell. All rights reserved. This program is
677 free software; you can redistribute it and/or modify it under the same
678 terms as Perl itself.
679
681 Hey! The above document had some coding errors, which are explained
682 below:
683 Around line 694:
685 '=item' outside of any '=over'
686 Around line 706:
688 '=item' outside of any '=over'
689perl v5.34.0 2021-07-22 Chart(3)