plot

Compositional visualization library inspired by Algebra of Graphics

kit-plot builds chart specifications from data, aesthetic mappings, marks, and

configuration. It can render through Vega-Lite, SVG, Plotly.js, Chart.js, and

Observable Plot.

Inspired by Daniel Slutsky's Implementing the Algebra of Graphics in Clojure - Part 1 and AlgebraOfGraphics.

Files

FileDescription
.editorconfigEditor formatting configuration
.gitignoreGit ignore rules for build artifacts and generated output
.tool-versionsasdf tool versions for Zig and Kit
LICENSEMIT license file
README.mdThis file
examples/chartjs/Chart.js examples that generate browser-ready HTML
examples/observable/Observable Plot examples that generate browser-ready HTML
examples/plotly/Plotly.js examples that generate browser-ready HTML
examples/svg/SVG examples, including rainbow charts and PCA biplots
examples/vega-lite/Vega-Lite examples that generate browser-ready HTML
kit.tomlPackage manifest, capabilities, dependency, and task definitions
src/plot.kitPublic Kit.Plot entry point and backend re-exports
src/plot-core.kitCore plotting API without backend re-exports
src/core.kitCore plotting API without backend re-exports, used by examples and backends
src/types.kitPublic type wrapper for plot values, marks, themes, scales, and configs
src/internal/types.kitInternal type definitions used by the core and backend modules
src/shared.kitShared backend helpers, data extraction, and JSON serialization
src/backends/chartjs.kitChart.js backend
src/backends/observable.kitObservable Plot backend
src/backends/plotly.kitPlotly.js backend
src/backends/svg.kitSVG backend built on kit-svg
src/backends/vega-lite.kitVega-Lite JSON and HTML backend
tests/integration.test.kitIntegration tests
tests/plot.test.kitCore plotting tests

Dependencies

  • kit-svg - Type-safe SVG generation for Kit.

The HTML backends emit CDN-backed pages for browser rendering. These JavaScript

libraries are not bundled into the Kit package.

Installation

kit add gitlab.com/kit-lang/packages/kit-plot.git

Usage

import File
import Kit.Plot as Plot

sales = [
  [("month", Plot.from-string "Jan"), ("value", Plot.from-float 120.0)],
  [("month", Plot.from-string "Feb"), ("value", Plot.from-float 150.0)],
  [("month", Plot.from-string "Mar"), ("value", Plot.from-float 180.0)]
]

spec = sales
  |> Plot.data
  |> Plot.x "month"
  |> Plot.y "value"
  |> Plot.bar
  |> Plot.to-spec
  |> Plot.title "Monthly Sales"
  |> Plot.x-label "Month"
  |> Plot.y-label "Sales"

html = Plot.to-vega-lite-html spec
file-path = "/tmp/kit-plot-sales.html"

main = fn(env: Env) =>
  match env.root
    | RootAuth ->
      match File.write file-path html
        | Ok _ ->
          println "Saved to: ${file-path}"
          println "Open in browser: ${file-path}"
        | Err e ->
          println "Error writing file: ${show e}"

main

Run an example with file-write capability:

kit run --allow=file,file-write examples/vega-lite/bar-chart.kit

Core Concepts

Data-First Composition

Most functions take the layer or spec first so they work naturally in pipes:

spec = data
  |> Plot.data
  |> Plot.x "x"
  |> Plot.y "y"
  |> Plot.scatter
  |> Plot.to-spec
  |> Plot.title "Sample Scatter Plot"

Aesthetic Mappings

FunctionDescription
Plot.xX-axis position
Plot.yY-axis position
Plot.colorColor encoding
Plot.sizeSize encoding
Plot.shapeShape encoding
Plot.alphaOpacity encoding
Plot.fillFill color
Plot.strokeStroke color
Plot.labelText labels

Visual Marks

FunctionDescription
Plot.scatterScatter plot
Plot.lineLine chart
Plot.barBar chart
Plot.areaArea chart
Plot.histogramHistogram
Plot.boxplotBox plot
Plot.textText marks
Plot.ruleReference lines
Plot.pie / Plot.donutPie and donut charts
Plot.heatmapHeatmap
Plot.violinViolin plot
Plot.waterfallWaterfall chart
Plot.funnelFunnel chart
Plot.candlestick / Plot.ohlcFinancial OHLC charts
Plot.radarRadar chart
Plot.treemapTreemap
Plot.rainbowLog-regression rainbow bands
Plot.biplotPCA biplot

Backends

Kit.Plot re-exports the common backend functions:

FunctionOutput
Plot.to-vega-liteVega-Lite JSON
Plot.to-vega-lite-htmlVega-Lite HTML
Plot.to-svgSVG string
Plot.to-plotlyPlotly JSON
Plot.to-plotly-htmlPlotly HTML
Plot.to-chartjsChart.js JSON
Plot.to-chartjs-htmlChart.js HTML
Plot.to-observableObservable Plot JavaScript
Plot.to-observable-htmlObservable Plot HTML

Backend Support Matrix

Chart TypeVega-LiteSVGPlotlyChart.jsObservable
Scatteryesyesyesyesyes
Lineyesyesyesyesyes
Baryesyesyesyesyes
Areayesyesyesyes
Histogramyesyesyesyesyes
Boxplotyesyesyes
Textyes
Ruleyesyes
Pie / Donutyesyesyesyes
Heatmapyesyesyesyes
Lollipopyesyesyesyes
Densityyesyesyesyes
Stripyesyesyesyes
Violinyesyesyes
Waterfallyesyesyesyesyes
Funnelyesyesyesyesyes
Candlestickyesyesyesyesyes
OHLCyesyesyesyesyes
Error Baryesyesyesyes
Radaryesyes
Treemapyes
Rainbowyesyes
Biplotyesyes

Specialized Charts

Plot.rainbow overlays logarithmically-spaced colored bands on price data.

Use Plot.rainbow-with-config with Plot.default-rainbow-config when labels,

colors, or regression settings need to be customized.

Plot.biplot computes PCA scores and loadings directly in Kit. Fields mapped to

aesthetics such as color or label are excluded from PCA automatically. Use

Plot.biplot-with-config when you need to select components, standardize values,

or adjust loading arrows.

Development

Running Examples

Run examples with the interpreter:

kit run --allow=file,file-write examples/vega-lite/bar-chart.kit

Compile an example to verify native code generation:

kit build examples/vega-lite/bar-chart.kit -o /tmp/kit-plot-bar-chart --allow=file,file-write

The examples are marked @check(interactive) because they write files and are

intended to be inspected in a browser. Parity checks build them but does not

execute the compiled binaries.

Running Tests

Run the test suite:

kit test

Run the test suite with coverage:

kit test --coverage

Running kit dev

Run the standard development workflow:

kit dev

This formats and checks source files, then runs the test suite with coverage.

Running Parity

Check examples through the interpreter and native compiler:

kit parity --no-spinner --failures-only

Generating Documentation

Generate API documentation from doc comments:

kit doc

Kit sources with doc comments (##) generate HTML documents in docs/*.html.

Cleaning Build Artifacts

Remove generated files, caches, and build artifacts:

kit task clean

Defined in kit.toml.

Local Installation

To install this package locally for development:

kit install

This installs the package to ~/.kit/packages/@kit/plot/, making it available

for import as Kit.Plot in other projects.

License

This package is released under the MIT License - see LICENSE for details.

Third-Party Licenses

kit-plot can generate output for these browser visualization libraries:

LibraryLicense
Chart.jsMIT License
Vega-LiteBSD 3-Clause License
Plotly.jsMIT License
Observable PlotISC License

Exported Functions & Types

value-to-json

Convert a plot Value to a JSONValue.

Value -> JSONValue

value-to-json (VInt 42)  # => JSONInt 42
value-to-json (VString "hello")  # => JSONString "hello"

lookup-field

Look up a field value in a data row by field name.

List (String, Value) -> String -> Option Value

row = [("x", VInt 10), ("y", VInt 20)]
lookup-field row "x"  # => Some (VInt 10)
lookup-field row "z"  # => None

has-field?

Check if a data row has a specific field.

List (String, Value) -> String -> Bool

row = [("x", VInt 10)]
has-field? row "x"  # => true
has-field? row "z"  # => false

get-field-value

Get a field value as JSONValue, defaulting to JSONNull if not found.

List (String, Value) -> String -> JSONValue

row = [("x", VInt 10)]
get-field-value row "x"  # => JSONInt 10
get-field-value row "z"  # => JSONNull

row-to-json

Convert a data row to a JSONObject.

List (String, Value) -> JSONValue

row = [("x", VInt 10), ("y", VInt 20)]
row-to-json row  # => JSONObject [("x", JSONInt 10), ("y", JSONInt 20)]

dataset-to-json

Convert a dataset (list of rows) to a JSONArray.

List (List (String, Value)) -> JSONValue

data = [[("x", VInt 1)], [("x", VInt 2)]]
dataset-to-json data  # => JSONArray [JSONObject [...], ...]

json-escape

Escape a string for inclusion in JSON output.

String -> String

json-stringify

Convert a JSONValue to a JSON string.

JSONValue -> String

extract-values

Extract values from a field as a JSONArray.

List (List (String, Value)) -> String -> JSONValue

data = [[("x", VInt 1)], [("x", VInt 2)], [("y", VInt 3)]]
extract-values data "x"  # => JSONArray [JSONInt 1, JSONInt 2]

extract-values-list

Extract values as a list (for internal processing).

List (List (String, Value)) -> NonEmptyString -> List JSONValue

extract-unique-values

Extract unique values from a field as a JSONArray.

List (List (String, Value)) -> String -> JSONValue

data = [[("x", VString "a")], [("x", VString "b")], [("x", VString "a")]]
extract-unique-values data "x"  # => JSONArray [JSONString "a", JSONString "b"]

get-field-for-channel

Get the field name for a specific aesthetic channel from mappings.

List AesMapping -> AesChannel -> Option String

mappings = [{channel: AesX, field: "date"}, {channel: AesY, field: "value"}]
get-field-for-channel mappings AesX  # => Some "date"
get-field-for-channel mappings AesSize  # => None

get-x-field

Get x field name from aesthetic mappings, defaulting to "x".

List AesMapping -> String

get-y-field

Get y field name from aesthetic mappings, defaulting to "y".

List AesMapping -> String

get-color-field

Get color field name from aesthetic mappings (optional).

List AesMapping -> Option String

get-size-field

Get size field name from aesthetic mappings (optional).

List AesMapping -> Option String

get-series-color

Get a color from the palette by index. Falls back to primary color if index is out of bounds.

Palette -> Int -> String

palette = {primary: "#000", colors: ["#f00", "#0f0", "#00f"], ...}
get-series-color palette 0  # => "#f00"
get-series-color palette 99  # => "#000"

build-object-optional

Build a JSONObject, filtering out pairs where the value is None. Useful for constructing JSON with optional fields.

List (String, Option JSONValue) -> JSONValue

build-object-optional [
  ("name", Some (JSONString "test")),
  ("age", None)
]
# => JSONObject [("name", JSONString "test")]

build-object-nonempty

Build a JSONObject from a list of key-value pairs. Filters out pairs where the value is an empty string (for string values).

List (String, JSONValue) -> JSONValue

jstring

Convenience: wrap a string in JSONString.

String -> JSONValue

jint

Convenience: wrap an int in JSONInt.

Int -> JSONValue

jfloat

Convenience: wrap a float in JSONFloat.

Float -> JSONValue

jbool

Convenience: wrap a bool in JSONBool.

Bool -> JSONValue

jarray

Convenience: create a JSONArray.

List JSONValue -> JSONValue

jobject

Convenience: create a JSONObject.

List (String, JSONValue) -> JSONValue

compute-log-regression

Compute logarithmic regression coefficients (a, b) for data points. Fits log(y) = a * ln(x_index + 1) + b via least-squares. Returns (a, b) as a tuple.

[Float] -> (Float, Float)

compute-rainbow-bands

Compute rainbow band boundaries for each data point. Given regression params (a, b), number of bands, and a spread factor, returns a list of (regression-value, [band-boundary]) for each x index. Each element is a list of (num-bands + 1) boundary values evenly spaced in log space.

(Float, Float) -> Int -> Float -> Int -> [(Float, [Float])]

is-value-numeric?

Check if a Value is numeric (Int or Float).

Value -> Bool

value-to-float-num

Convert a Value to Float. Returns 0.0 for non-numeric values.

Value -> Float

extract-numeric-fields

Identify numeric field names from the first data row.

DataRow -> [String]

extract-numeric-matrix

Extract a matrix of floats from a dataset for given field names. Returns [[Float]] where each inner list is a row of values.

DataSet -> [String] -> [[Float]]

vec-dot

Dot product of two vectors.

[Float] -> [Float] -> Float

vec-norm

Euclidean norm of a vector.

[Float] -> Float

vec-normalize

Normalize a vector to unit length.

[Float] -> [Float]

vec-scale

Scalar * vector.

Float -> [Float] -> [Float]

vec-sub

Vector subtraction: a - b.

[Float] -> [Float] -> [Float]

mat-vec-mul

Matrix-vector multiplication: mat * vec. mat is [[Float]] (list of rows), vec is [Float].

[[Float]] -> [Float] -> [Float]

compute-column-means

Compute column-wise means of a matrix.

[[Float]] -> [Float]

compute-column-stds

Compute column-wise standard deviations of a matrix (given means).

[[Float]] -> [Float] -> [Float]

center-matrix

Center a matrix by subtracting column means from each row.

[[Float]] -> [Float] -> [[Float]]

standardize-matrix

Standardize a centered matrix by dividing by column standard deviations.

[[Float]] -> [Float] -> [[Float]]

compute-covariance

Compute the covariance matrix from a centered matrix. Returns [[Float]] of size p x p.

[[Float]] -> [[Float]]

deflate-matrix

Remove an eigenvector's contribution from a matrix: A' = A - lambda * v * vT.

[[Float]] -> Float -> [Float] -> [[Float]]

power-iteration

Extract the dominant eigenvector via power iteration. Returns (eigenvalue, eigenvector).

[[Float]] -> Int -> (Float, [Float])

compute-pca

Full PCA pipeline: extract fields, center, [standardize], covariance, power iteration. Returns {scores: [[Float]], loadings: [[Float]], variance-pct: [Float], field-names: [String]}.

DataSet -> BiplotConfig -> [String] -> {scores: [[Float]], loadings: [[Float]], variance-pct: [Float], field-names: [String]}

from-int

Convert an integer to a Value.

Int -> Value

from-float

Convert a float to a Value.

Float -> Value

from-string

Convert a string to a Value.

String -> Value

from-bool

Convert a boolean to a Value.

Bool -> Value

null-value

The null value constant.

is-null?

Check if a value is null.

Value -> Bool

is-numeric?

Check if a value is numeric (int or float).

Value -> Bool

value-to-int

Extract an integer from a Value, if present.

Value -> Option Int

value-to-float

Extract a float from a Value, converting ints if needed.

Value -> Option Float

row

Create a data row from a list of field/value pairs.

[(String, Value)] -> DataRow

get-field

Get a field value from a data row by key.

NonEmptyString -> DataRow -> Option Value

empty-dataset

An empty dataset with no rows.

from-rows

Create a dataset from a list of rows.

[DataRow] -> DataSet

row-count

Get the number of rows in a dataset.

DataSet -> Int

data

Create a layer from a dataset. Entry point for the pipe API.

DataSet -> Layer

layer

An empty layer constant.

add-mapping

Add an aesthetic mapping to a layer.

Layer -> AesChannel -> String -> Layer

set-visual

Set the visual mark type for a layer.

Visual -> Layer -> Layer

set-stat

Set the statistical transformation for a layer.

Stat -> Layer -> Layer

add-scale

Add a scale to a layer for a specific channel.

Layer -> AesChannel -> Scale -> Layer

layer-label

Set the label (series name) for a layer. Used for legends.

Layer -> NonEmptyString -> Layer

get-mapping

Get an aesthetic mapping from a layer by channel.

Layer -> AesChannel -> Option AesMapping

has-mapping?

Check if a layer has a mapping for a channel.

Layer -> AesChannel -> Bool

get-mapped-field

Get the field name mapped to a channel, if present.

Layer -> AesChannel -> Option String

x

Map a field to the X-axis position.

Layer -> String -> Layer

y

Map a field to the Y-axis position.

Layer -> String -> Layer

color

Map a field to color encoding.

Layer -> String -> Layer

size

Map a field to size encoding.

Layer -> String -> Layer

shape

Map a field to shape encoding.

Layer -> String -> Layer

alpha

Map a field to opacity encoding.

Layer -> String -> Layer

label

Map a field to text labels.

Layer -> String -> Layer

fill

Map a field to fill color.

Layer -> String -> Layer

stroke

Map a field to stroke color.

Layer -> String -> Layer

scatter

Set the visual mark to scatter (points).

Layer -> Layer

scatter-sized

Set the visual mark to scatter with a specific size.

Layer -> Float -> Layer

bubble

Set the visual mark to bubble chart (scatter with data-driven size). Use with the size combinator to map a field to bubble size.

Layer -> Layer

line

Set the visual mark to line.

Layer -> Layer

line-width

Set the visual mark to line with a specific width.

Layer -> Float -> Layer

bar

Set the visual mark to bar.

Layer -> Layer

bar-position

Set the visual mark to bar with a specific position adjustment.

Layer -> BarPosition -> Layer

bar-grouped

Set the visual mark to grouped (dodged) bar for side-by-side comparison.

Layer -> Layer

bar-stacked-fill

Set the visual mark to stacked bar (normalized to 100%).

Layer -> Layer

area

Set the visual mark to area.

Layer -> Layer

area-stacked

Set the visual mark to stacked area.

Layer -> Layer

area-fill

Set the visual mark to normalized stacked area (100% fill).

Layer -> Layer

histogram

Set the visual mark to histogram.

Layer -> Layer

histogram-bins

Set the visual mark to histogram with a specific number of bins.

Layer -> Int -> Layer

boxplot

Set the visual mark to boxplot.

Layer -> Layer

text

Set the visual mark to text.

Layer -> Layer

rule

Set the visual mark to rule (reference line).

Layer -> Layer

pie

Set the visual mark to pie chart.

Layer -> Layer

donut

Set the visual mark to donut chart (pie with inner radius).

Layer -> Layer

donut-with-radius

Set the visual mark to donut chart with custom inner radius.

Layer -> Float -> Layer

heatmap

Set the visual mark to heatmap.

Layer -> Layer

heatmap-with-scheme

Set the visual mark to heatmap with a specific color scheme.

Layer -> ColorScheme -> Layer

lollipop

Set the visual mark to lollipop (dot + stem).

Layer -> Layer

lollipop-sized

Set the visual mark to lollipop with custom dot size.

Layer -> Float -> Layer

density

Set the visual mark to density plot (kernel density estimation).

Layer -> Layer

density-bandwidth

Set the visual mark to density plot with custom bandwidth.

Layer -> Float -> Layer

strip

Set the visual mark to strip plot (categorical scatter).

Layer -> Layer

jitter

Set the visual mark to strip plot with jitter for overlapping points.

Layer -> Float -> Layer

violin

Set the visual mark to violin plot (distribution shape by category).

Layer -> Layer

violin-bandwidth

Set the visual mark to violin plot with custom bandwidth.

Layer -> Float -> Layer

waterfall

Set the visual mark to waterfall chart (with connectors).

Layer -> Layer

waterfall-no-connectors

Set the visual mark to waterfall chart without connectors.

Layer -> Layer

funnel

Set the visual mark to funnel chart (vertical orientation).

Layer -> Layer

funnel-horizontal

Set the visual mark to funnel chart with horizontal orientation.

Layer -> Layer

candlestick

Set the visual mark to candlestick chart with default field names (open, high, low, close).

Layer -> Layer

candlestick-fields

Set the visual mark to candlestick chart with custom field names.

Layer -> String -> String -> String -> String -> Layer

ohlc

Set the visual mark to OHLC bar chart with default field names (open, high, low, close).

Layer -> Layer

ohlc-fields

Set the visual mark to OHLC bar chart with custom field names.

Layer -> String -> String -> String -> String -> Layer

error-bar

Set the visual mark to error bars (symmetric error using a single error field). Displays scatter points with vertical error bars.

Layer -> String -> Layer

error-bar-asymmetric

Set the visual mark to asymmetric error bars (different upper and lower errors).

Layer -> String -> String -> Layer

radar

Set the visual mark to radar/spider chart. The axes parameter lists the field names for each axis. Supported by Chart.js (native) and Plotly (scatterpolar).

Layer -> [String] -> Layer

radar-with-opacity

Set the visual mark to radar chart with custom fill opacity.

Layer -> [String] -> UnitFloat -> Layer

treemap

Set the visual mark to treemap for hierarchical data. Requires id-field (unique identifier), parent-field (parent id, empty string for root), and value-field (size of each node). Supported by Plotly (native treemap type).

Layer -> String -> String -> String -> Layer

treemap-with-labels

Set the visual mark to treemap with custom label field.

Layer -> String -> String -> String -> String -> Layer

rainbow

Set the visual mark to rainbow chart with default 9-band Bitcoin-style configuration. Overlays logarithmic regression bands on price data to indicate valuation zones.

Layer -> Layer

rainbow-with-config

Set the visual mark to rainbow chart with custom configuration.

Layer -> RainbowConfig -> Layer

biplot

Set the visual mark to PCA biplot with default configuration. Auto-computes PCA on all numeric columns, excluding aesthetic-mapped fields. No Plot.x/Plot.y needed — axes are set to PC1/PC2 with variance labels.

Layer -> Layer

biplot-with-config

Set the visual mark to PCA biplot with custom configuration.

Layer -> BiplotConfig -> Layer

stat-identity

Apply identity transformation (no change).

Layer -> Layer

stat-count

Apply count aggregation.

Layer -> Layer

stat-bin

Apply binning transformation.

Layer -> Layer

stat-bin-n

Apply binning transformation with a specific number of bins.

Layer -> Int -> Layer

stat-smooth

Apply LOESS smoothing transformation.

Layer -> Layer

stat-smooth-linear

Apply linear regression smoothing.

Layer -> Layer

stat-smooth-loess

Apply LOESS smoothing transformation.

Layer -> Layer

scale-x-linear

Set X-axis to linear scale.

Layer -> Layer

scale-x-log

Set X-axis to logarithmic scale.

Layer -> Layer

scale-x-sqrt

Set X-axis to square root scale.

Layer -> Layer

scale-x-time

Set X-axis to time scale.

Layer -> Layer

scale-y-linear

Set Y-axis to linear scale.

Layer -> Layer

scale-y-log

Set Y-axis to logarithmic scale.

Layer -> Layer

scale-y-sqrt

Set Y-axis to square root scale.

Layer -> Layer

scale-y-time

Set Y-axis to time scale.

Layer -> Layer

scale-color

Set color scale with a specific scheme.

Layer -> ColorScheme -> Layer

scale-color-categorical

Set color scale to categorical (category10).

Layer -> Layer

scale-color-viridis

Set color scale to viridis.

Layer -> Layer

scale-color-blues

Set color scale to blues.

Layer -> Layer

scale-color-greens

Set color scale to greens.

Layer -> Layer

scale-color-reds

Set color scale to reds.

Layer -> Layer

to-spec

Convert a layer to a plot specification.

Layer -> PlotSpec

overlay

Create a plot specification from multiple layers (overlay).

[Layer] -> PlotSpec

layers

Alias for overlay.

[Layer] -> PlotSpec

title

Set the plot title.

PlotSpec -> String -> PlotSpec

subtitle

Set the plot subtitle.

PlotSpec -> String -> PlotSpec

x-label

Set the X-axis label.

PlotSpec -> String -> PlotSpec

y-label

Set the Y-axis label.

PlotSpec -> String -> PlotSpec

dimensions

Set the plot dimensions (width and height).

PlotSpec -> PositiveInt -> PositiveInt -> PlotSpec

width

Set the plot width.

PlotSpec -> PositiveInt -> PlotSpec

height

Set the plot height.

PlotSpec -> PositiveInt -> PlotSpec

facet-wrap

Apply wrap faceting by a field.

PlotSpec -> String -> PlotSpec

facet-wrap-cols

Apply wrap faceting with a specific number of columns.

PlotSpec -> String -> Int -> PlotSpec

facet-grid

Apply grid faceting by row and column fields.

PlotSpec -> Option String -> Option String -> PlotSpec

facet-row

Apply row faceting by a field.

PlotSpec -> String -> PlotSpec

facet-col

Apply column faceting by a field.

PlotSpec -> String -> PlotSpec

theme

Set a custom theme for the plot.

PlotSpec -> PlotTheme -> PlotSpec

theme-dark

Apply the dark theme to the plot.

PlotSpec -> PlotSpec

theme-minimal

Apply the minimal theme to the plot.

PlotSpec -> PlotSpec

animate

Enable animation with a specific duration in milliseconds.

PlotSpec -> Int -> PlotSpec

animate-with-easing

Enable animation with duration and easing.

PlotSpec -> Int -> AnimationEasing -> PlotSpec

no-animate

Disable animation.

PlotSpec -> PlotSpec

legend-position

Set the legend position.

PlotSpec -> LegendPosition -> PlotSpec

legend-title

Set the legend title.

PlotSpec -> String -> PlotSpec

legend-font-size

Set the legend font size.

PlotSpec -> Int -> PlotSpec

no-legend

Hide the legend.

PlotSpec -> PlotSpec

from-int

Convert an integer to a Value.

Int -> Value

from-float

Convert a float to a Value.

Float -> Value

from-string

Convert a string to a Value.

String -> Value

from-bool

Convert a boolean to a Value.

Bool -> Value

null-value

The null value constant.

is-null?

Check if a value is null.

Value -> Bool

is-numeric?

Check if a value is numeric (int or float).

Value -> Bool

value-to-int

Extract an integer from a Value, if present.

Value -> Option Int

value-to-float

Extract a float from a Value, converting ints if needed.

Value -> Option Float

row

Create a data row from a list of field/value pairs.

[(String, Value)] -> DataRow

get-field

Get a field value from a data row by key.

NonEmptyString -> DataRow -> Option Value

empty-dataset

An empty dataset with no rows.

from-rows

Create a dataset from a list of rows.

[DataRow] -> DataSet

row-count

Get the number of rows in a dataset.

DataSet -> Int

data

Create a layer from a dataset. Entry point for the pipe API.

DataSet -> Layer

layer

An empty layer constant.

add-mapping

Add an aesthetic mapping to a layer.

Layer -> AesChannel -> String -> Layer

set-visual

Set the visual mark type for a layer.

Visual -> Layer -> Layer

set-stat

Set the statistical transformation for a layer.

Stat -> Layer -> Layer

add-scale

Add a scale to a layer for a specific channel.

Layer -> AesChannel -> Scale -> Layer

layer-label

Set the label (series name) for a layer. Used for legends.

Layer -> NonEmptyString -> Layer

get-mapping

Get an aesthetic mapping from a layer by channel.

Layer -> AesChannel -> Option AesMapping

has-mapping?

Check if a layer has a mapping for a channel.

Layer -> AesChannel -> Bool

get-mapped-field

Get the field name mapped to a channel, if present.

Layer -> AesChannel -> Option String

x

Map a field to the X-axis position.

Layer -> String -> Layer

y

Map a field to the Y-axis position.

Layer -> String -> Layer

color

Map a field to color encoding.

Layer -> String -> Layer

size

Map a field to size encoding.

Layer -> String -> Layer

shape

Map a field to shape encoding.

Layer -> String -> Layer

alpha

Map a field to opacity encoding.

Layer -> String -> Layer

label

Map a field to text labels.

Layer -> String -> Layer

fill

Map a field to fill color.

Layer -> String -> Layer

stroke

Map a field to stroke color.

Layer -> String -> Layer

scatter

Set the visual mark to scatter (points).

Layer -> Layer

scatter-sized

Set the visual mark to scatter with a specific size.

Layer -> Float -> Layer

bubble

Set the visual mark to bubble chart (scatter with data-driven size). Use with the size combinator to map a field to bubble size.

Layer -> Layer

line

Set the visual mark to line.

Layer -> Layer

line-width

Set the visual mark to line with a specific width.

Layer -> Float -> Layer

bar

Set the visual mark to bar.

Layer -> Layer

bar-position

Set the visual mark to bar with a specific position adjustment.

Layer -> BarPosition -> Layer

bar-grouped

Set the visual mark to grouped (dodged) bar for side-by-side comparison.

Layer -> Layer

bar-stacked-fill

Set the visual mark to stacked bar (normalized to 100%).

Layer -> Layer

area

Set the visual mark to area.

Layer -> Layer

area-stacked

Set the visual mark to stacked area.

Layer -> Layer

area-fill

Set the visual mark to normalized stacked area (100% fill).

Layer -> Layer

histogram

Set the visual mark to histogram.

Layer -> Layer

histogram-bins

Set the visual mark to histogram with a specific number of bins.

Layer -> Int -> Layer

boxplot

Set the visual mark to boxplot.

Layer -> Layer

text

Set the visual mark to text.

Layer -> Layer

rule

Set the visual mark to rule (reference line).

Layer -> Layer

pie

Set the visual mark to pie chart.

Layer -> Layer

donut

Set the visual mark to donut chart (pie with inner radius).

Layer -> Layer

donut-with-radius

Set the visual mark to donut chart with custom inner radius.

Layer -> Float -> Layer

heatmap

Set the visual mark to heatmap.

Layer -> Layer

heatmap-with-scheme

Set the visual mark to heatmap with a specific color scheme.

Layer -> ColorScheme -> Layer

lollipop

Set the visual mark to lollipop (dot + stem).

Layer -> Layer

lollipop-sized

Set the visual mark to lollipop with custom dot size.

Layer -> Float -> Layer

density

Set the visual mark to density plot (kernel density estimation).

Layer -> Layer

density-bandwidth

Set the visual mark to density plot with custom bandwidth.

Layer -> Float -> Layer

strip

Set the visual mark to strip plot (categorical scatter).

Layer -> Layer

jitter

Set the visual mark to strip plot with jitter for overlapping points.

Layer -> Float -> Layer

violin

Set the visual mark to violin plot (distribution shape by category).

Layer -> Layer

violin-bandwidth

Set the visual mark to violin plot with custom bandwidth.

Layer -> Float -> Layer

waterfall

Set the visual mark to waterfall chart (with connectors).

Layer -> Layer

waterfall-no-connectors

Set the visual mark to waterfall chart without connectors.

Layer -> Layer

funnel

Set the visual mark to funnel chart (vertical orientation).

Layer -> Layer

funnel-horizontal

Set the visual mark to funnel chart with horizontal orientation.

Layer -> Layer

candlestick

Set the visual mark to candlestick chart with default field names (open, high, low, close).

Layer -> Layer

candlestick-fields

Set the visual mark to candlestick chart with custom field names.

Layer -> String -> String -> String -> String -> Layer

ohlc

Set the visual mark to OHLC bar chart with default field names (open, high, low, close).

Layer -> Layer

ohlc-fields

Set the visual mark to OHLC bar chart with custom field names.

Layer -> String -> String -> String -> String -> Layer

error-bar

Set the visual mark to error bars (symmetric error using a single error field). Displays scatter points with vertical error bars.

Layer -> String -> Layer

error-bar-asymmetric

Set the visual mark to asymmetric error bars (different upper and lower errors).

Layer -> String -> String -> Layer

radar

Set the visual mark to radar/spider chart. The axes parameter lists the field names for each axis. Supported by Chart.js (native) and Plotly (scatterpolar).

Layer -> [String] -> Layer

radar-with-opacity

Set the visual mark to radar chart with custom fill opacity.

Layer -> [String] -> UnitFloat -> Layer

treemap

Set the visual mark to treemap for hierarchical data. Requires id-field (unique identifier), parent-field (parent id, empty string for root), and value-field (size of each node). Supported by Plotly (native treemap type).

Layer -> String -> String -> String -> Layer

treemap-with-labels

Set the visual mark to treemap with custom label field.

Layer -> String -> String -> String -> String -> Layer

rainbow

Set the visual mark to rainbow chart with default 9-band Bitcoin-style configuration. Overlays logarithmic regression bands on price data to indicate valuation zones.

Layer -> Layer

rainbow-with-config

Set the visual mark to rainbow chart with custom configuration.

Layer -> RainbowConfig -> Layer

biplot

Set the visual mark to PCA biplot with default configuration. Auto-computes PCA on all numeric columns, excluding aesthetic-mapped fields. No Plot.x/Plot.y needed — axes are set to PC1/PC2 with variance labels.

Layer -> Layer

biplot-with-config

Set the visual mark to PCA biplot with custom configuration.

Layer -> BiplotConfig -> Layer

stat-identity

Apply identity transformation (no change).

Layer -> Layer

stat-count

Apply count aggregation.

Layer -> Layer

stat-bin

Apply binning transformation.

Layer -> Layer

stat-bin-n

Apply binning transformation with a specific number of bins.

Layer -> Int -> Layer

stat-smooth

Apply LOESS smoothing transformation.

Layer -> Layer

stat-smooth-linear

Apply linear regression smoothing.

Layer -> Layer

stat-smooth-loess

Apply LOESS smoothing transformation.

Layer -> Layer

scale-x-linear

Set X-axis to linear scale.

Layer -> Layer

scale-x-log

Set X-axis to logarithmic scale.

Layer -> Layer

scale-x-sqrt

Set X-axis to square root scale.

Layer -> Layer

scale-x-time

Set X-axis to time scale.

Layer -> Layer

scale-y-linear

Set Y-axis to linear scale.

Layer -> Layer

scale-y-log

Set Y-axis to logarithmic scale.

Layer -> Layer

scale-y-sqrt

Set Y-axis to square root scale.

Layer -> Layer

scale-y-time

Set Y-axis to time scale.

Layer -> Layer

scale-color

Set color scale with a specific scheme.

Layer -> ColorScheme -> Layer

scale-color-categorical

Set color scale to categorical (category10).

Layer -> Layer

scale-color-viridis

Set color scale to viridis.

Layer -> Layer

scale-color-blues

Set color scale to blues.

Layer -> Layer

scale-color-greens

Set color scale to greens.

Layer -> Layer

scale-color-reds

Set color scale to reds.

Layer -> Layer

to-spec

Convert a layer to a plot specification.

Layer -> PlotSpec

overlay

Create a plot specification from multiple layers (overlay).

[Layer] -> PlotSpec

layers

Alias for overlay.

[Layer] -> PlotSpec

title

Set the plot title.

PlotSpec -> String -> PlotSpec

subtitle

Set the plot subtitle.

PlotSpec -> String -> PlotSpec

x-label

Set the X-axis label.

PlotSpec -> String -> PlotSpec

y-label

Set the Y-axis label.

PlotSpec -> String -> PlotSpec

dimensions

Set the plot dimensions (width and height).

PlotSpec -> PositiveInt -> PositiveInt -> PlotSpec

width

Set the plot width.

PlotSpec -> PositiveInt -> PlotSpec

height

Set the plot height.

PlotSpec -> PositiveInt -> PlotSpec

facet-wrap

Apply wrap faceting by a field.

PlotSpec -> String -> PlotSpec

facet-wrap-cols

Apply wrap faceting with a specific number of columns.

PlotSpec -> String -> Int -> PlotSpec

facet-grid

Apply grid faceting by row and column fields.

PlotSpec -> Option String -> Option String -> PlotSpec

facet-row

Apply row faceting by a field.

PlotSpec -> String -> PlotSpec

facet-col

Apply column faceting by a field.

PlotSpec -> String -> PlotSpec

theme

Set a custom theme for the plot.

PlotSpec -> PlotTheme -> PlotSpec

theme-dark

Apply the dark theme to the plot.

PlotSpec -> PlotSpec

theme-minimal

Apply the minimal theme to the plot.

PlotSpec -> PlotSpec

animate

Enable animation with a specific duration in milliseconds.

PlotSpec -> Int -> PlotSpec

animate-with-easing

Enable animation with duration and easing.

PlotSpec -> Int -> AnimationEasing -> PlotSpec

no-animate

Disable animation.

PlotSpec -> PlotSpec

legend-position

Set the legend position.

PlotSpec -> LegendPosition -> PlotSpec

legend-title

Set the legend title.

PlotSpec -> String -> PlotSpec

legend-font-size

Set the legend font size.

PlotSpec -> Int -> PlotSpec

no-legend

Hide the legend.

PlotSpec -> PlotSpec

to-vega-lite

Convert a plot specification to Vega-Lite JSON string.

PlotSpec -> String

to-vega-lite-html

Convert a plot specification to embeddable HTML with Vega-Lite.

PlotSpec -> String

Print Vega-Lite JSON to stdout.

PlotSpec -> String

Print embeddable HTML to stdout.

PlotSpec -> String

to-svg

Convert a plot specification to SVG string.

PlotSpec -> String

to-svg-with-config

Convert a plot specification to SVG with custom configuration.

PlotSpec -> SvgConfig -> String

Print SVG to stdout.

PlotSpec -> String

to-plotly

Convert a plot specification to Plotly JSON string.

PlotSpec -> String

to-plotly-html

Convert a plot specification to embeddable HTML with Plotly.js.

PlotSpec -> String

Print Plotly JSON to stdout.

PlotSpec -> String

Print Plotly HTML to stdout.

PlotSpec -> String

to-chartjs

Convert a plot specification to Chart.js JSON string.

PlotSpec -> String

to-chartjs-html

Convert a plot specification to embeddable HTML with Chart.js.

PlotSpec -> String

Print Chart.js JSON to stdout.

PlotSpec -> String

Print Chart.js HTML to stdout.

PlotSpec -> String

to-observable

Convert a plot specification to Observable Plot JavaScript.

PlotSpec -> String

to-observable-html

Convert a plot specification to embeddable HTML with Observable Plot.

PlotSpec -> String

Print Observable Plot JavaScript to stdout.

PlotSpec -> String

Print Observable Plot HTML to stdout.

PlotSpec -> String

from-int

Convert an integer to a Value.

Int -> Value

from-float

Convert a float to a Value.

Float -> Value

from-string

Convert a string to a Value.

String -> Value

from-bool

Convert a boolean to a Value.

Bool -> Value

null-value

The null value constant.

is-null?

Check if a value is null.

Value -> Bool

is-numeric?

Check if a value is numeric (int or float).

Value -> Bool

value-to-int

Extract an integer from a Value, if present.

Value -> Option Int

value-to-float

Extract a float from a Value, converting ints if needed.

Value -> Option Float

row

Create a data row from a list of field/value pairs.

[(String, Value)] -> DataRow

get-field

Get a field value from a data row by key.

NonEmptyString -> DataRow -> Option Value

empty-dataset

An empty dataset with no rows.

from-rows

Create a dataset from a list of rows.

[DataRow] -> DataSet

row-count

Get the number of rows in a dataset.

DataSet -> Int

data

Create a layer from a dataset. Entry point for the pipe API.

DataSet -> Layer

layer

An empty layer constant.

add-mapping

Add an aesthetic mapping to a layer.

Layer -> AesChannel -> String -> Layer

set-visual

Set the visual mark type for a layer.

Visual -> Layer -> Layer

set-stat

Set the statistical transformation for a layer.

Stat -> Layer -> Layer

add-scale

Add a scale to a layer for a specific channel.

Layer -> AesChannel -> Scale -> Layer

layer-label

Set the label (series name) for a layer. Used for legends.

Layer -> NonEmptyString -> Layer

get-mapping

Get an aesthetic mapping from a layer by channel.

Layer -> AesChannel -> Option AesMapping

has-mapping?

Check if a layer has a mapping for a channel.

Layer -> AesChannel -> Bool

get-mapped-field

Get the field name mapped to a channel, if present.

Layer -> AesChannel -> Option String

x

Map a field to the X-axis position.

Layer -> String -> Layer

y

Map a field to the Y-axis position.

Layer -> String -> Layer

color

Map a field to color encoding.

Layer -> String -> Layer

size

Map a field to size encoding.

Layer -> String -> Layer

shape

Map a field to shape encoding.

Layer -> String -> Layer

alpha

Map a field to opacity encoding.

Layer -> String -> Layer

label

Map a field to text labels.

Layer -> String -> Layer

fill

Map a field to fill color.

Layer -> String -> Layer

stroke

Map a field to stroke color.

Layer -> String -> Layer

scatter

Set the visual mark to scatter (points).

Layer -> Layer

scatter-sized

Set the visual mark to scatter with a specific size.

Layer -> Float -> Layer

bubble

Set the visual mark to bubble chart (scatter with data-driven size). Use with the size combinator to map a field to bubble size.

Layer -> Layer

line

Set the visual mark to line.

Layer -> Layer

line-width

Set the visual mark to line with a specific width.

Layer -> Float -> Layer

bar

Set the visual mark to bar.

Layer -> Layer

bar-position

Set the visual mark to bar with a specific position adjustment.

Layer -> BarPosition -> Layer

bar-grouped

Set the visual mark to grouped (dodged) bar for side-by-side comparison.

Layer -> Layer

bar-stacked-fill

Set the visual mark to stacked bar (normalized to 100%).

Layer -> Layer

area

Set the visual mark to area.

Layer -> Layer

area-stacked

Set the visual mark to stacked area.

Layer -> Layer

area-fill

Set the visual mark to normalized stacked area (100% fill).

Layer -> Layer

histogram

Set the visual mark to histogram.

Layer -> Layer

histogram-bins

Set the visual mark to histogram with a specific number of bins.

Layer -> Int -> Layer

boxplot

Set the visual mark to boxplot.

Layer -> Layer

text

Set the visual mark to text.

Layer -> Layer

rule

Set the visual mark to rule (reference line).

Layer -> Layer

pie

Set the visual mark to pie chart.

Layer -> Layer

donut

Set the visual mark to donut chart (pie with inner radius).

Layer -> Layer

donut-with-radius

Set the visual mark to donut chart with custom inner radius.

Layer -> Float -> Layer

heatmap

Set the visual mark to heatmap.

Layer -> Layer

heatmap-with-scheme

Set the visual mark to heatmap with a specific color scheme.

Layer -> ColorScheme -> Layer

lollipop

Set the visual mark to lollipop (dot + stem).

Layer -> Layer

lollipop-sized

Set the visual mark to lollipop with custom dot size.

Layer -> Float -> Layer

density

Set the visual mark to density plot (kernel density estimation).

Layer -> Layer

density-bandwidth

Set the visual mark to density plot with custom bandwidth.

Layer -> Float -> Layer

strip

Set the visual mark to strip plot (categorical scatter).

Layer -> Layer

jitter

Set the visual mark to strip plot with jitter for overlapping points.

Layer -> Float -> Layer

violin

Set the visual mark to violin plot (distribution shape by category).

Layer -> Layer

violin-bandwidth

Set the visual mark to violin plot with custom bandwidth.

Layer -> Float -> Layer

waterfall

Set the visual mark to waterfall chart (with connectors).

Layer -> Layer

waterfall-no-connectors

Set the visual mark to waterfall chart without connectors.

Layer -> Layer

funnel

Set the visual mark to funnel chart (vertical orientation).

Layer -> Layer

funnel-horizontal

Set the visual mark to funnel chart with horizontal orientation.

Layer -> Layer

candlestick

Set the visual mark to candlestick chart with default field names (open, high, low, close).

Layer -> Layer

candlestick-fields

Set the visual mark to candlestick chart with custom field names.

Layer -> String -> String -> String -> String -> Layer

ohlc

Set the visual mark to OHLC bar chart with default field names (open, high, low, close).

Layer -> Layer

ohlc-fields

Set the visual mark to OHLC bar chart with custom field names.

Layer -> String -> String -> String -> String -> Layer

error-bar

Set the visual mark to error bars (symmetric error using a single error field). Displays scatter points with vertical error bars.

Layer -> String -> Layer

error-bar-asymmetric

Set the visual mark to asymmetric error bars (different upper and lower errors).

Layer -> String -> String -> Layer

radar

Set the visual mark to radar/spider chart. The axes parameter lists the field names for each axis. Supported by Chart.js (native) and Plotly (scatterpolar).

Layer -> [String] -> Layer

radar-with-opacity

Set the visual mark to radar chart with custom fill opacity.

Layer -> [String] -> UnitFloat -> Layer

treemap

Set the visual mark to treemap for hierarchical data. Requires id-field (unique identifier), parent-field (parent id, empty string for root), and value-field (size of each node). Supported by Plotly (native treemap type).

Layer -> String -> String -> String -> Layer

treemap-with-labels

Set the visual mark to treemap with custom label field.

Layer -> String -> String -> String -> String -> Layer

rainbow

Set the visual mark to rainbow chart with default 9-band Bitcoin-style configuration. Overlays logarithmic regression bands on price data to indicate valuation zones.

Layer -> Layer

rainbow-with-config

Set the visual mark to rainbow chart with custom configuration.

Layer -> RainbowConfig -> Layer

biplot

Set the visual mark to PCA biplot with default configuration. Auto-computes PCA on all numeric columns, excluding aesthetic-mapped fields. No Plot.x/Plot.y needed — axes are set to PC1/PC2 with variance labels.

Layer -> Layer

biplot-with-config

Set the visual mark to PCA biplot with custom configuration.

Layer -> BiplotConfig -> Layer

stat-identity

Apply identity transformation (no change).

Layer -> Layer

stat-count

Apply count aggregation.

Layer -> Layer

stat-bin

Apply binning transformation.

Layer -> Layer

stat-bin-n

Apply binning transformation with a specific number of bins.

Layer -> Int -> Layer

stat-smooth

Apply LOESS smoothing transformation.

Layer -> Layer

stat-smooth-linear

Apply linear regression smoothing.

Layer -> Layer

stat-smooth-loess

Apply LOESS smoothing transformation.

Layer -> Layer

scale-x-linear

Set X-axis to linear scale.

Layer -> Layer

scale-x-log

Set X-axis to logarithmic scale.

Layer -> Layer

scale-x-sqrt

Set X-axis to square root scale.

Layer -> Layer

scale-x-time

Set X-axis to time scale.

Layer -> Layer

scale-y-linear

Set Y-axis to linear scale.

Layer -> Layer

scale-y-log

Set Y-axis to logarithmic scale.

Layer -> Layer

scale-y-sqrt

Set Y-axis to square root scale.

Layer -> Layer

scale-y-time

Set Y-axis to time scale.

Layer -> Layer

scale-color

Set color scale with a specific scheme.

Layer -> ColorScheme -> Layer

scale-color-categorical

Set color scale to categorical (category10).

Layer -> Layer

scale-color-viridis

Set color scale to viridis.

Layer -> Layer

scale-color-blues

Set color scale to blues.

Layer -> Layer

scale-color-greens

Set color scale to greens.

Layer -> Layer

scale-color-reds

Set color scale to reds.

Layer -> Layer

to-spec

Convert a layer to a plot specification.

Layer -> PlotSpec

overlay

Create a plot specification from multiple layers (overlay).

[Layer] -> PlotSpec

layers

Alias for overlay.

[Layer] -> PlotSpec

title

Set the plot title.

PlotSpec -> String -> PlotSpec

subtitle

Set the plot subtitle.

PlotSpec -> String -> PlotSpec

x-label

Set the X-axis label.

PlotSpec -> String -> PlotSpec

y-label

Set the Y-axis label.

PlotSpec -> String -> PlotSpec

dimensions

Set the plot dimensions (width and height).

PlotSpec -> PositiveInt -> PositiveInt -> PlotSpec

width

Set the plot width.

PlotSpec -> PositiveInt -> PlotSpec

height

Set the plot height.

PlotSpec -> PositiveInt -> PlotSpec

facet-wrap

Apply wrap faceting by a field.

PlotSpec -> String -> PlotSpec

facet-wrap-cols

Apply wrap faceting with a specific number of columns.

PlotSpec -> String -> Int -> PlotSpec

facet-grid

Apply grid faceting by row and column fields.

PlotSpec -> Option String -> Option String -> PlotSpec

facet-row

Apply row faceting by a field.

PlotSpec -> String -> PlotSpec

facet-col

Apply column faceting by a field.

PlotSpec -> String -> PlotSpec

theme

Set a custom theme for the plot.

PlotSpec -> PlotTheme -> PlotSpec

theme-dark

Apply the dark theme to the plot.

PlotSpec -> PlotSpec

theme-minimal

Apply the minimal theme to the plot.

PlotSpec -> PlotSpec

animate

Enable animation with a specific duration in milliseconds.

PlotSpec -> Int -> PlotSpec

animate-with-easing

Enable animation with duration and easing.

PlotSpec -> Int -> AnimationEasing -> PlotSpec

no-animate

Disable animation.

PlotSpec -> PlotSpec

legend-position

Set the legend position.

PlotSpec -> LegendPosition -> PlotSpec

legend-title

Set the legend title.

PlotSpec -> String -> PlotSpec

legend-font-size

Set the legend font size.

PlotSpec -> Int -> PlotSpec

no-legend

Hide the legend.

PlotSpec -> PlotSpec