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 similiar functions are available for jpeg
37 # Retrieve imagemap information
39 $obj->set ( 'imagemap' => 'true' );
40 $imagemap_ref = $obj->imagemap_dump ();
41
43 These manpages 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 modi‐
47 fied and expanded. I borrowed most of the API from Martien Ver‐
48 bruggen's GIFgraph module. I liked most of GIFgraph, but I thought it
49 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
58 the different chart types (Points, Lines, Bars, LinesPoints, Composite,
59 StackedBars, Pie, Pareto, HorizontalBars, Split, ErrorBars, Direction
60 and Mountain so far) are classes by themselves, each inheriting a bunch
61 of methods from the Chart::Base class. Simply replace the word type
62 with the type of chart you want and you're on your way. For example,
63 use Chart::Lines;
65 would invoke the lines module.
67 Getting an object
69 The new method can either be called without arguments, in which case it
71 returns an object with the default image size (400x300 pixels), or you
72 can specify the width and height of the image. Just remember to
73 replace type with the type of graph you want. For example,
74 $obj = Chart::Bars->new (600,400);
76 would return a Chart::Bars object containing a 600x400 pixel image.
78 New also initializes most of the default variables, which you can sub‐
79 sequently change with the set method.
80 Setting different options
82 This is where the fun begins. Set looks for a hash of keys and values.
84 You can pass it a hash that you've already constructed, like
85 %hash = ('title' => 'Foo Bar');
87 $obj->set (%hash);
88 or you can try just constructing the hash inside the set call, like
90 $obj->set ('title' => 'Foo Bar');
92 The following are all of the currently supported options:
94 'transparent'
96 Makes the background of the image transparent if set to 'true'.
97 Useful for making web page images. Default is 'false'.
98 'png_border'
100 Sets the number of pixels used as a border between the graph and
101 the edges of the png/jpeg. Defaults to 10.
102 'graph_border'
104 Sets the number of pixels used as a border between the title/labels
105 and the actual graph within the png. Defaults to 10.
106 'text_space'
108 Sets the amount of space left on the sides of text, to make it more
109 readable. Defaults to 2.
110 'title'
112 Tells GD graph what to use for the title of the graph. If empty,
113 no title is drawn. It recognizes '\n' as a newline, and acts
114 accordingly. Remember, if you want to use normal quotation marks
115 insted of single quotation marks then you have to qoute "\\n".
116 Default is empty.
117 'sub_title'
119 Write a sub-title under the title in smaller letters.
120 'x_label'
122 Tells Chart what to use for the x-axis label. If empty, no label
123 is drawn. Default is empty.
124 'y_label', 'y_label2'
126 Tells Chart what to use for the y-axis labels. If empty, no label
127 is drawn. Default is empty.
128 'legend'
130 Specifies the placement of the legend. Valid values are 'left',
131 'right', 'top', 'bottom'. Setting this to 'none' tells chart not
132 to draw a legend. Default is 'right'.
133 'legend_labels'
135 Sets the values for the labels for the different datasets. Should
136 be assigned a reference to an array of labels. For example,
137 @labels = ('foo', 'bar');
139 $obj->set ('legend_labels' => \@labels);
140 Default is empty, in which case 'Dataset 1', 'Dataset 2', etc. are
142 used as the labels.
143 'tick_len'
145 Sets the length of the x- and y-ticks in pixels. Default is 4.
146 'x_ticks'
148 Specifies how to draw the x-tick labels. Valid values are 'nor‐
149 mal', 'staggered' (staggers the labels vertically), and 'vertical'
150 (the labels are draw upwards). Default is 'normal'.
151 'xy_plot'
153 Forces Chart to plot a x-y-graph, which means, that the x-axis is
154 also numeric if set to 'true'. Very usefull for mathematical
155 graphs. Works for Lines, Points, LinesPoints and ErrorBars. Split
156 makes always a xy_plot. Defaults to 'false'.
157 'min_y_ticks'
159 Sets the minimum number of y_ticks to draw when generating a scale.
160 Default is 6, The minimum is 2.
161 'max_y_ticks'
163 Sets the maximum number of y_ticks to draw when generating a scale.
164 Default is 100. This limit is used to avoid ploting an unreasonably
165 large number of ticks if non-round values are used for the min_val
166 and max_val.
167 The value for 'max_y_ticks' should be at least 5 times larger than
169 'min_y_ticks'.
170 'max_x_ticks', 'min_x_ticks'
172 Work similar as 'max_y_ticks' and 'min_y_ticks'. Of course, only
173 for a xy_plot.
174 'integer_ticks_only'
176 Specifies how to draw the x- and y-ticks: as floating point
177 ('false', '0') or as integer numbers ('true', 1). Default: 'false'
178 'skip_int_ticks'
180 If 'integer_ticks_only' was set to 'true' the labels and ticks will
181 be drawn every nth tick. Of course in horizontalBars it affects th
182 x-axis. Default to 1, no skipping.
183 'precision'
185 Sets the number of numerals after the decimal point. Affects in
186 most cases the y-axis. But also the x-axis if 'xy_plot' was set and
187 also the labels in a pie chart. Defaults to 3.
188 'max_val'
190 Sets the maximum y-value on the graph, overriding the normal
191 auto-scaling. Default is undef.
192 'min_val'
194 Sets the minimum y-value on the graph, overriding the normal
195 auto-scaling. Default is undef.
196 Caution should be used when setting 'max_val' and 'min_val' to
198 floating point or non-round numbers. This is because the scale must
199 start & end on a tick, ticks must have round-number intervals, and
200 include round numbers.
201 Example: Suppose your dataset has a range of 35-114 units, If you
203 specify them as the 'min_val' & 'max_val', The y_axis will be
204 ploted with 80 ticks every 1 unit.. If no 'min_val' & 'max_val',
205 the system will autoscale the range to 30-120 with 10 ticks every
206 10 units.
207 If the 'min_val' & 'max_val' are specifed to exesive precision,
209 they may be overiden by the system, ploting a maximum 'max_y_ticks'
210 ticks.
211 'include_zero'
213 If 'true', forces the y-axis to include zero if it is not in the
214 dataset range. Default is 'false'.
215 In general, it is better to use this, than to set the 'min_val' if
217 that is all you want to acheve.
218 'pt_size'
220 Sets the radius of the points (for Chart::Points, etc.) in pixels.
221 Default is 18.
222 'brush_size'
224 Sets the width of the lines (for Chart::Lines, etc.) in pixels.
225 Default is 6.
226 'skip_x_ticks'
228 Sets the number of x-ticks and x-tick labels to skip. (ie. if
229 'skip_x_ticks' was set to 4, Chart would draw every 4th x-tick and
230 x-tick label). Default is undef.
231 'custom_x_ticks'
233 Used in points, lines, linespoints, errorbars and bars charts, this
234 option allows you to specify exatly which x-ticks and x-tick labels
235 should be drawn. It should be assigned a reference to an array of
236 desired ticks. Just remember that I'm counting from the 0th ele‐
237 ment of the array. (ie., if 'custom_x_ticks' is assigned [0,3,4],
238 then the 0th, 3rd, and 4th x-ticks will be displayed)
239 'f_x_tick'
241 Needs a reference to a function which uses the x-tick labels gener‐
242 ated by the '@data->[0]' as the argument. The result of this func‐
243 tion can reformat the labels. For instance
244 $obj -> set ('f_x_tick' => \&formatter );
246 An example for the function formatter: x labels are seconds since
248 an event. The referenced function can transformat this seconds to
249 hour, minutes and seconds.
250 'f_y_tick'
252 The same situation as for 'f_x_tick' but now used for y labels.
253 'colors'
255 This option lets you control the colors the chart will use. It
256 takes a reference to a hash. The hash should contain keys mapped
257 to references to arrays of rgb values. For instance,
258 $obj->set('colors' => {'background' => [255,255,255]});
260 sets the background color to white (which is the default). Valid
262 keys for this hash are
263 'background' (background color for the png)
265 'title' (color of the title)
266 'text' (all the text in the chart)
267 'x_label' (color of the x-axis label)
268 'y_label' (color of the first y axis label)
269 'y_label2' (color of the second y axis label)
270 'grid_lines' (color of the grid lines)
271 'x_grid_lines' (color of the x grid lines - for x axis ticks)
272 'y_grid_lines' (color of the y grid lines - for to left y axis ticks)
273 'y2_grid_lines' (color of the y2 grid lines - for right y axis ticks)
274 'dataset0'..'dataset63' (the different datasets)
275 'misc' (everything else, ie. ticks, box around the legend)
276 NB. For composite charts, there is a limit of 8 datasets per compo‐
278 nent. The colors for 'dataset8' through 'dataset15' become the
279 colors for 'dataset0' through 'dataset7' for the second component
280 chart.
281 'title_font'
283 This option changes the font of the title. The key has to be a GD
284 font. eg. GD::Font->Large
285 'label_font'
287 This option changes the font of the labels. The key has to be a GD
288 font.
289 'legend_font'
291 This option changes the font of the text in the legend. The key
292 has to be a GD font.
293 'tick_label_font'
295 This is the font for the tick labels. It also needs a GD font
296 object as an argument.
297 'grey_background'
299 Puts a nice soft grey background on the actual data plot when set
300 to 'true'. Default is 'true'.
301 'y_axes'
303 Tells Chart where to place the y-axis. Has no effect on Composite
304 and Pie. Valid values are 'left', 'right' and 'both'. Defaults to
305 'left'.
306 'x_grid_lines'
308 Draws grid lines matching up to x ticks if set to 'true'. Default
309 is false.
310 'y_grid_lines'
312 Draws grid lines matching up to y ticks if set to 'true'. Default
313 is false.
314 'grid_lines'
316 Draws grid lines matching up to x and y ticks.
317 'spaced_bars'
319 Leaves space between the groups of bars at each data point when set
320 to 'true'. This just makes it easier to read a bar chart. Default
321 is 'true'.
322 'imagemap'
324 Lets Chart know you're going to ask for information about the
325 placement of the data for use in creating an image map from the
326 png. This information can be retrieved using the imagemap_dump()
327 method. NB. that the imagemap_dump() method cannot be called until
328 after the Chart has been generated (ie. using the png() or
329 cgi_png() methods).
330 'sort'
332 In a xy-plot, the data will be sorted ascending if set to 'true'.
333 (Should be set if the data isn't sorted, especially in Lines, Split
334 and LinesPoints) In a Pareto Chart the data will be sorted descend‐
335 ing. Defaults to 'false'.
336 'composite_info'
338 This option is only used for composite charts. It contains the
339 information about which types to use for the two component charts,
340 and which datasets belong to which component chart. It should be a
341 reference to an array of array references, containing information
342 like the following
343 $obj->set ('composite_info' => [ ['Bars', [1,2]],
345 ['Lines', [3,4] ] ]);
346 This example would set the two component charts to be a bar chart
348 and a line chart. It would use the first two data sets for the bar
349 chart (note that the numbering starts at 1, not zero like most of
350 the other numbered things in Chart), and the second two data sets
351 for the line chart. The default is undef.
352 NB. Chart::Composite can only do two component charts.
354 'min_val1', 'min_val2'
356 Only for composite charts, these options specify the minimum
357 y-value for the first and second components respectively. Both
358 default to undef.
359 'max_val1', 'max_val2'
361 Only for composite charts, these options specify the maximum
362 y-value for the first and second components respectively. Both
363 default to undef.
364 'ylabel2'
366 The label for the right y-axis (the second component chart) on a
367 composite chart. Default is undef.
368 'y_ticks1', 'y_ticks2'
370 The number of y ticks to use on the first and second y-axis on a
371 composite chart. Please note that if you just set the 'y_ticks'
372 option, both axes will use that number of y ticks. Both default to
373 undef.
374 'f_y_ticks1', 'f_y_ticks2'
376 Only for composite charts, needs a reference to a function which
377 has one argument and has to return a string which labels the first
378 resp. second y axis. Both default to undef.
379 'same_y_axes'
381 Forces both component charts in a composite chart to use the same
382 maximum and minimum y-values if set to 'true'. This helps to keep
383 the composite charts from being too confusing. Default is undef.
384 'no_cache'
386 Adds Pragma: no-cache to the http header. Be careful with this
387 one, as Netscape 4.5 is unfriendly with POST using this method.
388 'legend_example_size'
390 Sets the length of the example line in the legend in pixels.
391 Defaults to 20.
392 'same_error'
394 This is a option only for ErrorBars. It tells chart that you want
395 use the same error value of a data point if set to 'true'. Look at
396 the documentation to see how the module ErrorBars works. Default:
397 'false'.
398 'skip_y_ticks'
400 Does the same for the y-axis at a HorizontalBars chart as
401 'skip_x_ticks' does for other charts. Defaults to 1.
402 'label_values'
404 Tells a pie chart what labels to draw beside the pie. Valid values
405 are 'percent', 'value', 'both' and 'none'. Defaults to 'percent'.
406 'legend_label_values'
408 Tells a pie chart what labels to draw in the legende. Valid values
409 are 'percent', 'value', 'both' and 'none'. Defaults to 'value'.
410 'start'
412 Required value for a split chart. Sets the start value of the first
413 interval. If the x coordinate of the first data point is zero, you
414 should 'set' to zero. Default is 'undef'.
415 'interval'
417 Also a required value for a split chart. It sets the interval of
418 one line to plot. Defaults 'undef'.
419 'interval_ticks'
421 Sets the number of ticks for the x-axis of a Split chart. Defaults
422 to 5.
423 'scale'
425 Every y-value of a split chart will be multiplied with that value,
426 but the scale won't change. Which means that split allows to over‐
427 draw certain rows! Only useful if you want to give prominence to
428 the maximal amplitudes of the data. Defaults to 1.
429 'point'
431 Indicates to draw points in a direction chart. 'true' or 'false'
432 possible. Defaults to 'true'.
433 'line'
435 If you turn this optin to 'true', then direction will connect the
436 points with lines. Defaults to 'false'.
437 'arrow'
439 This is also an option for the direction module. If set to 'true',
440 chart will draw a arrow from the center to the point. Defaults to
441 'false'.
442 'angle_interval'
444 This option tells direction, how many angle lines should be drawn.
445 The default value is 30, which means that a line will be drawn
446 eyery 30 degrees. Valid Values are: 0, 5, 10, 15, 20, 30, 45 and
447 60. If you choose 0, direction will draw no line.
448 'min_circles'
450 Sets the minimum number of circles when generating a scale for
451 direction. Default is 4, minimum is 2.
452 'max_circles'
454 Sets the maximum number of circles when generating a scale for
455 direction. Default is 100. This limit is used to avoid plotting
456 an unreasonable large number of ticks if non-round values are used
457 for the min_val and max_val.
458 'pairs'
460 Only used for direction how to handle more datasets.
461 If 'pairs' is set to 'true',
462 Chart uses the first dataset as a set of degrees and
463 the second dataset as a set of values.
464 Then, the third set is a set of degrees und the
465 fourth a set of values \dots. \\
466 If 'pairs' is set to 'false',
467 Chart uses the first dataset as a set of angels
468 and all following datasets as sets of values.
469 Defaults to 'false'.
470 Sets the maximum number of circles when generating a scale for
472 direction. Default is 100. This limit is used to avoid plotting
473 an unreasonable large number of ticks if non-round values are used
474 for the min_val and max_val.
475 GIFgraph.pm-style API
477 Sending the image to a file
479 Invoking the png method causes the graph to be plotted and saved to
480 a file. It takes the name of the output file and a reference to
481 the data as arguments. For example,
482 $obj->png ("foo.png", \@data);
484 would plot the data in @data, and the save the image to foo.png.
486 Of course, this then beggars the question "What should @data look
487 like?". Well, just like GIFgraph, @data should contain references
488 to arrays of data, with the first array reference pointing to an
489 array of x-tick labels. For example,
490 @data = ( [ 'foo', 'bar', 'junk' ],
492 [ 30.2, 23.5, 92.1 ] );
493 would set up a graph with one dataset, and three data points in
495 that set. In general, the @data array should look something like
496 @data = ( \@x_tick_labels, \@dataset1, ... , \@dataset_n );
498 And no worries, I make my own internal copy of the data, so that it
500 doesn't mess with yours.
501 CGI and Chart
503 Okay, so you're probably thinking, "Do I always have to save these
504 images to disk? What if I want to use Chart to create dynamic
505 images for my web site?" Well, here's the answer to that.
506 $obj->cgi_png ( \@data );
508 The cgi_png method will print the chart, along with the appropriate
510 http header, to stdout, allowing you to call chart-generating
511 scripts directly from your html pages (ie. with a <lt>img
512 src=image.pl<gt> HTML tag). The @data array should be set up the
513 same way as for the normal png method.
514 Graph.pm-style API
516 You might ask, "But what if I just want to add a few points to the
518 graph, and then display it, without all those references to refer‐
519 ences?". Well, friend, the solution is simple. Borrowing the add_pt
520 idea from Matt Kruse's Graph module, you simply make a few calls to the
521 add_pt method, like so:
522 $obj->add_pt ('foo', 30, 25);
524 $obj->add_pt ('bar', 16, 32);
525 Or, if you want to be able to add entire datasets, simply use the
527 add_dataset method:
528 $obj->add_dataset ('foo', 'bar');
530 $obj->add_dataset (30, 16);
531 $obj->add_dataset (25, 32);
532 These methods check to make sure that the points and datasets you are
534 adding are the same size as the ones already there. So, if you have
535 two datasets currently stored, and try to add a data point with three
536 different values, it will carp (per the Carp module) an error message.
537 Similarly, if you try to add a dataset with 4 data points, and all the
538 other datasets have 3 data points, it will carp an error message.
539 Don't forget, when using this API, that I treat the first dataset as a
541 series of x-tick labels. So, in the above examples, the graph would
542 have two x-ticks, labeled 'foo' and 'bar', each with two data points.
543 Pie and ErrorBars handle it different, look at the documentation to see
544 how it works.
545 Adding a datafile
547 You can also add a complete datafile to a chart object. Just use
548 the add_datafile() method.
549 $obj->add_datafile('file', 'set' or 'pt');
551 file can be the name of the data file or a filehandle. 'set' or
553 'pt is the type of the datafile. If the parameter is 'set' then
554 each line in the data file has to be a complete data set. The value
555 of the set has to be seperated by whitespaces. For example the file
556 looks like this:
557 'foo' 'bar'
559 30 16
560 25 32
561 If the parameter is 'pt', one line has to include all values of one
563 data point seperated by whitespaces. For example:
564 'foo' 30 25
566 'bar' 16 32
567 Clearing the data
569 A simple call to the clear_data method empties any values that may
570 have been entered.
571 $obj->clear_data ();
573 Getting a copy of the data
575 If you want a copy of the data that has been added so far, make a
576 call to the get_data method like so:
577 $dataref = $obj->get_data;
579 It returns (you guessed it!) a reference to an array of references
581 to datasets. So the x-tick labels would be stored as
582 @x_labels = @{$dataref->[0]};
584 Sending the image to a file
586 If you just want to print this chart to a file, all you have to do
587 is pass the name of the file to the png() method.
588 $obj->png ("foo.png");
590 Sending the image to a filehandle
592 If you want to do something else with the image, you can also pass
593 a filehandle (either a typeglob or a FileHandle object) to png, and
594 it will print directly to that.
595 $obj->png ($filehandle);
597 $obj->png (FILEHANDLE);
598 CGI and Chart
600 Okay, so you're probably thinking (again), "Do I always have to
601 save these images to disk? What if I want to use Chart to create
602 dynamic images for my web site?" Well, here's the answer to that.
603 $obj->cgi_png ();
605 The cgi_png method will print the chart, along with the appropriate
607 http header, to stdout, allowing you to call chart-generating
608 scripts directly from your html pages (ie. with a <lt>img
609 src=image.pl<gt> HTML tag).
610 Imagemap Support
612 Chart can also return the pixel positioning information so that you can
614 create image maps from the pngs Chart generates. Simply set the
615 'imagemap' option to 'true' before you generate the png, then call the
616 imagemap_dump() method afterwards to retrieve the information. You
617 will be returned a data structure almost identical to the @data array
618 described above to pass the data into Chart.
619 $imagemap_data = $obj->imagemap_dump ();
621 Instead of single data values, you will be passed references to arrays
623 of pixel information. For Bars, HorizontalBars and StackedBars charts,
624 the arrays will contain two x-y pairs (specifying the upper left and
625 lower right corner of the bar), like so
626 ( $x1, $y1, $x2, $y2 ) = @{ $imagemap_data->[$dataset][$datapoint] };
628 For Lines, Points, ErrorBars, Split and LinesPoints, the arrays will
630 contain a single x-y pair (specifying the center of the point), like so
631 ( $x, $y ) = @{ $imagemap_data->[$dataset][$datapoint] };
633 A few caveats apply here. First of all, GD treats the upper-left cor‐
635 ner of the png as the (0,0) point, so positive y values are measured
636 from the top of the png, not the bottom. Second, these values will
637 most likely contain long decimal values. GD, of course, has to trun‐
638 cate these to single pixel values. Since I don't know how GD does it,
639 I can't truncate it the same way he does. In a worst-case scenario,
640 this will result in an error of one pixel on your imagemap. If this is
641 really an issue, your only option is to either experiment with it, or
642 to contact Lincoln Stein and ask him. Third, please remember that the
643 0th dataset will be empty, since that's the place in the @data array
644 for the data point labels.
645
647 · Add some 3-D graphs. Include True Type Fonts
648
650 Probably quite a few, since it's been completely rewritten. As usual,
651 please mail me with any bugs, patches, suggestions, comments, flames,
652 death threats, etc.
653
655 David Bonner (dbonner@cs.bu.edu)
656
658 Chart Group (Chart@wettzell.ifag.de)
659
661 Copyright(c) 1997-1998 by David Bonner, 1999 by Peter Clark, 2001 by
662 the Chart group at BKG-Wettzell. All rights reserved. This program is
663 free software; you can redistribute it and/or modify it under the same
664 terms as Perl itself.
665perl v5.8.8 2003-12-04 Chart(3)