Permalink
Browse files

Make function documentation more consistent

  • Loading branch information...
1 parent eb432b6 commit fbd7ba1da75f36dc906d74dba6a3bd60b49770b0 @hadley committed Oct 11, 2012
Showing with 293 additions and 300 deletions.
  1. +0 −2 R/ply-array.r
  2. +24 −94 R/ply-mapply.r
  3. +11 −62 R/ply-null.r
  4. +8 −0 man-roxygen/-_.r
  5. +1 −3 man-roxygen/a-.r
  6. +1 −3 man-roxygen/d-.r
  7. +2 −5 man-roxygen/l-.r
  8. +13 −0 man-roxygen/m-.r
  9. +2 −0 man-roxygen/ply.r
  10. +29 −19 man/a_ply.Rd
  11. +8 −8 man/aaply.Rd
  12. +3 −3 man/adply.Rd
  13. +3 −3 man/alply.Rd
  14. +33 −17 man/d_ply.Rd
  15. +6 −6 man/daply.Rd
  16. +3 −3 man/ddply.Rd
  17. +3 −3 man/dlply.Rd
  18. +23 −13 man/l_ply.Rd
  19. +3 −3 man/laply.Rd
  20. +3 −3 man/ldply.Rd
  21. +3 −3 man/llply.Rd
  22. +30 −13 man/m_ply.Rd
  23. +27 −11 man/maply.Rd
  24. +30 −11 man/mdply.Rd
  25. +24 −12 man/mlply.Rd
View
@@ -47,8 +47,6 @@ laply <- function(.data, .fun = NULL, ..., .progress = "none", .drop = TRUE, .p
#' variables, a formula or character vector
#' @param .drop_i should combinations of variables that do not appear in the
#' input data be preserved (FALSE) or dropped (TRUE, default)
-#' @param .parallel if \code{TRUE}, apply function in parallel, using parallel
-#' backend provided by foreach
#' @return if results are atomic with same type and dimensionality, a
#' vector, matrix or array; otherwise, a list-array (a list with
#' dimensions)
View
@@ -1,31 +1,12 @@
#' Call function with arguments in array or data frame, returning a data frame.
#'
-#' Call a multi-argument function with values taken from columns of an data frame or array, and combine results into a data frame
+#' Call a multi-argument function with values taken from columns of an
+#' data frame or array, and combine results into a data frame
#'
-#' The \code{m*ply} functions are the \code{plyr} version of \code{mapply},
-#' specialised according to the type of output they produce. These functions
-#' are just a convenient wrapper around \code{a*ply} with \code{margins = 1}
-#' and \code{.fun} wrapped in \code{\link{splat}}.
-#'
-#' This function combines the result into a data frame. If there are no
-#' results, then this function will return a data frame with zero rows and
-#' columns (\code{data.frame()}).
-#'
-#'
-#' @keywords manip
-#' @param .data matrix or data frame to use as source of arguments
-#' @param .fun function to be called with varying arguments
-#' @param ... other arguments passed on to \code{.fun}
-#' @param .expand should output be 1d (expand = FALSE), with an element for
-#' each row; or nd (expand = TRUE), with a dimension for each variable.
-#' @param .progress name of the progress bar to use, see \code{\link{create_progress_bar}}
-#' @param .parallel if \code{TRUE}, apply function in parallel, using parallel
-#' backend provided by foreach
-#' @return a data frame
+#' @template ply
+#' @template m-
+#' @template -d
#' @export
-#' @references Hadley Wickham (2011). The Split-Apply-Combine Strategy for
-#' Data Analysis. Journal of Statistical Software, 40(1), 1-29.
-#' \url{http://www.jstatsoft.org/v40/i01/}.
#' @examples
#' mdply(data.frame(mean = 1:5, sd = 1:5), rnorm, n = 2)
#' mdply(expand.grid(mean = 1:5, sd = 1:5), rnorm, n = 2)
@@ -41,70 +22,36 @@ mdply <- function(.data, .fun = NULL, ..., .expand = TRUE, .progress = "none", .
#' Call function with arguments in array or data frame, returning an array.
#'
-#' Call a multi-argument function with values taken from columns of an data frame or array, and combine results into an array
-#'
-#' The \code{m*ply} functions are the \code{plyr} version of \code{mapply},
-#' specialised according to the type of output they produce. These functions
-#' are just a convenient wrapper around \code{a*ply} with \code{margins = 1}
-#' and \code{.fun} wrapped in \code{\link{splat}}.
-#'
-#' This function combines the result into an array. If there are no results,
-#' then this function will return a vector of length 0 (\code{vector()}).
-#'
+#' Call a multi-argument function with values taken from columns of an
+#' data frame or array, and combine results into an array
#'
-#' @keywords manip
-#' @param .data matrix or data frame to use as source of arguments
-#' @param .fun function to be called with varying arguments
-#' @param ... other arguments passed on to \code{.fun}
-#' @param .expand should output be 1d (expand = FALSE), with an element for
-#' each row; or nd (expand = TRUE), with a dimension for each variable.
-#' @param .progress name of the progress bar to use, see \code{\link{create_progress_bar}}
-#' @param .parallel if \code{TRUE}, apply function in parallel, using parallel
-#' backend provided by foreach
-#' @return if results are atomic with same type and dimensionality, a vector, matrix or array; otherwise, a list-array (a list with dimensions)
+#' @template ply
+#' @template m-
+#' @template -a
#' @export
-#' @references Hadley Wickham (2011). The Split-Apply-Combine Strategy for
-#' Data Analysis. Journal of Statistical Software, 40(1), 1-29.
-#' \url{http://www.jstatsoft.org/v40/i01/}.
#' @examples
#' maply(cbind(mean = 1:5, sd = 1:5), rnorm, n = 5)
#' maply(expand.grid(mean = 1:5, sd = 1:5), rnorm, n = 5)
#' maply(cbind(1:5, 1:5), rnorm, n = 5)
-maply <- function(.data, .fun = NULL, ..., .expand = TRUE, .progress = "none", .parallel = FALSE) {
+maply <- function(.data, .fun = NULL, ..., .expand = TRUE, .progress = "none",
+ .drop = TRUE, .parallel = FALSE) {
if (is.matrix(.data) & !is.list(.data)) .data <- .matrix_to_df(.data)
f <- splat(.fun)
aaply(.data = .data, .margins = 1, .fun = f, ...,
- .expand = .expand, .progress = .progress, .parallel = .parallel)
+ .expand = .expand, .progress = .progress, .parallel = .parallel,
+ .drop = drop)
}
#' Call function with arguments in array or data frame, returning a list.
#'
-#' Call a multi-argument function with values taken from columns of an data frame or array, and combine results into a list
-#'
-#' The \code{m*ply} functions are the \code{plyr} version of \code{mapply},
-#' specialised according to the type of output they produce. These functions
-#' are just a convenient wrapper around \code{a*ply} with \code{margins = 1}
-#' and \code{.fun} wrapped in \code{\link{splat}}.
-#'
-#' This function combines the result into a list. If there are no results,
-#' then this function will return a list of length 0 (\code{list()}).
+#' Call a multi-argument function with values taken from columns of an
+#' data frame or array, and combine results into a list.
#'
-#'
-#' @keywords manip
-#' @param .data matrix or data frame to use as source of arguments
-#' @param .fun function to be called with varying arguments
-#' @param ... other arguments passed on to \code{.fun}
-#' @param .expand should output be 1d (expand = FALSE), with an element for
-#' each row; or nd (expand = TRUE), with a dimension for each variable.
-#' @param .progress name of the progress bar to use, see \code{\link{create_progress_bar}}
-#' @param .parallel if \code{TRUE}, apply function in parallel, using parallel
-#' backend provided by foreach
-#' @return list of results
+#' @template ply
+#' @template m-
+#' @template -l
#' @export
-#' @references Hadley Wickham (2011). The Split-Apply-Combine Strategy for
-#' Data Analysis. Journal of Statistical Software, 40(1), 1-29.
-#' \url{http://www.jstatsoft.org/v40/i01/}.
#' @examples
#' mlply(cbind(1:4, 4:1), rep)
#' mlply(cbind(1:4, times = 4:1), rep)
@@ -122,30 +69,13 @@ mlply <- function(.data, .fun = NULL, ..., .expand = TRUE, .progress = "none", .
#' Call function with arguments in array or data frame, discarding results.
#'
-#' Call a multi-argument function with values taken from columns of an data frame or array, and discard results
-#'
-#' The \code{m*ply} functions are the \code{plyr} version of \code{mapply},
-#' specialised according to the type of output they produce. These functions
-#' are just a convenient wrapper around \code{a*ply} with \code{margins = 1}
-#' and \code{.fun} wrapped in \code{\link{splat}}.
-#'
-#' This function combines the result into a list. If there are no results,
-#' then this function will return a list of length 0 (\code{list()}).
+#' Call a multi-argument function with values taken from columns of an
+#' data frame or array, and discard results into a list.
#'
-#' @keywords manip
-#' @param .data matrix or data frame to use as source of arguments
-#' @param .fun function to be called with varying arguments
-#' @param ... other arguments passed on to \code{.fun}
-#' @param .expand should output be 1d (expand = FALSE), with an element for
-#' each row; or nd (expand = TRUE), with a dimension for each variable.
-#' @param .progress name of the progress bar to use, see \code{\link{create_progress_bar}}
-#' @param .print automatically print each result? (default: \code{FALSE})
-#' @param .parallel if \code{TRUE}, apply function in parallel, using parallel
-#' backend provided by foreach
+#' @template ply
+#' @template m-
+#' @template -_
#' @export
-#' @references Hadley Wickham (2011). The Split-Apply-Combine Strategy for
-#' Data Analysis. Journal of Statistical Software, 40(1), 1-29.
-#' \url{http://www.jstatsoft.org/v40/i01/}.
m_ply <- function(.data, .fun = NULL, ..., .expand = TRUE, .progress = "none",
.print = FALSE, .parallel = FALSE ) {
if (is.matrix(.data) & !is.list(.data)) .data <- .matrix_to_df(.data)
View
@@ -2,24 +2,10 @@
#'
#' For each element of a list, apply function and discard results
#'
-#' All plyr functions use the same split-apply-combine strategy: they split the
-#' input into simpler pieces, apply \code{.fun} to each piece, and then combine
-#' the pieces into a single data structure. This function splits lists by
-#' elements and discards the output. This is useful for functions that you are
-#' calling purely for their side effects like display plots and saving output.
-#'
-#' @keywords manip
-#' @param .data list to be processed
-#' @param .fun function to apply to each piece
-#' @param ... other arguments passed on to \code{.fun}
-#' @param .progress name of the progress bar to use, see \code{\link{create_progress_bar}}
-#' @param .print automatically print each result? (default: \code{FALSE})
-#' @param .parallel if \code{TRUE}, apply function in parallel, using parallel
-#' backend provided by foreach
+#' @template ply
+#' @template l-
+#' @template -_
#' @export
-#' @references Hadley Wickham (2011). The Split-Apply-Combine Strategy for
-#' Data Analysis. Journal of Statistical Software, 40(1), 1-29.
-#' \url{http://www.jstatsoft.org/v40/i01/}.
l_ply <- function(.data, .fun = NULL, ..., .progress = "none", .print = FALSE,
.parallel = FALSE) {
if (is.character(.fun) || is.list(.fun)) .fun <- each(.fun)
@@ -52,31 +38,14 @@ l_ply <- function(.data, .fun = NULL, ..., .progress = "none", .print = FALSE,
#'
#' For each subset of a data frame, apply function and discard results
#'
-#' All plyr functions use the same split-apply-combine strategy: they split the
-#' input into simpler pieces, apply \code{.fun} to each piece, and then combine
-#' the pieces into a single data structure. This function splits data frames
-#' by variable and discards the output. This is useful for functions that you
-#' are calling purely for their side effects like display plots and saving
-#' output.
-#'
-#'
-#' @keywords manip
-#' @param .data data frame to be processed
-#' @param .variables variables to split data frame by, as quoted variables, a formula or character vector
-#' @param .fun function to apply to each piece
-#' @param ... other arguments passed on to \code{.fun}
-#' @param .progress name of the progress bar to use, see \code{\link{create_progress_bar}}
-#' @param .print automatically print each result? (default: \code{FALSE})
-#' @param .parallel if \code{TRUE}, apply function in parallel, using parallel
-#' backend provided by foreach
+#' @template ply
+#' @template d-
+#' @template -_
#' @export
-#' @references Hadley Wickham (2011). The Split-Apply-Combine Strategy for
-#' Data Analysis. Journal of Statistical Software, 40(1), 1-29.
-#' \url{http://www.jstatsoft.org/v40/i01/}.
d_ply <- function(.data, .variables, .fun = NULL, ..., .progress = "none",
- .print = FALSE, .parallel = FALSE) {
+ .drop = TRUE, .print = FALSE, .parallel = FALSE) {
.variables <- as.quoted(.variables)
- pieces <- splitter_d(.data, .variables)
+ pieces <- splitter_d(.data, .variables, .drop = .drop)
l_ply(.data = pieces, .fun = .fun, ...,
.progress = .progress, .print = .print, .parallel = .parallel)
@@ -86,30 +55,10 @@ d_ply <- function(.data, .variables, .fun = NULL, ..., .progress = "none",
#'
#' For each slice of an array, apply function and discard results
#'
-#' All plyr functions use the same split-apply-combine strategy: they split the
-#' input into simpler pieces, apply \code{.fun} to each piece, and then combine
-#' the pieces into a single data structure. This function splits matrices,
-#' arrays and data frames by dimensions and discards the output. This is
-#' useful for functions that you are calling purely for their side effects like
-#' display plots and saving output.
-#'
-#'
-#' @keywords manip
-#' @param .data matrix, array or data frame to be processed
-#' @param .margins a vector giving the subscripts to split up \code{data} by. 1 splits up by rows, 2 by columns and c(1,2) by rows and columns, and so on for higher dimensions
-#' @param .fun function to apply to each piece
-#' @param ... other arguments passed on to \code{.fun}
-#' @param .expand if \code{.data} is a data frame, should output be 1d
-#' (expand = FALSE), with an element for each row; or nd (expand = TRUE),
-#' with a dimension for each variable.
-#' @param .progress name of the progress bar to use, see \code{\link{create_progress_bar}}
-#' @param .print automatically print each result? (default: \code{FALSE})
-#' @param .parallel if \code{TRUE}, apply function in parallel, using parallel
-#' backend provided by foreach
+#' @template ply
+#' @template a-
+#' @template -_
#' @export
-#' @references Hadley Wickham (2011). The Split-Apply-Combine Strategy for
-#' Data Analysis. Journal of Statistical Software, 40(1), 1-29.
-#' \url{http://www.jstatsoft.org/v40/i01/}.
a_ply <- function(.data, .margins, .fun = NULL, ..., .expand = TRUE,
.progress = "none", .print = FALSE, .parallel = FALSE) {
pieces <- splitter_a(.data, .margins, .expand)
View
@@ -0,0 +1,8 @@
+#' @family no output
+#' @section Output:
+#' All output is discarded. This is useful for functions that you are
+#' calling purely for their side effects like displaying plots or
+#' saving output.
+#'
+#' @return Nothing
+#' @param .print automatically print each result? (default: \code{FALSE})
View
@@ -1,14 +1,12 @@
+#' @family array input
#' @section Input: This function splits matrices, arrays and data frames by
#' dimensions
#'
#' @param .data matrix, array or data frame to be processed
#' @param .margins a vector giving the subscripts to split up \code{data} by.
#' 1 splits up by rows, 2 by columns and c(1,2) by rows and columns, and so
#' on for higher dimensions
-#' @family array input
#' @param .expand if \code{.data} is a data frame, should output be 1d (expand
#' = FALSE), with an element for each row; or nd (expand = TRUE), with a
-#' @param .parallel if \code{TRUE}, apply function in parallel, using parallel
-#' backend provided by foreach
#' dimension for each variable.
View
@@ -1,10 +1,8 @@
+#' @family data frame input
#' @section Input: This function splits data frames by variables.
#'
#' @param .data data frame to be processed
#' @param .variables variables to split data frame by, as \code{\link{as.quoted}}
#' variables, a formula or character vector
#' @param .drop should combinations of variables that do not appear in the
#' input data be preserved (FALSE) or dropped (TRUE, default)
-#' @param .parallel if \code{TRUE}, apply function in parallel, using parallel
-#' backend provided by foreach
-#' @family data frame input
View
@@ -1,7 +1,4 @@
-#' @section Input: This function splits lists by elements and combines the
-#' result into a data frame.
+#' @family list input
+#' @section Input: This function splits lists by elements.
#'
#' @param .data list to be processed
-#' @param .parallel if \code{TRUE}, apply function in parallel, using parallel
-#' backend provided by foreach
-#' @family list input
View
@@ -0,0 +1,13 @@
+#' @details
+#' The \code{m*ply} functions are the \code{plyr} version of \code{mapply},
+#' specialised according to the type of output they produce. These functions
+#' are just a convenient wrapper around \code{a*ply} with \code{margins = 1}
+#' and \code{.fun} wrapped in \code{\link{splat}}.
+#'
+#' @family multiple arguments input
+#' @section Input: Call a multi-argument function with values taken from
+#' columns of an data frame or array
+#'
+#' @param .data matrix or data frame to use as source of arguments
+#' @param .expand should output be 1d (expand = FALSE), with an element for
+#' each row; or nd (expand = TRUE), with a dimension for each variable.
View
@@ -2,6 +2,8 @@
#' @param ... other arguments passed on to \code{.fun}
#' @param .progress name of the progress bar to use, see
#' \code{\link{create_progress_bar}}
+#' @param .parallel if \code{TRUE}, apply function in parallel, using parallel
+#' backend provided by foreach
#' @keywords manip
#' @references Hadley Wickham (2011). The Split-Apply-Combine Strategy
#' for Data Analysis. Journal of Statistical Software, 40(1), 1-29.
Oops, something went wrong.

0 comments on commit fbd7ba1

Please sign in to comment.