Chart data and series

Supply a chart’s data, and style the series it plots and its legend.

ChartData

class creator_studio_doc_format.core.ChartData(*, preset_identifier='', plot_direction=None, shared_xvalues=True, chart_data_source, column_labels=None, row_labels=None, rows=None, **extra_data)[source]

The chart’s data as a grid of cells, together with how that grid maps onto the chart.

plot_direction decides whether the grid’s rows or its columns become the series; the labels along the other direction name the categories.

field plot_direction : PlotDirection | None = None

Whether the rows or the columns of the data grid become the chart’s series. When omitted, the direction preferred by the chart type is kept.

field shared_xvalues : bool = True

Whether the grid’s first row or column holds the X values every series shares. It’s true by default; when false, each series carries its own X values. Y values, and a bubble series’ size values, follow in either case. Only scatter and bubble charts use it; other chart types ignore it.

field chart_data_source : ChartDataSource [Required]

The source of the chart’s data. Only chart_data_grid is supported: that is the value always written, and any other value is ignored, so the grid in rows is used either way.

field column_labels : list[str] | None = None

The names of the grid’s columns. The number of columns comes from the longest row of rows, so extra names are dropped and missing names become empty.

field row_labels : list[str] | None = None

The names of the grid’s rows. The number of rows comes from rows, so extra names are dropped and missing names become empty.

field rows : list[ChartDataRow] | None = None

The grid’s data rows. The grid is made rectangular: it takes the length of the longest row, and shorter rows are padded with empty cells. When rows is empty or omitted, the chart keeps the placeholder data it was created with.

ChartDataRow

class creator_studio_doc_format.core.ChartDataRow(*, preset_identifier='', values, **extra_data)[source]

One row of the chart’s data grid, holding its cells in column order.

A row isn’t necessarily a series: plot_direction decides whether rows or columns become the chart’s series. Rows need not be the same length, because the grid is padded out to its longest row.

field values : list[ChartDataValue] [Required]

The row’s cells, in column order. Rows need not be the same length: a short row is padded with empty cells to the length of the longest row.

ChartDataValue

class creator_studio_doc_format.core.ChartDataValue(*, preset_identifier='', date=None, duration=None, empty=None, number=None, **extra_data)[source]

A single value in the chart’s data grid.

A value is a number, a date, or a duration; a cell holding anything else, text included, is read as empty.

field date : Date | None = None

A cell holding a date.

field duration : Duration | None = None

A cell holding a length of time.

field empty : Literal[True] | None = None

An empty cell. Any cell that doesn’t hold a number, a date, or a duration is written as empty.

field number : float | None = None

A cell holding a number.

ChartDataSource

class creator_studio_doc_format.core.ChartDataSource(str, Enum)[source]

The stated source of a chart’s values.

It’s recorded for provenance only: the grid in rows is what is read, whatever this value is.

A field accepts a member or its value, so ChartDataSource.CHART_DATA_GRID and 'chart_data_grid' are the same. The member’s name as a string isn’t accepted.

CHART_DATA_GRID = 'chart_data_grid'

The chart’s data is the grid carried in rows. This is the only supported source, and the only value ever written.

TABLE_FORMULA_REFERENCES = 'table_formula_references'

Reserved for data drawn from table formula references and expressions. Not supported, and never written.

UNINITIALIZED = 'uninitialized'

A value for a chart whose data source hasn’t been set. It’s never written and, like every other value of this property, has no effect: the grid in rows is used either way.

PlotDirection

class creator_studio_doc_format.core.PlotDirection(str, Enum)[source]

The direction in which the data grid is read to produce the chart’s series.

A field accepts a member or its value, so PlotDirection.COLUMNS_AS_SERIES and 'columns_as_series' are the same. The member’s name as a string isn’t accepted.

COLUMNS_AS_SERIES = 'columns_as_series'

Each column of the grid is a series, so column_labels name the series and row_labels name the categories.

ROWS_AS_SERIES = 'rows_as_series'

Each row of the grid is a series, so row_labels name the series and column_labels name the categories.

ChartSeries

class creator_studio_doc_format.core.ChartSeries(*, preset_identifier='', label_format_type=None, label_date_format=None, label_duration_format=None, label_number_format=None, label_currency_format=None, series_index=None, show_value_labels=False, value_label_position=None, value_label_text_style=None, value_label_outside_text_style=None, fill=Override.not_set(), stroke=None, symbol_type=None, symbol_stroke=None, symbol_fill=Override.not_set(), symbol_size=None, fill_reuse_rules=None, fill_use_series_stroke_alpha_multiplier=None, connection_line_type=None, value_labels_selection=None, show_negative_data=False, mixed_series_type=None, y_axis_selection=None, **extra_data)[source]

The appearance and label formatting of one of a chart’s data series.

It covers the series’ fill, stroke, data symbols, connecting line, and value labels; the plotted values come from the chart’s data grid. Many properties apply only to certain chart types and are ignored on the rest.

field label_format_type : FormatType | None = None

The kind of formatting applied to the label’s value. It also selects which of label_number_format, label_currency_format, label_date_format, and label_duration_format applies. text, boolean, and base have no equivalent for chart labels and behave like number, which is also what omitting this property means.

field label_date_format : DateTimeFormat | None = None

The date and time format of the label, used when label_format_type is date_time. An empty format string is treated as no format at all and isn’t preserved.

field label_duration_format : DurationFormat | None = None

The label’s duration format, used when label_format_type is duration. It covers automatic units, the smallest and largest unit, and the style.

field label_number_format : NumberFormat | None = None

The decimal places, negative-number style, and thousands separator of the label, used for number, percentage, and scientific labels. A value of 253 for decimal places means automatic. It’s omitted for fraction, base, and custom labels, which have none of these attributes; a prefix or suffix, a fraction accuracy, and a custom format string aren’t preserved. Currency labels use label_currency_format instead. On a stacked chart whose value axis has a ChartValueAxis.scale of percent, the value labels of each series don’t use this format, and their decimal places, negative-number style, and thousands separator aren’t preserved.

field label_currency_format : CurrencyFormat | None = None

The currency code, accounting style, decimal places, negative-number style, and thousands separator of the label, used when label_format_type is currency. It takes the place of label_number_format for currency labels, and it’s what preserves the currency code; a prefix or suffix and a custom format string aren’t preserved.

field series_index : int | None = None

The zero-based index of the data series this entry applies to. If it’s omitted, the entry’s own position in the series array is used; an entry whose index is negative or past the last series in the data is ignored rather than treated as an error.

field show_value_labels : bool = False

Whether each data point in this series is labeled with its value.

field value_label_position : SeriesValueLabelPosition | None = None

The position of a data point’s value label relative to the point. Not every chart type offers every position, and a position that isn’t one of the values listed here isn’t preserved.

field value_label_text_style : ParagraphProperties | None = None

The text style of value labels drawn inside the series element.

field value_label_outside_text_style : ParagraphProperties | None = None

The text style of value labels drawn outside the series element.

field fill : Override[Fill] = Override.not_set()

The fill of the series’ bars, columns, wedges, or area. null clears the fill; omitting the key inherits it from the chart’s style. It’s ignored when fill_reuse_rules derives the fill from another color instead.

field stroke : Stroke | None = None

The stroke of the series’ line, or of the border of its bars, columns, or wedges. Bubble series have no such stroke (see symbol_stroke instead): a stroke supplied for one is ignored and isn’t preserved.

field symbol_type : SeriesSymbolType | None = None

The shape of the data symbol drawn at each data point, or none for no data symbol. Data symbols exist only on 2D line, area, scatter, radar, and mixed line or area series, not on bubble or 3D series. Setting any shape other than none also turns data symbols on.

field symbol_stroke : Stroke | None = None

The stroke of the data symbols drawn at each data point. It applies only to series that draw data symbols, which for this purpose include bubbles.

field symbol_fill : Override[Fill] = Override.not_set()

The fill of the data symbols drawn at each data point. null clears the fill; omitting the key inherits it from the chart’s style. It applies only to series that draw data symbols, which for this purpose include bubbles.

field symbol_size : float | None = None

The size of the data symbols drawn at each data point, in points. Bubble series have no data symbol size, because a bubble is sized from its data value; a size of 0 is treated as unset and isn’t preserved.

field fill_reuse_rules : list[Annotated[FillReuseRule, Strict(False)]] | None = None

The rules that derive the data symbol or series fill from another of the series’ colors instead of an explicit fill.

field fill_use_series_stroke_alpha_multiplier : float | None = None

The alpha applied to the series stroke color to derive the series fill when fill_reuse_rules contains series_fill_use_series_stroke. It’s ignored otherwise.

field connection_line_type : ConnectionLineType | None = None

The style of the line joining this series’ data points: none, straight, or curved. It applies only to series that draw a joining line, such as line, scatter, bubble, and radar series.

field value_labels_selection : ValueLabelsSelection | None = None

The values of a data point that appear in its value label on a bubble or scatter chart. It’s ignored by other chart types; combinations other than the ones listed here aren’t preserved.

field show_negative_data : bool = False

Whether a bubble chart shows a bubble for a negative value, sized from the value’s magnitude. When it’s false, negative values aren’t plotted. It’s ignored by other chart types.

field mixed_series_type : MixedSeriesType | None = None

The shape of this series on a mixed or two-axis chart: columns, a line, or an area. It’s ignored by other chart types.

field y_axis_selection : int | None = None

The value axis this series is plotted against on a two-axis chart: 0 for the primary axis and 1 for the secondary axis. It’s ignored by other chart types. It’s always written for a two-axis chart, including 0, because omitting the key leaves the series on its default axis, which is the secondary axis for every series after the first.

ValueLabelsSelection

class creator_studio_doc_format.core.ValueLabelsSelection(str, Enum)[source]

The values of a data point that appear in its value label.

It applies only to bubble and scatter charts.

A field accepts a member or its value, so ValueLabelsSelection.NONE and 'none' are the same. The member’s name as a string isn’t accepted.

NONE = 'none'
SIZE = 'size'
X = 'x'
X_AND_Y = 'x_and_y'
Y = 'y'

MixedSeriesType

class creator_studio_doc_format.core.MixedSeriesType(str, Enum)[source]

The shape a single series takes on a mixed or two-axis chart.

Each series on these charts can take a different shape, and these are the only chart types that read this value. The choice also determines which of the series’ other style properties apply, since a series drawn as columns has neither data symbols nor a connecting line.

A field accepts a member or its value, so MixedSeriesType.AREA and 'area' are the same. The member’s name as a string isn’t accepted.

AREA = 'area'
COLUMN = 'column'
LINE = 'line'

SeriesSymbolType

class creator_studio_doc_format.core.SeriesSymbolType(str, Enum)[source]

The shape of the data symbol drawn at each of a series’ data points.

It also sets whether data symbols are drawn at all: none turns them off, and any other case turns them on. Only a series that draws an editable data symbol uses it; a bubble series doesn’t, because its circles are sized from the data.

A field accepts a member or its value, so SeriesSymbolType.CIRCLE and 'circle' are the same. The member’s name as a string isn’t accepted.

CIRCLE = 'circle'
DIAMOND = 'diamond'
NONE = 'none'
PLUS = 'plus'
SQUARE = 'square'
TRIANGLE = 'triangle'
X = 'x'
YIELD = 'yield'

A triangle pointing the opposite way from triangle, apex toward the bottom.

ConnectionLineType

class creator_studio_doc_format.core.ConnectionLineType(str, Enum)[source]

The style of the line drawn through a series’ data points.

It also sets whether a line is drawn at all: none removes the line rather than falling back to a default. Only a series that joins its points with a line uses it; elsewhere the value is ignored and isn’t written back out.

A field accepts a member or its value, so ConnectionLineType.CURVED and 'curved' are the same. The member’s name as a string isn’t accepted.

CURVED = 'curved'
NONE = 'none'
STRAIGHT = 'straight'

FillReuseRule

class creator_studio_doc_format.core.FillReuseRule(str, Enum)[source]

A rule that reuses one of a series’ own colors in place of an explicit fill.

It lets data symbols track the series’ fill or stroke instead of carrying a color of their own.

A field accepts a member or its value, so FillReuseRule.SERIES_FILL_USE_SERIES_STROKE and 'series_fill_use_series_stroke' are the same. The member’s name as a string isn’t accepted.

SERIES_FILL_USE_SERIES_STROKE = 'series_fill_use_series_stroke'
SYMBOL_FILL_USES_SERIES_FILL = 'symbol_fill_uses_series_fill'
SYMBOL_FILL_USES_SERIES_STROKE = 'symbol_fill_uses_series_stroke'

SeriesValueLabelPosition

class creator_studio_doc_format.core.SeriesValueLabelPosition(str, Enum)[source]

The position of a data point’s value label, for a series that shows value labels.

Each chart type uses only the placements that suit it and replaces any other with one it supports. A pie wedge or donut segment, for instance, keeps inside and outside, and anything else (auto included) comes out as the automatic centered placement.

A field accepts a member or its value, so SeriesValueLabelPosition.AUTO and 'auto' are the same. The member’s name as a string isn’t accepted.

AUTO = 'auto'
BOTTOM = 'bottom'
BOTTOM_LEFT = 'bottom_left'
BOTTOM_RIGHT = 'bottom_right'
CENTER = 'center'
INSIDE = 'inside'
INSIDE_BOTTOM = 'inside_bottom'
INSIDE_LEFT = 'inside_left'
INSIDE_RIGHT = 'inside_right'
INSIDE_TOP = 'inside_top'
LEFT = 'left'
OUTSIDE = 'outside'
OUTSIDE_TOP = 'outside_top'
RIGHT = 'right'
TOP = 'top'
TOP_LEFT = 'top_left'
TOP_RIGHT = 'top_right'

ChartLegend

class creator_studio_doc_format.core.ChartLegend(*, preset_identifier='', geometry=None, label_text_style=None, **extra_data)[source]

The legend of a chart.

Its position is an offset from the center of the plot area rather than a position on the slide. Whether it’s shown is set by ChartCommon.show_legend, and its entry labels come from the chart’s series.

field geometry : Geometry | None = None

The legend’s position and size. Geometry.position is the offset from the center of the chart’s plot area to the legend’s top-left corner, so either coordinate can be negative, and Geometry.size is its width and height. Geometry.angle, Geometry.flip_horizontally, Geometry.width_valid, and Geometry.height_valid don’t apply to a legend and aren’t preserved.

field label_text_style : ParagraphProperties | None = None

The text style of the legend labels, such as their font, size, and alignment.