How to write a rapport template

library(devtools)
install_github('pander','Rapporter')  # installing pander package
install_github('rapport','Rapporter') # installing rapport package

library(rapport)   # call in rapport package
library(pander)    # call in pander package

For R users producing a template wouldn’t need too much extra skills to gain. On the other hand, there are still some things which one should look at on while writing one:

Templates have to be written in brew syntax. The most important to note in connection with that is the two kind of special tags which this kind of syntax uses:

<%= command %>
<% command %>

These two codes look pretty the same and actually doesn’t differ too much, but still in a crucial way.

Both of them are good for running R commands, but the first will run each expression after each other and send the markdown format result to the interface. The code in the belly of the second tag is to be used for unprinted results and mostly for conditional statements or loops. It is strongly advised to use the prior tag for even expressions without a result to use the cache and improved error handling.

To see the use-cases of the tags a little bit clearer, let me show you some basic commands as an example with loading a built in database of the rapport package, the Internet Usage Survey in 2008:

<%=
data(ius2008)
colnames(ius2008[1])
%>       #  That was not more complicated than just producing a string ("gender")

Let’s see how to use the tag without the equal sign:

<%if (colnames(ius2008[1])=="gender") { %>
The first variable of the ius2008 database contains the responder's gender.
<% } %>   # The following sentence will be written on the interface we use: "The first variable of the ius2008 database contains the responder's gender."

Next to that we can obviously use additional command like in R:

<% if (colnames(ius2008[1])=="gender") { %>
The first variable of the ius2008 database contains the responder's gender.
<% } else { %>
We do not know what kind of information the first variable of the ius2008 database contains.
<%}%>   #  In this case only the second sentence will be shown.

In order to make the template enable to run via R, and to provide some meta-tags, filling in with some information about itself, that needs to have a beginning part, called Header. The Header part also has a beginning (<!--head) and a finishing (head-->) tag like the others elaborated above.

The Header contains some mandatory and some optional fields. With the help of that, one can show his/her template’s most important properties and specify the fields, which are necessary to run that.

As a mandatory part one has to give a Title, an Author and a short Description about the template. Sometimes the Title tells everything about the template for most of the users but it could be useful also to elaborate that, especially in complex templates.

The writer can optionally extend the amount of the information with giving his/her email address in case to exchange the experience with the users. There is also a possibility to give one or more example(s) how to run it in R. An example of the example is:

Example:  rapport("t-test", ius2008, x = "leisure", y = "gender")   # t-test will run with variables gender and leisure

The aboved listed information are mostly important for the users (and the example also for the developper to easily test the new template with tpl.example function), but we still need to specify some other things to tell R which variables to use inside the template body.

It could happen that running a template would require a specific dataset or a package. In the Header one can set that in a new line, started by Packages/Data required. In the package line, one should write the names of the required packages separated by a comma, but don’t forget, the chosen package should be installed on the computer before we want to use that in the template.

The Data required command works like a boolean type, we just set it TRUE if we needed a specific dataset and later specify that while running the template. A short example of them looks like:

Packages:        nortest   # nortest package is needed to run the template
Data required:   TRUE      # data should be specified in the R code

With this part we slightly touched the field and arrived to the input specifications, but while the dataset and the packages are optional to be set as required, variables are always likely to be specified. To give some spice to it, next to variables there is a possibility to set any parameters from the template as optional.

Each lines contain 4 parts, separated by a pipe character (|). In the first part one should specify the name of the input, what will have to be written after into the R code to specify the variable or the parameter we want to use.

In the second part of the line can be set the type of the parameter and which variables are required to use, thus they have to be specified in the R code while running the template. We can set that with a star (*). In the lines of the variables we don’t want to set as required, we should just leave out the star sign.

There are different types of variables and parameters as well. In the case of an optional feature of the template we should set that a default FALSE there, which can be overwritten from the command line by passing TRUE to that field.

To make it a little bit clearer let me show you some examples of the specifications from the t-test.tpl:

x        | *numeric      | X variable      | Dependent (response variable)      # required numeric variable
mu       | number[1,10]  | Mean value      | Mean value for one-sample t-test   # optional to be passed to R
paired   | FALSE         | Paired t-test   | Carry out paired t-test or not     # to be used in conditional statements

The last two parts can be useful in the template body to have conditional expressions etc.

As a summary let’s see the header of t-test.tpl in one piece:

<!--head
Title:          t-test Template
Author:         Aleksandar Blagotić
Description:    A t-test report with table of descriptives, diagnostic tests and t-test specific statistics.
Packages:       nortest
Data required:  TRUE
Example:        rapport("t-test", ius2008, x = "leisure", y = "gender")
                rapport("t-test", ius2008, x = "leisure", mu = 3.2)

x         | *numeric          | X variable          | Dependent (response) variable
y         | variable          | Y variable          | Independent variable (factor, or another numeric)
alter     | two.sided,less,greater | Alternative hypothesis | Whether two-sided, greater or less variant will be applied
mu        | number[1,10]      | Mean value          | Mean value for one-sample t-test
paired    | FALSE             | Paired t-test       | Carry out paired t-test or not
var.equal | FALSE             | Variance equality   | Equal variances assumed: choose automatically or not
ci.level  | number[1,10]=0.95 | Confidence interval | Confidence interval level
head-->

Formatting the text

After we have seen above how to compile the header of the template and also checked out the brew syntax, it could be useful to look at some practical way to format our template, and see which tags of Pandoc’s markdown help us to present the template in a nice way.

Title

Formatting the title one could have several levels. All of them lies on the beginning of the line in ATX stlye. For example:

# Top header
## Subtitle
### Minor title
#### And even smaller parts up to 6 # signs

Text

There are several ways to make the text nicer and easier to read. For example we can emphasize part of that or add links which direct us to other homepages. We were using these tools to extend our templates and here I will show how you can also do that with yours.

_If you put the text in the belly of two underscore, it will be italicized_ and [You can connect a part of the text with a homepeage, with writing it between two scared brackets and the link in parenthesis after. Most of the links in the templates will direct you to one article on wikipedia](www.wikipedia.org)

So (finally) how to write a template?
After we successfully run over the most important special properties of the template-writing now we can start to produce one! In this example I did not focus on using complicated R commands or making an extravagant outlook, the aim was rather to show how full template looks and to give a summary.


So let’s see how it looks as a template:

<!--head
Title:         Example Template
Author:        Rapporter Development Team
Description:   This example will hopefully help you to understand and summarize the staff you red in the blogpost
Data required: TRUE
Example:       rapport("example-template", ius2008, x = "leisure", pi.value=TRUE)
x              | *numeric | X variable | Observed variable
pi.value       | FALSE    | pi         | pi 
head-->

<%=
mean.of.x <- mean(na.omit(x))
%>

# Introduction

In this example of a [template](http://en.wikipedia.org/wiki/Template) the user can see al the type of formatting and programming tools which was written in the _blogpost_.

# The main part

## Calculating the mean

We may want to compute the average of our observed variable. That was calculated after the Header, and we can just tell R to lay that here: <%=mean.of.x%>

## Show the value of pi if in the command we set that option as TRUE

<%=ifelse(pi.value, pi, "We are not interested in the value of the pi")%>

### And one important note to the end, you should leave a blank line at the and of the template :)