var_grid: Create a tibble of combinations of selected column names

In nuggets: Extensible Data Pattern Searching Framework

Create a tibble of combinations of selected column names

Description

xvars and yvars arguments are tidyselect expressions (see tidyselect syntax) that specify the columns of x whose names will be used as a domain for combinations.

If yvars is NULL, the function creates a tibble with one column var enumerating all column names specified by the xvars argument.

If yvars is not NULL, the function creates a tibble with two columns, xvar and yvar, whose rows enumerate all combinations of column names specified by the xvars and yvars argument.

It is allowed to specify the same column in both xvars and yvars arguments. In such a case, the combinations of the same column with itself are removed from the result.

In other words, the function creates a grid of all possible pairs (xx, yy) where xx \in xvars, yy \in yvars, and xx \neq yy.

Usage

var_grid(
  x,
  xvars = everything(),
  yvars = everything(),
  allow = "all",
  xvar_name = if (quo_is_null(enquo(yvars))) "var" else "xvar",
  yvar_name = "yvar",
  error_context = list(arg_x = "x", arg_xvars = "xvars", arg_yvars = "yvars", arg_allow =
    "allow", arg_xvar_name = "xvar_name", arg_yvar_name = "yvar_name", call =
    current_env())
)

Arguments

x	either a data frame or a matrix
xvars	a tidyselect expression (see tidyselect syntax) specifying the columns of x, whose names will be used as a domain for combinations use at the first place (xvar)
yvars	NULL or a tidyselect expression (see tidyselect syntax) specifying the columns of x, whose names will be used as a domain for combinations use at the second place (yvar)
allow	a character string specifying which columns are allowed to be selected by xvars and yvars arguments. Possible values are: "all" - all columns are allowed to be selected "numeric" - only numeric columns are allowed to be selected
xvar_name	the name of the first column in the resulting tibble.
yvar_name	the name of the second column in the resulting tibble. The column does not exist if yvars is NULL.
error_context	A list of details to be used in error messages. This argument is useful when var_grid() is called from another function to provide error messages, which refer to arguments of the calling function. The list must contain the following elements: arg_x - the name of the argument x as a character string arg_xvars - the name of the argument xvars as a character string arg_yvars - the name of the argument yvars as a character string arg_allow - the name of the argument allow as a character string arg_xvar_name - the name of the xvar column in the output tibble arg_yvar_name - the name of the yvar column in the output tibble call - an environment in which to evaluate the error messages.

Value

if yvars is NULL, the function returns a tibble with a single column (var). If yvars is a non-NULL expression, the function returns two columns (xvar and yvar) with rows enumerating all combinations of column names specified by tidyselect expressions in xvars and yvars arguments.

Author(s)

Michal Burda

Examples

# Create a grid of combinations of all pairs of columns in the CO2 dataset:
var_grid(CO2)

# Create a grid of combinations of all pairs of columns in the CO2 dataset
# such that the first, i.e., `xvar` column is `Plant`, `Type`, or
# `Treatment`, and the second, i.e., `yvar` column is `conc` or `uptake`:
var_grid(CO2, xvars = Plant:Treatment, yvars = conc:uptake)

nuggets documentation built on April 3, 2025, 8:07 p.m.