rapport (version 0.51)

tpl.inputs: 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

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

Arguments

fp

a template file pointer (see tpl.find 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 |code{R} object provided indataargument inrapportcall. Currently,rapportsupports onlydata.frameobjects, but that may change in the (near) future.
• standalone inputs- the inputs that do not depend on the dataset. The user can just provide anRobject of an appropriate class (and other input attributes) to match astandaloneinput.

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.rapportinputs currently have custom naming conventions - seeguess.input.namefor details.
• label(character string) - input label. It can be blank, but it's useful to provide input label asrapporthelpers use that information in plot labels and/or exported HTML tables. Defaults to empty string.
• description(character string) - similar tolabel, 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,numericandraw(all atomic vector classes are supported). Class attribute should usually be provided, but it can also beNULL(default) - in that case the input class will be guessed based on matchedRobject's value.
• required(logical value) - does the input require a value? Defaults toFALSE.
• standalone(logical value) - indicates that the input depends on a dataset. Defaults toFALSE.
• length(either an integer value or a named list with integer values) - provides a set of rules for input value's length.lengthattribute can be defined via:
  • an integer value, e.g.length: 10, which sets restriction to exactly 10 vectors or values.
  • named list withminand/ormaxattributes nested underlengthattribute. This will define a range of values in which input length must must fall. Note that range limits are inclusive. Eitherminormaxattribute can be omitted, and they will default to1andInf, respectively.
  IMPORTANT!Note thatrapporttreats input length in a bit different manner. If you match a subset of 10 character vectors from the dataset, input length will be10, as you might expect. But if you select only one variable, length will be equal to1, 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 inclassandlengthattributes, 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 aslength. IfNULL(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 toNULL- no checks are applied.
• matchable(logical value) - ifTRUE,optionsattribute must be provided, whilevalueis optional, though recommended.optionsshould contain values to be chosen from, just liketag does when nested inHTML tag, whilevaluemust contain a value fromoptionsor it can be omitted (NULL).allow_multiplewill allow values fromoptionslist to be matched multiple times. Note that unlike previous versions ofrapport, partial matching is not performed.

numeric, integer

• limit- similar tolengthattribute, but allows onlyminandmaxnested attributes. Unlikelengthattribute,limitchecks input values rather than input length.limitattribute isNULLby default and the checks are performed only whenlimitis defined (non-NULL).

factor

• nlevels- accepts the same format aslengthattribute, but the check is performed rather on the number of factor levels.
• matchable-ibidas in character inputs (note that in previous versions ofrapportmatching was performed against factor levels - well, not any more, now we match against values to make it consistent withcharacterinputs).