Computational essays

http://blog.stephenwolfram.com/2017/11/what-is-a-computational-essay/

There are basically three kinds of things [in a computational essay]:

• First, ordinary text (here in English).
• Second, computer input.
• And third, computer output.

And the crucial point is that these three kinds all work together to express what’s being communicated.

Rmarkdown

• Interleaved R input and output together with your narative.

• In R we use Rmarkdown which combines markdown with R input and rendered output.

• We can (depending on system install) output to html, pdf and MS Word files (plus more, e.g. power point slides).

• This implies that we can make both static and dynamic documents, including tables, pictures and mathematical formulae.

Chunks

We can include R code (or code from other languages, e.g. python, css or others) in the document.

We do this by inserting chunks in the markdown document

```{r NAME, CHUNK OPTIONS}
R code that is evaluated as in an ordinary (interactive) R session
If the code produces any output (table, plot or other) it is outputtet below the chunk
```

We can insert chunks in different ways:

• Using the add chunk in the editor (green C with a plus)
• Menu: Code > Insert Chunk
• Keyboard shortcuts:
  • Windows and Linux: Ctrl + Alt + i
  • Mac: Option + Command + i

Setup knitr

The first chunk called setup, and it will specify the default behaviour for the remaining chunks in the documents. There are many parameters to tune:

Chunk options

The description of the various options is available at Yihui Xie’s webpage

The most relevant ones are (default first):

• eval = TRUE/FALSE: Evaluate the code? Can also be numeric, e.g. eval = 1:3 only evaluates the first three lines. This can also be negative, e.g. eval = -2 skips line two.
• include = TRUE/FALSE: Should the output be included in the document?
• echo = TRUE/FALSE: Should the input be included in the document? Can also be numeric.
• message = TRUE/FALSE: Should messages be included?
• warning = TRUE/FALSE: Should warnings be included?
• results = 'markup', 'asis', 'hold', 'hide'. The 'hide' options suppress the results and 'asis' do not format the output.
• error = FALSE/TRUE: Should errors be allowed (if TRUE errors are allowed - if FALSE errors stop the compiling).

Global options

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE, message = FALSE, comment = NA, 
                      fig.width = 10, warning = FALSE, error = TRUE)
```

By setting the above line in the beginning of the document, these values applies as default values for all chunks in the document. However, all options can be overwritten locally.

Inline code

When we want to format code in tt-font, we simply enclose it in `ticks`.

If we want to output from R, we simply add a r in the beginning, e.g. 2+3 = 5, which is given as `r 2+3`.

This can be usefull in case we have a report we want to compile and some of the summary data is needed in the plain text, e.g. the number of observations or similar:

The number of cars in the dataset mtcars is 32, which was written as `r nrow(mtcars)`.

Typesetting is intuitive

# This is a section header

## With a subsection below it

markdown syntax

The syntax behind this document format is known as markdown - hence almost everything that works in markdown works in Rmarkdown.

Text formatting 
------------------------------------------------------------

*italic*  or _italic_
**bold**   __bold__
`code`
superscript^2^ and subscript~2~

Headings
------------------------------------------------------------

# 1st Level Header

## 2nd Level Header

### 3rd Level Header

Lists
------------------------------------------------------------

*   Bulleted list item 1

*   Item 2

    * Item 2a

    * Item 2b

1.  Numbered list item 1

1.  Item 2. The numbers are incremented automatically in the output.

Links and images
------------------------------------------------------------

<http://example.com>

[linked phrase](http://example.com)

![optional caption text](path/to/img.png)

Tables 
------------------------------------------------------------

First Header  | Second Header
------------- | -------------
Content Cell  | Content Cell
Content Cell  | Content Cell

How the process is done

YAML header

Yet Another Meta Language

---
title: "Rmarkdown"
author: "Torben Tvedebrink"
date: "May 11, 2021"
output: html_document
---

Formatting R objects for nice output

There are several such packages that extents knitr and Rmarkdown. One is pander (the engine converting Rmarkdown to its output format is pandoc). It works like this

library(pander)

tab <- data.frame(
  species = c("ex", "niv"), 
  mean_temp = c(25.7571428571429, 21.71875), 
  mean_pps = c(85.5857142857143, 61.0375))

tab

##   species mean_temp mean_pps
## 1      ex  25.75714 85.58571
## 2     niv  21.71875 61.03750

pander(tab)

?pander
methods(pander)

##  [1] pander.anova*           pander.aov*             pander.aovlist*        
##  [4] pander.Arima*           pander.call*            pander.cast_df*        
##  [7] pander.character*       pander.clogit*          pander.coxph*          
## [10] pander.cph*             pander.CrossTable*      pander.data.frame*     
## [13] pander.data.table*      pander.Date*            pander.default*        
## [16] pander.density*         pander.describe*        pander.ets*            
## [19] pander.evals*           pander.factor*          pander.formula*        
## [22] pander.ftable*          pander.function*        pander.glm*            
## [25] pander.Glm*             pander.gtable*          pander.htest*          
## [28] pander.image*           pander.irts*            pander.list*           
## [31] pander.lm*              pander.lme*             pander.logical*        
## [34] pander.lrm*             pander.manova*          pander.matrix*         
## [37] pander.microbenchmark*  pander.name*            pander.nls*            
## [40] pander.NULL*            pander.numeric*         pander.ols*            
## [43] pander.orm*             pander.polr*            pander.POSIXct*        
## [46] pander.POSIXlt*         pander.prcomp*          pander.randomForest*   
## [49] pander.rapport*         pander.rlm*             pander.sessionInfo*    
## [52] pander.smooth.spline*   pander.stat.table*      pander.summary.aov*    
## [55] pander.summary.aovlist* pander.summary.glm*     pander.summary.lm*     
## [58] pander.summary.lme*     pander.summary.manova*  pander.summary.nls*    
## [61] pander.summary.polr*    pander.summary.prcomp*  pander.summary.rms*    
## [64] pander.summary.survreg* pander.summary.table*   pander.survdiff*       
## [67] pander.survfit*         pander.survreg*         pander.table*          
## [70] pander.tabular*         pander.ts*              pander.zoo*            
## see '?methods' for accessing help and source code

• https://cran.r-project.org/package=pander
• https://cran.r-project.org/web/packages/pander/vignettes/pandoc_table.html

?pandoc.table

pander(tab, justify = c('right', 'center', 'left'))

pander(tab, 
       justify = c('right', 'center', 'left'), 
       emphasize.strong.cols = 2)

pander(tab, digits = 5)

Things not mentioned

• Caching
• Appendixing
• Going from Rmarkdown to R script (purl)
• Going from R script to Rmarkdown (spin)
• Child documents
• Knit with parameters
• The two-way workflow between R Markdown and Word with redoc
• …

Further readings

https://blog.rstudio.com/2021/04/15/2021-spring-rmd-news/