man/..Rd man/.matrix_to_df.Rd man/[.indexed.Rd man/[.split.Rd man/[[.indexed_array.Rd man/[[.indexed_df.Rd man/a_ply.Rd man/aaply.Rd man/adply.Rd man/alply.Rd man/amv_dim.Rd man/amv_dimnames.Rd man/arrange.Rd man/as.data.frame.function.Rd man/as.list.indexed.Rd man/as.list.split.Rd man/as.quoted.NULL.Rd man/as.quoted.Rd man/as.quoted.call.Rd man/as.quoted.character.Rd man/as.quoted.formula.Rd man/as.quoted.numeric.Rd man/as.quoted.quoted.Rd man/as_df.Rd man/c.quoted.Rd man/catcolwise.Rd man/colwise.Rd man/compact.Rd man/copy_rownames.Rd man/create_progress_bar.Rd man/d_ply.Rd man/daply.Rd man/ddply.Rd man/defaults.Rd man/dims.Rd man/dlply.Rd man/each.Rd man/end_iteration.Rd man/eval.quoted.Rd man/failwith.Rd man/icanhasnext.Rd man/indexed_array.Rd man/indexed_df.Rd man/is.discrete.Rd man/is.formula.Rd man/is.iterator.Rd man/iteration_has_ended.Rd man/join.Rd man/join.keys.Rd man/l_ply.Rd man/laply.Rd man/ldply.Rd man/length.indexed.Rd man/length.indexed_array.Rd man/liply.Rd man/list_to_array.Rd man/list_to_dataframe.Rd man/list_to_vector.Rd man/llply.Rd man/m_ply.Rd man/maply.Rd man/mdply.Rd man/mlply.Rd man/names.indexed.Rd man/names.indexed_array.Rd man/names.quoted.Rd man/new_iterator.Rd man/ninteraction.Rd man/numcolwise.Rd man/nunique.Rd man/print.indexed.Rd man/print.quoted.Rd man/print.split.Rd man/progress_none.Rd man/progress_text.Rd man/progress_tk.Rd man/progress_win.Rd man/quickdf.Rd man/r_ply.Rd man/raply.Rd man/rbind.fill.Rd man/rdply.Rd man/reduce_dim.Rd man/rlply.Rd man/splat.Rd man/split_labels.Rd man/splitter_a.Rd man/splitter_d.Rd man/summarise.Rd man/true.Rd man/tryNULL.Rd man/try_default.Rd man/tryapply.Rd man/unrowname.Rd @@ -4,9 +4,24 @@ Title: Tools for splitting, applying and combining data Version: 0.1.10 Author: Hadley Wickham <h.wickham@gmail.com> Maintainer: Hadley Wickham <h.wickham@gmail.com> -Description: plyr is a set of tools that solves a common set of problems: you need to break a big problem down into manageable pieces, operate on each pieces and then put all the pieces back together. For example, you might want to fit a model to each spatial location or time point in your study, summarise data by panels or collapse high-dimensional arrays to simpler summary statistics. +Description: plyr is a set of tools that solves a common set of + problems: you need to break a big problem down into manageable + pieces, operate on each pieces and then put all the pieces back + together. For example, you might want to fit a model to each + spatial location or time point in your study, summarise data by + panels or collapse high-dimensional arrays to simpler summary + statistics. URL: http://had.co.nz/plyr Depends: R (>= 2.8) -Suggests: abind, tcltk -License: R -LazyData: true \ No newline at end of file +Suggests: RUnit, abind, tcltk +License: GPL +LazyData: true +Collate: 'dimensions.r' 'helper-arrange.r' 'helper-col-wise.r' + 'helper-data-frame.r' 'helper-defaults.r' 'helper-each.r' + 'helper-splat.r' 'helper-summarise.r' 'helper-try.r' + 'indexed-array.r' 'indexed-data-frame.r' 'indexed.r' 'iterator.r' + 'join.r' 'ninteraction.r' 'ply-array.r' 'ply-data-frame.r' + 'ply-iterator.r' 'ply-list.r' 'ply-mapply.r' 'ply-null.r' + 'ply-replicate.r' 'progress.r' 'quote.r' 'rbind.r' + 'simplify-array.r' 'simplify-data-frame.r' 'simplify-vector.r' + 'split-array.r' 'split-data-frame.r' 'split.r' 'utils.r' DESCRIPTION @@ -1,27 +1,27 @@ -# Number of dimensions -# Number of dimensions of an array or vector -# -# @arguments array -# @keyword internal +#' Number of dimensions +#' Number of dimensions of an array or vector +#' +#' @param x array +#' @keywords internal dims <- function(x) length(amv_dim(x)) -# Dimensions -# Consistent dimensions for vectors, matrices and arrays. -# -# @arguments array, matrix or vector -# @keyword internal +#' Dimensions +#' Consistent dimensions for vectors, matrices and arrays. +#' +#' @param x array, matrix or vector +#' @keywords internal amv_dim <- function(x) if (is.vector(x)) length(x) else dim(x) -# Dimension names -# Consistent dimnames for vectors, matrices and arrays. -# -# Unlike \code{\link{dimnames}} no part of the output will ever be -# null. If a component of dimnames is omitted, \code{amv_dimnames} -# will return an integer sequence of the appropriate length. -# -# @arguments array, matrix or vector -# @keyword internal +#' Dimension names +#' Consistent dimnames for vectors, matrices and arrays. +#' +#' Unlike \code{\link{dimnames}} no part of the output will ever be +#' null. If a component of dimnames is omitted, \code{amv_dimnames} +#' will return an integer sequence of the appropriate length. +#' +#' @param x array, matrix or vector +#' @keywords internal amv_dimnames <- function(x) { d <- if (is.vector(x)) list(names(x)) else dimnames(x) @@ -33,11 +33,11 @@ amv_dimnames <- function(x) { d } -# Reduce dimensions -# Remove extraneous dimensions -# -# @arguments array -# @keyword internal +#' Reduce dimensions +#' Remove extraneous dimensions +#' +#' @arguments array +#' @keyword internal reduce_dim <- function(x) { do.call("[", c(list(x), lapply(dim(x), function(x) if (x==1) 1 else T), drop=TRUE)) } R/dimensions.r @@ -1,43 +1,44 @@ -# Column-wise function -# Turn a function that operates on a vector into a function that operates column-wise on a data.frame -# -# \code{catcolwise} and \code{numcolwise} provide version that only operate -# on discrete and numeric variables respectively -# -# @arguments function -# @arguments either function that tests columns for inclusion, or a quoted object giving which columns to process -# @alias catcolwise -# @alias numcolwise -#X # Count number of missing values -#X nmissing <- function(x) sum(is.na(x)) -#X -#X # Apply to every column in a data frame -#X colwise(nmissing)(baseball) -#X # This syntax looks a little different. It is shorthand for the -#X # the following: -#X f <- colwise(nmissing) -#X f(baseball) -#X -#X # This is particularly useful in conjunction with d*ply -#X ddply(baseball, .(year), colwise(nmissing)) -#X -#X # To operate only on specified columns, supply them as the second -#X # argument. Many different forms are accepted. -#X ddply(baseball, .(year), colwise(nmissing, .(sb, cs, so))) -#X ddply(baseball, .(year), colwise(nmissing, c("sb", "cs", "so"))) -#X ddply(baseball, .(year), colwise(nmissing, ~ sb + cs + so)) -#X -#X # Alternatively, you can specify a boolean function that determines -#X # whether or not a column should be included -#X ddply(baseball, .(year), colwise(nmissing, is.character)) -#X ddply(baseball, .(year), colwise(nmissing, is.numeric)) -#X ddply(baseball, .(year), colwise(nmissing, is.discrete)) -#X -#X # These last two cases are particularly common, so some shortcuts are -#X # provided: -#X ddply(baseball, .(year), numcolwise(nmissing)) -#X ddply(baseball, .(year), catcolwise(nmissing)) -colwise <- function(.fun, .cols = function(x) TRUE) { +#' Column-wise function. +#' Turn a function that operates on a vector into a function that operates +#' column-wise on a data.frame. +#' +#' \code{catcolwise} and \code{numcolwise} provide version that only operate +#' on discrete and numeric variables respectively. +#' +#' @param .fun function +#' @param .cols either function that tests columns for inclusion, or a quoted object giving which columns to process +#' @aliases colwise catcolwise numcolwise +#' @examples +#' # Count number of missing values +#' nmissing <- function(x) sum(is.na(x)) +#' +#' # Apply to every column in a data frame +#' colwise(nmissing)(baseball) +#' # This syntax looks a little different. It is shorthand for the +#' # the following: +#' f <- colwise(nmissing) +#' f(baseball) +#' +#' # This is particularly useful in conjunction with d*ply +#' ddply(baseball, .(year), colwise(nmissing)) +#' +#' # To operate only on specified columns, supply them as the second +#' # argument. Many different forms are accepted. +#' ddply(baseball, .(year), colwise(nmissing, .(sb, cs, so))) +#' ddply(baseball, .(year), colwise(nmissing, c("sb", "cs", "so"))) +#' ddply(baseball, .(year), colwise(nmissing, ~ sb + cs + so)) +#' +#' # Alternatively, you can specify a boolean function that determines +#' # whether or not a column should be included +#' ddply(baseball, .(year), colwise(nmissing, is.character)) +#' ddply(baseball, .(year), colwise(nmissing, is.numeric)) +#' ddply(baseball, .(year), colwise(nmissing, is.discrete)) +#' +#' # These last two cases are particularly common, so some shortcuts are +#' # provided: +#' ddply(baseball, .(year), numcolwise(nmissing)) +#' ddply(baseball, .(year), catcolwise(nmissing)) +colwise <- function(.fun, .cols = true) { if (!is.function(.cols)) { .cols <- as.quoted(.cols) filter <- function(df) as.data.frame(eval.quoted(.cols, df)) @@ -63,3 +64,5 @@ numcolwise <- function(.fun, .try = FALSE) { colwise(.fun, is.numeric) } + +true <- function(x) TRUE \ No newline at end of file R/helper-col-wise.r @@ -1,12 +1,14 @@ -# Make a function return a data frame -# Create a new function that returns the existing function wrapped in a data.frame -# -# This is useful when calling \code{*dply} functions with a function that -# returns a vector, and you want the output in rows, rather than columns -# -# @keyword manip -# @argument function to make return a data frame -# @argument other arguments necessary to match the generic, but not used +#' Make a function return a data frame +#' Create a new function that returns the existing function wrapped in a data.frame +#' +#' This is useful when calling \code{*dply} functions with a function that +#' returns a vector, and you want the output in rows, rather than columns +#' +#' @keywords manip +#' @param x function to make return a data frame +#' @param row.names necessary to match the generic, but not used +#' @param optional necessary to match the generic, but not used +#' @param ... necessary to match the generic, but not used as.data.frame.function <- function(x, row.names, optional, ...) { name <- deparse(substitute(x)) function(...) data.frame(value = x(...)) R/helper-data-frame.r @@ -1,10 +1,9 @@ - -# Set defaults -# Convient method for combining a list of values with their defaults. -# -# @arguments list of values -# @arguments defaults -# @keyword manip +#' Set defaults +#' Convient method for combining a list of values with their defaults. +#' +#' @param x list of values +#' @param y defaults +#' @keywords manip defaults <- function(x, y) { c(x, y[setdiff(names(y), names(x))]) } R/helper-defaults.r @@ -1,15 +1,16 @@ -# Aggregate multiple functions into a single function -# Combine multiple functions to a single function returning a named vector of outputs -# -# Each function should produce a single number as output -# -# @arguments functions to combine -# @keyword manip -#X each(min, max)(1:10) -#X each("min", "max")(1:10) -#X each(c("min", "max"))(1:10) -#X each(c(min, max))(1:10) -#X each(length, mean, var)(rnorm(100)) +#' Aggregate multiple functions into a single function +#' Combine multiple functions to a single function returning a named vector of outputs +#' +#' Each function should produce a single number as output +#' +#' @param ... functions to combine +#' @keywords manip +#' @examples +#' each(min, max)(1:10) +#' each("min", "max")(1:10) +#' each(c("min", "max"))(1:10) +#' each(c(min, max))(1:10) +#' each(length, mean, var)(rnorm(100)) each <- function(...) { fnames <- laply(match.call()[-1], deparse) fs <- list(...) R/helper-each.r @@ -1,18 +1,18 @@ -# `Splat' arguments to a function -# Wraps a function in do.call -# -# This is useful when you want to pass a function a row of data frame or -# array, and don't want to manually pull it apart in your function. -# -# @arguments function to splat -# @value a function -# -#X hp_per_cyl <- function(hp, cyl, ...) hp / cyl -#X splat(hp_per_cyl)(mtcars[1,]) -#X splat(hp_per_cyl)(mtcars) -#X -#X f <- function(mpg, wt, ...) data.frame(mw = mpg / wt) -#X ddply(mtcars, .(cyl), splat(f)) +#' `Splat' arguments to a function +#' Wraps a function in do.call +#' +#' This is useful when you want to pass a function a row of data frame or +#' array, and don't want to manually pull it apart in your function. +#' +#' @param flat function to splat +#' @return a function +#' @examples +#' hp_per_cyl <- function(hp, cyl, ...) hp / cyl +#' splat(hp_per_cyl)(mtcars[1,]) +#' splat(hp_per_cyl)(mtcars) +#' +#' f <- function(mpg, wt, ...) data.frame(mw = mpg / wt) +#' ddply(mtcars, .(cyl), splat(f)) splat <- function(flat) { function(args, ...) { do.call(flat, c(args, list(...))) R/helper-splat.r @@ -1,32 +1,29 @@ -# Summarise a data frame. -# Create a new data frame that summarises an existing data frame. -# -# Summarise works in an analagous way to transform, except instead of adding -# columns to an existing data frame, it creates a new one. This is -# particularly useful in conjunction with \code{\link{ddply}} as it makes it -# easy to perform group-wise summaries. -# -# @arguments The data frame to be summarised -# @arguments Further arguments of the form var = value -# @keyword manip -# @alias summarize -#X summarise(baseball, -#X duration = max(year) - min(year), -#X nteams = length(unique(team))) -#X ddply(baseball, "id", summarise, -#X duration = max(year) - min(year), -#X nteams = length(unique(team))) +#' Summarise a data frame. +#' Create a new data frame that summarises an existing data frame. +#' +#' Summarise works in an analagous way to transform, except instead of adding +#' columns to an existing data frame, it creates a new one. This is +#' particularly useful in conjunction with \code{\link{ddply}} as it makes it +#' easy to perform group-wise summaries. +#' +#' @param .data the data frame to be summarised +#' @param ... further arguments of the form var = value +#' @keywords manip +#' @aliases summarise summarize +#' @examples +#' summarise(baseball, +#' duration = max(year) - min(year), +#' nteams = length(unique(team))) +#' ddply(baseball, "id", summarise, +#' duration = max(year) - min(year), +#' nteams = length(unique(team))) summarise <- function(.data, ...) { as.data.frame(eval(substitute(list(...)), .data, parent.frame())) } summarize <- summarise -# Alternative names: tally? sketch? abstract? abbreviate? - - -# system.time(ddply(baseball, "id", summarise, duration = max(year) - min(year), nteams = length(unique(team)))) quickdf <- function(list) { structure(list, class = "data.frame", row.names = seq_along(list[[1]])) -} \ No newline at end of file +} R/helper-summarise.r @@ -1,37 +1,39 @@ -# Fail with -# Modify a function so that it returns a default value when there is an error. -# -# @arguments default value -# @arguments function -# @argument should all error messages be suppressed? -# @value a function -# @seealso \code{\link{try_default}} -# @keyword debugging -#X f <- function(x) if (x == 1) stop("Error!") else 1 -#X \dontrun{ -#X f(1) -#X f(2) -#X } -#X -#X safef <- failwith(NULL, f) -#X safef(1) -#X safef(2) +#' Fail with +#' Modify a function so that it returns a default value when there is an error. +#' +#' @param default default value +#' @param f function +#' @param quiet all error messages be suppressed? +#' @return a function +#' @seealso \code{\link{try_default}} +#' @keywords debugging +#' @examples +#' f <- function(x) if (x == 1) stop("Error!") else 1 +#' \dontrun{ +#' f(1) +#' f(2) +#' } +#' +#' safef <- failwith(NULL, f) +#' safef(1) +#' safef(2) failwith <- function(default = NULL, f, quiet = FALSE) { f <- match.fun(f) function(...) try_default(f(...), default, quiet = quiet) } -# Try, with default in case of error -# \code{try_default} wraps try so that it returns a default value in the case of error. -# -# \code{tryNULL} provides a useful special case when dealing with lists. -# -# @alias tryNULL -# @arguments expression to try -# @arguments default value in case of error -# @keyword internal -# @seealso \code{\link{tryapply}} -try_default <- function(expr, default = NA, quiet = FALSE) { +#' Try, with default in case of error. +#' \code{try_default} wraps try so that it returns a default value in the case of error. +#' +#' \code{tryNULL} provides a useful special case when dealing with lists. +#' +#' @param expr expression to try +#' @param default default value in case of error +#' @param quiet should errors be printed (TRUE) or ignored (FALSE, default) +#' @aliases try_default tryNULL +#' @keywords internal +#' @seealso \code{\link{tryapply}} +try_default <- function(expr, default, quiet = FALSE) { result <- default if (quiet) { tryCatch(result <- expr, error = function(e) {}) @@ -43,10 +45,10 @@ try_default <- function(expr, default = NA, quiet = FALSE) { tryNULL <- function(expr) try_default(expr, NULL, quiet = TRUE) -# Apply with built in try -# Uses compact, lapply and tryNULL -# -# @keyword internal +#' Apply with built in try +#' Uses compact, lapply and tryNULL +#' +#' @keywords internal tryapply <- function(list, fun, ...) { compact(lapply(list, function(x) tryNULL(fun(x, ...)))) } \ No newline at end of file R/helper-try.r @@ -1,12 +1,11 @@ -# An indexed array -# Create a indexed array, a space efficient way of indexing into a large array -# -# @arguments environment containing data frame -# @argument list of indices -# @keyword internal -# @alias [[.indexed_array -# @alias names.indexed_array -# @alias length.indexed_array +#' An indexed array +#' Create a indexed array, a space efficient way of indexing into a large array +#' +#' @param env environment containing data frame +#' @param index list of indices +#' @keywords internal +#' @aliases indexex_array [[.indexed_array names.indexed_array +#' length.indexed_array indexed_array <- function(env, index) { exact <- all(laply(index, is.numeric)) R/indexed-array.r @@ -1,15 +1,11 @@ -# An indexed list -# Create a indexed list, a space efficient way of indexing into a large data frame -# -# @arguments environment containing data frame -# @argument list of indices -# @keyword internal -# @alias length.indexed -# @alias names.indexed -# @alias as.list.indexed -# @alias [[.indexed_df -# @alias [.indexed -# @alias print.indexed +#' An indexed list +#' Create a indexed list, a space efficient way of indexing into a large data frame +#' +#' @param env environment containing data frame +#' @param index list of indices +#' @keywords internal +#' @aliases indexed_df length.indexed names.indexed as.list.indexed +#' [[.indexed_df [.indexed print.indexed indexed_df <- function(env, index) { structure( list(env = env, index = index), R/indexed-data-frame.r @@ -1,4 +1,3 @@ -library(iterators) icanhasnext <- function(iterator) { # If already has hasNext function return iterator unchanged if (!is.null(iterator$hasNext)) return(iterator) R/iterator.r @@ -1,37 +1,12 @@ -# bsmall <- subset(baseball, id %in% sample(unique(baseball$id), 10))[, 1:5] -# bsmall$id <- factor(bsmall$id) -# bsmall <- bsmall[with(bsmall, order(id, year, stint)), ] -# bsmall <- bsmall[sample(rownames(bsmall)), ] -# rownames(bsmall) <- NULL - -# first <- ddply(baseball, "id", summarise, first = min(year)) -# system.time(b2 <- merge(baseball, first, by = "id", all.x = T)) -# system.time(b3 <- join(baseball, first, by = "id")) -# -# b2 <- arrange(b2, id, year, stint) -# b3 <- arrange(b3, id, year, stint) -# rownames(b2) <- NULL -# rownames(b3) <- NULL -# all.equal(b2, b3) - -# -# geo1 <- merge(sales, ad, by = c("street", "city", "zip"), all.x = TRUE) -# geo1 <- arrange(geo1, zip, city, street, date) -# rownames(geo1) <- NULL -# -# geo2 <- join(sales, ad, by = c("street", "city", "zip")) -# geo2 <- arrange(geo2, zip, city, street, date) -# rownames(geo2) <- NULL -# -# system.time(join(sales, ad, by = c("street", "city", "zip"))) -# -# all.equal(geo1, geo2) - - -# Join -# -# Unlike merge, preserves the order of x no matter what join type is used. -# If needed, rows from y will be added to the bottom. +#' Join +#' +#' Unlike merge, preserves the order of x no matter what join type is used. +#' If needed, rows from y will be added to the bottom. +#' +#' @examples +#' first <- ddply(baseball, "id", summarise, first = min(year)) +#' system.time(b2 <- merge(baseball, first, by = "id", all.x = T)) +#' system.time(b3 <- join(baseball, first, by = "id")) join <- function(x, y, by = intersect(names(x), names(y)), type = "left") { type <- match.arg(type, c("left", "right", "inner", "full")) @@ -68,11 +43,6 @@ join <- function(x, y, by = intersect(names(x), names(y)), type = "left") { } } -copy_rownames <- function(to, from) { - rownames(to) <- rownames(from) - to -} - join.keys <- function(x, y, by) { joint <- rbind.fill(x[by], y[by]) R/join.r @@ -1,7 +1,9 @@ -# Numerical interaction -# A purely numerical interaction function that powers \code{aaply}. -# -# @keyword internal +#' Numerical interaction +#' A purely numerical interaction function that powers \code{aaply}. +#' +#' @param .variables list of variables +#' @param drop drop unusued factor levels? +#' @keywords internal ninteraction <- function(.variables, drop = FALSE) { if (length(.variables) == 0) { res <- structure(rep.int(1L, nrow(.variables)), n = 1L) @@ -48,11 +50,11 @@ ninteraction <- function(.variables, drop = FALSE) { res } -# Number of unique values -# Calculate number of unique values of a variable as efficiently as possible. -# -# @arguments vector -# @keyword internal +#' Number of unique values +#' Calculate number of unique values of a variable as efficiently as possible. +#' +#' @param x vector +#' @keywords internal nunique <- function(x) { if (is.factor(x)) { length(levels(x)) R/ninteraction.r @@ -1,33 +1,34 @@ -# Split list, apply function, and return results in an array -# For each element of a list, apply function then combine results into an array -# -# 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 combines the result into an array. If there are no results, -# then this function will return a vector of length 0 (\code{vector()}). -# -# \code{laply} is very similar in spirit to \code{\link{sapply}} except that -# it will always return an array, and the output is transposed with respect -# \code{sapply} - each element of the list corresponds to a column, not a -# row. -# -# -# @keyword manip -# @arguments input list -# @arguments function to apply to each piece -# @arguments other arguments passed on to \code{.fun} -# @arguments name of the progress bar to use, see \code{\link{create_progress_bar}} -# @arguments should extra dimensions of length 1 be dropped, simplifying the output. Defaults to \code{TRUE} -# @value if results are atomic with same type and dimensionality, a vector, matrix or array; otherwise, a list-array (a list with dimensions) -#X laply(baseball, is.factor) -#X # cf -#X ldply(baseball, is.factor) -#X colwise(is.factor)(baseball) -#X -#X laply(seq_len(10), identity) -#X laply(seq_len(10), rep, times = 4) -#X laply(seq_len(10), matrix, nrow = 2, ncol = 2) +#' Split list, apply function, and return results in an array +#' For each element of a list, apply function then combine results into an array +#' +#' 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 combines the result into an array. If there are no results, +#' then this function will return a vector of length 0 (\code{vector()}). +#' +#' \code{laply} is very similar in spirit to \code{\link{sapply}} except that +#' it will always return an array, and the output is transposed with respect +#' \code{sapply} - each element of the list corresponds to a column, not a +#' row. +#' +#' +#' @keywords manip +#' @param .data input list +#' @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 .drop should extra dimensions of length 1 be dropped, simplifying the output. Defaults to \code{TRUE} +#' @return if results are atomic with same type and dimensionality, a vector, matrix or array; otherwise, a list-array (a list with dimensions) +#' @examples +#' laply(baseball, is.factor) +#' # cf +#' ldply(baseball, is.factor) +#' colwise(is.factor)(baseball) +#' +#' laply(seq_len(10), identity) +#' laply(seq_len(10), rep, times = 4) +#' laply(seq_len(10), matrix, nrow = 2, ncol = 2) laply <- function(.data, .fun = NULL, ..., .progress = "none", .drop = TRUE) { if (is.character(.fun)) .fun <- do.call("each", as.list(.fun)) if (!is.function(.fun)) stop(".fun is not a function.") @@ -39,34 +40,34 @@ laply <- function(.data, .fun = NULL, ..., .progress = "none", .drop = TRUE) { } -# Split data frame, apply function, and return results in an array -# For each subset of data frame, apply function then combine results into an array -# -# 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 combines the result into an array. If there are no results, -# then this function will return a vector of length 0 (\code{vector()}). -# -# \code{daply} with a function that operates column-wise is similar to -# \code{\link{aggregate}}. -# -# @keyword manip -# @arguments data frame to be processed -# @arguments variables to split data frame by, as quoted variables, a formula or character vector -# @arguments function to apply to each piece -# @arguments other arguments passed on to \code{.fun} -# @arguments name of the progress bar to use, see \code{\link{create_progress_bar}} -# @arguments should extra dimensions of length 1 be dropped, simplifying the output. Defaults to \code{TRUE} -# @value if results are atomic with same type and dimensionality, a vector, matrix or array; otherwise, a list-array (a list with dimensions) -#X daply(baseball, .(year), nrow) -#X -#X # Several different ways of summarising by variables that should not be -#X # included in the summary -#X -#X daply(baseball[, c(2, 6:9)], .(year), mean) -#X daply(baseball[, 6:9], .(baseball$year), mean) -#X daply(baseball, .(year), function(df) mean(df[, 6:9])) +#' Split data frame, apply function, and return results in an array +#' For each subset of data frame, apply function then combine results into an array +#' +#' 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 combines the result into an array. If there are no results, +#' then this function will return a vector of length 0 (\code{vector()}). +#' +#' \code{daply} with a function that operates column-wise is similar to +#' \code{\link{aggregate}}. +#' +#' @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 .drop should extra dimensions of length 1 be dropped, simplifying the output. Defaults to \code{TRUE} +#' @return if results are atomic with same type and dimensionality, a vector, matrix or array; otherwise, a list-array (a list with dimensions) +#' daply(baseball, .(year), nrow) +#' +#' # Several different ways of summarising by variables that should not be +#' # included in the summary +#' +#' daply(baseball[, c(2, 6:9)], .(year), mean) +#' daply(baseball[, 6:9], .(baseball$year), mean) +#' daply(baseball, .(year), function(df) mean(df[, 6:9])) daply <- function(.data, .variables, .fun = NULL, ..., .progress = "none", .drop = TRUE) { .data <- as.data.frame(.data) .variables <- as.quoted(.variables) @@ -75,47 +76,47 @@ daply <- function(.data, .variables, .fun = NULL, ..., .progress = "none", .drop laply(.data = pieces, .fun = .fun, ..., .progress = .progress, .drop = .drop) } -# Split array, apply function, and return results in an array -# For each slice of an array, apply function then combine results into an array -# -# 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 combines the result into an array. -# If there are no results, then this function will return a vector of length 0 (\code{vector()}). -# -# This function is very similar to \code{\link{apply}}, except that it will -# always return an array, and when the function returns >1 d data structures, -# those dimensions are added on to the highest dimensions, rather than the -# lowest dimensions. This makes \code{aaply} idempotent, so that -# \code{apply(input, X, identity)} is equivalent to \code{aperm(input, X)}. -# -# -# @keyword manip -# @arguments matrix, array or data frame to be processed -# @arguments 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 -# @arguments function to apply to each piece -# @arguments other arguments passed on to \code{.fun} -# @arguments name of the progress bar to use, see \code{\link{create_progress_bar}} -# @arguments should extra dimensions of length 1 be dropped, simplifying the output. Defaults to \code{TRUE} -# @value if results are atomic with same type and dimensionality, a vector, matrix or array; otherwise, a list-array (a list with dimensions) -#X dim(ozone) -#X aaply(ozone, 1, mean) -#X aaply(ozone, 1, mean, .drop = FALSE) -#X aaply(ozone, 3, mean) -#X aaply(ozone, c(1,2), mean) -#X -#X dim(aaply(ozone, c(1,2), mean)) -#X dim(aaply(ozone, c(1,2), mean, .drop = FALSE)) -#X -#X aaply(ozone, 1, each(min, max)) -#X aaply(ozone, 3, each(min, max)) -#X -#X standardise <- function(x) (x - min(x)) / (max(x) - min(x)) -#X aaply(ozone, 3, standardise) -#X aaply(ozone, 1:2, standardise) -#X -#X aaply(ozone, 1:2, diff) +#' Split array, apply function, and return results in an array +#' For each slice of an array, apply function then combine results into an array +#' +#' 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 combines the result into an array. +#' If there are no results, then this function will return a vector of length 0 (\code{vector()}). +#' +#' This function is very similar to \code{\link{apply}}, except that it will +#' always return an array, and when the function returns >1 d data structures, +#' those dimensions are added on to the highest dimensions, rather than the +#' lowest dimensions. This makes \code{aaply} idempotent, so that +#' \code{apply(input, X, identity)} is equivalent to \code{aperm(input, X)}. +#' +#' +#' @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 .progress name of the progress bar to use, see \code{\link{create_progress_bar}} +#' @param .drop should extra dimensions of length 1 be dropped, simplifying the output. Defaults to \code{TRUE} +#' @return if results are atomic with same type and dimensionality, a vector, matrix or array; otherwise, a list-array (a list with dimensions) +#' dim(ozone) +#' aaply(ozone, 1, mean) +#' aaply(ozone, 1, mean, .drop = FALSE) +#' aaply(ozone, 3, mean) +#' aaply(ozone, c(1,2), mean) +#' +#' dim(aaply(ozone, c(1,2), mean)) +#' dim(aaply(ozone, c(1,2), mean, .drop = FALSE)) +#' +#' aaply(ozone, 1, each(min, max)) +#' aaply(ozone, 3, each(min, max)) +#' +#' standardise <- function(x) (x - min(x)) / (max(x) - min(x)) +#' aaply(ozone, 3, standardise) +#' aaply(ozone, 1:2, standardise) +#' +#' aaply(ozone, 1:2, diff) aaply <- function(.data, .margins, .fun = NULL, ..., .progress = "none", .drop = TRUE) { pieces <- splitter_a(.data, .margins) R/ply-array.r @@ -1,26 +1,26 @@ -# Split list, apply function, and return results in a data frame -# For each element of a list, apply function then combine results into a data frame -# -# 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 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()}). -# -# The most unambiguous behaviour is achieved when \code{.fun} returns a -# data frame - in that case pieces will be combined with -# \code{\link{rbind.fill}}. If \code{.fun} returns an atomic vector of fixed -# length, it will be \code{rbind}ed together and converted to a data frame. -# Any other values will result in an error. -# -# -# @keyword manip -# @arguments list to be processed -# @arguments function to apply to each piece -# @arguments other arguments passed on to \code{.fun} -# @arguments name of the progress bar to use, see \code{\link{create_progress_bar}} -# @value a data frame +#' Split list, apply function, and return results in a data frame +#' For each element of a list, apply function then combine results into a data frame +#' +#' 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 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()}). +#' +#' The most unambiguous behaviour is achieved when \code{.fun} returns a +#' data frame - in that case pieces will be combined with +#' \code{\link{rbind.fill}}. If \code{.fun} returns an atomic vector of fixed +#' length, it will be \code{rbind}ed together and converted to a data frame. +#' Any other values will result in an error. +#' +#' +#' @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}} +#' @return a data frame ldply <- function(.data, .fun = NULL, ..., .progress = "none") { if (!inherits(.data, "split")) .data <- as.list(.data) res <- llply(.data = .data, .fun = .fun, ..., .progress = .progress) @@ -28,40 +28,41 @@ ldply <- function(.data, .fun = NULL, ..., .progress = "none") { list_to_dataframe(res, attr(.data, "split_labels")) } -# Split data frame, apply function, and return results in a data frame -# For each subset of a data frame, apply function then combine results into a data frame -# -# 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 variables and 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()}). -# -# The most unambiguous behaviour is achieved when \code{.fun} returns a -# data frame - in that case pieces will be combined with -# \code{\link{rbind.fill}}. If \code{.fun} returns an atomic vector of fixed -# length, it will be \code{rbind}ed together and converted to a data frame. -# Any other values will result in an error. -# -# -# @keyword manip -# @arguments data frame to be processed -# @arguments variables to split data frame by, as quoted variables, a formula or character vector -# @arguments function to apply to each piece -# @arguments other arguments passed on to \code{.fun} -# @arguments name of the progress bar to use, see \code{\link{create_progress_bar}} -# @value a data frame -#X ddply(baseball, .(year), "nrow") -#X ddply(baseball, .(lg), c("nrow", "ncol")) -#X -#X rbi <- ddply(baseball, .(year), summarise, -#X mean_rbi = mean(rbi, na.rm = TRUE)) -#X with(rbi, plot(year, mean_rbi, type="l")) -#X -#X base2 <- ddply(baseball, .(id), transform, -#X career_year = year - min(year) + 1 -#X ) +#' Split data frame, apply function, and return results in a data frame +#' For each subset of a data frame, apply function then combine results into a data frame +#' +#' 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 variables and 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()}). +#' +#' The most unambiguous behaviour is achieved when \code{.fun} returns a +#' data frame - in that case pieces will be combined with +#' \code{\link{rbind.fill}}. If \code{.fun} returns an atomic vector of fixed +#' length, it will be \code{rbind}ed together and converted to a data frame. +#' Any other values will result in an error. +#' +#' +#' @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}} +#' @return a data frame +#' @examples +#' ddply(baseball, .(year), "nrow") +#' ddply(baseball, .(lg), c("nrow", "ncol")) +#' +#' rbi <- ddply(baseball, .(year), summarise, +#' mean_rbi = mean(rbi, na.rm = TRUE)) +#' with(rbi, plot(year, mean_rbi, type="l")) +#' +#' base2 <- ddply(baseball, .(id), transform, +#' career_year = year - min(year) + 1 +#' ) ddply <- function(.data, .variables, .fun = NULL, ..., .progress = "none", .drop = TRUE) { .data <- as.data.frame(.data) .variables <- as.quoted(.variables) @@ -70,23 +71,23 @@ ddply <- function(.data, .variables, .fun = NULL, ..., .progress = "none", .drop ldply(.data = pieces, .fun = .fun, ..., .progress = .progress) } -# Split array, apply function, and return results in a data frame -# For each slice of an array, apply function then combine results into a data frame -# -# 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 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()}). -# -# @keyword manip -# @arguments matrix, array or data frame to be processed -# @arguments 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 -# @arguments function to apply to each piece -# @arguments other arguments passed on to \code{.fun} -# @arguments name of the progress bar to use, see \code{\link{create_progress_bar}} -# @value a data frame +#' Split array, apply function, and return results in a data frame +#' For each slice of an array, apply function then combine results into a data frame +#' +#' 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 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, 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 .progress name of the progress bar to use, see \code{\link{create_progress_bar}} +#' @return a data frame adply <- function(.data, .margins, .fun = NULL, ..., .progress = "none") { pieces <- splitter_a(.data, .margins) R/ply-data-frame.r @@ -1,29 +1,30 @@ -# Split list, apply function, and return results in a list -# For each element of a list, apply function then combine results into a list -# -# 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 combines the result into a list. If there are no results, then -# this function will return a list of length 0 (\code{list()}). -# -# \code{llply} is equivalent to \code{\link{lapply}} except that it will -# preserve labels and can display a progress bar. -# -# -# @keyword manip -# @arguments list to be processed -# @arguments function to apply to each piece -# @arguments other arguments passed on to \code{.fun} -# @arguments name of the progress bar to use, see \code{\link{create_progress_bar}} -# @value list of results -#X llply(llply(mtcars, round), table) -#X llply(baseball, summary) -#X # Examples from ?lapply -#X x <- list(a = 1:10, beta = exp(-3:3), logic = c(TRUE,FALSE,FALSE,TRUE)) -#X -#X llply(x, mean) -#X llply(x, quantile, probs = 1:3/4) +#' Split list, apply function, and return results in a list +#' For each element of a list, apply function then combine results into a list +#' +#' 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 combines the result into a list. If there are no results, then +#' this function will return a list of length 0 (\code{list()}). +#' +#' \code{llply} is equivalent to \code{\link{lapply}} except that it will +#' preserve labels and can display a progress bar. +#' +#' +#' @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}} +#' @return list of results +#' @examples +#' llply(llply(mtcars, round), table) +#' llply(baseball, summary) +#' # Examples from ?lapply +#' x <- list(a = 1:10, beta = exp(-3:3), logic = c(TRUE,FALSE,FALSE,TRUE)) +#' +#' llply(x, mean) +#' llply(x, quantile, probs = 1:3/4) llply <- function(.data, .fun = NULL, ..., .progress = "none", .inform = FALSE) { pieces <- if (inherits(.data, "split")) .data else as.list(.data) if (is.null(.fun)) return(as.list(pieces)) @@ -70,34 +71,35 @@ llply <- function(.data, .fun = NULL, ..., .progress = "none", .inform = FALSE) result } -# Split data frame, apply function, and return results in a list -# For each subset of a data frame, apply function then combine results into a list -# -# 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 variables and combines the result into a list. If there are no results, -# then this function will return a list of length 0 (\code{list()}). -# -# \code{dlply} is similar to \code{\link{by}} except that the results are -# returned in a different format. -# -# -# @keyword manip -# @arguments data frame to be processed -# @arguments variables to split data frame by, as quoted variables, a formula or character vector -# @arguments function to apply to each piece -# @arguments other arguments passed on to \code{.fun} -# @arguments name of the progress bar to use, see \code{\link{create_progress_bar}} -# @value if results are atomic with same type and dimensionality, a vector, matrix or array; otherwise, a list-array (a list with dimensions) -#X linmod <- function(df) lm(rbi ~ year, data = transform(df, year = year - min(year))) -#X models <- dlply(baseball, .(id), linmod) -#X models[[1]] -#X -#X coef <- ldply(models, coef) -#X with(coef, plot(`(Intercept)`, year)) -#X qual <- laply(models, function(mod) summary(mod)$r.squared) -#X hist(qual) +#' Split data frame, apply function, and return results in a list +#' For each subset of a data frame, apply function then combine results into a list +#' +#' 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 variables and combines the result into a list. If there are no results, +#' then this function will return a list of length 0 (\code{list()}). +#' +#' \code{dlply} is similar to \code{\link{by}} except that the results are +#' returned in a different format. +#' +#' +#' @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}} +#' @return if results are atomic with same type and dimensionality, a vector, matrix or array; otherwise, a list-array (a list with dimensions) +#' @examples +#' linmod <- function(df) lm(rbi ~ year, data = transform(df, year = year - min(year))) +#' models <- dlply(baseball, .(id), linmod) +#' models[[1]] +#' +#' coef <- ldply(models, coef) +#' with(coef, plot(`(Intercept)`, year)) +#' qual <- laply(models, function(mod) summary(mod)$r.squared) +#' hist(qual) dlply <- function(.data, .variables, .fun = NULL, ..., .progress = "none", .drop = TRUE) { .data <- as.data.frame(.data) .variables <- as.quoted(.variables) @@ -106,29 +108,30 @@ dlply <- function(.data, .variables, .fun = NULL, ..., .progress = "none", .drop llply(.data = pieces, .fun = .fun, ..., .progress = .progress) } -# Split array, apply function, and return results in a list -# For each slice of an array, apply function then combine results into a list -# -# 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 combines the result into a list. -# If there are no results, then this function will return a list of length 0 -# (\code{list()}). -# -# \code{alply} is somewhat similar to \code{\link{apply}} for cases where the -# results are not atomic. -# -# -# @keyword manip -# @arguments matrix, array or data frame to be processed -# @arguments 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 -# @arguments function to apply to each piece -# @arguments other arguments passed on to \code{.fun} -# @arguments name of the progress bar to use, see \code{\link{create_progress_bar}} -# @value list of results -#X alply(ozone, 3, quantile) -#X alply(ozone, 3, function(x) table(round(x))) +#' Split array, apply function, and return results in a list +#' For each slice of an array, apply function then combine results into a list +#' +#' 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 combines the result into a list. +#' If there are no results, then this function will return a list of length 0 +#' (\code{list()}). +#' +#' \code{alply} is somewhat similar to \code{\link{apply}} for cases where the +#' results are not atomic. +#' +#' +#' @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 .progress name of the progress bar to use, see \code{\link{create_progress_bar}} +#' @return list of results +#' @examples +#' alply(ozone, 3, quantile) +#' alply(ozone, 3, function(x) table(round(x))) alply <- function(.data, .margins, .fun = NULL, ..., .progress = "none") { pieces <- splitter_a(.data, .margins) R/ply-list.r @@ -1,25 +1,25 @@ -# 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 -# -# 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()}). -# -# -# @keyword manip -# @arguments matrix or data frame to use as source of arguments -# @arguments function to be called with varying arguments -# @arguments other arguments passed on to \code{.fun} -# @arguments name of the progress bar to use, see \code{\link{create_progress_bar}} -# @value a data frame -#X mdply(data.frame(mean = 1:5, sd = 1:5), rnorm, n = 2) -#X mdply(expand.grid(mean = 1:5, sd = 1:5), rnorm, n = 2) -#X mdply(cbind(mean = 1:5, sd = 1:5), rnorm, n = 5) +#' 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 +#' +#' 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 .progress name of the progress bar to use, see \code{\link{create_progress_bar}} +#' @return a data frame +#' mdply(data.frame(mean = 1:5, sd = 1:5), rnorm, n = 2) +#' mdply(expand.grid(mean = 1:5, sd = 1:5), rnorm, n = 2) +#' mdply(cbind(mean = 1:5, sd = 1:5), rnorm, n = 5) mdply <- function(.data, .fun = NULL, ..., .progress = "none") { if (is.matrix(.data) & !is.list(.data)) .data <- .matrix_to_df(.data) @@ -27,27 +27,27 @@ mdply <- function(.data, .fun = NULL, ..., .progress = "none") { adply(.data = .data, .margins = 1, .fun = f, ..., .progress = .progress) } -# 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()}). -# -# -# @keyword manip -# @arguments matrix or data frame to use as source of arguments -# @arguments function to be called with varying arguments -# @arguments other arguments passed on to \code{.fun} -# @arguments name of the progress bar to use, see \code{\link{create_progress_bar}} -# @value if results are atomic with same type and dimensionality, a vector, matrix or array; otherwise, a list-array (a list with dimensions) -#X maply(cbind(mean = 1:5, sd = 1:5), rnorm, n = 5) -#X maply(cbind(1:5, 1:5), rnorm, n = 5) -#X maply(expand.grid(mean = 1:5, sd = 1:5), rnorm, n = 5) +#' 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()}). +#' +#' +#' @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 .progress name of the progress bar to use, see \code{\link{create_progress_bar}} +#' @return if results are atomic with same type and dimensionality, a vector, matrix or array; otherwise, a list-array (a list with dimensions) +#' maply(cbind(mean = 1:5, sd = 1:5), rnorm, n = 5) +#' maply(cbind(1:5, 1:5), rnorm, n = 5) +#' maply(expand.grid(mean = 1:5, sd = 1:5), rnorm, n = 5) maply <- function(.data, .fun = NULL, ..., .progress = "none") { if (is.matrix(.data) & !is.list(.data)) .data <- .matrix_to_df(.data) @@ -55,30 +55,31 @@ maply <- function(.data, .fun = NULL, ..., .progress = "none") { aaply(.data = .data, .margins = 1, .fun = f, ..., .progress = .progress) } -# 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()}). -# -# -# @keyword manip -# @arguments matrix or data frame to use as source of arguments -# @arguments function to be called with varying arguments -# @arguments other arguments passed on to \code{.fun} -# @arguments name of the progress bar to use, see \code{\link{create_progress_bar}} -# @value list of results -#X mlply(cbind(1:4, 4:1), rep) -#X mlply(cbind(1:4, times = 4:1), rep) -#X -#X mlply(cbind(1:4, 4:1), seq) -#X mlply(cbind(1:4, length = 4:1), seq) -#X mlply(cbind(1:4, by = 4:1), seq, to = 20) +#' 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()}). +#' +#' +#' @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 .progress name of the progress bar to use, see \code{\link{create_progress_bar}} +#' @return list of results +#' @examples +#' mlply(cbind(1:4, 4:1), rep) +#' mlply(cbind(1:4, times = 4:1), rep) +#' +#' mlply(cbind(1:4, 4:1), seq) +#' mlply(cbind(1:4, length = 4:1), seq) +#' mlply(cbind(1:4, by = 4:1), seq, to = 20) mlply <- function(.data, .fun = NULL, ..., .progress = "none") { if (is.matrix(.data) & !is.list(.data)) .data <- .matrix_to_df(.data) @@ -86,22 +87,22 @@ mlply <- function(.data, .fun = NULL, ..., .progress = "none") { alply(.data = .data, .margins = 1, .fun = f, ..., .progress = .progress) } -# 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()}). -# -# @keyword manip -# @arguments matrix or data frame to use as source of arguments -# @arguments function to be called with varying arguments -# @arguments other arguments passed on to \code{.fun} -# @arguments name of the progress bar to use, see \code{\link{create_progress_bar}} +#' 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()}). +#' +#' @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 .progress name of the progress bar to use, see \code{\link{create_progress_bar}} m_ply <- function(.data, .fun = NULL, ..., .progress = "none") { if (is.matrix(.data) & !is.list(.data)) .data <- .matrix_to_df(.data) R/ply-mapply.r @@ -1,19 +1,19 @@ -# Split list, apply function, and discard results -# 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. -# -# -# @keyword manip -# @arguments list to be processed -# @arguments function to apply to each piece -# @arguments other arguments passed on to \code{.fun} -# @arguments name of the progress bar to use, see \code{\link{create_progress_bar}} -# @argument automatically print each result? (default: \code{FALSE}) +#' Split list, apply function, and discard results +#' 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 automatically print each result? (default: \code{FALSE}) l_ply <- function(.data, .fun = NULL, ..., .progress = "none", .print = FALSE) { if (is.character(.fun)) .fun <- do.call("each", as.list(.fun)) if (!is.function(.fun)) stop(".fun is not a function.") @@ -32,24 +32,24 @@ l_ply <- function(.data, .fun = NULL, ..., .progress = "none", .print = FALSE) { invisible() } -# Split data frame, apply function, and discard results -# 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. -# -# -# @keyword manip -# @arguments data frame to be processed -# @arguments variables to split data frame by, as quoted variables, a formula or character vector -# @arguments function to apply to each piece -# @arguments other arguments passed on to \code{.fun} -# @arguments name of the progress bar to use, see \code{\link{create_progress_bar}} -# @argument automatically print each result? (default: \code{FALSE}) +#' Split data frame, apply function, and discard results +#' 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 automatically print each result? (default: \code{FALSE}) d_ply <- function(.data, .variables, .fun = NULL, ..., .progress = "none", .print = FALSE) { .data <- as.data.frame(.data) .variables <- as.quoted(.variables) @@ -58,24 +58,24 @@ d_ply <- function(.data, .variables, .fun = NULL, ..., .progress = "none", .prin l_ply(.data = pieces, .fun = .fun, ..., .progress = .progress, .print = .print) } -# Split array, apply function, and discard results -# 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. -# -# -# @keyword manip -# @arguments matrix, array or data frame to be processed -# @arguments 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 -# @arguments function to apply to each piece -# @arguments other arguments passed on to \code{.fun} -# @arguments name of the progress bar to use, see \code{\link{create_progress_bar}} -# @argument automatically print each result? (default: \code{FALSE}) +#' Split array, apply function, and discard results +#' 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 .progress name of the progress bar to use, see \code{\link{create_progress_bar}} +#' @param automatically print each result? (default: \code{FALSE}) a_ply <- function(.data, .margins, .fun = NULL, ..., .progress = "none", .print = FALSE) { pieces <- splitter_a(.data, .margins) R/ply-null.r @@ -1,20 +1,20 @@ -# Replicate expression and return results in a list -# Evalulate expression n times then combine results into a list -# -# This function runs an expression multiple times, and combines the -# result into a list. If there are no results, then this function will return -# a list of length 0 (\code{list()}). This function is equivalent to -# \code{\link{replicate}}, but will always return results as a list. -# -# -# @keyword manip -# @arguments number of times to evaluate the expression -# @arguments expression to evaluate -# @arguments name of the progress bar to use, see \code{\link{create_progress_bar}} -# @value list of results -# -#X mods <- rlply(100, lm(y ~ x, data=data.frame(x=rnorm(100), y=rnorm(100)))) -#X hist(laply(mods, function(x) summary(x)$r.squared)) +#' Replicate expression and return results in a list +#' Evalulate expression n times then combine results into a list +#' +#' This function runs an expression multiple times, and combines the +#' result into a list. If there are no results, then this function will return +#' a list of length 0 (\code{list()}). This function is equivalent to +#' \code{\link{replicate}}, but will always return results as a list. +#' +#' +#' @keywords manip +#' @param .n number of times to evaluate the expression +#' @param .expr expression to evaluate +#' @param .progress name of the progress bar to use, see \code{\link{create_progress_bar}} +#' @return list of results +#' @examples +#' mods <- rlply(100, lm(y ~ x, data=data.frame(x=rnorm(100), y=rnorm(100)))) +#' hist(laply(mods, function(x) summary(x)$r.squared)) rlply <- function(.n, .expr, .progress = "none") { if (is.function(.expr)) { f <- .expr @@ -35,25 +35,25 @@ rlply <- function(.n, .expr, .progress = "none") { result } -# Replicate expression and return results in a data frame -# Evalulate expression n times then combine results into a data frame -# -# This function runs an expression multiple times, and combines the -# result into a data frame. If there are no results, then this function -# returns a data frame with zero rows and columns (\code{data.frame()}). -# This function is equivalent to \code{\link{replicate}}, but will always -# return results as a data frame. -# -# -# @keyword manip -# @arguments number of times to evaluate the expression -# @arguments expression to evaluate -# @arguments name of the progress bar to use, see \code{\link{create_progress_bar}} -# @value a data frame -#X -#X rdply(20, mean(runif(100))) -#X rdply(20, each(mean, var)(runif(100))) -#X rdply(20, data.frame(x = runif(2))) +#' Replicate expression and return results in a data frame +#' Evalulate expression n times then combine results into a data frame +#' +#' This function runs an expression multiple times, and combines the +#' result into a data frame. If there are no results, then this function +#' returns a data frame with zero rows and columns (\code{data.frame()}). +#' This function is equivalent to \code{\link{replicate}}, but will always +#' return results as a data frame. +#' +#' +#' @keywords manip +#' @param .n number of times to evaluate the expression +#' @param .expr expression to evaluate +#' @param .progress name of the progress bar to use, see \code{\link{create_progress_bar}} +#' @return a data frame +#' @examples +#' rdply(20, mean(runif(100))) +#' rdply(20, each(mean, var)(runif(100))) +#' rdply(20, data.frame(x = runif(2))) rdply <- function(.n, .expr, .progress = "none") { if (is.function(.expr)) { f <- .expr @@ -67,32 +67,31 @@ rdply <- function(.n, .expr, .progress = "none") { } -# Replicate expression and return results in a array -# Evalulate expression n times then combine results into an array -# -# This function runs an expression multiple times, and combines the -# result into a data frame. If there are no results, then this function -# returns a vector of length 0 (\code{vector(0)}). -# This function is equivalent to \code{\link{replicate}}, but will always -# return results as a vector, matrix or array. -# -# -# @keyword manip -# @arguments number of times to evaluate the expression -# @arguments expression to evaluate -# @arguments name of the progress bar to use, see \code{\link{create_progress_bar}} -# @value if results are atomic with same type and dimensionality, a vector, matrix or array; otherwise, a list-array (a list with dimensions) -# -#X raply(100, mean(runif(100))) -#X raply(100, each(mean, var)(runif(100))) -#X -#X raply(10, runif(4)) -#X raply(10, matrix(runif(4), nrow=2)) -#X -#X # See the central limit theorem in action -#X hist(raply(1000, mean(rexp(10)))) -#X hist(raply(1000, mean(rexp(100)))) -#X hist(raply(1000, mean(rexp(1000)))) +#' Replicate expression and return results in a array +#' Evalulate expression n times then combine results into an array +#' +#' This function runs an expression multiple times, and combines the +#' result into a data frame. If there are no results, then this function +#' returns a vector of length 0 (\code{vector(0)}). +#' This function is equivalent to \code{\link{replicate}}, but will always +#' return results as a vector, matrix or array. +#' +#' @keywords manip +#' @param .n number of times to evaluate the expression +#' @param .expr expression to evaluate +#' @param .progress name of the progress bar to use, see \code{\link{create_progress_bar}} +#' @return if results are atomic with same type and dimensionality, a vector, matrix or array; otherwise, a list-array (a list with dimensions) +#' @examples +#' raply(100, mean(runif(100))) +#' raply(100, each(mean, var)(runif(100))) +#' +#' raply(10, runif(4)) +#' raply(10, matrix(runif(4), nrow=2)) +#' +#' # See the central limit theorem in action +#' hist(raply(1000, mean(rexp(10)))) +#' hist(raply(1000, mean(rexp(100)))) +#' hist(raply(1000, mean(rexp(1000)))) raply <- function(.n, .expr, .progress = "none", .drop = TRUE) { if (is.function(.expr)) { f <- .expr @@ -104,22 +103,21 @@ raply <- function(.n, .expr, .progress = "none", .drop = TRUE) { list_to_array(res, NULL, .drop) } -# Replicate expression and discard results -# Evalulate expression n times then discard results -# -# This function runs an expression multiple times, discarding the results. -# This function is equivalent to \code{\link{replicate}}, but never returns -# anything -# -# -# @keyword manip -# @arguments number of times to evaluate the expression -# @arguments expression to evaluate -# @arguments name of the progress bar to use, see \code{\link{create_progress_bar}} -# @argument automatically print each result? (default: \code{FALSE}) -# -#X r_ply(10, plot(runif(50))) -#X r_ply(25, hist(runif(1000))) +#' Replicate expression and discard results +#' Evalulate expression n times then discard results +#' +#' This function runs an expression multiple times, discarding the results. +#' This function is equivalent to \code{\link{replicate}}, but never returns +#' anything +#' +#' @keywords manip +#' @param .n number of times to evaluate the expression +#' @param .expr expression to evaluate +#' @param .progress name of the progress bar to use, see \code{\link{create_progress_bar}} +#' @param automatically print each result? (default: \code{FALSE}) +#' @examples +#' r_ply(10, plot(runif(50))) +#' r_ply(25, hist(runif(1000))) r_ply <- function(.n, .expr, .progress = "none", .print = FALSE) { if (is.function(.expr)) { f <- .expr R/ply-replicate.r @@ -1,44 +1,46 @@ -# Create progress bar -# Create progress bar object from text string. -# -# Progress bars give feedback on how apply step is proceeding. This -# is mainly useful for long running functions, as for short functions, the -# time taken up by splitting and combining may be on the same order (or -# longer) as the apply step. Additionally, for short functions, the time -# needed to update the progress bar can significantly slow down the process. -# For the trivial examples below, using the tk progress bar slows things down -# by a factor of a thousand. -# -# Note the that progress bar is approximate, and if the time taken by -# individual function applications is highly non-uniform it may not be very -# informative of the time left. -# -# There are currently four types of progress bar: "none", "text", "tk", and -# "win". See the individual documentation for more details. In plyr -# functions, these can either be specified by name, or you can create the -# progress bar object yourself if you want more control over its apperance. -# See the examples. -# -# @arguments type of progress bar to create -# @seealso \code{\link{progress_none}}, \code{\link{progress_text}}, \code{\link{progress_tk}}, \code{\link{progress_win}} -# @keyword utilities -#X l_ply(1:1000, identity, .progress = "none") -#X l_ply(1:1000, identity, .progress = "tk") -#X l_ply(1:1000, identity, .progress = "text") -#X l_ply(1:1000, identity, .progress = progress_text(char = "-")) +#' Create progress bar +#' Create progress bar object from text string. +#' +#' Progress bars give feedback on how apply step is proceeding. This +#' is mainly useful for long running functions, as for short functions, the +#' time taken up by splitting and combining may be on the same order (or +#' longer) as the apply step. Additionally, for short functions, the time +#' needed to update the progress bar can significantly slow down the process. +#' For the trivial examples below, using the tk progress bar slows things down +#' by a factor of a thousand. +#' +#' Note the that progress bar is approximate, and if the time taken by +#' individual function applications is highly non-uniform it may not be very +#' informative of the time left. +#' +#' There are currently four types of progress bar: "none", "text", "tk", and +#' "win". See the individual documentation for more details. In plyr +#' functions, these can either be specified by name, or you can create the +#' progress bar object yourself if you want more control over its apperance. +#' See the examples. +#' +#' @param name type of progress bar to create +#' @seealso \code{\link{progress_none}}, \code{\link{progress_text}}, \code{\link{progress_tk}}, \code{\link{progress_win}} +#' @keywords utilities +#' @examples +#' l_ply(1:1000, identity, .progress = "none") +#' l_ply(1:1000, identity, .progress = "tk") +#' l_ply(1:1000, identity, .progress = "text") +#' l_ply(1:1000, identity, .progress = progress_text(char = "-")) create_progress_bar <- function(name = "none") { if (!is.character(name)) return(name) match.fun(paste("progress", name, sep="_"))() } -# Null progress bar -# A progress bar that does nothing -# -# This the default progress bar used by plyr functions. It's very simple to -# understand - it does nothing! -# -# @keyword internal -#X l_ply(1:100, identity, .progress = "none") +#' Null progress bar +#' A progress bar that does nothing +#' +#' This the default progress bar used by plyr functions. It's very simple to +#' understand - it does nothing! +#' +#' @keywords internal +#' @examples +#' l_ply(1:100, identity, .progress = "none") progress_none <- function() { list( init = function(x) {}, @@ -47,16 +49,18 @@ progress_none <- function() { ) } -# Text progress bar -# A textual progress bar -# -# This progress bar displays a textual progress bar that works on all -# platforms. It is a thin wrapper around the built-in -# \code{\link{setTxtProgressBar}} and can be customised in the same way. -# -# @argument style of text bar, see Details section of \code{\link{txtProgressBar}} -#X l_ply(1:1000, identity, .progress = "text") -#X l_ply(1:1000, identity, .progress = progress_text(char = "-")) +#' Text progress bar +#' A textual progress bar +#' +#' This progress bar displays a textual progress bar that works on all +#' platforms. It is a thin wrapper around the built-in +#' \code{\link{setTxtProgressBar}} and can be customised in the same way. +#' +#' @param style style of text bar, see Details section of \code{\link{txtProgressBar}} +#' @param ... other arugments passed on to \code{\link{txtProgressBar}} +#' @examples +#' l_ply(1:1000, identity, .progress = "text") +#' l_ply(1:1000, identity, .progress = progress_text(char = "-")) progress_text <- function(style = 3, ...) { n <- 0 txt <- NULL @@ -74,18 +78,19 @@ progress_text <- function(style = 3, ...) { ) } -# Graphical progress bar, powered by Tk -# A graphical progress bar displayed in a Tk window -# -# This graphical progress will appear in a separate window. -# -# @arguments window title -# @arguments progress bar label (inside window) -# @arguments other arguments passed on to \code{\link[tcltk]{tkProgressBar}} -# @seealso \code{\link[tcltk]{tkProgressBar}} for the function that powers this progress bar -#X l_ply(1:1000, identity, .progress = "tk") -#X l_ply(1:1000, identity, .progress = progress_tk(width=400)) -#X l_ply(1:1000, identity, .progress = progress_tk(label="")) +#' Graphical progress bar, powered by Tk +#' A graphical progress bar displayed in a Tk window +#' +#' This graphical progress will appear in a separate window. +#' +#' @param title window title +#' @param lable progress bar label (inside window) +#' @param ... other arguments passed on to \code{\link[tcltk]{tkProgressBar}} +#' @seealso \code{\link[tcltk]{tkProgressBar}} for the function that powers this progress bar +#' @examples +#' l_ply(1:1000, identity, .progress = "tk") +#' l_ply(1:1000, identity, .progress = progress_tk(width=400)) +#' l_ply(1:1000, identity, .progress = progress_tk(label="")) progress_tk <- function(title = "plyr progress", label = "Working...", ...) { stopifnot(require("tcltk", quiet=TRUE)) n <- 0 @@ -104,18 +109,19 @@ progress_tk <- function(title = "plyr progress", label = "Working...", ...) { ) } -# Graphical progress bar, powered by Windows -# A graphical progress bar displayed in a separate window -# -# This graphical progress only works on Windows. -# -# @arguments window title -# @arguments other arguments passed on to \code{\link[utils]{winProgressBar}} -# @seealso \code{\link[utils]{winProgressBar}} for the function that powers this progress bar -#X if(exists("winProgressBar")) { -#X l_ply(1:1000, identity, .progress = "win") -#X l_ply(1:1000, identity, .progress = progress_win(title="Working...")) -#X } +#' Graphical progress bar, powered by Windows +#' A graphical progress bar displayed in a separate window +#' +#' This graphical progress only works on Windows. +#' +#' @param title window title +#' @param ... other arguments passed on to \code{\link[utils]{winProgressBar}} +#' @seealso \code{\link[utils]{winProgressBar}} for the function that powers this progress bar +#' @examples +#' if(exists("winProgressBar")) { +#' l_ply(1:1000, identity, .progress = "win") +#' l_ply(1:1000, identity, .progress = progress_win(title="Working...")) +#' } progress_win <- function(title = "plyr progress", ...) { n <- 0 win <- NULL R/progress.r @@ -1,51 +1,52 @@ -# Quote variables -# Create a list of unevaluated expressions for later evaluation -# -# This function is similar to \code{\link{~}} in that it is used to -# capture the name of variables, not their current value. This is used -# throughout plyr to specify the names of variables (or more complicated -# expressions). -# -# Similar tricks can be performed with \code{\link{substitute}}, but when -# functions can be called in multiple ways it becomes increasingly tricky -# to ensure that the values are extracted from the correct frame. Substitute -# tricks also make it difficult to program against the functions that use -# them, while the \code{quoted} class provides -# \code{\link{as.quoted.character}} to convert strings to the appropriate -# data structure. -# -# @arguments unevaluated expressions to be recorded. Specify names if you want the set the names of the resultant variables -# @value list of symbol and language primitives -# @alias quoted -#X .(a, b, c) -#X .(first = a, second = b, third = c) -#X .(a ^ 2, b - d, log(c)) -#X as.quoted(~ a + b + c) -#X as.quoted(a ~ b + c) -#X as.quoted(c("a", "b", "c")) -#X -#X # Some examples using ddply - look at the column names -#X ddply(mtcars, "cyl", each(nrow, ncol)) -#X ddply(mtcars, ~ cyl, each(nrow, ncol)) -#X ddply(mtcars, .(cyl), each(nrow, ncol)) -#X ddply(mtcars, .(log(cyl)), each(nrow, ncol)) -#X ddply(mtcars, .(logcyl = log(cyl)), each(nrow, ncol)) -#X ddply(mtcars, .(vs + am), each(nrow, ncol)) -#X ddply(mtcars, .(vsam = vs + am), each(nrow, ncol)) +#' Quote variables +#' Create a list of unevaluated expressions for later evaluation +#' +#' This function is similar to \code{\link{~}} in that it is used to +#' capture the name of variables, not their current value. This is used +#' throughout plyr to specify the names of variables (or more complicated +#' expressions). +#' +#' Similar tricks can be performed with \code{\link{substitute}}, but when +#' functions can be called in multiple ways it becomes increasingly tricky +#' to ensure that the values are extracted from the correct frame. Substitute +#' tricks also make it difficult to program against the functions that use +#' them, while the \code{quoted} class provides +#' \code{\link{as.quoted.character}} to convert strings to the appropriate +#' data structure. +#' +#' @param ... unevaluated expressions to be recorded. Specify names if you want the set the names of the resultant variables +#' @return list of symbol and language primitives +#' @aliases . quoted +#' @examples +#' .(a, b, c) +#' .(first = a, second = b, third = c) +#' .(a ^ 2, b - d, log(c)) +#' as.quoted(~ a + b + c) +#' as.quoted(a ~ b + c) +#' as.quoted(c("a", "b", "c")) +#' +#' # Some examples using ddply - look at the column names +#' ddply(mtcars, "cyl", each(nrow, ncol)) +#' ddply(mtcars, ~ cyl, each(nrow, ncol)) +#' ddply(mtcars, .(cyl), each(nrow, ncol)) +#' ddply(mtcars, .(log(cyl)), each(nrow, ncol)) +#' ddply(mtcars, .(logcyl = log(cyl)), each(nrow, ncol)) +#' ddply(mtcars, .(vs + am), each(nrow, ncol)) +#' ddply(mtcars, .(vsam = vs + am), each(nrow, ncol)) . <- function(...) { structure(as.list(match.call()[-1]), class="quoted") } -# Print quoted variables -# Display the \code{\link{str}}ucture of quoted variables -# -# @keyword internal +#' Print quoted variables +#' Display the \code{\link{str}}ucture of quoted variables +#' +#' @keywords internal print.quoted <- function(x, ...) str(x) -# Compute names of quoted variables -# Figure out names of quoted variables, using specified names if they exist, otherwise using \code{\link{make.names}} on the values. -# -# @keyword internal +#' Compute names of quoted variables +#' Figure out names of quoted variables, using specified names if they exist, otherwise using \code{\link{make.names}} on the values. +#' +#' @keywords internal names.quoted <- function(x) { part_names <- make.names(x) user_names <- names(unclass(x)) @@ -57,11 +58,11 @@ names.quoted <- function(x) { part_names } -# Evaluate a quoted list of variables -# Evaluates quoted variables in specified environment -# -# @value a list -# @keyword internal +#' Evaluate a quoted list of variables +#' Evaluates quoted variables in specified environment +#' +#' @return a list +#' @keywords internal eval.quoted <- function(exprs, envir = parent.frame(), enclos = if (is.list(envir) || is.pairlist(envir)) parent.frame() else baseenv()) { if (is.numeric(exprs)) return(envir[exprs]) @@ -72,27 +73,22 @@ eval.quoted <- function(exprs, envir = parent.frame(), enclos = if (is.list(env results } -# Convert input to quoted variables -# Convert characters, formulas and calls to quoted .variables -# -# This method is called by default on all plyr functions that take a -# \code{.variables} argument, so that equivalent forms can be used anywhere. -# -# Currently conversions exist for character vectors, formulas and -# call objects. -# -# @value a list of quoted variables -# @seealso \code{\link{.}} -# @alias as.quoted.call -# @alias as.quoted.character -# @alias as.quoted.formula -# @alias as.quoted.quoted -# @alias as.quoted.NULL -# @alias as.quoted.numeric -# @alias c.quoted -# @alais as.quoted.NULL -#X as.quoted(c("a", "b", "log(d)")) -#X as.quoted(a ~ b + log(d)) +#' Convert input to quoted variables +#' Convert characters, formulas and calls to quoted .variables +#' +#' This method is called by default on all plyr functions that take a +#' \code{.variables} argument, so that equivalent forms can be used anywhere. +#' +#' Currently conversions exist for character vectors, formulas and +#' call objects. +#' +#' @return a list of quoted variables +#' @seealso \code{\link{.}} +#' @aliases as.quoted.call as.quoted.character as.quoted.formula +#' as.quoted.quoted as.quoted.NULL as.quoted.numeric c.quoted as.quoted +#' @examples +#' as.quoted(c("a", "b", "log(d)")) +#' as.quoted(a ~ b + log(d)) as.quoted <- function(x) UseMethod("as.quoted") as.quoted.call <- function(x) structure(as.list(x)[-1], class="quoted") as.quoted.character <- function(x) { @@ -135,8 +131,8 @@ c.quoted <- function(..., recursive = FALSE) { structure(NextMethod("c"), class = "quoted") } -# Is a formula? -# Checks if argument is a formula -# -# @keyword internal +#' Is a formula? +#' Checks if argument is a formula +#' +#' @keywords internal is.formula <- function(x) inherits(x, "formula") R/quote.r @@ -4,8 +4,10 @@ # This is a minor enhancement to \code{\link{rbind}} which adds in columns # that are not present in all inputs. # -# @arguments data frames to row bind together -# @keyword manip +#' @param ... data frames to row bind together +#' @keywords manip +#' @examples +#' rbind.fill(mtcars[c("mpg", "wt")], mtcars[c("wt", "cyl")]) rbind.fill <- function(...) { dfs <- list(...) if (length(dfs) == 0) return(list()) @@ -63,17 +65,18 @@ rbind.fill <- function(...) { as_df(output) } -# Compact list -# Remove all NULL entries from a list -# -# @arguments list -# @keyword manip +#' Compact list +#' Remove all NULL entries from a list +#' +#' @param l list +#' @keywords manip compact <- function(l) Filter(Negate(is.null), l) -# Convert list to data frame -# Works like cbind, but crams everything into a column -# -# @keyword internal +#' Convert list to data frame +#' Works like cbind, but crams everything into a column +#' +#' @param output output list to turn into a data frame +#' @keywords internal as_df <- function(output) { if (length(output) == 0) return(data.frame()) # Convert list to data.frame R/rbind.r @@ -1,11 +1,11 @@ -# List to array -# Reduce/simplify a list of homogenous objects to an array -# -# @arguments list of input data -# @arguments a data frame of labels, one row for each element of res -# @arguments should extra dimensions be dropped (TRUE) or preserved (FALSE) -# @keyword internal +#' List to array +#' Reduce/simplify a list of homogenous objects to an array +#' +#' @param res list of input data +#' @param labels a data frame of labels, one row for each element of res +#' @param .drop should extra dimensions be dropped (TRUE) or preserved (FALSE) +#' @keywords internal list_to_array <- function(res, labels = NULL, .drop = FALSE) { if (length(res) == 0) return(vector()) n <- length(res) R/simplify-array.r @@ -1,9 +1,9 @@ -# List to data frame -# Reduce/simplify a list of homogenous objects to a data frame -# -# @arguments list of input data -# @arguments a data frame of labels, one row for each element of res -# @keyword internal +#' List to data frame +#' Reduce/simplify a list of homogenous objects to a data frame +#' +#' @param res list of input data +#' @param labels a data frame of labels, one row for each element of res +#' @keywords internal list_to_dataframe <- function(res, labels = NULL) { if (length(res) == 0) return(data.frame()) R/simplify-data-frame.r @@ -1,8 +1,8 @@ -# List to vector -# Reduce/simplify a list of homogenous objects to a vector -# -# @arguments list of input data -# @keyword internal +#' List to vector +#' Reduce/simplify a list of homogenous objects to a vector +#' +#' @param res list of input data +#' @keywords internal list_to_vector <- function(res) { n <- length(res) if (n == 0) return(vector()) R/simplify-vector.r @@ -1,26 +1,27 @@ -# Split an array by .margins -# Split a 2d or higher data structure into lower-d pieces based -# -# This is the workhorse of the \code{a*ply} functions. Given a >1 d -# data structure (matrix, array, data.frame), it splits it into pieces -# based on the subscripts that you supply. Each piece is a lower dimensional -# slice. -# -# The margins are specified in the same way as \code{\link{apply}}, but -# \code{splitter_a} just splits up the data, while \code{apply} also -# applies a function and combines the pieces back together. This function -# also includes enough information to recreate the split from attributes on -# the list of pieces. -# -# @params >1d data structure (matrix, data.frame or array) -# @params 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 -# @value a list of lower-d slices, with attributes that record split details -#X splitter_a(mtcars, 1) -#X splitter_a(mtcars, 2) -#X -#X splitter_a(ozone, 2) -#X splitter_a(ozone, 3) -#X splitter_a(ozone, 1:2) +#' Split an array by .margins +#' Split a 2d or higher data structure into lower-d pieces based +#' +#' This is the workhorse of the \code{a*ply} functions. Given a >1 d +#' data structure (matrix, array, data.frame), it splits it into pieces +#' based on the subscripts that you supply. Each piece is a lower dimensional +#' slice. +#' +#' The margins are specified in the same way as \code{\link{apply}}, but +#' \code{splitter_a} just splits up the data, while \code{apply} also +#' applies a function and combines the pieces back together. This function +#' also includes enough information to recreate the split from attributes on +#' the list of pieces. +#' +#' @param data >1d data structure (matrix, data.frame or array) +#' @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 +#' @return a list of lower-d slices, with attributes that record split details +#' @examples +#' splitter_a(mtcars, 1) +#' splitter_a(mtcars, 2) +#' +#' splitter_a(ozone, 2) +#' splitter_a(ozone, 3) +#' splitter_a(ozone, 1:2) splitter_a <- function(data, .margins = 1) { if (!all(.margins %in% seq_len(dims(data)))) stop("Invalid margin") R/split-array.r @@ -1,38 +1,41 @@ -# Split a data frame by variables -# Split a data frame into pieces based on variable contained in that data frame -# -# This is the workhorse of the \code{d*ply} functions. Based on the variables -# you supply, it breaks up a single data frame into a list of data frames, -# each containing a single combination from the levels of the specified -# variables. -# -# This is basically a thin wrapper around \code{\link{split}} which -# evaluates the variables in the context of the data, and includes enough -# information to reconstruct the labelling of the data frame after -# other operations. -# -# @seealso \code{\link{.}} for quoting variables, \code{\link{split}} -# @arguments data frame -# @arguments a \link{quoted} list of variables, a formula, or character vector -# @value a list of data.frames, with attributes that record split details -#X splitter_d(mtcars, .(cyl)) -#X splitter_d(mtcars, .(vs, am)) -#X splitter_d(mtcars, .(am, vs)) -#X -#X mtcars$cyl2 <- factor(mtcars$cyl, levels = c(2, 4, 6, 8, 10)) -#X splitter_d(mtcars, .(cyl2), drop = TRUE) -#X splitter_d(mtcars, .(cyl2), drop = FALSE) -#X -#X mtcars$cyl3 <- ifelse(mtcars$vs == 1, NA, mtcars$cyl) -#X splitter_d(mtcars, .(cyl3)) -#X splitter_d(mtcars, .(cyl3, vs)) -#X splitter_d(mtcars, .(cyl3, vs), drop = FALSE) +#' Split a data frame by variables +#' Split a data frame into pieces based on variable contained in that data frame +#' +#' This is the workhorse of the \code{d*ply} functions. Based on the variables +#' you supply, it breaks up a single data frame into a list of data frames, +#' each containing a single combination from the levels of the specified +#' variables. +#' +#' This is basically a thin wrapper around \code{\link{split}} which +#' evaluates the variables in the context of the data, and includes enough +#' information to reconstruct the labelling of the data frame after +#' other operations. +#' +#' @seealso \code{\link{.}} for quoting variables, \code{\link{split}} +#' @param data data frame +#' @param .variables a \link{quoted} list of variables, a formula, or character vector +#' @param .drop drop unnused factor levels? +#' @return a list of data.frames, with attributes that record split details +#' @examples +#' splitter_d(mtcars, .(cyl)) +#' splitter_d(mtcars, .(vs, am)) +#' splitter_d(mtcars, .(am, vs)) +#' +#' mtcars$cyl2 <- factor(mtcars$cyl, levels = c(2, 4, 6, 8, 10)) +#' splitter_d(mtcars, .(cyl2), drop = TRUE) +#' splitter_d(mtcars, .(cyl2), drop = FALSE) +#' +#' mtcars$cyl3 <- ifelse(mtcars$vs == 1, NA, mtcars$cyl) +#' splitter_d(mtcars, .(cyl3)) +#' splitter_d(mtcars, .(cyl3, vs)) +#' splitter_d(mtcars, .(cyl3, vs), drop = FALSE) splitter_d <- function(data, .variables = NULL, drop = TRUE) { splits <- eval.quoted(.variables, data, parent.frame()) splitv <- ninteraction(splits, drop = drop) split_labels <- split_labels(splits, drop = drop) + browser() index <- tapply(1:nrow(data), splitv, list) if (!drop) { @@ -54,12 +57,12 @@ splitter_d <- function(data, .variables = NULL, drop = TRUE) { ) } -# Generate labels for split data frame -# Create data frame giving labels for split data frame. -# -# @arguments list of variables to split up by -# @argument whether all possible combinations should be considered, or only those present in the data -# @keyword internal +#' Generate labels for split data frame +#' Create data frame giving labels for split data frame. +#' +#' @param list of variables to split up by +#' @param whether all possible combinations should be considered, or only those present in the data +#' @keywords internal split_labels <- function(splits, drop) { if (drop) { R/split-data-frame.r @@ -1,8 +1,11 @@ -# Subset splits -# Subset splits, ensuring that labels keep matching -# -# @keyword internal +#' Subset splits +#' Subset splits, ensuring that labels keep matching +#' +#' @keywords internal +#' @param x split object +#' @param i index +#' @param ... unused "[.split" <- function(x, i, ...) { structure( NextMethod(), @@ -12,10 +15,12 @@ ) } -# Convert split list to regular list -# Strip off label related attributed to make a strip list as regular list -# -# @keyword internal +#' Convert split list to regular list +#' Strip off label related attributed to make a strip list as regular list +#' +#' @keywords internal +#' @param x object to convert to a list +#' @param ... unused as.list.split <- function(x, ...) { attr(x, "split_type") <- NULL attr(x, "split_labels") <- NULL @@ -23,10 +28,12 @@ as.list.split <- function(x, ...) { x } -# Print split -# Don't print labels, so it appears like a regular list -# -# @keyword internal +#' Print split +#' Don't print labels, so it appears like a regular list +#' +#' @keywords internal +#' @param x object to print +#' @param ... unused print.split <- function(x, ...) { print(as.list(x)) } \ No newline at end of file R/split.r @@ -1,28 +1,20 @@ -# Determine if a vector is discrete -# A discrete vector is a factor or a character vector -# -# @arguments vector to test -# @keyword internal -#X is.discrete(1:10) -#X is.discrete(c("a", "b", "c")) -#X is.discrete(factor(c("a", "b", "c"))) +#' Determine if a vector is discrete +#' A discrete vector is a factor or a character vector +#' +#' @param x vector to test +#' @keywords internal +#' @examples +#' is.discrete(1:10) +#' is.discrete(c("a", "b", "c")) +#' is.discrete(factor(c("a", "b", "c"))) is.discrete <- function(x) is.factor(x) || is.character(x) || is.logical(x) -# Un-rowname -# Strip rownames from an object -# -# @keyword internal +#' Un-rowname +#' Strip rownames from an object +#' +#' @keywords internal +#' @param x data frame unrowname <- function(x) { rownames(x) <- NULL x } - -# Reorder character -# Make it possible to reorder character vectors -# -# Should be removed once this is built into R. -# -# @keyword internal -reorder.character <- function(x, X, FUN = mean, ...) { - reorder(factor(x), X = X, FUN = FUN, ...) -} \ No newline at end of file R/utils.r @@ -20,19 +20,19 @@ a list of length 0 (\code{list()}). See \code{vignette("intro", "plyr")} for more details, description and case studies. -@keyword manip +@keywords manip -@arguments matrix, array or data frame to be processed -@arguments list to be processed -@arguments data frame to be processed +@param matrix, array or data frame to be processed +@param list to be processed +@param data frame to be processed -@arguments variables to split data frame by, as quoted variables, a formula or character vector -@arguments 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 variables to split data frame by, as quoted variables, a formula or character vector +@param 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 -@arguments function to apply to each piece -@arguments other arguments passed on to \code{.fun} -@arguments name of the progress bar to use, see \code{\link{create_progress_bar}} +@param function to apply to each piece +@param other arguments passed on to \code{.fun} +@param name of the progress bar to use, see \code{\link{create_progress_bar}} -@value if results are atomic with same type and dimensionality, a vector, matrix or array; otherwise, a list-array (a list with dimensions) -@value list of results -@value a data frame +@return if results are atomic with same type and dimensionality, a vector, matrix or array; otherwise, a list-array (a list with dimensions) +@return list of results +@return a data frame plyr-doc.txt NAMESPACE man/a-ply-2j.rd man/aaply-ym.rd man/adply-du.rd man/alply-wh.rd man/amv-dim-98.rd man/amv-dimnames-eb.rd man/as-data-frame-function-e1.rd man/as-df-d2.rd man/as-list-split-td.rd man/as-quoted-3f.rd man/b.rd man/colwise-5m.rd man/compact-79.rd man/create-progress-bar-4d.rd man/d-ply-4j.rd man/daply-7r.rd man/ddply-5k.rd man/defaults-jw.rd man/dims-7t.rd man/dlply-7t.rd man/each-4v.rd man/eval-quoted-ki.rd man/failwith-sc.rd man/get--split-0n.rd man/indexed-array-4w.rd man/indexed-df-uf.rd man/is-discrete-93.rd man/is-formula-9d.rd man/l-ply-3u.rd man/laply-10.rd man/ldply-f5.rd man/list-to-array-ki.rd man/list-to-dataframe-zb.rd man/list-to-vector-27.rd man/llply-12.rd man/m-ply-5z.rd man/maply-h2.rd man/mdply-cn.rd man/mlply-h5.rd man/names-quoted-g1.rd man/ninteraction-vw.rd man/nunique-ob.rd man/print-quoted-15.rd man/print-split-fc.rd man/progress-none-u0.rd man/progress-text-29.rd man/progress-tk-qf.rd man/progress-win-b6.rd man/r-ply-qd.rd man/raply-uc.rd man/rbind-fill-di.rd man/rdply-1o.rd man/reduce-cf.rd man/reorder-character-4u.rd man/rlply-s7.rd man/splat-n6.rd man/split-labels-0o.rd man/splitter-a-cs.rd man/splitter-d-cs.rd man/summarise-n4.rd man/try-default-rw.rd man/tryapply-sa.rd man/unrowname-ef.rd 2580967577babd05be1f91a4337960d45d8ea920 hadley h.wickham@gmail.com http://github.com/hadley/plyr/commit/13c1ea51ee50bf46693c333287296806215e4c8e 13c1ea51ee50bf46693c333287296806215e4c8e 2009-09-14T06:02:18-07:00 2009-09-14T05:45:15-07:00 Convert documentation to roxygen. 536ed62cee9b0233607f0ef434745165fa2ac263 hadley h.wickham@gmail.com