rapport.inputs {rapport}

Template Inputs

Description

Displays summary for template inputs (if any). Note that as of version 0.5, rapport template inputs should be defined using YAML syntax. See deprecated-inputs for details on old input syntax. The following sections describe new YAML input definition style.

Usage

rapport.inputs(fp, use.header = FALSE)

Arguments

fp

a template file pointer (see rapport:::rapport.read for details)

use.header

a logical value indicating whether the header section is provided in h argument

Details

Introduction

The full power of rapport comes into play with template inputs. One can match inputs against dataset variables or custom R objects. The inputs provide means of assigning R objects to symbols in the template evaluation environment. Inputs themselves do not handle only the template names, but also provide an extensive set of rules that each dataset variable/user-provided R object has to satisfy. The new YAML input specification takes advantage of R class system. The input attributes should resemble common R object attributes and methods.

Inputs can be divided into two categories:

• dataset inputs, i.e. the inputs that refer to named element of an |codeR object provided in data argument in rapport call. Currently, rapport supports only data.frame objects, but that may change in the (near) future.

• standalone inputs - the inputs that do not depend on the dataset. The user can just provide an R object of an appropriate class (and other input attributes) to match a standalone input.

General input attributes

Following attributes are available for all inputs:

• name (character string, required) - input name. It acts as an identifier for a given input, and is required as such. Template cannot contain duplicate names. rapport inputs currently have custom naming conventions - see guess.input.name for details.

• label (character string) - input label. It can be blank, but it's useful to provide input label as rapport helpers use that information in plot labels and/or exported HTML tables. Defaults to empty string.

• description (character string) - similar to label, but should contain long description of given input.

• class (character string) - defines an input class. Currently supported input classes are: character, complex, factor, integer, logical, numeric and raw (all atomic vector classes are supported). Class attribute should usually be provided, but it can also be NULL (default) - in that case the input class will be guessed based on matched R object's value.

• required (logical value) - does the input require a value? Defaults to FALSE.

• standalone (logical value) - indicates that the input depends on a dataset. Defaults to FALSE.

• length (either an integer value or a named list with integer values) - provides a set of rules for input value's length. length attribute can be defined via:

  • an integer value, e.g. length: 10, which sets restriction to exactly 10 vectors or values.

  • named list with min and/or max attributes nested under length attribute. This will define a range of values in which input length must must fall. Note that range limits are inclusive. Either min or max attribute can be omitted, and they will default to 1 and Inf, respectively.

  IMPORTANT! Note that rapport treats input length in a bit different manner. If you match a subset of 10 character vectors from the dataset, input length will be 10, as you might expect. But if you select only one variable, length will be equal to 1, and not to the number of vector elements. This stands both for standalone and dataset inputs. However, if you match a character vector against a standalone input, length will be stored correctly - as the number of vector elements.

• value (a vector of an appropriate class). This attribute only exists for standalone inputs. Provided value must satisfy rules defined in class and length attributes, as well as any other class-specific rules (see below).

Class-specific attributes

character

• nchar - restricts the number of characters of the input value. It accepts the same attribute format as length. If NULL (default), no checks will be performed.

• regexp (character string) - contains a string with regular expression. If non-NULL, all strings in a character vector must match the given regular expression. Defaults to NULL - no checks are applied.

• matchable (logical value) - if TRUE, options attribute must be provided, while value is optional, though recommended. options should contain values to be chosen from, just like <option> tag does when nested in <select> HTML tag, while value must contain a value from options or it can be omitted (NULL). allow_multiple will allow values from options list to be matched multiple times. Note that unlike previous versions of rapport, partial matching is not performed.

numeric, integer

• limit - similar to length attribute, but allows only min and max nested attributes. Unlike length attribute, limit checks input values rather than input length. limit attribute is NULL by default and the checks are performed only when limit is defined (non-NULL).

factor

• nlevels - accepts the same format as length attribute, but the check is performed rather on the number of factor levels.

• matchable - ibid as in character inputs (note that in previous versions of rapport matching was performed against factor levels - well, not any more, now we match against values to make it consistent with character inputs).

See Also

rapport.meta rapport.info