R: Template Inputs

rapport.inputs {rapport} | R Documentation

## 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 `symbol`s 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`

[Package rapport version 1.0 Index]