Introductory slides on RSP

Henrik Bengtsson

September 18, 2013

Availability: install.packages("R.rsp") from CRAN

Since: 2002

RSP: Hello world!

> library(R.rsp)

> rcat("A random number: <%=sample(1:10, size=1)%>")
A random number: 7

Objectives

• Dynamically generate documents and reports (and web/help pages).
• Quickly turn your favorite static report template into a dynamic one.
• Support all formats, e.g. LaTeX, Markdown, HTML, …
• Supplement and/or complement Sweave, knitr, …
• Mix and match code and text however you want.
• Simplify sharing of template and output documents.
• Use for R package vignettes (since R 3.0.0).

Some usage

• PSCBS: PDF reports of copy-number segmentation results
• aroma-project.org: Interactive Chromosome Explorer and Array Explorer
• Haplin GUI - genetic association analyses
• googleVis - Google Chart Tools from R

Compiling RSP document into PDF, HTML, …

> rfile("http://example.org/vignette.tex.rsp")
RspFileProduct:
Pathname: vignette.pdf
File size: 264925 bytes
Content type: application/pdf
Metadata 'title': 'Dynamic document creation using RSP'
Metadata 'keywords': 'Literate programming, HTML, PDF'
Metadata 'author': 'Henrik Bengtsson'

Very simple idea: Translate RSP to R and evaluate

1. RSP document

Title: Example
Counting:<% for (i in 1:3) { %>
 <%=i%>
<% } %>

2. R script

cat("Title: Example\nCounting:")
for (i in 1:3) {
  cat(" ")
  cat(i)
}

3. RSP output

Title: Example
Counting: 1 2 3

RSP Markup Language

1. RSP comments (<%-- ... --%>)

2. RSP preprocessing directives (<%@ ... %>)

3. RSP code expressions (<% ... %>)

RSP Markup Language

1. RSP comments (<%-- ... --%>)

<%-----------------------------
  Compile to PDF:
  R.rsp::rfile("report.tex.rsp")
  ------------------------------%>
\documentclass{report}
...

RSP comments drop anything within, e.g. private notes, other RSP constructor (nested comments too) and will never be part of the output.

RSP Markup Language

2. RSP preprocessing directives (<%@ ... %>)

Including local and online files

<%@include file="http://example.org/QC.tex.rsp"%>

Conditional inclusion

<%@ifeq version="devel"%>
  <%@include file="templates/QA-devel.tex.rsp"%>
<%@else%>
  Quality assessment is still under development.
<%@endif%>

Meta data

<%@meta title="Example"%>
\hypersetup{pdftitle=<%@meta name="title"%>}
\title{<%@meta name="title"%>}

RSP preprocessing directives are independent of R, i.e. they would look the same with RSP for Python.

RSP Markup Language

3. RSP code expressions (<% ... %>)

Insert value of evaluated R expressions

<%= sample(1:100, size=1) %>

Code snippets - mixture of RSP and text

<% for (i in 1:3) { %>
 <%=i%>
<% } %>

Looping over mixtures of code and text

<% fit <- segmentByPairedPSCBS(data) %>

\section{Segmentation results}

<% for (chr in 1:23) { %>
  \subsection{Chromosome <%=chr%>}

  <% fitT <- extractChromosome(fit, chr) %>
  PSCBS identified <%=nbrOfSegments(fitT)%> segments
  on Chr. <%=chr%>.

  ...
<% } # for (chr ...) %>

It is rather tedious to achieve the same using noweb-style markup, e.g. Sweave and knitr.

RSP template functions

<%-- RSP TEMPLATES --%>
<% chromosomeSummary <- function(chr) { %>
  <% fitT <- extractChromosome(fit, chr) %>
  PSCBS identified <%=nbrOfSegments(fitT)%> segments
  on Chr. <%=chr%>.
  ...
<% } %>

<%-- DOCUMENT --%>
...
<% for (chr in 1:23) { %>
  \subsection{Chromosome <%=chr%>}
  <% chromosomeSummary(chr) %>
<% } # for (chr ...) %>

R.rsp package - RSP engine for R

rcat() - RSP version of cat()

> rcat("A random integer in [1,100]:
        <%=sample(1:100, size=1)%>\n")
A random integer in [1,100]: 77

rsource() - RSP version of source()

Consider RSP file ‘count.rsp’ (think ‘count.R’):

Counting:<% for (i in 1:10) { %>
  <% Sys.sleep(0.3) %><%=i%>
<% } %>.

Running this RSP script gives:

> rsource("count.rsp")
Counting: 1 2 3 4 5 6 7 8 9 10.

rfile() - end-to-end compilation

> rfile("report.md.rsp", args=list(n=50, model="L1"))
RspFileProduct:
Pathname: report.html
File size: 43564 bytes
Content type: text/html

> rfile("http://example.org/vignette.tex.rsp")
RspFileProduct:
Pathname: vignette.pdf
File size: 264925 bytes
Content type: application/pdf
Metadata 'title': 'Dynamic document creation using RSP'
Metadata 'keywords': 'Literate programming, HTML, PDF'
Metadata 'author': 'Henrik Bengtsson'

Including graphics (using R.devices package)

RSP-embedded LaTeX

\includegraphics{<%=toPDF("MyFigure,yeah,cool", {
 curve(dnorm, from=-5, to=+5)
})%>}

generates the image file and outputs

\includegraphics{MyFigure,yeah,cool}

which appears as

Appendix

Session info:

R version 3.0.2 RC (2013-09-17 r63944)
Platform: x86_64-w64-mingw32/x64 (64-bit)

locale:
[1] LC_COLLATE=C                          
[2] LC_CTYPE=English_United States.1252   
[3] LC_MONETARY=English_United States.1252
[4] LC_NUMERIC=C                          
[5] LC_TIME=English_United States.1252    

attached base packages:
[1] stats     graphics  grDevices utils     datasets  methods   base     

other attached packages:
[1] R.utils_1.27.1    R.devices_2.6.1   R.rsp_0.9.24      R.oo_1.15.1      
[5] R.methodsS3_1.5.1

loaded via a namespace (and not attached):
[1] base64enc_0.1-1 tools_3.0.2    

This report was automatically generated using rfile() of the R.rsp package. Total processing time after RSP-to-R translation was 0.12 secs.