help vioplot                                 Nicholas Winter and Austin Nichols
-------------------------------------------------------------------------------

Title

    vioplot -- Violin Plots


Syntax

        vioplot varlist [if] [in] [weight] [, options]

    options                           Description
    -------------------------------------------------------------------------
    Group options
      over(varname[, over_options])   categories; option may be repeated
                                        twice
         missing                      keep missing values as a category for
                                        this overvar
         total                        add total group (can only be specified
                                        in one over() option)
         nolabel                      do not use value labels to label
                                        category axis

      nofill                          omit empty categories
    


    Orientation
      vertical                        orient densities vertically (the
                                        default)
      horizontal                      orient densities horizontally

    Number of cases
      obs                             include number of observations per
                                        category
      obs(alt)                        move display of obs to the opposite
                                        axis; implies option obs

    kdensity options
      kernel(kernel)                  specify kernel function; default is
                                        kernel(epanechnikov)
      bwidth(#)                       half-width of kernel

    Scaling & labelling
      barwidth(#)                     width of bars as percentage of default
      dscale(#)                       width of densities as percentage of
                                        default

      ygap(#)                         gap between y variables as percentage
                                        of default
      ogap(#)                         gap between 2d level over categories as
                                        percentage of default
      noylabel                        use yvar names rather than labels for
                                        legending

    Graph appearance
      density(area_options)           options affecting the plotting of the
                                        densities
      bar(barlook_options)            options affecting the plotting of the
                                        bars
      line(line_options)              options affecting the plotting of the
                                        spikes
      median(marker_options)          options affecting the plotting of the
                                        medians
      obsopts(marker_label_options)   options affecting the plotting of
                                        observation counts

      twoway_options                  Options affecting the graph as a whole


Description

    vioplot displays a violin plot for one or more variables, optionally by
    categories formed by one or two other variables.  Violin plots are a
    modification of box plots that add plots of the estimated kernel density
    to the summary statistics displayed by box plots. They were first
    suggested by Hintze and Nelson (1998).

    Violin plots include a marker for the median of the data, a box
    indicating the interquartile range, and spikes extending to the upper-
    and lower-adjacent values, as in standard box plots.  Overlaid with this
    modified box plot is a density, estimated by kdensity.

    vioplot allows aweights, fweights, and pweights; see weight.


Reference

    Hintze, Jerry L., and Ray D. Nelson. 1998.  "Violin Plots: A Box
        Plot-Density Trace Synergism." The American Statistician
        52(2):181-84.


Examples

        sysuse auto, clear

        vioplot mpg, over(rep78)

        vioplot mpg, over(rep78) over(foreign)

        vioplot mpg, over(rep78, missing) over(foreign)

        vioplot mpg, over(rep78) over(foreign) nofill

        vioplot mpg, over(rep78) horizontal name(myplot) title("Violin Plot
            of Mileage") subtitle("By repair record") ytitle(Repair Record)
            ylab(, angle(horiz)) scheme(s2mono)

        vioplot gear head, over(foreign) scheme(s2color)

        vioplot gear head, over(rep78) legend( ring(0) pos(2) cols(1))
            xtitle("Categories of Repair Record") scheme(s2color)

        vioplot gear head, over(rep78, m) over(foreign, total)
            scheme(s2color)

Authors

    Nick Winter
    University of Virginia


    Austin Nichols
    Urban Institute
    Washington DC
    austinnichols@gmail.com