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
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/jpeg. 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 insted of single quotation marks then you have to qoute "\\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 datasets. 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 usefull for mathematical
152 graphs. Works for Lines, Points, LinesPoints and ErrorBars. Split
153 makes 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 ploting an unreasonably
162 large number of ticks if non-round values are used for the min_val
163 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 th
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 dataset has a range of 35-114 units, If you
200 specify them as the 'min_val' & 'max_val', The y_axis will be
201 ploted with 80 ticks every 1 unit.. If no 'min_val' & 'max_val',
202 the system will autoscale the range to 30-120 with 10 ticks every
203 10 units.
204 If the 'min_val' & 'max_val' are specifed to exesive precision,
206 they may be overiden by the system, ploting a maximum 'max_y_ticks'
207 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 acheve.
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 'skip_x_ticks'
225 Sets the number of x-ticks and x-tick labels to skip. (ie. if
226 'skip_x_ticks' was set to 4, Chart would draw every 4th x-tick and
227 x-tick label). Default is undef.
228 'custom_x_ticks'
230 Used in points, lines, linespoints, errorbars and bars charts, this
231 option allows you to specify exatly which x-ticks and x-tick labels
232 should be drawn. It should be assigned a reference to an array of
233 desired ticks. Just remember that I'm counting from the 0th
234 element of the array. (ie., if 'custom_x_ticks' is assigned
235 [0,3,4], then the 0th, 3rd, and 4th x-ticks will be displayed)
236 'f_x_tick'
238 Needs a reference to a function which uses the x-tick labels
239 generated by the '@data->[0]' as the argument. The result of this
240 function can reformat the labels. For instance
241 $obj -> set ('f_x_tick' => \&formatter );
243 An example for the function formatter: x labels are seconds since
245 an event. The referenced function can transformat this seconds to
246 hour, minutes and seconds.
247 'f_y_tick'
249 The same situation as for 'f_x_tick' but now used for y labels.
250 'colors'
252 This option lets you control the colors the chart will use. It
253 takes a reference to a hash. The hash should contain keys mapped
254 to references to arrays of rgb values. For instance,
255 $obj->set('colors' => {'background' => [255,255,255]});
257 sets the background color to white (which is the default). Valid
259 keys for this hash are
260 'background' (background color for the png)
262 'title' (color of the title)
263 'text' (all the text in the chart)
264 'x_label' (color of the x-axis label)
265 'y_label' (color of the first y axis label)
266 'y_label2' (color of the second y axis label)
267 'grid_lines' (color of the grid lines)
268 'x_grid_lines' (color of the x grid lines - for x axis ticks)
269 'y_grid_lines' (color of the y grid lines - for to left y axis ticks)
270 'y2_grid_lines' (color of the y2 grid lines - for right y axis ticks)
271 'dataset0'..'dataset63' (the different datasets)
272 'misc' (everything else, ie. ticks, box around the legend)
273 NB. For composite charts, there is a limit of 8 datasets per
275 component. The colors for 'dataset8' through 'dataset15' become
276 the colors for 'dataset0' through 'dataset7' for the second
277 component chart.
278 'title_font'
280 This option changes the font of the title. The key has to be a GD
281 font. eg. GD::Font->Large
282 'label_font'
284 This option changes the font of the labels. The key has to be a GD
285 font.
286 'legend_font'
288 This option changes the font of the text in the legend. The key
289 has to be a GD font.
290 'tick_label_font'
292 This is the font for the tick labels. It also needs a GD font
293 object as an argument.
294 'grey_background'
296 Puts a nice soft grey background on the actual data plot when set
297 to 'true'. Default is 'true'.
298 'y_axes'
300 Tells Chart where to place the y-axis. Has no effect on Composite
301 and Pie. Valid values are 'left', 'right' and 'both'. Defaults to
302 'left'.
303 'x_grid_lines'
305 Draws grid lines matching up to x ticks if set to 'true'. Default
306 is false.
307 'y_grid_lines'
309 Draws grid lines matching up to y ticks if set to 'true'. Default
310 is false.
311 'grid_lines'
313 Draws grid lines matching up to x and y ticks.
314 'spaced_bars'
316 Leaves space between the groups of bars at each data point when set
317 to 'true'. This just makes it easier to read a bar chart. Default
318 is 'true'.
319 'imagemap'
321 Lets Chart know you're going to ask for information about the
322 placement of the data for use in creating an image map from the
323 png. This information can be retrieved using the imagemap_dump()
324 method. NB. that the imagemap_dump() method cannot be called until
325 after the Chart has been generated (ie. using the png() or
326 cgi_png() methods).
327 'sort'
329 In a xy-plot, the data will be sorted ascending if set to 'true'.
330 (Should be set if the data isn't sorted, especially in Lines, Split
331 and LinesPoints) In a Pareto Chart the data will be sorted
332 descending. Defaults to 'false'.
333 'composite_info'
335 This option is only used for composite charts. It contains the
336 information about which types to use for the two component charts,
337 and which datasets belong to which component chart. It should be a
338 reference to an array of array references, containing information
339 like the following
340 $obj->set ('composite_info' => [ ['Bars', [1,2]],
342 ['Lines', [3,4] ] ]);
343 This example would set the two component charts to be a bar chart
345 and a line chart. It would use the first two data sets for the bar
346 chart (note that the numbering starts at 1, not zero like most of
347 the other numbered things in Chart), and the second two data sets
348 for the line chart. The default is undef.
349 NB. Chart::Composite can only do two component charts.
351 'min_val1', 'min_val2'
353 Only for composite charts, these options specify the minimum
354 y-value for the first and second components respectively. Both
355 default to undef.
356 'max_val1', 'max_val2'
358 Only for composite charts, these options specify the maximum
359 y-value for the first and second components respectively. Both
360 default to undef.
361 'ylabel2'
363 The label for the right y-axis (the second component chart) on a
364 composite chart. Default is undef.
365 'y_ticks1', 'y_ticks2'
367 The number of y ticks to use on the first and second y-axis on a
368 composite chart. Please note that if you just set the 'y_ticks'
369 option, both axes will use that number of y ticks. Both default to
370 undef.
371 'f_y_ticks1', 'f_y_ticks2'
373 Only for composite charts, needs a reference to a function which
374 has one argument and has to return a string which labels the first
375 resp. second y axis. Both default to undef.
376 'same_y_axes'
378 Forces both component charts in a composite chart to use the same
379 maximum and minimum y-values if set to 'true'. This helps to keep
380 the composite charts from being too confusing. Default is undef.
381 'no_cache'
383 Adds Pragma: no-cache to the http header. Be careful with this
384 one, as Netscape 4.5 is unfriendly with POST using this method.
385 'legend_example_size'
387 Sets the length of the example line in the legend in pixels.
388 Defaults to 20.
389 'same_error'
391 This is a option only for ErrorBars. It tells chart that you want
392 use the same error value of a data point if set to 'true'. Look at
393 the documentation to see how the module ErrorBars works. Default:
394 'false'.
395 'skip_y_ticks'
397 Does the same for the y-axis at a HorizontalBars chart as
398 'skip_x_ticks' does for other charts. Defaults to 1.
399 'label_values'
401 Tells a pie chart what labels to draw beside the pie. Valid values
402 are 'percent', 'value', 'both' and 'none'. Defaults to 'percent'.
403 'legend_label_values'
405 Tells a pie chart what labels to draw in the legende. Valid values
406 are 'percent', 'value', 'both' and 'none'. Defaults to 'value'.
407 'start'
409 Required value for a split chart. Sets the start value of the first
410 interval. If the x coordinate of the first data point is zero, you
411 should 'set' to zero. Default is 'undef'.
412 'interval'
414 Also a required value for a split chart. It sets the interval of
415 one line to plot. Defaults 'undef'.
416 'interval_ticks'
418 Sets the number of ticks for the x-axis of a Split chart. Defaults
419 to 5.
420 'scale'
422 Every y-value of a split chart will be multiplied with that value,
423 but the scale won't change. Which means that split allows to
424 overdraw certain rows! Only useful if you want to give prominence
425 to the maximal amplitudes of the data. Defaults to 1.
426 'point'
428 Indicates to draw points in a direction chart. 'true' or 'false'
429 possible. Defaults to 'true'.
430 'line'
432 If you turn this optin to 'true', then direction will connect the
433 points with lines. Defaults to 'false'.
434 'arrow'
436 This is also an option for the direction module. If set to 'true',
437 chart will draw a arrow from the center to the point. Defaults to
438 'false'.
439 'angle_interval'
441 This option tells direction, how many angle lines should be drawn.
442 The default value is 30, which means that a line will be drawn
443 eyery 30 degrees. Valid Values are: 0, 5, 10, 15, 20, 30, 45 and
444 60. If you choose 0, direction will draw no line.
445 'min_circles'
447 Sets the minimum number of circles when generating a scale for
448 direction. Default is 4, minimum is 2.
449 'max_circles'
451 Sets the maximum number of circles when generating a scale for
452 direction. Default is 100. This limit is used to avoid plotting
453 an unreasonable large number of ticks if non-round values are used
454 for the min_val and max_val.
455 'pairs'
457 Only used for direction how to handle more datasets.
458 If 'pairs' is set to 'true',
459 Chart uses the first dataset as a set of degrees and
460 the second dataset as a set of values.
461 Then, the third set is a set of degrees und the
462 fourth a set of values \dots. \\
463 If 'pairs' is set to 'false',
464 Chart uses the first dataset as a set of angels
465 and all following datasets as sets of values.
466 Defaults to 'false'.
467 Sets the maximum number of circles when generating a scale for
469 direction. Default is 100. This limit is used to avoid plotting
470 an unreasonable large number of ticks if non-round values are used
471 for the min_val and max_val.
472 GIFgraph.pm-style API
474 Sending the image to a file
475 Invoking the png method causes the graph to be plotted and saved to
476 a file. It takes the name of the output file and a reference to
477 the data as arguments. For example,
478 $obj->png ("foo.png", \@data);
480 would plot the data in @data, and the save the image to foo.png.
482 Of course, this then beggars the question "What should @data look
483 like?". Well, just like GIFgraph, @data should contain references
484 to arrays of data, with the first array reference pointing to an
485 array of x-tick labels. For example,
486 @data = ( [ 'foo', 'bar', 'junk' ],
488 [ 30.2, 23.5, 92.1 ] );
489 would set up a graph with one dataset, and three data points in
491 that set. In general, the @data array should look something like
492 @data = ( \@x_tick_labels, \@dataset1, ... , \@dataset_n );
494 And no worries, I make my own internal copy of the data, so that it
496 doesn't mess with yours.
497 CGI and Chart
499 Okay, so you're probably thinking, "Do I always have to save these
500 images to disk? What if I want to use Chart to create dynamic
501 images for my web site?" Well, here's the answer to that.
502 $obj->cgi_png ( \@data );
504 The cgi_png method will print the chart, along with the appropriate
506 http header, to stdout, allowing you to call chart-generating
507 scripts directly from your html pages (ie. with a <lt>img
508 src=image.pl<gt> HTML tag). The @data array should be set up the
509 same way as for the normal png method.
510 Graph.pm-style API
512 You might ask, "But what if I just want to add a few points to the
513 graph, and then display it, without all those references to
514 references?". Well, friend, the solution is simple. Borrowing the
515 add_pt idea from Matt Kruse's Graph module, you simply make a few calls
516 to the add_pt method, like so:
517 $obj->add_pt ('foo', 30, 25);
519 $obj->add_pt ('bar', 16, 32);
520 Or, if you want to be able to add entire datasets, simply use the
522 add_dataset method:
523 $obj->add_dataset ('foo', 'bar');
525 $obj->add_dataset (30, 16);
526 $obj->add_dataset (25, 32);
527 These methods check to make sure that the points and datasets you are
529 adding are the same size as the ones already there. So, if you have
530 two datasets currently stored, and try to add a data point with three
531 different values, it will carp (per the Carp module) an error message.
532 Similarly, if you try to add a dataset with 4 data points, and all the
533 other datasets have 3 data points, it will carp an error message.
534 Don't forget, when using this API, that I treat the first dataset as a
536 series of x-tick labels. So, in the above examples, the graph would
537 have two x-ticks, labeled 'foo' and 'bar', each with two data points.
538 Pie and ErrorBars handle it different, look at the documentation to see
539 how it works.
540 Adding a datafile
542 You can also add a complete datafile to a chart object. Just use
543 the add_datafile() method.
544 $obj->add_datafile('file', 'set' or 'pt');
546 file can be the name of the data file or a filehandle. 'set' or
548 'pt is the type of the datafile. If the parameter is 'set' then
549 each line in the data file has to be a complete data set. The value
550 of the set has to be seperated by whitespaces. For example the file
551 looks like this:
552 'foo' 'bar'
554 30 16
555 25 32
556 If the parameter is 'pt', one line has to include all values of one
558 data point seperated by whitespaces. For example:
559 'foo' 30 25
561 'bar' 16 32
562 Clearing the data
564 A simple call to the clear_data method empties any values that may
565 have been entered.
566 $obj->clear_data ();
568 Getting a copy of the data
570 If you want a copy of the data that has been added so far, make a
571 call to the get_data method like so:
572 $dataref = $obj->get_data;
574 It returns (you guessed it!) a reference to an array of references
576 to datasets. So the x-tick labels would be stored as
577 @x_labels = @{$dataref->[0]};
579 Sending the image to a file
581 If you just want to print this chart to a file, all you have to do
582 is pass the name of the file to the png() method.
583 $obj->png ("foo.png");
585 Sending the image to a filehandle
587 If you want to do something else with the image, you can also pass
588 a filehandle (either a typeglob or a FileHandle object) to png, and
589 it will print directly to that.
590 $obj->png ($filehandle);
592 $obj->png (FILEHANDLE);
593 CGI and Chart
595 Okay, so you're probably thinking (again), "Do I always have to
596 save these images to disk? What if I want to use Chart to create
597 dynamic images for my web site?" Well, here's the answer to that.
598 $obj->cgi_png ();
600 The cgi_png method will print the chart, along with the appropriate
602 http header, to stdout, allowing you to call chart-generating
603 scripts directly from your html pages (ie. with a <lt>img
604 src=image.pl<gt> HTML tag).
605 Imagemap Support
607 Chart can also return the pixel positioning information so that you can
608 create image maps from the pngs Chart generates. Simply set the
609 'imagemap' option to 'true' before you generate the png, then call the
610 imagemap_dump() method afterwards to retrieve the information. You
611 will be returned a data structure almost identical to the @data array
612 described above to pass the data into Chart.
613 $imagemap_data = $obj->imagemap_dump ();
615 Instead of single data values, you will be passed references to arrays
617 of pixel information. For Bars, HorizontalBars and StackedBars charts,
618 the arrays will contain two x-y pairs (specifying the upper left and
619 lower right corner of the bar), like so
620 ( $x1, $y1, $x2, $y2 ) = @{ $imagemap_data->[$dataset][$datapoint] };
622 For Lines, Points, ErrorBars, Split and LinesPoints, the arrays will
624 contain a single x-y pair (specifying the center of the point), like so
625 ( $x, $y ) = @{ $imagemap_data->[$dataset][$datapoint] };
627 A few caveats apply here. First of all, GD treats the upper-left
629 corner of the png as the (0,0) point, so positive y values are measured
630 from the top of the png, not the bottom. Second, these values will
631 most likely contain long decimal values. GD, of course, has to
632 truncate these to single pixel values. Since I don't know how GD does
633 it, I can't truncate it the same way he does. In a worst-case
634 scenario, this will result in an error of one pixel on your imagemap.
635 If this is really an issue, your only option is to either experiment
636 with it, or to contact Lincoln Stein and ask him. Third, please
637 remember that the 0th dataset will be empty, since that's the place in
638 the @data array for the data point labels.
639
641 ยท Add some 3-D graphs. Include True Type Fonts
642
644 Probably quite a few, since it's been completely rewritten. As usual,
645 please mail me with any bugs, patches, suggestions, comments, flames,
646 death threats, etc.
647
649 David Bonner (dbonner@cs.bu.edu)
650
652 Chart Group (Chart@wettzell.ifag.de)
653
655 Copyright(c) 1997-1998 by David Bonner, 1999 by Peter Clark, 2001 by
656 the Chart group at BKG-Wettzell. All rights reserved. This program is
657 free software; you can redistribute it and/or modify it under the same
658 terms as Perl itself.
659perl v5.12.0 2003-12-04 Chart(3)