violin

A Gaussian kernel density estimate of a sample, mirrored about the line it stands on.

violinNode
Only withxxyargandplane
Three violins, one each for control, treated and placebo, every one a smooth bell with its own centre and spread.Three violins, one each for control, treated and placebo, every one a smooth bell with its own centre and spread.

A violin draws a Gaussian kernel density estimate of the readings, mirrored about the line it stands on: wide where readings crowd and narrow where they thin, cut off square at the smallest and largest reading. It is the estimate a density draws as one curve.

It stands as a boxplot does — a lane on the number line, one coordinate and on: on a plane, or both coordinates with one axis ruled in names for a violin at every name — and is refused with both axes numeric, which leaves no line to stand on. A violin, a box and a scatter of the same readings at one place share one slot, so a narrow box sits inside its violin:

graph{
    violin(x: #penguins.flipper; y: #penguins.species; colour: purple)
    boxplot(x: #penguins.flipper; y: #penguins.species; band: 0.15; colour: teal)
}(
    x axis label: flipper length (mm)
)

Every violin is band of its slot wide at its own peak, so the shapes compare and the sample sizes do not. bandwidth is the standard deviation of the kernel, in the readings' units; left out, each sample takes Silverman's rule, as a density does. A written bandwidth must be positive (canvas/violin-bandwidth); a parameter driven to zero draws nothing.

#Attributes

On any plane
bandwidthAnimatable
The standard deviation of the Gaussian kernel each reading is smoothed by, in the readings' units. Left out, each sample takes Silverman's rule, 0.9 × min(s, IQR ÷ 1.34) × n^(−1/5). A written number must be positive (canvas/violin-bandwidth); a parameter driven to zero draws nothing.
parametised-number
colour
The violins' colour: one colour, or a list violin by violin in the order they stand — colour: grey, teal. Grouped by a column of names, it can also be applied to that column, so each violin takes its own name's colour whatever order the violins stand in: colour: #polls.party -> (DEM: blue; REP: red; otherwise: grey).
colour-style
Also written: color
Defaultpurple
style
How each violin is filled: solid, hatched, dotted or outlined. One style, or a list violin by violin.
fill-style-style
Defaultsolid
bandAnimatable
The share of its slot a violin is wide at its peak — the same room a boxplot's and a scatter's band: are shares of, so a narrow box sits inside a wide violin by giving each its own share.
parametised-number
Default0.8
opacityAnimatable
Opacity.
number
Default1
label
Text drawn beside the element — rich text, so $maths$ and inline formatting render. Fades and draws with the element.
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 and holds its slot, 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 violin 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
Only withxplane
xImplicitAnimatable
The readings — numbers written out, or a dataset column bound whole. The sample itself, not a density worked out by hand. One coordinate is one sample; x: and y: together, with one axis ruled in names, are a sample grouped by those names, a violin at each.
series
Can be written as shorthand: violin:value
Only withxyplane
xImplicitAnimatable
The readings — numbers written out, or a dataset column bound whole. The sample itself, not a density worked out by hand. One coordinate is one sample; x: and y: together, with one axis ruled in names, are a sample grouped by those names, a violin at each.
series
Can be written as shorthand: violin:value
yAnimatable
The readings when the sample is measured up the y axis, or the names column of a grouped violin whose readings are on x.
series
onAnimatable
Where a one-sample violin stands on the other axis — a number, a name, or a date, as a boxplot's on:. Required on a plane for a violin written with one coordinate; refused on the number line, whose violins take lanes, and on a grouped violin, whose names column already says where.
axis-value
Only withargandplane
reAnimatable
The readings on the real axis, on the argand plane.
series
imAnimatable
The readings on the imaginary axis, on the argand plane.
series
onAnimatable
Where a one-sample violin stands on the other axis — a number, a name, or a date, as a boxplot's on:. Required on a plane for a violin written with one coordinate; refused on the number line, whose violins take lanes, and on a grouped violin, whose names column already says where.
axis-value

#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 violin is drawn from, every name's together when it stands at several.
meanDerived
The mean of the readings, not of the curve, in the axis's units; a dash for a violin standing at several names or with no readings.
medianDerived
The middle of the ordered readings, in the axis's units; a dash for a violin standing at several names or with no readings.
sdDerived
The sample standard deviation (divided by n − 1) of the readings, in the axis's units; a dash for a violin standing at several names or with fewer than two readings.

#Allowed in

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

#Examples

One violin over ten readings, widest at its two humps.One violin over ten readings, widest at its two humps.
graph:x{
    violin(x: 2, 3, 3, 4, 4, 5, 7, 8, 8, 9)
}
Three violins of flipper length, one for each penguin species, Gentoo’s highest.Three violins of flipper length, one for each penguin species, Gentoo’s highest.
graph{
    violin(x: #penguins.flipper; y: #penguins.species)
}
A narrow-bandwidth violin of a trial’s control arm, standing at control on the x axis.A narrow-bandwidth violin of a trial’s control arm, standing at control on the x axis.
graph{
    violin(y: #trial.mass; on: control; bandwidth: 0.4)
}

Last updated