violinplot

Stata module to draw violin plots

violinplot draws so called violin plots that illustrate the distributions of the specified variables. A violin plot is an overlay of a (reflected) density estimate and a box plot.

violinplot Stata 15 or newer as well as the following packages from SSC: dstat, moremata, palettes, colrspace

---

Installation from GitHub:

. net from https://raw.githubusercontent.com/benjann/violinplot/main/
. net install violinplot, replace

Installation from SSC:

. ssc install violinplot, replace

Install dependencies from SSC:

. ssc install dstat, replace
. ssc install moremata, replace
. ssc install palettes, replace
. ssc install colrspace, replace

---

Some examples (use of the grstyle package is made; type ssc install grstyle to install the package):

clear all
sysuse nlsw88
grstyle init
grstyle set imesh
grstyle set color sb muted
violinplot wage ttl_exp tenure, pdf(ll(0))

violinplot wage ttl_exp tenure, pdf(ll(0)) fill

violinplot wage ttl_exp tenure, pdf(ll(0)) fill vertical

violinplot (ttl_exp) (tenure), pdf(ll(0)) fill over(race)

violinplot wage, pdf(ll(0)) noline fill(line) over(union) overlay

violinplot wage ttl_exp tenure, pdf(ll(0)) split(union) key(fill) ///
    labels("" "Work Experience" "Tenure")

violinplot wage, pdf(ll(0)) over(industry) colors(plasma) fill nomedian nobox nowhiskers

violinplot wage, pdf(ll(0)) over(industry) colors(plasma) fill nobox nowhiskers ///
    left pad(0) median(type(line)) dscale(4) bind

violinplot wage, pdf(ll(0)) over(industry, sort) colors(plasma) box(type(fill)) nowhiskers

violinplot wage, left dscale(.) rag(offset(-.005) mlcolor(%20))

violinplot wage, over(union) overlay left dscale(.) nomedian ///
    rag(offset(-.005 -0.01) mlcolor(%40))

violinplot wage, over(union) vertical fill absolute ///
    rag(spread(10) msymbol(o) mcolor(%20) mlc(%0) pstyle(p2))

sysuse auto, clear
violinplot mpg turn, left rag(stack right msymbol(o) offset(-.05))

violinplot mpg turn, rag(unique msize(*4) msymbol(o) mlcolor(white)) ///
    nobox nowhiskers nomedian

violinplot mpg turn, over(foreign) swap nostack nodensity outsides

---

Main changes:

12jun2025 (1.2.7)
- split(), over(), by(): display format now taken into account when generating
  labels (if numeric)
- split(), over(), by(): non-integer values could lead to empty subpopulations;
  this is fixed
- multiple sets of limits can now be specified in range()

13may2025 (1.2.6)
- vertical now default if nodensity is specified

13may2025 (1.2.5)
- option -nodensity- added
- option -outsides()- added
- option -pad()- added; outer padding of 0.5 is now applied by default 
- option -range()- now allows limiting the range of the density estimation
  by the box, whiskers, or custom statistics
- suboption -line- added in fill()
- type(bar) in box() renamed to type(spike); type(bar) now plots the bars using
  -rbar- and is now the default if nodensity is specified
- type(bar) added in median() and mean()
- cap() added in whiskers()
- rag(outsides) and rag(boutsides) returned error; this is fixed
- definition of legend option is now returned in r(legend)
- some changes have been made to how default rendering options are determined

29apr2025 (1.2.4)
- summary statistics of the violins are now stored in r(table)
- option -table- displays the summary statistics in the results window

25apr2025 (1.2.3)
- density estimation is now skipped if display of density curves is suppressed
  (i.e. if both -noline- and -nofill- are specified) and none of the other
  elements makes use of the density estimates

23apr2025 (1.2.2)
- suboption -statistics()- now available in -whiskers()-

07apr2025 (1.2.1)
- option -bind- added
- option noclean is now applied in internal call to dstat if the list of
  statistics contains duplicates, e.g. because -median(statistic(mean))- has
  been specified; this requires dstat version 1.4.5 (04apr2025) or higher

30mar2025 (1.2.0)
- suboption limits() added to option box()

15feb2024 (1.1.9)
- markers of rag will now always be printed in the order of the weights (so that
 (so that large dots will be at the back; if there are weights)

15feb2024 (1.1.8)
- rag(stack) now uses the same default step size for symmetric and asymmetric
  stacks
- rag(stack) and rag(spread) now print large dots in the back (this is relevant,
  e.g., if weights have been specified)
- rag(spread) now takes account of relative weights when generating the spread
  (so that large dots tend to be placed more in the center)

14feb2024 (1.1.7)
- revised the computation of weighted markers in the rag; the sizes are now
  determined in a way such that average weight typically corresponds to the
  default (unweighted) marker size
- reorganized some code and fixed some minor issues

13feb2024 (1.1.6)
- markers in rag() will now be scaled by the weights if weights have been
  specified; likewise, if suboption -unique- is specified, the markers of the
  rag will be scaled by the number of collapsed observations (or sum of
  weights); across results, the scaling of markers will be determined in a
  way such that it is consistent with the scaling applied to the density
  estimates; specify rag(noweight) to omit the scaling of markers

12feb2024 (1.1.5)
- rag() now has suboption stack() that can be used to produce raindrop plots

10feb2024 (1.1.3)
- second argument in rag(spread()) now allowed to use a fixed value for the
  width of the spread (i.e. do not scale the distribution in proportion to the
  density estimate)
- noline and nofill are now both allowed; noline and fill(select()) are now both
  allowed
- key(fill) now also allowed with fill(select()); default key now rearmost
  element if noline is specified

22mar2023 (1.1.2)
- violinplot did not work in Stata 15; this is fixed

02dec2022 (1.1.1)
- suboption unique added to rag()

29nov2022 (1.1.0)
- numlist now allowed in offset(), doffset(), and rag(offset()); numbers
  will be recycled across physical plots

28nov2022 (1.0.9)
- options rag(), ragcolors(), and p#rag() added
- options left and right added
- options offset() and doffset() added; split(, offset())) no longer documented
  (but still supported for backward compatibility)
- option dscale(.) now retains the original scaling of the PDFs (and replaces
  the categprical axis by a continuous axis if there is only one violin or only
  one overlay of violins)
- shorter abbreviations are now allowed for various options
- internal change in how positions of the violins are determines; counting now
  starts at zero; now using negative counting in case of -horizontal- (rather
  then using a revered axis)

25nov2022 (1.0.8)
- option slabels() did not work as expected; this is fixed
- options color(), lcolor(), fcolor() etc. did not allow color specifications
  enclosed in double quotes; this is fixed

20nov2022 (version 1.0.7)
- options split() and slabels() added
- option absolute added
- can now also specify ltight or rtight; [l|r]tight is now passed through to
  dstat; this requires the newest updates of dstat and moremata

07nov2022 (version 1.0.6)
- suboptions sort(), descending, and tlast added in over()
- suboptions type() and stat() added in box(), median(), and mean()
- option order() added
- p#el() options added; behavior of p#() improved
- option n() added
- addplot() did not work well if by() has been specified; this is fixed
- now using labsize(medium) for main axis labels if there are two levels
  of axis labels

01nov2022 (version 1.0.5)
- option by() added
- options over(), olabels(), swap, gap(), atover, asover, nostack added
- change in suboptions of dscale()
- option nolabel added
- option addplot() added
- option cw added
- support for p#() options added
- now returning error if there are no valid observations
- density estimation now skipped if x is constant
- now using exact density estimation if range() restricts the evaluation
  range to less than half the default evaluation range
- ticks and grid lines on categorical axis now deactivated (unless atover is
  specified)

25oct2022 (version 1.0.4)
- weights were not taken into account; this is fixed
- option key() added
- option qdef() added
- option tight added

24oct2022 (version 1.0.3)
- the definition used to compute the whiskers was not correct; this is fixed

22oct2022 (version 1.0.2)
- changed default rendering of box and median (such that box is less thick)

22oct2022 (version 1.0.1)
- documentation added
- overlay option added
- option pstyles() added
- option horizontal added
- dscale(,subgraph) renamed to dscale(,group)
- various additional refinements and bug fixes

20oct2022 (version 1.0.0)
- released on GitHub