Document function type_* shortcut strings

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,

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, ...) {

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)
 #' ))

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, ...) {

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(

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)

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

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