0.5, rapport relies on YAML
syntax to define inputs. The following sections describe
deprecated input definition syntax. 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:
*foo.bar | 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 ("foo.bar" 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:
foo.bar, 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
check.name 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:
factorclass)match.arg. The first value in a list
is the default one. 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.
numberandstringrespectively. They
can also contain limit specifications, but the limits are
treated in a slightly different manner.number[-2.58,3]will match any number within an
interval from -2.58 to 3. If the limit specification is
ommited, an implicit ones are assigned
([-Inf,Inf]. Limit specifications for string
inputs define the range of characters that provided
string can have, e.g.string[1,6]matches the
string with at least 1 and at most 6 characters. If
ommited, limit specifications for strings are implicitly
set to[1,256].numberandstringinputs can havedefault value, which can be
defined by placing=after type/limit
specification followed by default value. For instance,number[1,6]=3.14sets value3.14as
default. Note that for number inputs an additional check
will be applied to ensure that provided default number
belongs to an interval defined in the limit specification
([1,6]=7will throw an error). For string inputs,
the default valuestring=foosets "foo" as default
string value (note that you don't have to specify quotes
unless they are the part of the default string). Default
value will be checked to ensure that its length falls
within the interval provided in the limit specification.TRUEorFALSEvalues. The specified value
is the default one. They cannot contain limit
specification, but implicitly the limits are set to[1,1].match.argfunction. That means that you could
only choose one value from a list. Partial matches are
allowed, and the first value inoptionlist is the
default one. Just like inbooleaninputs, limits
are implicitly set to[1,1].Input Label and Description
Third block in input definition is an input label. While
variable can have its own label (see
rp.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.