This is the most important property of a series and must be set for every chart object. It links the chart with the worksheet data that it displays. A formula or array ref can be used for the data range, see below.

categories

This sets the chart category labels. The category is more or less the same as the X axis. In most chart types the categories property is optional and the chart will just assume a sequential series from 1 .. n.

name

Set the name for the series. The name is displayed in the chart legend and in the formula bar. The name property is optional and if it isn't supplied it will default to Series 1 .. n.

line

Set the properties of the series line type such as colour and width. See the "CHART FORMATTING" section below.

border

Set the border properties of the series such as colour and style. See the "CHART FORMATTING" section below.

fill

Set the fill properties of the series such as colour. See the "CHART FORMATTING" section below.

marker

Set the properties of the series marker such as style and colour. See the "SERIES OPTIONS" section below.

trendline

Set the properties of the series trendline such as linear, polynomial and moving average types. See the "SERIES OPTIONS" section below.

smooth

The smooth option is used to set the smooth property of a line series. See the "SERIES OPTIONS" section below.

y_error_bars

Set vertical error bounds for a chart series. See the "SERIES OPTIONS" section below.

x_error_bars

Set horizontal error bounds for a chart series. See the "SERIES OPTIONS" section below.

You can add more than one series to a chart. In fact, some chart types such as stock require it. The series numbering and order in the Excel chart will be the same as the order in which they are added in Excel::Writer::XLSX.

The number format is similar to the Worksheet Cell Format num_format apart from the fact that a format index cannot be used. The explicit format string must be used as shown above. See "set_num_format()" in Excel::Writer::XLSX for more information.

line

Set the properties of the axis line type such as colour and width. See the "CHART FORMATTING" section below.

$chart->set_x_axis( line => { none => 1 });

fill

Set the fill properties of the axis such as colour. See the "CHART FORMATTING" section below. Note, in Excel the axis fill is applied to the area of the numbers of the axis and not to the area of the axis bounding box. That background is set from the chartarea fill.

min

Set the minimum value for the axis range. (Applicable to value axes only.)

$chart->set_x_axis( min => 20 );

max

Set the maximum value for the axis range. (Applicable to value axes only.)

$chart->set_x_axis( max => 80 );

minor_unit

Set the increment of the minor units in the axis range. (Applicable to value axes only.)

$chart->set_x_axis( minor_unit => 0.4 );

major_unit

Set the increment of the major units in the axis range. (Applicable to value axes only.)

$chart->set_x_axis( major_unit => 2 );

interval_unit

Set the interval unit for a category axis. (Applicable to category axes only.)

$chart->set_x_axis( interval_unit => 2 );

crossing

Set the position where the y axis will cross the x axis. (Applicable to category and value axes.)

The crossing value can either be the string 'max' to set the crossing at the maximum axis value or a numeric value.

The set_size() method is used to set the dimensions of the chart. The size properties that can be set are:

width
height
x_scale
y_scale
x_offset
y_offset

The width and height are in pixels. The default chart width is 480 pixels and the default height is 288 pixels. The size of the chart can be modified by setting the width and height or by setting the x_scale and y_scale:

By default Excel adds an automatic chart title to charts with a single series and a user defined series name. The none option turns this default title off. It also turns off all other set_title() options.

The name property sets an optional name for the trendline that will appear in the chart legend. If it isn't specified the Excel default name will be displayed. This is usually a combination of the trendline type and the series name.

Error bars can be added to a chart series to indicate error bounds in the data. The error bars can be vertical y_error_bars (the most common type) or horizontal x_error_bars (for Bar and Scatter charts only).

Note: Even when leader lines are turned on they aren't automatically visible in Excel or Excel::Writer::XLSX. Due to an Excel limitation (or design) leader lines only appear if the data label is moved manually or if the data labels are very close and need to be adjusted automatically.

The separator property is used to change the separator between multiple data label items:

The number format is similar to the Worksheet Cell Format num_format apart from the fact that a format index cannot be used. The explicit format string must be used as shown above. See "set_num_format()" in Excel::Writer::XLSX for more information.

The font property is used to set the font properties of the data labels in a series:

In general formatting is applied to an entire series in a chart. However, it is occasionally required to format individual points in a series. In particular this is required for Pie and Doughnut charts where each segment is represented by a point.

In these cases it is possible to use the points property of add_series():

The following chart formatting properties can be set for any chart object that they apply to (and that are supported by Excel::Writer::XLSX) such as chart lines, column fill areas, plot area borders, markers, gridlines and other chart elements documented above.

It can be used as a descriptive substitute for line in chart types such as Bar and Column that have a border and fill style rather than a line style. In general chart objects with a border property will also have a fill property.

The following font properties can be set for any chart object that they apply to (and that are supported by Excel::Writer::XLSX) such as chart titles, axis labels, axis numbering and data labels. They correspond to the equivalent Worksheet cell Format object properties. See "FORMAT_METHODS" in Excel::Writer::XLSX for more information.

name
size
bold
italic
underline
rotation
color

The following explains the available font properties:

name

Set the font name:

$chart->set_x_axis( num_font => { name => 'Arial' } );

size

Set the font size:

$chart->set_x_axis( num_font => { name => 'Arial', size => 10 } );

bold

Set the font bold property, should be 0 or 1:

$chart->set_x_axis( num_font => { bold => 1 } );

italic

Set the font italic property, should be 0 or 1:

$chart->set_x_axis( num_font => { italic => 1 } );

underline

Set the font underline property, should be 0 or 1:

$chart->set_x_axis( num_font => { underline => 1 } );

rotation

Set the font rotation in the range -90 to 90:

$chart->set_x_axis( num_font => { rotation => 45 } );

This is useful for displaying large axis data such as dates in a more compact format.

color

Set the font color property. Can be a color index, a color name or HTML style RGB colour:

Excel differentiates between a chart axis that is used for series categories and an axis that is used for series values.

In the example above the X axis is the category axis and each of the values is evenly spaced. The Y axis (in this case) is the value axis and points are displayed according to their value.

Since Excel treats the axes differently it also handles their formatting differently and exposes different properties for each.

As such some of Excel::Writer::XLSX axis properties can be set for a value axis, some can be set for a category axis and some properties can be set for both.

For example the min and max properties can only be set for value axes and reverse can be set for both. The type of axis that a property applies to is shown in the set_x_axis() section of the documentation above.

Some charts such as Scatter and Stock have two value axes.

Date Axes are a special type of category axis which are explained below.

The secondary chart can also be placed on a secondary axis using the methods shown in the previous section.

In this case it is just necessary to add a y2_axis parameter to the series and, if required, add a title using set_y2_axis(). The following are the additions to the previous example to place the secondary chart on the secondary axis:

The examples above use the concept of a primary and secondary chart. The primary chart is the chart that defines the primary X and Y axis. It is also used for setting all chart properties apart from the secondary data series. For example the chart title and axes properties should be set via the primary chart.

See also chart_combined.pl and chart_pareto.pl examples in the distro for more detailed examples.

There are some limitations on combined charts:

Pie charts cannot currently be combined.

Scatter charts cannot currently be used as a primary chart but they can be used as a secondary chart.

Bar charts can only combined secondary charts on a secondary axis. This is an Excel limitation.