skeleton.Rmd

---
title: "Main Document"
author: "Author Name"
date: "`r format(Sys.time(), '%a %d %b %Y')`"
output:
  reportMD::multi_document:
    toc: true
    fig_caption: true
    highlight: atom-one-dark
    depends:
      part1: part1.Rmd
      part2: part2.Rmd
    use_namespace: true
params:
  version: !r if(nchar(Sys.which('git'))) system("git describe --long --dirty --abbrev=10 --tags --always", intern=TRUE) else date()
---

```{r loadPackages, include=FALSE, cache=FALSE}
## load additional packages in this chunk
library(reportMD)
library(knitr)
library(pander)
library(ggplot2)
library(plotly)
```

```{r setup, include=FALSE, cache=FALSE}
## This chunk should contain global configuration commands.
## Use this to set knitr options and related things. Everything
## in this chunk will be included in an appendix to document the
## configuration used.

## Pander options
panderOptions("digits", 3)
panderOptions("table.split.table", 160)
```

```{r functions, include=FALSE}
## Custom functions used in the analysis should go into this chunk.
## They will be listed in their own section of the appendix.

```


# Using this template
## Basics
This is an R Markdown document. Markdown is a simple formatting syntax for authoring HTML, PDF, and MS Word documents. For more details on using R Markdown see <http://rmarkdown.rstudio.com>. This template uses the *Multi-part report* template from the *reportMD* package, which is designed
to produce a series of interconected HTML documents.

When you click the **Knit** button a document will be generated that includes both content as well as the output of any embedded R code chunks within the document. You can embed an R code chunk like this:

```{r data}
data(mtcars)
```

## Figures and Figure labels
You can also embed plots, for example:

```{r examplePlot, fig.cap="An example plot", fig_format='interactive'}
carFig <- ggplot(mtcars, aes(x=hp, y=mpg, colour=cyl, text=rownames(mtcars))) + geom_point() + theme_bw()
plotMD(carFig)
```

Note that a figure label (by default this is *Figure N*) is added to the figure caption when the plot is included in the output.
This plot can be referenced in the text by including a call to the `figRef` function using the the chunk label as its only
argument. This is a reference to `r figRef('examplePlot')`. The *reportMD* package supports the use of interactive plots 
in HTML pages (generated with [*plotly*](https://github.com/ropensci/plotly)) as well static versions. This feature relies on
the use of *ggplot2* for plotting. Using the *plotMD* function to produce the plot from a *grob* prepared earlier allows
seamless switching between the two by setting the `fig_format` option, either globally (in the YAML frontmatter or in the 
call to *render*), via a call to `knitr::opts_chunk$set` or in the options for an individual chunk. Please note that the
interactive version of a figure is only shown on devices with sufficient resolution. On low resolution screens (or in small
browser windows) a static version of the plot will be displayed instead.

```{r staticPlot, fig.cap=paste("Static version of", figRef('examplePlot'))}
carFig <- ggplot(mtcars, aes(x=hp, y=mpg, colour=cyl, text=rownames(mtcars))) + geom_point() + theme_bw()
plotMD(carFig)
```

### Controlling Figure size
The size of generated figures can be controlled via the *fig_width* and *fig_height*
options. These work in the YAML header, where they will set the default size for
all figures in the document, as well as in the options for an individual figure
chunk. In either case *fig_width* and *fig_height* should be specified in inches.

By default the output document will display thumbnails of figures on screens that
are at least 992px wide. The default for these thumbnails is to be half the width
of the main text. To change the size of the thumbnails set *thumbnail_size*
in the YAML header to a value between 1 and 12, where 12 corresponds to the width
of the main text. The size of the thumbnail for an individual figure can be
changed by setting the *bootstrap.thumbnail.size* chunk option. To disable
thumbnails entirely, set `thumbnail: false` in the YAML header or
`bootstrap.thumbnail=FALSE` in the chunk options.

### Appearance of Figure lables
A number of options are available to modify the appearance of figure lables.
The default appearance (**Figure N**: Some caption) can be changed by setting
the *figcap_prefix*, *figcap_sep* and *figcap_prefix_highlight* options
in the YAML header. These control the prefix ('Figure'), separator (':') and
highlighting (**bold**) of the figure label respectively. For example, to change figure labels
to the form '*Fig. N:*', set *figcap_prefix* to 'Fig.' and *figcap_prefix_highlight*
to '*'.

## Tables
Tables can be added to the output document by printing a `data.frame` or `matrix` using *printMD*.
Use the `tab.cap` chunk option to provide a table caption.

```{r carTable, tab.cap="A subset of the *mtcars* dataset.", download='mtcars'}
printMD(mtcars[1:5, c('mpg', 'hp', 'cyl')])
```

It sometimes is desirable to provide access to the data displayed in the
table. If a table chunk contains an option of the form `download="variable_name"`,
a file containing the the data stored in *variable_name* will be created and
a download link pointing to that file will be added to the table caption.

Tables can be referenced in the same way as figures, using the *tabRef* function. This is a reference to `r tabRef('carTable')`.

## MathJax

MathJax does work with this custom template so you can insert any LaTeX expression you want.  
Here we just use a random formula to demonstrate that everything is working. Check [this link](http://www.calvin.edu/~rpruim/courses/m343/F12/RStudio/LatexExamples.html) for a briew overview of basic LaTeX commands.

$$
nri_{B1,B2}=\frac{R_{B1}-R_{B2}}{R_{B1}+R_{B2}}
$$
## Inline R code
This document format attempts to format output from inline code to be easily readable and consistent without
requireing careful formatting at the time of writing.
For example, this is a large number: `r 10^4`, this one is even larger: `r 3*10^6`. Here is a small one: `r 10^-6`.
$\pi$ is approximately `r pi`. The number of significant digits displayed can be controlled via
*pander*'s *digits* option (which this document set to 3). If higher accuracy is desired for a specific
number this can be achieved by passing it through *printMD* directly. A petter approximation of $\pi$
is given by `r printMD(pi, digits=10)`.

## Using R objects from child documents
Your R chunks may use objects created by a chunk in a different (child) document, provided the generating chunk is cached 
and the cache is available when this document is knitted. To do this, simply list the path to the child document in the
YAML header under the output options:

```yaml
output:
  reportMD::multi_document:
    depends:
      part1: part1.Rmd
      part2: part2.Rmd
```

This will load all R objects generated by cached chunks in *part1.Rmd* into the environment in which the chunks of this
document are evaluated. To only load a subset of chunks from the child document, provide a list of chunk labels:

```yaml
output:
  reportMD::multi_document:
    depends:
      part2: 
        part2.Rmd: [regression, prepRegPlot]
```

Sometimes it may be preferable not to load R objects from other documents directly
into the global environment. To load dependencies into a separate environment
for each child document, add the `use_namespace` option:

```yaml
output:
  reportMD::multi_document:
    depends:
      part2: 
        part2.Rmd: [regression, prepRegPlot]
    use_namespace: true
```

Now objects form *part2.Rmd* are accessible as `part2$object_name` 
(instead of simply `object_name`). This helps to avoid name clashes between 
objects imported from different documents.

Eiter way, we have direct access to the R objects created in the child documents and can use them in the main
document in whatever order is most useful to explain the analysis and discuss the results. In *part2.Rmd*
we constructed a ggplot and cached the resulting object. This can now be used to
produce the plot here (`r figRef('regression')`).

Note that some care is necessary when reproducing plots from child documents. 
If the plot is not self contained, i.e. it references local variables from
the envirnment where it was created, the chunks containing the relevant variables
have to be specified as dependencies. If *use_namespace* is set it is also 
necessary to provide the environment corresponding to the child document to
*plotMD*. 

```{r childPlot, eval=FALSE, cache=FALSE}
plotMD(part2$reg_fig, envir=part2)
```

```{r regression, dependson=c('part2:regression', 'part2:prepRegPlot'), fig.cap="Linear regression result. Car weight is a good predictor for MPG and the US built cars in the dataset tend to be heavier."}
plotMD(part2$reg_fig, envir=part2)
```

In addition to specifying all chunks to import from a child document it is also possible to specify required
chunks as part of the *dependson* chunk option by providing dependencies of the form '`child label`:`chunk label`'.
For example, to load the *regression* chunk from *part2.Rmd* (to which we have assigned the label *part2*) we
could add `dependson='part2:regression'` to the chunk options. This has the advantage that dependencies are managed
for each chunk, making it easier to update dependencies as the requirements of a code chunk change. It also makes
it more explicit where objects in a code chunk come from.

## Linking to child documents
It may be useful to add links to the child documents in appropriate places throughout the text. This can
be achieved using *pandoc*'s reference link syntax. For example, to link to [Part 2][part2] simply use `[some text][part2]`.
Links to all document dependencies listed in the header will be added to the *Related Documents* section of the appendix.

It is possible to link to specific parts of a child document by using the corresponding 
dependency object directly. 

```{r get_dependencies}
deps <- knitr::opts_knit$get('dependencies')
```

Printing a dependency object (*via* `printMD`) will insert a reference to the
corresponding output document in the text. The optional `target` argument
to `printMD` allows to specify any anchor for the link. This can correspond
to a heading, e.g. see the `r printMD(deps$part1, target='introduction', text='Introduction of Part 1')`,
or a code chunk (details of the `r printMD(deps$part2, target='regression', text='regression model used in Part 2')`).

It is also possible to link to a figure or table in a child document by providing the corresponding label
from the list of dependencies to indicate the target file: `r figRef('boxplot', target='part2')`.

```{r appendix, child='rmd/appendix.Rmd'}
```