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.
(aesthetic-magnitude-fn layer aesthetic bufs)A function from a value in bufs to the quantity a mark draws it as
-- a radius, a width, an opacity -- for aesthetic on plan layer.
This is the drawing half of a layer type's :varies declaration.
Declaring an aesthetic 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
aesthetic 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/aesthetic-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 `aesthetic` on plan `layer`.
This is the drawing half of a layer type's `:varies` declaration.
Declaring an aesthetic 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
aesthetic 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/aesthetic-magnitude-fn layer :size (keep :sizes groups))]
(if sizes (f (sizes i)) default-radius))(channel-magnitude-fn & _)Retired in favour of aesthetic-magnitude-fn, which does the same
thing under the name the rest of the library uses. Reports the new
name rather than resolving to nothing.
Retired in favour of `aesthetic-magnitude-fn`, which does the same thing under the name the rest of the library uses. Reports the new name rather than resolving to nothing.
(column-counts layer-type)The numbers of columns layer-type draws from, as a set drawn from 1
and 2 -- see register!. layer-type is a registered keyword or a
layer-type map. A layer whose type is still to be inferred (:infer)
can draw either, since inference chooses from the columns it is
given; an unregistered keyword draws two, as an entry with no
declaration does.
The numbers of columns `layer-type` draws from, as a set drawn from 1 and 2 -- see `register!`. `layer-type` is a registered keyword or a layer-type map. A layer whose type is still to be inferred (`:infer`) can draw either, since inference chooses from the columns it is given; an unregistered keyword draws two, as an entry with no declaration does.
What an aesthetic is taken to be drawn as where the mark declares nothing. Reached only for a mark that draws the aesthetic without saying so -- which the plan warns about -- and set to what the built-in marks do.
Its keys are also the aesthetics a mark may declare it varies: these
are the two the plan and the scale ask about, so a :varies naming
any other aesthetic would be read by nothing.
What an aesthetic is taken to be drawn as where the mark declares nothing. Reached only for a mark that draws the aesthetic without saying so -- which the plan warns about -- and set to what the built-in marks do. Its keys are also the aesthetics a mark may declare it varies: these are the two the plan and the scale ask about, so a `:varies` naming any other aesthetic would be read by nothing.
(ink-exponent mark aesthetic)How the ink a mark covers grows with the quantity it draws
aesthetic 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 `aesthetic` as. What lets a scale's `:by` mean one thing across marks that draw different shapes.
Documentation for the keys of a layer's mapping -- aesthetics and layer settings alike. Maps key to description string.
Documentation for the keys of a layer's mapping -- aesthetics and layer settings alike. Maps key to description string.
Deprecated: the earlier name of layer-mapping-docs, the same map.
It will be removed in the next release.
Deprecated: the earlier name of `layer-mapping-docs`, the same map. It will be removed in the next release.
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 aesthetic)The quantity mark draws aesthetic 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 `aesthetic` 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 aesthetic)Every mark that varies aesthetic from row to row, as a set. What
the plan's messages name when a column is mapped to an aesthetic no
mark on the plot draws.
Every mark that varies `aesthetic` from row to row, as a set. What the plan's messages name when a column is mapped to an aesthetic no mark on the plot draws.
The quantities a mark can draw an appearance aesthetic as, and what
each one implies. A mark names one of these per aesthetic 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 aesthetic. 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 an aesthetic 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 aesthetic as, and what
each one implies. A mark names one of these per aesthetic 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 aesthetic. 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 an aesthetic 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 settings 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.
:column-counts is the set of numbers of columns the layer type draws
from: #{1} for an x column alone (a histogram), #{2} for an x and a
y column (a scatter), #{1 2} for either (a bar counts one column and
takes a second as its heights). Undeclared, it is #{1} where the
entry says :x-only true -- the older spelling of #{1} -- and #{2}
otherwise. It decides which cells of a split a layer written above
them is drawn in, and whether a pose naming only :y draws the layer
on its side. Read it back with column-counts.
:varies is an optional map from appearance aesthetic to the quantity
the mark draws it as, from quantities -- :point declares
{:size :radius :alpha :opacity}. An aesthetic 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 an aesthetic 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 settings 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.
:column-counts is the set of numbers of columns the layer type draws
from: `#{1}` for an x column alone (a histogram), `#{2}` for an x and a
y column (a scatter), `#{1 2}` for either (a bar counts one column and
takes a second as its heights). Undeclared, it is `#{1}` where the
entry says `:x-only true` -- the older spelling of `#{1}` -- and `#{2}`
otherwise. It decides which cells of a split a layer written above
them is drawn in, and whether a pose naming only `:y` draws the layer
on its side. Read it back with `column-counts`.
:varies is an optional map from appearance aesthetic to the quantity
the mark draws it as, from `quantities` -- `:point` declares
`{:size :radius :alpha :opacity}`. An aesthetic 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 an aesthetic 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.
Deprecated: the earlier name of universal-mapping-keys, the same
vector. It will be removed in the next release.
Deprecated: the earlier name of `universal-mapping-keys`, the same vector. It will be removed in the next release.
Keys the mapping of every layer type accepts. :x and :y are included
because a layer may name its own columns. :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.
:tooltip is the aesthetic a mark reads its hover text from -- a
column of values, or one value every mark of the layer shows. A
value is a string, shown as it stands, or a hiccup vector, drawn as
markup. The
:point and :interval-h marks read it; a tooltip written on any
other layer type is reported and draws none. Not to be confused with
the plot option of the same name, which is the switch that turns
hovering on.
Keys the mapping of every layer type accepts. :x and :y are included because a layer may name its own columns. :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. `:tooltip` is the aesthetic a mark reads its hover text from -- a column of values, or one value every mark of the layer shows. A value is a string, shown as it stands, or a hiccup vector, drawn as markup. The `:point` and `:interval-h` marks read it; a tooltip written on any other layer type is reported and draws none. Not to be confused with the plot option of the same name, which is the switch that turns hovering on.
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 |