diff --git a/NAMESPACE b/NAMESPACE index e89863807..afd84cb87 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -228,6 +228,7 @@ export(data_adjust) export(data_arrange) export(data_codebook) export(data_duplicated) +export(data_expand) export(data_extract) export(data_filter) export(data_find) diff --git a/R/data_expand.R b/R/data_expand.R new file mode 100644 index 000000000..e0d528031 --- /dev/null +++ b/R/data_expand.R @@ -0,0 +1,69 @@ +#' @title Expand (i.e. replicate rows) a data frame +#' @name data_expand +#' +#' @description +#' Expand a data frame by replicating rows based on another variable that +#' contains the counts of replications per row. +#' +#' @param data A data frame. +#' @param expand The name of the column that contains the counts of replications +#' for each row. +#' @param ... Currently not used. +#' @inheritParams find_columns +#' +#' @return `data`, with each row replicated as many times as defined in `expand`. +#' +#' @examples +#' data(mtcars) +#' data_expand(head(mtcars), "carb") +#' @export +data_expand <- function(data, + expand = NULL, + select = NULL, + exclude = NULL, + remove_na = FALSE, + ignore_case = FALSE, + verbose = TRUE, + regex = FALSE, + ...) { + # we need a name for the new column + if (is.null(expand)) { + insight::format_error( + "No column that should be used to expand the data frame was provided. Please use `expand` to define a column." + ) + } + + # only one column name + if (length(expand) > 1) { + insight::format_error( + "Please provide only a single string for `expand`, no character vector with multiple values." + ) + } + + # check if in data + if (!expand %in% colnames(data)) { + insight::format_error( + "The column provided in `expand` does not exist in the data frame.", + .misspelled_string(colnames(data), expand, "Possibly misspelled?") + ) + } + + # evaluate select/exclude, may be select-helpers + select <- .select_nse(select, + data, + exclude, + ignore_case, + regex = regex, + verbose = verbose + ) + + # extract variable that contains the counts of replicates + replicates <- data[[expand]] + # we can remove that column now + data[[replicates]] <- NULL + + # fin + as.data.frame(do.call(cbind, lapply(data[select], function(variable) { + unlist(Map(rep, variable, replicates), use.names = FALSE) + }))) +} diff --git a/_pkgdown.yaml b/_pkgdown.yaml index 2adc0768c..93043c95a 100644 --- a/_pkgdown.yaml +++ b/_pkgdown.yaml @@ -20,6 +20,7 @@ reference: - data_partition - data_rotate - data_group + - data_expand - data_duplicated - data_unique diff --git a/man/data_expand.Rd b/man/data_expand.Rd new file mode 100644 index 000000000..b3f14e19d --- /dev/null +++ b/man/data_expand.Rd @@ -0,0 +1,88 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/data_expand.R +\name{data_expand} +\alias{data_expand} +\title{Expand (i.e. replicate rows) a data frame} +\usage{ +data_expand( + data, + expand = NULL, + select = NULL, + exclude = NULL, + remove_na = FALSE, + ignore_case = FALSE, + verbose = TRUE, + regex = FALSE, + ... +) +} +\arguments{ +\item{data}{A data frame.} + +\item{expand}{The name of the column that contains the counts of replications +for each row.} + +\item{select}{Variables that will be included when performing the required +tasks. Can be either +\itemize{ +\item a variable specified as a literal variable name (e.g., \code{column_name}), +\item a string with the variable name (e.g., \code{"column_name"}), or a character +vector of variable names (e.g., \code{c("col1", "col2", "col3")}), +\item a formula with variable names (e.g., \code{~column_1 + column_2}), +\item a vector of positive integers, giving the positions counting from the left +(e.g. \code{1} or \code{c(1, 3, 5)}), +\item a vector of negative integers, giving the positions counting from the +right (e.g., \code{-1} or \code{-1:-3}), +\item one of the following select-helpers: \code{starts_with()}, \code{ends_with()}, +\code{contains()}, a range using \code{:} or \code{regex("")}. \code{starts_with()}, +\code{ends_with()}, and \code{contains()} accept several patterns, e.g +\code{starts_with("Sep", "Petal")}. +\item or a function testing for logical conditions, e.g. \code{is.numeric()} (or +\code{is.numeric}), or any user-defined function that selects the variables +for which the function returns \code{TRUE} (like: \code{foo <- function(x) mean(x) > 3}), +\item ranges specified via literal variable names, select-helpers (except +\code{regex()}) and (user-defined) functions can be negated, i.e. return +non-matching elements, when prefixed with a \code{-}, e.g. \code{-ends_with("")}, +\code{-is.numeric} or \code{-(Sepal.Width:Petal.Length)}. \strong{Note:} Negation means +that matches are \emph{excluded}, and thus, the \code{exclude} argument can be +used alternatively. For instance, \code{select=-ends_with("Length")} (with +\code{-}) is equivalent to \code{exclude=ends_with("Length")} (no \code{-}). In case +negation should not work as expected, use the \code{exclude} argument instead. +} + +If \code{NULL}, selects all columns. Patterns that found no matches are silently +ignored, e.g. \code{find_columns(iris, select = c("Species", "Test"))} will just +return \code{"Species"}.} + +\item{exclude}{See \code{select}, however, column names matched by the pattern +from \code{exclude} will be excluded instead of selected. If \code{NULL} (the default), +excludes no columns.} + +\item{ignore_case}{Logical, if \code{TRUE} and when one of the select-helpers or +a regular expression is used in \code{select}, ignores lower/upper case in the +search pattern when matching against variable names.} + +\item{verbose}{Toggle warnings.} + +\item{regex}{Logical, if \code{TRUE}, the search pattern from \code{select} will be +treated as regular expression. When \code{regex = TRUE}, select \emph{must} be a +character string (or a variable containing a character string) and is not +allowed to be one of the supported select-helpers or a character vector +of length > 1. \code{regex = TRUE} is comparable to using one of the two +select-helpers, \code{select = contains("")} or \code{select = regex("")}, however, +since the select-helpers may not work when called from inside other +functions (see 'Details'), this argument may be used as workaround.} + +\item{...}{Currently not used.} +} +\value{ +\code{data}, with each row replicated as many times as defined in \code{expand}. +} +\description{ +Expand a data frame by replicating rows based on another variable that +contains the counts of replications per row. +} +\examples{ +data(mtcars) +data_expand(head(mtcars), "carb") +}