Chart types

AbstractChart

Supertype for charts read from a workbook. Two concrete subtypes exist: Chart for the standard c: schema, and ChartEx for the newer cx: schema used by waterfall, funnel, treemap, sunburst, histogram, Pareto, box & whisker and region map charts.

Chart

A handle to one c: chart part. It holds the part's identity and anchor only; everything else is read from the current part on each call, so a Chart never goes stale and setters return it unchanged.

Fields

• package — the XLSXFile the part belongs to.
• path — package path, e.g. "xl/charts/chart1.xml".
• name — part name without extension, e.g. "chart1".
• rId — relationship id of the chart within its drawing part, if resolved.
• sheet — name of the sheet the chart is anchored to, if resolved.
• from, to — anchor cell references as strings, following getImages.

Content is reached through accessors: getChartTitle, getChartTypes, getChartSeries, getChartData and the rest of the chart API. The values they return carry keys, so they remain valid arguments after later writes; see ChartSeries.

ChartEx

A handle to one chartEx part: a chart in the Microsoft cx: namespace (http://schemas.microsoft.com/office/drawing/2014/chartex), used by Excel for waterfall, funnel, treemap, sunburst, histogram, Pareto, box & whisker and region map charts. Charts in the ECMA-376 c: namespace are Chart.

A ChartEx holds only the part's identity and its anchor. Its content (layout, data references, title) is read from the part on each call, so a ChartEx remains valid after the part is written to.

Fields

• package - the XLSXFile containing the chart.
• path - package path, e.g. "xl/charts/chartEx1.xml".
• name - part name without extension, e.g. "chartEx1".
• rId - relationship id of the chart within its drawing part, if resolved.
• sheet - name of the sheet the chart is anchored to, if resolved.
• from, to - anchor cell references as strings, following getImages.

Reading content

• getChartType - e.g. :waterfall, :histogram.
• getChartTitle - title text, whether typed or bound to a cell; nothing if the title has no text of its own.
• getChartRanges - the source range of each data dimension, resolved through the workbook's hidden _xlchart.* defined names.

See also getCharts, getChartSchema.

ChartRef

One cached reference from a chart series: the formula it came from, the number format Excel recorded for it, and the cached values themselves.

Fields

• kind::Symbol - one of :num, :str, :multiLvlStr (multi-level), :numLit (literal-numbers), :strLit (literal-text).
• ref::Union{Nothing,String} - the c:f formula (Sheet1!$B$2:$B$9). nothing for literal (c:numLit / c:strLit) series, which have no source range.
• format_code::Union{Nothing,String} - number format recorded in the cache.
• ptCount::Int - number of points Excel declared, whether or not the cache was read.
• data::Vector - cached values, length ptCount, gaps as missing. Empty when the chart was read with cache=false.
• errors::Dict{Int,UInt64} - index => error code for cached error values.

Excel caches only #N/A as an error. Other error values are cached as 0, so they cannot be told apart from a real zero.

ChartRef only applies to c: charts and not cx: charts.

ChartRange

A resolved series reference: a SheetCellRef, SheetCellRange, SheetRowRange, SheetColumnRange or NonContiguousRange; XL_REF where Excel has replaced the reference with #REF!; or nothing where the series has no reference of that kind or it could not be resolved.

ChartRanges

What getChartRanges returns for one series: a named tuple of idx, name, and the categories, values and bubble_sizes references, each a ChartRange.

idx is the series' c:idx; see ChartSeries. A field is nothing where the series has no reference of that kind — bubble_sizes on anything but a bubble chart, for instance.

ChartSeries

One series (c:ser), as read.

categories holds c:cat for category charts and c:xVal for scatter and bubble charts; values holds c:val or c:yVal correspondingly, so the two fields mean the same thing whatever the chart type.

idx is the series' c:idx, unique within the chart and unaffected by adding series. It is the key the value types carry as series_idx, so a ChartDataPoint or ChartTrendline read from this series still addresses it after later writes. order is the plotting order (c:order) and is not a key.

A series position i, as taken by the setter functions and the setters, counts from 1 in document order and is resolved afresh on each call. It is not idx; the two agree only where Excel has numbered the series from 0 in order, as it normally does.

ChartAxis

One axis (c:catAx, c:valAx, c:dateAx or c:serAx), as read.

Fields

• kind — the element tag as a Symbol, e.g. :valAx.
• axid — c:axId, the key.
• pos — c:axPos: :b (bottom), :t (top), :l (left) or :r (right).
• crossax — c:crossAx, the axid of the axis this one crosses.
• deleted — c:delete; a deleted axis is not drawn but remains formattable.
• raw — the element as read, or nothing for an axis built in code.

Identified by axid. Functions taking (c, ax) find the axis by it in the current part, so ax stays usable across writes. The other fields describe the axis as it was when read; getters that depend on the axis kind check the current element, since Excel keeps the axId when a category axis is switched to a date axis. raw is never used to address the part.

ChartGroup

One chart-type group in c:plotArea (c:barChart, c:lineChart, …), as read.

Fields

• kind — the element tag as a Symbol, e.g. :barChart.
• axids — the c:axId values the group plots against, in order; empty for pie and doughnut groups.
• raw — the element as read, or nothing for a group built in code.

Identified by (kind, axids): a combo chart's groups plot against different axis pairs, so the pair is unique in practice. Functions taking (c, g) find the group by it in the current part and throw if no group, or more than one, matches. Equality and hashing use the key alone. raw is never used to address the part.

ChartMarker

Marker properties (c:marker under a c:ser or c:dPt), as read.

Fields

• series_idx — c:idx of the owning series.
• point_idx — c:idx of the owning data point, 0-based as written, or nothing for the series' own marker.
• symbol — :circle, :square, :none, …; nothing means absent.
• size — points, 2 to 72; nothing means absent.
• shape — the marker's c:spPr, if written.
• raw — the element as read, or nothing for a marker built in code.

Identified by series_idx and point_idx. raw is never used to address the part.

ChartDataPoint

Per-point formatting override on a series (c:dPt), as read.

Fields

• series_idx — c:idx of the owning series.
• idx — the point's c:idx, 0-based as written. Functions taking a point position count from 1, so a point at idx == 0 is position 1.
• invert_if_negative, bubble3d — as written; nothing means absent.
• raw — the element as read, or nothing for a point built in code.

Identified by series_idx and idx. Functions taking (c, d) find the element by these in the current part, so d stays usable across writes. The other fields describe the point as it was when read; raw is never used to address the part.

ChartDataLabel

An individual data label override (c:dLbl within a series' c:dLbls), as read.

Fields

• series_idx — c:idx of the owning series.
• idx — the labelled point's c:idx, 0-based as written, one less than the position the setters take, as ChartDataPoint.
• delete — c:delete; a deleted label carries no other properties.
• raw — the element as read, or nothing for a label built in code.

Identified by series_idx and idx, as ChartDataPoint.

ChartTrendline

A trendline on a series (c:trendline), as read.

Fields

• series_idx — c:idx of the owning series.
• ordinal — 1-based position among the series' c:trendline elements.
• kind — c:trendlineType: :linear, :exp (exponential), :log, :movingAvg (moving-average), :poly (polynomial), :power.
• name, order, period, forward, backward, intercept, disp_rsqr, disp_eq — as written; nothing means absent.
• raw — the element as read, or nothing for a trendline built in code.

Identified by series_idx and ordinal. Trendlines have no identifier of their own, so the ordinal is positional: it holds as long as no earlier trendline on the same series is removed. raw is never used to address the part.

ChartErrorBars

A set of error bars on a series (c:errBars), as read. A series carries at most two, one per direction.

Fields

• series_idx — c:idx of the owning series.
• ordinal — 1-based position among the series' c:errBars elements.
• direction, bar_type, value_type, value, no_end_cap — as written; nothing means absent.
• raw — the element as read, or nothing for error bars built in code.

Identified by series_idx and ordinal, as ChartTrendline.

ChartUpDownBars

Up-down bars on a line or stock chart group (c:upDownBars), as read.

Fields

• group — the owning ChartGroup, which is the key.
• gap_width — c:gapWidth; nothing means absent.
• raw — the element as read, or nothing for bars built in code.

ChartExData

One cx:data block. Series refer to a block by id through cx:dataId.

ChartExDimension

One data dimension of a chartEx data block: a cx:numDim or cx:strDim.

Fields

• kind - :num or :str.
• type - the dimension's role as written, e.g. :val (values), :cat (categories), :size, :x, :y, :colorVal (numeric-colour), :colorStr (text-colour), :entityId (region).
• formula - the text of cx:f, usually a hidden _xlchart.* defined name; nothing if the dimension has no formula.
• range - the resolved source range; nothing if unresolved.

ChartExBinning

Histogram binning from cx:layoutPr/cx:binning. Field names follow the XML. A numeric field may also be :auto; nothing means not written.

Fields

• intervalClosed - :r (right-closed) or :l (left-closed), the closed side of each bin interval.
• underflow, overflow - the underflow and overflow bin cut-offs.
• binSize - bin width.
• binCount - number of bins.

FormatSite

One rung of a formatting cascade: the node that could carry a property, and whether it does. container always exists — it is the c:ser, c:dPt, c:marker or chart-space element being inspected. props is the spPr or txPr found on it, or nothing where none was written, which is the rung being absent rather than the property being off.

kind distinguishes what props holds, so a chain is interpretable without knowing which resolver built it: :shape for an spPr on the element itself, :marker for an spPr on its c:marker, :text for a txPr.

Effective{T}

The result of resolving a property up a cascade. value is the first explicit setting found, or nothing where the property is written at no rung at all — which means Excel takes it from the chart style part, not that it is off. An explicit <a:noFill/> resolves to a DrawingFill with kind === :none and a site, because deliberately off is a setting.

site is the rung that answered. chain is every rung that was or could have been consulted, highest precedence first, and is populated whether or not a value was found — a setter uses it to decide where to write.

SchemeColor(token; lumMod = nothing, lumOff = nothing, ...)
SchemeColor(token, transforms)

A DrawingML theme color: a token naming a slot in the workbook's color scheme, plus any transforms applied to it. Distinct from the spreadsheet <color theme="N"/> mechanism, which is index-ordered and uses a different tint algorithm — see get_theme_colors for that.

token is one of :bg1 (background), :tx1 (text), :bg2, :tx2 (likewise), :accent1 … :accent6, :hlink (hyperlink), :folHlink (visited-hyperlink), or the aliases :lt1 (light), :dk1 (dark), :lt2, :dk2.

The :lt1, :dk1, :lt2 and :dk2 aliases are preserved as written, so a round trip keeps the spelling the file used, but two spellings of one slot compare and hash equal.

Transforms are held in document order, because DrawingML applies them in sequence and lumMod before lumOff is not the same as the reverse. Equality is positional for the same reason: two SchemeColors with the same transforms in different orders are not equal, because they do not render the same. Values are percentages, not the hundredths DrawingML writes: lumMod = 75 is 75%.

The keyword constructor emits transforms in the conventional order — lumMod before lumOff, shade or tint last. Any other order needs the vector form.

Examples

SchemeColor(:accent1)
SchemeColor(:accent1; lumMod = 75)                    # 104862 against the Office theme
SchemeColor(:tx1; lumMod = 65, lumOff = 35)           # 595959
SchemeColor(:accent2, [:shade => 50.0, :alpha => 80.0])

ColorSpec

Anything that can specify a color where one is written: a parsed DrawingColor, a SchemeColor, or a string naming an AARRGGBB value or a Colors.jl color.

The parser only ever produces DrawingColor, so a value read from a file is always that. The other two exist for construction.

DrawingColor

A DrawingML colour: the element as written, plus the RGB it resolves to.

kind and val record the reference as authored - a theme colour stays a theme colour - and transforms the modifications applied to it, in document order. rgb and alpha give the resolved result for anyone who just wants to know what it looks like.

Fields

• kind::Symbol - :srgb (hex), :scheme (theme), :sys (system), :prst (named), :hsl or :scrgb (linear-RGB).
• val::String - the val attribute: "FF0000", "accent1", "windowText".
• transforms::Vector{Pair{Symbol,Int}} - e.g. [:lumMod => 60000, :lumOff => 40000], in thousandths of a percent, in the order DrawingML applies them. A SchemeColor built in code holds the same transforms as percentages, so 60000 here is lumMod = 60 there.
• rgb::String - the resolved colour as "RRGGBB".
• alpha::Float64 - 1.0 unless an alpha transform applies.

rgb and alpha are resolved values, not source, and are not written — the file keeps the scheme reference and its transforms so the theme still applies.

DrawingFill

A DrawingML fill: <a:solidFill>, <a:noFill>, <a:gradFill>, <a:pattFill> or <a:blipFill>.

A solid fill resolves to one colour in fgcolor. A pattern fill resolves to two, fgcolor and bgcolor, with the pattern itself in preset - matching how cell fills are exposed. Gradient and picture fills are identified by kind but not modelled further: raw holds the element as read, so nothing is lost on write.

Fields

• kind::Symbol - :none, :solid, :gradient, :pattern, :blip (picture) or :group.
• fgcolor - the colour of a solid fill, or a pattern's foreground.
• bgcolor - a pattern's background; nothing otherwise.
• preset::Union{Nothing,String} - a pattern's prst attribute, e.g. "pct25", "ltUpDiag".
• raw::Union{Nothing,XML.Node} - the element as read, or nothing for a fill built in code. Gradient, pattern, picture and group fills are written back from it.

DrawingLine

A DrawingML outline: <a:ln>.

The stroke colour lives in fill, since a line is filled the same way a shape is - solid, gradient, pattern or none.

Fields

• fill::Union{Nothing,DrawingFill} - the stroke; nothing where the element says nothing about it, kind === :none where it explicitly has no outline.
• width::Union{Nothing,Float64} - the w attribute, in points (the file stores EMU, 12700 to the point).
• dash::Union{Nothing,String} - "solid", "dash", "sysDot", and so on.
• cap::Union{Nothing,String} - "rnd", "sq", "flat".
• compound::Union{Nothing,String} - the cmpd attribute: "sng", "dbl", …
• join::Union{Nothing,String} - "round", "bevel" or "miter", from the a:round/a:bevel/a:miter child.
• miter_limit::Union{Nothing,Float64} - the a:miter lim, as a multiple of the line width; only with a miter join.
• raw::Union{Nothing,XML.Node} - the element as read, or nothing for a line built in code.

DrawingShapeProps

Shape properties (a:spPr) — the fill and outline of anything drawn in a chart: series, data points, the plot area, the chart area, axis lines, legend, gridlines.

fill and line distinguish three states, and the difference matters:

The same applies to line.fill: <a:ln><a:noFill/></a:ln> is how Excel writes "no border", which is not the same as omitting a:ln entirely.

effects holds a:effectLst or a:effectDag as an unparsed node — enough to report that a shape has effects without modelling shadows and glows. Geometry (a:xfrm, a:prstGeom, a:custGeom) and 3-D (a:scene3d, a:sp3d) are not modelled; they stay in raw and are written back from it unchanged. Chart parts rarely carry geometry — it belongs to the drawing shapes that host the chart, not the chart itself.

DrawingText

A DrawingML text body (CT_TextBody): c:txPr, c:rich, or the cx: equivalent.

liststyle is kept as an unparsed node — it is empty in most chart parts and carries list-level defaults we don't model. raw is the text body element itself, for surgical write-back.

DrawingParagraph

One a:p: properties, runs in document order, and the trailing a:endParaRPr, which is what Excel writes when a paragraph has no runs.

DrawingParaProps

Paragraph properties (a:pPr). Margins and indent are points; spacing fields are (:pct, percent) or (:pts, points). defprops is the nested a:defRPr, which in a chart txPr is usually the only place the font is specified.

DrawingRun

One a:r, a:br or a:fld, distinguished by kind (:run, :br (line-break), :fld (field)). A break carries "\n" as its text so text_content needs no special case.

DrawingRunProps

Character-level properties: a:rPr, a:defRPr or a:endParaRPr.

Sizes are points (the file stores 1/100 pt), baseline is a fraction of the font size, and under / strike / caps keep the DrawingML vocabulary as written ("sng", "noStrike", "small"). Typefaces may be theme references — "+mn-lt" for the minor latin font, "+mj-lt" for major.

DrawingBodyProps

Text-body properties (a:bodyPr). rotation is degrees (stored as 1/60000), insets are points, and autofit is :none, :normal or :shape — parsed from a child element, with fontscale and linespacereduction populated only for :normal.