help joyplot/ridgelinejoyplot/ridgeline v1.71 (GitHub)

joyplot/ridgeline

: A Stata package for joyplots or ridgeline plots.

Please note that joyplot can be substituted with ridgeline.

The command is based on the following guide on Medium: Ridgeline plots (Joy plots).

Syntax

joyplot y [x] [if] [in], by(variable)
[ overlap(num) bwidth(num) palette(str) alpha(num) offset(num) lines droplow normalize(local|global)
rescale offset(num) laboffset(num) lwidth(num) lcolor(str) ylabsize(num) ylabcolor(str) ylabposition(str)
yline ylcolor(str) ylwidth(str) ylpattern(str) xreverse yreverse peaks peaksize(num) n(num)
xtitle(str) ytitle(str) title(str) subtitle(str) xlabel(str)note(str) scheme(str) name(str) saving(str)
]

joyplot y [x] The command requires a numeric y variable and an optional numeric x variable. If x is not specified, then overlapping densities for y are drawn.
If x is specified, a lowess fit between y and x is performed. Usually x represents a time variable.

by(variable) This is the group variable that defines the joyplot layers. If there are fewer than 10 observations per over group, the program will
throw a warning message and exit. This is important to flag since densities are likely to create errors with few observations.
Either clean these groups manually or use the droplow option to automatically drop them.

droplow Automatically drop the over groups with fewer than 10 observations.

bwidth(num) A higher bandwidth value will result in higher smoothing. The default value is bwid(0.1).
This value might need adjustment depending on the data. Note that if you use joyplot and the ridge lines do not appear, then the bandwidth certainly needs adjustment.
In this case, increase the bandwidth.

overlap(num) A higher value increases the overlap, and the height of the joyplots. The default value is overlap(6) and the minimum allowed value is 1.

palette(str) palette uses any named scheme defined in the colorpalette package.
Default is CET C1. Here, one can also pass single colors, for example, palette(black).

alpha(num) Alpha is used to change the transparency of the area fills. Default value is alpha(80) for 80% transparency.

lines Draw colored lines instead of area fills. This option is much faster since area fills are computationally intensive.
The option lcolor() does not work here. Instead define the line colors using the palette() option. The option lwidth() is allowed.

normalize(local|global) Normalize by the local or global maximum of the y variable. The default is set to global, but in certain circumstances,
the user might want to just look at the distribution of a variable within a group. In this case the option norm(local) can be specified.

rescale This option is used to rescale the data such that the global minimum value is set to 0. This is helpful in two instances.
First, the data contains high values that create a large gap from the horizontal zero axis. This might make it look like that the labels are displaced.
In this case, rescale can be used to recenter the horizontal lines to the global minimum value. The minimum and maximum values are stored in locals.
See return list. Second, use this option if the data contains negative values. Since densities do not deal with negative numbers,
rescale helps recentering the data allowing the users to plot the all the values.

xreverse, yreverse Reverse the x and y axes. While reversing the y-axis might be desireable, for example, to change the alphabetical
order of the categories, xreverse should be used with caution.

peaks Mark the highest point of each ridgeline with a dot. This option is currently beta.

peaksize(num) Size of peak dots. Default is peaksize(0.2).

Fine tuning

lcolor(str) The outline color of the area fills. Default is lc(white).

lwidth(num) The outline width of the area fills. Default is lw(0.15).

yline Shows base reference lines for each by() category.

xline(numlist) Passthru option for xline(). This option can be used to add vertical lines to graphs.

ylcolor(str) The color of the y-axis grids lines. Default is ylc(black).

ylwidth(num) The width of the y-axis grids lines. Default is ylw(0.04).

ylpattern(str) The pattern of the y-axis grids lines. Default is ylp(solid).

ylabposition(str) The position of the y-axis labels takes on the values left or right.
The default orientation is ylabpos(left).

laboffset(num) This option is used for offseting the labels on the y-axis.
For example, offset(-20) will move the labels left by 20 pixels. Default is laboffset(0) for no displacement.

offset(num) This option is used for extending the range of the x-axis. Default is offset(0) or 0% of the total width.

n(num) Advanced option for increasing the number of observations for generating single density joyplots. Default is n(50).

xtitle(), ytitle(), xlabel() These are standard twoway graph options.

title(), subtitle(), note() These are standard twoway graph options.

xsize(), ysize(), name(), saving() These are standard twoway graph options for changing the dimensions of the graphs.

scheme() Load the custom scheme. Above options can be used to fine tune individual elements.

Dependencies

The palette package (Jann 2018, 2022) is required for joyplot:

ssc install palettes, replace
ssc install colrspace, replace

Even if you have these installed, it is highly recommended to update the dependencies:
ado update, update

Examples

See GitHub for examples.

Version history

- 1.71: Fixed a bug where locals were passing incorrectly. Fixed a bug in "lines". Added n() option for single density graphs.
- 1.7 : Options xline(), saving(), peaks, peaksize() added. The command ridgeline added as mirror for joyplot.
- 1.62: Changed over() to by(). Added offset() and laboffset().
- 1.61: ylabel in densities fixed. normalize in densities fixed.
- 1.6 : color renamed to palette. Global normalization is now default. Rescale option added. Less than 10 observations per group are flagged.
- 1.5 : Major code clean-up. Default values optimized. Redundant options removed.
- 1.42: Fix a bug in the y-axis
- 1.41: Fixed the dependency package installations. Joyplot can now take numeric over values.
- 1.4 : The options to reverse x and y axes added. Graph saving option added. Several bug fixes and optimizations.
- 1.3 : Density stacking added. y-axis grid lines added. Placement of labels optimized.
- 1.21: xsize and ysize options added. Labels on left-side options added.
- 1.2 : x-axis angle option added. Global normalization option added. Draw lines only option added.
- 1.1 : Code cleanup. Various options added.
- 1.0 : First version.

Package details

Version : joyplot v1.71
This release : 03 Oct 2023
First release: 13 Dec 2021
Repository : GitHub
Keywords : Stata, graph, joyplot, ridgeline plot
License : MIT

Author : Asjad Naqvi
E-mail : asjadnaqvi@gmail.com
Twitter : @AsjadNaqvi

Feedback and issues

Please submit bugs, errors, feature requests on GitHub by opening a new issue.

References

Jann, B. (2018). Color palettes for Stata graphics. The Stata Journal 18(4): 765-785.

Jann, B. (2022). Color palettes for Stata graphics: An update. University of Bern Social Sciences Working Papers No. 43.

Other visualization packages

arcplot, alluvial, bimap, bumparea, bumpline, circlebar, circlepack, clipgeo, delaunay, joyplot,
marimekko, sankey, schemepack, spider, streamplot, sunburst, treecluster, treemap