inputs-deprecated: Deprecated Input Definition

Description Details


As of version 0.5, rapport relies on YAML syntax to define inputs. The following sections describe deprecated input definition syntax.


Input Specifications

Apart from template metadata, header also requires specification for template inputs. In most cases, inputs refer to variable names in provided dataset, but some inputs have special meaning inside rapport, and some of them don't have anything to do with provided dataset whatsoever. Most inputs can contain limit specification, and some inputs can also have a default value. At first we'll explain input specifications on the fly, and in following sections we'll discuss each part in thorough details. Let's start with a single dummy input specification:

* | numeric[1,6] | Numeric variable | A set of up to 6 numeric variables

Required Inputs

Asterisk sign (*) in front of an input name indicates a mandatory input. So it is possible to omit input (unless it's required, of course), but you may want to use this feature carefully, as you may end up with ugly output. If an input isn't mandatory,NULLis assigned to provided input name, and the object is stored in transient evaluation environment.

Input Name

rapport has its own naming conventions which are compatible, but different from traditional R naming conventions. Input name ("" in previous example) must start with an alphabet letter, followed either by other alphabet letters or numbers, separated with _ or .. For example, valid names are:, f00_bar, or Fo0_bar.input. Input name length is limited on 30 characters by default. At any time you can check your desired input name with function. Note that input names are case-sensitive, just like symbols in R.

Input Type

Input type is specified in the second input block. It is the most (read: "only") complex field in an input specification. It consists of type specification, limit specification and sometimes a default value specification. Most input types are compatible with eponymous R modes: character, complex, logical, numeric, or R classes like factor. Some are used as "wildcards", like variable, and some do not refer to dataset variables at all: boolean, number, string and option. Here we'll discuss each input type thoroughly. We will use term variable to denote a vector taken from a dataset (for more details see documentation for is.variable). All inputs can be divided into two groups, depending on whether they require a dataset or not:

Now we'll make a little digression and talk about input limits. You may have noticed some additional stuff in type specification, e.g. numeric[1,6]. All dataset inputs, as well as *string* and *numeric standalone inputs* can contain limit specifications. If you want to bundle several variables from dataset or provide a vector with several string/numeric values, you can apply some rules within square brackets in [a,b] format, where [a,b] stands for "from a to b inputs", e.g. [1,6] means "from 1 to 6 inputs". Limit specifications can be left out, but even in that case implicit limit rules are applied - for variables, as well as boolean and option inputs it's [1,1], for strings [1,256] and for number inputs [-Inf,Inf].

Dataset inputs will match one or more variables from a dataset, and check its mode and/or class. variable type is a bit different, since it matches any kind of variable (not to confuse with Any type), but it still refers to variable(s) from a provided dataset. Dataset inputs cannot have default value, but can be optional (just leave out * sign in front of input name). Note that if you provide more than one variable name in rapport function call, that input will be stored as a data.frame, otherwise, it will be stored as a variable (atomic vector).

Standalone inputs are a bit different since they do not refer to any variables from a dataset. However, they are more complex than *dataset inputs*, especially because they can contain default values.

Input Label and Description

Third block in input definition is an input label. While variable can have its own label (see label), you may want to use the one defined in input specifications. At last, fourth block contains input description, which should be a lengthy description of current input. Note that all the fields in input specification are mandatory. You can cheat, though, by providing a non-space character (e.g. a dot) as an input label and/or description, but please don't do that unless you're testing the template. Labels and descriptions are meant to be informative.

rapport documentation built on April 12, 2021, 1:06 a.m.