CategoryChartData
Accumulates data specifying categories and series values for a chart. Used as a parameter in shapes.add_chart() and Chart.replace_data().
Suitable for category charts (those with discrete category labels). Each data point specifies only the Y value; the X value is inferred by position.
Methods
Create a new CategoryChartData instance.Excel number format string (e.g., ’#,##0.0’)
from pptx.chart.data import CategoryChartData
chart_data = CategoryChartData()
chart_data.categories = ['Q1', 'Q2', 'Q3', 'Q4']
chart_data.add_series('Revenue', (10.5, 20.3, 30.1, 40.8))
Return newly created Category object appended to the category collection.label
str | number | datetime.date | datetime.datetime
required
Category label. All labels must be the same type.
chart_data.add_category('East')
chart_data.add_category('West')
add_series(name, values, number_format)
Add a series to this data set.Series name (appears in legend)
Iterable of numeric values
Excel number format for this series
chart_data.add_series('Revenue', (42, 38, 51, 47))
chart_data.add_series('Costs', (31, 29, 38, 35), number_format='#,##0')
Properties
Categories object providing access to category-object hierarchy. Assigning an iterable of labels replaces the Categories object.chart_data.categories = ['North', 'South', 'East', 'West']
# or use date categories
from datetime import date
chart_data.categories = [date(2024, 1, 1), date(2024, 2, 1)]
Excel number format template string. Can be overridden per series or data point.chart_data.number_format = '#,##0.00'
XyChartData
Specialized ChartData for XY (scatter) charts. Has no category sequence. Each data point specifies both X and Y values.
Methods
Create a new XyChartData instance.Excel number format string
from pptx.chart.data import XyChartData
chart_data = XyChartData()
series = chart_data.add_series('Series 1')
series.add_data_point(1.5, 10.2)
series.add_data_point(2.3, 15.7)
add_series(name, number_format)
Return XySeriesData object newly created and added at the end of this sequence.Excel number format for this series
series = chart_data.add_series('Temperature vs Time')
series.add_data_point(0, 20.5)
series.add_data_point(1, 22.3)
BubbleChartData
Specialized ChartData for bubble charts. Essentially an XY chart where markers are scaled to provide a third quantitative dimension.
Methods
Create a new BubbleChartData instance.Excel number format string
from pptx.chart.data import BubbleChartData
chart_data = BubbleChartData()
series = chart_data.add_series('Product A')
series.add_data_point(10, 50, 1000) # x, y, size
add_series(name, number_format)
Return BubbleSeriesData object newly created and added to this sequence.Excel number format for this series
series = chart_data.add_series('Market Share')
series.add_data_point(25, 75, 5000) # x=price, y=sales, size=profit
Categories
Sequence of Category objects with hierarchical graph behaviors for multi-level categories.
Methods
Return newly created Category object appended to the end of this sequence.label
str | number | datetime.date | datetime.datetime
required
Category label. All labels must be the same type.
categories = chart_data.categories
cat1 = categories.add_category('Q1')
cat1.add_sub_category('Jan')
cat1.add_sub_category('Feb')
Properties
True if first category has a date label (datetime.date or datetime.datetime). Returns False for hierarchical categories.if chart_data.categories.are_dates:
print("Using date axis")
True if first category has a numeric label (including dates). Returns False for hierarchical categories.
Number of hierarchy levels in this category graph. Returns 0 if it contains no categories.if chart_data.categories.depth > 1:
print("Multi-level categories")
Number of leaf-level categories in this hierarchy. Same as len() only when hierarchy is single level.
Excel number format string. Only relevant for numeric or date categories. Assigning None uses default format.categories.number_format = 'mm/dd/yyyy'
Category
Chart category with a label for the category axis. Can be configured in a hierarchy for multi-level categories.
Methods
Return newly created Category object appended to the sub-category sequence.quarter = chart_data.categories.add_category('Q1')
quarter.add_sub_category('January')
quarter.add_sub_category('February')
quarter.add_sub_category('March')
Properties
label
str | number | datetime.date | datetime.datetime
Value that appears on the axis for this category. Can be a string, number, or date.category.label # Read-only access to label
Sequence of child categories for this category.for sub_cat in category.sub_categories:
print(sub_cat.label)
XySeriesData
Data for a particular XY chart series. The sequence of data points is significant; lines follow the sequence even if that causes backward movement.
Methods
add_data_point(x, y, number_format)
Return XyDataPoint object newly created with values x and y, appended to this sequence.X value for this data point
Y value for this data point
Excel number format for this point
series = chart_data.add_series('Temperature')
series.add_data_point(0.0, 20.5)
series.add_data_point(1.0, 22.3)
series.add_data_point(2.0, 21.8)
Properties
Name of this series (column heading for y-values, appears in legend).
Formatting template for numbers in this series. Inherits from chart data if not specified.
Sequence containing the X value of each datapoint in this series.x_vals = series.x_values # [0.0, 1.0, 2.0]
Sequence containing the Y value of each datapoint in this series.
BubbleSeriesData
Data for a particular Bubble chart series. Extends XySeriesData with bubble size.
Methods
add_data_point(x, y, size, number_format)
Append new BubbleDataPoint with values x, y, and size.X value for this data point
Y value for this data point
Bubble size for this data point
Excel number format for Y value
series = chart_data.add_series('Product Performance')
series.add_data_point(25, 75, 5000) # price, sales, profit
series.add_data_point(30, 65, 4500)
Properties
Sequence containing the bubble size for each datapoint in this series.sizes = series.bubble_sizes # [5000, 4500]