---
title: "Project Report Title"
author: "First Last"
date: last-modified
format:
  html:
    theme: cosmo # also try flatly or lumen
    toc: true
    toc-depth: 3
    toc-location: left
    number-sections: true
    code-fold: false
    code-tools: true
    fig-cap-location: bottom
    df-print: kable
embed-resources: true
bibliography: bibtex.bib
---

## Quarto Overview

Quarto combines markdown (an easy to write plain text format) with embedded
R code chunks. When compiling Quarto documents, the code components can be
evaluated so that both the code and its output can be included in the final
document. This makes analysis reports highly reproducible by allowing to automatically
regenerate them when the underlying R code or data changes. Quarto
documents (`.qmd` files) can be rendered to various formats including HTML and
PDF. The R code in an `.qmd` document is processed by `knitr`, while the
resulting `.md` file is rendered by `pandoc` to the final output formats
(_e.g._ HTML or PDF). Historically, Quarto is an extension of the older
`Sweave/Latex` environment. Rendering of mathematical expressions and reference
management is also supported by Quarto using embedded Latex syntax and
Bibtex, respectively. A new and related publishing environemt is [Quarto](https://quarto.org/docs/tools/neovim.html) (not covered here).

## Quick Start

### Install Quarto

To work with this tutorial, the `rmarkdown` package needs to be installed on a system. 

```{r install_rmarkdown}
#| eval: false
install.packages("quarto")
```

### Initialize a new Quarto (`qmd`) script

To minimize typing, it can be helful to start with a Quarto template ([here](https://girke.bioinformatics.ucr.edu/GEN242/tutorials/quarto/quarto_index.html#metadata-section)) and
then modify it as needed. Note the file name of a Quarto scirpt needs to
have the extension `.qmd`. The template files for the following exercises are available 
here:

+ Quarto sample script: [`sample.qmd`](https://raw.githubusercontent.com/tgirke/GEN242/refs/heads/main/tutorials/quarto/sample.qmd)
+ Bibtex file for handling citations and reference section: [`bibtex.bib`](https://raw.githubusercontent.com/tgirke/GEN242/refs/heads/main/tutorials/quarto/bibtex.bib)

Users want to download these files, open the `sample.qmd` file with their preferred R IDE 
(_e.g._ RStudio, Nvim-R-Tmux or emacs), initilize an R session and then direct their R session to 
the location of these two files.


### Metadata section

The metadata section (YAML header) in an Quarto script defines how it will be processed and 
rendered. The metadata section also includes both title, author, and date information as well as 
options for customizing the output format. For instance, PDF and HTML output can be defined 
with `pdf_document` and `html_document`, respectively. 

```
---
title: "Project Report Title"
author: "First Last"
date: last-modified
format:
  html:
    theme: cosmo # also try flatly or lumen
    toc: true
    toc-depth: 3
    toc-location: left
    number-sections: true
    code-fold: false
    code-tools: true
    fig-cap-location: bottom
    df-print: kable
embed-resources: true
bibliography: bibtex.bib
---
```

### Render `qmd` script

A Quarto script can be evaluated and rendered with the following `quarto_render` command or by pressing the `knit` button in RStudio.
The `output_format` argument defines the format of the output. 

```{r render_rmarkdown, eval=FALSE, message=FALSE}
quarto::quarto_render("sample.qmd")                        # default format from YAML
quarto::quarto_render("sample.qmd", output_format="pdf")   

```

The following shows how to render a `qmd` file from the command-line. To render to PDF format, use the argument setting: `output_format="pdf_document"` or `--to pdf` from R or command-line, respectively.

```{sh render_commandline}
#| eval: false
#| message: false
quarto render sample.qmd 
quarto render sample.qmd --to pdf  
```

### R code chunks

R Code Chunks can be embedded in a Quarto script by using three backticks
at the beginning of a new line along with arguments in the following lines starting
with `#|` that control the behavior of the code. The following lines contain the
plain R code. A code chunk is terminated by a new line starting with three backticks.

````{verbatim}
```{r code_chunk_name}
#| eval: false
x <- 1:10
```
````

The most important chunk options are:

+ `eval: true/false` — execute the chunk
+ `echo: true/false` — show the source code in the output
+ `warning: false` — suppress warnings
+ `message: false` — suppress messages
+ `cache: true` — cache results to speed up re-rendering
+ `fig-height: 4` — figure height in inches
+ `fig-width: 6` — figure width in inches
+ `fig-cap: "..."` — figure caption
+ `label: fig-name` — chunk label for cross-referencing (must start with `fig-` for figures)

For more details on chunk caching see the
[knitr cache documentation](https://bookdown.org/yihui/rmarkdown-cookbook/cache.html).

### Learning Markdown

Quarto uses standard Markdown for prose. The syntax is minimal and easy to learn:

+ [Quarto Markdown Basics](https://quarto.org/docs/authoring/markdown-basics.html)
+ [Markdown Intro on GitHub](https://guides.github.com/features/mastering-markdown/)
+ [Markdown Cheat Sheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet)
+ [Quarto cheatsheet](https://rstudio.github.io/cheatsheets/quarto.pdf)


### Tables

There are several ways to render tables. First, they can be printed within the R code chunks. Second, 
much nicer formatted tables can be generated with the functions `kable`, `kableExtra`, `pander` or `xtable`. The following
example uses `kable` from the `knitr` package.

### With `knitr::kable`

```{r kable}
library(knitr)
kable(iris[1:12,])
```

A much more elegant and powerful solution is to create fully interactive tables with the [`DT` package](https://rstudio.github.io/DT/). 
This JavaScirpt based environment provides a wrapper to the `DataTables` library using jQuery. The resulting tables can be sorted, queried and resized by the
user. Note, Quarto source files containing JavaScript components can only be rendered into HTML and not PDF.

### With `DT::datatable` 

```{r dt}
library(DT)
datatable(iris)
```

### Figures

Plots generated by the R code chunks in a Quarto document can be automatically 
inserted in the output file. The size of the figure can be controlled with the `fig.height`
and `fig.width` arguments.

```{r some_jitter_plot}
#| eval: true
library(ggplot2)
dsmall <- diamonds[sample(nrow(diamonds), 1000), ]
ggplot(dsmall, aes(color, price/carat)) + geom_jitter(alpha = I(1 / 2), aes(color=color))
```

Sometimes it can be useful to explicitly write an image to a file and then insert that 
image into the final document by referencing its file name in the R Markdown source. For 
instance, this can be useful for time consuming analyses. The following code will generate a 
file named `myplot.png`. To insert the file  in the final document, one can use standard 
Markdown or HTML syntax, _e.g._: `<img src="myplot.png"/>`.  

```{r some_custom_inserted_plot}
#| eval: true
#| warning: false
#| message: false
#| results: hide
png("myplot.png")
ggplot(dsmall, aes(color, price/carat)) + geom_jitter(alpha = I(1 / 2), aes(color=color))
dev.off()
```
<center><img title="some_title" src="myplot.png"/></center>

Quarto has a native cross-referencing system. This works as follows: give a chunk a label starting with `fig-`
and add a caption; then reference it anywhere in the document with `@fig-label`, which
renders as a numbered hyperlink, here @fig-jitter. This name-based referencing scheme 
applies to tables (`tbl-` prefix) and sections (`sec-` prefix, requires `number-sections: true`). 
Before this extremely useful feature was only available in LaTeX (missing in 
R Markdown). Also note: for large documents, like PhD theses, where referencing 
of figures and tables across documents is important, this feature is best supported in 
[Quarto Books](https://quarto.org/docs/books/). In this context it is also useful to know 
that Quarto documents can be converted to `tex` (LaTeX) files. 

````{verbatim}
```{r}
#| label: fig-jitter # Note: when label is used, omit name in header line!
#| fig-cap: "Diamond price by color."
#| fig-height: 4
ggplot(dsmall, aes(color, price/carat)) +
  geom_jitter(alpha = 0.5, aes(color = color))
```
````

```{r}
#| label: fig-jitter
#| fig-cap: "Diamond price by color."
#| fig-height: 4
ggplot(dsmall, aes(color, price/carat)) +
  geom_jitter(alpha = 0.5, aes(color = color))
```

### Custom functions

Custom functions can be kept in a separate R file (here [`custom_Fct.R`](https://raw.githubusercontent.com/tgirke/GEN242/main/content/en/tutorials/rmarkdown/custom_Fct.R)) and then imported
with the `source()` command. In the following example, the `custom_Fct.R` file is located on GitHub.  

```{r import_custom_fct}
#| eval: true
source("https://raw.githubusercontent.com/tgirke/GEN242/refs/heads/main/tutorials/quarto/custom_Fct.R")
```

Now the imported function (here `myMAcomp`) can be used.

```{r use_custom_fct}
#| eval: true
myMA <- matrix(rnorm(100000), 10000, 10, dimnames=list(1:10000, paste("C", 1:10, sep="")))
resultDF <- myMAcomp(myMA=myMA, group=c(1,1,1,2,2,2,3,3,4,4), myfct=mean)
kable(resultDF[1:12,])
```

### Inline R code

To evaluate R code inline, one can enclose an R expression with a single back-tick
followed by `r` and then the actual expression.  For instance, the back-ticked version 
of 'r 1 + 1' evaluates to `r 1 + 1` and 'r pi' evaluates to `r pi`.

### Mathematical equations

To render mathematical equations, one can use standard Latex syntax. When expressions are 
enclosed with single `$` signs then they will be shown inline, while 
enclosing them with double `$$` signs will show them in display mode. For instance, the following 
Latex syntax `d(X,Y) = \sqrt[]{ \sum_{i=1}^{n}{(x_{i}-y_{i})^2} }` renders in display mode as follows:

$$d(X,Y) = \sqrt[]{ \sum_{i=1}^{n}{(x_{i}-y_{i})^2} }$$

To learn LaTeX syntax for mathematical equations, one can consult various online manuals, such as 
this [Wikibooks tutorial](https://en.wikibooks.org/wiki/LaTeX/Mathematics), or use an online
equation rendering and checking tool, such as this [one](https://arachnoid.com/latex/).

### Citations and bibliographies

Citations and bibliographies can be autogenerated in Quarto in a similar
way as in Latex/Bibtex. Reference collections should be stored in a separate
file in Bibtex or other supported formats. To cite a publication in a Quarto 
script, one uses the syntax `[@<id1>]` where `<id1>` needs to be replaced with a 
reference identifier present in the Bibtex database listed in the metadata section 
of the Quarto script  (_e.g._ `bibtex.bib`). For instance, to cite Lawrence et al. 
(2013), one  uses its reference identifier (_e.g._ `Lawrence2013-kt`) as `<id1>` [@Lawrence2013-kt]. 
This will place the citation inline in the text and add the corresponding
reference to a reference list at the end of the output document. For the latter a 
special section called `References` needs to be specified at the end of the R Markdown script.
To fine control the formatting of citations and reference lists, users want to consult this 
[R Markdown page](http://rmarkdown.rstudio.com/authoring_bibliographies_and_citations.html).
Also, for general reference management and obtaining references in Bibtex format [Paperpile](https://paperpile.com/features) 
can be very helpful.


### Viewing Quarto reports on HPCC cluster

Quarto reports located on UCR's HPCC Cluster can be viewed locally in a web browser (without moving 
the source HTML) by creating a symbolic link from a user's `.html` directory. This way any updates to 
the report will show up immediately without creating another copy of the HTML file. For instance, if user 
`ttest` has generated an Quarto report under `~/bigdata/today/rmarkdown/sample.html`, then the 
symbolic link can be created as follows:

```{r rmarkdown_symbolic_link}
#| eval: false
cd ~/.html
ln -s ~/bigdata/today/rmarkdown/sample.html sample.html
```

After this one can view the report in a web browser using this URL [https://cluster.hpcc.ucr.edu/~ttest/rmarkdown/sample.html](https://cluster.hpcc.ucr.edu/~ttest/rmarkdown/sample.html).
If necessary access to the URL can be restricted with a password following the instructions [here](http://hpcc.ucr.edu/manuals_linux-cluster_sharing.html#sharing-files-on-the-web).

### Viewing Quarto report on GitHub

To host and view static HTML files on GitHub, follow the instructions [here](https://girke.bioinformatics.ucr.edu/GEN242/tutorials/github/github.html#viewing-static-html-files-on-github). Note, this works
only with public GitHub repos. 


## Session Info

```{r sessionInfo}
sessionInfo()
```

## References

