Skip to contents

Create a specified data frame stabilizer function

Source: R/specify_df.R
specify_df.Rd

specify_df() creates a function that will call stabilize_df() with the provided arguments. specify_data_frame() is a synonym of specify_df().

Usage

specify_df(
  ...,
  .extra_cols = NULL,
  .col_names = NULL,
  .min_rows = NULL,
  .max_rows = NULL,
  .allow_null = TRUE,
  .allow_zero_length = TRUE,
  .required = ...names()
)

specify_data_frame(
  ...,
  .extra_cols = NULL,
  .col_names = NULL,
  .min_rows = NULL,
  .max_rows = NULL,
  .allow_null = TRUE,
  .allow_zero_length = TRUE,
  .required = ...names()
)

Arguments

...

Named stabilizer functions, such as stabilize_* functions (stabilize_chr(), etc) or functions produced by specify_*() functions (specify_chr(), etc). Each name corresponds to a column in .x, and the function is used to validate that column when present. Whether the column is required is controlled by .required.

.extra_cols

Controls how columns of .x that are not explicitly listed in ... are handled. One of:

  • NULL or FALSE (default): any extra columns cause an error.

  • TRUE: extra columns are allowed, unchecked.

  • A single stabilizer function, such as a stabilize_* function (stabilize_chr(), etc) or a function produced by a specify_*() function (specify_chr(), etc), used to validate every extra column.

.col_names

(character) A character vector of column names that must be present in .x. Any columns listed here that are absent from .x will cause an error. Unlike ..., this does not validate the column contents.

.min_rows

(integer(1)) The minimum number of rows allowed in .x. If NULL (default), the row count is not checked.

.max_rows

(integer(1)) The maximum number of rows allowed in .x. If NULL (default), the row count is not checked.

.allow_null

(logical(1)) Is NULL an acceptable value?

.allow_zero_length

(logical(1)) Are zero-length vectors acceptable?

.required

(character) Names (from ...) of columns that must be present in .x. Defaults to all names in ..., so every named spec is required unless you opt it out. Named specs not listed here are optional: if absent, no error is raised; if present, they're validated normally. Pass NULL or character() to make every named spec optional. A .x with zero columns skips this check when .allow_zero_length = TRUE (the default).

Value

A function of class "stbl_specified_fn" that calls stabilize_df() with the provided arguments. The generated function will also accept ... for additional named column specifications to pass to stabilize_df(). You can copy/paste the body of the resulting function if you want to provide additional context or functionality.

See also

Other data frame functions: stabilize_df(), to(), to_df()

Other specification functions: specify_all_of(), specify_any_of(), specify_chr(), specify_date(), specify_dbl(), specify_dttm(), specify_dur(), specify_each(), specify_fct(), specify_int(), specify_lgl(), specify_lst(), specify_one_of(), specify_time()

Examples

stabilize_person_df <- specify_df(
  name = specify_chr_scalar(allow_na = FALSE),
  age = specify_int_scalar(allow_na = FALSE),
  .extra_cols = assert_present
)
stabilize_person_df(data.frame(name = "Alice", age = 30L, score = 99.5))
#>    name age score
#> 1 Alice  30  99.5
try(stabilize_person_df(data.frame(name = "Alice")))
#> Error in eval(expr, envir) : 
#>   `data.frame(name = "Alice")` must contain element "age".

# Mark a column as optional via .required
stabilize_person_df2 <- specify_df(
  name = specify_chr_scalar(allow_na = FALSE),
  age = specify_int_scalar(allow_na = FALSE),
  .required = "name"
)
stabilize_person_df2(data.frame(name = "Alice"))
#>    name
#> 1 Alice