From 228251ef6e2f88a1678df913c412e9dcb0bb79a7 Mon Sep 17 00:00:00 2001 From: Joe Thorley Date: Tue, 8 Sep 2026 12:59:48 -0700 Subject: [PATCH 1/3] Clarify new_data() docs and fix broken links Closes #98 Co-Authored-By: Claude Fable 5.1 --- DESCRIPTION | 2 +- R/new-data.R | 52 ++++++++++++++++++++++++++++++++----------------- man/new_data.Rd | 51 ++++++++++++++++++++++++++++++++---------------- 3 files changed, 69 insertions(+), 36 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index 2c1b0af..5146a8c 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -42,7 +42,7 @@ Suggests: testthat (>= 3.0.0), withr Config/Needs/website: poissonconsulting/poissontemplate -Config/roxygen2/version: 8.1.0 +Config/roxygen2/version: 8.1.0.9000 Config/testthat/edition: 3 Encoding: UTF-8 Language: en-US diff --git a/R/new-data.R b/R/new-data.R index 49b5e76..d078432 100644 --- a/R/new-data.R +++ b/R/new-data.R @@ -3,33 +3,49 @@ #' Generates a new data frame (in the form of a tibble) with each variable #' held constant or varying as a unique ordered sequence. #' -#' Although superseded it is maintained for backwards compatibility with existing code. +#' `new_data()` has been superseded by [xnew_data()], +#' which accepts bare column names and provides +#' finer control through [xnew_seq()], [xnew_value()], [xobs_only()] and [xcast()]. +#' `new_data()` remains fully functional and is maintained +#' for backwards compatibility with existing code. +#' All of its arguments continue to work. +#' The `ref` and `obs_only` arguments are deprecated, +#' which means that using them produces a warning +#' but they still behave as documented. #' -#' The code +#' The call #' `new_data(data, seq = c("a", "b"), length_out = 30)` -#' is effectively a wrapper for -#' `xnew_data(data, a, b, .length_out = 30)` -#' to allow a string of column names to be passed. +#' is equivalent to +#' `xnew_data(data, a, b, .length_out = 30)`. #' #' @param data The data frame to generate the new data from. -#' @param seq A character vector of the variables in `data` to generate -#' sequences for. -#' @param ref `r lifecycle::badge("deprecated")` A named list of reference values for variables that are not in seq. -#' Deprecated for `[xnew_value()]` in `[xnew_data()]`. -#' @param obs_only `r lifecycle::badge("deprecated")` A list of character vectors -#' indicating the sets of variables -#' to only allow observed combinations for. -#' If TRUE then obs_only is set to be seq. -#' Deprecated for `[xobs_only()]` in `[xnew_data()]`. -#' @param length_out -#' A count indicating the maximum length of sequences for all -#' types of variables except logical, character, factor and ordered factors. +#' @param seq A character vector of the names of the variables in `data` to +#' generate sequences for. +#' All other variables are held constant at their reference value. +#' @param ref `r lifecycle::badge("deprecated")` A named list of reference +#' values for variables that are not in `seq`. +#' Using it produces a warning. +#' Instead name the value in [xnew_data()], +#' for example `xnew_data(data, a, b = 1)`. +#' @param obs_only `r lifecycle::badge("deprecated")` A list of character +#' vectors indicating the sets of variables to only allow observed +#' combinations for. +#' If `TRUE` then `obs_only` is set to be `seq`. +#' Using it produces a warning. +#' Instead use [xobs_only()] in [xnew_data()], +#' for example `xnew_data(data, xobs_only(a, b))`. +#' @param length_out A count indicating the maximum length of sequences for +#' all types of variables except logical, character, factor and ordered +#' factors. #' @return A tibble of the new data. -#' @seealso [xnew_data()]. +#' @seealso [xnew_data()] #' @examples #' new_data(old_data, "int") #' new_data(old_data, "dbl") #' new_data(old_data, c("int", "dbl")) +#' +#' # equivalent using xnew_data() +#' xnew_data(old_data, int, dbl) #' @export new_data <- function( data, diff --git a/man/new_data.Rd b/man/new_data.Rd index c8281b3..88956ca 100644 --- a/man/new_data.Rd +++ b/man/new_data.Rd @@ -15,20 +15,27 @@ new_data( \arguments{ \item{data}{The data frame to generate the new data from.} -\item{seq}{A character vector of the variables in \code{data} to generate -sequences for.} +\item{seq}{A character vector of the names of the variables in \code{data} to +generate sequences for. +All other variables are held constant at their reference value.} -\item{ref}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} A named list of reference values for variables that are not in seq. -Deprecated for \verb{[xnew_value()]} in \verb{[xnew_data()]}.} +\item{ref}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} A named list of reference +values for variables that are not in \code{seq}. +Using it produces a warning. +Instead name the value in \code{\link[=xnew_data]{xnew_data()}}, +for example \code{xnew_data(data, a, b = 1)}.} -\item{obs_only}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} A list of character vectors -indicating the sets of variables -to only allow observed combinations for. -If TRUE then obs_only is set to be seq. -Deprecated for \verb{[xobs_only()]} in \verb{[xnew_data()]}.} +\item{obs_only}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} A list of character +vectors indicating the sets of variables to only allow observed +combinations for. +If \code{TRUE} then \code{obs_only} is set to be \code{seq}. +Using it produces a warning. +Instead use \code{\link[=xobs_only]{xobs_only()}} in \code{\link[=xnew_data]{xnew_data()}}, +for example \code{xnew_data(data, xobs_only(a, b))}.} -\item{length_out}{A count indicating the maximum length of sequences for all -types of variables except logical, character, factor and ordered factors.} +\item{length_out}{A count indicating the maximum length of sequences for +all types of variables except logical, character, factor and ordered +factors.} } \value{ A tibble of the new data. @@ -38,19 +45,29 @@ Generates a new data frame (in the form of a tibble) with each variable held constant or varying as a unique ordered sequence. } \details{ -Although superseded it is maintained for backwards compatibility with existing code. +\code{new_data()} has been superseded by \code{\link[=xnew_data]{xnew_data()}}, +which accepts bare column names and provides +finer control through \code{\link[=xnew_seq]{xnew_seq()}}, \code{\link[=xnew_value]{xnew_value()}}, \code{\link[=xobs_only]{xobs_only()}} and \code{\link[=xcast]{xcast()}}. +\code{new_data()} remains fully functional and is maintained +for backwards compatibility with existing code. +All of its arguments continue to work. +The \code{ref} and \code{obs_only} arguments are deprecated, +which means that using them produces a warning +but they still behave as documented. -The code +The call \code{new_data(data, seq = c("a", "b"), length_out = 30)} -is effectively a wrapper for -\code{xnew_data(data, a, b, .length_out = 30)} -to allow a string of column names to be passed. +is equivalent to +\code{xnew_data(data, a, b, .length_out = 30)}. } \examples{ new_data(old_data, "int") new_data(old_data, "dbl") new_data(old_data, c("int", "dbl")) + +# equivalent using xnew_data() +xnew_data(old_data, int, dbl) } \seealso{ -\code{\link[=xnew_data]{xnew_data()}}. +\code{\link[=xnew_data]{xnew_data()}} } From dd05df6818409272d773371e299ad4d304ef50f9 Mon Sep 17 00:00:00 2001 From: Joe Thorley Date: Wed, 9 Sep 2026 07:19:02 -0700 Subject: [PATCH 2/3] Update R/new-data.R Co-authored-by: Stefano Mezzini --- R/new-data.R | 2 ++ 1 file changed, 2 insertions(+) diff --git a/R/new-data.R b/R/new-data.R index d078432..8e5fe62 100644 --- a/R/new-data.R +++ b/R/new-data.R @@ -45,6 +45,8 @@ #' new_data(old_data, c("int", "dbl")) #' #' # equivalent using xnew_data() +#' xnew_data(old_data, int) +#' xnew_data(old_data, dbl) #' xnew_data(old_data, int, dbl) #' @export new_data <- function( From d8d91b5b86479fea5600acb5240ca8caccad8cf0 Mon Sep 17 00:00:00 2001 From: Stefano Mezzini <42444204+StefanoMezzini@users.noreply.github.com> Date: Wed, 9 Sep 2026 10:03:09 -0700 Subject: [PATCH 3/3] Update new_data.Rd --- man/new_data.Rd | 2 ++ 1 file changed, 2 insertions(+) diff --git a/man/new_data.Rd b/man/new_data.Rd index 88956ca..7e1d270 100644 --- a/man/new_data.Rd +++ b/man/new_data.Rd @@ -66,6 +66,8 @@ new_data(old_data, "dbl") new_data(old_data, c("int", "dbl")) # equivalent using xnew_data() +xnew_data(old_data, int) +xnew_data(old_data, dbl) xnew_data(old_data, int, dbl) } \seealso{