View source: R/adjusted_boxplot.R
| adjusted_boxplot | R Documentation |
This function generates the adjusted boxplot, which is a robust graphical method for visualizing skewed data distributions. It provides a more accurate representation of the data's spread and skewness compared to standard boxplot, especially in the presence of outliers.
adjusted_boxplot(
x,
plot = TRUE,
id = NULL,
group = NULL,
scales = c("free_y", "fixed"),
points = c("outliers", "all", "none"),
label_outliers = FALSE,
show_n = TRUE,
show_mean = FALSE,
annotate = NULL,
horizontal = FALSE,
log = FALSE,
fill = "grey85",
xlab = NULL,
ylab = NULL,
title = NULL,
caption = TRUE,
base_size = 11,
point_size = NULL,
point_alpha = 0.75,
x_labels_angle = 0,
box_width = 0.5,
notch = FALSE,
notch_width = 0.5,
staple_width = 0.5,
xlabels.angle = deprecated(),
xlabels.vjust = deprecated(),
xlabels.hjust = deprecated(),
box.width = deprecated(),
notchwidth = deprecated(),
staplewidth = deprecated()
)
The function is based on the medcouple (MC) measure computed on the data and which
robustly measures skewness. This measure is bounded between -1 and 1. The
medcouple is equal to zero when the observed distribution is symmetric,
whereas a positive (resp. negative) value of MC corresponds to a right
(resp. left) tailed distribution. The fences are, for \text{MC} \geq 0,
[Q_1 - 1.5 e^{-4\,\text{MC}}\,\text{IQR};\; Q_3 + 1.5 e^{3\,\text{MC}}\,\text{IQR}]
and, for \text{MC} < 0,
[Q_1 - 1.5 e^{-3\,\text{MC}}\,\text{IQR};\; Q_3 + 1.5 e^{4\,\text{MC}}\,\text{IQR}],
calibrated by Hubert and Vandervieren (2008) so that about 0.7% of the
observations of a clean, moderately skewed distribution are flagged, as
with Tukey's boxplot for normal data. The whiskers end at the most extreme
observations within the fences, and the observations outside are drawn as
points. The statistics are computed by robustbase::adjboxStats(), whose
quartiles are Tukey's hinges, as in boxplot(). The method suits
distributions that are not excessively skewed, i.e. with
|\text{MC}| \leq 0.6.
Layout. Each variable is drawn in its own panel, with its own value
axis (scales = "free_y"), so that variables of different scales or units
stay readable; scales = "fixed" draws them in one panel, on a common
axis. With group, the boxes of the groups are side by side in the panel
of each variable. Below each box, n is the number of non-missing values.
Points. By default, the outlying observations are drawn, slightly
spread sideways so that equal values do not hide each other.
points = "all" draws every observation, the outlying ones in black,
as some journals require; label_outliers = TRUE names the outlying
observations by id (else by row number), and the outliers table of
plot = FALSE gives them all.
Annotations. annotate adds, for each box:
"shape": the medcouple (MC, marked (> 0.6) beyond the range of
the method), or the g and h of the generalized boxplot, which
explain the asymmetry of the whiskers;
"outliers": the number of flagged values, with the number expected in
clean data (about 0.7% for the adjusted boxplot, which Hubert and
Vandervieren calibrated as Tukey's boxplot for normal data, and alpha
for the generalized one): many more flagged values than expected point
to real outliers;
"fences": the fences beyond which values are flagged, as dashed marks
(on the sides with outlying values), the whiskers ending at the last
values inside;
"median": the median with its distribution-free 95% confidence
interval, from the order statistics (Md); the notches are made to
compare two medians, and are not a confidence interval of one;
"spread": the interquartile range and the robust coefficient of
variation \text{rCV} = \text{IQR} / (1.349\,\text{median}), in
percent, read as a relative standard deviation;
"location": the biweight location (biweight_location()), a robust
mean, marked by a cross (the mean, with show_mean, is pulled by the
outlying values);
"test": with group, the p-value of the Kruskal-Wallis test between
the groups, below the variable name. With several variables, adjust the
p-values for multiple testing (see p.adjust() and the tests table);
"missing": the number of missing values, next to n.
annotate = "all" adds them all (the test only with group). The
caption gives their key. With several boxes in a panel, each statistic
takes two short lines: for many groups, make the figure wider or choose
fewer annotations. All the values are in the stats and tests tables
of plot = FALSE.
Publication figures. Give the units of the variables in their names
(such as "Ca (%)", with check.names = FALSE in data.frame()) or in
ylab. Make the plot at its printed size, with base_size set to the
text size of the journal (often 7 to 9 points), and save it with
ggplot2::ggsave(), for example
ggsave("figure.pdf", p, width = 85, height = 70, units = "mm") for a
single column. The caption says which boxplot is drawn, because readers
assume Tukey's whiskers (1.5 IQR) otherwise; use caption = FALSE and
state it in the figure legend instead, for example: "Adjusted boxplots
(Hubert and Vandervieren, 2008): the boxes show the quartiles and the
median, the whiskers extend to the most extreme values within the
medcouple-adjusted fences, and the points are the values outside."
If plot = TRUE, a ggplot2 object.
If plot = FALSE, a list of tibbles: stats, with one row per
variable (and group): the numbers of values n and of missing values
n_missing, the whisker ends lower and upper (the most extreme
values within the fences), the quartiles q1 and q3, the median,
the fences, the notch limits, the medcouple, the 95% confidence
interval of the median (median_lower, median_upper), the iqr,
the robust coefficient of variation rcv (%), the biweight
location, the mean, and the numbers of outlying values n_outliers
and of expected ones in clean data expected_outliers; outliers,
with the outlying values, their row in x, their id and their
tail out ("lower" or "upper"); and, with group, tests, the
Kruskal-Wallis test between the groups of each variable (statistic,
df, p_value).
Christian L. Goueguel
The adjusted boxplot is based on the methodology described in:
Brys, G., Hubert, M., Struyf, A., (2004). A Robust Measure of Skewness. Journal of Computational and Graphical Statistics, 13(4):996-1017
Hubert, M., Vandervieren, E., (2008). An adjusted boxplot for skewed distributions. Computational Statistics and Data Analysis, 52(12):5186-5201
McGill, R., Tukey, J. W., Larsen, W. A. (1978). Variations of box plots. The American Statistician, 32(1):12-16 (notches)
generalized_boxplot() for skewed and heavy-tailed distributions.
data(forageLIBS)
minerals <- forageLIBS[c("Measurement", "Ca", "Mg", "P", "K", "S")]
# mineral contents, each on its own axis and with its own fill color, the
# outlying samples named: a figure of a journal page width
p <- adjusted_boxplot(minerals, id = Measurement, label_outliers = TRUE,
fill = hcl.colors(5, "Pastel 1"), ylab = "Content (%)",
base_size = 8)
p
# saved at that size (here in the temporary directory)
ggplot2::ggsave(file.path(tempdir(), "minerals.pdf"), p, width = 175, height = 70,
units = "mm")
# the statistics and the outlying samples
res <- adjusted_boxplot(minerals, id = Measurement, plot = FALSE)
res$stats
res$outliers
# potassium and phosphorus by calcium level, with notches, means and a
# darker blue for a higher level: a figure of a journal column (85 x 75 mm)
minerals$Ca_level <- cut(minerals$Ca, quantile(minerals$Ca, 0:3 / 3),
labels = c("Low Ca", "Mid Ca", "High Ca"),
include.lowest = TRUE)
p <- adjusted_boxplot(minerals[c("K", "P", "Ca_level")], group = Ca_level,
notch = TRUE, show_mean = TRUE, ylab = "Content (%)",
fill = c("#deebf7", "#9ecae1", "#4292c6"),
title = "Potassium and phosphorus by calcium level",
base_size = 8)
p
# trace elements on a logarithmic axis, horizontal, with all the samples
# and one fill color for all the boxes
traces <- forageLIBS[c("Fe", "Mn", "Zn")]
adjusted_boxplot(traces, log = TRUE, horizontal = TRUE, points = "all",
fill = "#fdd49e", ylab = "Content (mg/kg)")
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.