Merge pull request #435 from BrianDiggs/facet-grid-margins-doc

Margins option of facet_grid insufficiently documented.
Fixes #435

R/facet-grid-.r

@@ -5,7 +5,13 @@
 #'   formula is used to indicate there should be no faceting on this dimension
 #'   (either row or column). The formula can also be provided as a string
 #'   instead of a classical formula object
-#' @param margins logical value, should marginal rows and columns be displayed
+#' @param margins either a logical value or a character
+#'   vector. Margins are additional facets which contain all the data
+#'   for each of the possible values of the faceting variables. If
+#'   \code{FALSE}, no additional facets are included (the
+#'   default). If \code{TRUE}, margins are included for all faceting
+#'   variables. If specified as a character vector, it is the names of
+#'   variables for which margins are to be created.
 #' @param scales Are scales shared across all facets (the default,
 #'   \code{"fixed"}), or do they vary across rows (\code{"free_x"}),
 #'   columns (\code{"free_y"}), or both rows and columns (\code{"free"})
@@ -130,6 +136,19 @@
 #' p <- qplot(wt, mpg, data = mtcars)
 #' p + facet_grid(. ~ vs, labeller = label_bquote(alpha ^ .(x)))
 #' p + facet_grid(. ~ vs, labeller = label_bquote(.(x) ^ .(x))) 
+#'
+#' # Margins can be specified by logically (all yes or all no) or by specific
+#' # variables as (character) variable names
+#' mg <- ggplot(mtcars, aes(x = mpg, y = wt)) + geom_point()
+#' mg + facet_grid(vs + am ~ gear)
+#' mg + facet_grid(vs + am ~ gear, margins = TRUE)
+#' mg + facet_grid(vs + am ~ gear, margins = "am")
+#' # when margins are made over "vs", since the facets for "am" vary
+#' # within the values of "vs", the marginal facet for "vs" is also
+#' # a margin over "am".
+#' mg + facet_grid(vs + am ~ gear, margins = "vs")
+#' mg + facet_grid(vs + am ~ gear, margins = "gear")
+#' mg + facet_grid(vs + am ~ gear, margins = c("gear", "am"))
 #' }
 facet_grid <- function(facets, margins = FALSE, scales = "fixed", space = "fixed", shrink = TRUE, labeller = "label_value", as.table = TRUE, drop = TRUE) {
   scales <- match.arg(scales, c("fixed", "free_x", "free_y", "free"))

man/facet_grid.Rd

@@ -14,8 +14,14 @@
   (either row or column). The formula can also be provided
   as a string instead of a classical formula object}
 
-  \item{margins}{logical value, should marginal rows and
-  columns be displayed}
+  \item{margins}{either a logical value or a character
+  vector. Margins are additional facets which contain all
+  the data for each of the possible values of the faceting
+  variables. If \code{FALSE}, no additional facets are
+  included (the default). If \code{TRUE}, margins are
+  included for all faceting variables. If specified as a
+  character vector, it is the names of variables for which
+  margins are to be created.}
 
   \item{scales}{Are scales shared across all facets (the
   default, \code{"fixed"}), or do they vary across rows
@@ -153,6 +159,19 @@ k + facet_grid(. ~ cyl2, labeller = label_parsed)
 p <- qplot(wt, mpg, data = mtcars)
 p + facet_grid(. ~ vs, labeller = label_bquote(alpha ^ .(x)))
 p + facet_grid(. ~ vs, labeller = label_bquote(.(x) ^ .(x)))
+
+# Margins can be specified by logically (all yes or all no) or by specific
+# variables as (character) variable names
+mg <- ggplot(mtcars, aes(x = mpg, y = wt)) + geom_point()
+mg + facet_grid(vs + am ~ gear)
+mg + facet_grid(vs + am ~ gear, margins = TRUE)
+mg + facet_grid(vs + am ~ gear, margins = "am")
+# when margins are made over "vs", since the facets for "am" vary
+# within the values of "vs", the marginal facet for "vs" is also
+# a margin over "am".
+mg + facet_grid(vs + am ~ gear, margins = "vs")
+mg + facet_grid(vs + am ~ gear, margins = "gear")
+mg + facet_grid(vs + am ~ gear, margins = c("gear", "am"))
 }
 }