1Chart::Manual::Types(3)User Contributed Perl DocumentatioCnhart::Manual::Types(3)
2
6 Chart::Manual::Types - all chart types by example
7
9 This page illustrates all supported chart types, describes their
10 special abilities and programming needs. Detailled information is
11 linked whenever possible.
12 Currently available are xycharts with points, lines, mountains, bar
14 charts, stacked bars, error bars, pie and ring charts with split and
15 polar coordinate systems. Also composite charts are possible.
16 Generally, each chart type here is implementd by a class: Chart::*
18 (name), which inherits most of its methods from Chart::Base. Every
19 constructor takes two arguments, which are width and height of the
20 later generated image.
21 Bars
23 The class Chart::Bars creates a chart made up of a series of vertical
24 bars. The length of each bar depicts one value of your second data
25 set. The first data set however, defines the domain. In this example
26 the first value of the first (domain) data set is 'camel'. So the first
27 value of the second set (300) is positioned above the first tick on the
28 x-axis labeled 'camel'. Right beside it is a differently colored bar,
29 depticting the first value of the third data set (800). Since the
30 option spaced_bars is set to 'true' on default, both bars are separated
31 from the next group of bars. In this example it also makes also sense
32 to activate the horizontal y_grid_lines and give them a subtle color.
33 Further important was it to set the property min_val to zero, so that
34 the bars could be seen in full length and not from the min value of the
35 data sets (300) on upwards. precision set to zero just drops the
36 decimals on the tick label so the chart looks a little cleaner. All the
37 the other color set serv the same purpose.
38 use Chart::Bars;
40 my $g = Chart::Bars->new( 500, 300 );
42 $g->add_dataset( qw/ camel cat dog bear shell/ );
43 $g->add_dataset( 300, 400, 800, 500, 900 );
44 $g->add_dataset( 800, 600, 300, 300, 400 );
45 $g->set(
47 title => 'Bars !',
48 x_label => 'Group',
49 y_label => 'Value',
50 y_grid_lines => 'true',
51 colors => {
52 y_grid_lines => 'gray70',
53 misc => 'gray55',
54 text => 'gray55',
55 x_label => 'gray40',
56 y_label => 'gray40',
57 title => 'gray20',
58 },
59 min_val => 0,
60 precision => 0,
61 # spaced_bars => 'false',
62 );
63 $g->png("bars.png");
64 Composite
66 The class Chart::Composite creates a two component chart with two types
67 of charts which are layered one above each other. Just set the option
68 composite info. For example, you can create a two component chart with
69 bars and lines. A composite chart does not make sense with all
70 combinations of chart types, but it works pretty good with Lines,
71 Points, LinesPoints and Bars. Note that two similar chart types may
72 come into visual conflict. Chart::Composite can do only composite
73 charts made up of two components.
74 In this example are the data sets one and two displayed as "Bars" and
76 the next two als "LinesPoints" as set by the property composite_info.
77 Please read these sections too. Otherwise we only colored the last data
78 set for better contrast und cut the decimals from the axis labels via
79 precision.
80 use Chart::Composite;
82 my $g = Chart::Composite->new( );
84 $g->add_dataset( 1, 2, 3 );
85 $g->add_dataset( 10, 20, 30 );
86 $g->add_dataset( 15, 25, 32 );
87 $g->add_dataset( 7, 24, 23 );
88 $g->add_dataset( 5.1, 7.5, 9.9 );
89 $g->set(
90 title => 'Composite Chart',
91 composite_info => [ [ 'Bars', [ 1, 2 ] ],
92 [ 'LinesPoints', [ 3, 4 ] ] ],
93 include_zero => 'true',
94 precision => 0,
95 colors => {
96 dataset3 => 'darkorange',
97 }
98 );
99 $g->png("composite.png");
100 Direction
102 The class Chart::Direction creates a diagram based on polar
103 coordinates. This type of diagram is occasionally referred to as a
104 radial or as a radar chart, which has a circle as x-axis and its values
105 define an angle. The y-value in the center is min_value and the most
106 outer circle is at max_value. In order to reverse that you have to set
107 polar 'true'. In our example we preferred to have a real comparison
108 between arrow lengths so we artificially put zero as "min_value" by
109 setting include_zero 'true'. The just mentioned arrow style we achieved
110 by deactivating point (drawing small circles) and turning on arrow. An
111 additional 'true' line would connect the points (arrow heads) with
112 lines (as well as the first and last). As in \Lines and \Points:
113 pt_size defines the point size and brush_size the line thickness.
114 Usually the background of each chart (just inside the coordinate
115 system) is a light gray - here deactivated. Radial grid lines are drawn
116 every 45 degrees (angle_interval).
117 As with most chart types, the first data set defines the domain : the
119 x-values of all following data sets, which then define the associated
120 y-values (and therefore all sets have to have the same length).
121 Because we set in this example pairs 'true', now every odd numbered
122 data set is the domain for the next set. But they still all sets have
123 to have the same length.
124 use Chart::Direction;
126 my $g = Chart::Direction->new( 500, 500 );
128 $g->add_dataset( 210, 220, 200, 215, 225, 200 );
130 $g->add_dataset( 30, 40, 20, 35, 45, 20 );
131 $g->add_dataset( 30, 40, 20, 35, 45, 20 );
133 $g->add_dataset( 30, 40, 20, 35, 45, 20 );
134 $g->add_dataset( 120, 130, 110, 125, 135, 110 );
136 $g->add_dataset( 30, 40, 20, 35, 45, 20 );
137 $g->add_dataset( 300, 310, 290, 305, 315, 290 );
139 $g->add_dataset( 30, 40, 20, 35, 45, 20 );
140 $g->set(
142 title => 'Direction Demo',
143 angle_interval => 45,
144 precision => 0,
145 arrow => 'true',
146 point => 'false',
147 include_zero => 'true',
148 legend => 'none',
149 grey_background => 'false',
150 pairs => 'true',
151 );
152 $g->png("direction.png");
153 ErrorBars
155 The class Chart::ErrorBars creates a point chart with error bars, which
156 are vertical lines, depicting the uncertainty - a range which is
157 possible for that value. As seen in the example, we need four data sets
158 to define a series of error bars. The first data set are the x-values
159 of the error bars, the second the y-values. The third set holds the
160 lenght of the upper part of the error bar and the fourth set the lower
161 part (distance between main point and the lower bound of the error
162 bar). The fourth set might be omitted, when property same_error is set
163 'true'. In this case upper and lower part of the error bar have the
164 same size. Because all this produced only one set of error bars with
165 one color, there is no need for a legend. That is why it is switched
166 off by setting property legend to 'none'. The label on the x-axis are
167 painted in the 'staggered' style, so they don't overlap. pt_size refers
168 to the diameter in pixel of the errors bars central point. brush_size
169 is the thickness of the bar. For better readability 'both' y_axes were
170 labeled.
171 use Chart::ErrorBars;
173 my $g = Chart::ErrorBars->new();
175 $g->add_dataset(qw(1 1.1 1.2 1.3 1.4 1.5 1.6 1.7 1.8 1.9 2 2.1 2.2 2.3 2.4 2.5));
176 $g->add_dataset(qw(1 1.1 1.2 1.1 1.14 1.15 1.26 1.2 1.1 1.19 1.2 1.4 1.6 2.0 2.5 3.1));
177 $g->add_dataset(qw(0.4 0.1 0.2 0.1 0.14 0.15 0.26 0.27 0.1 0.19 0.2 0.1 0.1 0.2 0.1 0.3));
178 $g->add_dataset(qw(0.2 0.11 0.12 0.11 0.2 0.3 0.12 0.27 0.11 0.3 0.2 0.2 0.2 0.1 0.1 0.2));
179 $g->set(
180 title => 'Error Bars Demo',
181 legend => 'none',
182 y_axes => 'both',
183 x_ticks => 'staggered',
184 pt_size => 12,
185 brush_size => 2,
186 grid_lines => 'true',
187 colors => {
188 grid_lines => 'gray70',
189 misc => 'gray65',
190 },
191 );
192 $g->png("error.png");
193 HorizontalBars
195 The class Chart::HorizontalBars creates a chart of horizontally
196 oriented bars. Same rules apply as in "Bars", except due negative
197 values in our data sets here min_val doesn't have to be set to zero.
198 And instead of y_grid_lines we activate and color x_grid_lines.
199 Deactivating the grey background of the plot just adds a little
200 friendliness.
201 use Chart::HorizontalBars;
203 my $g = Chart::HorizontalBars->new( 600, 600 );
205 $g->add_dataset( qw/ camel cat dog bear shell/ );
206 $g->add_dataset( -300, 400, 800, -500, 200 );
207 $g->add_dataset( 800, -600, 300, 300, 400 );
208 $g->set(
209 title => 'Bars !',
210 x_label => 'Group',
211 y_label => 'Value',
212 x_grid_lines => 'true',
213 precision => 0,
214 colors => {
215 x_grid_lines => 'gray70',
216 misc => 'gray55',
217 text => 'gray55',
218 x_label => 'gray40',
219 y_label => 'gray40',
220 title => 'gray20',
221 }
222 grey_background => 'false',
223 );
224 $g->png("hbars.png");
225
227 The class Chart::Lines creates a chart with lines that connect the
228 would be data points. If you want to make the points more visible, use
229 "LinesPoints". The only special property is brush_size, the thickness
230 of the lines, which was not even utilized in this example. To make
231 things nicer we put only some softer colors to the horizontal (y) grid
232 lines and the box and ticks (misc) and placed the legend on the bottom
233 so that the chart doesn't get sqeezed by it.
234 use Chart::Lines;
236 my $g = Chart::Lines->new( 600, 400 );
238 $g->add_dataset( 'foo', 'bar', 'whee', 'ding', 'bat', 'bit' );
239 $g->add_dataset( 3.2, 4.34, 9.456, 10.459, 11.24234, 14.0234 );
240 $g->add_dataset( -1.3, 8.4, 5.34, 3.234, 4.33, 13.09 );
241 $g->add_dataset( 5, 7, 2, 10, 12, 2.3445 );
242 $g->set(
243 title => 'Lines Chart',
244 legend => 'bottom' ,
245 y_label => 'y label 1',
246 precision => 0,
247 y_grid_lines => 'true',
248 colors => {
249 y_label => 'orangepeel',
250 y_grid_lines => [ 190, 190, 190 ],
251 misc => [ 100, 100, 100 ],
252 },
253 );
254 $g->png("lines.png");
255 LinesPoints
257 The class Chart::LinesPoints creates chart, which is a combination of
258 "Points" and "Lines": shaped symbols connected by lines. This requires
259 a combination of the special properties of both chart types: brushStyle
260 (point shape), pt_size (point diameter) and brush_size (line
261 thickness).
262 In our example we named both axis via x_label and y_label and set
264 xy_plot off, which is not really needed, since it is on 'false' per
265 default. This allows you to give the x-axis none numerical, custom
266 tick labels, which are by accident the numbers 1 .. 17, as the first
267 data row shows. The purpose of this maneuver is to not have zero as
268 the first column label.
269 Because the origin of coordinate system is usually in the left lower
271 corner, we used a trick to flip the y-axis having the smallest values
272 up. We negated all values in the data, so that 8 is lower than 2,
273 because -8 is smaller than -2. Than we transformed the y-axis labels
274 with a function, that negates the value of the original label, erasing
275 the minus sign.
276 For additional clarity, we put the names of the teams into the legend,
278 which is per default on the right side. And to make the code more
279 compact, we packed the first (just labels) and the four real data sets
280 (rows) together into an array or arrays and gave it as second argument
281 directly to the drawing method.
282 use Chart::LinesPoints;
284 my $g = Chart::LinesPoints->new( 600, 300 );
286 $g->set(
287 title => 'Soccer Season 2002',
288 legend_labels => ['NY Soccer Club', 'Denver Tigers',
289 'Houston Spacecats', 'Washington Presidents'],
290 y_label => 'position in the table',
291 x_label => 'day of play',
292 grid_lines => 'true',
293 f_y_tick => sub { - $_[0] },
294 # xy_plot => 'true',
295 integer_ticks_only => 'true',
296 colors => {
297 grid_lines => 'gray70',
298 },
299 );
300 $g->png("linespoints.png", [
301 [qw(1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17)],
302 [qw(-7 -5 -6 -8 -9 -7 -5 -4 -3 -2 -4 -6 -3 -5 -3 -4 -6)],
303 [qw(-1 -1 -1 -1 -2 -2 -3 -3 -4 -4 -6 -3 -2 -2 -2 -1 -1)],
304 [qw(-4 -4 -3 -2 -1 -1 -1 -2 -1 -1 -3 -2 -4 -3 -4 -2 -2)],
305 [qw(-6 -3 -2 -3 -3 -3 -2 -1 -2 -3 -1 -1 -1 -1 -1 -3 -3)],
306 ]);
307 Mountain
309 The class Chart::Mountain creates a mountain chart, which is a line
310 chart (see "Lines"), where the area under the curve, right to the curve
311 below is filled with the color of the data set. In the following
312 example we use custom colors in hex notation (as supported by
313 Chart::Color) which are getting mapped onto the colors settings of
314 dataset0 .. dataset4. As always, the first data set (row in the data
315 table) holds the domain or x-axis labels. Another specialty of mountain
316 charts are patterns (not provided !), to fill the area with. We load
317 them via GD and give them over to the 'patterns' property. Patterns are
318 small images with one color and the second being transparent.
319 use Chart::Mountain;
321 my @data = (
323 ["1st", "2nd", "3rd", "4th", "5th", "6th", "7th", "8th", "9th" ],
324 [ 3, 7, 8, 2, 4 , 8.5, 2, 5, 9],
325 [ 4, 2, 5, 6, 3 , 2.5, 3, 3, 4],
326 [ 7, 3, 2, 8, 8.5, 2 , 9, 4, 5],
327 );
328 my @hex_colors = ('#0099FF', '#00CC00', '#EEAA00', '#FF0099','#3333FF');
329 my $PNG;
330 my @patterns = map {
331 open( $PNG, '<', "./patterns/PATTERN$_.PNG" ) or die "Can't load pattern $_";
332 GD::Image->newFromPng( $PNG );
333 } 0 .. 4;
334 my $g = new Chart::Mountain( 500, 300);
336 $g->set(
337 title => 'Mountain Chart with Patterns',
338 x_label => 'Lengths',
339 y_label => 'Height',
340 grid_lines => 'true',
341 patterns => \@patterns,
342 precision => 1,
343 colors => {
344 grid_lines => 'gray70',
345 misc => 'gray55',
346 map { ( "dataset$_" => $hex_colors[$_] ) } 0 .. $#hex_colors,
347 },
348 );
349 $g->png( 'mountain.png', \@data );
350 Pareto
352 The class Chart::Pareto creates a combination of a "Bars" and a "Lines"
353 chart. The bars display absolute values of the data set (Pareto accepts
354 only one), while the line represent the accumulation (sum of all values
355 from the start on the left up to this value). For a better orientation
356 the absolute values should be sorted. In case your data set is not
357 already, change the property sort to 'true'. (Note that the days of
358 the week are not in chronological order, but in the order of decreasing
359 sale amounts.) The first given data set is like in most cases the
360 domain (x-axis labels). So the color of the first data set containing
361 numbers has the color of dataset0 and the accumulation gets the color
362 of dataset1 (which are per default also red and green, but in reverse
363 order). We choose a Pantone Report designer red, which sticks out but
364 is not too shrill.
365 For better optics we set spaced_bars off, so that the bars touch each
367 other and give a nice counterweight to the red color of the line. It's
368 also a bit nicer, when the red labels above the red line don't stick
369 out the chart, so we increased the max_val from 5180 to 5500. Finally
370 to prevent the y-axis from overcrowding, we set labels (and
371 y_grid_lines) only every 250 by setting skip_int_ticks and activating
372 integer_ticks_only.
373 use Chart::Pareto;
375 my $g = Chart::Pareto->new( 450, 400 );
377 $g->add_dataset( 'Mo', 'Tue', 'We', 'Th', 'Fr', 'Sa', 'Su' );
378 $g->add_dataset( 2500, 1000, 250, 700, 100, 610, 20 );
379 $g->set(
380 title => 'Sold Tickets for Beethovens 9th',
381 y_label => 'Sold Tickets',
382 x_label => '! sold out in the first week !',
383 sort => 'true',
384 max_val => 5500,
385 integer_ticks_only => 'true',
386 skip_int_ticks => 250,
387 y_grid_lines => 'true',
388 spaced_bars => 'false',
389 legend => 'none',
390 colors => {
391 title => 'darkblue',
392 dataset0 => 'green',
393 dataset1 => 'aurorared',
394 x_label => 'aurorared',
395 y_grid_lines => 'white',
396 },
397 );
398 $g->png("pareto.png");
399 Pie
401 The class Chart::Pie creates a pie or ring chart. The first added data
402 set must contain the labels and the second set the values. Our example
403 displays a ring chart with a thickness of 35% (of the radius). If the
404 ring property is omitted, the chart form falls back to regular pie.
405 Every ring slice is labeled with the stated label, plus the percentage
406 of its value, as defined with the property label_values. Connecting
407 lines between label and slice are drawn because legend_lines is set to
408 'true'. The actual legend is placed on the bottom, in order to leave
409 the ring as large as possible. The legend again shows the association
410 between color and data point and its value because legend_label_values
411 is set to 'values'. Unlike other chart types, where one data set is
412 correlated with a color, here every slice has to have its own color.
413 Thats why the first data point has the color of dataset0 the second of
414 dataset1 and so forth. In most cases the default colors are good
415 enough, unless you have special meanings in mind. Please also note the
416 multi line (row) title text.
417 use Chart::Pie;
419 my $g = Chart::Pie->new( 500, 450 );
421 $g->add_dataset( qw/eins zwei drei vier fuenf sechs sieben acht neun zehn/ );
422 $g->add_dataset( 120, 50, 100, 80, 40, 45, 150, 60, 110, 50 );
423 $g->set( 'title' => 'Pie\nDemo Chart',
424 'legend' => 'bottom',
425 'legend_label_values' => 'value',
426 'label_values' => 'percent',
427 'legend_lines' => 'true',
428 'ring' => 0.35,
429 );
430 $g->png("pie.png");
431 Points
433 The class Chart::Points creates a xy-chart (also called scattergram),
434 where the individual data points are marked with a symbol. The shape
435 of the symbol is selected by the property brushStyle, which was not
436 utilized in this example, in order to use the default shape: a circle
437 of a diameter set by pt_size. All shapes can be seen in the demo
438 above, right. (If you want in addition lines, connecting the points,
439 check "LinesPoints".)
440 The first data set comprises the domain set, displayed on the x-axis.
442 precision set to zero cuts the decimals on the y-axis labels and keeps
443 it clean. The method "add_pt" appends to every data set another value,
444 adding another column to the chart. png_border does just adds frame of
445 10 pixel width around the entire image. They middle gray grid lines are
446 just easy for the eyes.
447 use Chart::Points;
449 my $g = Chart::Points->new();
451 $g->add_dataset( 'foo', 'bar', 'blank' );
452 $g->add_dataset( 3, 4, 9 );
453 $g->add_dataset( 8, 6, 0 );
454 $g->add_dataset( 5, 7, 2 );
455 $g->add_pt( 'dat', 1, 5, 7 );
456 $g->set(
457 title => 'Points Chart',
458 pt_size => 18,
459 # brushStyle => 'Star',
460 precision => 0,
461 grid_lines => 'true',
462 png_border => 10,
463 colors => {
464 grid_lines => 'gray70',
465 },
467 );
468 $g->png("points.png");
469 Split
471 The class Chart::Split creates a "Lines" chart where both x and y axes
472 are assumed to be numeric. Split charts are mainly intended for cases
473 where many data points are spread over a wide x range while at the same
474 time the y range is limited. Typical examples are weather or seismic
475 data. The x axis will be split into several intervals of the same
476 length (specified with the mandatory option interval and starting at
477 start). Chart::Split will draw only positive x coordinates. The y axis
478 will not be labelled with the y values. Rather, the axis will show only
479 the sequence numbers of the intervals.
480 use Chart::Split;
482 my $g = Chart::Split->new( 500, 500 );
484 my @domain = 1 .. 4000;
486 my @rnd = map { srand( time() / $_ * 50 ); rand(10) } @domain, 4001;
487 my @diff = map { abs $rnd[$_-1] - $rnd[$_] } @domain;
488 pop @rnd;
489 $g->add_dataset(@domain);
491 $g->add_dataset(@rnd);
492 $g->add_dataset(@diff);
493 $g->set(
494 title => "Random Numbers Test",
495 x_label => "4000 Random Numbers",
496 start => 0,
497 interval => 400,
498 brush_size => 1,
499 interval_ticks => 0,
500 legend => 'bottom',
501 legend_labels => ['random numbers', 'difference' ],
502 colors => {
503 title => 'darkblue',
504 text => 'gray45',
505 misc => 'gray45',
506 },
507 );
508 $g->png("split.png");
509 StackedBars
511 The class Chart::StackedBars is a variant of "Bars" that stacks bars
512 belonging to one x-value on top of each other, instead of putting them
513 beside each other. Data sets 0..n are ordered from the bottom up. They
514 are in most cases more intuitive than "Pie" charts, because its easier
515 to intuit linear than quadratic ratios. As in the Bars example we
516 activated horizontal grid lines, which were subtle colored. To surpress
517 decimals on the y-axis precision was turned down. And as in most cases
518 - the first data set is the domain, which will be drawn as x-axis
519 labels.
520 use Chart::StackedBars;
522 my $g = Chart::StackedBars->new( 600, 400 );
524 $g->add_dataset( 'camel', 'dromedar', 'llama', 'vicuna');
525 $g->add_dataset( 3, 4, 9, 10, );
526 $g->add_dataset( 8, 6, 1, 12, );
527 $g->add_dataset( 5, 7, 2, 13, );
528 $g->set(
529 title => 'Stacked Bars',
530 legend => 'left',
531 precision => 0,
532 y_grid_lines => 'true',
533 grey_background => 'false',
534 colors => {
535 grid_lines => 'gray80',
536 misc => 'gray55',
537 text => 'gray55',
538 x_label => 'gray40',
539 y_label => 'gray40',
540 title => 'gray20',
541 }
542 );
543 $g->png("stackedbars.png");
544
546 Copyright 2022 David Bonner, Herbert Breunung.
547 This program is free software; you can redistribute it and/or modify it
549 under same terms as Perl itself.
550
552 David Bonner, <chartgrp@web.de>
553 Herbert Breunung, <lichtkind@cpan.org>
555perl v5.36.0 2022-08-01 Chart::Manual::Types(3)