Skip to contents

Create a tibble of combinations of selected column names

Source: R/var_grid.R
var_grid.Rd

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",
  disjoint = var_names(colnames(x)),
  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_disjoint = "disjoint", 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

disjoint

an atomic vector of size equal to the number of columns of x that specifies the groups of predicates: if some elements of the disjoint vector are equal, then the corresponding columns of x will NOT be present together in a single combination of xvars and yvars. If yvars is NULL, the disjoint argument is ignored.

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

Michal Burda

Examples

# Create a grid of combinations of all pairs of columns in the CO2 dataset:
var_grid(CO2)
#> # A tibble: 10 × 2
#>    xvar      yvar     
#>    <chr>     <chr>    
#>  1 Plant     Type     
#>  2 Plant     Treatment
#>  3 Plant     conc     
#>  4 Plant     uptake   
#>  5 Type      Treatment
#>  6 Type      conc     
#>  7 Type      uptake   
#>  8 Treatment conc     
#>  9 Treatment uptake   
#> 10 conc      uptake   

# 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)
#> # A tibble: 6 × 2
#>   xvar      yvar  
#>   <chr>     <chr> 
#> 1 Plant     conc  
#> 2 Plant     uptake
#> 3 Type      conc  
#> 4 Type      uptake
#> 5 Treatment conc  
#> 6 Treatment uptake