add_series()

In an Excel chart a "series" is a collection of information such as values, X axis labels and the formatting that define which data is plotted.

With an Excel::Writer::XLSX chart object the "add_series()" method is used to set the properties for a series:

    $chart->add_series(
        categories => '=Sheet1!$A$2:$A$10', # Optional.
        values     => '=Sheet1!$B$2:$B$10', # Required.
        line       => { color => 'blue' },
    );

The properties that can be set are:

• "values"

  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.

• "pattern"

  Set the pattern properties of the series. See the "CHART FORMATTING" section below.

• "gradien"

  Set the gradient properties of the series. 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.

• "data_labels"

  Set data labels for the series. See the "SERIES OPTIONS" section below.

• "points"

  Set properties for individual points in a series. See the "SERIES OPTIONS" section below.

• "invert_if_negative"

  Invert the fill colour for negative values. Usually only applicable to column and bar charts.

• "overlap"

  Set the overlap between series in a Bar/Column chart. The range is +/- 100. Default is 0.

      overlap => 20,
      

  Note, it is only necessary to apply this property to one series of the chart.

• "gap"

  Set the gap between series in a Bar/Column chart. The range is 0 to 500. Default is 150.

      gap => 200,
      

  Note, it is only necessary to apply this property to one series of the chart.

The "categories" and "values" can take either a range formula such as "=Sheet1!$A$2:$A$7" or, more usefully when generating the range programmatically, an array ref with zero indexed row/column values:

     [ $sheetname, $row_start, $row_end, $col_start, $col_end ]

The following are equivalent:

    $chart->add_series( categories => '=Sheet1!$A$2:$A$7'      ); # Same as ...
    $chart->add_series( categories => [ 'Sheet1', 1, 6, 0, 0 ] ); # Zero-indexed.

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.

    # Add the first series.
    $chart->add_series(
        categories => '=Sheet1!$A$2:$A$7',
        values     => '=Sheet1!$B$2:$B$7',
        name       => 'Test data series 1',
    );
    # Add another series. Same categories. Different range values.
    $chart->add_series(
        categories => '=Sheet1!$A$2:$A$7',
        values     => '=Sheet1!$C$2:$C$7',
        name       => 'Test data series 2',
    );

It is also possible to specify non-contiguous ranges:

    $chart->add_series(
        categories      => '=(Sheet1!$A$1:$A$9,Sheet1!$A$14:$A$25)',
        values          => '=(Sheet1!$B$1:$B$9,Sheet1!$B$14:$B$25)',
    );

set_x_axis()

The "set_x_axis()" method is used to set properties of the X axis.

    $chart->set_x_axis( name => 'Quarterly results' );

The properties that can be set are:

    name
    name_font
    name_layout
    num_font
    num_format
    line
    fill
    pattern
    gradient
    min
    max
    minor_unit
    major_unit
    interval_unit
    interval_tick
    crossing
    reverse
    position_axis
    log_base
    label_position
    major_gridlines
    minor_gridlines
    visible
    date_axis
    text_axis
    minor_unit_type
    major_unit_type
    minor_tick_mark
    major_tick_mark
    display_units
    display_units_visible

These are explained below. Some properties are only applicable to value or category axes, as indicated. See "Value and Category Axes" for an explanation of Excel's distinction between the axis types.

• "name"

  Set the name (title or caption) for the axis. The name is displayed below the X axis. The "name" property is optional. The default is to have no axis name. (Applicable to category and value axes).

      $chart->set_x_axis( name => 'Quarterly results' );
      

  The name can also be a formula such as "=Sheet1!$A$1".

• "name_font"

  Set the font properties for the axis title. (Applicable to category and value axes).

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

• "name_layout"

  Set the "(x, y)" position of the axis caption in chart relative units. (Applicable to category and value axes).

      $chart->set_x_axis(
          name        => 'X axis',
          name_layout => {
              x => 0.34,
              y => 0.85,
          }
      );
      

  See the "CHART LAYOUT" section below.

• "num_font"

  Set the font properties for the axis numbers. (Applicable to category and value axes).

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

  See the "CHART FONTS" section below.

• "num_format"

  Set the number format for the axis. (Applicable to category and value axes).

      $chart->set_x_axis( num_format => '#,##0.00' );
      $chart->set_y_axis( num_format => '0.00%'    );
      

  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.

• "pattern"

  Set the pattern properties of the axis such as colour. See the "CHART FORMATTING" section below.

• "gradient"

  Set the gradient properties of the axis such as colour. See the "CHART FORMATTING" section below.

• "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 );
      

• "interval_tick"

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

      $chart->set_x_axis( interval_tick => 4 );
      

• "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.

      $chart->set_x_axis( crossing => 3 );
      # or
      $chart->set_x_axis( crossing => 'max' );
      

  For category axes the numeric value must be an integer to represent the category number that the axis crosses at. For value axes it can have any value associated with the axis.

  If crossing is omitted (the default) the crossing will be set automatically by Excel based on the chart data.

• "position_axis"

  Position the axis on or between the axis tick marks. (Applicable to category axes only.)

  There are two allowable values "on_tick" and "between":

      $chart->set_x_axis( position_axis => 'on_tick' );
      $chart->set_x_axis( position_axis => 'between' );
      

• "reverse"

  Reverse the order of the axis categories or values. (Applicable to category and value axes.)

      $chart->set_x_axis( reverse => 1 );
      

• "log_base"

  Set the log base of the axis range. (Applicable to value axes only.)

      $chart->set_x_axis( log_base => 10 );
      

• "label_position"

  Set the "Axis labels" position for the axis. The following positions are available:

      next_to (the default)
      high
      low
      none
      

• "major_gridlines"

  Configure the major gridlines for the axis. The available properties are:

      visible
      line
      

  For example:

      $chart->set_x_axis(
          major_gridlines => {
              visible => 1,
              line    => { color => 'red', width => 1.25, dash_type => 'dash' }
          }
      );
      

  The "visible" property is usually on for the X-axis but it depends on the type of chart.

  The "line" property sets the gridline properties such as colour and width. See the "CHART FORMATTING" section below.

• "minor_gridlines"

  This takes the same options as "major_gridlines" above.

  The minor gridline "visible" property is off by default for all chart types.

• "visible"

  Configure the visibility of the axis.

      $chart->set_x_axis( visible => 0 );
      

• "date_axis"

  This option is used to treat a category axis with date or time data as a Date Axis. (Applicable to category axes only.)

      $chart->set_x_axis( date_axis => 1 );
      

  This option also allows you to set "max" and "min" values for a category axis which isn't allowed by Excel for non-date category axes.

  See "Date Category Axes" for more details.

• "text_axis"

  This option is used to treat a category axis explicitly as a Text Axis. (Applicable to category axes only.)

      $chart->set_x_axis( text_axis => 1 );
      

• "minor_unit_type"

  For "date_axis" axes, see above, this option is used to set the type of the minor units. (Applicable to date category axes only.)

      $chart->set_x_axis(
          date_axis         => 1,
          minor_unit        => 4,
          minor_unit_type   => 'months',
      );
      

  The allowable values for this option are "days", "months" and "years".

• "major_unit_type"

  Same as "minor_unit_type", see above, but for major axes unit types.

  More than one property can be set in a call to "set_x_axis()":

      $chart->set_x_axis(
          name => 'Quarterly results',
          min  => 10,
          max  => 80,
      );
      

• "major_tick_mark"

  Set the axis major tick mark type to one of the following values:

      none
      inside
      outside
      cross   (inside and outside)
      

  For example:

      $chart->set_x_axis( major_tick_mark => 'none',
                          minor_tick_mark => 'inside' );
      

• "minor_tick_mark"

  Set the axis minor tick mark type. Same as "major_tick_mark", see above.

• "display_units"

  Set the display units for the axis. This can be useful if the axis numbers are very large but you don't want to represent them in scientific notation. (Applicable to value axes only.) The available display units are:

      hundreds
      thousands
      ten_thousands
      hundred_thousands
      millions
      ten_millions
      hundred_millions
      billions
      trillions
      

  Example:

      $chart->set_x_axis( display_units => 'thousands' )
      $chart->set_y_axis( display_units => 'millions' )
      

  * "display_units_visible"

  Control the visibility of the display units turned on by the previous option. This option is on by default. (Applicable to value axes only.)::

      $chart->set_x_axis( display_units         => 'thousands',
                          display_units_visible => 0 )
      

set_y_axis()

The "set_y_axis()" method is used to set properties of the Y axis. The properties that can be set are the same as for "set_x_axis", see above.

set_x2_axis()

The "set_x2_axis()" method is used to set properties of the secondary X axis. The properties that can be set are the same as for "set_x_axis", see above. The default properties for this axis are:

    label_position => 'none',
    crossing       => 'max',
    visible        => 0,

set_y2_axis()

The "set_y2_axis()" method is used to set properties of the secondary Y axis. The properties that can be set are the same as for "set_x_axis", see above. The default properties for this axis are:

    major_gridlines => { visible => 0 }

combine()

The chart "combine()" method is used to combine two charts of different types, for example a column and line chart:

    my $column_chart = $workbook->add_chart( type => 'column', embedded => 1 );
    # Configure the data series for the primary chart.
    $column_chart->add_series(...);
    # Create a new column chart. This will use this as the secondary chart.
    my $line_chart = $workbook->add_chart( type => 'line', embedded => 1 );
    # Configure the data series for the secondary chart.
    $line_chart->add_series(...);
    # Combine the charts.
    $column_chart->combine( $line_chart );

See "Combined Charts" for more details.

set_size()

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":

    $chart->set_size( width => 720, height => 576 );
    # Same as:
    $chart->set_size( x_scale => 1.5, y_scale => 2 );

The "x_offset" and "y_offset" position the top left corner of the chart in the cell that it is inserted into.

Note: the "x_scale", "y_scale", "x_offset" and "y_offset" parameters can also be set via the "insert_chart()" method:

    $worksheet->insert_chart( 'E2', $chart, 2, 4, 1.5, 2 );

set_title()

The "set_title()" method is used to set properties of the chart title.

    $chart->set_title( name => 'Year End Results' );

The properties that can be set are:

• "name"

  Set the name (title) for the chart. The name is displayed above the chart. The name can also be a formula such as "=Sheet1!$A$1". The name property is optional. The default is to have no chart title.

• "name_font"

  Set the font properties for the chart title. See the "CHART FONTS" section below.

• "overlay"

  Allow the title to be overlaid on the chart. Generally used with the layout property below.

• "layout"

  Set the "(x, y)" position of the title in chart relative units:

      $chart->set_title(
          name    => 'Title',
          overlay => 1,
          layout  => {
              x => 0.42,
              y => 0.14,
          }
      );
      

  See the "CHART LAYOUT" section below.

• "none"

  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.

      $chart->set_title( none => 1 );
      

set_legend()

The "set_legend()" method is used to set properties of the chart legend.

The properties that can be set are:

• "none"

  The "none" option turns off the chart legend. In Excel chart legends are on by default:

      $chart->set_legend( none => 1 );
      

  Note, for backward compatibility, it is also possible to turn off the legend via the "position" property:

      $chart->set_legend( position => 'none' );
      

• "position"

  Set the position of the chart legend.

      $chart->set_legend( position => 'bottom' );
      

  The default legend position is "right". The available positions are:

      top
      bottom
      left
      right
      top_right
      overlay_left
      overlay_right
      overlay_top_right
      none
      

• "border"

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

• "fill"

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

• "pattern"

  Set the pattern fill properties of the legend. See the "CHART FORMATTING" section below.

• "gradient"

  Set the gradient fill properties of the legend. See the "CHART FORMATTING" section below.

• "font"

  Set the font properties of the chart legend:

      $chart->set_legend( font => { bold => 1, italic => 1 } );
      

  See the "CHART FONTS" section below.

• "delete_series"

  This allows you to remove 1 or more series from the legend (the series will still display on the chart). This property takes an array ref as an argument and the series are zero indexed:

      # Delete/hide series index 0 and 2 from the legend.
      $chart->set_legend( delete_series => [0, 2] );
      

• "layout"

  Set the "(x, y)" position of the legend in chart relative units:

      $chart->set_legend(
          layout => {
              x      => 0.80,
              y      => 0.37,
              width  => 0.12,
              height => 0.25,
          }
      );
      

  See the "CHART LAYOUT" section below.

set_chartarea()

The "set_chartarea()" method is used to set the properties of the chart area.

    $chart->set_chartarea(
        border => { none  => 1 },
        fill   => { color => 'red' }
    );

The properties that can be set are:

• "border"

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

• "fill"

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

• "pattern"

  Set the pattern fill properties of the chartarea. See the "CHART FORMATTING" section below.

• "gradient"

  Set the gradient fill properties of the chartarea. See the "CHART FORMATTING" section below.

set_plotarea()

The "set_plotarea()" method is used to set properties of the plot area of a chart.

    $chart->set_plotarea(
        border => { color => 'yellow', width => 1, dash_type => 'dash' },
        fill   => { color => '#92D050' }
    );

The properties that can be set are:

• "border"

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

• "fill"

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

• "pattern"

  Set the pattern fill properties of the plotarea. See the "CHART FORMATTING" section below.

• "gradient"

  Set the gradient fill properties of the plotarea. See the "CHART FORMATTING" section below.

• "layout"

  Set the "(x, y)" position of the plotarea in chart relative units:

      $chart->set_plotarea(
          layout => {
              x      => 0.35,
              y      => 0.26,
              width  => 0.62,
              height => 0.50,
          }
      );
      

  See the "CHART LAYOUT" section below.

set_style()

The "set_style()" method is used to set the style of the chart to one of the 42 built-in styles available on the 'Design' tab in Excel:

    $chart->set_style( 4 );

The default style is 2.

set_table()

The "set_table()" method adds a data table below the horizontal axis with the data used to plot the chart.

    $chart->set_table();

The available options, with default values are:

    vertical   => 1    # Display vertical lines in the table.
    horizontal => 1    # Display horizontal lines in the table.
    outline    => 1    # Display an outline in the table.
    show_keys  => 0    # Show the legend keys with the table data.
    font       => {}   # Standard chart font properties.

The data table can only be shown with Bar, Column, Line, Area and stock charts. For font properties see the "CHART FONTS" section below.

set_up_down_bars

The "set_up_down_bars()" method adds Up-Down bars to Line charts to indicate the difference between the first and last data series.

    $chart->set_up_down_bars();

It is possible to format the up and down bars to add "fill", "pattern", "gradient" and "border" properties if required. See the "CHART FORMATTING" section below.

    $chart->set_up_down_bars(
        up   => { fill => { color => 'green' } },
        down => { fill => { color => 'red' } },
    );

Up-down bars can only be applied to Line charts and to Stock charts (by default).

set_drop_lines

The "set_drop_lines()" method adds Drop Lines to charts to show the Category value of points in the data.

    $chart->set_drop_lines();

It is possible to format the Drop Line "line" properties if required. See the "CHART FORMATTING" section below.

    $chart->set_drop_lines( line => { color => 'red', dash_type => 'square_dot' } );

Drop Lines are only available in Line, Area and Stock charts.

set_high_low_lines

The "set_high_low_lines()" method adds High-Low lines to charts to show the maximum and minimum values of points in a Category.

    $chart->set_high_low_lines();

It is possible to format the High-Low Line "line" properties if required. See the "CHART FORMATTING" section below.

    $chart->set_high_low_lines( line => { color => 'red' } );

High-Low Lines are only available in Line and Stock charts.

show_blanks_as()

The "show_blanks_as()" method controls how blank data is displayed in a chart.

    $chart->show_blanks_as( 'span' );

The available options are:

        gap    # Blank data is shown as a gap. The default.
        zero   # Blank data is displayed as zero.
        span   # Blank data is connected with a line.

show_hidden_data()

Display data in hidden rows or columns on the chart.

    $chart->show_hidden_data();

Marker

The marker format specifies the properties of the markers used to distinguish series on a chart. In general only Line and Scatter chart types and trendlines use markers.

The following properties can be set for "marker" formats in a chart.

    type
    size
    border
    fill
    pattern
    gradient

The "type" property sets the type of marker that is used with a series.

    $chart->add_series(
        values     => '=Sheet1!$B$1:$B$5',
        marker     => { type => 'diamond' },
    );

The following "type" properties can be set for "marker" formats in a chart. These are shown in the same order as in the Excel format dialog.

    automatic
    none
    square
    diamond
    triangle
    x
    star
    short_dash
    long_dash
    circle
    plus

The "automatic" type is a special case which turns on a marker using the default marker style for the particular series number.

    $chart->add_series(
        values     => '=Sheet1!$B$1:$B$5',
        marker     => { type => 'automatic' },
    );

If "automatic" is on then other marker properties such as size, border or fill cannot be set.

The "size" property sets the size of the marker and is generally used in conjunction with "type".

    $chart->add_series(
        values     => '=Sheet1!$B$1:$B$5',
        marker     => { type => 'diamond', size => 7 },
    );

Nested "border" and "fill" properties can also be set for a marker. See the "CHART FORMATTING" section below.

    $chart->add_series(
        values     => '=Sheet1!$B$1:$B$5',
        marker     => {
            type    => 'square',
            size    => 5,
            border  => { color => 'red' },
            fill    => { color => 'yellow' },
        },
    );

Trendline

A trendline can be added to a chart series to indicate trends in the data such as a moving average or a polynomial fit.

The following properties can be set for trendlines in a chart series.

    type
    order               (for polynomial trends)
    period              (for moving average)
    forward             (for all except moving average)
    backward            (for all except moving average)
    name
    line
    intercept           (for exponential, linear and polynomial only)
    display_equation    (for all except moving average)
    display_r_squared   (for all except moving average)

The "type" property sets the type of trendline in the series.

    $chart->add_series(
        values     => '=Sheet1!$B$1:$B$5',
        trendline  => { type => 'linear' },
    );

The available "trendline" types are:

    exponential
    linear
    log
    moving_average
    polynomial
    power

A "polynomial" trendline can also specify the "order" of the polynomial. The default value is 2.

    $chart->add_series(
        values    => '=Sheet1!$B$1:$B$5',
        trendline => {
            type  => 'polynomial',
            order => 3,
        },
    );

A "moving_average" trendline can also specify the "period" of the moving average. The default value is 2.

    $chart->add_series(
        values     => '=Sheet1!$B$1:$B$5',
        trendline  => {
            type   => 'moving_average',
            period => 3,
        },
    );

The "forward" and "backward" properties set the forecast period of the trendline.

    $chart->add_series(
        values    => '=Sheet1!$B$1:$B$5',
        trendline => {
            type     => 'linear',
            forward  => 0.5,
            backward => 0.5,
        },
    );

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.

    $chart->add_series(
        values    => '=Sheet1!$B$1:$B$5',
        trendline => {
            type => 'linear',
            name => 'Interpolated trend',
        },
    );

The "intercept" property sets the point where the trendline crosses the Y (value) axis:

    $chart->add_series(
        values    => '=Sheet1!$B$1:$B$5',
        trendline => {
            type      => 'linear',
            intercept => 0.8,
        },
    );

The "display_equation" property displays the trendline equation on the chart.

    $chart->add_series(
        values    => '=Sheet1!$B$1:$B$5',
        trendline => {
            type             => 'linear',
            display_equation => 1,
        },
    );

The "display_r_squared" property displays the R squared value of the trendline on the chart.

    $chart->add_series(
        values    => '=Sheet1!$B$1:$B$5',
        trendline => {
            type              => 'linear',
            display_r_squared => 1
        },
    );

Several of these properties can be set in one go:

    $chart->add_series(
        values     => '=Sheet1!$B$1:$B$5',
        trendline  => {
            type              => 'polynomial',
            name              => 'My trend name',
            order             => 2,
            forward           => 0.5,
            backward          => 0.5,
            intercept         => 1.5,
            display_equation  => 1,
            display_r_squared => 1,
            line              => {
                color     => 'red',
                width     => 1,
                dash_type => 'long_dash',
            }
        },
    );

Trendlines cannot be added to series in a stacked chart or pie chart, radar chart, doughnut or (when implemented) to 3D, or surface charts.

Error Bars

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).

The following properties can be set for error bars in a chart series.

    type
    value        (for all types except standard error and custom)
    plus_values  (for custom only)
    minus_values (for custom only)
    direction
    end_style
    line

The "type" property sets the type of error bars in the series.

    $chart->add_series(
        values       => '=Sheet1!$B$1:$B$5',
        y_error_bars => { type => 'standard_error' },
    );

The available error bars types are available:

    fixed
    percentage
    standard_deviation
    standard_error
    custom

All error bar types, except for "standard_error" and "custom" must also have a value associated with it for the error bounds:

    $chart->add_series(
        values       => '=Sheet1!$B$1:$B$5',
        y_error_bars => {
            type  => 'percentage',
            value => 5,
        },
    );

The "custom" error bar type must specify "plus_values" and "minus_values" which should either by a "Sheet1!$A$1:$A$5" type range formula or an arrayref of values:

    $chart->add_series(
        categories   => '=Sheet1!$A$1:$A$5',
        values       => '=Sheet1!$B$1:$B$5',
        y_error_bars => {
            type         => 'custom',
            plus_values  => '=Sheet1!$C$1:$C$5',
            minus_values => '=Sheet1!$D$1:$D$5',
        },
    );
    # or
    $chart->add_series(
        categories   => '=Sheet1!$A$1:$A$5',
        values       => '=Sheet1!$B$1:$B$5',
        y_error_bars => {
            type         => 'custom',
            plus_values  => [1, 1, 1, 1, 1],
            minus_values => [2, 2, 2, 2, 2],
        },
    );

Note, as in Excel the items in the "minus_values" do not need to be negative.

The "direction" property sets the direction of the error bars. It should be one of the following:

    plus    # Positive direction only.
    minus   # Negative direction only.
    both    # Plus and minus directions, The default.

The "end_style" property sets the style of the error bar end cap. The options are 1 (the default) or 0 (for no end cap):

    $chart->add_series(
        values       => '=Sheet1!$B$1:$B$5',
        y_error_bars => {
            type      => 'fixed',
            value     => 2,
            end_style => 0,
            direction => 'minus'
        },
    );

Data Labels

Data labels can be added to a chart series to indicate the values of the plotted data points.

The following properties can be set for "data_labels" formats in a chart.

    value
    category
    series_name
    position
    percentage
    leader_lines
    separator
    legend_key
    num_format
    font

The "value" property turns on the Value data label for a series.

    $chart->add_series(
        values      => '=Sheet1!$B$1:$B$5',
        data_labels => { value => 1 },
    );

The "category" property turns on the Category Name data label for a series.

    $chart->add_series(
        values      => '=Sheet1!$B$1:$B$5',
        data_labels => { category => 1 },
    );

The "series_name" property turns on the Series Name data label for a series.

    $chart->add_series(
        values      => '=Sheet1!$B$1:$B$5',
        data_labels => { series_name => 1 },
    );

The "position" property is used to position the data label for a series.

    $chart->add_series(
        values      => '=Sheet1!$B$1:$B$5',
        data_labels => { value => 1, position => 'center' },
    );

In Excel the data label positions vary for different chart types. The allowable positions are:

    |  Position     |  Line     |  Bar      |  Pie      |  Area     |
    |               |  Scatter  |  Column   |  Doughnut |  Radar    |
    |               |  Stock    |           |           |           |
    |---------------|-----------|-----------|-----------|-----------|
    |  center       |  Yes      |  Yes      |  Yes      |  Yes*     |
    |  right        |  Yes*     |           |           |           |
    |  left         |  Yes      |           |           |           |
    |  above        |  Yes      |           |           |           |
    |  below        |  Yes      |           |           |           |
    |  inside_base  |           |  Yes      |           |           |
    |  inside_end   |           |  Yes      |  Yes      |           |
    |  outside_end  |           |  Yes*     |  Yes      |           |
    |  best_fit     |           |           |  Yes*     |           |

Note: The * indicates the default position for each chart type in Excel, if a position isn't specified.

The "percentage" property is used to turn on the display of data labels as a Percentage for a series. It is mainly used for pie and doughnut charts.

    $chart->add_series(
        values      => '=Sheet1!$B$1:$B$5',
        data_labels => { percentage => 1 },
    );

The "leader_lines" property is used to turn on Leader Lines for the data label for a series. It is mainly used for pie charts.

    $chart->add_series(
        values      => '=Sheet1!$B$1:$B$5',
        data_labels => { value => 1, leader_lines => 1 },
    );

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:

    $chart->add_series(
        values      => '=Sheet1!$B$1:$B$5',
        data_labels => { percentage => 1 },
        data_labels => { value => 1, category => 1, separator => "\n" },
    );

The separator value must be one of the following strings:

            ','
            ';'
            '.'
            "\n"
            ' '

The "legend_key" property is used to turn on Legend Key for the data label for a series:

    $chart->add_series(
        values      => '=Sheet1!$B$1:$B$5',
        data_labels => { value => 1, legend_key => 1 },
    );

The "num_format" property is used to set the number format for the data labels.

    $chart->add_series(
        values      => '=Sheet1!$A$1:$A$5',
        data_labels => { value => 1, num_format => '#,##0.00' },
    );

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:

    $chart->add_series(
        values      => '=Sheet1!$A$1:$A$5',
        data_labels => {
            value => 1,
            font  => { name => 'Consolas' }
        },
    );

The "font" property is also used to rotate the data labels in a series:

    $chart->add_series(
        values      => '=Sheet1!$A$1:$A$5',
        data_labels => {
            value => 1,
            font  => { rotation => 45 }
        },
    );

See the "CHART FONTS" section below.

Points

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()":

    $chart->add_series(
        values => '=Sheet1!$A$1:$A$3',
        points => [
            { fill => { color => '#FF0000' } },
            { fill => { color => '#CC0000' } },
            { fill => { color => '#990000' } },
        ],
    );

The "points" property takes an array ref of format options (see the "CHART FORMATTING" section below). To assign default properties to points in a series pass "undef" values in the array ref:

    # Format point 3 of 3 only.
    $chart->add_series(
        values => '=Sheet1!$A$1:$A$3',
        points => [
            undef,
            undef,
            { fill => { color => '#990000' } },
        ],
    );
    # Format the first point only.
    $chart->add_series(
        values => '=Sheet1!$A$1:$A$3',
        points => [ { fill => { color => '#FF0000' } } ],
    );

Smooth

The "smooth" option is used to set the smooth property of a line series. It is only applicable to the "Line" and "Scatter" chart types.

    $chart->add_series( values => '=Sheet1!$C$1:$C$5',
                        smooth => 1 );

Line

The line format is used to specify properties of line objects that appear in a chart such as a plotted line on a chart or a border.

The following properties can be set for "line" formats in a chart.

    none
    color
    width
    dash_type
    transparency

The "none" property is uses to turn the "line" off (it is always on by default except in Scatter charts). This is useful if you wish to plot a series with markers but without a line.

    $chart->add_series(
        values     => '=Sheet1!$B$1:$B$5',
        line       => { none => 1 },
    );

The "color" property sets the color of the "line".

    $chart->add_series(
        values     => '=Sheet1!$B$1:$B$5',
        line       => { color => 'red' },
    );

The available colours are shown in the main Excel::Writer::XLSX documentation. It is also possible to set the colour of a line with a HTML style RGB colour:

    $chart->add_series(
        line       => { color => '#FF0000' },
    );

The "width" property sets the width of the "line". It should be specified in increments of 0.25 of a point as in Excel.

    $chart->add_series(
        values     => '=Sheet1!$B$1:$B$5',
        line       => { width => 3.25 },
    );

The "dash_type" property sets the dash style of the line.

    $chart->add_series(
        values     => '=Sheet1!$B$1:$B$5',
        line       => { dash_type => 'dash_dot' },
    );

The following "dash_type" values are available. They are shown in the order that they appear in the Excel dialog.

    solid
    round_dot
    square_dot
    dash
    dash_dot
    long_dash
    long_dash_dot
    long_dash_dot_dot

The default line style is "solid".

The "transparency" property sets the transparency of the "line" color in the integer range 1 - 100. The color must be set for transparency to work, it doesn't work with an automatic/default color:

    $chart->add_series(
        values     => '=Sheet1!$B$1:$B$5',
        line       => { color => 'yellow', transparency => 50 },
    );

More than one "line" property can be specified at a time:

    $chart->add_series(
        values     => '=Sheet1!$B$1:$B$5',
        line       => {
            color     => 'red',
            width     => 1.25,
            dash_type => 'square_dot',
        },
    );

Border

The "border" property is a synonym for "line".

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.

Solid Fill

The fill format is used to specify filled areas of chart objects such as the interior of a column or the background of the chart itself.

The following properties can be set for "fill" formats in a chart.

    none
    color
    transparency

The "none" property is used to turn the "fill" property off (it is generally on by default).

    $chart->add_series(
        values     => '=Sheet1!$B$1:$B$5',
        fill       => { none => 1 },
    );

The "color" property sets the colour of the "fill" area.

    $chart->add_series(
        values     => '=Sheet1!$B$1:$B$5',
        fill       => { color => 'red' },
    );

The available colours are shown in the main Excel::Writer::XLSX documentation. It is also possible to set the colour of a fill with a HTML style RGB colour:

    $chart->add_series(
        fill       => { color => '#FF0000' },
    );

The "transparency" property sets the transparency of the solid fill color in the integer range 1 - 100. The color must be set for transparency to work, it doesn't work with an automatic/default color:

    $chart->set_chartarea( fill => { color => 'yellow', transparency => 75 } );

The "fill" format is generally used in conjunction with a "border" format which has the same properties as a "line" format.

    $chart->add_series(
        values     => '=Sheet1!$B$1:$B$5',
        border     => { color => 'red' },
        fill       => { color => 'yellow' },
    );

Pattern Fill

The pattern fill format is used to specify pattern filled areas of chart objects such as the interior of a column or the background of the chart itself.

The following properties can be set for "pattern" fill formats in a chart:

    pattern:   the pattern to be applied (required)
    fg_color:  the foreground color of the pattern (required)
    bg_color:  the background color (optional, defaults to white)

For example:

    $chart->set_plotarea(
        pattern => {
            pattern  => 'percent_5',
            fg_color => 'red',
            bg_color => 'yellow',
        }
    );

The following patterns can be applied:

    percent_5
    percent_10
    percent_20
    percent_25
    percent_30
    percent_40
    percent_50
    percent_60
    percent_70
    percent_75
    percent_80
    percent_90
    light_downward_diagonal
    light_upward_diagonal
    dark_downward_diagonal
    dark_upward_diagonal
    wide_downward_diagonal
    wide_upward_diagonal
    light_vertical
    light_horizontal
    narrow_vertical
    narrow_horizontal
    dark_vertical
    dark_horizontal
    dashed_downward_diagonal
    dashed_upward_diagonal
    dashed_horizontal
    dashed_vertical
    small_confetti
    large_confetti
    zigzag
    wave
    diagonal_brick
    horizontal_brick
    weave
    plaid
    divot
    dotted_grid
    dotted_diamond
    shingle
    trellis
    sphere
    small_grid
    large_grid
    small_check
    large_check
    outlined_diamond
    solid_diamond

The foreground color, "fg_color", is a required parameter and can be a Html style "#RRGGBB" string or a limited number of named colors. The available colours are shown in the main Excel::Writer::XLSX documentation.

The background color, "bg_color", is optional and defaults to black.

If a pattern fill is used on a chart object it overrides the solid fill properties of the object.

Gradient Fill

The gradient fill format is used to specify gradient filled areas of chart objects such as the interior of a column or the background of the chart itself.

The following properties can be set for "gradient" fill formats in a chart:

    colors:    a list of colors
    positions: an optional list of positions for the colors
    type:      the optional type of gradient fill
    angle:     the optional angle of the linear fill

The "colors" property sets a list of colors that define the "gradient":

    $chart->set_plotarea(
        gradient => { colors => [ '#DDEBCF', '#9CB86E', '#156B13' ] }
    );

Excel allows between 2 and 10 colors in a gradient but it is unlikely that you will require more than 2 or 3.

As with solid or pattern fill it is also possible to set the colors of a gradient with a Html style "#RRGGBB" string or a limited number of named colors. The available colours are shown in the main Excel::Writer::XLSX documentation:

    $chart->add_series(
        values   => '=Sheet1!$A$1:$A$5',
        gradient => { colors => [ 'red', 'green' ] }
    );

The "positions" defines an optional list of positions, between 0 and 100, of where the colors in the gradient are located. Default values are provided for "colors" lists of between 2 and 4 but they can be specified if required:

    $chart->add_series(
        values   => '=Sheet1!$A$1:$A$5',
        gradient => {
            colors    => [ '#DDEBCF', '#156B13' ],
            positions => [ 10,        90 ],
        }
    );

The "type" property can have one of the following values:

    linear        (the default)
    radial
    rectangular
    path

For example:

    $chart->add_series(
        values   => '=Sheet1!$A$1:$A$5',
        gradient => {
            colors => [ '#DDEBCF', '#9CB86E', '#156B13' ],
            type   => 'radial'
        }
    );

If "type" isn't specified it defaults to "linear".

For a "linear" fill the angle of the gradient can also be specified:

    $chart->add_series(
        values   => '=Sheet1!$A$1:$A$5',
        gradient => { colors => [ '#DDEBCF', '#9CB86E', '#156B13' ],
                      angle => 30 }
    );

The default angle is 90 degrees.

If gradient fill is used on a chart object it overrides the solid fill and pattern fill properties of the object.