Utilities

Status: Implemented

This document specifies the general-purpose modules used across the library: Visualize.Color (parsing, colour spaces and manipulation), Visualize.Interpolate (interpolator factories), Visualize.Ease (easing curves), Visualize.Random (seeded random variates), Visualize.Data (statistics and data shaping), Visualize.Data.Table (tabular sources as rows) and Visualize.Theme (the colours, font and sizes every mark draws with). All are pure except Random, which reads and advances the calling process's :rand state.

1. Color

1.1 Struct

%Visualize.Color{r, g, b, opacity} with r, g, b in [0, 255] and opacity in [0, 1] (default 1.0). Constructors round channels to integers; interpolation may leave them as floats.

1.2 Parsing

parse/1 trims and lower-cases its argument and returns a colour or nil. A non-binary argument returns nil. Accepted syntaxes:

• Hex: #rgb, #rgba, #rrggbb, #rrggbbaa. Short digits are doubled; an alpha byte becomes opacity = a / 255. Any other length after # returns nil; a non-hex digit raises ArgumentError.
• rgb(r, g, b) and rgba(r, g, b, a): integer channels, optional decimal alpha, arbitrary whitespace around separators. Percentages are not accepted. A non-matching string returns nil.
• hsl(h, s, l) and hsla(h, s, l, a): decimal components, % optional on s and l. A non-matching string returns nil.
• Named colours: the 148 CSS colour keywords (the 147 classic names plus rebeccapurple, with both gray and grey spellings). Unknown names return nil.

named/1 returns the lower-case hex string for a keyword (case-insensitively) or nil; named_colors/0 returns the keyword list in unspecified order.

1.3 Constructors

• rgb/3,4 clamps channels to [0, 255] and opacity to [0, 1] without rounding.
• hsl/3,4 takes h in degrees (truncated to an integer and wrapped into [0, 360)), s and l in [0, 100] (clamped); channels are rounded.
• lab/3,4 takes CIE Lab* (l 0–100, a and b roughly −128–127), converts through XYZ with reference white Xn = 0.96422, Yn = 1, Zn = 0.82521 (the d3-color constants) to sRGB, clamps and rounds.
• hcl/3,4 takes hue in degrees, chroma and luminance, converts to Lab (a = c cos h, b = c sin h) and delegates to lab/4.

1.4 Conversions

1.5 Manipulation

• brighter/1,2 and darker/1,2: k defaults to 1; the colour is converted to Lab, L is increased (decreased) by 18 * k, and converted back. The factor is additive in Lab luminance, not multiplicative in RGB.
• saturate/1,2 multiplies HSL saturation by amount (default 1.2); desaturate/1,2 is saturate/2 with default 0.8.
• rotate/2 adds degrees to the HSL hue.
• grayscale/1 sets every channel to round(0.299 r + 0.587 g + 0.114 b).
• invert/1 sets each channel to 255 - channel.
• with_opacity/2 sets a clamped opacity.
• luminance/1 is WCAG relative luminance in [0, 1]; contrast/2 is (L_light + 0.05) / (L_dark + 0.05) in [1, 21].
• mix/2 is interpolate_rgb(c1, c2, 0.5).

1.6 Interpolation

Each interpolate_*/3 takes two colours and t (not clamped) and returns a colour. interpolate_rgb/3 interpolates channels and opacity linearly and leaves them unrounded. interpolate_hsl/3 and interpolate_hcl/3 interpolate in HSL and HCL respectively, taking the shorter arc around the hue circle; interpolate_lab/3 interpolates in Lab. Results other than RGB pass through the corresponding constructor and are rounded.

1.7 Functions

2. Interpolate

Every function in Visualize.Interpolate returns a one-argument function of t. t is not clamped unless stated; callers pass [0, 1] for the nominal range.

2.1 Colour inputs and output

rgb/2, hsl/2 and hsl_long/2 accept each endpoint as a hex string with or without # (3 or 6 digits), an {r, g, b} tuple, or one of thirteen basic names (red, green, blue, white, black, yellow, cyan, magenta, orange, purple, pink, gray, grey). Anything else is treated as black. %Visualize.Color{} structs are not accepted. The returned function yields #RRGGBB with upper-case hex digits (as produced by Integer.to_string/2).

2.2 Interpolators

2.3 Functions

3. Ease

Visualize.Ease provides 25 easing functions from t in [0, 1] to a float, nominally in [0, 1] (the elastic_* and back_* families overshoot). names/0 returns the 25 atoms below in this order; by_name/1 returns the arity-1 function for an atom and raises FunctionClauseError for any other atom. frames/2 with count > 1 returns count values at t = i / (count - 1) for i in 0..count - 1; frames(_, 1) returns [1.0].

3.1 Formulas

With c1 = 1.70158, c2 = c1 * 1.525, c3 = c1 + 1, c4 = 2π / 3, c5 = 2π / 4.5, n1 = 7.5625, d1 = 2.75:

The exact-endpoint clauses match the integer literals 0 and 1 only; the floats 0.0 and 1.0 fall through to the formula (exp_in(0.0) is 2^-10).

Parameterised variants: poly_in/2, poly_out/2 and poly_in_out/2 take an exponent e (default 3): t^e; 1 - (1 - t)^e; t < 0.5: 2^(e-1) t^e else 1 - (-2t + 2)^e / 2. back_in/2 and back_out/2 take an overshoot s replacing c1 (with c3 = s + 1); there is no back_in_out/2.

3.2 Functions

4. Random

Visualize.Random draws from the process-local :rand generator. seed/1 calls :rand.seed(:exsss, {s, 2s, 3s}) and returns the new state, making subsequent draws in the calling process reproducible.

4.1 Distributions

4.2 Points and collections

• in_circle/0..3 (cx = 0, cy = 0, radius = 1): uniform over the disc using r = radius * sqrt(u).
• on_circle/0..3 (same defaults): uniform on the circumference.
• in_rect/4 (x0, y0, x1, y1): uniform over the rectangle.
• samples/2 (fun, n): a list of n calls of the zero-arity function; MUST be [] for n = 0.
• shuffle/1: Enum.shuffle/1.
• sample/2 (list, n): n distinct elements of a shuffled list (fewer when the list is shorter).
• pick/1: a random element, or nil for [].

binomial(0, p) is 0 and samples(fun, 0) is []: both iterate 1..n//1, which is empty for n = 0 (D-44).

4.3 Functions

5. Data

Visualize.Data shadows Kernel.min/2 and Kernel.max/2 inside the module. Every statistic takes an optional arity-1 accessor as its last argument (nil means the elements are the values).

5.1 Statistics

5.2 Grouping and shaping

• group/2 — Enum.group_by/2: a map from key to the elements with that key, in input order.

• rollup/3 — group/2 followed by applying the reducer to each group's list: a map from key to reduced value.

• bin/1,2 — histogram bins. Options: :thresholds — an integer count n (default 10), producing n - 1 interior thresholds evenly spaced over the domain and hence n bins, or an explicit list of thresholds producing length + 1 bins; :domain — [min, max], defaulting to the data extent. Returns [%{x0, x1, values}] where each value is placed in the first bin with x0 <= v < x1, a value equal to the last x1 goes in the last bin, and values outside the domain are dropped; values keep input order. [] yields [].

• cross/2,3 — the Cartesian product of two lists as {a, b} tuples, or as combine.(a, b) when a two-arity function is given.

• range/2,3 — start, stop, step = 1: max(0, ceil((stop - start) / step)) values start + i * step, so the result is empty when stop is not beyond start in the direction of step; negative steps count down. step MUST be non-zero (otherwise FunctionClauseError).

• ticks/3 — start, stop, count > 0: nice tick values. The step is 10^k times 1, 2, 5 or 10, chosen from |stop - start| / count with the d3 thresholds sqrt(2), sqrt(10), sqrt(50); ticks run from ceil(start / step) * step to floor(stop / step) * step inclusive, rounded to 10 decimals, and are [] when no multiple of the step lies inside the span. A zero span returns [start]; start > stop returns the ticks of the reversed span in descending order. count MUST be positive (otherwise FunctionClauseError).

• sort/2,3 — Enum.sort_by/3 on the accessor, :asc (default) or :desc.

• unique/1,2 — Enum.uniq/1, or Enum.uniq_by/2 with an accessor.

• lttb/2,3 and m4/2,3 — shape-preserving downsampling of a series (#448): a subsequence of the input elements, never new ones, so a tooltip over a kept point reads a real datum. The accessor returns {x, y}; without one the elements are {x, y} tuples. A datum is defined when both x and y are numbers; any other datum is a gap. The defined data split at the gaps into runs, and both functions reduce each run separately and keep exactly the first element of every run of gaps, in place — so a line drawn over the result still breaks where the input broke (spec/04's defined/2). Both are one pass over the input plus a constant amount per element: O(n) time, and O(n) space for the random access a run's buckets need. Both read the elements in input order and expect x ascending within a run, as a series is; neither sorts.

  • lttb(data, n, accessor) — Largest-Triangle-Three-Buckets (Steinarsson 2013, Downsampling Time Series for Visual Representation, §4.2). n is an integer >= 3 (otherwise FunctionClauseError). Input of n or fewer elements, gaps counted, is returned unchanged. A single run of L > n elements keeps exactly n: its first and last, and one per bucket of the n − 2 buckets that split the interior evenly — bucket i (0 ≤ i < n − 2) is the interior indices [floor(i·e) + 1, floor((i + 1)·e) + 1) with e = (L − 2) / (n − 2) — choosing in each the element that forms the largest triangle with the element chosen in the bucket before it (the first element, for bucket 0) and the mean point of the bucket after it (indices [floor((i + 1)·e) + 1, min(floor((i + 2)·e) + 1, L)), which for the last bucket holds the last element); a tie keeps the earliest. With gaps, a run of L defined elements out of D in all has the budget b = max(min(L, 2), floor(n · L / D)): a run with b ≥ L is kept whole, b = 2 keeps its first and last, and otherwise LTTB with b. The total is therefore about n and exactly n without gaps.
  • m4(data, width, accessor) — M4 (Jugel et al. 2014, M4: A Visualization-Oriented Time Series Data Aggregation): per pixel column, the first, last, minimum-y and maximum-y elements. width is an integer >= 1 (otherwise FunctionClauseError), the column count. The columns split the defined x extent [x_min, x_max] evenly: a defined datum's column is min(width − 1, floor((x − x_min) / (x_max − x_min) · width)), every datum column 0 when x_min == x_max. A column visit is a maximal stretch of consecutive defined elements of one run in one column; each visit keeps its first, its last, its earliest least y and its earliest greatest y, deduplicated and in input order — so at most four per visit, and a run whose every visit has four or fewer elements is kept whole. Drawn as a line on a plot width pixels wide whose x scale spans [x_min, x_max], the result covers every pixel column the input covers with the same vertical extent and the same entry and exit points, which is why it is lossless at that resolution: a peak is never dropped.

  Neither has an Nx path. LTTB's choice in a bucket depends on the choice in the bucket before it, a serial dependency a vectorised pass cannot express; M4 needs a segmented argmin and argmax per column, which Nx offers no primitive for; and both keep whole elements, which a tensor does not hold, so the cost an Nx path would save — the arithmetic — is not the cost of the call, which is reading the accessor over every element. Visualize.Shape.LineNx's optional-Nx pattern (spec/04 §10.1) is therefore deferred until a measurement shows the arithmetic, not the reading, is what a reduction costs; the benchmark of #448 (a tagged test, not a gate) is that measurement's baseline.

5.3 Functions

6. Data.Table

Visualize.Data.Table turns the shapes chart data arrives in into the list of rows every generator consumes (04-shapes-and-curves §1). The table package (the Table.Reader protocol and its List and Map impls) is an optional dependency like Nx (D-52): a host that has it reads Explorer frames and any other struct implementing the protocol; without it lists, column maps and tensors still work and a struct source raises UndefinedFunctionError at Table.to_rows/1.

6.1 Sources

Visualize.Data.Table.rows/1 accepts, and distinguishes by shape:

[], %{} and the empty keyword list yield []. A rank-1 tensor bound to a dense series stays a first-class source for Visualize.Shape.LineNx and the binary path; Visualize.Data.Table.rows/1 does not stand between them.

6.2 Column names

A source names its columns with atoms or strings and a caller writes accessors in either. Visualize.Data.Table.get/2 reads the row by the given spelling first, then by the other: an atom name falls back to Atom.to_string/1, a string name to the atom key that spells the same. No atom is ever created. nil when neither is a key, so a missing column behaves as an absent map key does in 04-shapes-and-curves §1.1. Visualize.Data.Table.accessor/1 is fn row -> get(row, name) end, and returns a 1-arity function unchanged so a generator normalises every accessor form through one call. A tuple row has no names: get/2 raises BadMapError.

6.3 Time columns

Visualize.Data.Table.time_columns/1 names the columns a time scale could be inferred from: every key of every map row, sorted by term order (a row without the key contributes nil), kept when the column has at least one non-nil value and every value is nil or temporal?/1. Visualize.Data.Table.temporal?/1 is true for DateTime, Date and NaiveDateTime and for a string one of DateTime.from_iso8601/1, NaiveDateTime.from_iso8601/1 or Date.from_iso8601/1 parses; anything else, including a bare year or a non-ISO date, is false. Detection reads the whole column, not the first row as Tucan does: every row is visited and every string parsed, so the cost is the size of the table, and a column that starts temporal and stops being so is not temporal. Tuple rows have no names and yield [].

Visualize.Data.Table.column_types/1 (#369) types every named column of a table as spec/14 §2.3's four, reading the whole column as time_columns/1 does: a column whose non-nil values are all temporal?/1 is :time; all numbers, :number; all strings (none temporal), :text; all atoms or booleans, :category; a column with no non-nil value, or with values of more than one of those shapes, has no type and is left out. The result is a map from name to type, %{} for an empty table or tuple rows. It is a suggestion for a tool to pre-fill a design's types, never something the layer reads at render.

6.4 Functions

7. Theme

Visualize.Theme names the colours, font and sizes a chart draws with, so that no axis, mark or component carries a colour literal and a consumer restyles every chart from one place — a theme struct in Elixir, or CSS custom properties in a stylesheet (D-55). Ggity's Theme and Tucan's themes are the precedent; the CSS half is this library's own, because its output lives in a page.

7.1 Struct and slots

%Visualize.Theme{name, series, axis, grid, text, background, surface, font_family, font_size, label_size, title_size}. name is an atom naming the theme (:default, :dark, or the consumer's own); series is a non-empty list of colour strings; axis, grid, text, background and surface are colour strings; font_family is a CSS font-family string; the three sizes are numbers in user units (pixels).

A slot names one value of a theme:

slots/1 lists a theme's slots in that order, :series_1 to :series_n first. series_slot/2 is the :series_k atom that {:series, i} cycles to. A slot that is none of these, or :series_k with k > n or k < 1, raises ArgumentError in every function that takes a slot.

7.2 Built-in themes

Both palettes are ten hues in the order of d3's category10 — blue, orange, red, teal, green, yellow, purple, pink, brown, grey — each adjusted until it holds at least 3:1 (Visualize.Color.contrast/2, §1.5) against its own background; text holds at least 4.5:1 and axis at least 3:1. Neither palette is a d3 scheme, because every d3 categorical scheme has a colour under 2.1:1 on white (category10's olive is 2.0:1), and a theme that promises contrast cannot ship one unchanged. 7.4 states the floors.

surface is a step off the background towards the grid — a cool grey on the light theme, a step above #1b1e24 on the dark — so a field reads as a plane under the data without becoming a data colour. new/1 is default/0 with the given keyword fields replaced, so a host theme that names no surface takes the light one, as it takes every other field it leaves out; merge/2 replaces the fields of any theme. An unknown field raises KeyError; an empty series raises ArgumentError.

7.3 Resolution

resolve(theme, slot, mode) is the one door through which anything reads a theme, and the mode is what the render target needs:

• :literal — the slot's value as stored: a colour or font string, or a number for a size. A canvas colour is a literal, so every canvas backend resolves this way.
• :css — a CSS custom-property reference with the literal as its fallback: var(--vis-axis, #666666), var(--vis-series-3, #c8373b), var(--vis-font-size, 10px) (a size gains px). What the SVG output carries.

css_name/1 is the property name of a slot atom: --vis- and the slot with _ as - (:series_1 → --vis-series-1, :font_family → --vis-font-family). mode/1 maps a backend — a module, :svg, :canvas or nil, resolved by Visualize.Backend.resolve/1 (spec/02 §3.2) — to the mode: Visualize.Backend.SVG is :css, every other backend :literal. Visualize.Axis.render/2 applies it (spec/05 §1.6) and the style grammar of the declarative layer resolves through the same call.

The reference carries its fallback rather than the root declaring the property (D-55). A declaration on the <svg> — inline or in a <style> — would beat every ancestor rule in the cascade, so a consumer could not switch a theme from a class without !important; with the fallback form a chart rendered outside any stylesheet (a standalone .svg, an <img>) still draws in its theme, and a rule on any ancestor, .night { --vis-axis: #a0a4ab }, overrides it. stylesheet/1 writes that rule for a whole theme — .vis-theme-<name> { then one --vis-<slot>: <value>; line per slot of slots/1, sizes with px, then } — so a consumer that includes stylesheet(dark()) in its CSS switches every chart under an element with class="vis-theme-dark" without touching Elixir.

The contrast ink (#486, D-123). ink(theme, under) is the colour a text drawn on under should take: the theme's text or its background, whichever has the higher contrast ratio against under by Visualize.Color.contrast/2 — text on a tie — always as the slot's literal, never a reference. When the higher of the two is under 4.5:1 (WCAG AA for text), it is #000000 or #ffffff instead, whichever contrasts more, and one of those two always holds 4.58:1 or better against any colour, so the ink always meets AA against the colour it is chosen for. under is a colour string Visualize.Color.parse/1 reads, a %Visualize.Color{}, or nil for "nothing under the text" — the theme's own background — and a string it cannot parse is nil; a slot whose own value does not parse is skipped. It is a literal because the choice is made between literals: a var(--vis-text, …) that a stylesheet re-pointed would undo it. The style grammar's :contrast value resolves through it (spec/14 §3.2, §5.5).

7.4 Contrast

A theme MUST hold, by Visualize.Color.contrast/2 against its own background: text at least 4.5:1 (WCAG AA for text), axis at least 3:1 (WCAG non-text contrast), every series colour at least 3:1, and grid at least 1.2:1 — visible, and faint on purpose. surface MUST differ from grid: the grid is drawn over the surface (a map's graticule over its ocean), and a surface equal to it would swallow every line (#422). Both built-in themes do; a theme from new/1 is not checked, since a house palette is the consumer's choice. Across the colour schemes of Visualize.Scale.Color.schemes/0, every colour parses with Visualize.Color.parse/1 and every scheme has at least one colour at 3:1 or better against the dark background and at 2.5:1 or better against the light one (set2, a pastel scheme, tops out at 2.6:1 on white), so any scheme has a usable colour on either theme; a scheme's lightest colours vanish on the light theme (blues opens at 1.04:1 on white) and its darkest on the dark (blues closes at 1.8:1 on #1b1e24), which is why the built-in themes carry their own palettes (7.2). test/visualize/theme_contrast_test.exs holds both themes and every scheme to this.

7.5 Functions

8. Signals

Implemented (#244). A signal is a generated source: a description from which Visualize.Signals yields rows, pure and deterministic for a tick, so a chart under design has feeds that move without a host supplying any. A deployed design still binds to the host's pool (spec/14 §7.3) under the same names; signals are the builder's stand-in for it.

8.1 A signal

Value columns differ from each other: the n-th value column (0-based) of a sine or a square is shifted by n / count of a cycle, so two columns are never the same line; a random column draws its own stream from seed and the column's index; a discrete column starts n higher.

8.2 The rows

rows(signal, tick) yields window rows, one per tick from tick − window + 1 to tick in order — a tick below 0 yields no row, so the window fills over its first ticks — each a map of the signal's fields: the time column the tick, and each value column its kind's value at that tick:

• :sine — min + (max − min) · (1 + sin(2π (t / period + phase))) / 2, so at tick 0 the first column stands at the midpoint;
• :square — max for the first half of a cycle, min for the second, the column's phase applied;
• :random — a value in [min, max) from :rand.uniform_real/0 under a seed derived from seed, the column's index and the tick, so the same tick always draws the same value;
• :discrete — min + rem(t + n, max − min + 1).

The window slides: tick 25 over a window of 24 yields ticks 2..25, and the next tick drops 2 and adds 26. pool(signals, tick) yields a pool, name to rows, for a map of named signals, ready for Visualize.Chart.apply/2.

8.3 Functions

9. FFT

9.1 The transform

Visualize.Data.FFT (#375) is the fast Fourier transform in pure Elixir: a radix-2 Cooley–Tukey decimation in time over lists, O(N log N), with no native code. fft/1 takes a sequence whose length is a power of two — numbers read as real, {re, im} pairs as complex — and returns the N complex terms X_k = Σ x_n e^{−2πi kn/N} as {re, im} pairs; any other length raises ArgumentError. magnitudes/1 is sqrt(re² + im²) of every term. Parseval holds: the sum of the squared magnitudes over N equals the sum of the squared samples, to floating precision.

9.2 Windows and the spectrum

window/2 tapers a sequence by :hann (0.5 − 0.5 cos(2πi/(N−1))), :hamming (0.54 − 0.46 cos(2πi/(N−1))) or :none — a sequence shorter than four is not tapered, the Hann of two points being all zeros; windows/0 lists them, :hann first. spectrum/3 is the reading a chart draws: spectrum(values, every, opts) takes the newest samples values — the option, a power of two, else the largest power of two not above the count — subtracts their mean when detrend: true (#376; an offset otherwise leaks from the DC line into its neighbours under a window), tapers them, transforms them and returns samples / 2 lines %{frequency, magnitude, phase}: frequency is k / (samples · every) in hertz for every seconds between samples; magnitude the one-sided amplitude |X_k| · 2 / (samples · gain) with the window's mean gain divided out, so a sine of amplitude A reads A at its frequency whatever the taper, the DC line not doubled; phase the argument of X_k. Fewer than two values, or fewer than samples, yield []. A 4096-point spectrum costs single-digit milliseconds, a 1024-point one about two. The test suite holds the cost's growth by count, not by clock (#462): four times the samples is under six times the work in reductions, as n log n gives and a quadratic transform's sixteen does not; the millisecond figures are a :benchmark test, stated rather than gated (12-testing-and-conformance §6).

9.3 Functions