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_directiondecides 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.
Whether the grid’s first row or column holds the X values every series shares. It’s
trueby default; whenfalse, 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_gridis supported: that is the value always written, and any other value is ignored, so the grid inrowsis 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
rowsis empty or omitted, the chart keeps the placeholder data it was created with.
-
field plot_direction : PlotDirection | None =
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_directiondecides 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 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.
-
field empty : Literal[True] | None =
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
rowsis what is read, whatever this value is.A field accepts a member or its value, so
ChartDataSource.CHART_DATA_GRIDand'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
rowsis used either way.
-
CHART_DATA_GRID =
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_SERIESand'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_labelsname the series androw_labelsname the categories.
-
ROWS_AS_SERIES =
'rows_as_series'¶ Each row of the grid is a series, so
row_labelsname the series andcolumn_labelsname the categories.
-
COLUMNS_AS_SERIES =
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, andlabel_duration_formatapplies.text,boolean, andbasehave no equivalent for chart labels and behave likenumber, 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_typeisdate_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_typeisduration. 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_formatinstead. On a stacked chart whose value axis has aChartValueAxis.scaleofpercent, 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_typeiscurrency. It takes the place oflabel_number_formatfor 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.
nullclears the fill; omitting the key inherits it from the chart’s style. It’s ignored whenfill_reuse_rulesderives 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_strokeinstead): 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
nonefor 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 thannonealso 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.
nullclears 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
0is 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_rulescontainsseries_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, orcurved. 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:
0for the primary axis and1for 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.
-
field label_format_type : FormatType | None =
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.NONEand'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'¶
-
NONE =
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.AREAand'area'are the same. The member’s name as a string isn’t accepted.-
AREA =
'area'¶
-
COLUMN =
'column'¶
-
LINE =
'line'¶
-
AREA =
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:
noneturns 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.CIRCLEand'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.
-
CIRCLE =
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:
noneremoves 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.CURVEDand'curved'are the same. The member’s name as a string isn’t accepted.-
CURVED =
'curved'¶
-
NONE =
'none'¶
-
STRAIGHT =
'straight'¶
-
CURVED =
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_STROKEand'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'¶
-
SERIES_FILL_USE_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
insideandoutside, and anything else (autoincluded) comes out as the automatic centered placement.A field accepts a member or its value, so
SeriesValueLabelPosition.AUTOand'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'¶
-
AUTO =
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.positionis the offset from the center of the chart’s plot area to the legend’s top-left corner, so either coordinate can be negative, andGeometry.sizeis its width and height.Geometry.angle,Geometry.flip_horizontally,Geometry.width_valid, andGeometry.height_validdon’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.
-
field geometry : Geometry | None =