*! version 1.0 March 2022

Title

joy_plot -- Module create joy/violin plots across different groups.

Syntax

joy_plot varlist [if] [in] [aweight], [over(varname) by(varname)] [joy_plot_options color_options legend_options twoway_options]

options

varlist You need to specify a list of variable that will be used to create plots (kdensity, or line).

over(varname) Indicates a variable that defines the groups to be used for the joy_plot. If you omit this, you probably would prefer using kdensity directly. See descriptions for details.

by(varname) Indicates a variable that defines what groups to be plotted by. This creates multiple density plots for each level defined by over(). This variable can only take 2 values if using for violin plot. See descriptions for details.

joy_plot options

This options are used to modify some aspects specific to the looks of the joy_plot

radj(#) When used, the range used for the plots will be extended beyong the max or min values of the varname. Defeult is 0.

range(#1 #2) When used, it sets the range for the plot to be between #1 and #2. The default uses the sample min and max.

dadj(#) When used the height of the densities will be adjusted. This allows for plots to overlap each other. Default is 1 (no overlapping).

bwadj(#) Should be between 0 and 1. It is used to determine the bandwidth for each subplot. When bwadj=1 each plot uses the bandwidth determined by kdensity, which may vary by subgroup. When bwadj=0, all plots use a bandwidth equal to the simple average across all subgroups. Any number between 0 and 1 will use a weighted average between both options. For example, bwadj(0.5) will use a bandwith equal to the simple average between the subgroup kdensity specific bandwidth, and the overal mean bandwidth.

bwadj2(#) Any positive number. It is use to change the bandwith across all plots. One can, for example, modify all
bandwidths to be half (bwadj2=0.5) of the one originally estimated. Default is 1.

bwadj3(#) Any positive number. It is used to define the bandwidth for all plots exogenously. For example bwadj3(0.5) sets the bandwidth to 0.5
across all plots. This is the fastest option.

kernel(kfun) This can be used to select a particular type of kernel function for the plots. Default is Gaussian.

nobs(#) This is used to define how many points to be used for the plot. Larger number creates a smoother figure,
but uses more memory. Default is 200.

Other options

These options can be used to modify the look of the legend, or text describing the groups.

strict Unless specified, the value labels, or values of over(variable) will be used to label groups. Using "strict"
will not show any text, if a value label is undefined. See macro, and section on "label".

notext When used, no text will be added on the vertical axis.

textopt(opts) When producing joy_plots, one can use this option to change some aspects of the group indentifiers. See added_text_options or details.

right When used, it will put the text identifying groups on the right of the plot. The default is to add this text on the left.

offset(#) When used, It request to offset (move) the text # points to the right (+) or left (-).

gap0 When used, all joy_plots will be drawn starting at 0. This will be similar to producing various kdensity plots, but using areas. Cannot be combined with violin.

alegend When used, It will add a legend with all values defined in over(varname) or by(varname) to the graph. The default is not to show any legends. When over() and by() are specified, legends will be created based on the labels of variable in by(). This option can be combined with legend_options.

iqr[(numlist)] When specified, it will add lines to the graph indicating specified percentiles (numlist).
If numlist is not provided, it produces the 25th, 50th and 75th percentile.

iqrlwidth(numlist) Used to change the width of the lines marking the specified percentiles. Default is 0.3.

iqrlcolor(color) Used to change the color, or color properties of lines marking the specified percentiles. It may overwrite other color options.

violin When specified, it produces a violin type plot, rather than the kernel density plots. If by() is used, it produces half violin plots.

color options

color(colorlist) Can be used to specify colors for each group defined by over(varname), using
a list of colors. If you add fewer colors than groups in over(varname), subsequent groups will use last specified color.
For example if you type color(red blue), but over(var) has 3 groups, the last group will also be assigned the "blue" color.

colorpalette(*) An alternative approach to specify colors. This uses the command colorpalette
to define colors and use them for the scatter plot.

If neither option is used, colors are assigned based on the current scheme, which uses up to 15 different
colors.

Note: If one uses over() option only, each group will be ploted with different colors. However, if by() option is used
colors will be assigned based on by() not over().

Other color options

One can use other rarea specific options including fcolor, fintensity, lcolor,
lwidth, lpattern, lalign, lstyle. Be aware that the same option will be applied to each sub rarea defined by over(varname).

twoway options

It is also possible to use any of the twoway options, including labels, titles, name, notes, etc.

Description

This module aims to provide an easy way to create joy_plots and violin plots, over different groups. These are basically kernel density plots for a single variable
across multiple groups (either over() or by())

For example, say that one is interested in visualizing the wage distribution for men and women. What you would normally do would be

twoway kdensity wage if sex==1 || kdensity wage age if sex==2, legend(order(1 "Men" 2 "Women"))

Instead you could create a similar graph using the following syntax:

joy_plot wage , over(sex)

And if you would prefer a violin plot, you could use the following

joy_plot wage , over(sex) violin

This program should also facilitate using different colors to each sub group. For example, one can simply
provide the list of colors using color(colorlist). You coud also use the option
colorpalette() to select colors for each group defined by over(varname).

This can also be used to produce bi-dimensional plots using the options "over()" and "by()". over() will create plots at different levels,
whereas by() will produce various plots within each level. For example, one could plot
wage distribution across education levels, for men and women.

See examples for details

Examples

Lets start by loading some data:

. use http://fmwww.bc.edu/RePEc/bocode/o/oaxaca.dta

Say that you want to see the relationship between wages and experience, but differentiating
by marital status:

gen mstatus=single+2*married+3*divorced

joy_plot lnwage , over(mstatus)

But now you want to add a label to differentiate all groups, and show this as a legend:

label define mstatus 1 Single 2 Married 3 Divorced

label values mstatus mstatus

joy_plot lnwage, over(mstatus) alegend notext

But what if you want to try using colors other than the default. You have three options

Provide a list of colors manually

joy_plot lnwage , over(mstatus) alegend color(navy gold)

Or use colorpalette:

joy_plot lnwage , over(mstatus) alegend colorpalette(blues) notext

You could also use rarea options, and two way options

`"joy_plot lnwage , over(mstatus) color(gs10) iqr right title("Wages distribution") subtitle("by Marital Status") "'

You could also request producing a graph that ignores the lower tail of the distribution.

`"joy_plot lnwage , over(mstatus) iqr range(2 5) title("Wages distribution") subtitle("by Marital Status") "'

Now say that you want to compare wage distribution of men and women, over marital status.

`"joy_plot lnwage , over(mstatus) by(female) title("Wages distribution") subtitle("by Marital Status") "'

Or produce a violin plot from here as well:

`"joy_plot lnwage , over(mstatus) by(female) title("Wages distribution") subtitle("by Marital Status and Gender") violin"'

Finally, you can plot over gender, by marital Status. Although violin is no longer an option

`"joy_plot lnwage , by(mstatus) over(female) title("Wages distribution") subtitle("by Marital Status and Gender") "'

Aknowledgement

This command came up to existance because I do this kind of graphs often just to visualize multiple groups at the same time.
Since I was in a programming mood, I decided to write up a command for this.

Also, colorpalette is a very powerful command by Ben Jann. Without it, playing with colors would be far more difficult!

Finally, many thanks to Eric Melse, who suggested many new features for this command.

One last point. If you are interested on this or other of my visualization tools, check https://github.com/friosavila/stataviz, where I will try to
keep updated versions of these commands.

Author

Fernando Rios-Avila

Levy Economics Institute of Bard College

Blithewood-Bard College

Annandale-on-Hudson, NY

friosavi@levy.org

Also see

Help: colorpalette, scatter, kdensity, ridgeline_plot, waffle_plot