---
title: "RNA-seq Analysis 1"
author: "Pietà Schofield"
subtitle: Introduction to R, RStudio and Rmarkdown 
output:
  html_document:
    code_folding: show
    fig_caption: yes
    highlight: textmate
    theme: spacelab
    toc: yes
    toc_depth: 3
    toc_float:
      collapsed: no
      smooth_scroll: yes
  pdf_document:
    toc: yes
    toc_depth: '3'
---


```{r setup,echo=FALSE,include=FALSE}
require(RefManageR)
BibOptions(style="html",longnamesfirst=F)
#if(!file.exists(".pieta.bib")){
# download.file("http://www.compbio.dundee.ac.uk/user/pschofield/biblio.bib",".pieta.bib")
#}
#bib <- ReadBib(".pieta.bib",check=FALSE)
require(knitr)
opts_chunk$set( message=F, warning=F, comment=NA)
#
# This little bit of trickery is rather complex knitr-foo thanks to Ramnath Vaidyanathan
#
# http://ramnathv.github.io/posts/verbatim-chunks-knitr/index.html
#
# It enables code chunks to be included with the surrounding brackets and options
# for illustrative purposes
#
knitr::opts_chunk$set(tidy = F)
knit_hooks$set(source = function(x, options){
  if (!is.null(options$verbatim) && options$verbatim){
    opts = gsub(",\\s*verbatim\\s*=\\s*TRUE\\s*", "", options$params.src)
    bef = sprintf('\n\n    ```{r %s}\n', opts, "\n")
    stringr::str_c(
      bef, 
      knitr:::indent_block(paste(x, collapse = '\n'), "    "), 
      "\n    ```\n"
    )
  } else {
    stringr::str_c("\n\n```", tolower(options$engine), "\n", 
      paste(x, collapse = '\n'), "\n```\n\n"
    )
  }
})
#
# a little bit of R from Yihui Xieto put in verbatim inline R
#
# http://stackoverflow.com/questions/20409172/how-to-display-verbatim-inline-r-code-with-backticks-using-rmarkdown
#
urlStub <- "http://www.compbio.dundee.ac.uk/user/pschofield/Projects/teaching_pg/"
rinline <- function(code) {
  sprintf('``` `r %s` ```', code)
}
```

- [Return to the  main page](http://www.compbio.dundee.ac.uk/user/pschofield/Projects/teaching_pg)
- [Full Rmarkdown script for this workshop](http://www.compbio.dundee.ac.uk/user/pschofield/Projects/teaching_pg/code/RStudioServer.Rmd)

# RStudio 

RStudio is designed to make literate programming and producing documented analysis relatively simple and painless. There are a few options to achieve this the main one is provided by the package [knitr](http://yihui.name/knitr/), which enable the writing of documents in a markup language such as [HTML](https://en.wikipedia.org/wiki/HTML) , [LaTeX](https://en.wikipedia.org/wiki/LaTeX) or [markdown](https://en.wikipedia.org/wiki/Markdown), with embedded code chunks, that can then be compiled into a final document in a range of formats such as portable document format (PDF), Microsoft Word (docx) or HTML. During the compilation process code chunks are executed and output such as figures are generated and incorporated into the final document.

In this course we will focus on the use of [Rmarkdown](http://rmarkdown.rstudio.com), there is extensive documentation available as [http://rmarkdown.rstudio.com](http://rmarkdown.rstudio.com). 
We will also be using RStudio via a web browser interface to RStudio Server.

## RStudio Server

In a web browser such as Chrome, FireFox or Safari navigate to [http://rstudio.compbio.dundee.ac.uk](http://rstudio.compbio.dundee.ac.uk:8787) the Life Sciences instance of RStudio Server and log in with your cluster id and password.

## Rmarkdown Document

You can start a new `rmarkdown` document from with-in RStudio from the **File - New File - R Markdown...** menu option 

![R markdown menu](`r paste0(urlStub,"/figures/openmarkdown.png")`)

that opens the dialogue box below

![R markdown dialogue box in RStudio](`r paste0(urlStub,"/figures/rmarkdowndialogue.jpg")`)

Select Document option on the left hand side and the PDF option on the right hand side, fill in a title of your choice and your name and a  to create a demo rmarkdown document, that will open in the RStudio editor panel. Without making any changes to this file you can compile it into a PDF by clicking the **Knit PDF** button on the editor panel button bar. You will be prompted to save the file, so you should chose and name and location for the file.

![R markdown knit PDF button](`r paste0(urlStub,"/figures/knitbutton.jpg")`)

If you examine the file in the editor you will see it is structured in a particular ways. 

# Rmarkdown Document Structure 

## YAML header

In recursive geek speak [YAML](https://en.wikipedia.org/wiki/YAML) is an acronym that stands for **Y**AML **A**in't **M**arkup **L**anguage. It is a header block of parameters used through out the document compilation process. It uses a standard format for many programming and markup languages, though the permissable option vary. It is separated from the rest of the document being surrounded by three dashes `---`

For example the YAML block for this document is 

```
---
title: 'RNA-seq Analysis 1: Introduction to Bioconductor'
author: "Pietà Schofield"
output: 
  html_document:
    fig_caption: yes
    toc: yes
    toc_depth: 2
    toc_float:
      collapsed: no
      smooth_scroll: yes
    code_folding: show
    css: workshop.css
---
```

There are lines in the `output` section of the above YAML that are not going to explain be explained at here, however RStudio will create a simple YAML for the output type you selected during the dialogue to generate the document. RStudio also will alter the YAML if you select to Knit the document into a different output format. So indepth understanding of YAML is not needed to get going with rmarkdown. **Note Side floating

## Code Chunks

Sections of R (and other language) code can be embedded in the document surrounded by the three back tick delimites as in the example below. 

```{r chuckName, fig.caption="Some Random Stuff", verbatim=TRUE, eval=FALSE}
#
# Plot anything R can plot
#
plot(1:10+rnorm(10),1:10+rnorm(10),pch="x", 
     xlab="expected", ylab="measured",main="Demo Plot")
#
# One option is to just send it to the default device and knitr
# captures it and put it in a temporary place
#
abline(0,1,col="red")
# 
# alternatively write it to a file and link to the file in the markdown
#
```

The first line holds paramters or **chunk options** between the parentheses that control how the chunk will be processed during compilation and how the output from the chuck if it is executed will be incorporated and formated in the document. For example whether the chunk is executed is controlled by the **eval** option and whether the chunk is displayed in the output document is controlled by the **echo** option

## Markdown Text

The rest of the document is in markdown and certain codes will produce various formatting styles in the output document. For example various numbers of # characters at the start of a line control heading levels * or _ will control italic and bold text. 

## Graphics

The code chunk above produces a graph in the output. It is possible to change the code in the chunk to change the figure. It is also possible to set chunk options  so that only the graph is displayed and not the code, or only the code and not the graph.

```{r plotgraph, fig.cap="Some Random Stuff"}
#
# Plot anything R can plot
#
plot(1:10+rnorm(10),1:10+rnorm(10),pch="x", 
     xlab="expected", ylab="measured",main="Demo Plot")
#
# One option is to just send it to the default device and knitr
# captures it and put it in a temporary place
#
abline(0,1,col="red")

```

## Useful R Commands 

There are several useful R commands that will be used extensively over the course of the workshops, as always with R there are possibly too many ways of doing these things, but these are my favourite ways and so these are the ones I have used in the workshop rmarkdown scripts so I introduce them here. 

```{r usefulFunction}
fileName <- "/homes/pschofield/public_html/Projects/teaching_pg/index.html"
# parsing filenames
basename(fileName)
dirname(fileName)

# constructing strings
paste0("The file name is '",basename(fileName),
       "' and the full directory name is '",dirname(fileName),"'")

# listing files in directories
fileNames <- list.files(dirname(fileName),pattern=".*")
indexFile <- list.files(dirname(fileName),pattern=".*html$")
fullIndexFile <- list.files(dirname(fileName),pattern=".*html$",full.names = T)

# finding items in vectors
grepl("html$",fileNames)
grep("html$",fileNames)
which(!grepl("html$",fileNames))

# editing text programmatically
gsub("^index","myindex",fileNames)
```

## Task 

Create an rmarkdown document that will compile to PDF. 

- Alter the document to hide the code that displays the summary of the car dataset.
- Alter the document to add a table of contents.
- Add a code chunk to the document to use the `head()` function to display the first 10 items 
  in the pressure data frame.
- Add a final section heading and code chunk using the `sessionInfo()` function to include the R
  configuration information in the document.


# Session Info

```{r session, echo=FALSE}
sessionInfo()
```



