density

A Gaussian kernel density estimate of a sample, drawn as one curve.

densityNode
Only withxyplane
A purple density curve over ten readings, with two humps.A purple density curve over ten readings, with two humps.

density(x: #sample.height) draws a Gaussian kernel density estimate of the readings: one curve, spread along the axis the readings are written on and rising up the other. y: turns the picture a quarter turn. Two coordinates are refused (canvas/density-form), and the mark is on the xy plane only.

The curve's heights are densities, in reciprocal units of the readings. The whole estimate has area 1, but it is drawn only from the smallest reading to the largest and cut square at each end, so the drawn area is a little under 1. A histogram's bars are counts, so the two do not share a y scale.

bandwidth is the standard deviation of the kernel, in the readings' units. Left out, it is Silverman's rule, 0.9 × min(s, IQR ÷ 1.34) × n^(−1/5), with s the sample standard deviation and the IQR from Tukey's hinges. A written bandwidth must be positive (canvas/density-bandwidth); a parameter driven to zero draws nothing. The curve publishes mode, the reading it peaks at, peak, its height there, and current-bandwidth, the width actually used — the only way to state what Silverman's rule chose.

scene{
    Smoothed by {{round(#kde.current-bandwidth, 2)}}, the incomes peak at {{round(#kde.mode, 1)}}.
}[
    graph{
        slider:h(name: bandwidth; range: [0.5, 8]; default: 2)
        density#kde(x: #income.k; bandwidth: h)
    }(
        x axis label: income (£k)
    )
]

#Attributes

xImplicitAnimatable
The readings — numbers written out, or a dataset column bound whole. The sample itself, not a curve worked out by hand; writing them on x spreads the density along x, with the estimate rising up y.
series
Can be written as shorthand: density:value
yAnimatable
The readings when the sample is measured up the y axis — the same picture, turned a quarter turn, with the estimate running out along x. Not with x:.
series
bandwidthAnimatable
The standard deviation of the Gaussian kernel each reading is smoothed by, in the readings' units. Left out, Silverman's rule: 0.9 × min(s, IQR ÷ 1.34) × n^(−1/5), with s the sample standard deviation. A written number must be positive (canvas/density-bandwidth); a parameter driven to zero draws nothing.
parametised-number
colour
Colour.
colour-along
Also written: color
Defaultpurple
width
Stroke width, as a curve's is.
width-along
Default2
stroke-style
How the curve is drawn: solid, dashed or dotted. A function of the point it is at, so it may change along the curve.
stroke-along
Defaultsolid
fill-style
How the wash under the curve is filled: solid, hatched, dotted, or outlined, the curve alone. It may change along the curve, so a wash can cover only the tail past a critical value.
fill-along
Defaultoutlined
opacityAnimatable
Opacity.
number
Default1
label
Text drawn beside the element — rich text, so $maths$ and inline formatting render. Placed at the curve's peak, which is where a family of densities is told apart.
rich-text
hiddenAnimatable
Declared but not drawn. Animatable — hidden: true !cue.to{false}(at: 2) reveals it — and unlike a cue, a hidden element still frames the plot, so nothing moves when it appears.
boolean
Defaultfalse
lock
Keeps the reader from editing this element on an editable: graph. Nothing at all on a graph that is not editable.
boolean
Also written: locked
Defaultfalse
text-sizeAnimatable
Text size.
number
Default20
layerAnimatable
Paint order among the marks: a higher layer is drawn later, on top; equal or omitted, the marks stack in document order (later on top).
parametised-number
group
The groups this density belongs to, comma-separated: group: Treated, Projected. It is drawn in the colour of the first group that has one, over its own colour:, and the footer's key names every group. A stroke the graph's key: gives a group does not change it.
string

#Derived attributes

Computed while the element renders — read one with #id.name in attribute position or {{#id.name}} in prose, never set.

countDerived
The number of readings the curve is estimated from; a dash where no coordinate is written.
meanDerived
The mean of the readings, in the axis's units, known even where the curve has no spread to draw; a dash with no readings.
sdDerived
The sample standard deviation (divided by n − 1) of the readings, in the axis's units; a dash with fewer than two readings.
modeDerived
The reading the curve peaks at — the sample's mode as the estimate sees it, which moves with the bandwidth.
peakDerived
The density at that reading — how tall the curve is at its highest.
current-bandwidthDerived
The width actually smoothed by: the one written, or the one Silverman's rule chose — which is the number nobody knows without being told it. Named apart from the bandwidth attribute, which says what was asked for rather than what was used.

#Allowed in

graph { }cue { }cue.draw { }cue.trace { }cue.highlight { }cue.spotlight { }

#Examples

A density curve over 38 heights.A density curve over 38 heights.
graph{
    density(x: #sample.height)
}
A purple density curve over the same heights, with a bandwidth slider beneath the plot.A purple density curve over the same heights, with a bandwidth slider beneath the plot.
graph{
    slider:h(name: bandwidth; range: [0.2, 4]; default: 1)
    density(x: #sample.height; bandwidth: h; colour: purple)
}
Two density curves over the same incomes: a narrow bandwidth showing two humps, and a wide teal one smoothing them into one.Two density curves over the same incomes: a narrow bandwidth showing two humps, and a wide teal one smoothing them into one.
graph{
    density(x: #avp.income; bandwidth: 0.5; label: narrow)
    density(x: #avp.income; bandwidth: 2; label: wide; colour: teal)
}

Last updated