R markdown

Introduction

Whenever possible, your analyses should be documented in the form of knitted R markdown files and uploaded to one of the neurogenomics lab's GitHub repositories.

Thedocument_and_share repository contains a useful Rmarkdown template file, and an introduction to using Rmarkdown.

Further improving Rmarkdown

There are some things that increase the usability of these in the future, such as:

1. Knit as html and share via GitHub Pages

GitHub pages is an incredibly useful (and free!) feature on GitHub that allows you to create websites from any html file, including those produced via knitting Rmarkdown, or rendering Jupyter notebooks with nbconvert.

This makes it extremely easy to push your latest results to GitHub, and then immediately start sharing them with collaborators by simply sending them the link, all without having to send (many versions) of files and data.

2. Always share the data used to generate figures as a data table.

It will often be desirable to regenerate figures in the future. Therefore, providing the data that was fed directly into the (ggplot) plotting function (not just the raw, pre-processed data) is really helpful. In the next step, we list several ways to do this.

3. Add download buttons to tables

You can easily make data tables interactive, filterable, sortable, and downloadable (in multiple formats!). We highly recommend this wherever possible, because otherwise it can be difficult to later try regenerating these figures and data.

Caveats

That said sharing very large datasets via the interactive table is a bad idea because it drastically slows down the whole Rmarkdown file/web page.

Instead, you can just provide an interactive header or subset of the data in the interactive data table, and then right below provide the link to the full dataset stored on GitHub (e.g. here) or elsewhere, so long as it's publicly accessible to anyone who clicks it.

You can even provide a link that downloads the data as soon as the user clicks it, by instead right clicking the Download button on the upper right of the file's GitHub location and selecting "Copy Link Address", e.g. here.

Code for interactive, downloadable tables in Rmarkdown

#' Interactive DT
#'
#' Generate an interactive data table with download buttons.
#'
#' @family general
#' @keywords internal
createDT <- function(DF, caption="", scrollY=400){
  data <- DT::datatable(DF, caption=caption,
                        extensions = 'Buttons',
                        options = list( dom = 'Bfrtip',
                                        buttons = c('copy', 'csv', 'excel', 'pdf', 'print'),
                                        scrollY = scrollY, scrollX=T, scrollCollapse = T, paging = F,
                                        columnDefs = list(list(className = 'dt-center', targets = "_all"))
                        )
  )
  return(data)
}

#' Interactive DT (html)
#'
#' Generate an interactive data table with download buttons.
#' Use this function when manually constructing rmarkdown chunks using cat() in a for loop.
#'
#' @family general
#' @keywords internal
createDT_html <- function(DF, caption="", scrollY=400){
  htmltools::tagList( createDT(DF, caption, scrollY))
}

4. Increase figure resolution

Figures within Rmarkdown can easily be downloaded by right clicking (just as you would with any other image on a web page). But these aren't always very high resolution.

You can increase the resolution of figures throughout your Rmarkdown by adding the following within your first code chunk:

```{r style, dpi=400}

Caveats

This will increase the resolution of all your figures to 400dpi (the minimum standard for most scientific journals). However, be warned, this will increase the. size of your knitted Rmarkdown output file (e.g. html, PDF).

4. [Optional] Make plots interactive

As a bonus, you can also make plots interactive. Wrapping ggplot2 objects within plotly::ggplotly() is the easiest way to achieve this. See here various tutorials. These can be very useful for zooming in on overcrowded plots, removing layers of data, and even exploring your plots in 3D!

Caveats

As awesome as interactive plots are, they aren't necessary or desirable in many cases. Even more so than with increasing image resolution, this will increase the size of your knitted Rmarkdown (html) output file. This also means including too many interactive plots in one file can slow down the time it takes to load the page in.