In humburg/reportmd: Scientific reports with RMarkdown

## load additional packages in this chunk
library(reportMD)
library(knitr)
library(pander)
library(ggplot2)
library(plotly)

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

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

data(mtcars)

Figures and Figure labels

You can also embed plots, for example:

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) 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.

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.

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

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:

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:

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.

plotMD(part2$reg_fig, envir=part2)

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.

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').

humburg/reportmd documentation built on May 17, 2019, 9:13 p.m.