How to write a rapport template

[This article was first published on rapporter, and kindly contributed to R-bloggers]. (You can report issue about the content on this page here)
Want to share your content on R-bloggers? click here if you have a blog, or here if you don't.

This post will show an introduction for the users how to produce a template, so how to produce similar results, like those one can see on rapport’s homepage or in our forthcoming reporting web application.

The post was written from the view of a Windows user, if problems were came up because you use an other operating system, don’t hesitate to contact us to get the solutions for that. As it is widely known, to run the templates we use R. Writing a template I would suggest to use Notepad++, although the rest of the development team swear on Emacs/ESS 🙂

Just to avoid annoying little mistakes I might note, one should be careful with some settings in the IDE:
  • Encoding should be UTF-8 without BOM and 
  • End-of-line characters has to be set to Unix.
At the first sight the template (without the Header, which will be elaborated in a later stage of this post) seems like a “normal text filled in with R commands”. This impression doesn’t exist without reason. The text parts help the user to understand the statistical method, interpret the results or sometimes just broaden the user’s knowledge.

The aim of a template and our web application is to present a user-friendly interface and output for a wide scale of people. Thus it can be available for the less R-friendly users and for them who already digged deeply into the programming field as well.

What do you need to being able to write or run a template?

Before starting to elaborate the way of writing a template, let me write briefly which steps have to be done before starting to write one. As a reason, that the templates run in R, basically it is unavoidable that program to be installed. Moreover it is advisable to check which version, because the older version do not support some new features. These needed packages are the rapport and the pander. There are various ways to install them (if we didn’t do that before), the simplest one beside heading to CRAN is to do that directly from GitHub:

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

As R users probably know, installing is not enough for the program to use a package, we have to tell it each time which package to use. The commands for that are:

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

These are the preparations which are inevitable to be done before we start to begin producing a template, although you might also consider installing Pandoc to produce HTML, pdf, docx, odt and other popular formats.

Specialties

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:

The syntax

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.

Header

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 :)

To leave a comment for the author, please follow the link and comment on their blog: rapporter.

R-bloggers.com offers daily e-mail updates about R news and tutorials about learning R and many other topics. Click here if you're looking to post or find an R/data-science job.
Want to share your content on R-bloggers? click here if you have a blog, or here if you don't.

Never miss an update!
Subscribe to R-bloggers to receive
e-mails with the latest R posts.
(You will not see this message again.)

Click here to close (This popup will not appear again)