Chart
view release on metacpan or search on metacpan
lib/Chart/Manual/Properties.pod view on Meta::CPAN
=for HTML <p>
<img src="https://raw.githubusercontent.com/lichtkind/Chart/main/dev/example/manual/layout.png" alt="layout">
</p>
=head1 DATA TYPES
Every key expects values of a certain data type. The more often occurring
types are sorted, enumerated and decibed in this section.
=head2 boolean
Yes or no decisions you can answer with the perlish C<0> or C<1> as well
as with C<'true'> or C<'false'>, which might be shortened to C<'t'> and C<'T'>
or C<'f'> and C<'F'>. C<'none'> as an alias of C<'false'> is also an option.
=head2 code
Anonymous subroutine that usually takes the first argument and returns
a transformed result:
sub { $_[0] + 1 }
=head2 color
The usual options are:
names: 'blue'
All names are tabulated visually and by name under L<Chart::Property::DataType::Color::Constant/NAMES>.
You can also define a color with integer values in the RGB or HSL space.
Acceptable ranges are for RGB: 3x 0..255 and for HSL: 0..359, 2 x 0..100.
RGB triplets: [0,255,255]
RGB hashes: { Red => 0, Green => 255, Blue => 255 }
RGB hashes: { R => 0, G => 255, B => 255 }
HSL hashes: { H => 240, S => 100, L => 50 }
HSL hashes: { hue => 240, saturation => 100, lightness => 50 }
Detailed explanation and even more options you find under L<Graphics::Toolkit::Color>.
=head2 font
There are a handful GD built in font object, than can be referenced:
GD::Font->Tiny
GD::Font->Small
GD::Font->MediumBold
GD::Font->Large
GD::Font->Giant
=head2 integer
Whole numbers (without decimals) to set position, size and alike.
=head2 positive integer
Integers greater or equal zero.
=head2 string
Short texts for title, sub_title and labels on axis, tics and legend.
Line breaks (C</n>) are only acceptable inside single quotes and in the
L</title>.
=head1 BY CHART TYPE
Summary of all properties, grouped by chart type where there applicable.
Sections are named after the Chart type in question, except B<All> and B<NoPie>.
The format is: name ... L<type|/"DATA TYPES">, description; C<default value>.
Click on name for a longer explanation.
=head2 All
Properties available in all chart types:
L<colors-background|/colors> ... L</color> of whole image background ; C<'white'>
L<colors-datasetx|/colors> ..... L</color> of points/lines/bars of dataset number x = 0..64
L<colors-grid_lines|/colors> ... L</color> of vertical and horizontal grid lines in the plot background; C<'black'>
L<colors-x_grid_lines|/colors> . L</color> of vertical grid lines; C<'black'>
L<colors-y_grid_lines|/colors> . L</color> of horizontal grid lines; C<'black'>
L<colors-text|/colors> ......... L</color> of all text ; C<'black'>
L<colors-title|/colors> ........ L</color> of text above the graph ; C<'black'>
L<colors-x_label|/colors> ...... L</color> of x-axis label text; C<'black'>
L<colors-y_label|/colors> ...... L</color> of y-axis (left side) label text; C<'black'>
L<colors-y_label2|/colors> .... L</color> of y-axis (right side) label text; C<'black'>
L<colors-misc|/colors> ....... L</color> of boxes, ticks, axis and alike; C<'black'>
L</f_x_tick> ................ L</code> that transforms "would have" into actual tick label on left x-axis; C<undef>
L</f_y_tick> ............... L</code> that transforms "would have" into actual tick label on right y-axis; C<undef>
L</graph_border> .......... space between graph and title + legend in pixel; C<10>
L</grey_background> ...... L<bool|/boolean>: sets plot background to grey; C<'true'>
L</imagemap> ............ L<bool|/boolean>: enable imagemap_dump(); C<'false'>
L</label_font> .......... L</font> of axis labels; GD::Font->MediumBold
L</legend> .............. qw[left right top bottom none]: placement of the legend; C<'right'>
L</legend_font> ......... L</font> of the text in the legend; GD::Font->Small.
L</legend_labels> ....... (array ref): labels of colors in legend; C<undef>
L</png_border> .......... L<pos_int|/"positive integer">: space between graph parts and image edge in pixel; C<10>
L</sub_title> ........... L</string>: text below the L</title> in smaller letters; C<''>
L</text_space> .......... L<pos_int|/"positive integer">: extra space around any text; C<2>
L</title> ............... L</string>: text on top of a chart; C<''>
L</title_font> .......... L</font> of the title text; GD::Font->Large
L</transparent> ......... L<bool|/boolean>: full image background transparency; C<'false'>
L</x_label> ............. L</string>: x-axis label text; C<''>
L</y_label> ............. L</string>:label on the standard, left y-axis; C<''>
L</y_label2> ............ L</string>:label on right y-axis, if different; C<''>
=head2 NoPie
Properties available in all chart types of kinda xy-plot, not L</Pie>:
L</custom_x_ticks> ..... (array ref): [0,3,4] displays 0th, 3rd, and 4th x-tick; C<undef>
L</grid_lines> ......... L<bool|/boolean>: draw vertical and horizontal grid lines; C<'false'>
L</include_zero> ....... L<bool|/boolean>: forces y-axis to include zero; C<'false'>
L</integer_ticks_only> . L<bool|/boolean>: draw x-axis ticks with label only on whole values; C<'false'>
L</max_val> ............ L<pos_int|/"positive integer">: maximum value on y-axis; C<undef>
L</max_x_ticks> ........ L<pos_int|/"positive integer">: maximum of ticks and labels to draw on x-axis; C<100>
L</max_y_ticks> ........ L<pos_int|/"positive integer">: maximum of ticks and labels to draw on y-axis; C<100>
L</min_val> ............ L<pos_int|/"positive integer">: maximum value on y-axis; C<undef>
L</min_x_ticks> ........ L<pos_int|/"positive integer">: minimum of ticks and labels to draw on x-axis; C<6> (min 2)
L</min_y_ticks> ........ L<pos_int|/"positive integer">: minimum of ticks and labels to draw on y-axis; C<6> (min 2)
L</precision> .......... L<pos_int|/"positive integer">: nr. of numerals after the decimal point in axis labels; C<3>
L</skip_int_ticks> ..... L<pos_int|/"positive integer">: draw only n'th tick on whole x-value; C<1> (if L</integer_ticks_only>)
L</skip_x_ticks> ....... L<pos_int|/"positive integer">: draw only every n'th tick with label; C<1>
L</sort> ............... L<bool|/boolean>: sort data in ascending order; C<'false'>
L</tick_label_font> .... L</font> of tick labels; GD::Font->Small
L</tick_len> ........... L<pos_int|/"positive integer">: length of the x- and y-ticks in pixels; C<4>
L</x_grid_lines> ....... L<bool|/boolean>: vertical grid lines matching x ticks; C<'false'>
L</x_ticks> ............ qw[normal staggered vertical]: style of x-axis labels; C<'normal'>
L</xy_plot> ............ L<bool|/boolean>: forces x-y-graph, with numeric x-axis; C<'false'>
L</y_axes> ............. (C<'left'>, C<'right'>, C<'both'>): position of y-axis;C<'left'>
L</y_grid_lines> ....... L<bool|/boolean>: horizontal grid lines matching y ticks; C<'false'>
=head2 Bars
This includes Bars StackedBars and HorizontalBars.
L</spaced_bars> ........ L<bool|/boolean>: leave space between the groups of bars; C<'true'>
=head2 HorizontalBars
L</skip_y_ticks> ....... L<pos_int|/"positive integer">: draw every n'th tick with label on y-axis; C<1>
=head2 Composite
L</brush_style1> ....... brush style of points associated with left y-axis; C<undef>
L</brush_style2> ....... brush style of points associated with right y-axis; C<undef>
L</composite_info> ..... (array of arrays) which data sets produce which chart types; C<undef>
L</f_y_tick1> .......... L</code> that transforms "would have" into actual label on left y-axis; C<undef>
L</f_y_tick2> .......... L</code> that transforms "would have" into actual label on right y-axis; C<undef>
L</legend_example_size> Length of the color example line in legend in pixel; C<20>
L</max_val1> ........... L</code> maximum y value on the left axis; C<undef>
L</max_val2> ........... L</code> maximum y value on the right axis; C<undef>
L</min_val1> ........... L</code> minimum y value on the left axis; C<undef>
L</min_val2> ........... L</code> minimum y value on the right axis; C<undef>
L</same_y_axes> ........ L</code> both y-axis have same min and max; C<undef>
L</y_ticks1> ........... L<pos_int|/"positive integer">: number of y ticks on left y-axis; C<undef>
L</y_ticks2> ........... L<pos_int|/"positive integer">: number of y ticks on right y-axis; C<undef>
=head2 Direction
L</angle_interval> ..... L<pos_int|/"positive integer">: angle between radial lines; C<30>
L</arrow> .............. L<bool|/boolean>: paint points as arrows; C<'false'>
L</brush_size> ......... L<pos_int|/"positive integer">: width of the lines in pixels; C<6>
L</line> ............... L<bool|/boolean>: connected points with lines; C<'false'>
L</max_circles> ........ L<pos_int|/"positive integer">: max nr. of coordinate grid circles; C<100>
L</min_circles> ........ L<pos_int|/"positive integer">: min nr. of coordinate grid circles; C<4> (min. 2)
L</pair> ............... L<bool|/boolean>: use odd numbered data sets to build pairs with the next; C<'false'>
L</point> .............. L<bool|/boolean>: paint points at all (or only lines); C<'false'>
L</polar> .............. L<bool|/boolean>: reverse x axis; C<'false'>
L</pt_size> ............ L<pos_int|/"positive integer">: radius of points in pixels; C<18>
=head2 ErrorBars
L</brush_size> ......... L<pos_int|/"positive integer">: width of the lines in pixels; C<6>
L</pt_size> ............ L<pos_int|/"positive integer">: radius of points in pixels; C<18>
L</same_error> ......... L<bool|/boolean>: same values for upper and lower error bounds; C<'false'>
=head2 Lines
including chart type LinesPoints
L</brush_size> ......... L<pos_int|/"positive integer">: width of the lines in pixels; C<6>
=head2 Points
including chart type LinesPoints
L</brushStyle> ......... shape of the points; C<'FilledCircle'>
L</pt_size> ............ L<pos_int|/"positive integer">: radius of points in pixels; C<18>
=head2 Pie
L</label_values> ....... qw[percent value both none]: label content on pie slice label; C<'percent'>
L</legend_label_values> qw[percent value both none]: label content in the legend; C<'value'>
L</legend_lines> ....... L<bool|/boolean>: draw lines connecting pie slices and label; C<'false'>
L</ring> ............... L</real>: percentage of visible radius; C<1> (full pie)
=head2 Split
L</interval> ........... L<pos_int|/"positive integer">: interval of a plot segment; C<'undef'>
L</interval_ticks> ..... L<pos_int|/"positive integer">: number of ticks on x-axis; C<5>
L</scale> .............. L</integer>: factor for y-values; C<1>
L</start> .............. L</integer>: start value of the first interval; C<'undef'>
=head1 ALPHABETICALLY
=head2 angle_interval
L</Direction> only: how many radial lines should be drawn.
The default value is 30, which means that a line will be drawn every
30 degrees. Valid Values are: 0, 5, 10, 15, 20, 30, 45 and 60.
If you choose 0, direction will draw no line.
=head2 arrow
L</Direction> only: L<Bool|/boolean> that if C<'true'>, chart will draw a
arrow from the center to the point. Defaults to C<'false'>.
=head2 brush_size
L</Lines> only: Integer sets the width of the lines in pixels. Default is 6.
=head2 background
see L</colors>
=head2 brushStyle
Sets the shape of points for Chart::Points, Chart::LinesPoints.
Possible values are: 'FilledCircle', 'circle', 'donut', 'OpenCircle',
'fatPlus', 'triangle', 'upsidedownTriangle', 'square', 'hollowSquare',
'OpenRectangle', 'FilledDiamond', 'OpenDiamond', 'Star', 'OpenStar'.
Default: 'FilledCircle'. Look at Demo at L<Chart::Manual::Types/Points>.
=head2 brush_style1
L</Composite> only: brush style of points associated with left y-axis.
=head2 brush_style2
L</Composite> only: brush style of points associated with right y-axis.
=head2 colors
The key C<colors> is special, because there are a lot of things that
need to be colored. That's why its value is a hash with keys within,
which name what exactly needs to be colored. Their value has to be a
L<color> definition (name, RGB array ref or HSL hash ref):
$obj->set('colors' => {'background' => [255,255,255]});
sets the background color to white (which is the default). Valid keys are:
'background' (background color for the image)
'title' (color of the title)
'text' (all the text in the chart)
'x_label' (color of the x-axis label)
'y_label' (color of the first y axis label)
'y_label2' (color of the second y axis label)
'grid_lines' (color of the grid lines)
'x_grid_lines' (color of the x grid lines - for x axis ticks)
'y_grid_lines' (color of the y grid lines - for to left y axis ticks)
'y2_grid_lines' (color of the y2 grid lines - for right y axis ticks)
'dataset0'..'dataset63' (the different datasets)
'misc' (everything else, ie. axis, ticks, box around the legend)
NB. For composite charts, there is a limit of 8 datasets per component.
The colors for 'dataset8' through 'dataset15' become the colors
for 'dataset0' through 'dataset7' for the second component chart.
=head2 composite_info
L</Composite> only: information about which data set gets visualized by
which chart type. It should be a reference to an array of array references,
containing information like the following:
$obj->set ('composite_info' => [ ['Bars', [1,2]],
['Lines', [3,4] ] ]);
This example would set the two component charts to be a bar chart and
a line chart. It would use the first two data sets for the bar
chart (note that the numbering starts at 1, not zero like most of
the other numbered things in Chart), and the second two data sets
for the line chart. The default is undef.
NB. Chart::Composite can only do two component charts.
=head2 custom_x_ticks
Used in L</Points>, L</Lines>, L</Linespoints>, L</Errorbars>, and
L</Bars> charts. This option allows you to you to specify exactly which
x-ticks and x-tick labels should be drawn. It should be assigned a
reference to an array of desired ticks. Just remember that I'm counting
from the 0th element of the array. (ie., if 'custom_x_ticks' is assigned
[0,3,4], then the 0th, 3rd, and 4th x-ticks will be displayed)
=head2 datasetx
see L</colors>
=head2 f_x_tick
Needs a reference to a function (L</code>) which uses the x-tick labels
generated by the '@data[0]' as the argument. The result of this function
can reformat the labels. For instance
$obj -> set ('f_x_tick' => \&formatter );
An example for the function formatter: x labels are seconds since an event.
The referenced function can transform this seconds to hour, minutes and seconds.
=head2 f_y_tick
The same situation as for 'f_x_tick' but now used for y labels.
=head2 f_y_tick1
L</Composite> only: L</code> ref to a function which has one argument
and has to return a string which labels the first resp. second y axis.
Both default to undef.
=head2 f_y_tick2
L</Composite> only: L</code> ref to a function which has one argument
and has to return a string which labels the first resp. second y axis.
Both default to undef.
=head2 graph_border
L</Pie> only: Sets the number of pixels used as a border between the
title/labels and the actual graph within the image. Defaults to 10.
=head2 grey_background
Puts a nice soft grey background on the data plot area when set to C<'true'>.
Default is C<'true'>.
=head2 grid_lines
L<bool|/boolean>: draw grid lines matching up to x and y ticks.
Default is C<'false'>.
=head2 imagemap
Lets Chart know you're going to ask for information about the placement
of the data for use in creating an image map from the png. This information
can be retrieved using the L<imagemap_dump()|Chart::Manual::Methods/imagemap_dump>
method. NB. that the imagemap_dump() method cannot be called until after
the Chart has been L<generated|"/Chart::Manual::Workflows/create image">.
=head2 include_zero
If C<'true'>, forces the y-axis to include zero if it is not in the dataset
range. Default is C<'false'>.
In general, it is better to use this, than to set the L</min_val> if that
is all you want to achieve.
=head2 integer_ticks_only
L<bool|/boolean> specifies to draw the x- and y-ticks at floating point
values (as normal) or when set to C<'true'> only at integer values.
Default: C<'false'>
=head2 interval
L</Split> only: Sets the interval of one partition of plot. Defaults 'undef'.
=head2 interval_ticks
L</Split> only: Number of ticks for the x-axis. Defaults to 5.
=head2 label_font
This option changes the L</font> of the axis labels.
Default is GD::Font->MediumBold.
=head2 label_values
L</Pie> only: What kind of value labels to show alongside the pie.
Valid values are C<'percent'>, C<'value'>, C<'both'> and C<'none'>.
Defaults to C<'percent'>.
=head2 legend
Specifies the placement of the legend. Valid values are C<'left'>,
C<'right'>, C<'top'>, C<'bottom'>. Setting this to C<'none'> tells chart
not to draw a legend. Default is C<'right'>.
=head2 legend_example_size
L</Composite> only: Length of the example line in the legend in pixels.
Defaults to C<20>.
=head2 legend_font
This option changes the L</font> of the text in the legend.
Default is GD::Font->Small.
=head2 legend_labels
Array reference containing texts, which are the labels assigned to each
color in the legend. Amount has to correspond to the amount of data sets.
@labels = ('foo', 'bar');
$obj->set ('legend_labels' => \@labels);
Default is empty, in which case C<'Dataset 1'>, C<'Dataset 2'>, etc. are
used as the labels.
=head2 legend_label_values
L</Pie> only: What labels to draw in the legend. Valid values are
c<'percent'>, C<'value'>, C<'both'> and C<'none'>. Defaults to C<'value'>.
=head2 legend_lines
L</Pie> only: L<bool|/boolean> to decide if lines connecting pie slices
and label are drawn. Default is C<'false'>.
=head2 label_values
L</Pie> only: Labels to draw beside the pie slices. Valid values are
C<'percent'>, C<'value'>, C<'both'> and C<'none'>. Defaults to C<'percent'>.
=head2 line
L</Direction> only: If you turn this option to C<'true'>, then point will
be connected with lines. Defaults to C<'false'>.
=head2 max_circles
L</Direction> only: Sets the maximum number of circles in the coordinate system.
Default is 100. This limit is used to avoid plotting an unreasonable
large number of ticks if non-round values are used for the min_val and max_val.
=head2 max_val
Sets the maximum y-value on the graph, overriding the normal auto-scaling.
Default is undef.
=head2 max_val1
L</Composite> only: Maximum y-value for the first (left y-axis) components.
Default to undef.
=head2 max_val2
L</Composite> only: Maximum y-value for the second (right y-axis) components.
Default to undef.
=head2 max_x_ticks
Work similar as 'max_y_ticks' and 'min_y_ticks'. Of course, only for a
xy_plot.
=head2 max_y_ticks
Sets the maximum number of y_ticks to draw when generating a scale.
Default is 100. This limit is used to avoid plotting an unreasonable
large number of ticks if non-round values are used for the min_val
and max_val.
The value for 'max_y_ticks' should be at least 5 times larger than
'min_y_ticks'.
=head2 min_circles
L</Direction> only: Sets the minimum number of circles when generating
a scale for direction. Default is 4, minimum is 2.
=head2 min_val
Sets the minimum y-value on the graph, overriding the normal auto-scaling.
Default is undef.
lib/Chart/Manual/Properties.pod view on Meta::CPAN
L</Split> only: Every y-value will be multiplied with that value, but
the scale won't change. Which means that split allows one to overdraw
certain rows! Only useful if you want to give prominence to the maximal
amplitudes of the data. Defaults to C<1>.
=head2 same_error
L</ErrorBars> only: It tells chart that you want use the same
error value of a data point if set to C<'true'>. Look at the documentation
to see how the module ErrorBars works. Default: C<'false'>.
=head2 same_y_axes
L</Composite> only: Forces both component charts to use the same maximum
and minimum y-values if set to C<'true'>. This helps to keep the composite
charts from being too confusing. Default is C<undef>.
=head2 skip_int_ticks
If C<'true'> the labels and ticks will be drawn every nth tick. Of course
in horizontalBars it affects the x-axis. Default to C<1>, no skipping.
=head2 skip_x_ticks
Sets the number of x-ticks and x-tick labels to skip. (ie.
if 'skip_x_ticks' was set to 4, Chart would draw every 4th x-tick
and x-tick label). Default is C<undef>.
=head2 skip_y_ticks
L</HorizontalBars> only: Draw only every n'th tick with label on y-axis.
does for other charts. Defaults to C<1> (draw all).
=head2 sort
In a xy-plot, the data will be sorted ascending if set to C<'true'>.
(Should be set if the data isn't sorted, especially in Lines, Split
and LinesPoints) In a Pareto Chart the data will be sorted descending.
Defaults to C<'false'>.
=head2 spaced_bars
L</Bars> only: Leaves space between the groups of bars at each data point
when set to C<'true'>. This just makes it easier to read a bar chart.
Default is C<'true'>.
=head2 start
L</Split> only: Sets the start value of the first interval.
If the x coordinate of the first data point is zero, you should 'set' to
zero. Default is C<'undef'>.
=head2 sub_title
Write a sub-title under the L</title> in smaller letters.
Default is empty.
=head2 text_space
Sets the amount of space left on the sides (lext and right) of text,
(title, legend, label) to make it more readable. Defaults to C<2>.
=head2 tick_label_font
This is the font for the tick labels. It also needs
a GD font object as an argument. Default is GD::Font->Small.
=head2 tick_len
Sets the length of the x- and y-ticks in pixels. Default is C<4>.
=head2 title
Content of title text. If empty, no title is drawn.
It recognizes '\n' as a newline, and acts accordingly.
Remember, if you want to use normal quotation marks instead of single
quotation marks then you have to quote "\\n". Default is empty.
=head2 title_font
This option changes the L</font> of the title. Default is GD::Font->Large.
=head2 transparent
Makes the background of the whole image transparent if set to C<'true'>.
Useful for making web page images. Default is C<'false'>.
=head2 x_grid_lines
Draws vertical grid lines matching up to x ticks if set to C<'true'>.
Default is C<'false'>.
=head2 x_label
Tells Chart what to use for the x-axis label. If empty, no label
is drawn. Default is empty.
=head2 x_ticks
Specifies how to draw the x-tick labels. Valid values are 1: C<'normal'>,
2: C<'staggered'> (alternating on upper and lower row - for very long labels),
and 3: C<'vertical'> (the labels are draw upwards in right angle).
Default is C<'normal'>.
=head2 xy_plot
Forces Chart to plot a x-y-graph, which means, that the x-axis is also
numeric if set to C<'true'>. Very useful for mathematical graphs.
Works for Lines, Points, LinesPoints and ErrorBars. Split makes always a
xy_plot. Defaults to C<'false'>.
=head2 y_label
Tells Chart what to use for labels on the standard, left y-axis.
If empty, no label is drawn. Default is empty (C<''>).
=head2 y_label2
Text of the label on the second, right y-axis (if different from left).
If empty, no label is drawn. Default is empty (C<''>).
( run in 0.516 second using v1.01-cache-2.11-cpan-437f7b0c052 )