How to write a rapport template
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
The syntax
<%= command %> <% command %>
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.
<%= data(ius2008) colnames(ius2008[1]) %> # That was not more complicated than just producing a string ("gender")
<%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."
<% 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
) 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.
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.
Example: rapport("t-test", ius2008, x = "leisure", y = "gender") # t-test will run with variables gender and leisure
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:
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:
<%= 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 :)
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.