ggplot2 3.5.0
This is a minor release that turned out quite beefy. It is focused on
overhauling the guide system: the system responsible for displaying information
from scales in the guise of axes and legends. As part of that overhaul, new
guides have been implemented and existing guides have been refined. The look
and feel of guides has been mostly preserved, but their internals and
styling options have changed drastically.
Briefly summarising other highlights, we also welcome coord_radial()
as a
successor of coord_polar()
. Initial support for newer graphical features,
such as pattern fills has been added. The API has changed how I()
/<AsIs>
vectors interact with the scale system, namely: not at all.
Breaking changes
-
The guide system. As a whole. See 'new features' for more information.
While the S3 guide generics are still in place, the S3 methods for
guide_train()
,guide_merge()
,guide_geom()
,guide_transform()
,
guide_gengrob()
have been superseded by the respective ggproto methods.
In practice, this will mean thatNextMethod()
or sub-classing ggplot2's
guides with the S3 system will no longer work. -
By default,
guide_legend()
now only draws a key glyph for a layer when
the value is in the layer's data. To revert to the old behaviour, you
can still setshow.legend = c({aesthetic} = TRUE)
(@teunbrand, #3648). -
In the
scale_{colour/fill}_gradient2()
and
scale_{colour/fill}_steps2()
functions, themidpoint
argument is
transformed by the scale transformation (#3198). -
The
legend.key
theme element is set to inherit from thepanel.background
theme element. The default themes no longer set thelegend.key
element.
This causes a visual change with the defaulttheme_gray()
(#5549). -
The
scale_name
argument incontinuous_scale()
,discrete_scale()
and
binned_scale()
is soft-deprecated. If you have implemented custom scales,
be advised to double-check that unnamed arguments ends up where they should
(@teunbrand, #1312). -
The
legend.text.align
andlegend.title.align
arguments intheme()
are
deprecated. Thehjust
setting of thelegend.text
andlegend.title
elements continues to fulfill the role of text alignment (@teunbrand, #5347). -
'lines' units in
geom_label()
, often used in thelabel.padding
argument,
are now are relative to the text size. This causes a visual change, but fixes
a misalignment issue between the textbox and text (@teunbrand, #4753) -
coord_flip()
has been marked as superseded. The recommended alternative is
to swap thex
andy
aesthetic and/or using theorientation
argument in
a layer (@teunbrand, #5130). -
The
trans
argument in scales and secondary axes has been renamed to
transform
. Thetrans
argument itself is deprecated. To access the
transformation from the scale, a newget_transformation()
method is
added to Scale-classes (#5558). -
Providing a numeric vector to
theme(legend.position)
has been deprecated.
To set the default legend position inside the plot use
theme(legend.position = "inside", legend.position.inside = c(...))
instead.
New features
-
Plot scales now ignore
AsIs
objects constructed withI(x)
, instead of
invoking the identity scale. This allows these columns to co-exist with other
layers that need a non-identity scale for the same aesthetic. Also, it makes
it easy to specify relative positions (@teunbrand, #5142). -
The
fill
aesthetic in many geoms now accepts grid's patterns and gradients.
For developers of layer extensions, this feature can be enabled by switching
fromfill = alpha(fill, alpha)
tofill = fill_alpha(fill, alpha)
when
providing fills togrid::gpar()
(@teunbrand, #3997). -
New function
check_device()
for testing the availability of advanced
graphics features introduced in R 4.1.0 onward (@teunbrand, #5332). -
coord_radial()
is a successor tocoord_polar()
with more customisation
options.coord_radial()
can:- integrate with the new guide system via a dedicated
guide_axis_theta()
to
display the angle coordinate. - in addition to drawing full circles, also draw circle sectors by using the
end
argument. - avoid data vanishing in the center of the plot by setting the
donut
argument. - adjust the
angle
aesthetic of layers, such asgeom_text()
, to align
with the coordinate system using therotate_angle
argument.
- integrate with the new guide system via a dedicated
The guide system
The guide system encompassing axes and legends, as the last remaining chunk of
ggplot2, has been rewritten to use the <ggproto>
system instead of the S3
system. This change was a necessary step to officially break open the guide
system for extension package developers. The axes and legends now inherit from
a <Guide>
class, which makes them extensible in the same manner as geoms,
stats, facets and coords (#3329, @teunbrand)
-
The most user-facing change is that the styling of guides is rewired through
the theme system. Guides now have atheme
argument that can style
individual guides, whiletheme()
has gained additional arguments to style
guides. Theme elements declared in the guide override theme elements set
through the plot. The new theme elements for guides are:
legend.key.spacing{.x/.y}
,legend.frame
,legend.axis.line
,
legend.ticks
,legend.ticks.length
,legend.text.position
and
legend.title.position
. Previous style options in the arguments of
guide_*()
functions are soft-deprecated. -
Unfortunately, we could not fully preserve the function of pre-existing
guide extensions written in the S3 system. A fallback for these old guides
is encapsulated in the<GuideOld>
class, which calls the old S3 generics.
The S3 methods have been removed as part of cleaning up, so the old guides
will still work if the S3 methods are reimplemented, but we encourage to
switch to the new system (#2728). -
The
order
argument of guides now strictly needs to be a length-1
integer (#4958).
Axes
-
New
guide_axis_stack()
to combine other axis guides on top of one another. -
New
guide_axis_theta()
to draw an axis in a circular arc in
coord_radial()
. The guide can be controlled by adding
guides(theta = guide_axis_theta(...))
to a plot. -
New
guide_axis_logticks()
can be used to draw logarithmic tick marks as
an axis. It supersedes theannotation_logticks()
function
(@teunbrand, #5325). -
guide_axis()
gains aminor.ticks
argument to draw minor ticks (#4387). -
guide_axis()
gains acap
argument that can be used to trim the
axis line to extreme breaks (#4907). -
Primary axis titles are now placed at the primary guide, so that
guides(x = guide_axis(position = "top"))
will display the title at the
top by default (#4650). -
The default
vjust
for theaxis.title.y.right
element is now 1 instead of
0. -
Unknown secondary axis guide positions are now inferred as the opposite
of the primary axis guide when the latter has a knownposition
(#4650).
Legends
-
New
guide_custom()
function for drawing custom graphical objects (grobs)
unrelated to scales in legend positions (#5416). -
All legends have acquired a
position
argument, that allows individual guides
to deviate from thelegend.position
set in thetheme()
function. This
means that legends can now be placed at multiple sides of the plot (#5488). -
The spacing between legend keys and their labels, in addition to legends
and their titles, is now controlled by the text'smargin
setting. Not
specifying margins will automatically add appropriate text margins. To
control the spacing within a legend between keys, the new
legend.key.spacing.{x/y}
argument can be used intheme()
. This leaves the
legend.spacing
theme setting dedicated to solely controlling the spacing
between different guides (#5455). -
guide_colourbar()
andguide_coloursteps()
gain analpha
argument to
set the transparency of the bar (#5085). -
New
display
argument inguide_colourbar()
supplants theraster
argument.
In R 4.1.0 and above,display = "gradient"
will draw a gradient. -
Legend keys that can draw arrows have their size adjusted for arrows.
-
When legend titles are larger than the legend, title justification extends
to the placement of keys and labels (#1903). -
Glyph drawing functions of the
draw_key_*()
family can now set"width"
and"height"
attributes (in centimetres) to the produced keys to control
their displayed size in the legend. -
coord_sf()
now uses customisable guides provided in the scales or
guides()
function (@teunbrand).
Improvements
-
guide_coloursteps(even.steps = FALSE)
now draws one rectangle per interval
instead of many small ones (#5481). -
draw_key_label()
now better reflects the appearance of labels (#5561). -
position_stack()
no longer silently removes missing data, which is now
handled by the geom instead of position (#3532). -
The
minor_breaks
function argument in scales can now also take a function
with two arguments: the scale's limits and the scale's major breaks (#3583). -
Failing to fit or predict in
stat_smooth()
now gives a warning and omits
the failed group, instead of throwing an error (@teunbrand, #5352). -
labeller()
now handles unspecified entries from lookup tables
(@92amartins, #4599). -
fortify.default()
now accepts a data-frame-like object granted the object
exhibits healthydim()
,colnames()
, andas.data.frame()
behaviours
(@hpages, #5390). -
geom_violin()
gains abounds
argument analogous togeom_density()
s
(@eliocamp, #5493). -
To apply dodging more consistently in violin plots,
stat_ydensity()
now
has adrop
argument to keep or discard groups with 1 observation. -
geom_boxplot()
gains a new argument,staplewidth
that can draw staples
at the ends of whiskers (@teunbrand, #5126) -
geom_boxplot()
gains anoutliers
argument to switch outliers on or off,
in a manner that does affects the scale range. For hiding outliers that does
not affect the scale range, you can continue to useoutlier.shape = NA
(@teunbrand, #4892). -
Nicer error messages for xlim/ylim arguments in coord-* functions
(@92amartins, #4601, #5297). -
You can now omit either
xend
oryend
fromgeom_segment()
as only one
of these is now required. If one is missing, it will be filled from thex
andy
aesthetics respectively. This makes drawing horizontal or vertical
segments a little bit more convenient (@teunbrand, #5140). -
When
geom_path()
has aesthetics varying within groups, thearrow()
is
applied to groups instead of individual segments (@teunbrand, #4935). -
geom_text()
andgeom_label()
gained asize.unit
parameter that set the
text size to millimetres, points, centimetres, inches or picas
(@teunbrand, #3799). -
geom_label()
now uses theangle
aesthetic (@teunbrand, #2785) -
The
label.padding
argument ingeom_label()
now supports inputs created
with themargin()
function (#5030). -
ScaleContinuous$get_breaks()
now only callsscales::zero_range()
on limits
in transformed space, rather than in data space (#5304). -
Scales throw more informative messages (@teunbrand, #4185, #4258)
-
scale_*_manual()
with a namedvalues
argument now emits a warning when
none of those names match the values found in the data (@teunbrand, #5298). -
The
name
argument in most scales is now explicitly the first argument
(#5535) -
The
translate_shape_string()
internal function is now exported for use in
extensions of point layers (@teunbrand, #5191). -
To improve
width
calculation in bar plots with empty factor levels,
resolution()
considersmapped_discrete
values as having resolution 1
(@teunbrand, #5211) -
In
theme()
, some elements can be specified withrel()
to inherit from
unit
-class objects in a relative fashion (@teunbrand, #3951). -
theme()
now supports splicing a list of arguments (#5542). -
In the theme element hierarchy, parent elements that are a strict subclass
of child elements now confer their subclass upon the children (#5457). -
New
plot.tag.location
intheme()
can control placement of the plot tag
in the"margin"
,"plot"
or the new"panel"
option (#4297). -
coord_munch()
can now close polygon shapes (@teunbrand, #3271) -
Aesthetics listed in
geom_*()
andstat_*()
layers now point to relevant
documentation (@teunbrand, #5123). -
The new argument
axes
infacet_grid()
andfacet_wrap()
controls the
display of axes at interior panel positions. Additionally, theaxis.labels
argument can be used to only draw tick marks or fully labelled axes
(@teunbrand, #4064). -
coord_polar()
can have free scales in facets (@teunbrand, #2815). -
The
get_guide_data()
function can be used to extract position and label
information from the plot (#5004). -
Improve performance of layers without positional scales (@zeehio, #4990)
-
More informative error for mismatched
direction
/theme(legend.direction = ...)
arguments (#4364, #4930).
Bug fixes
-
Fixed regression in
guide_legend()
where thelinewidth
key size
wasn't adapted to the width of the lines (#5160). -
In
guide_bins()
, the title no longer arbitrarily becomes offset from
the guide when it has long labels. -
guide_colourbar()
andguide_coloursteps()
merge properly when one
of the aesthetics is dropped (#5324). -
When using
geom_dotplot(binaxis = "x")
with a discrete y-variable, dots are
now stacked from the y-position rather than from 0 (@teunbrand, #5462) -
stat_count()
treatsx
as unique in the same mannerunique()
does
(#4609). -
The plot's title, subtitle and caption now obey horizontal text margins
(#5533). -
Contour functions will not fail when
options("OutDec")
is not.
(@eliocamp, #5555). -
Lines where
linewidth = NA
are now dropped ingeom_sf()
(#5204). -
ggsave()
no longer sometimes creates new directories, which is now
controlled by the newcreate.dir
argument (#5489). -
Legend titles no longer take up space if they've been removed by setting
legend.title = element_blank()
(@teunbrand, #3587). -
resolution()
has a small tolerance, preventing spuriously small resolutions
due to rounding errors (@teunbrand, #2516). -
stage()
now works correctly, even with aesthetics that do not have scales
(#5408) -
stat_ydensity()
with incomplete groups calculates the defaultwidth
parameter more stably (@teunbrand, #5396) -
The
size
argument inannotation_logticks()
has been deprecated in favour
of thelinewidth
argument (#5292). -
Binned scales now treat
NA
s in limits the same way continuous scales do
(#5355). -
Binned scales work better with
trans = "reverse"
(#5355). -
Integers are once again valid input to theme arguments that expect numeric
input (@teunbrand, #5369) -
Legends in
scale_*_manual()
can showNA
values again when thevalues
is
a named vector (@teunbrand, #5214, #5286). -
Fixed bug in
coord_sf()
where graticule lines didn't obey
panel.grid.major
's linewidth setting (@teunbrand, #5179) -
Fixed bug in
annotation_logticks()
when no suitable tick positions could
be found (@teunbrand, #5248). -
The default width of
geom_bar()
is now based on panel-wise resolution of
the data, rather than global resolution (@teunbrand, #4336). -
stat_align()
is now applied per panel instead of globally, preventing issues
when facets have different ranges (@teunbrand, #5227). -
A stacking bug in
stat_align()
was fixed (@teunbrand, #5176). -
stat_contour()
andstat_contour_filled()
now warn about and remove
duplicated coordinates (@teunbrand, #5215). -
guide_coloursteps()
andguide_bins()
sort breaks (#5152).
Internal changes
-
The
ScaleContinuous$get_breaks()
method no longer censors
the computed breaks. -
The ggplot object now contains
$layout
which points to theLayout
ggproto
object and will be used by theggplot_build.ggplot
method. This was exposed
so that package developers may extend the behaviour of theLayout
ggproto
object without needing to develop an entirely newggplot_build
method
(@jtlandis, #5077). -
Guide building is now part of
ggplot_build()
instead of
ggplot_gtable()
to allow guides to observe unmapped data (#5483). -
The
titleGrob()
function has been refactored to be faster and less
complicated. -
The
scales_*()
functions related to managing the<ScalesList>
class have
been implemented as methods in the<ScalesList>
class, rather than stray
functions (#1310).