Layer-type registry — keyword → layer-type map (mark + stat + position).
Layer types are plain data maps. The registry makes them discoverable
and extensible. Use lookup to get a layer type by keyword, registered
to enumerate all layer types, and register! to add new ones.
Layer-type registry — keyword → layer-type map (mark + stat + position). Layer types are plain data maps. The registry makes them discoverable and extensible. Use `lookup` to get a layer type by keyword, `registered` to enumerate all layer types, and `register!` to add new ones.
(channel-magnitude-fn layer channel bufs)A function from a value in bufs to the quantity a mark draws it as
-- a radius, a width, an opacity -- for channel on plan layer.
This is the drawing half of a layer type's :varies declaration.
Declaring a channel earns the layer a legend, and the legend's
swatches are built from this same function: a mark that applies it
to its own per-row buffers draws what its legend explains, and one
that scales the values itself does not.
layer is the plan layer a renderer is handed, and bufs are the
per-row buffers it will draw from -- their extremes are what the
scale reads the values against. Answers identity where the channel
is drawn as it stands (a mapping's :scale false), so a renderer
can apply the result either way, and nil where there is nothing to
draw.
(let [f (layer-type/channel-magnitude-fn layer :size (keep :sizes groups))]
(if sizes (f (sizes i)) default-radius))
A function from a value in `bufs` to the quantity a mark draws it as
-- a radius, a width, an opacity -- for `channel` on plan `layer`.
This is the drawing half of a layer type's `:varies` declaration.
Declaring a channel earns the layer a legend, and the legend's
swatches are built from this same function: a mark that applies it
to its own per-row buffers draws what its legend explains, and one
that scales the values itself does not.
`layer` is the plan layer a renderer is handed, and `bufs` are the
per-row buffers it will draw from -- their extremes are what the
scale reads the values against. Answers `identity` where the channel
is drawn as it stands (a mapping's `:scale false`), so a renderer
can apply the result either way, and nil where there is nothing to
draw.
(let [f (layer-type/channel-magnitude-fn layer :size (keep :sizes groups))]
(if sizes (f (sizes i)) default-radius))What a channel is taken to be drawn as where the mark declares nothing. Reached only for a mark that draws the channel without saying so -- which the plan warns about -- and set to what the built-in marks do.
Its keys are also the channels a mark may declare it varies: these
are the two the plan and the scale ask about, so a :varies naming
any other channel would be read by nothing.
What a channel is taken to be drawn as where the mark declares nothing. Reached only for a mark that draws the channel without saying so -- which the plan warns about -- and set to what the built-in marks do. Its keys are also the channels a mark may declare it varies: these are the two the plan and the scale ask about, so a `:varies` naming any other channel would be read by nothing.
(ink-exponent mark channel)How the ink a mark covers grows with the quantity it draws channel
as. What lets a scale's :by mean one thing across marks that draw
different shapes.
How the ink a mark covers grows with the quantity it draws `channel` as. What lets a scale's `:by` mean one thing across marks that draw different shapes.
Documentation for layer option keys. Maps key to description string.
Documentation for layer option keys. Maps key to description string.
Canonical display order for built-in layer types.
Canonical display order for built-in layer types.
(lookup k)Look up a registered layer type by keyword. Returns the layer-type map (with :mark, :stat, :position, :doc), or nil if not found.
Look up a registered layer type by keyword. Returns the layer-type map (with :mark, :stat, :position, :doc), or nil if not found.
(mark-varies mark channel)The quantity mark draws channel as from row to row, or nil where
it draws one value for the whole layer.
Asked of the mark rather than of the layer type, because a layer can
name its own :mark and because two layer types sharing a mark draw
the same thing — :label is :text with a box preset on. Derived by
looking through the registry rather than stored beside it, so one
register! call is still the whole of the extension contract.
register! refuses a disagreement, so the first entry found answers
for the mark.
The quantity `mark` draws `channel` as from row to row, or nil where it draws one value for the whole layer. Asked of the mark rather than of the layer type, because a layer can name its own `:mark` and because two layer types sharing a mark draw the same thing — `:label` is `:text` with a box preset on. Derived by looking through the registry rather than stored beside it, so one `register!` call is still the whole of the extension contract. `register!` refuses a disagreement, so the first entry found answers for the mark.
(marks-varying channel)Every mark that varies channel from row to row, as a set. What the
plan's messages name when a column is mapped to a channel no mark on
the plot draws.
Every mark that varies `channel` from row to row, as a set. What the plan's messages name when a column is mapped to a channel no mark on the plot draws.
The quantities a mark can draw an appearance channel as, and what
each one implies. A mark names one of these per channel it varies
from row to row, under :varies.
:ink-exponent — how the ink a mark covers grows with the
quantity. A circle's radius and a square's side both square it; a
stroke's width does not. It is what makes {:by :area} mean the
same thing on every mark: area is the quantity raised to this
power, so the scale can spread ink evenly without knowing which
shape draws it.:swatch — what the legend draws to explain the channel. A width
encoding explained by graduated circles has the reader comparing
diameters while the panel shows thicknesses.:opacity is the odd one: it is not a geometry, so nothing about
area applies to it, and its exponent is 1 only in the sense that it
has no shape to grow. :geometry? records that difference, which is
what lets register! refuse a channel drawn as a quantity of the
wrong kind -- an opacity declared as a radius is not inert, it
squares the opacity curve.
The quantities a mark can draw an appearance channel as, and what
each one implies. A mark names one of these per channel it varies
from row to row, under `:varies`.
- `:ink-exponent` — how the ink a mark covers grows with the
quantity. A circle's radius and a square's side both square it; a
stroke's width does not. It is what makes `{:by :area}` mean the
same thing on every mark: area is the quantity raised to this
power, so the scale can spread ink evenly without knowing which
shape draws it.
- `:swatch` — what the legend draws to explain the channel. A width
encoding explained by graduated circles has the reader comparing
diameters while the panel shows thicknesses.
`:opacity` is the odd one: it is not a geometry, so nothing about
area applies to it, and its exponent is 1 only in the sense that it
has no shape to grow. `:geometry?` records that difference, which is
what lets `register!` refuse a channel drawn as a quantity of the
wrong kind -- an opacity declared as a radius is not inert, it
squares the opacity curve.(register! k entry)Register a layer type. k is a keyword, entry is a map with
:mark, :stat, and optionally :position and :doc.
Position defaults to nil (identity) — only :dodge, :stack, :fill are explicit.
:defaults is an optional map of layer-option values the layer type
presets — how one layer type differs from another that shares its mark
by the options it starts with rather than by what it draws. :label is
:text with {:box true}. Options passed at the call site win over
these; see resolve-layer-type-info in impl/pose.clj.
:varies is an optional map from appearance channel to the quantity
the mark draws it as, from quantities — :point declares
{:size :radius :alpha :opacity}. A channel absent from the map is
one the mark draws once for the whole layer, so a column mapped to
it varies nothing: :line takes one stroke width whatever the
column holds.
Two things read the declaration, and both were closed tables before
it existed. The plan asks it whether a column mapped to a channel is
drawn at all — a mark it had never heard of answered no, so an
extension that varied size per row was warned about and denied its
legend while drawing correctly. The scale asks it which quantity to
compute, so {:by :area} lands as an area whether the mark draws a
radius or a width.
Register a layer type. `k` is a keyword, `entry` is a map with
:mark, :stat, and optionally :position and :doc.
Position defaults to nil (identity) — only :dodge, :stack, :fill are explicit.
:defaults is an optional map of layer-option values the layer type
presets — how one layer type differs from another that shares its mark
by the options it starts with rather than by what it draws. `:label` is
`:text` with `{:box true}`. Options passed at the call site win over
these; see resolve-layer-type-info in impl/pose.clj.
:varies is an optional map from appearance channel to the quantity
the mark draws it as, from `quantities` — `:point` declares
`{:size :radius :alpha :opacity}`. A channel absent from the map is
one the mark draws once for the whole layer, so a column mapped to
it varies nothing: `:line` takes one stroke width whatever the
column holds.
Two things read the declaration, and both were closed tables before
it existed. The plan asks it whether a column mapped to a channel is
drawn at all — a mark it had never heard of answered no, so an
extension that varied size per row was warned about and denied its
legend while drawing correctly. The scale asks it which quantity to
compute, so `{:by :area}` lands as an area whether the mark draws a
radius or a width.(registered)Return all registered layer types as a map of keyword → entry.
Return all registered layer types as a map of keyword → entry.
The coordinate systems a layer's :x and :y can be given in, named
by :in. :data is the default and is what every layer has always
used. :drawing-area measures in drawing units from the top left of
the panel background, inside the axis margin.
Not to be confused with :position, which is the dodge/stack/fill
adjustment a layer type carries.
The coordinate systems a layer's `:x` and `:y` can be given in, named by `:in`. `:data` is the default and is what every layer has always used. `:drawing-area` measures in drawing units from the top left of the panel background, inside the axis margin. Not to be confused with `:position`, which is the dodge/stack/fill adjustment a layer type carries.
Layer options accepted by all layer types. :x and :y are included so a layer can override the pose's position mapping (an overlay-like pattern); the four-level merge in pose/leaf->draft already honors layer-level x/y, this list keeps build-layer's unknown-option warning consistent with that behavior. :x-type/:y-type/:color-type override the inferred column types (e.g. :x-type :categorical treats a numeric x as categorical). :mark and :stat let any layer override the visual mark or statistical transform supplied by its layer-type entry; unknown keywords raise a clear error at build time.
Layer options accepted by all layer types. :x and :y are included so a layer can override the pose's position mapping (an overlay-like pattern); the four-level merge in pose/leaf->draft already honors layer-level x/y, this list keeps build-layer's unknown-option warning consistent with that behavior. :x-type/:y-type/:color-type override the inferred column types (e.g. :x-type :categorical treats a numeric x as categorical). :mark and :stat let any layer override the visual mark or statistical transform supplied by its layer-type entry; unknown keywords raise a clear error at build time.
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |