
<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>RSP: A Brief Introduction</title>
  <meta name="author" content="Henrik Bengtsson">
  <meta name="keywords" content="R, RSP markup language, literate programming, reproducible research, report generator, Sweave, knitr, brew, noweb, TeX, LaTeX, Markdown, AsciiDoc, reStructuredText, Org-Mode, HTML, PDF">
  <style>

body {
  font-family: serif;
}

h1, h2, h3 {
  font-family: sans-serif;
  font-weight: normal;
}

section {
  font-size: 16pt;
}

h1 {
  -webkit-margin-before: 0.27em;
  -webkit-margin-after: 0.67em;
}

ul {
  padding-left: 2ex;
  list-style-position: outside;
}

li {
  margin-top: 0.75ex;
}

.remark-slide-content h1 { font-size: 140%; }
.remark-slide-content h2 { font-size: 100%; }
.remark-slide-content h3 { font-size: 90%; }

.remark-slide-content {
  font-size: 115%;
  /* Defaults: 1em 4em 1em 4em; */
  margin: 0ex;
  padding: 0em 3em 0em 3em;
}

.remark-code, .remark-inline-code {
  font-family: monospace;
  font-weight: bold;
  font-size: 90%;
}

img.screenshot-center {
   position: relative;
   bottom: 20%;
   width: 100%;
   box-shadow: 10px 10px 5px #888888;
}

img.screenshot-center-medium {
   position: relative;
   bottom: 20%;
   width: 70%;
   box-shadow: 10px 10px 5px #888888;
}

th {
   background-color: #f2f2f2;
}
tr:nth-child(even) {
   background-color: #f2f2f2
}

.blank {
  background-color: white;
}

td {
   width: 20%;
}
td:first-child {
   width: 15%;
}

#author {
  font-size: 150%;
}

.footnote-large {
  position: absolute;
  bottom: 3%;
  font-size: 120%;
}

.footnote-small {
  position: absolute;
  bottom: 5%;
  font-size: 80%;
}

  </style>
</head>
<body>
<textarea id="source" style="visibility: hidden">

# RSP: A Brief Introduction

by Henrik Bengtsson, NA


Available on <a href="https://cran.r-project.org/package=R.rsp">CRAN</a> since 2005 (first version ~2002):

```r
install.packages("R.rsp")
```

```r
> 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.

## Some usage
* PSCBS: PDF reports of copy-number segmentation results
* aroma-project.org: Interactive [Chromosome Explorer](http://aroma-project.org/data/reports/GSE8605/ACC,-XY,BPN,-XY,AVG,FLN,-XY,paired/ChromosomeExplorer.html) and [Array Explorer](http://www.aroma-project.org/data/reports/GSE8605/raw/ArrayExplorer.html)


	      
---
# Compiling RSP document into PDF, HTML, ...
```r
> rfile("http://example.org/vignette.tex.rsp")
RspFileProduct:
Pathname: vignette.pdf
File size: 258.71 kB (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
```r
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) %>
```

<br>

### Code snippets - mixture of RSP and text 
```
<% for (i in 1:3) { %>
 Step <%= 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 ...) %>
```

<br>

To achieve the same using noweb-style markup (e.g. Sweave and knitr) is tedious.



	      
---
# 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()
```r
> rcat("A random integer in [1,100]:
        <%=sample(1:100, size = 1)%>\n")
A random integer in [1,100]: 77
```

<br>

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

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

	      
---
# rfile() - end-to-end compilation
```r
> rfile("report.md.rsp", args = list(n = 50, model = "L1"))
RspFileProduct:
Pathname: report.html
File size: 42.54 kB (43564 bytes)
Content type: text/html
```

<br>

```r
> rfile("http://example.org/vignette.tex.rsp")
RspFileProduct:
Pathname: vignette.pdf
File size: 258.71 kB (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 (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

<img src="data:image/png;base64, " width=480>


	      
---
# Appendix
Session info:

```
R version 4.3.2 (2023-10-31)
Platform: x86_64-pc-linux-gnu (64-bit)
Running under: Ubuntu 22.04.3 LTS

Matrix products: default
BLAS:   /home/henrik/shared/software/CBI/_ubuntu22_04/R-4.3.2-gcc11/lib/R/lib/libRblas.so 
LAPACK: /usr/lib/x86_64-linux-gnu/lapack/liblapack.so.3.10.0

locale:
 [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C              
 [3] LC_TIME=en_US.UTF-8        LC_COLLATE=C              
 [5] LC_MONETARY=en_US.UTF-8    LC_MESSAGES=en_US.UTF-8   
 [7] LC_PAPER=en_US.UTF-8       LC_NAME=C                 
 [9] LC_ADDRESS=C               LC_TELEPHONE=C            
[11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C       

time zone: America/Los_Angeles
tzcode source: system (glibc)

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

other attached packages:
[1] R.devices_2.17.2  R.rsp_0.46.0      R.oo_1.26.0       R.methodsS3_1.8.2

loaded via a namespace (and not attached):
[1] compiler_4.3.2      tools_4.3.2         base64enc_0.1-4    
[4] digest_0.6.34       R.cache_0.16.0      Cairo_1.6-2        
[7] R.utils_2.12.3-9002
```

These slides were generated using `R.rsp::rfile()` in 0.06 secs.

</textarea>

<script src="https://remarkjs.com/downloads/remark-latest.min.js"></script>
<script>
var slideshow = remark.create({
  ratio: '4:3',
})
</script>

</body>
</html>
