From 6609682cb4ece712e4d2a7841ad52ffc5362f22e Mon Sep 17 00:00:00 2001 From: Sebastian Carl Date: Thu, 15 Aug 2024 14:48:47 +0200 Subject: [PATCH] fix r-devel doc NOTEs and redocument --- R/geom_lines.R | 2 +- R/scale_nfl.R | 10 +++++----- R/theme_nfl.R | 2 +- man/geom_from_path.Rd | 24 ++++++++++++------------ man/geom_lines.Rd | 20 ++++++++++---------- man/geom_nfl_headshots.Rd | 34 +++++++++++++++++++++++++--------- man/geom_nfl_logos.Rd | 38 +++++++++++++++++++++++++++++--------- man/geom_nfl_wordmarks.Rd | 34 +++++++++++++++++++++++++--------- man/scale_axes_nfl.Rd | 7 +++---- man/scale_nfl.Rd | 8 ++------ 10 files changed, 113 insertions(+), 66 deletions(-) diff --git a/R/geom_lines.R b/R/geom_lines.R index 0e0c9d5..851a351 100644 --- a/R/geom_lines.R +++ b/R/geom_lines.R @@ -8,7 +8,7 @@ #' @inheritDotParams ggpath::geom_mean_lines #' @inheritDotParams ggpath::geom_median_lines #' -#' @seealso The underlying ggplot2 geoms [`geom_hline()`] and [`geom_vline()`] +#' @seealso The underlying ggplot2 geoms [`ggplot2::geom_hline`] and [`ggplot2::geom_vline`] #' @details These functions have been outsourced to the ggpath package. #' See [`ggpath::geom_median_lines`] and [`ggpath::geom_mean_lines`] for details. #' diff --git a/R/scale_nfl.R b/R/scale_nfl.R index cd4bed6..c7d4b74 100644 --- a/R/scale_nfl.R +++ b/R/scale_nfl.R @@ -13,8 +13,8 @@ #' values will be matched based on the names instead. Data values that don't #' match will be given `na.value`. #' @param guide A function used to create a guide or its name. If `NULL` (the default) -#' no guide will be plotted for this scale. See [ggplot2::guides()] for more information. -#' @param alpha Factor to modify color transparency via a call to [`scales::alpha()`]. +#' no guide will be plotted for this scale. See [`ggplot2::guides`] for more information. +#' @param alpha Factor to modify color transparency via a call to [`scales::alpha`]. #' If `NA` (the default) no transparency will be applied. Can also be a vector of #' alphas. All alpha levels must be in range `[0,1]`. #' @name scale_nfl @@ -121,7 +121,7 @@ scale_fill_nfl <- function(type = c("primary", "secondary"), #' available as axis labels #' @details The scale translates the NFL team abbreviations into raw image #' html and places the html as axis labels. Because of the way ggplots are -#' constructed, it is necessary to adjust the [`theme()`] after calling this +#' constructed, it is necessary to adjust the [`ggplot2::theme`] after calling this #' scale. This can be done by calling [`theme_x_nfl()`] or [`theme_y_nfl()`] #' or alternatively by manually changing the relevant `axis.text` to #' [`ggtext::element_markdown()`]. However, this will only work if an underlying @@ -131,8 +131,8 @@ scale_fill_nfl <- function(type = c("primary", "secondary"), #' and as width for an y-scale. #' @name scale_axes_nfl #' @keywords internal -#' @return A discrete ggplot2 scale created with [ggplot2::scale_x_discrete()] or -#' [ggplot2::scale_y_discrete()]. +#' @return A discrete ggplot2 scale created with [`ggplot2::scale_x_discrete`] or +#' [`ggplot2::scale_y_discrete`]. #' @aliases NULL #' @seealso [`theme_x_nfl()`], [`theme_y_nfl()`] #' @examples diff --git a/R/theme_nfl.R b/R/theme_nfl.R index 99783e1..e58e02b 100644 --- a/R/theme_nfl.R +++ b/R/theme_nfl.R @@ -13,7 +13,7 @@ #' @name theme_nfl #' @aliases NULL #' @keywords internal -#' @return A ggplot2 theme created with [ggplot2::theme()]. +#' @return A ggplot2 theme created with [`ggplot2::theme`]. #' @seealso [`theme_x_nfl()`], [`theme_y_nfl()`] #' @examples #' \donttest{ diff --git a/man/geom_from_path.Rd b/man/geom_from_path.Rd index 26f9ba3..e982bcc 100644 --- a/man/geom_from_path.Rd +++ b/man/geom_from_path.Rd @@ -66,21 +66,21 @@ See \code{\link[ggpath:geom_from_path]{ggpath::geom_from_path}} for details. \section{Aesthetics}{ -\code{geom_from_path()} understands the following aesthetics (required aesthetics have no default value): -\describe{ -\item{\code{x}}{The x-coordinate. Required.} -\item{\code{y}}{The y-coordinate. Required.} -\item{\code{path}}{a file path, url, raster object or bitmap array. See \code{\link[magick:editing]{magick::image_read()}} for further information. Required.} -\item{\code{alpha = NULL}}{The alpha channel, i.e. transparency level, as a numerical value between 0 and 1.} -\item{\code{colour = NULL}}{The image will be colorized with this colour. Use the special character \code{"b/w"} to set it to black and white. For more information on valid colour names in ggplot2 see \url{https://ggplot2.tidyverse.org/articles/ggplot2-specs.html?q=colour#colour-and-fill}} -\item{\code{angle = 0}}{The angle of the image as a numerical value between 0° and 360°.} -\item{\code{hjust = 0.5}}{The horizontal adjustment relative to the given x coordinate. Must be a numerical value between 0 and 1.} -\item{\code{vjust = 0.5}}{The vertical adjustment relative to the given y coordinate. Must be a numerical value between 0 and 1.} -\item{\code{width = 1.0}}{The desired width of the image in \code{npc} (Normalised Parent Coordinates). +\code{geom_from_path()} understands the following aesthetics (required aesthetics are in bold): +\itemize{ +\item{\strong{x}}{ - The x-coordinate.} +\item{\strong{y}}{ - The y-coordinate.} +\item{\strong{path}}{ - a file path, url, raster object or bitmap array. See \code{\link[magick:editing]{magick::image_read()}} for further information.} +\item{\code{alpha = NULL}}{ - The alpha channel, i.e. transparency level, as a numerical value between 0 and 1.} +\item{\code{colour = NULL}}{ - The image will be colorized with this colour. Use the special character \code{"b/w"} to set it to black and white. For more information on valid colour names in ggplot2 see \url{https://ggplot2.tidyverse.org/articles/ggplot2-specs.html?q=colour#colour-and-fill}} +\item{\code{angle = 0}}{ - The angle of the image as a numerical value between 0° and 360°.} +\item{\code{hjust = 0.5}}{ - The horizontal adjustment relative to the given x coordinate. Must be a numerical value between 0 and 1.} +\item{\code{vjust = 0.5}}{ - The vertical adjustment relative to the given y coordinate. Must be a numerical value between 0 and 1.} +\item{\code{width = 1.0}}{ - The desired width of the image in \code{npc} (Normalised Parent Coordinates). The default value is set to 1.0 which is \emph{big} but it is necessary because all used values are computed relative to the default. A typical size is \code{width = 0.1} (see below examples).} -\item{\code{height = 1.0}}{The desired height of the image in \code{npc} (Normalised Parent Coordinates). +\item{\code{height = 1.0}}{ - The desired height of the image in \code{npc} (Normalised Parent Coordinates). The default value is set to 1.0 which is \emph{big} but it is necessary because all used values are computed relative to the default. A typical size is \code{height = 0.1} (see below examples).} diff --git a/man/geom_lines.Rd b/man/geom_lines.Rd index 7fed0c6..7c53117 100644 --- a/man/geom_lines.Rd +++ b/man/geom_lines.Rd @@ -59,15 +59,15 @@ See \code{\link[ggpath:geom_lines]{ggpath::geom_median_lines}} and \code{\link[g \code{geom_median_lines()} and \code{geom_mean_lines()} understand the following -aesthetics (at least one of the \code{x0} or \code{y0} aesthetics is required): -\describe{ -\item{\code{x0}}{The variable for which to compute the median/mean that is drawn as vertical line.} -\item{\code{y0}}{The variable for which to compute the median/mean that is drawn as horizontal line.} -\item{\code{alpha = NA}}{The alpha channel, i.e. transparency level, as a numerical value between 0 and 1.} -\item{\code{color = "red"}}{The color of the drawn lines.} -\item{\code{linetype = 2}}{The linetype of the drawn lines.} -\item{\code{size = 0.5}}{The size of the drawn lines. Deprecated as of ggplot2 v3.4.0, use \code{linewidth} instead.} -\item{\code{linewidth = 0.5}}{The width of the drawn lines. Starting at ggplot2 v3.4.0.} +aesthetics (at least one of the bold aesthetics is required): +\itemize{ +\item{\strong{x0}}{ - The variable for which to compute the median/mean that is drawn as vertical line.} +\item{\strong{y0}}{ - The variable for which to compute the median/mean that is drawn as horizontal line.} +\item{\code{alpha = NA}}{ - The alpha channel, i.e. transparency level, as a numerical value between 0 and 1.} +\item{\code{color = "red"}}{ - The color of the drawn lines.} +\item{\code{linetype = 2}}{ - The linetype of the drawn lines.} +\item{\code{size = 0.5}}{ - The size of the drawn lines. Deprecated as of ggplot2 v3.4.0, use \code{linewidth} instead.} +\item{\code{linewidth = 0.5}}{ - The width of the drawn lines. Starting at ggplot2 v3.4.0.} } } @@ -104,5 +104,5 @@ ggplot(mtcars, aes(x = disp, y = mpg)) + theme_minimal() } \seealso{ -The underlying ggplot2 geoms \code{\link[=geom_hline]{geom_hline()}} and \code{\link[=geom_vline]{geom_vline()}} +The underlying ggplot2 geoms \code{\link[ggplot2:geom_abline]{ggplot2::geom_hline()}} and \code{\link[ggplot2:geom_abline]{ggplot2::geom_vline()}} } diff --git a/man/geom_nfl_headshots.Rd b/man/geom_nfl_headshots.Rd index 6ba013a..aaa67aa 100644 --- a/man/geom_nfl_headshots.Rd +++ b/man/geom_nfl_headshots.Rd @@ -36,15 +36,31 @@ the plot data. The return value must be a \code{data.frame}, and will be used as the layer data. A \code{function} can be created from a \code{formula} (e.g. \code{~ head(.x, 10)}).} -\item{stat}{The statistical transformation to use on the data for this -layer, either as a \code{ggproto} \code{Geom} subclass or as a string naming the -stat stripped of the \code{stat_} prefix (e.g. \code{"count"} rather than -\code{"stat_count"})} - -\item{position}{Position adjustment, either as a string naming the adjustment -(e.g. \code{"jitter"} to use \code{position_jitter}), or the result of a call to a -position adjustment function. Use the latter if you need to change the -settings of the adjustment.} +\item{stat}{The statistical transformation to use on the data for this layer. +When using a \verb{geom_*()} function to construct a layer, the \code{stat} +argument can be used the override the default coupling between geoms and +stats. The \code{stat} argument accepts the following: +\itemize{ +\item A \code{Stat} ggproto subclass, for example \code{StatCount}. +\item A string naming the stat. To give the stat as a string, strip the +function name of the \code{stat_} prefix. For example, to use \code{stat_count()}, +give the stat as \code{"count"}. +\item For more information and other ways to specify the stat, see the +\link[ggplot2:layer_stats]{layer stat} documentation. +}} + +\item{position}{A position adjustment to use on the data for this layer. This +can be used in various ways, including to prevent overplotting and +improving the display. The \code{position} argument accepts the following: +\itemize{ +\item The result of calling a position function, such as \code{position_jitter()}. +This method allows for passing extra arguments to the position. +\item A string naming the position adjustment. To give the position as a +string, strip the function name of the \code{position_} prefix. For example, +to use \code{position_jitter()}, give the position as \code{"jitter"}. +\item For more information and other ways to specify the position, see the +\link[ggplot2:layer_positions]{layer position} documentation. +}} \item{...}{Other arguments passed on to \code{\link[ggplot2:layer]{ggplot2::layer()}}. These are often aesthetics, used to set an aesthetic to a fixed value. See the below diff --git a/man/geom_nfl_logos.Rd b/man/geom_nfl_logos.Rd index 6fd1d2d..0b1d89c 100644 --- a/man/geom_nfl_logos.Rd +++ b/man/geom_nfl_logos.Rd @@ -36,15 +36,31 @@ the plot data. The return value must be a \code{data.frame}, and will be used as the layer data. A \code{function} can be created from a \code{formula} (e.g. \code{~ head(.x, 10)}).} -\item{stat}{The statistical transformation to use on the data for this -layer, either as a \code{ggproto} \code{Geom} subclass or as a string naming the -stat stripped of the \code{stat_} prefix (e.g. \code{"count"} rather than -\code{"stat_count"})} - -\item{position}{Position adjustment, either as a string naming the adjustment -(e.g. \code{"jitter"} to use \code{position_jitter}), or the result of a call to a -position adjustment function. Use the latter if you need to change the -settings of the adjustment.} +\item{stat}{The statistical transformation to use on the data for this layer. +When using a \verb{geom_*()} function to construct a layer, the \code{stat} +argument can be used the override the default coupling between geoms and +stats. The \code{stat} argument accepts the following: +\itemize{ +\item A \code{Stat} ggproto subclass, for example \code{StatCount}. +\item A string naming the stat. To give the stat as a string, strip the +function name of the \code{stat_} prefix. For example, to use \code{stat_count()}, +give the stat as \code{"count"}. +\item For more information and other ways to specify the stat, see the +\link[ggplot2:layer_stats]{layer stat} documentation. +}} + +\item{position}{A position adjustment to use on the data for this layer. This +can be used in various ways, including to prevent overplotting and +improving the display. The \code{position} argument accepts the following: +\itemize{ +\item The result of calling a position function, such as \code{position_jitter()}. +This method allows for passing extra arguments to the position. +\item A string naming the position adjustment. To give the position as a +string, strip the function name of the \code{position_} prefix. For example, +to use \code{position_jitter()}, give the position as \code{"jitter"}. +\item For more information and other ways to specify the position, see the +\link[ggplot2:layer_positions]{layer position} documentation. +}} \item{...}{Other arguments passed on to \code{\link[ggplot2:layer]{ggplot2::layer()}}. These are often aesthetics, used to set an aesthetic to a fixed value. See the below @@ -121,6 +137,7 @@ df$colour <- ifelse(matches, NA, "gray") ggplot(df, aes(x = a, y = b)) + geom_nfl_logos(aes(team_abbr = teams), width = 0.075) + geom_label(aes(label = teams), nudge_y = -0.35, alpha = 0.5) + + expand_limits(y = c(0.9, 4.1)) + theme_void() # apply alpha via an aesthetic from inside the dataset `df` @@ -129,6 +146,7 @@ ggplot(df, aes(x = a, y = b)) + ggplot(df, aes(x = a, y = b)) + geom_nfl_logos(aes(team_abbr = teams, alpha = alpha), width = 0.075) + geom_label(aes(label = teams), nudge_y = -0.35, alpha = 0.5) + + expand_limits(y = c(0.9, 4.1)) + scale_alpha_identity() + theme_void() @@ -138,6 +156,7 @@ ggplot(df, aes(x = a, y = b)) + ggplot(df, aes(x = a, y = b)) + geom_nfl_logos(aes(team_abbr = teams, alpha = alpha, colour = colour), width = 0.075) + geom_label(aes(label = teams), nudge_y = -0.35, alpha = 0.5) + + expand_limits(y = c(0.9, 4.1)) + scale_alpha_identity() + scale_color_identity() + theme_void() @@ -146,6 +165,7 @@ ggplot(df, aes(x = a, y = b)) + ggplot(df, aes(x = a, y = b)) + geom_nfl_logos(aes(team_abbr = teams), width = 0.075, alpha = 0.6) + geom_label(aes(label = teams), nudge_y = -0.35, alpha = 0.5) + + expand_limits(y = c(0.9, 4.1)) + theme_void() # it's also possible to plot NFL and conference logos diff --git a/man/geom_nfl_wordmarks.Rd b/man/geom_nfl_wordmarks.Rd index 5634255..41b2cef 100644 --- a/man/geom_nfl_wordmarks.Rd +++ b/man/geom_nfl_wordmarks.Rd @@ -36,15 +36,31 @@ the plot data. The return value must be a \code{data.frame}, and will be used as the layer data. A \code{function} can be created from a \code{formula} (e.g. \code{~ head(.x, 10)}).} -\item{stat}{The statistical transformation to use on the data for this -layer, either as a \code{ggproto} \code{Geom} subclass or as a string naming the -stat stripped of the \code{stat_} prefix (e.g. \code{"count"} rather than -\code{"stat_count"})} - -\item{position}{Position adjustment, either as a string naming the adjustment -(e.g. \code{"jitter"} to use \code{position_jitter}), or the result of a call to a -position adjustment function. Use the latter if you need to change the -settings of the adjustment.} +\item{stat}{The statistical transformation to use on the data for this layer. +When using a \verb{geom_*()} function to construct a layer, the \code{stat} +argument can be used the override the default coupling between geoms and +stats. The \code{stat} argument accepts the following: +\itemize{ +\item A \code{Stat} ggproto subclass, for example \code{StatCount}. +\item A string naming the stat. To give the stat as a string, strip the +function name of the \code{stat_} prefix. For example, to use \code{stat_count()}, +give the stat as \code{"count"}. +\item For more information and other ways to specify the stat, see the +\link[ggplot2:layer_stats]{layer stat} documentation. +}} + +\item{position}{A position adjustment to use on the data for this layer. This +can be used in various ways, including to prevent overplotting and +improving the display. The \code{position} argument accepts the following: +\itemize{ +\item The result of calling a position function, such as \code{position_jitter()}. +This method allows for passing extra arguments to the position. +\item A string naming the position adjustment. To give the position as a +string, strip the function name of the \code{position_} prefix. For example, +to use \code{position_jitter()}, give the position as \code{"jitter"}. +\item For more information and other ways to specify the position, see the +\link[ggplot2:layer_positions]{layer position} documentation. +}} \item{...}{Other arguments passed on to \code{\link[ggplot2:layer]{ggplot2::layer()}}. These are often aesthetics, used to set an aesthetic to a fixed value. See the below diff --git a/man/scale_axes_nfl.Rd b/man/scale_axes_nfl.Rd index e1108b9..29578be 100644 --- a/man/scale_axes_nfl.Rd +++ b/man/scale_axes_nfl.Rd @@ -66,7 +66,8 @@ notation. }} \item{\code{drop}}{Should unused factor levels be omitted from the scale? The default, \code{TRUE}, uses the levels that appear in the data; -\code{FALSE} uses all the levels in the factor.} +\code{FALSE} includes the levels in the factor. Please note that to display +every level in a legend, the layer should use \code{show.legend = TRUE}.} \item{\code{na.translate}}{Unlike continuous scales, discrete scales can easily show missing values, and do so by default. If you want to remove missing values from a discrete scale, specify \code{na.translate = FALSE}.} @@ -74,8 +75,6 @@ from a discrete scale, specify \code{na.translate = FALSE}.} missing values be displayed as? Does not apply to position scales where \code{NA} is always placed at the far right.} \item{\code{aesthetics}}{The names of the aesthetics that this scale works with.} - \item{\code{scale_name}}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} The name of the scale -that should be used for error messages associated with this scale.} \item{\code{labels}}{One of: \itemize{ \item \code{NULL} for no labels @@ -120,7 +119,7 @@ available as axis labels \details{ The scale translates the NFL team abbreviations into raw image html and places the html as axis labels. Because of the way ggplots are -constructed, it is necessary to adjust the \code{\link[=theme]{theme()}} after calling this +constructed, it is necessary to adjust the \code{\link[ggplot2:theme]{ggplot2::theme()}} after calling this scale. This can be done by calling \code{\link[=theme_x_nfl]{theme_x_nfl()}} or \code{\link[=theme_y_nfl]{theme_y_nfl()}} or alternatively by manually changing the relevant \code{axis.text} to \code{\link[ggtext:element_markdown]{ggtext::element_markdown()}}. However, this will only work if an underlying diff --git a/man/scale_nfl.Rd b/man/scale_nfl.Rd index 99e7390..0448d67 100644 --- a/man/scale_nfl.Rd +++ b/man/scale_nfl.Rd @@ -52,9 +52,6 @@ match will be given \code{na.value}.} \item{...}{ Arguments passed on to \code{\link[ggplot2:discrete_scale]{discrete_scale}} \describe{ - \item{\code{palette}}{A palette function that when called with a single integer -argument (the number of levels in the scale) returns the values that -they should take (e.g., \code{\link[scales:pal_hue]{scales::pal_hue()}}).} \item{\code{limits}}{One of: \itemize{ \item \code{NULL} to use the default scale values @@ -66,12 +63,11 @@ notation. }} \item{\code{drop}}{Should unused factor levels be omitted from the scale? The default, \code{TRUE}, uses the levels that appear in the data; -\code{FALSE} uses all the levels in the factor.} +\code{FALSE} includes the levels in the factor. Please note that to display +every level in a legend, the layer should use \code{show.legend = TRUE}.} \item{\code{na.translate}}{Unlike continuous scales, discrete scales can easily show missing values, and do so by default. If you want to remove missing values from a discrete scale, specify \code{na.translate = FALSE}.} - \item{\code{scale_name}}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} The name of the scale -that should be used for error messages associated with this scale.} \item{\code{name}}{The name of the scale. Used as the axis or legend title. If \code{waiver()}, the default, the name of the scale is taken from the first mapping used for that aesthetic. If \code{NULL}, the legend title will be