Interface IErrorBar

public interface IErrorBar

Represents the error bars in a chart series.

Error bars indicate the degree of uncertainty for chart data. They can be applied to series in area, bar, column, line, and scatter groups on 2D charts. Only scatter series support both X and Y error bars.

Use this interface to configure the included error-bar parts, value type, end style, amount, custom positive and negative formulas, and chart formatting for a series.


 worksheet.getRange("A1:B4").setValue(new Object[][] {
     {"Quarter", "Sales"},
     {"Q1", 1200},
     {"Q2", 1500},
     {"Q3", 1800}
 });
 IShape shape = worksheet.getShapes().addChart(ChartType.ColumnClustered, 20, 20, 360, 220);
 shape.getChart().getSeriesCollection().add(worksheet.getRange("A1:B4"), RowCol.Columns, true, true);
 ISeries series = shape.getChart().getSeriesCollection().get(0);
 series.setHasErrorBars(true);
 IErrorBar errorBar = series.getYErrorBar();
 errorBar.setValueType(ErrorBarType.FixedValue);
 errorBar.setAmount(100);

Method Summary

Modifier and Type

Method

Description

void

clearFormats()

Clears the formatting of this error bar.

void

delete()

Deletes this error bar from its chart series.

double

getAmount()

Gets the amount used by the error bar.

ErrorBarDirection

getDirection()

Gets the direction of this error bar.

EndStyleCap

getEndStyle()

Gets the end style for the error bar.

IChartFormat

getFormat()

Gets the IChartFormat object for this error bar.

String

getMinus()

Gets the formula for the negative error amount when the error bar value type is ErrorBarType.Custom.

ISeries

getParent()

Gets the parent ISeries that contains this error bar.

String

getPlus()

Gets the formula for the positive error amount when the error bar value type is ErrorBarType.Custom.

ErrorBarInclude

getType()

Gets which parts of the error bar are included.

ErrorBarType

getValueType()

Gets how the error bar range is determined.

void

setAmount(double value)

Sets the amount used by the error bar.

void

setEndStyle(EndStyleCap value)

Sets the end style for the error bar.

void

setMinus(String value)

Sets the formula for the negative error amount when the error bar value type is ErrorBarType.Custom.

void

setPlus(String value)

Sets the formula for the positive error amount when the error bar value type is ErrorBarType.Custom.

void

setType(ErrorBarInclude value)

Sets which parts of the error bar are included.

void

setValueType(ErrorBarType value)

Sets how the error bar range is determined.

Method Details

getFormat

IChartFormat getFormat()

Gets the IChartFormat object for this error bar.

Use the returned format object to access and modify the appearance of the error bar, such as line color and line style.


 worksheet.getRange("A1:B4").setValue(new Object[][] {{"X", "Y"}, {1, 2}, {2, 4}, {3, 3}});
 IChart chart = worksheet.getShapes().addChart(ChartType.XYScatter, 20, 20, 300, 200).getChart();
 chart.getSeriesCollection().add(worksheet.getRange("A1:B4"));
 chart.getSeriesCollection().get(0).setHasErrorBars(true);
 IChartFormat format = chart.getSeriesCollection().get(0).getYErrorBar().getFormat();
 format.getLine().getColor().setRGB(Color.GetRed());

Returns:: The IChartFormat object for this error bar.

getParent

ISeries getParent()

Gets the parent ISeries that contains this error bar.

Use this method to access the chart series that owns the current error bar.


 worksheet.getRange("A1:B4").setValue(new Object[][] {{"X", "Y"}, {1, 2}, {2, 4}, {3, 3}});
 IChart chart = worksheet.getShapes().addChart(ChartType.XYScatter, 20, 20, 300, 200).getChart();
 chart.getSeriesCollection().add(worksheet.getRange("A1:B4"));
 chart.getSeriesCollection().get(0).setHasErrorBars(true);
 IErrorBar errorBar = chart.getSeriesCollection().get(0).getYErrorBar();
 ISeries parentSeries = errorBar.getParent();

Returns:: The parent ISeries of this error bar.

getDirection

ErrorBarDirection getDirection()

Gets the direction of this error bar.

The returned value indicates whether this error bar applies to X values or Y values in the chart series. For scatter series, error bars can exist in both directions.


 worksheet.getRange("A1:B4").setValue(new Object[][] {{"X", "Y"}, {1, 2}, {2, 4}, {3, 3}});
 IChart chart = worksheet.getShapes().addChart(ChartType.XYScatter, 20, 20, 300, 200).getChart();
 chart.getSeriesCollection().add(worksheet.getRange("A1:B4"));
 ISeries series = chart.getSeriesCollection().get(0);
 series.setHasErrorBars(true);
 ErrorBarDirection direction = series.getYErrorBar().getDirection();

Returns:: The ErrorBarDirection that specifies whether this error bar is for X values or Y values.

getValueType

ErrorBarType getValueType()

Gets how the error bar range is determined.

The returned ErrorBarType indicates whether the error bar uses a fixed value, percentage, standard deviation, standard error, or custom values.


 worksheet.getRange("A1:B4").setValue(new Object[][] {{"X", "Y"}, {1, 2}, {2, 4}, {3, 3}});
 IChart chart = worksheet.getShapes().addChart(ChartType.XYScatter, 20, 20, 300, 200).getChart();
 chart.getSeriesCollection().add(worksheet.getRange("A1:B4"));
 chart.getSeriesCollection().get(0).setHasErrorBars(true);
 IErrorBar errorBar = chart.getSeriesCollection().get(0).getYErrorBar();
 ErrorBarType valueType = errorBar.getValueType();

Returns:: The ErrorBarType that specifies how the error bar range is calculated.

setValueType

void setValueType(ErrorBarType value)

Sets how the error bar range is determined.

Use this method to choose whether the error bar uses a fixed value, percentage, standard deviation, standard error, or custom values.


 worksheet.getRange("A1:B4").setValue(new Object[][] {{"X", "Y"}, {1, 2}, {2, 4}, {3, 3}});
 IChart chart = worksheet.getShapes().addChart(ChartType.XYScatter, 20, 20, 300, 200).getChart();
 chart.getSeriesCollection().add(worksheet.getRange("A1:B4"));
 chart.getSeriesCollection().get(0).setHasErrorBars(true);
 IErrorBar errorBar = chart.getSeriesCollection().get(0).getYErrorBar();
 errorBar.setValueType(ErrorBarType.FixedValue);

Parameters:: value - The ErrorBarType that specifies how the error bar range is calculated.

getType

ErrorBarInclude getType()

Gets which parts of the error bar are included.

The returned ErrorBarInclude value specifies whether the error bar shows positive values, negative values, both, or no range.


 worksheet.getRange("A1:B4").setValue(new Object[][] {{"X", "Y"}, {1, 2}, {2, 4}, {3, 3}});
 IChart chart = worksheet.getShapes().addChart(ChartType.XYScatter, 20, 20, 300, 200).getChart();
 chart.getSeriesCollection().add(worksheet.getRange("A1:B4"));
 chart.getSeriesCollection().get(0).setHasErrorBars(true);
 IErrorBar errorBar = chart.getSeriesCollection().get(0).getYErrorBar();
 errorBar.setType(ErrorBarInclude.Both);
 ErrorBarInclude type = errorBar.getType();

Returns:: The ErrorBarInclude value that specifies which error-bar parts are included.

setType

void setType(ErrorBarInclude value)

Sets which parts of the error bar are included.

Use this method to specify whether the error bar shows positive values, negative values, both, or no range.


 worksheet.getRange("A1:B4").setValue(new Object[][] {{"X", "Y"}, {1, 2}, {2, 4}, {3, 3}});
 IChart chart = worksheet.getShapes().addChart(ChartType.XYScatter, 20, 20, 300, 200).getChart();
 chart.getSeriesCollection().add(worksheet.getRange("A1:B4"));
 chart.getSeriesCollection().get(0).setHasErrorBars(true);
 IErrorBar errorBar = chart.getSeriesCollection().get(0).getYErrorBar();
 errorBar.setType(ErrorBarInclude.Plus);

Parameters:: value - The ErrorBarInclude value that specifies which error-bar parts to include.

getAmount

double getAmount()

Gets the amount used by the error bar.

The meaning of the returned value depends on the current error bar value type. For example, it represents the fixed amount for ErrorBarType.FixedValue, the percentage value for ErrorBarType.Percentage, or the number of standard deviations for ErrorBarType.StDev. For custom error bars, use getPlus() and getMinus().


 worksheet.getRange("A1:B4").setValue(new Object[][] {{"X", "Y"}, {1, 2}, {2, 4}, {3, 3}});
 IChart chart = worksheet.getShapes().addChart(ChartType.XYScatter, 20, 20, 300, 200).getChart();
 chart.getSeriesCollection().add(worksheet.getRange("A1:B4"));
 chart.getSeriesCollection().get(0).setHasErrorBars(true);
 IErrorBar errorBar = chart.getSeriesCollection().get(0).getYErrorBar();
 errorBar.setValueType(ErrorBarType.FixedValue);
 errorBar.setAmount(0.5);
 double amount = errorBar.getAmount();

Returns:: The amount of the error bar.

setAmount

void setAmount(double value)

Sets the amount used by the error bar.

The meaning of the value depends on the current error bar value type. For example, it represents the fixed amount for ErrorBarType.FixedValue, the percentage value for ErrorBarType.Percentage, or the number of standard deviations for ErrorBarType.StDev. For custom error bars, use setPlus(String) and setMinus(String).


 worksheet.getRange("A1:B4").setValue(new Object[][] {{"X", "Y"}, {1, 2}, {2, 4}, {3, 3}});
 IChart chart = worksheet.getShapes().addChart(ChartType.XYScatter, 20, 20, 300, 200).getChart();
 chart.getSeriesCollection().add(worksheet.getRange("A1:B4"));
 chart.getSeriesCollection().get(0).setHasErrorBars(true);
 IErrorBar errorBar = chart.getSeriesCollection().get(0).getYErrorBar();
 errorBar.setValueType(ErrorBarType.FixedValue);
 errorBar.setAmount(100.0);

Parameters:: value - The amount of the error bar.

getPlus

String getPlus()

Gets the formula for the positive error amount when the error bar value type is ErrorBarType.Custom.

Use this method to retrieve the formula string that defines the positive custom error values for the error bar.


 worksheet.getRange("A1:C4").setValue(new Object[][] {{"X", "Y", "Plus"}, {1, 2, 0.2}, {2, 4, 0.4}, {3, 3, 0.3}});
 IChart chart = worksheet.getShapes().addChart(ChartType.XYScatter, 20, 20, 300, 200).getChart();
 chart.getSeriesCollection().add(worksheet.getRange("A1:B4"));
 chart.getSeriesCollection().get(0).setHasErrorBars(true);
 IErrorBar errorBar = chart.getSeriesCollection().get(0).getYErrorBar();
 errorBar.setValueType(ErrorBarType.Custom);
 errorBar.setPlus("=Sheet1!$C$2:$C$4");
 String formula = errorBar.getPlus();

Returns:: The formula string that specifies the positive error amount. Returns null if no positive custom error formula has been set.

setPlus

void setPlus(String value)

Sets the formula for the positive error amount when the error bar value type is ErrorBarType.Custom.

Use this method to set the formula string that defines the positive custom error values for the error bar.


 worksheet.getRange("A1:C4").setValue(new Object[][] {{"X", "Y", "Plus"}, {1, 2, 0.2}, {2, 4, 0.4}, {3, 3, 0.3}});
 IChart chart = worksheet.getShapes().addChart(ChartType.XYScatter, 20, 20, 300, 200).getChart();
 chart.getSeriesCollection().add(worksheet.getRange("A1:B4"));
 chart.getSeriesCollection().get(0).setHasErrorBars(true);
 IErrorBar errorBar = chart.getSeriesCollection().get(0).getYErrorBar();
 errorBar.setValueType(ErrorBarType.Custom);
 errorBar.setPlus("=Sheet1!$C$2:$C$4");

Parameters:: value - The formula string that specifies the positive error amount. Sets null if no positive custom error formula has been set.

getMinus

String getMinus()

Gets the formula for the negative error amount when the error bar value type is ErrorBarType.Custom.

Use this method to retrieve the formula string that defines the negative custom error values for the error bar.


 worksheet.getRange("A1:B4").setValue(new Object[][] {{"X", "Y"}, {1, 2}, {2, 4}, {3, 3}});
 IChart chart = worksheet.getShapes().addChart(ChartType.XYScatter, 20, 20, 300, 200).getChart();
 chart.getSeriesCollection().add(worksheet.getRange("A1:B4"));
 chart.getSeriesCollection().get(0).setHasErrorBars(true);
 IErrorBar errorBar = chart.getSeriesCollection().get(0).getYErrorBar();
 errorBar.setValueType(ErrorBarType.Custom);
 errorBar.setMinus("=Sheet1!$C$2:$C$4");
 String formula = errorBar.getMinus();

Returns:: The formula string for the negative custom error values. Returns null if no negative custom formula has been set.

setMinus

void setMinus(String value)

Sets the formula for the negative error amount when the error bar value type is ErrorBarType.Custom.

Use this method to set the formula string that defines the negative custom error values for the error bar.


 worksheet.getRange("A1:B4").setValue(new Object[][] {{"X", "Y"}, {1, 2}, {2, 4}, {3, 3}});
 IChart chart = worksheet.getShapes().addChart(ChartType.XYScatter, 20, 20, 300, 200).getChart();
 chart.getSeriesCollection().add(worksheet.getRange("A1:B4"));
 chart.getSeriesCollection().get(0).setHasErrorBars(true);
 IErrorBar errorBar = chart.getSeriesCollection().get(0).getYErrorBar();
 errorBar.setValueType(ErrorBarType.Custom);
 errorBar.setMinus("=Sheet1!$C$2:$C$4");

Parameters:: value - The formula string for the negative custom error values. Sets null if no negative custom formula has been set.

getEndStyle

EndStyleCap getEndStyle()

Gets the end style for the error bar.

The returned value specifies whether the error bar is displayed with caps at its ends.


 worksheet.getRange("A1:B4").setValue(new Object[][] {{"X", "Y"}, {1, 2}, {2, 4}, {3, 3}});
 IChart chart = worksheet.getShapes().addChart(ChartType.XYScatter, 20, 20, 300, 200).getChart();
 chart.getSeriesCollection().add(worksheet.getRange("A1:B4"));
 chart.getSeriesCollection().get(0).setHasErrorBars(true);
 chart.getSeriesCollection().get(0).getYErrorBar().setEndStyle(EndStyleCap.NoCap);
 EndStyleCap endStyle = chart.getSeriesCollection().get(0).getYErrorBar().getEndStyle();

Returns:: The end style of the error bar.

setEndStyle

void setEndStyle(EndStyleCap value)

Sets the end style for the error bar.

Use this method to specify whether caps are shown at the ends of the error bar lines.


 worksheet.getRange("A1:B4").setValue(new Object[][] {{"X", "Y"}, {1, 2}, {2, 4}, {3, 3}});
 IChart chart = worksheet.getShapes().addChart(ChartType.XYScatter, 20, 20, 300, 200).getChart();
 chart.getSeriesCollection().add(worksheet.getRange("A1:B4"));
 chart.getSeriesCollection().get(0).setHasErrorBars(true);
 IErrorBar errorBar = chart.getSeriesCollection().get(0).getYErrorBar();
 errorBar.setEndStyle(EndStyleCap.Cap);

Parameters:: value - The end style to apply to the error bar.

clearFormats

void clearFormats()

Clears the formatting of this error bar.

Use this method to remove custom formatting that has been applied to the error bar.


 worksheet.getRange("A1:B4").setValue(new Object[][] {{"X", "Y"}, {1, 2}, {2, 4}, {3, 3}});
 IChart chart = worksheet.getShapes().addChart(ChartType.XYScatter, 20, 20, 300, 200).getChart();
 chart.getSeriesCollection().add(worksheet.getRange("A1:B4"));
 chart.getSeriesCollection().get(0).setHasErrorBars(true);
 IErrorBar errorBar = chart.getSeriesCollection().get(0).getYErrorBar();
 errorBar.getFormat().getLine().getColor().setRGB(Color.GetRed());
 errorBar.clearFormats();

delete

void delete()

Deletes this error bar from its chart series.

Use this method to remove an existing X or Y error bar that was obtained from a series.


 worksheet.getRange("A1:B3").setValue(new Object[][] {
     {"Month", "Sales"},
     {"Jan", 10},
     {"Feb", 12}
 });
 IChart chart = worksheet.getShapes().addChart(ChartType.ColumnClustered, 20, 20, 300, 200).getChart();
 chart.getSeriesCollection().add(worksheet.getRange("A1:B3"), RowCol.Columns, true, true);
 ISeries series = chart.getSeriesCollection().get(0);
 series.setHasErrorBars(true);
 IErrorBar errorBar = series.getYErrorBar();
 errorBar.delete();