Package 'interfacer'

Description

Cast an iface to a plain list.

Usage

## S3 method for class 'iface'
as.list(x, ..., flatten = FALSE)

Arguments

Value

a list representation of the iface input.

Examples

my_iface = iface( 
  col1 = integer + group_unique ~ "an integer column"
)

as.list(my_iface, flatten=TRUE)

Description

Checks a set of variables can be coerced to a character and coerces them

Usage

check_character(
  ...,
  .message = "`{param}` is not a character: ({err}).",
  .env = rlang::caller_env()
)

Arguments

Value

nothing. called for side effects. throws error if not all variables can be coerced.

Examples

a = c(Sys.Date()+1:10)
b = format(a)
f = iris$Species
g = NA
check_character(a,b,f,g)

Description

If the parameters of a function are given in some combination but have an interdependency (e.g. different parametrisations of a probability distribution) or a constraint (like x>0) this function can simultaneously check all interrelations are satisfied and report on all the not conformant features of the parameters.

Usage

check_consistent(..., .env = rlang::caller_env())

Arguments

Value

nothing, throws an informative error if the checks fail.

Examples

testfn = function(pos, neg, n) {
  check_consistent(pos=n-neg, neg=n-pos, n=pos+neg, n>pos, n>neg)
}

testfn(pos = 1:4, neg=4:1, n=rep(5,4))
try(testfn(pos = 1:4, neg=5:2, n=rep(5,4)))

Description

Checks a set of variables can be coerced to a date and coerces them

Usage

check_date(
  ...,
  .message = "`{param}` is not a date: ({err}).",
  .env = rlang::caller_env()
)

Arguments

Value

nothing. called for side effects. throws error if not all variables can be coerced.

Examples

a = c(Sys.Date()+1:10)
b = format(a)
f = "1970-01-01"
g = NA
check_date(a,b,f,g)

c = c("dfsfs")
try(check_date(c,d, mean))

Description

N.B. This only works for the specific environment (to prevent weird side effects)

Usage

check_integer(
  ...,
  .message = "`{param}` is not an integer ({err}).",
  .env = rlang::caller_env()
)

Arguments

Value

nothing. called for side effects. throws error if not all variables can be coerced.

Examples

a = c(1:4)
b = c("1",NA,"3")
f = NULL
g = NA
check_integer(a,b,f,g)

c = c("dfsfs")
e = c(1.0,2.3)
try(check_integer(c,d,e, mean))

Description

Checks a set of variables can be coerced to a logical and coerces them

Usage

check_logical(
  ...,
  .message = "`{param}` is not a logical: ({err}).",
  .env = rlang::caller_env()
)

Arguments

Value

nothing. called for side effects. throws error if not all variables can be coerced.

Examples

a = c("T","F")
b = c(1,0,1,0)
f = TRUE
g = NA
check_logical(a,b,f,g)

c = c("dfsfs")
try(check_logical(c,d, mean))

Description

N.B. This only works for the specific environment (to prevent weird side effects)

Usage

check_numeric(
  ...,
  .message = "`{param}` is non-numeric ({err}).",
  .env = rlang::caller_env()
)

Arguments

Value

nothing. called for side effects. throws error if not all variables can be coerced.

Examples

a = c(1:4L)
b = c("1",NA,"3.3")
f = NULL
g = NA
check_numeric(a,b,f,g)

c = c("dfsfs")
try(check_numeric(c,d, mean))

Description

Checks a set of variables are all of length one

Usage

check_single(
  ...,
  .message = "`{param}` is not length one: ({err}).",
  .env = rlang::caller_env()
)

Arguments

Value

nothing. called for side effects. throws error if not all variables can be coerced.

Examples

a = 1
b = "Hello"
g = NA
check_single(a,b,g)

c= c(1,2,3)
d=list(a,b)
try(check_single(c,d,missing))

Description

Format an iface specification for printing

Usage

## S3 method for class 'iface'
format(x, ...)

Arguments

Value

a formatted string representation of an iface

Examples

my_iface = iface( 
  col1 = integer + group_unique ~ "an integer column"
)

print(my_iface)
knitr::knit_print(my_iface)

Description

When developing with interfacer it is useful to be able to base a function input off a prototype that you are for example using as testing. This function generates an interfacer::iface specification for the supplied data frame and copies it to the clipboard so that it can be pasted into the package code you are working on.

Usage

iclip(df, df_name = deparse(substitute(df)))

Arguments

Details

If the dataframe contains one or more list columns with nested dataframes the nested dataframes are also defined using a second iface specification.

Value

nothing, populates clipboard

Examples

if (interactive()) iclip(iris)

Description

This function is called by ivalidate() and is not generally intended to be used directly by the end user. It may be helpful in debugging during package development to interactive test a iface spec. iconvert is an interactive version of ivalidate().

Usage

iconvert(
  df,
  iface,
  .imap = interfacer::imapper(),
  .dname = "<unknown>",
  .fname = "<unknown>",
  .has_dots = TRUE,
  .prune = FALSE,
  .env = rlang::current_env()
)

Arguments

Value

the input dataframe coerced to be conformant to the iface specification, or an informative error is thrown.

Examples

i_diamonds = iface( 
  color = enum(D,E,F,G,H,I,J,extra) ~ "the colour", 
  price = integer ~ "the price"
)

iconvert(ggplot2::diamonds, i_diamonds,.prune = TRUE)

Description

This provides a dataframe analogy to S3 dispatch. If multiple possible dataframe formats are possible for a function, each with different processing requirements, then the choice of function can be made based on matching the input dataframe to a set of iface specifications. The first matching iface specification determines which function is used for dispatch.

Usage

idispatch(x, ..., .default = NULL)

Arguments

Value

the result of dispatching the dataframe to the first function that matches the rules in .... Matching is permissive in that the test is passed if a dataframe can be coerced to the iface specified format.

Examples

i1 = iface( col1 = integer ~ "An integer column" )
i2 = iface( col2 = integer ~ "A different integer column" )

# this is an example function that would typically be inside a package, and
# is exported from the package.
extract_mean = function(df, ...) {
  idispatch(df,
    extract_mean.i1 = i1,
    extract_mean.i2 = i2
  )
}

# this is expected to be an internal package function
# the naming convention here is based on S3 but it is not required
extract_mean.i1 = function(df = i1, ...) {
  message("using i1")
  # input validation is not required in functions that are being called using
  # `idispatch` as the validation occurs during dispatch. 
  mean(df$col1)
}

extract_mean.i2 = function(df = i2, uplift = 1, ...) {
  message("using i2")
  mean(df$col2)+uplift
}

# this input matches `i1` and the `extract_mean` call is dispatched 
# via `extract_mean.i1`
test = tibble::tibble( col2 = 1:10 )
extract_mean(test, uplift = 50)

# this input matches `i2` and the `extract_mean` call is dispatched 
# via `extract_mean.i2`
test2 = tibble::tibble( col1 = 1:10 )
extract_mean(test2, uplift = 50)

# This input does not match any of the allowable input specifications and 
# generates an error.
test3 = tibble::tibble( wrong_col = 1:10 )
try(extract_mean(test3, uplift = 50))

Description

This function is expected to be called within the documentation of a function as inline code in the parameter documentation of the function. It details the expected columns that the input dataframe should possess. This has mostly been superseded by the ⁠@iparam <name> <description>⁠ roxygen2 tag which does this automatically, however in some circumstances (particularly multiple dispatch) you may want to assemble dataframe documentation manually.

Usage

idocument(fn, param = NULL)

Arguments

Value

a markdown snippet

Examples

#' @param df `r idocument(x, df)`
x = function(df = iface( col1 = integer ~ "an integer column" )) {}

cat(idocument(x, df))

Description

The simple use case. For more complex behaviour see switch_pipeline().

Usage

if_col_present(df, col, if_present, if_missing = ~.x)

Arguments

Value

either the value of if_present/if_absent or the result of calling if_present/if_absent as functions on df.

Examples

iris %>% if_col_present(Species, ~ .x %>% dplyr::rename(new = Species)) %>%
  colnames()

# in contrast to `purrr` absolute values are not interpreted as function names  
iris %>% if_col_present(Species2, "Yes", "No")

Description

An iface specification defines the expected structure of a dataframe, in terms of the column names, column types, grouping structure and uniqueness constraints that the dataframe must conform to. A dataframe can be tested for conformance to an iface specification using ivalidate().

Usage

iface(..., .groups = NULL, .default = NULL)

Arguments

Details

An iface specification is designed to be used to define the type of a parameter in a function. This is done by using the iface specification as the default value of the parameter in the function definition. The definition can then be validated at runtime by a call to ivalidate() inside the function.

When developing a function output an iface specification may also be used in ireturn() to enforce that the output of a function is correct.

iface definitions can be printed and included in roxygen2 documentation and help us to document input dataframe parameters and dataframe return values in a standardised way by using the ⁠@iparam⁠ roxygen2 tag.

iface specifications are defined in the form of a named list of formulae with the structure column_name = type ~ "documentation".

type can be one of anything, character, complete, date, default, double, enum, factor, finite, group_unique, in_range, integer, logical, not_missing, numeric, of_type, positive_double, positive_integer, proportion, unique_id (e.g. enum(level1,level2,...), in_range(min,max)) or alternatively anything that resolves to a function e.g. as.ordered.

If type is a function name, then the function must take a single vector parameter and return a single vector of the same size. The function must also return a zero length vector of an appropriate type if passed NULL.

type can also be a concatenation of rules separated by +, e.g. integer + group_unique for an integer that is unique within a group.

Value

the definition of an interface as a iface object

Examples

test_df = tibble::tibble(
  grp = c(rep("a",10),rep("b",10)), 
  col1 = c(1:10,1:10)
) %>% dplyr::group_by(grp)

my_iface = iface( 
  col1 = integer + group_unique ~ "an integer column",
  .default = test_df
)

print(my_iface)

# the function x defines a formal `df` with default value of `my_iface`
# this default value is used to validate the structure of the user supplied
# value when the function is called.
x = function(df = my_iface, ...) {
  df = ivalidate(df,...)
  return(df)
}

# this works
x(tibble::tibble(col1 = c(1,2,3)))

# this fails as x is of the wrong type
try(x(tibble::tibble(col1 = c("a","b","c"))))

# this fails as x has duplicates
try(x(tibble::tibble(col1 = c(1,2,3,3))))

# this gives the default value
x()


my_iface2 = iface(
  first_col = numeric ~ "column order example",
  my_iface, 
  last_col = character ~ "another col", .groups = ~ first_col + col1
)
print(my_iface2)



my_iface_3 = iface( 
  col1 = integer + group_unique ~ "an integer column",
  .default = test_df_2
)
x = function(d = my_iface_3) {ivalidate(d)}

# Doesn't work as test_df_2 hasn't been defined
try(x())

test_df_2 = tibble::tibble(
  grp = c(rep("a",10),rep("b",10)), 
  col1 = c(1:10,1:10)
) %>% dplyr::group_by(grp)

# now it works as has been defined
x()

# it still works as default has been cached.
rm(test_df_2)
x()

Description

This function is designed to be used by a package author within an enclosing function. The enclosing function is assumed to take as input a dataframe and have an iface specified for that dataframe.

Usage

igroup_process(df = NULL, fn, ...)

Arguments

Details

This function detects when the grouping of the input has additional groups over and above those in the specification and intercepts them, regrouping the dataframe and applying fn group-wise using an equivalent of a dplyr::group_modify. The parameters provided to the enclosing function will be passed to fn and they should have compatible method signatures.

Value

the result of calling fn(df, ...) on each unexpected group

Examples

# This specification requires that the dataframe is grouped only by the color
# column
i_diamond_price = interfacer::iface(
  color = enum(`D`,`E`,`F`,`G`,`H`,`I`,`J`, .ordered=TRUE) ~ "the color column",
  price = integer ~ "the price column",
  .groups = ~ color
)

# An example function which would be exported in a package
ex_mean = function(df = i_diamond_price, extra_param = ".") {
  
  # When called with a dataframe with extra groups `igroup_process` will 
  # regroup the dataframe according to the structure 
  # defined for `i_diamond_price` and apply the inner function to each group
  # after first calling `ivalidate` on each group.
  
  igroup_process(df, 
    
    # the real work of this function is provided as an anonymous inner
    # function (but can be any other function e.g. package private function)
    # or a purrr style lambda.
    
    function(df, extra_param) {
      message(extra_param, appendLF = FALSE)
      return(df %>% dplyr::summarise(mean_price = mean(price)))
    }
    
  )
}

# The correctly grouped dataframe. The `ex_mean` function calculates the mean
# price for each `color` group.
ggplot2::diamonds %>% 
  dplyr::group_by(color) %>% 
  ex_mean(extra_param = "without additional groups...") %>% 
  dplyr::glimpse()
  
# If an additionally grouped dataframe is provided by the user. The `ex_mean` 
# function calculates the mean price for each `cut`,`clarity`, and `color` 
# combination.

ggplot2::diamonds %>% 
  dplyr::group_by(cut, color, clarity) %>% 
  ex_mean() %>% 
  dplyr::glimpse()
  
# The output of this is actually grouped by cut then clarity as
# color is consumed by the igroup_dispatch summarise.

Description

When a function uses ivalidate() internally to check a dataframe conforms to the input it can attempt to rescue an incorrectly formatted dataframe. This is a pretty advanced idea and is not generally recommended.

Usage

imapper(...)

Arguments

Details

This function is expected to be used only in the context of a .imap = imapper(...) parameter to an ivalidate() call to make sure that certain columns are present or are a set value. Anything provided here will overwrite existing dataframe columns and its use is likely to make function behaviour obtuse. It may be deprecated in the future. The ... input expressions should almost certainly check for the values already existing before overwriting them.

If you are considering using this for replacing missing values check using the default(...) iface type definition instead.

Value

a set of mappings

Examples

x = function(df = iface(col1 = integer ~ "an integer column" ), ...) {
  df = ivalidate(df,...)
}
input=tibble::tibble(col2 = c(1,2,3)) 
# This fails because col1 is missing
try(x(input))
# This fixes it for this input
x(input, .imap=imapper(col1 = col2))

Description

This function is used internally for default values for a dataframe parameter. It generates a zero length dataframe that conforms to a iface specification, in terms of column names, data types and groupings. Such a dataframe is not guaranteed to be fully conformant to the iface specification if, for example, completeness constraints are applied.

Usage

iproto(iface)

Arguments

Value

a dataframe conforming to iface

Examples

i = interfacer::iface(
  col1 = integer ~ "A number",
  col2 = character ~ "A string"
)

iproto(i)

Description

This is intended to be used within a function to check the validity of a data frame being returned from a function against an ispec which is provided.

Usage

ireturn(df, iface, .prune = FALSE)

Arguments

Value

a dataframe based on df with validity checks passed, data-types coerced, and correct grouping applied to conform to iface

Examples

input = iface(col_in = integer ~ "an integer column" )
output = iface(col_out = integer ~ "an integer column" )

x = function(df = input, ...) {
  df = ivalidate(...)
  tmp = df %>% dplyr::rename(col_out = col_in)
  ireturn(tmp, output)
}
x(tibble::tibble(col_in = c(1,2,3)))
output

Description

Check for existence of a set of columns in a dataframe

Usage

is_col_present(df, ...)

Arguments

Value

TRUE if the columns are all there, false otherwise

Examples

is_col_present(iris, Species, Petal.Width)

Description

Check if an object is an interface specification

Usage

is.iface(x, ...)

Arguments

Value

a boolean.

Description

ivalidate throws errors deliberately however sometimes dealing with invalid input may be desirable. itest is generally designed to be used within a function which specifies the expected input using iface, and allows the function to test if its given input is conformant to the interface.

Usage

itest(df = NULL, iface = NULL, .imap = imapper())

Arguments

Value

TRUE if the dataframe is conformant, FALSE otherwise

Examples

if (rlang::is_installed("ggplot2")) {
  i_diamonds = iface( 
    color = enum(D,E,F,G,H,I,J,extra) ~ "the colour", 
    price = integer ~ "the price"
  )
  
  # Ad hoc testing
  itest(ggplot2::diamonds, i_diamonds)
  
  # Use within function:
  x = function(df = i_diamonds) {
    if(itest()) message("PASS!")
  }
  
  x(ggplot2::diamonds)
}

Description

ivalidate(...) is intended to be used within a function to check the validity of a data frame parameter (usually the first parameter) against an ispec which is given as a default value of a formal parameter.

Usage

ivalidate(df = NULL, ..., .imap = imapper(), .prune = FALSE, .default = NULL)

Arguments

Value

a dataframe based on df with validity checks passed and .imap mappings applied if present

Examples

x = function(df = iface(col1 = integer ~ "an integer column" ), ...) {
  df = ivalidate(...)
  return(df)
}
input=tibble::tibble(col1 = c(1,2,3))
x(input)

# This fails because col1 is not coercable to integer
input2=tibble::tibble(col1 = c(1.5,2,3))
try(x(input2))

Description

Format an iface specification for printing

Usage

knit_print.iface(x, ...)

Arguments

Value

a formatted string representation of an iface

Examples

my_iface = iface( 
  col1 = integer + group_unique ~ "an integer column"
)

print(my_iface)
knitr::knit_print(my_iface)

Description

Format an iface specification for printing

Usage

## S3 method for class 'iface'
print(x, ...)

Arguments

Value

a formatted string representation of an iface

Examples

my_iface = iface( 
  col1 = integer + group_unique ~ "an integer column"
)

print(my_iface)
knitr::knit_print(my_iface)

Description

recycle is called within a function and ensures the parameters in the calling function are all the same length by repeating them using rep. This function alters the environment from which it is called. It is stricter than R recycling in that it will not repeat vectors other than length one to match the longer ones, and it throws more informative errors.

Usage

recycle(..., .min = 1, .env = rlang::caller_env())

Arguments

Details

NULL values are not recycled, missing values are ignored.

Value

the length of the longest variable

Examples

testfn = function(a, b, c) {
  n = recycle(a,b,c)
  print(a)
  print(b)
  print(c)
  print(n)
}

testfn(a=c(1,2,3), b="needs recycling", c=NULL)
try(testfn(a=c(1,2,3), c=NULL))

testfn(a=character(), b=integer(), c=NULL)

# inconsistent to have a zero length and a non zero length
try(testfn(a=c("a","b"), b=integer(), c=NULL))

Description

Uses relationships between parameters to iteratively fill in missing values. It is possible to specify an inconsistent set of rules or data in which case the resulting values will be picked up and an error thrown.

Usage

resolve_missing(
  ...,
  .env = rlang::caller_env(),
  .eval_null = TRUE,
  .error = NULL
)

Arguments

Value

nothing. Alters the .env environment to fill in missing values or throws an informative error

Examples

# missing variables left with no default value in function definition
testfn = function(pos, neg, n) {
  resolve_missing(pos=n-neg, neg=n-pos, n=pos+neg)
  return(tibble::tibble(pos=pos,neg=neg,n=n))
}

testfn(pos=1:4, neg = 4:1)
testfn(neg=1:4, n = 10:7)

try(testfn())

# not enough info to infer the missing variables
try(testfn(neg=1:4))

# the parameters given are inconsistent with the relationships defined.
try(testfn(pos=2, neg=1, n=4))

Description

The ⁠@iparam <name> <description>⁠ tag can be used in roxygen2 documentation of a function to describe a dataframe parameter. The function must be using interfacer::iface to define the input dataframe parameter format. The ⁠@iparam⁠ tag will then generate documentation about the type of dataframe the function is expecting.

Usage

## S3 method for class 'roxy_tag_iparam'
roxy_tag_parse(x)

Arguments

Value

a roxy_tag object with the val field set to the parsed value

Examples

# This provides support to `roxygen2` and only gets executed in the context
# of `devtools::document()`. There is no interactive use of this function.

Description

The ⁠@iparam <name> <description>⁠ tag can be used in roxygen2 documentation of a function to describe a dataframe parameter. The function must be using interfacer::iface to define the input dataframe parameter format. The ⁠@iparam⁠ tag will then generate documentation about the type of dataframe the function is expecting.

Usage

## S3 method for class 'roxy_tag_iparam'
roxy_tag_rd(x, base_path, env)

Arguments

Value

an roxygen2::rd_section (see roxygen2 documentation)

Examples

# An example function definition:
fn_definition <- "
#' This is a title
#' 
#' This is the description.
#' 
#' @md
#' @iparam df the input
#' @export
f <- function(df = interfacer::iface(
  id = integer ~ \"an integer `ID`\",
  test = logical ~ \"the test result\"
)) {
  ivalidate(df)
}
"

# For this example we manually parse the function specification in `fn_definition`
# creating a .Rd block - normally this is done by `roxygen2` which then
# writes this to an .Rd file. This function is not intended to be used 
# outside of a call to `devtools::document`.

tmp = roxygen2::parse_text(fn_definition)
print(tmp)

Description

Branch a dplyr pipeline based on a set of conditions

Usage

switch_pipeline(.x, ...)

Arguments

Value

the result of applying ⁠purrr function⁠ to .x in the case where predicate evaluates to true. Both predicate and function can refer to the pipeline dataframe using .x

Examples

iris %>% switch_pipeline(
  is_col_present(.x, Species) ~ .x %>% dplyr::rename(new = Species)
) %>% dplyr::glimpse()

Description

Coerce to an unspecified type

Usage

type.anything(x)

Arguments

Value

the input (unless x is NULL in which case a character())

Description

Coerce to a character.

Usage

type.character()

Value

the input as a character.

Description

This test checks either for factors that all factor levels are present in the input, or for numerics if the sequence from minimum to maximum by the smallest difference are not all (approximately) present. Empty values are ignored.

Usage

type.complete(x)

Arguments

Value

the input or error if not complete

Description

Coerce to a Date.

Usage

type.date(x, ...)

Arguments

Value

the input as a date vector, error if this would involve data loss.

Description

Any NA values will be replaced by this value. N.b. default values must be provided before any other rules if the validation is not to fail.

Usage

type.default(value)

Arguments

Value

a validation function that switches NAs for default values

Description

Coerce to a double.

Usage

type.double(x)

Arguments

Value

the input as a double, error if this would involve data loss.

Description

Define a conformance rule to match a factor with specific levels.

Usage

type.enum(..., .drop = FALSE, .ordered = FALSE)

Arguments

Value

a function that can check and convert input into the factor with specified levels. This will re-level factors with matching levels but in a different order.

Examples

f = type.enum(one,two,three)
f(c("three","two","one"))
f(factor(rep(1:3,5), labels = c("one","two","three")))

Description

Coerce to a factor.

Usage

type.factor(x)

Arguments

Value

the input as a factor, error if this would involve data loss.

Description

Any non finite values will cause failure of validation.

Usage

type.finite(x)

Arguments

Value

the input coerced to a numeric value, or an error if any non-finite values detected

Description

Coerce to a unique value within the current grouping structure.

Usage

type.group_unique(x)

Arguments

Value

the input or error if any of x is not unique.

Description

This is anticipated to be part of a iface rule e.g.

Usage

type.in_range(min, max, include.min = TRUE, include.max = TRUE)

Arguments

Details

iface(test_col = integer + in_range(-10,10) ~ "An integer from -10 to 10")

Value

a function which checks the values and returns them if OK or throws an error if not

Examples

type.in_range(0,10,TRUE,TRUE)(0:10)
try(type.in_range(0,10,TRUE,FALSE)(0:10))
try(type.in_range(0,10,FALSE)(0:10))
type.in_range(0,10,FALSE,TRUE)(1:10)
type.in_range(0,10,TRUE,FALSE)(0:9)
type.in_range(0,Inf,FALSE,FALSE)(1:9)
try(type.in_range(0,10)(1:99))

Description

Coerce to integer

Usage

type.integer(x)

Arguments

Value

the input as an integer, error if this would involve data loss.

Description

Coerce to a logical

Usage

type.logical(x)

Arguments

Value

the input as a logical, error if this would involve data loss.

Description

Any NA values will cause failure of validation.

Usage

type.not_missing(x)

Arguments

Value

the input if no missing values detected, otherwise an error

Description

Coerce to a numeric.

Usage

type.numeric(x)

Arguments

Value

the input as a numeric, error if this would involve data loss.

Description

Any values of the wrong class will cause failure of validation. This is particularly useful for custom vectors of for list types (e.g. list(of_type(lm)))

Usage

type.of_type(type, .not_null = FALSE)

Arguments

Value

a function that can check the input is of the correct type.

Description

Coerce to a positive double.

Usage

type.positive_double(x)

Arguments

Value

the input as a positive double, error if this would involve data loss.

Description

Coerce to a positive integer.

Usage

type.positive_integer(x)

Arguments

Value

the input as a positive integer, error if this would involve data loss.

Description

Coerce to a number between 0 and 1

Usage

type.proportion(x)

Arguments

Value

the input as a number from 0 to 1, error if this would involve data loss.

Description

A globally unique ids.

Usage

type.unique_id(x)

Arguments

Value

the input.

Description

Using the interfacer framework you can document data during development. This provides the basic documentation framework for a dataset based on a dataframe in the correct format into the right place.

Usage

use_dataframe(
  df,
  name = deparse(substitute(df)),
  output = "R/data.R",
  pkg = "."
)

Arguments

Details

If this is your only use case for interfacer then you will not need to import interfacer in your package, as none of the generated code will depend on it.

Value

nothing, used for side effects.

Examples

# example code
if (interactive()) {
  # This is not run as it is designed for interactive use only and will
  # write to the userspace after checking that is what the user wants.
  use_dataframe(iris) 
}

Description

Generating and documenting an iface for a given dataframe would be time consuming and annoying if you could not do it automatically. In this case as you interactively develop a package using a test dataframe, the structure of which can be explicitly documented and made into a specific contract within the package. This supports development using test dataframes as a prototype for function ensuring future user input conforms to the same expectations as the test data.

Usage

use_iface(
  df,
  name = deparse(substitute(df)),
  output = "R/interfaces.R",
  use_as_default = FALSE,
  pkg = "."
)

Arguments

Value

nothing, used for side effects.

Examples

# example code
if (interactive()) {
  # This is not run as it is designed for interactive use only and will
  # write to the userspace after checking that is what the user wants.
  use_iface(iris) 
}