SPB Git

Repository Public

README.md 16.8 KB

# SheetCharts

Charting engine of ORIX Sheet: a pure model + drawing package (Swift 6, macOS 14+). It depends on SheetCore, CoreGraphics, CoreText, ImageIO and UniformTypeIdentifiers — no SwiftUI/AppKit, no third-party code — so it runs headless and is fully testable.

Design rule: every mark derives from data. Nothing decorative is drawn; a value that cannot be represented (missing, non-positive on a log axis, negative in a pie) is left out and never replaced by zero.

swift
var spec = ChartSpec(kind: .column, title: "Sales")
spec.categories = .range(sheet: "Data", range: RangeRef(a1: "A2:A13")!)
spec.series = [SeriesSpec(nameRef: .range(sheet: "Data", range: RangeRef(a1: "B1")!),
                          values: .range(sheet: "Data", range: RangeRef(a1: "B2:B13")!))]
let source = WorkbookDataSource(workbook: workbook)
let pdf = ChartRenderer.pdfData(spec, source: source, size: CGSize(width: 480, height: 300))
sheet.meta.objects.append(try spec.sheetObject(x: 40, y: 40, width: 480, height: 300))   // kind "chart"

# Layout of the package

Directory Content
Model/ ChartSpec, SeriesSpec, AxisSpec, LegendSpec, Annotation, ChartOptions, ChartTheme, JSON coding
Data/ ChartDataSource, WorkbookDataSource, LiteralDataSource, ChartData (resolved numbers)
Stats/ quantiles, box statistics, binning, KDE, stacking, regression, marching squares, treemap, decimation, colour maps
Scales/ tick generation (linear, log, calendar), AxisScaleMap, built-in axis formatter
Canvas/ ChartCanvas protocol, CGChartCanvas, SVGChartCanvas, CoreText measurement
Render/ scene builder, frame (title / legend), Cartesian layout and axes, ChartLayout, ChartRenderer
Marks/ one file per family of marks (XY, bars, distributions, grids, pie, radar/treemap, surface, decorations)
Figure/ ORIX Figure Studio: FigureSpec, FigureTemplates, FigureRenderer
Suggest/ ChartSuggest (default charts for a selection)
Samples/ deterministic synthetic sample charts (gallery, previews, tests)

chart-gallery <dir> (executable target) writes a PNG (2x), SVG and PDF per chart kind, dark PNGs, option variants and multi-panel figures, and prints timings.

# Spec model

ChartSpec is Codable, Sendable, Hashable, versioned (schema, currently 1). encoded() / ChartSpec.decoded(from:) give the SheetObject payload. Decoding is tolerant: the stored JSON is overlaid on the defaults of the current model, so payloads that lack keys (older schema, hand-written JSON) still load. FigureSpec works the same way (SheetObject.kind == "figure").

  • kind — 21 kinds: line, bar (horizontal), column, area, scatter, bubble, histogram, boxPlot, violin, heatmap, waterfall, candlestick, pie, donut, radar, treemap, surface3D, contour, density, timeSeries, combo.
  • series[] — name / nameRef, and the references used by the kind: values, x, size, open/high/low/close, lower/upper (confidence band), per-series categories; style (colour, line width, dash, marker, fill opacity); axis (primary / secondary); kind (mark override in a combo chart: line, column, area, scatter); trendline; errorBars; showDataLabels.
  • DataRef — .range(sheet:range:) (sheet addressed by name), .literal([Double]), .labels([String]).
  • categories, rowLabels — band labels, pie / treemap labels, radar spokes, matrix column / row coordinates.
  • xAxis, yAxis, y2Axis — title, unit, min / max, major step, minor ticks, scale (linear, log10, log2, date), number-format code, gridlines, reversed, label rotation, includeZero. xAxis is always the independent axis: for horizontal bars it is the one drawn on the left.
  • legend, annotations (text, arrow, reference line, band — in data coordinates), theme, options.

What each kind reads:

Kind Data
line, area, column, bar, combo, radar categories + series[].values
scatter, timeSeries series[].x + values (x falls back to numeric categories, then 1, 2, 3…)
bubble x, values, size
histogram, density, boxPlot, violin each series' values is one sample
pie, donut, treemap, waterfall first series + categories
candlestick first series' open/high/low/close + categories; further series with values are line overlays
heatmap, contour, surface3D one series whose values is a 2-D range, or one series per matrix row; categories / rowLabels are the column / row labels (numeric, strictly monotonic labels become coordinates for contour and surface)

A line or area chart uses a category axis unless a series has x or xAxis.scale is log / date.

# Data resolution and the missing-value rule

ChartData.resolve(spec, source:) turns references into numbers through a ChartDataSource. WorkbookDataSource(workbook:) reads computed values, clips open-ended references (A:A) to the stored extent, and takes an optional synchronize closure (or a lock / unlock pair) because Workbook is not thread-safe.

Only numeric cells holding a finite number are data. Blank cells, text (including text that looks like a number), booleans, error values and NaN / ±∞ are missing. Missing values are never plotted as zero: line-type marks break (unless options.connectGaps), bar-type marks leave the slot empty, stacks do not move, statistics exclude the value. ChartData.skippedCells counts the non-blank cells that were skipped.

Further rules: values ≤ 0 are skipped on log axes; pie / donut / treemap draw strictly positive values only (ChartLayout.notes reports dropped negatives); a candle needs all four prices; bubbles need a size > 0. When a chart has nothing to draw it shows a short note ("No numeric data") instead of an empty frame.

# Statistical conventions

Topic Convention Reference used in tests
Linear ticks steps 1-2-5 × 10^k, at least two ticks inside the range, automatic ends extended to the enclosing ticks (a bound passing a tick by < 15 % of a step does not add an interval) matplotlib.ticker.MaxNLocator(steps=[1,2,5,10])
Log ticks integer powers of the base, regular stride when crowded, 2…9 minors; 1-2-5 multiples under one decade numpy
Calendar ticks seconds → years from serial dates through DateSerial (1900 and 1904 systems); months and years on the first day, weeks on Mondays Python datetime
Histogram bins auto, freedmanDiaconis, sturges, scott, fixedCount, fixedWidth; bins are [a, b) with the last one closed; auto = min(max(FD, range / 2√n), Sturges); at most 2000 bins numpy.histogram_bin_edges / numpy.histogram (2.4)
Normalisation count, density (count / (n · width)), probability numpy density=True
Quartiles Hyndman–Fan type 7 inclusive (default; Excel QUARTILE.INC), type 6 exclusive, type 2 averaged, type 8 medianUnbiased numpy.quantile methods linear, weibull, averaged_inverted_cdf, median_unbiased
Box plot box Q1–Q3, median line, whiskers to the most extreme observation within 1.5 · IQR (Tukey) or to min / max, the rest are outliers; optional mean matplotlib.cbook.boxplot_stats
KDE (violin, density) Gaussian kernel; bandwidth silverman = 0.9 · min(s, IQR / 1.34) · n^(−1/5) (default), scott = s · n^(−1/5), or fixed; s is the sample standard deviation. No estimate (nothing drawn) for n < 2 or zero spread. Density curves extend 3 bandwidths beyond the data; violins are trimmed to the data range and all scaled to the same maximum width scipy.stats.gaussian_kde
Stacking positive values stack upward from zero, negative values downward; 100 % mode divides by the sum of absolute values of the category numpy cumulative sums
Trendlines least squares: linear, polynomial (degree ≤ 8, solved by Householder QR on centred / scaled x), exponential (ln y on x, y > 0), logarithmic (y on ln x, x > 0), power (ln y on ln x), trailing moving average. R² is computed in the space of the fit (Excel's convention). On category axes x = 1, 2, 3… numpy.polyfit
Error bars fixed, percent of the value, k · sample standard deviation of the series, k · standard error (s / √n), custom ranges closed forms
Contours marching squares on grid nodes (inside = value ≥ level, saddles resolved by the cell mean), segments joined into polylines; filled bands are exact polygon clips of the same piecewise-linear surface matplotlib / contourpy iso-line lengths, analytic circle
Treemap squarified (Bruls, Huizing & van Wijk); areas exactly proportional to values property tests
Bubbles area proportional to size (diameter ∝ √size) closed form
Waterfall values are deltas; indices in waterfallTotals show the running sum from zero (index 0 as a total is the opening balance) closed form
Colour maps viridis, magma, plasma, inferno, cividis, RdBu, coolwarm, BrBG, Blues, Greys — 65 anchors each, linearly interpolated; diverging maps are centred on zero unless bounds are given matplotlib (within 4 / 255)
3D surface static orthographic projection (azimuth, elevation), quads painted far-to-near by mean depth; no perspective, lighting or interaction —

Reference numbers are generated by Tests/SheetChartsTests/Generators/gen_fixtures.py and gen_colormaps.py (/opt/homebrew/bin/python3, numpy 2.4.4, scipy 1.17.1, matplotlib) into Tests/SheetChartsTests/Fixtures/.

# Decimation

  • Lines longer than 2000 points are reduced per horizontal bucket of 0.5 pt to at most four points — first, lowest, highest, last, in order (Decimation.minMaxIndices). Every bucket keeps its exact vertical extent, so the drawn envelope is unchanged while the path is bounded by the plot width. Disable with options.decimation = false; smoothed and area series are not decimated.
  • Scatter series above 20 000 opaque markers skip a marker that falls on an already occupied 0.5 pt cell (identical markers on top of each other are indistinguishable). Markers are emitted in chunks of 64 per path.
  • Hit-test data always contains every point.

Measured on this machine (release build, 640 × 400 pt, best of three; resolve + layout + draw + encode):

100 000 points PNG 2x PDF SVG
line (decimated) 40–45 ms 8–9 ms 5–6 ms
line, decimation off 1.4–1.7 s — —
scatter 0.26–0.57 s 0.29–0.85 s 0.10–0.18 s

(Two runs; the machine was shared with other builds, hence the ranges.)

# Drawing, layout and interaction

ChartRenderer.scene(spec, data:size:measure:viewport:formatter:) builds a ChartScene: a ChartLayout plus a display list. scene.draw(in:) replays it into any ChartCanvas; ChartRenderer.draw / pngData / pdfData / svgString are conveniences. Cache the scene and replay it for redraws.

ChartLayout exposes the plot rectangle, axis scales and ticks (with label frames), legend entries, colour-bar frame, every text frame, and hit-test data:

  • hitTest(point) → the mark under the point, else the nearest anchor within a distance; items(alignedWith:) → all series at the nearest x (shared tooltip); item(series:point:);
  • dataPoint(at:) and position(x:y:axis:) convert between canvas and data coordinates;
  • viewport + ChartViewport.zoomed(by:aroundX:y:) / panned(dx:dy:) → pass the result back as viewport: to zoom and pan (category axes use the category index as coordinate).

Number formatting: axes and labels use a small built-in formatter (automatic decimals from the tick step, thousands separators from 10 000, ×10ⁿ beyond 10⁹ / below 10⁻⁴, and a subset of format codes: 0.00, #,##0, 0%, 0.00E+00, literal prefix / suffix, date-time tokens). Pass a ChartValueFormatter closure ((value, formatCode) -> String?) to delegate format codes to SheetFormat.

Themes: ChartTheme.presets — Light, Dark, Okabe–Ito (colour-blind-safe) and its dark variant, Publication, Minimal, Financial, Presentation (light / dark), Monochrome. theme.variant(dark:) switches surfaces and palette. ChartPalette also carries Tol "bright" and Tableau 10.

Concurrency: scenes can be built on any thread. Font matching goes through a process-wide, locked cache (FontCache), because concurrent first-time font lookups from many threads can stall in the system font service.

# Export formats

Format API Notes
PNG pngData(…scale:) sRGB, scale pixels per point, DPI metadata
PDF pdfData single page, vector; text is text. Only heatmaps above 4096 cells embed a raster (one pixel per cell)
SVG svgString standalone SVG 1.1, real <text> elements, groups named series-N, grid, axes, legend… Fonts are referenced by family name, not embedded

Coordinates are points with the origin at the top-left. CGChartCanvas(context:height:flipped:) draws into any CGContext (views, printing).

# Figure Studio

FigureSpec places FigurePanels (a ChartSpec + row / column / spans + label) on a rows × cols grid of a figure sized in points (widthMM / heightMM convert). One FigureTypography (family + base size, from which the whole size ladder derives) and one ChartTheme are applied to every panel; panel titles move to a header line next to the panel label ("(a)", "A"…). shareX / shareY unify the automatic domains of continuous axes per column / row and keep the axis title on the outer panels only. FigureRenderer offers scene, draw, pngData, pdfData, svgString, exportData (format of the exportPreset).

FigureTemplates.all: Academic paper single column (89 mm) and double column (183 mm), Scientific publication (174 mm, serif), Financial report (170 mm), Business presentation (16:9), Dashboard. Templates are size, grid and typography presets only. They do not claim compliance with the requirements of any journal or publisher.

# Suggestions

ChartSuggest.suggest(for:in:) trims the selection to its content, detects a header row (text over numbers) and a category column (text, date-formatted numbers, years or 1, 2, 3…), then proposes charts best-first: time series for dates, column / bar / pie for one measure, grouped and stacked columns for several, histogram / box plot / density for a single long numeric column, scatter / bubble for two / three numeric columns, heatmap / contour / surface for a bare numeric matrix, candlestick for Open / High / Low / Close headers, series-in-rows for wide tables. ChartSuggest.analyze returns what was detected.

# Known limitations

  • The 3D surface is a static projection; the painter's algorithm can mis-order quads on steep, self-occluding surfaces, and its hit test returns the smallest containing quad.
  • Contour charts have no in-line level labels (levels are read on the colour bar). Heatmap / contour colour bars have no title.
  • A legend for bubble sizes is not drawn. One legend per chart; long legends are truncated to the available space.
  • Markers of one series are filled as compound paths: with fillOpacity < 1 overlapping markers of the same series do not darken each other.
  • Automatic tick labels are English / invariant ("Jan", "," grouping, "." decimals). Localised output needs the ChartValueFormatter and explicit format codes.
  • Text is single-line, left-to-right; long labels are truncated with an ellipsis. No rich text or line wrapping.
  • SVG and PDF reference fonts by family; a viewer without the font substitutes it.
  • Ranges are addressed by sheet name and are not adjusted automatically by structural edits: after a sheet rename or an insertion / deletion of rows or columns the owner of the SheetObject must call ChartSpec.mapRanges (and FigureSpec.mapRanges). referencedRanges lists the dependencies.
  • Histograms of several series share the bin edges of the pooled data and are overlaid, not dodged or stacked.
  • Stacking applies to columns, bars, areas and category-axis lines; not to continuous-x series.
  • Error-bar kind stddev draws ± k·s around each point (not around the series mean as Excel does).
  • shareX / shareY unify domains only; panels keep their own tick labels.

# Tests

swift test — 43 test functions (three of them parameterised over the 21 kinds): numeric algorithms against the Python references; every kind × {normal, empty, single point, all blank, negative, 1e-12…1e12, dirty (errors / text / NaN / booleans)} rendered to SVG (parsed with XMLParser), PDF and PNG; every kind in every theme and at extreme sizes; scales × stacking × decorations on difficult data; structural checks (marks per datum, positions through the axis scale within 0.5 pt, stack sums, bin geometry, wedge angles, bubble areas); no clipped or overlapping text on the gallery charts at three sizes; vector-PDF heuristics (fonts present, no image XObject except dense heatmaps); JSON round trips and tolerant decoding; data-source rules; suggestions; figures.

Files main
Menu

Theme