Chart

Chart — Aspose.Cells FOSS for Python API Reference

aspose-cells-foss supports embedding charts in worksheets. Charts are managed through ws.charts, a ChartCollection attached to each Worksheet. Series data is added through chart.n_series, an NSeries collection.

Package: aspose.cells_foss

from aspose.cells_foss import ChartType

ChartType

ChartType is an IntEnum that identifies the chart type.

Member	Value	Notes
`LINE`	0	Fully supported for save.
`BAR`	1	Fully supported for save.
`PIE`	2	Fully supported for save.
`AREA`	3	Fully supported for save.
`BOX_WHISKER`	4	Saved using chartEx format.
`WATERFALL`	5	Saved using chartEx format.
`COMBO`	6	Raises `NotImplementedError` on save.
`SCATTER`	7	Raises `NotImplementedError` on save.
`STOCK`	8	Fully supported for save.
`SURFACE`	9	Raises `NotImplementedError` on save.
`RADAR`	10	Raises `NotImplementedError` on save.
`TREEMAP`	11	Raises `NotImplementedError` on save.
`SUNBURST`	12	Raises `NotImplementedError` on save.
`HISTOGRAM`	13	Raises `NotImplementedError` on save.
`FUNNEL`	14	Raises `NotImplementedError` on save.
`MAP`	15	Raises `NotImplementedError` on save.

Chart

Chart objects are not constructed directly. Use ws.charts.add(...) or the typed convenience methods (add_bar(), add_line(), add_pie(), add_area()).

Properties

Property	Type	Access	Description
`type`	`ChartType`	Read	Chart type set at creation time.
`title`	`str \| None`	Read/Write	Chart title text. Set to `None` to remove the title.
`category_data`	`str \| None`	Read/Write	Range string for shared category axis data, e.g. `"Sheet1!A1:A5"`.
`n_series`	`NSeries`	Read	Collection of data series.
`show_legend`	`bool`	Read/Write	`True` (default) to display the chart legend.
`legend_position`	`str`	Read/Write	Legend placement: `'right'`, `'left'`, `'top'`, `'bottom'`, `'top_right'` (also accepts short forms `'r'`, `'l'`, `'t'`, `'b'`, `'tr'`).
`smooth`	`bool`	Read/Write	`True` to use smooth (spline) lines on line charts.
`grouping`	`str`	Read/Write	Series grouping: `'standard'`, `'stacked'`, `'percentStacked'`, `'clustered'`.
`bar_direction`	`str`	Read/Write	For `BAR` charts: `'bar'` (horizontal) or `'col'` (vertical/column).
`gap_width`	`int`	Read/Write	Gap between bar/column clusters, 0–500 (default 150).
`overlap`	`int`	Read/Write	Series overlap percentage, -100 to 100 (default 0).
`vary_colors`	`bool`	Read/Write	`True` to assign a distinct color to each data point.
`first_slice_angle`	`int`	Read/Write	Starting angle for the first pie slice, 0–360 degrees.
`is_3d`	`bool`	Read/Write	`True` to enable 3D rendering.
`view_3d`	`ChartView3D`	Read	3D rotation and perspective settings.
`axes`	`list[ChartAxis]`	Read	List of chart axes.
`upper_left_row`	`int`	Read	0-based row index of the chart’s top-left anchor cell.
`upper_left_column`	`int`	Read	0-based column index of the chart’s top-left anchor cell.
`lower_right_row`	`int`	Read	0-based row index of the chart’s bottom-right anchor cell.
`lower_right_column`	`int`	Read	0-based column index of the chart’s bottom-right anchor cell.

ChartCollection

ChartCollection is accessed as ws.charts. It contains all charts embedded in a worksheet.

Methods

add

ws.charts.add(
    chart_type: ChartType,
    upper_left_row: int,
    upper_left_column: int,
    lower_right_row: int,
    lower_right_column: int
) -> Chart

Adds a chart of the specified type. All position arguments are 0-based row/column indices.

add_bar

ws.charts.add_bar(upper_left_row, upper_left_column, lower_right_row, lower_right_column) -> Chart

Shortcut for add(ChartType.BAR, ...).

add_line

ws.charts.add_line(upper_left_row, upper_left_column, lower_right_row, lower_right_column) -> Chart

Shortcut for add(ChartType.LINE, ...).

add_pie

ws.charts.add_pie(upper_left_row, upper_left_column, lower_right_row, lower_right_column) -> Chart

Shortcut for add(ChartType.PIE, ...).

add_area

ws.charts.add_area(upper_left_row, upper_left_column, lower_right_row, lower_right_column) -> Chart

Shortcut for add(ChartType.AREA, ...).

Properties and Iteration

Member	Description
`count`	Number of charts in the collection (read-only).
`__len__()`	Returns `count`.
`__iter__()`	Iterates over all `Chart` objects.
`__getitem__(index)`	Returns the `Chart` at zero-based `index`.

NSeries

NSeries is accessed via chart.n_series. It manages the data series belonging to a chart.

Methods

add

chart.n_series.add(
    area: str,
    is_vertical: bool = False,
    category_data: str | None = None,
    name: str | None = None,
    chart_type: ChartType | None = None
) -> ChartSeries

Adds a data series. area is a range string such as "Sheet1!B1:B5". Set is_vertical=True when data is arranged in columns. chart_type overrides the parent chart type for this series (used in combo charts).

Properties and Iteration

Member	Description
`count`	Number of series (read-only).
`__len__()`	Returns `count`.
`__iter__()`	Iterates over all `ChartSeries` objects.
`__getitem__(index)`	Returns the `ChartSeries` at zero-based `index`.

ChartSeries

ChartSeries represents a single data series within a chart. Obtained via chart.n_series[index].

Properties

Property	Type	Description
`values`	`str`	Range string for the Y-value data (e.g., `"Sheet1!B2:B6"`).
`category_data`	`str`	Range string for the category/X-axis labels for this series.
`name`	`str \| None`	Series name, shown in the legend.
`chart_type`	`ChartType \| None`	Override chart type for this series (combo charts).
`x_values`	`str`	Range string for scatter-chart X values.
`error_bars`	`ChartErrorBars \| None`	Error bar settings, or `None` if not added. Read-only; call `add_error_bars()` to create.
`smooth`	`bool`	`True` to use smooth lines for this series.

Methods

add_error_bars

series.add_error_bars(
    direction='y',
    bar_type='both',
    val_type='fixedVal',
    val=1.0,
    no_end_cap=False
) -> ChartErrorBars

Adds error bars to this series and returns the ChartErrorBars object.

Parameter	Values
`direction`	`'x'`, `'y'`, `'xy'`
`bar_type`	`'both'`, `'minus'`, `'plus'`
`val_type`	`'fixedVal'`, `'percentage'`, `'stdDev'`, `'stdErr'`

ChartAxis

ChartAxis is accessed via chart.axes[index].

Properties

Property	Type	Description
`title`	`str \| None`	Axis title text.
`number_format`	`str \| None`	Number format code applied to axis tick labels.
`minimum_scale`	`float \| None`	Minimum axis value. `None` uses auto-scaling.
`maximum_scale`	`float \| None`	Maximum axis value. `None` uses auto-scaling.
`major_unit`	`float \| None`	Interval between major gridlines/ticks.
`minor_unit`	`float \| None`	Interval between minor gridlines/ticks.
`is_logarithmic`	`bool`	`True` to use a logarithmic scale.
`log_base`	`float`	Base of the logarithm when `is_logarithmic` is `True`.
`crosses`	`str`	Where this axis crosses the perpendicular axis: `'autoZero'`, `'min'`, `'max'`.
`crosses_at`	`float \| None`	Specific value where this axis crosses, when `crosses` is set accordingly.
`reverse_order`	`bool`	`True` to reverse the axis direction.
`axis_type`	`str`	Axis category type: `'catAx'`, `'valAx'`, `'dateAx'`, `'serAx'`.
`orientation`	`str`	`'minMax'` for normal direction, `'maxMin'` for reversed.

ChartView3D

ChartView3D is accessed via chart.view_3d. Applies only when chart.is_3d is True.

Properties

Property	Type	Description
`rotation_x`	`int`	X-axis rotation (elevation), 0–90 degrees.
`rotation_y`	`int`	Y-axis rotation, 0–360 degrees.
`right_angle_axes`	`bool`	`True` to use right-angle axes (isometric view).
`perspective`	`int`	Perspective distortion, 0–100. Ignored when `right_angle_axes` is `True`.
`height_percent`	`int`	Chart height as a percentage of the base, 5–500.
`depth_percent`	`int`	Chart depth as a percentage of the base, 20–2000.

ChartErrorBars

ChartErrorBars is accessed via series.error_bars. Create with series.add_error_bars(...).

Properties

Property	Type	Description
`direction`	`str`	Error bar direction: `'x'`, `'y'`, `'xy'`.
`bar_type`	`str`	Which bars to show: `'both'`, `'minus'`, `'plus'`.
`val_type`	`str`	Value type: `'fixedVal'`, `'percentage'`, `'stdDev'`, `'stdErr'`.
`val`	`float`	Fixed or percentage value used when `val_type` is `'fixedVal'` or `'percentage'`.
`no_end_cap`	`bool`	`True` to omit the end-cap line on error bars.
`plus_formula`	`str \| None`	Custom range formula for positive error values.
`minus_formula`	`str \| None`	Custom range formula for negative error values.
`line_width`	`int \| None`	Error bar line width in EMUs.
`line_color`	`str \| None`	Error bar color as RRGGBB hex.

Example

The following example writes monthly revenue data, creates a clustered bar chart with a title and two data series, and saves the workbook.

from aspose.cells_foss import Workbook, ChartType

wb = Workbook()
ws = wb.worksheets[0]
ws.name = "Revenue"

# Write headers and data
headers = ["Month", "Product A", "Product B"]
data = [
    ["Jan", 12000, 9500],
    ["Feb", 14500, 11000],
    ["Mar", 13200, 12800],
    ["Apr", 15800, 14100],
]
for col, h in enumerate(headers):
    ws.cells[0][col].put_value(h)
for row, row_data in enumerate(data, start=1):
    for col, val in enumerate(row_data):
        ws.cells[row][col].put_value(val)

# Add a bar chart covering rows 6-20, columns 0-6
chart = ws.charts.add_bar(6, 0, 20, 6)
chart.title = "Monthly Revenue by Product"
chart.bar_direction = "col"   # vertical (column chart)
chart.grouping = "clustered"

# Series: Product A and Product B
chart.n_series.add("Revenue!B2:B5", is_vertical=True, category_data="Revenue!A2:A5", name="Product A")
chart.n_series.add("Revenue!C2:C5", is_vertical=True, category_data="Revenue!A2:A5", name="Product B")

chart.show_legend = True
chart.legend_position = "bottom"

wb.save("revenue_chart.xlsx")

Chart — Aspose.Cells FOSS for Python API Reference

ChartType

Chart

Properties

ChartCollection

Methods

add

add_bar

add_line

add_pie

add_area

Properties and Iteration

NSeries

Methods

add

Properties and Iteration

ChartSeries

Properties

Methods

add_error_bars

ChartAxis

Properties

ChartView3D

Properties

ChartErrorBars

Properties

Example

See Also