diff --git a/R/sanitize.R b/R/sanitize.R index 48a9ed5d..d51be159 100644 --- a/R/sanitize.R +++ b/R/sanitize.R @@ -38,6 +38,7 @@ sanitize_type = function(type, x, y, dots) { "segments", "spine", "spineplot", "spline", + "summary", "text", "violin", "vline" @@ -89,6 +90,7 @@ sanitize_type = function(type, x, y, dots) { "spine" = type_spineplot, "spineplot" = type_spineplot, "spline" = type_spline, + "summary" = type_summary, "text" = type_text, "violin" = type_violin, "vline" = type_vline, diff --git a/R/type_abline.R b/R/type_abline.R index 17ebb89f..1240db2a 100644 --- a/R/type_abline.R +++ b/R/type_abline.R @@ -1,12 +1,41 @@ #' Add straight lines to a plot -#' -#' @inheritParams graphics::abline +#' @description +#' These functions add straight line(s) through the current plot. +#' @details +#' Unlike most tinyplot types, `type_abline`, `type_hline`, and `type_vline` +#' cannot be called as a base plot layer. Instead they *must* called as a +#' subsequent layer via [`tinyplot_add`]. +#' +#' @param a,b the intercept (default: `a` = 0) and slope (default: `b` = 1) +#' terms. Numerics of length 1 or equal to the number of facets. #' @examples -#' mod = lm(mpg ~ hp, data = mtcars) -#' y = mtcars$mpg -#' yhat = predict(mod) -#' tinyplot(y, yhat, xlim = c(0, 40), ylim = c(0, 40)) -#' tinyplot_add(type = type_abline(a = 0, b = 1)) +#' # +#' ## abline +#' +#' tinyplot(x = -10:10, y = rnorm(21) + -10:10, grid = TRUE) +#' tinyplot_add(type = "abline") +#' # same as... +#' # tinyplot_add(type = type_abline(a = 0, b = 1)) +#' +#' # customize by passing bespoke intercept and slope values +#' tinyplot_add(type = type_abline(a = -1, b = -0.5)) +#' +#' # +#' ## hline and vline +#' +#' # Base plot layer +#' tinyplot(mpg ~ hp | cyl, facet = "by", data = mtcars, ylim = c(0, 40)) +#' +#' # Add horizontal lines at the (default) 0 y-intercept +#' tinyplot_add(type = "hline", col = "grey") +#' +#' # Note that group+facet aesthetics will be inherited. We can use this to +#' # add customized lines (here: the mean `mpg` for each `cyl` group) +#' tinyplot_add(type = type_hline(with(mtcars, tapply(mpg, cyl, mean))), lty = 2) +#' +#' # Similar idea for vline +#' tinyplot_add(type = type_vline(with(mtcars, tapply(hp, cyl, mean))), lty = 2) +#' #' @export type_abline = function(a = 0, b = 1) { data_abline = function(datapoints, ...) { diff --git a/R/type_function.R b/R/type_function.R index 1f61d3c4..e2d825b4 100644 --- a/R/type_function.R +++ b/R/type_function.R @@ -12,10 +12,11 @@ #' @importFrom stats dnorm #' #' @examples -#' # Plot the normal density -#' tinyplot(x = -4:4, type = type_function(dnorm)) +#' # Plot the normal density (default function) +#' tinyplot(x = -4:4, type = "function") +#' # tinyplot(x = -4:4, type = type_function()) # same #' -#' # Extra arguments for the function to plot +#' # Customize by passing explicit arguments to your function #' tinyplot(x = -1:10, type = type_function( #' fun = dnorm, args = list(mean = 3) #' )) diff --git a/R/type_hline.R b/R/type_hline.R index 60cab4c2..7ace5d8b 100644 --- a/R/type_hline.R +++ b/R/type_hline.R @@ -1,9 +1,6 @@ -#' Trace a horizontal line on the plot -#' -#' @param h y-value(s) for horizontal line(s). Numeric of length 1 or equal to the number of facets. -#' @examples -#' tinyplot(mpg ~ hp | factor(cyl), facet = ~ factor(cyl), data = mtcars) -#' tinyplot_add(type = type_hline(h = 12), col = "pink", lty = 3, lwd = 3) +#' @rdname type_abline +#' @param h y-value(s) for horizontal line(s). Numeric of length 1 or equal to +#' the number of facets. #' @export type_hline = function(h = 0) { data_hline = function(datapoints, ...) { diff --git a/R/type_summary.R b/R/type_summary.R index df84a61e..90d9fcdf 100644 --- a/R/type_summary.R +++ b/R/type_summary.R @@ -2,8 +2,8 @@ #' #' @md #' @description -#' Applies a summary function to `y` along unique values of `x`. This is useful, -#' say, for quickly plotting mean values of your dataset. Internally, +#' Applies a summary function to `y` along unique values of `x`. For example, +#' plot the mean `y` value for each `x` value. Internally, #' `type_summary()` applies a thin wrapper around \code{\link[stats]{ave}} and #' then passes the result to [`type_lines`] for drawing. #' @@ -15,16 +15,17 @@ #' scenes. #' @examples #' # Plot the mean chick weight over time -#' tinyplot(weight ~ Time, data = ChickWeight, type = type_summary()) +#' tinyplot(weight ~ Time, data = ChickWeight, type = "summary") #' -#' # mean is the default function, so the above is equivalent to -#' tinyplot(weight ~ Time, data = ChickWeight, type = type_summary(mean)) +#' # Note: "mean" is the default function, so these are also equivalent: +#' # tinyplot(weight ~ Time, data = ChickWeight, type = type_summary()) +#' # tinyplot(weight ~ Time, data = ChickWeight, type = type_summary(mean)) #' #' # Plot the median instead #' tinyplot(weight ~ Time, data = ChickWeight, type = type_summary(median)) #' #' # Works with groups and/or facets too -#' tinyplot(weight ~ Time | Diet, facet = "by", data = ChickWeight, type = type_summary()) +#' tinyplot(weight ~ Time | Diet, facet = "by", data = ChickWeight, type = "summary") #' #' # Custom/complex function example #' tinyplot( diff --git a/R/type_vline.R b/R/type_vline.R index 462c85b1..a922f168 100644 --- a/R/type_vline.R +++ b/R/type_vline.R @@ -1,15 +1,6 @@ -#' Trace a vertical line on the plot -#' -#' @param v x-value(s) for vertical line(s). Numeric of length 1 or equal to the number of facets. -#' @examples -#' tinyplot(mpg ~ hp, data = mtcars) -#' tinyplot_add(type = type_vline(150)) -#' -#' # facet-specify location and colors -#' cols = c("black", "green", "orange") -#' tinyplot(mpg ~ hp | factor(cyl), facet = ~ factor(cyl), data = mtcars, col = cols) -#' tinyplot_add(type = type_vline(v = c(100, 150, 200)), lty = 3, lwd = 3) -#' +#' @param v x-value(s) for vertical line(s). Numeric of length 1 or equal to the +#' number of facets. +#' @rdname type_abline #' @export type_vline = function(v = 0) { assert_numeric(v) diff --git a/altdoc/quarto_website.yml b/altdoc/quarto_website.yml index 3c17b195..0efeadbd 100644 --- a/altdoc/quarto_website.yml +++ b/altdoc/quarto_website.yml @@ -94,11 +94,11 @@ website: - text: type_function file: man/type_function.qmd - text: type_hline - file: man/type_hline.qmd + file: man/type_abline.qmd - text: type_summary file: man/type_summary.qmd - text: type_vline - file: man/type_vline.qmd + file: man/type_abline.qmd - section: "Options & Internals" contents: - text: tpar diff --git a/man/type_abline.Rd b/man/type_abline.Rd index 365ef469..f2dd4992 100644 --- a/man/type_abline.Rd +++ b/man/type_abline.Rd @@ -1,21 +1,61 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/type_abline.R +% Please edit documentation in R/type_abline.R, R/type_hline.R, R/type_vline.R \name{type_abline} \alias{type_abline} +\alias{type_hline} +\alias{type_vline} \title{Add straight lines to a plot} \usage{ type_abline(a = 0, b = 1) + +type_hline(h = 0) + +type_vline(v = 0) } \arguments{ -\item{a, b}{the intercept and slope, single values.} +\item{a, b}{the intercept (default: \code{a} = 0) and slope (default: \code{b} = 1) +terms. Numerics of length 1 or equal to the number of facets.} + +\item{h}{y-value(s) for horizontal line(s). Numeric of length 1 or equal to +the number of facets.} + +\item{v}{x-value(s) for vertical line(s). Numeric of length 1 or equal to the +number of facets.} } \description{ -Add straight lines to a plot +These functions add straight line(s) through the current plot. +} +\details{ +Unlike most tinyplot types, \code{type_abline}, \code{type_hline}, and \code{type_vline} +cannot be called as a base plot layer. Instead they \emph{must} called as a +subsequent layer via \code{\link{tinyplot_add}}. } \examples{ -mod = lm(mpg ~ hp, data = mtcars) -y = mtcars$mpg -yhat = predict(mod) -tinyplot(y, yhat, xlim = c(0, 40), ylim = c(0, 40)) -tinyplot_add(type = type_abline(a = 0, b = 1)) +# +## abline + +tinyplot(x = -10:10, y = rnorm(21) + -10:10, grid = TRUE) +tinyplot_add(type = "abline") +# same as... +# tinyplot_add(type = type_abline(a = 0, b = 1)) + +# customize by passing bespoke intercept and slope values +tinyplot_add(type = type_abline(a = -1, b = -0.5)) + +# +## hline and vline + +# Base plot layer +tinyplot(mpg ~ hp | cyl, facet = "by", data = mtcars, ylim = c(0, 40)) + +# Add horizontal lines at the (default) 0 y-intercept +tinyplot_add(type = "hline", col = "grey") + +# Note that group+facet aesthetics will be inherited. We can use this to +# add customized lines (here: the mean `mpg` for each `cyl` group) +tinyplot_add(type = type_hline(with(mtcars, tapply(mpg, cyl, mean))), lty = 2) + +# Similar idea for vline +tinyplot_add(type = type_vline(with(mtcars, tapply(hp, cyl, mean))), lty = 2) + } diff --git a/man/type_function.Rd b/man/type_function.Rd index 3e494221..cd7ec90d 100644 --- a/man/type_function.Rd +++ b/man/type_function.Rd @@ -24,10 +24,11 @@ When using \code{type_function()} in a \code{tinyplot()} call, the \code{x} valu the range of values to plot on the x-axis. } \examples{ -# Plot the normal density -tinyplot(x = -4:4, type = type_function(dnorm)) +# Plot the normal density (default function) +tinyplot(x = -4:4, type = "function") +# tinyplot(x = -4:4, type = type_function()) # same -# Extra arguments for the function to plot +# Customize by passing explicit arguments to your function tinyplot(x = -1:10, type = type_function( fun = dnorm, args = list(mean = 3) )) diff --git a/man/type_hline.Rd b/man/type_hline.Rd deleted file mode 100644 index 8e85d745..00000000 --- a/man/type_hline.Rd +++ /dev/null @@ -1,18 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/type_hline.R -\name{type_hline} -\alias{type_hline} -\title{Trace a horizontal line on the plot} -\usage{ -type_hline(h = 0) -} -\arguments{ -\item{h}{y-value(s) for horizontal line(s). Numeric of length 1 or equal to the number of facets.} -} -\description{ -Trace a horizontal line on the plot -} -\examples{ -tinyplot(mpg ~ hp | factor(cyl), facet = ~ factor(cyl), data = mtcars) -tinyplot_add(type = type_hline(h = 12), col = "pink", lty = 3, lwd = 3) -} diff --git a/man/type_lines.Rd b/man/type_lines.Rd index 8e2ee6c0..7fd54ea0 100644 --- a/man/type_lines.Rd +++ b/man/type_lines.Rd @@ -8,8 +8,9 @@ type_lines(type = "l") } \arguments{ \item{type}{1-character string giving the type of plot desired. The - following values are possible, for details, see \code{\link[graphics]{plot}}: - \code{"p"} for points, \code{"l"} for lines, + following values are possible, for details, see \code{\link[base]{plot}}: + \code{"p"} for points, + \code{"l"} for lines, \code{"b"} for both points and lines, \code{"c"} for empty points joined by lines, \code{"o"} for overplotted points and lines, diff --git a/man/type_summary.Rd b/man/type_summary.Rd index 31c14c28..3d103904 100644 --- a/man/type_summary.Rd +++ b/man/type_summary.Rd @@ -14,23 +14,24 @@ type_summary(fun = mean, ...) ex: \code{type="p"}, \code{col="pink"}.} } \description{ -Applies a summary function to \code{y} along unique values of \code{x}. This is useful, -say, for quickly plotting mean values of your dataset. Internally, +Applies a summary function to \code{y} along unique values of \code{x}. For example, +plot the mean \code{y} value for each \code{x} value. Internally, \code{type_summary()} applies a thin wrapper around \code{\link[stats]{ave}} and then passes the result to \code{\link{type_lines}} for drawing. } \examples{ # Plot the mean chick weight over time -tinyplot(weight ~ Time, data = ChickWeight, type = type_summary()) +tinyplot(weight ~ Time, data = ChickWeight, type = "summary") -# mean is the default function, so the above is equivalent to -tinyplot(weight ~ Time, data = ChickWeight, type = type_summary(mean)) +# Note: "mean" is the default function, so these are also equivalent: +# tinyplot(weight ~ Time, data = ChickWeight, type = type_summary()) +# tinyplot(weight ~ Time, data = ChickWeight, type = type_summary(mean)) # Plot the median instead tinyplot(weight ~ Time, data = ChickWeight, type = type_summary(median)) # Works with groups and/or facets too -tinyplot(weight ~ Time | Diet, facet = "by", data = ChickWeight, type = type_summary()) +tinyplot(weight ~ Time | Diet, facet = "by", data = ChickWeight, type = "summary") # Custom/complex function example tinyplot( diff --git a/man/type_vline.Rd b/man/type_vline.Rd deleted file mode 100644 index 8fb91dcd..00000000 --- a/man/type_vline.Rd +++ /dev/null @@ -1,24 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/type_vline.R -\name{type_vline} -\alias{type_vline} -\title{Trace a vertical line on the plot} -\usage{ -type_vline(v = 0) -} -\arguments{ -\item{v}{x-value(s) for vertical line(s). Numeric of length 1 or equal to the number of facets.} -} -\description{ -Trace a vertical line on the plot -} -\examples{ -tinyplot(mpg ~ hp, data = mtcars) -tinyplot_add(type = type_vline(150)) - -# facet-specify location and colors -cols = c("black", "green", "orange") -tinyplot(mpg ~ hp | factor(cyl), facet = ~ factor(cyl), data = mtcars, col = cols) -tinyplot_add(type = type_vline(v = c(100, 150, 200)), lty = 3, lwd = 3) - -} diff --git a/vignettes/types.qmd b/vignettes/types.qmd index 7940edaf..ef14ea68 100644 --- a/vignettes/types.qmd +++ b/vignettes/types.qmd @@ -102,11 +102,11 @@ a convenience string (with default behaviour) or a companion `type_*()` function | string | function | description | docs | |-----------------------|--------------------|-----------------------------------------|------| -| _(None)_ | `type_abline()` | Line(s) with intercept and slope. | [link](/man/type_abline.qmd) | -| _(None)_ | `type_hline()` | Horizontal line(s). | [link](/man/type_hline.qmd) | -| _(None)_ | `type_vline()` | Vertical line(s). | [link](/man/type_vline.qmd) | -| _(None)_ | `type_function()` | Arbitrary function. | [link](/man/type_function.qmd) | -| _(None)_ | `type_summary()` | Summarizes `y` by unique values of `x`. | [link](/man/type_summary.qmd) | +| `"abline"` | `type_abline()` | Line(s) with intercept and slope. | [link](/man/type_abline.qmd) | +| `"hline"` | `type_hline()` | Horizontal line(s). | [link](/man/type_abline.qmd) | +| `"vline"` | `type_vline()` | Vertical line(s). | [link](/man/type_abline.qmd) | +| `"function"` | `type_function()` | Arbitrary function. | [link](/man/type_function.qmd) | +| `"summary"` | `type_summary()` | Summarizes `y` by unique values of `x`. | [link](/man/type_summary.qmd) | To see the difference between the convenience strings and their respective