Miscellaneous documentation improvements

NAMESPACE

@@ -8,15 +8,23 @@ export(get_saved_par)
 export(plt)
 export(tinyplot)
 export(tpar)
+export(type_area)
 export(type_boxplot)
 export(type_errorbar)
 export(type_glm)
 export(type_hist)
 export(type_histogram)
 export(type_jitter)
+export(type_lines)
 export(type_lm)
 export(type_loess)
+export(type_pointrange)
+export(type_points)
+export(type_polygon)
 export(type_polypath)
+export(type_rect)
+export(type_ribbon)
+export(type_segments)
 export(type_spline)
 importFrom(grDevices,adjustcolor)
 importFrom(grDevices,as.raster)

NEWS.md

@@ -1,7 +1,6 @@
 # News
 
 _If you are viewing this file on CRAN, please check the
-http://www.polljunkie.com/poll/qnbeij/fini
 [latest NEWS](https://grantmcdermott.com/tinyplot/NEWS.html) on our website
 where the formatting is also better._
 

R/type_area.R

@@ -1,3 +1,5 @@
+#' @rdname type_ribbon
+#' @export
 type_area = function() {
   out = list(
     draw = NULL,

R/type_boxplot.R

@@ -1,6 +1,23 @@
 #' Boxplot type
+#' 
+#' @description Type function for producing box-and-whisker plots.
+#' Arguments are passed to \code{\link[graphics]{boxplot}}, although `tinyplot`
+#' scaffolding allows added functionality such as grouping and faceting.
 #'
 #' @inheritParams graphics::boxplot
+#' @examples
+#' # "boxplot" type convenience string
+#' tinyplot(count ~ spray, data = InsectSprays, type = "boxplot")
+#' 
+#' # Note: Specifying the type here is redundant. Like base plot, tinyplot
+#' # automatically produces a boxplot if x is a factor and y is numeric
+#' tinyplot(count ~ spray, data = InsectSprays)
+#' 
+#' # Use `type_boxplot()` to pass extra arguments for customization
+#' tinyplot(
+#'   count ~ spray, data = InsectSprays, lty = 1,
+#'   type = type_boxplot(boxwex = 0.3, staplewex = 0, outline = FALSE)
+#' )
 #' @export
 type_boxplot = function(
     range = 1.5,

R/type_errorbar.R

@@ -1,6 +1,34 @@
-#' Error bars type
-#'
+#' Error bar and pointrange plot types
+#' 
+#' @description Type function(s) for producing error bar and pointrange plots.
+#' 
 #' @inheritParams graphics::arrows
+#' @examples
+#' mod = lm(Sepal.Length ~ 0 + Sepal.Width * Species, iris)
+#' mod = lm(mpg ~ wt * factor(am), mtcars)
+#' coefs = data.frame(names(coef(mod)), coef(mod), confint(mod))
+#' colnames(coefs) = c("term", "est", "lwr", "upr")
+#' 
+#' op = tpar(pch = 19)
+#'  
+#' # "errorbar" and "pointrange" type convenience strings
+#' with(
+#'   coefs,
+#'   tinyplot(x = term, y = est, ymin = lwr, ymax = upr, type = "errorbar")
+#' )
+#' with(
+#'   coefs,
+#'   tinyplot(x = term, y = est, ymin = lwr, ymax = upr, type = "pointrange")
+#' )
+#' 
+#' # Use `type_errorbar()` to pass extra arguments for customization
+#' with(
+#'   coefs,
+#'   tinyplot(x = term, y = est, ymin = lwr, ymax = upr, type = type_errorbar(length = 0.2))
+#' )
+#' 
+#' tpar(op)
+#' 
 #' @export
 type_errorbar = function(length = 0.05) {
   out = list(

R/type_glm.R

@@ -1,10 +1,19 @@
-#' GLM type
+#' Generalized linear model plot type
+#' 
+#' @description Type function for plotting a generalized model fit.
+#' Arguments are passed to \code{\link[stats]{glm}}.
 #' 
 #' @param se logical. If TRUE, confidence intervals are drawn.
 #' @inheritParams stats::glm
 #' @inheritParams stats::predict.glm
 #' @inheritParams stats::confint
 #' @importFrom stats glm predict
+#' @examples
+#' # "glm" type convenience string
+#' tinyplot(am ~ mpg, data = mtcars, type = "glm")
+#' 
+#' # Use `type_glm()` to pass extra arguments for customization
+#' tinyplot(am ~ mpg, data = mtcars, type = type_glm(family = "binomial"))
 #' @export
 type_glm = function(family = "gaussian", se = TRUE, level = 0.95, type = "response") {
     assert_flag(se)

R/type_histogram.R

@@ -1,4 +1,4 @@
-#' Histogram type
+#' Histogram plot type
 #' 
 #' @md
 #' @description Type function for histogram plots. `type_hist` is an alias for
@@ -14,6 +14,12 @@
 #' it was larger). If breaks is a function, the x vector is supplied to it as
 #' the only argument (and the number of breaks is only limited by the amount of
 #' available memory).
+#' @examples
+#' # "histogram"/"hist" type convenience string(s)
+#' tinyplot(Nile, type = "histogram")
+#' 
+#' # Use `type_histogram()` to pass extra arguments for customization
+#' tinyplot(Nile, type = type_histogram(breaks = 30))
 #' @export
 type_histogram = function(breaks = "Sturges") {
     out = list(

R/type_jitter.R

@@ -1,6 +1,16 @@
-#' Jittered points type
+#' Jittered points plot type
+#'
+#' @description Type function for plotting jittered points.
+#' Arguments are passed to \code{\link[base]{jitter}}.
 #'
 #' @inheritParams base::jitter
+#' @inherit base::jitter details
+#' @examples
+#' # "jitter" type convenience string
+#' tinyplot(Sepal.Length ~ Species, data = iris, type = "jitter")
+#' 
+#' # Use `type_jitter()` to pass extra arguments for customization
+#' tinyplot(Sepal.Length ~ Species, data = iris, type = type_jitter(factor = 0.5))
 #' @export
 type_jitter = function(factor = 1, amount = NULL) {
   out = list(

R/type_lines.R

@@ -1,3 +1,17 @@
+#' Lines plot type
+#'
+#' @description Type function for plotting lines.
+#' 
+#' @inheritParams graphics::plot.default
+#' 
+#' @examples
+#' # "l" type convenience character string
+#' tinyplot(circumference ~ age | Tree, data = Orange, type = "l")
+#' 
+#' # Use `type_lines()` to pass extra arguments for customization
+#' tinyplot(circumference ~ age | Tree, data = Orange, type = type_lines(type = "s"))
+#' 
+#' @export
 type_lines = function(type = "l") {
   out = list(
     draw = draw_lines(type = type),

R/type_lm.R

@@ -1,7 +1,16 @@
-#' LM type
-#' 
+#' Linear model plot type
+#'
+#' @description Type function for plotting a linear model fit.
+#' Arguments are passed to \code{\link[stats]{lm}}.
+#'  
 #' @inheritParams type_glm
 #' @importFrom stats lm predict
+#' @examples
+#' # "lm" type convenience string
+#' tinyplot(dist ~ speed, data = cars, type = "lm")
+#' 
+#' # Use `type_lm()` to pass extra arguments for customization
+#' tinyplot(dist ~ speed, data = cars, type = type_lm(level = 0.9))
 #' @export
 type_lm = function(se = TRUE, level = 0.95) {
     assert_flag(se)
@@ -35,7 +44,7 @@ data_lm = function(se, level, ...) {
                 nd$ymax = p$conf.high
                 nd$ymin = p$conf.low
             } else {
-                nd$y = predict(fit, nd)
+                nd$y = predict(fit, newdata = nd)
             }
             nd
         })

R/type_loess.R

@@ -1,4 +1,4 @@
-#' Loess type
+#' Local polynomial regression plot type
 #' 
 #' @description Type function for plotting a LOESS (LOcal regrESSion) fit.
 #' Arguments are passed to \code{\link[stats]{loess}}.

R/type_pointrange.R

@@ -1,3 +1,5 @@
+#' @rdname type_errorbar
+#' @export
 type_pointrange = function() {
   out = list(
     draw = draw_pointrange(),

R/type_points.R

@@ -1,3 +1,19 @@
+#' Points plot type
+#'
+#' @description Type function for plotting points, i.e. a scatter plot.
+#' 
+#' @examples
+#' # "p" type convenience character string
+#' tinyplot(dist ~ speed, data = cars, type = "p")
+#' 
+#' # Same result with type_points()
+#' tinyplot(dist ~ speed, data = cars, type = type_points())
+#' 
+#' # Note: Specifying the type here is redundant. Like base plot, tinyplot
+#' # automatically produces a scatter plot if x and y are numeric
+#' tinyplot(dist ~ speed, data = cars)
+#' 
+#' @export
 type_points = function() {
   out = list(
     draw = draw_points(),

R/type_polygon.R

@@ -1,6 +1,21 @@
-type_polygon = function() {
+#' Polygon plot type
+#'
+#' @description Type function for plotting polygons.
+#' Arguments are passed to \code{\link[graphics]{polygon}}.
+#' 
+#' @inheritParams graphics::polygon
+#' 
+#' @examples
+#' # "polygon" type convenience character string
+#' tinyplot(1:9, c(2,1,2,1,NA,2,1,2,1), type = "polygon")
+#' 
+#' # Use `type_polygon()` to pass extra arguments for customization
+#' tinyplot(1:9, c(2,1,2,1,NA,2,1,2,1), type = type_polygon(density = c(10, 20)))
+#' 
+#' @export
+type_polygon = function(density = NULL, angle = 45) {
   out = list(
-    draw = draw_polygon(),
+    draw = draw_polygon(density = density, angle = angle),
     data = NULL,
     name = "polygon"
   )
@@ -9,15 +24,17 @@ type_polygon = function() {
 }
 
 
-draw_polygon = function() {
+draw_polygon = function(density = density, angle = 45) {
     fun = function(ix, iy, icol, ibg, ilty = par("lty"), ilwd = par("lwd"), ...) {
         polygon(
             x = ix,
             y = iy,
             border = icol,
             col = ibg,
             lty = ilty,
-            lwd = ilwd
+            lwd = ilwd,
+            density = density,
+            angle = angle
         )
     }
     return(fun)

R/type_polypath.R

@@ -1,6 +1,24 @@
-#' Polypath type
+#' Polypath polygon type
+#' 
+#' @description Type function for plotting polygons.
+#' Arguments are passed to \code{\link[graphics]{polypath}}.
 #' 
 #' @inheritParams graphics::polypath
+#' 
+#' @examples
+#' # "polypath" type convenience character string
+#' tinyplot(
+#'     c(.1, .1, .6, .6, NA, .4, .4, .9, .9),
+#'     c(.1, .6, .6, .1, NA, .4, .9, .9, .4),
+#'     type = "polypath", fill = "grey"
+#' )
+#' 
+#' # Use `type_polypath()` to pass extra arguments for customization
+#' tinyplot(
+#'     c(.1, .1, .6, .6, NA, .4, .4, .9, .9),
+#'     c(.1, .6, .6, .1, NA, .4, .9, .9, .4),
+#'     type = type_polypath(rule = "evenodd"), fill = "grey"
+#' )
 #' @export
 type_polypath = function(rule = "winding") {
     draw_polypath = function() {

R/type_rect.R

@@ -1,3 +1,29 @@
+#' Rectangle plot type
+#'
+#' @description Type function for plotting rectangles.
+#' 
+#' @details Contrary to base \code{\link[graphics]{rect}}, rectangles in
+#' [tinyplot] must be specified using the `xmin`, `ymin`,`xmax`, and `ymax`
+#' arguments. 
+#' 
+#' @examples
+#' i = 4*(0:10)
+#' 
+#' # "rect" type convenience character string
+#' tinyplot(
+#'   xmin = 100+i, ymin = 300+i, xmax = 150+i, ymax = 380+i,
+#'   by = i, fill = 0.2,
+#'   type = "rect"
+#' )
+#' 
+#' # Same result with type_rect()
+#' tinyplot(
+#'   xmin = 100+i, ymin = 300+i, xmax = 150+i, ymax = 380+i,
+#'   by = i, fill = 0.2,
+#'   type = type_rect()
+#' )
+#' 
+#' @export
 type_rect = function() {
   out = list(
     draw = draw_rect(),

R/type_ribbon.R

@@ -1,3 +1,38 @@
+#' Ribbon and area plot types
+#' 
+#' @description Type constructor functions for producing polygon ribbons, which 
+#' define a `y` interval (usually spanning from `ymin` to `ymax`) for each
+#' `x` value. Area plots are a special case of ribbon plot where `ymin` is
+#' set to 0 and `ymax` is set to `y`.
+#' 
+#' @examples
+#' x = 1:100/10
+#' y = sin(x)
+#' 
+#' #
+#' ## Ribbon plots
+#' 
+#' # "ribbon" convenience string
+#' tinyplot(x = x, ymin = y-1, ymax = y+1, type = "ribbon")
+
+#' # Same result with type_ribbon()
+#' tinyplot(x = x, ymin = y-1, ymax = y+1, type = type_ribbon())
+#' 
+#' # y will be added as a line if it is specified
+#' tinyplot(x = x, y = y, ymin = y-1, ymax = y+1, type = "ribbon")
+#'
+#' #
+#' ## Area plots
+#'   
+#' # "area" type convenience string
+#' tinyplot(x, y, type = "area")
+#' 
+#' # Same result with type_area()
+#' tinyplot(x, y, type = type_area())
+#' 
+#' # Area plots are often used for time series charts
+#' tinyplot(AirPassengers, type = "area")
+#' @export
 type_ribbon = function() {
   out = list(
     draw = draw_ribbon(),

R/type_segments.R

@@ -1,3 +1,25 @@
+#' Line segments plot type
+#'
+#' @description Type function for plotting line segments.
+#' 
+#' @details Contrary to base \code{\link[graphics]{segments}}, line segments in
+#' [tinyplot] must be specified using the `xmin`, `ymin`,`xmax`, and `ymax`
+#' arguments. 
+#' 
+#' @examples
+#' # "segments" type convenience character string
+#' tinyplot(
+#'   xmin = c(0,.1), ymin = c(.2,1), xmax = c(1,.9), ymax = c(.75,0),
+#'   type = "segments"
+#' )
+#' 
+#' # Same result with type_segments()
+#' tinyplot(
+#'   xmin = c(0,.1), ymin = c(.2,1), xmax = c(1,.9), ymax = c(.75,0),
+#'   type = type_segments()
+#' )
+#' 
+#' @export
 type_segments = function() {
   out = list(
     draw = draw_segments(),