diff --git a/R/theme-elements.R b/R/theme-elements.R index a16302b6db..0ab5930dd0 100644 --- a/R/theme-elements.R +++ b/R/theme-elements.R @@ -131,7 +131,14 @@ element_line <- function(colour = NULL, linewidth = NULL, linetype = NULL, } -#' @param family Font family +#' @param family The typeface to use. The validity of this value will depend on +#' the graphics device being used for rendering the plot. See +#' [the systemfonts vignette](https://systemfonts.r-lib.org/articles/systemfonts.html) +#' for guidance on the best way to access fonts installed on your computer. +#' The values `"sans"`, `"serif"`, and `"mono"` should always be valid and +#' will select the default typeface for the respective styles. However, what +#' is considered default is dependant on the graphics device and the operating +#' system. #' @param face Font face ("plain", "italic", "bold", "bold.italic") #' @param hjust Horizontal justification (in \eqn{[0, 1]}) #' @param vjust Vertical justification (in \eqn{[0, 1]}) diff --git a/man/element.Rd b/man/element.Rd index 84fe10fd20..6ee08dd20d 100644 --- a/man/element.Rd +++ b/man/element.Rd @@ -125,7 +125,14 @@ calculating final element state.} \item{arrow.fill}{Fill colour for arrows.} -\item{family}{Font family} +\item{family}{The typeface to use. The validity of this value will depend on +the graphics device being used for rendering the plot. See +\href{https://systemfonts.r-lib.org/articles/systemfonts.html}{the systemfonts vignette} +for guidance on the best way to access fonts installed on your computer. +The values \code{"sans"}, \code{"serif"}, and \code{"mono"} should always be valid and +will select the default typeface for the respective styles. However, what +is considered default is dependant on the graphics device and the operating +system.} \item{face}{Font face ("plain", "italic", "bold", "bold.italic")} diff --git a/man/guide_bins.Rd b/man/guide_bins.Rd index d9fd873cdb..da37012904 100644 --- a/man/guide_bins.Rd +++ b/man/guide_bins.Rd @@ -37,7 +37,8 @@ representing the text angle in degrees, or \code{NULL} to not overrule the settings (default).} \item{position}{A character string indicating where the legend should be -placed relative to the plot panels.} +placed relative to the plot panels. +One of "top", "right", "bottom", "left", or "inside".} \item{direction}{A character string indicating the direction of the guide. One of "horizontal" or "vertical".} diff --git a/man/guide_colourbar.Rd b/man/guide_colourbar.Rd index bba0e628c0..1eced43c34 100644 --- a/man/guide_colourbar.Rd +++ b/man/guide_colourbar.Rd @@ -89,7 +89,8 @@ representing the text angle in degrees, or \code{NULL} to not overrule the settings (default).} \item{position}{A character string indicating where the legend should be -placed relative to the plot panels.} +placed relative to the plot panels. +One of "top", "right", "bottom", "left", or "inside".} \item{direction}{A character string indicating the direction of the guide. One of "horizontal" or "vertical."} diff --git a/man/guide_coloursteps.Rd b/man/guide_coloursteps.Rd index dc5806929a..dc8ba71c78 100644 --- a/man/guide_coloursteps.Rd +++ b/man/guide_coloursteps.Rd @@ -71,7 +71,8 @@ shown irrespective of the value of \code{show.limits}.} One of "horizontal" or "vertical."} \item{position}{A character string indicating where the legend should be -placed relative to the plot panels.} +placed relative to the plot panels. +One of "top", "right", "bottom", "left", or "inside".} \item{reverse}{logical. If \code{TRUE} the colourbar is reversed. By default, the highest value is on the top and the lowest value is on the bottom} diff --git a/man/guide_custom.Rd b/man/guide_custom.Rd index f13559cae2..2fa55193c4 100644 --- a/man/guide_custom.Rd +++ b/man/guide_custom.Rd @@ -32,7 +32,8 @@ the \code{legend}-prefix. Arguments that apply to combined legends \verb{legend.justification.*}, \code{legend.location} and \verb{legend.box.*}.} \item{position}{A character string indicating where the legend should be -placed relative to the plot panels.} +placed relative to the plot panels. +One of "top", "right", "bottom", "left", or "inside".} \item{order}{positive integer less than 99 that specifies the order of this guide among multiple guides. This controls the order in which diff --git a/man/hmisc.Rd b/man/hmisc.Rd index 96fd7bba30..40fe36ca41 100644 --- a/man/hmisc.Rd +++ b/man/hmisc.Rd @@ -29,10 +29,10 @@ These are wrappers around functions from \pkg{Hmisc} designed to make them easier to use with \code{\link[=stat_summary]{stat_summary()}}. See the Hmisc documentation for more details: \itemize{ -\item \code{\link[Hmisc:smean.sd]{Hmisc::smean.cl.boot()}} -\item \code{\link[Hmisc:smean.sd]{Hmisc::smean.cl.normal()}} -\item \code{\link[Hmisc:smean.sd]{Hmisc::smean.sdl()}} -\item \code{\link[Hmisc:smean.sd]{Hmisc::smedian.hilow()}} +\item \code{\link[Hmisc:smean.cl.boot]{Hmisc::smean.cl.boot()}} +\item \code{\link[Hmisc:smean.cl.normal]{Hmisc::smean.cl.normal()}} +\item \code{\link[Hmisc:smean.sdl]{Hmisc::smean.sdl()}} +\item \code{\link[Hmisc:smedian.hilow]{Hmisc::smedian.hilow()}} } } \examples{ diff --git a/vignettes/ggplot2-specs.Rmd b/vignettes/ggplot2-specs.Rmd index 21d90e12af..c346e8a08e 100644 --- a/vignettes/ggplot2-specs.Rmd +++ b/vignettes/ggplot2-specs.Rmd @@ -15,7 +15,7 @@ library(ggplot2) knitr::opts_chunk$set(fig.dpi = 96, collapse = TRUE, comment = "#>") ``` -This vignette summarises the various formats that grid drawing functions take. Most of this information is available scattered throughout the R documentation. This appendix brings it all together in one place. +This vignette summarises the various formats that grid drawing functions take. Most of this information is available scattered throughout the R documentation. This appendix brings it all together in one place. ## Colour and fill @@ -23,21 +23,21 @@ Almost every geom has either colour, fill, or both. Colours and fills can be spe * A __name__, e.g., `"red"`. R has `r length(colours())` built-in named colours, which can be listed with `colours()`. - -* An __rgb specification__, with a string of the form `"#RRGGBB"` where each of - the pairs `RR`, `GG`, `BB` consists of two hexadecimal digits giving a value + +* An __rgb specification__, with a string of the form `"#RRGGBB"` where each of + the pairs `RR`, `GG`, `BB` consists of two hexadecimal digits giving a value in the range `00` to `FF` - - You can optionally make the colour transparent by using the form + + You can optionally make the colour transparent by using the form `"#RRGGBBAA"`. * An __NA__, for a completely transparent colour. -* The [munsell](https://github.com/cwickham/munsell) package, by Charlotte - Wickham, makes it easy to choose specific colours using a system designed by +* The [munsell](https://github.com/cwickham/munsell) package, by Charlotte + Wickham, makes it easy to choose specific colours using a system designed by Albert H. Munsell. If you invest a little in learning the system, it provides a convenient way of specifying aesthetically pleasing colours. - + ```{r} munsell::mnsl("5PB 5/10") ``` @@ -50,7 +50,7 @@ As well as `colour`, the appearance of a line is affected by `linewidth`, `linet Line types can be specified with: -* An __integer__ or __name__: 0 = blank, 1 = solid, 2 = dashed, 3 = dotted, +* An __integer__ or __name__: 0 = blank, 1 = solid, 2 = dashed, 3 = dotted, 4 = dotdash, 5 = longdash, 6 = twodash, as shown below: ```{r} @@ -61,21 +61,21 @@ Line types can be specified with: linetypes <- data.frame( y = seq_along(lty), lty = lty - ) - ggplot(linetypes, aes(0, y)) + - geom_segment(aes(xend = 5, yend = y, linetype = lty)) + - scale_linetype_identity() + + ) + ggplot(linetypes, aes(0, y)) + + geom_segment(aes(xend = 5, yend = y, linetype = lty)) + + scale_linetype_identity() + geom_text(aes(label = lty), hjust = 0, nudge_y = 0.2) + - scale_x_continuous(NULL, breaks = NULL) + + scale_x_continuous(NULL, breaks = NULL) + scale_y_reverse(NULL, breaks = NULL) ``` -* The lengths of on/off stretches of line. This is done with a string +* The lengths of on/off stretches of line. This is done with a string containing 2, 4, 6, or 8 hexadecimal digits which give the lengths of - consecutive lengths. For example, the string `"33"` specifies three units - on followed by three off and `"3313"` specifies three units on followed by - three off followed by one on and finally three off. - + consecutive lengths. For example, the string `"33"` specifies three units + on followed by three off and `"3313"` specifies three units on followed by + three off followed by one on and finally three off. + ```{r} #| fig.alt: "A series of 9 horizontal lines with different line types. #| Each line is titled by two hexadecimal digits that determined the @@ -84,22 +84,22 @@ Line types can be specified with: linetypes <- data.frame( y = seq_along(lty), lty = lty - ) - ggplot(linetypes, aes(0, y)) + - geom_segment(aes(xend = 5, yend = y, linetype = lty)) + - scale_linetype_identity() + + ) + ggplot(linetypes, aes(0, y)) + + geom_segment(aes(xend = 5, yend = y, linetype = lty)) + + scale_linetype_identity() + geom_text(aes(label = lty), hjust = 0, nudge_y = 0.2) + - scale_x_continuous(NULL, breaks = NULL) + + scale_x_continuous(NULL, breaks = NULL) + scale_y_reverse(NULL, breaks = NULL) ``` - - The five standard dash-dot line types described above correspond to 44, 13, + + The five standard dash-dot line types described above correspond to 44, 13, 1343, 73, and 2262. ### Linewidth -Due to a historical error, the unit of linewidth is roughly 0.75 mm. Making it -exactly 1 mm would change a very large number of existing plots, so we're stuck +Due to a historical error, the unit of linewidth is roughly 0.75 mm. Making it +exactly 1 mm would change a very large number of existing plots, so we're stuck with this mistake. ### Line end/join paramters @@ -121,45 +121,45 @@ with this mistake. #| and ends in a square shape." df <- data.frame(x = 1:3, y = c(4, 1, 9)) base <- ggplot(df, aes(x, y)) + xlim(0.5, 3.5) + ylim(0, 10) - base + - geom_path(linewidth = 10) + + base + + geom_path(linewidth = 10) + geom_path(linewidth = 1, colour = "red") - - base + - geom_path(linewidth = 10, lineend = "round") + + + base + + geom_path(linewidth = 10, lineend = "round") + geom_path(linewidth = 1, colour = "red") - - base + - geom_path(linewidth = 10, lineend = "square") + + + base + + geom_path(linewidth = 10, lineend = "square") + geom_path(linewidth = 1, colour = "red") ``` -* The appearance of line joins is controlled by `linejoin` and can be one of +* The appearance of line joins is controlled by `linejoin` and can be one of "round" (the default), "mitre", or "bevel". ```{r} #| out-width: 30% #| fig-show: hold #| fig.alt: - #| - "A plot showing a thin red line on top of a thick black line shaped like + #| - "A plot showing a thin red line on top of a thick black line shaped like #| the letter 'V'. The corner in the black V-shape is rounded." - #| - "A plot showing a thin red line on top of a thick black line shaped like + #| - "A plot showing a thin red line on top of a thick black line shaped like #| the letter 'V'. The corner in the black V-shape is sharp." - #| - "A plot showing a thin red line on top of a thick black line shaped like - #| the letter 'V'. A piece of the corner is cut off so that the two + #| - "A plot showing a thin red line on top of a thick black line shaped like + #| the letter 'V'. A piece of the corner is cut off so that the two #| straight parts are connected by a horizontal part." df <- data.frame(x = 1:3, y = c(9, 1, 9)) base <- ggplot(df, aes(x, y)) + ylim(0, 10) - base + - geom_path(linewidth = 10) + + base + + geom_path(linewidth = 10) + geom_path(linewidth = 1, colour = "red") - - base + - geom_path(linewidth = 10, linejoin = "mitre") + + + base + + geom_path(linewidth = 10, linejoin = "mitre") + geom_path(linewidth = 1, colour = "red") - - base + - geom_path(linewidth = 10, linejoin = "bevel") + + + base + + geom_path(linewidth = 10, linejoin = "bevel") + geom_path(linewidth = 1, colour = "red") ``` @@ -180,30 +180,30 @@ Shapes take five types of values: ```{r} #| fig.alt: "A 5-by-5 grid of point symbols annotated by the numbers #| that can be used to represent the symbols. From left to right, the - #| first 15 symbols are lines or open shapes, the next 5 symbols are solid + #| first 15 symbols are lines or open shapes, the next 5 symbols are solid #| shapes and the last 5 symbols are filled shaped." shapes <- data.frame( shape = c(0:19, 22, 21, 24, 23, 20), x = 0:24 %/% 5, y = -(0:24 %% 5) ) - ggplot(shapes, aes(x, y)) + + ggplot(shapes, aes(x, y)) + geom_point(aes(shape = shape), size = 5, fill = "red") + geom_text(aes(label = shape), hjust = 0, nudge_x = 0.15) + scale_shape_identity() + expand_limits(x = 4.1) + theme_void() ``` - + * The __name__ of the shape: - + ```{r} #| out-width: 90% #| fig-asp: 0.4 #| fig-width: 8 - #| fig.alt: "An irregular 6-by-7 grid of point symbols annotated by the - #| names that can be used to represent the symbols. Broadly, from top to - #| bottom, the symbols are circles, squares, diamonds, triangles and + #| fig.alt: "An irregular 6-by-7 grid of point symbols annotated by the + #| names that can be used to represent the symbols. Broadly, from top to + #| bottom, the symbols are circles, squares, diamonds, triangles and #| others. Broadly from left to right, the symbols are solid shapes, #| open shapes, filled shapes and others." shape_names <- c( @@ -214,13 +214,13 @@ Shapes take five types of values: paste("triangle down", c("open", "filled")), "plus", "cross", "asterisk" ) - + shapes <- data.frame( shape_names = shape_names, x = c(1:7, 1:6, 1:3, 5, 1:3, 6, 2:3, 1:3), y = -rep(1:6, c(7, 6, 4, 4, 2, 3)) ) - + ggplot(shapes, aes(x, y)) + geom_point(aes(shape = shape_names), fill = "red", size = 5) + geom_text(aes(label = shape_names), nudge_y = -0.3, size = 3.5) + @@ -231,7 +231,7 @@ Shapes take five types of values: * A __single character__, to use that character as a plotting symbol. * A `.` to draw the smallest rectangle that is visible, usually 1 pixel. - + * An `NA`, to draw nothing. ### Colour and fill @@ -240,13 +240,13 @@ While `colour` applies to all shapes, `fill` only applies to shapes 21-25, as ca ```{r} #| fig.alt: "A plot showing a 4-by-4 grid of red points, the top 12 points with -#| black outlines. The size of the points increases horizontally. The stroke of +#| black outlines. The size of the points increases horizontally. The stroke of #| the outlines of the points increases vertically. A white diagonal line with -#| a negative slope marks that the 'stroke' versus 'size' trade-off has +#| a negative slope marks that the 'stroke' versus 'size' trade-off has #| similar total sizes." sizes <- expand.grid(size = (0:3) * 2, stroke = (0:3) * 2) -ggplot(sizes, aes(size, stroke, size = size, stroke = stroke)) + - geom_abline(slope = -1, intercept = 6, colour = "white", linewidth = 6) + +ggplot(sizes, aes(size, stroke, size = size, stroke = stroke)) + + geom_abline(slope = -1, intercept = 6, colour = "white", linewidth = 6) + geom_point(shape = 21, fill = "red") + scale_size_identity() ``` @@ -257,38 +257,44 @@ Because points are not typically filled, you may need to change some default set ### Font family -There are only three fonts that are guaranteed to work everywhere: "sans" (the default), "serif", or "mono": +`family` sets the typeface of the font. There are only three values that are guaranteed to work everywhere: "sans" (the default), "serif", or "mono": ```{r} -#| fig.alt: "A plot showing three text labels arranged vertically. The top +#| fig.alt: "A plot showing three text labels arranged vertically. The top #| label is 'sans' and is displayed in a sans-serif font. The middle label is #| 'serif' and is displayed in a serif font. The bottom label is 'mono' and #| is displayed in a monospaced font." df <- data.frame(x = 1, y = 3:1, family = c("sans", "serif", "mono")) -ggplot(df, aes(x, y)) + +ggplot(df, aes(x, y)) + geom_text(aes(label = family, family = family)) ``` -It's trickier to include a system font on a plot because text drawing is done differently by each graphics device (GD). There are five GDs in common use (`png()`, `pdf()`, on screen devices for Windows, Mac and Linux), so to have a font work everywhere you need to configure five devices in five different ways. Two packages simplify the quandary a bit: +While these are guaranteed to work, they might map to different typefaces depending on the graphics device and operating system. Choosing any other value puts you at the mercy of the graphics device in use. We *strongly* recommend using a graphics device built with [systemfonts](https://systemfonts.r-lib.org) support because this means that you can access all fonts installed on the operating system without any additional work. For now this means using [ragg](https://ragg.r-lib.org) for raster output (PNG, JPEG, TIFF), and [svglite](https://svglite.r-lib.org) for vector output (SVG). See the [Fonts from other places](https://systemfonts.r-lib.org/articles/systemfonts.html#fonts-from-other-places) section of the systemfonts vignette to learn how to make systemfonts aware of fonts not installed on the computer. + +For now there is no PDF device with systemfonts support. If you need to create a PDF file using fonts other than the postscript fonts that `pdf()` natively support you can look into either of these packages: -* `showtext` makes GD-independent plots by rendering all text as polygons. +* `showtext` renders text as polygons by hijacking the text rendering method of the graphics device. -* `extrafont` converts fonts to a standard format that all devices can use. +* `extrafont` registers system fonts in the `pdf()` device so it can natively find them. Both approaches have pros and cons, so you will to need to try both of them and see which works best for your needs. ### Font face ```{r} -#| fig.alt: "A plot showing four text labels arranged vertically. The top +#| fig.alt: "A plot showing four text labels arranged vertically. The top #| label is 'bold.italic' and is displayed in bold and italic. The next three -#| labels are 'italic', 'bold' and 'plain' and are displayed in their +#| labels are 'italic', 'bold' and 'plain' and are displayed in their #| respective styles." df <- data.frame(x = 1:4, fontface = c("plain", "bold", "italic", "bold.italic")) -ggplot(df, aes(1, x)) + +ggplot(df, aes(1, x)) + geom_text(aes(label = fontface, fontface = fontface)) ``` +`fontface`/`face` is a catch-all argument that describes the style of the typeface to use. It can take one of 4 values: `"plain"` is an upright normal-weight font, `"italic"` is a slanted normal-weight font, `"bold"` is an upright bold-weight font, and `"bold.italic"` is a slanted bold-weight font. + +The R graphics engine does not allow you to chose other combinations of styles such as other weights or specifying width. See the [Extra font styles](https://systemfonts.r-lib.org/articles/systemfonts.html#extra-font-styles) section of the systemfonts vignette for ways to circumvent this limitation. + ### Font size The `size` of text is measured in mm by default. This is unusual, but makes the size of text consistent with the size of lines and points. Typically you specify font size using points (or pt for short), where 1 pt = 0.35mm. In `geom_text()` and `geom_label()`, you can set `size.unit = "pt"` to use points instead of millimeters. In addition, @@ -303,15 +309,15 @@ Horizontal and vertical justification have the same parameterisation, either a s ```{r} #| fig.alt: "A 3-by-3 grid of text on top of points, with horizontal text -#| justification increasing from 0 to 1 on the x-axis and vertical +#| justification increasing from 0 to 1 on the x-axis and vertical #| justification increasing from 0 to 1 on the y-axis. The points make it #| easier to see the relative placement of text." just <- expand.grid(hjust = c(0, 0.5, 1), vjust = c(0, 0.5, 1)) just$label <- paste0(just$hjust, ", ", just$vjust) ggplot(just, aes(hjust, vjust)) + - geom_point(colour = "grey70", size = 5) + + geom_point(colour = "grey70", size = 5) + geom_text(aes(label = label, hjust = hjust, vjust = vjust)) ``` -Note that you can use numbers outside the range (0, 1), but it's not recommended. +Note that you can use numbers outside the range (0, 1), but it's not recommended.