tinyplot v0.3.0 is a big release with many new features, both internal and user-facing. Below we have tried to group alike news items together, starting with the new plot type processing system.
New plot type processing system:
tinyplot the plot type was specified by character
arguments, i.e., either the standard character shortcuts (such "p", "l",
etc.) or labels (such as "hist", "boxplot", etc.). In addition, the
type argument now accepts functional type_*() equivalents (e.g.,
type_hist()) which enable a variety of additional features, as well as a
more disciplined approach to explicit argument passing for customized type
behavior. (#222 @vincentarelbundock)tinyplot(Nile, type = "hist") and tinyplot(Nile, type = type_hist()).type_<typename>() functions.type_*() function call, e.g., as in
tinyplot(Nile, type = type_hist(breaks = 30)). In many situations it is
still possible to use the character specification plus extra arguments
instead, e.g., as in tinyplot(Nile, type = "hist", breaks = 30). However,
this only works if the ancilliary type arguments do not match or even
partially match any of the arguments of the tinyplot() function itself.
This is why the former approach is recommended (unless using only the
default type).ribbon.alpha in tinyplot(). Use the
alpha argument of the type_ribbon() function instead:
tinyplot(..., type = type_ribbon(alpha = 0.5)). Note that it is not
equivalent to use tinyplot(..., type = "ribbon", alpha = 0.5) because the
latter matches the alpha argument of tinyplot() (rather than of
type_ribbon()) and modifies the palette rather than the ribbon only.New plot types:
type_spineplot() (shortcut: "spineplot") spine plots and
spinograms. These are modified versions of a histogram or mosaic plot,
and are particularly useful for visualizing factor variables. (#233
@zeileis with contributions from @grantmcdermott)type_qq() (shortcut: "qq") for quantile-quantile plots. (#251
@vincentarelbundock)type_ridge() (shortcut: "ridge") for ridge plots aka Joy plots.
(#252 @vincentarelbundock, @zeileis, and @grantmcdermott)type_rug() (shortcut: "rug") adds a rug to an existing plot. (#276
@grantmcdermott)type_glm() (shortcut: "glm") (@vincentarelbundock)type_lm() (shortcut: "lm") (@vincentarelbundock)type_loess() (shortcut: "loess") (@vincentarelbundock)type_spline() (shortcut: "spline") (#241 @grantmcdermott)type_abline(): line(s) with intercept and slope (#249 @vincentarelbundock)type_hline(): horizontal line(s) (#249 @vincentarelbundock)type_vline(): vertical line(s) (#249 @vincentarelbundock)type_function(): arbitrary function. (#250 @vincentarelbundock)type_summary(): summarize values of y along unique values of x (#274
@grantmcdermott)Other new features:
tinyplot() arguments:
flip <logical> allows for easily flipping (swapping) the orientation
of the x and y axes. This should work regardless of plot type, e.g.
tinyplot(~Sepal.Length | Species, data = iris, type = "density", flip = TRUE).
(#216 @grantmcdermott)draw = <draw_funcs> allows users to pass arbitrary drawing functions that
are evaluated as-is, before the main plotting elements. A core use case is
drawing common annotations across every facet of a faceted plot, e.g. text or
threshold lines. (#245 @grantmcdermott)facet.args gains a free = <logical> sub-argument for independently
scaling the axes limits of individual facets. (#253 @grantmcdermott)tpar() gains additional grid.col, grid.lty, and grid.lwd arguments for
fine-grained control over the appearance of the default panel grid when
tinyplot(..., grid = TRUE) is called. (#237 @grantmcdermott)tinyplot_add() (alias: plt_add()) convenience function allows
easy layering of plots without having to specify repeat arguments. (#246
@vincentarelbundock)tinytheme() function provides a convenient mechanism for styling
plots according to a variety of pre-defined themes, e.g. tinytheme("clean").
Users can also add their own custom themes or tweak an existing theme. Themes
are persistent and will affect all subsequent plots until they are explicitly
reset, e.g. by calling tinytheme() (with no argument) to restore the default
plot aesthetic. Behind the scenes, tinytheme() sets a hook for a group
graphical parameters by passing them through tpar(). Users can still use
tpar() to style their plots by manually setting individual graphical
parameters. But going forward we expect that most tinyplot users will prefer
the convenience of going through tinytheme(). More details are provided in the
dedicated
Themes vignette
on the website. (#258 @vincentarelbundock and @grantmcdermott)Bug fixes:
plt(numeric ~ character) now work correctly, with the
character variable automatically being coerced to a factor. (#219 @zeileis)xlim and ylim when explicitly supplied by the user. (Thanks to
@mclements for code submission #221)ymin or ymax args, now inherit these values from y
(#224 @grantmcdermott)y is a factor now work automatically, dispatching to the new
type_spineplot() type. Thanks to @zeileis for the original suggestion all the
way back in #2 and the eventual solution in #233.Internals:
Misc:
New Features:
The axes argument of tinyplot()/plt() gains extra options for
fine-grained control of the plot axes. In addition to the existing logical
(TRUE/FALSE) option, users can now specify one of the following character
keywords (or, just their first letters as a convenient shorthand):
"standard" (with axis, ticks, and labels; equivalent to TRUE),"none" (no axes; equivalent to FALSE),"ticks" (only ticks and labels without axis line),"labels" (only labels without ticks and axis line),"axis" (only axis line and labels but no ticks).Simultaneously, the main plotting functions also gain the xaxt and yaxt
for separately controlling the two axes using the same keyword options. For
example, plt(0:10, xaxt = "l", yaxt = "t") will yield a plot where the x-axis
only contains labels and the y-axis contains both labels and ticks, but no axis
line. (#190 @zeileis)
Support additional boxplot arguments like varwidth, notch, etc. Note
that tinyplot(..., type = "boxplot", boxwidth = <num>) is equivalent to the
boxplot(..., width = <num>); we just use the "box(width)" prefix to avoid
conflicting with the existing tinyplot(..., width) argument.
(#196 @grantmcdermott)
Bug fixes:
type = "density", which was a regression
accidentally introduced in v0.2.0 (#187 @grantmcdermott)x == by, or these two are
functionally identical. (#196 @grantmcdermott)xlab and ylab arguments not respected in some plots. Thanks to @lbelzile
for reporting Issue #203.tinyplot(log(x) ~ x). (#197 @zeileis)tinyplot(mpg ~ wt, data = mtcars, facet = am + vs ~ gear))
now plot all panels correctly, even if some combinations are missing. (#197
@grantmcdermott)Internals:
New features:
type = "n", i.e. empty plot. Since type = "n" implicitly assumes points,
which limits the type of legend that can be drawn alongside the empty plot, we
have also added a companion empty argument that can be used alongside any
plot type. (#157, #167 @grantmcdermott)type = "boxplot". Simultaneously enables plt(numeric ~ factor)
support, first raised in #2, so that a boxplot is automatically plotted if a
numeric is plotted against a factor. (#154 @grantmcdermott)type = "polypath". (#159 @grantmcdermott)type = "rect". (#161 @grantmcdermott)type = "segments". (#163 @grantmcdermott)type = "histogram" (alias type = "hist"). (#164 @grantmcdermott)type = "jitter" (alias type = "j"). (#170 @grantmcdermott)Internals:
Misc:
Our first CRAN submission! This v0.1.0 release includes the following new features and updates:
License:
Breaking changes:
To ensure consistent "dot.case" style for all tinyplot() function arguments,
the following two arguments have been renamed (old => new):
par_restore => restore.par (note the change in word order too!)ribbon_alpha => ribbon.alphaWe don't believe that these two arguments are much used in practice. So
hopefully it will only have a negligible effect on existing tinyplot code in
the wild, even though it is a breaking change. (#149 @grantmcdermott)
New features:
by. Thanks to @zeileis for detailed feedback and advice around the default
palette choice (a restricted version of the "viridis" palette), as well as
StackOverflow user mnel, whose answer
here provided the inspiration for the
final implementation. (#122 @grantmcdermott)lwd argument for adjusting line widths. Similar to pch,
lty, etc. this arguments also accepts a "by" convenience keyword to
automatically vary line widths by group. (#134 @grantmcdermott)tpar() now accepts standard par() arguments in addition to the
tinyplot-specific ones. This allows users to set or query graphical parameters
via a single convenience function, instead having to invoke tpar and par
separately. (#140 @grantmcdermott)
tpar() has gained some additional parameters for fine-grained
control of global plot defaults, including grid, ribbon.alpha, and various
file.* parameters (see next bullet point).file argument,
alongside corresponding width and height arguments for output customization
(both of which are defined in inches). For example,
tinyplot(..., file = "~/myplot.png", width = 8, height = 5). This
implementation relies on a simple internal wrapper around the traditional R
external graphics devices like png(), pdf(), etc. But it may prove more
convenient, since the current global graphics parameters held in (t)par() are
carried over to the external device too and don't need to be reset. Note that
the appropriate device type is determined automatically by the file extension,
which must be one of ".png", ".jpg" (".jpeg"), ".pdf", or ".svg".
(#143 @grantmcdermott)tinyplot logo. (#148 @grantmcdermott)get_saved_par() function can be used to retrieve the par settings
from immediately before or immediately after the preceding tinyplot call.
This function replaces some older (non-exported) internal functions that
tinyplot was using to restore and control par environments. But it could
also prove help to end users who are looking for additional ways to restore
par settings after the fact. See ?get_saved_par for some examples. (#152
@grantmcdermott)tinyplot/plt gaina a new alpha = <numeric[0,1]> convenience argument for
adding transparency to plot elements and colours. Example use:
plt(rnorm(1e3), pch = 19, alpha = 0.3). (#129 @grantmcdermott)bg (or its alias, fill) a numeric in the range
[0,1]. This feature has the same effect as bg = "by" except for the added
transparency. Example use:
tinyplot(lat ~ long | depth, data = quakes, pch = 21, cex = 2, bg = 0.2). (#129
@grantmcdermott)Bug fixes:
tpar(facet.x = ...) args from being passed forward
and set correctly. (#137 @grantmcdermott)type = "density". (#147
@grantmcdermott)Internals:
tinyplot
website.
(#135 @grantmcdermott)inst/tinytest is pushing the install tarball over
CRAN's recommended 5 MB limit. Please note that local testing of the package
requires adding the NOT_CRAN=TRUE environment variable to your .Renviron file
(or, exporting it in your .bashrc/.zshrc/etc. dotfile if you prefer that
approach). (#145 @vincentarelbundock & @grantmcdermott)density grid coords. (#150 @grantmcdermott)IMPORTANT BREAKING CHANGE:
The package has been renamed to tinyplot. (#22 @grantmcdermott)
This package renaming also incorporates the following function changes:
plot2() is replaced by tinyplot() (or its shorthand alias plt()).par2() is replaced by tpar().So, where you used to write...
library(plot2)
plot2(Sepal.Length ~ Petal.Length | Species, iris)
... you should now write:
library(tinyplot)
tinyplot(Sepal.Length ~ Petal.Length | Species, iris)
# Or, use the equivalent shorthand `plt` alias
plt(Sepal.Length ~ Petal.Length | Species, iris)
The package URLs have been updated accordingly:
Many thanks to everyone who provided thoughtful feedback about this prospective name change, especially @zeileis and @vincentarelbundock for kicking off the discussion, as well as the 100+ participants who voted in the social media poll.
For more details about the rational underlying this renaming decision, please see the following GitHub comment, as well as the discussion that preceded it: https://github.com/grantmcdermott/plot2/issues/22#issuecomment-1928472754
Website:
We now have a dedicated website! (#80 @vincentarelbundock)
New features:
cex and bg (alias fill) arguments. The latter also permit
the "by" convenience keyword similar to lty and pch. This is useful for
plotting filled point characters (e.g., pch = 21), where you want a different
colour for the fill and border. (#50, #75 @grantmcdermott)add argument allows new plot2 objects to be added to / on top of the
existing plot window. (#60 @grantmcdermott)plot2(~ Temp | Month, airquality). (#62
@grantmcdermott and @zeileis)plot2(x, type = "density") as an alternative to
plot2(density(x)). Works for both the atomic and one-sided formula methods.
(#66 @grantmcdermott)plot2 gains a new facet argument for drawing faceted plots. Users can
override the default square arrangement by passing the desired number of facet
rows or columns to the companion facet.args helper function. Facets can be
combined with by grouping, or used on their own.
(#83, #91, #94, #96, #101, #103 @grantmcdermott)plot2-specific graphical parameters globally via
the new par2() function (which is modeled on the base par() function). At
the moment only a subset of global parameters, mostly related to legend and
facet behaviour, are exposed in par2. But users can expect that more will be
added in future releases. (#33, #94 @grantmcdermott)Bug fixes:
plot2(rnorm(100). (#52 etiennebacher)lmar and fmar arguments of par2(). The default
legend margin is par2(lmar = c(1,0, 0.1), which means that there is 1.0 line
of padding between the legend and the plot region (inside margin) and 0.1 line
of padding between the legend and edge of the graphics device (outer margin).
Similarly, the default facet padding is par2(fmar = c(1,1,1,1), which means
that there is a single line of padding around each side of the individual
facets. Users can override these defaults by passing numeric vectors of the
appropriate length to par2(). For example, par2(lmar = c(0,0.1) would shrink
the inner gap between the legend and plot region to zero, but leave the small
outer gap to outside of the graphics device unchanged. (#94 @grantmcdermott)Breaking changes:
palette argument that
unifies the old palette and (deprecated) palette.args arguments. In
addition, the default palette for small groups has been changed from "Okabe-Ito"
to "R4". (#31 and #32 @grantmcdermott)legend argument that unifies the
previous (deprecated) legend.position and legend.args arguments. This
change also enables several enhancements over the old legend behaviour; see
below. (#34 @grantmcdermott)New features:
log. (#15 @etiennebacher)pch and lty arguments now accept a "by" convenience keyword for
automatically adjusting plot characters and line types by groups. (#28
@grantmcdermott)legend argument, including changing
labels, turning of the legend title, and so on. (#34 @grantmcdermott)"pointrange", "errobar", and "ribbon" plot types. (#35
@vincentarelbundock, #40 and #46 @grantmcdermott)grid = TRUE as an alternative to grid = grid(). (#43
@grantmcdermott)Bug fixes:
par(pch=X) globally is now respected. (#20 @grantmcdermott)palette("ggplot2") is now respected. (#44
@grantmcdermott)Breaking changes:
New features:
pch, lty, and col types per group (#5
and #11 by @vincentarelbundock).Bug fixes:
plot2 now works (#13 by @grantmcdermott, thanks
@karoliskoncevicius for reporting).Internals:
plot2.formula (#8 by @zeileis).Project: