ROSALI-SIM/Modules/ado/plus/v/violin.hlp

.-
help for ^violin^                                               (STB-46: gr33)
.-

Violin plots
------------

    ^violin^ varlist [weight] [^if^ exp] [^in^ range]
        [^,^ {^bi^weight|^cos^ine|^ep^an|^gau^ss|^par^zen|^rec^tangle|^tri^angle}
         ^n(^#^) w^idth^(^#^) by(^byvar^) tru^ncat^(^#,#|*^) ro^und^(^#^)^ 
         graph_options ]

^fweights^ and ^aweights^ are allowed; see ^help^ @weights@.


Description
-----------

^violin^ produces violin plots, a graphical box plot--kernel density synergism.
The violin plot combines the basic summary statistics of a box plot with the 
visual information provided by a local density estimator. The goal is to 
reveal the distributional structure in a variable.  Much like a traditional 
box plot, the violin plot displays the median as a short horizontal line, the 
first-to-third interquartile range as a narrow shaded box, and the lower-to-
upper adjacent value range as a vertical line, but it does not plot outside 
values.  Instead, it "boxes" the data with mirrored density curves and labels 
the y-axis at the minimum, median and maximum observed data values.

^violin^ also lists basic descriptive statistics about the data (i.e., the 
lower and upper adjacent values, the 25th and 75th centiles, the minimum, 
median and maximum of the data, and the sample size) and it provides 
information about the density estimation (i.e., the kernel method used, the 
number of points of estimation, and the resulting scale and width factors).  
When ^by()^ is specified, descriptive statistics are displayed for the combined
group only.  When multiple variables are included in varlist, statistics are 
displayed for the last variable only.  

^violin^ discards observations on an casewise basis as a function of 1) missing
data and 2) the ^if^ (or ^in^) specification (i.e, it ignores the entire 
observation).  This behavior may lead to unexpected results when multiple 
variables are in the varlist.
  
Note: ^violin^ calls ^centile^ to compute the needed centiles but ^centile^ does
      not respond to a ^[weight]^ specification.  This conflicts with the 
      ^kdensity^ code which responds to that specification.  The implications of
      this conflict have not been explored, but ^violin^ currently allows the the
      ^[weight]^ specification to be passed through to ^kdensity^.

Note: ^violin^ uses a low-level ^gph^ command which is not supported in Stata's 
      release 2 ^.gph^ format.  As a result neither ^Stage^ nor the ^gphdot^ or 
      ^gphpen^ DOS-based graphics output programs can process a saved violin-plot
      graphics file.  This limitation does not affect screen display or output
      using the ^Print Graph^ option of Stata's ^File^ menu. 


Options
-------

^biweight^, ^cosine^, ..., ^triangle^ specify the kernel.  By default, ^epan^, the
    Epanechnikov kernel, is used.

^n(^#^)^ specifies the number of points at which density estimates will be
    evaluated.  The default is 50.

^width(^#^)^ specifies the halfwidth of the kernel, the width of the density
    window around each point.  If ^width()^ is not specified, then the "optimal"
    width is used; see ^[R] kdensity^.  For multimodal and highly skewed 
    densities, the "optimal" width is usually too wide and oversmooths the
    density.

^by(^byvar^)^ produces separate plots for the groups of observations defined by 
    byvar and displays them in a single graph having common vertical scale. 
    ^by()^ cannot be specified when there is more than one variable in the 
    varlist.

^truncat(^#^,^#|^*)^ limits the range of the density trace, either to a range 
    specified as ^(^#^,^#^)^, or to the observed data limits, specified as ^(*)^.
    Regardless of the actual ^(^#^,^#^)^ specification, the maximum range truncation
    honored is the observed data limits.  The precise truncation points will 
    be the most extreme points within the specified range where the density is
    calculated (the points of density calculation depend on ^n()^, ^width()^ 
    and the observed data).

^round(^#^)^ rounds the y-axis numeric labels to the value specified.  As a result,
    the labels and their corresponding tic marks may not be placed at the true
    minimum, median, or maximum values, rather they will be at the rounded
    values.  ^round()^ has no effect if ^ylabel^ is specified without arguments, 
    but is operative if ^ylabel^ is not specified or is specified with arguments.
    The ^round()^ option follows the rules of Stata's ^round(^x^,^y^)^ function, with 
    # being the y argument and each label value being the x argument; 
    see ^[U] 20.3.5 Special functions^.  

graph_options are any of the options allowed by ^graph, twoway^ except ^b2title()^
    (which is ignored); see ^help^ @graph@.  Some options are preset and, although
    changeable, usually should not be modified.  These include ^symbol(i)^ and 
    ^connect(l)^ for specifying the plotting symbol and point connection method
    for the density curve.  In addition, ^ylabel()^ is preset to label only the
    minimum, median and maximum points.  ^t1title(Violin Plot)^ is preset but can
    be changed--except when ^by()^ is specified; in this instance ^t1title^ is used
    for the variable name or label.  When changeable, use of ^t1title(.)^ will
    result in a blank title.  Other preset options, such as ^pen(2)^ for the
    plot pen color, are intended to be freely changed to suit user preference.
    A few options, such as the left and right titles, are set (or default to) 
    blank.  If specified, they appear beside each plot in a multi-variable
    graph.  Lastly, the ^saving()^ option differs slightly from ^graph^'s in
    that the filename extension is always ^.gph^ and must not be specified.


Saved values
------------

    S_1   name of kernel used for density trace
    S_2   number of points of density estimation
    S_3   band width for density estimation
    S_4   scale factor of density plot
    S_5   minimum
    S_6   lower adjacent value
    S_7   first quartile
    S_8   median
    S_9   third quartile
    S_10  upper adjacent value
    S_11  maximum
    S_12  n

When ^by()^ is specified: S_3 and S_4 contain the averages of the band width and
scale factors used in the subgroup density estimations; S_5, S_7, S_8, S_9, 
S_11 and S_12 are statistics for the combined group; and S_6 and S_10 are set 
missing.

When multiple variables are specified, the saved values contain results for
the last variable in the varlist.
  

Examples
--------

	. ^violin length, t1(Auto data) l1(length of car)^

	. ^violin length weight, n(100) w(20)^

	. ^violin weight, by(foreign) parzen^


Author
------

      Thomas J. Steichen
      RJRT
      steicht@@rjrt.com


Reference
---------

Hintze, J. L. and R. D. Nelson (1998).  "Violin plots: a box plot-density trace
     synergism."  The American Statistician, 52(2):181-4.


Also see
--------

    STB:  gr33 (STB-46)
 Manual:  ^[R] kdensity^, ^[R] graph box^, ^[R] centile^ 
          ^[U] 20.3.5 Special functions^
On-line:  help for @kdensity@, @graph@, @centile@, @functions@