5. Report Writing and Wrap-Up

Creating a markdown file from scratch

So far you have been working with the R notebooks supplied with the course, but for your own analyses you’ll want to start from scratch.

File → New File → R Markdown

  • Choose ‘Document’ and the default output type (HTML)
  • A new tab is created in RStudio
  • The header allows you to specify a Page title, author and output type

    ---
    title: "Untitled"
    author: "Mark Dunning"
    date: "22/12/2016"
    output: html_document
    ---

    Text formatting

    See HelpMarkdown Quick Reference in RStudio:

  • Enclose text in * to format in italics
  • Enclose text in ** to format in bold
  • *** for bold italics
  • ` to format like code
  • $ to include equations: \(e =mc^2\)
  • > quoted text:

To be or not to be

  • See Help -> Markdown Quick Reference for more:
    • Adding images
    • Adding web links
    • Tables

Not quite enough for a reproducible document

  • Minimally, you should record what version of R, and the packages you used.
  • Use the sessionInfo() function
    • e.g. for the version of R I used to make the slides
sessionInfo()

Defining chunks

  • It is not great practice to have one long, continuous R script
  • Better to break-up into smaller pieces; ‘chunks
  • You can document each chunk separately
  • Easier to catch errors
  • The characteristics of each chunk can be modified:
    • You might not want to print the R code for each chunk
    • …or the output

Chunk options

  • It’s a good idea to name each chunk
    • Easier to track-down errors
  • We can display R code, but not run it
    • eval=FALSE
  • We can run R code, but not display it
    • echo=FALSE
    • e.g. setting display options
  • Suppress warning messages
    • warning=FALSE

Chunk options: eval

  • Sometimes we want to format code for display, but not execute; we want to show the code for how we read our data, but want our report to compile quickly

e.g.

data <- read.delim("path.to.my.file")

Chunk options: echo

  • Might want to load some data, silently, from disk
    • e.g. the R object from reading the data in the previous slide
    • or your P.I. wants to see your results, but doesn’t really want to know about the R code that you used

Chunk options: results

  • Some code or functions might produce lots of output to the screen that we don’t need
    • results='hide'

Chunk options: message and warning

  • Loading an R package will sometimes print messages and / or warnings to the screen
  • This is not always helpful in a report:
  • Using message=FALSE and warning=FALSE
library(DESeq)
  • Could also need suppressPackageStartupMessages

Chunk options: cache

  • The argument cache=TRUE will stop certain chunks from being evaluate if their code does not change
  • It speeds-up the compilation of the document
    • we don’t want to reload our dataset if we’ve only made a tiny change downstream

Running R code from the main text

  • We can add R code to our main text, which gets evaluated
    • make sure we always have the latest figures, p-values etc
  • See example gene-expression-analysis.Rmd

End of Course

Wrap-up

  • Thanks for your attention
  • Practice, practice, practice
    • … & persevere
  • Need inspiration? R code is freely-available, so read other people’s code!
  • Please fill in the feedback form for us to improve the course
LS0tCnRpdGxlOiAiSW50cm9kdWN0aW9uIHRvIFNvbHZpbmcgQmlvbG9naWNhbCBQcm9ibGVtcyBVc2luZyBSIC0gRGF5IDIiCmF1dGhvcjogTWFyayBEdW5uaW5nLCBTdXJhaiBNZW5vbiBhbmQgQWlvcmEgWmFiYWxhLiBPcmlnaW5hbCBtYXRlcmlhbCBieSBSb2JlcnQgU3Rvam5pxIcsCiAgTGF1cmVudCBHYXR0bywgUm9iIEZveSwgSm9obiBEYXZleSwgRMOhdmlkIE1vbG7DoXIgYW5kIElhbiBSb2JlcnRzCmRhdGU6ICdgciBmb3JtYXQoU3lzLnRpbWUoKSwgIkxhc3QgbW9kaWZpZWQ6ICVkICViICVZIilgJwpvdXRwdXQ6IGh0bWxfbm90ZWJvb2sKLS0tCgojIDUuIFJlcG9ydCBXcml0aW5nIGFuZCBXcmFwLVVwCgoKIyMgQ3JlYXRpbmcgYSBtYXJrZG93biBmaWxlIGZyb20gc2NyYXRjaAoKU28gZmFyIHlvdSBoYXZlIGJlZW4gd29ya2luZyB3aXRoIHRoZSBSIG5vdGVib29rcyBzdXBwbGllZCB3aXRoIHRoZSBjb3Vyc2UsIGJ1dCBmb3IgeW91ciBvd24gYW5hbHlzZXMgeW91J2xsIHdhbnQgdG8gc3RhcnQgZnJvbSBzY3JhdGNoLgoKKioqRmlsZSDihpIgTmV3IEZpbGUg4oaSIFIgTWFya2Rvd24qKioKCi0gQ2hvb3NlICdEb2N1bWVudCcgYW5kIHRoZSBkZWZhdWx0IG91dHB1dCB0eXBlIChIVE1MKQotIEEgbmV3IHRhYiBpcyBjcmVhdGVkIGluIFJTdHVkaW8KLSBUaGUgaGVhZGVyIGFsbG93cyB5b3UgdG8gc3BlY2lmeSBhIFBhZ2UgdGl0bGUsIGF1dGhvciBhbmQgb3V0cHV0IHR5cGUKYGBgCi0tLQp0aXRsZTogIlVudGl0bGVkIgphdXRob3I6ICJNYXJrIER1bm5pbmciCmRhdGU6ICIyMi8xMi8yMDE2IgpvdXRwdXQ6IGh0bWxfZG9jdW1lbnQKLS0tCmBgYAojI1RleHQgZm9ybWF0dGluZwpTZWUgKioqSGVscCoqKiDihpIgKioqTWFya2Rvd24gUXVpY2sgUmVmZXJlbmNlKioqIGluIFJTdHVkaW86CgotIEVuY2xvc2UgdGV4dCBpbiBcKiB0byBmb3JtYXQgaW4gKml0YWxpY3MqCi0gRW5jbG9zZSB0ZXh0IGluIFwqXCogdG8gZm9ybWF0IGluICoqYm9sZCoqCi0gXCpcKlwqIGZvciAqKipib2xkIGl0YWxpY3MqKioKLSBcYCB0byBmb3JtYXQgbGlrZSBgY29kZWAKLSBcJCB0byBpbmNsdWRlIGVxdWF0aW9uczogJGUgPW1jXjIkCi0gXD4gcXVvdGVkIHRleHQ6IAoKPlRvIGJlIG9yIG5vdCB0byBiZQoKLSBTZWUgKipIZWxwIC0+IE1hcmtkb3duIFF1aWNrIFJlZmVyZW5jZSoqIGZvciBtb3JlOgogICAgKyBBZGRpbmcgaW1hZ2VzCiAgICArIEFkZGluZyB3ZWIgbGlua3MKICAgICsgVGFibGVzCgoKIyMgTm90IHF1aXRlIGVub3VnaCBmb3IgYSByZXByb2R1Y2libGUgZG9jdW1lbnQKCi0gTWluaW1hbGx5LCB5b3Ugc2hvdWxkIHJlY29yZCB3aGF0IHZlcnNpb24gb2YgUiwgYW5kIHRoZSBwYWNrYWdlcyB5b3UgdXNlZC4KLSBVc2UgdGhlIGBzZXNzaW9uSW5mbygpYCBmdW5jdGlvbgogICAgKyBlLmcuIGZvciB0aGUgdmVyc2lvbiBvZiBSIEkgdXNlZCB0byBtYWtlIHRoZSBzbGlkZXMKCmBgYHtyfQpzZXNzaW9uSW5mbygpCmBgYAogICAgCgojIyBEZWZpbmluZyBjaHVua3MKCi0gSXQgaXMgbm90IGdyZWF0IHByYWN0aWNlIHRvIGhhdmUgb25lIGxvbmcsIGNvbnRpbnVvdXMgUiBzY3JpcHQKLSBCZXR0ZXIgdG8gYnJlYWstdXAgaW50byBzbWFsbGVyIHBpZWNlczsgJypjaHVua3MqJwotIFlvdSBjYW4gZG9jdW1lbnQgZWFjaCBjaHVuayBzZXBhcmF0ZWx5Ci0gRWFzaWVyIHRvIGNhdGNoIGVycm9ycwotIFRoZSBjaGFyYWN0ZXJpc3RpY3Mgb2YgZWFjaCBjaHVuayBjYW4gYmUgbW9kaWZpZWQ6CiAgICArIFlvdSBtaWdodCBub3Qgd2FudCB0byBwcmludCB0aGUgUiBjb2RlIGZvciBlYWNoIGNodW5rCiAgICArIC4uLm9yIHRoZSBvdXRwdXQKCgoKIyMgQ2h1bmsgb3B0aW9ucwoKCi0gSXQncyBhIGdvb2QgaWRlYSB0byBuYW1lIGVhY2ggY2h1bmsKICAgICsgRWFzaWVyIHRvIHRyYWNrLWRvd24gZXJyb3JzCi0gV2UgY2FuIGRpc3BsYXkgUiBjb2RlLCBidXQgbm90IHJ1biBpdAogICAgKyBgZXZhbD1GQUxTRWAKLSBXZSBjYW4gcnVuIFIgY29kZSwgYnV0IG5vdCBkaXNwbGF5IGl0CiAgICArIGBlY2hvPUZBTFNFYAogICAgKyBlLmcuIHNldHRpbmcgZGlzcGxheSBvcHRpb25zCi0gU3VwcHJlc3Mgd2FybmluZyBtZXNzYWdlcwogICAgKyBgd2FybmluZz1GQUxTRWAKCiAgICAKIyMgQ2h1bmsgb3B0aW9uczogZXZhbAoKLSBTb21ldGltZXMgd2Ugd2FudCB0byBmb3JtYXQgY29kZSBmb3IgZGlzcGxheSwgYnV0IG5vdCBleGVjdXRlOyB3ZSB3YW50IHRvIHNob3cgdGhlIGNvZGUgZm9yIGhvdyB3ZSByZWFkIG91ciBkYXRhLCBidXQgd2FudCBvdXIgcmVwb3J0IHRvIGNvbXBpbGUgcXVpY2tseQoKZS5nLgoKYGBge3IsIGV2YWw9RkFMU0V9CmRhdGEgPC0gcmVhZC5kZWxpbSgicGF0aC50by5teS5maWxlIikKYGBgCgojIyBDaHVuayBvcHRpb25zOiBlY2hvCgotIE1pZ2h0IHdhbnQgdG8gbG9hZCBzb21lIGRhdGEsIHNpbGVudGx5LCBmcm9tIGRpc2sKICAgICsgZS5nLiB0aGUgUiBvYmplY3QgZnJvbSByZWFkaW5nIHRoZSBkYXRhIGluIHRoZSBwcmV2aW91cyBzbGlkZQogICAgKyBvciB5b3VyIFAuSS4gd2FudHMgdG8gc2VlIHlvdXIgcmVzdWx0cywgYnV0IGRvZXNuJ3QgcmVhbGx5IHdhbnQgdG8ga25vdyBhYm91dCB0aGUgUiBjb2RlIHRoYXQgeW91IHVzZWQKICAgIApgYGB7ciBlY2hvPUZBTFNFfQpwbG90KHJub3JtKDEwMCkpCmBgYAoKCiMjIENodW5rIG9wdGlvbnM6IHJlc3VsdHMKCi0gU29tZSBjb2RlIG9yIGZ1bmN0aW9ucyBtaWdodCBwcm9kdWNlIGxvdHMgb2Ygb3V0cHV0IHRvIHRoZSBzY3JlZW4gdGhhdCB3ZSBkb24ndCBuZWVkCiAgICArIGByZXN1bHRzPSdoaWRlJ2AKYGBge3IgcmVzdWx0cz0naGlkZSd9CmZvcihpIGluIDE6MTAwKSB7CiAgcHJpbnQoaSkKICB9CmBgYAoKCiMjQ2h1bmsgb3B0aW9uczogbWVzc2FnZSBhbmQgd2FybmluZwoKLSBMb2FkaW5nIGFuIFIgcGFja2FnZSB3aWxsIHNvbWV0aW1lcyBwcmludCBtZXNzYWdlcyBhbmQgLyBvciB3YXJuaW5ncyB0byB0aGUgc2NyZWVuCi0gVGhpcyBpcyBub3QgYWx3YXlzIGhlbHBmdWwgaW4gYSByZXBvcnQ6Ci0gVXNpbmcgYG1lc3NhZ2U9RkFMU0VgIGFuZCBgd2FybmluZz1GQUxTRWAKCgpgYGB7ciBtZXNzYWdlPUZBTFNFLCB3YXJuaW5nPUZBTFNFfQpsaWJyYXJ5KERFU2VxKQoKYGBgCi0gQ291bGQgYWxzbyBuZWVkIGBzdXBwcmVzc1BhY2thZ2VTdGFydHVwTWVzc2FnZXNgCgojI0NodW5rIG9wdGlvbnM6IGNhY2hlCgotIFRoZSBhcmd1bWVudCBgY2FjaGU9VFJVRWAgd2lsbCBzdG9wIGNlcnRhaW4gY2h1bmtzIGZyb20gYmVpbmcgZXZhbHVhdGUgaWYgdGhlaXIgY29kZSBkb2VzIG5vdCBjaGFuZ2UKLSBJdCBzcGVlZHMtdXAgdGhlIGNvbXBpbGF0aW9uIG9mIHRoZSBkb2N1bWVudAogICAgKyB3ZSBkb24ndCB3YW50IHRvIHJlbG9hZCBvdXIgZGF0YXNldCBpZiB3ZSd2ZSBvbmx5IG1hZGUgYSB0aW55IGNoYW5nZSBkb3duc3RyZWFtCgpgYGB7ciBlY2hvPUZBTFNFLCBjYWNoZT1UUlVFfQpldmFscyA8LSByZWFkLmRlbGltKCJnZW5lLmV4cHJlc3Npb24udHh0IikKYGBgCgojIyBSdW5uaW5nIFIgY29kZSBmcm9tIHRoZSBtYWluIHRleHQKCi0gV2UgY2FuIGFkZCBSIGNvZGUgdG8gb3VyIG1haW4gdGV4dCwgd2hpY2ggZ2V0cyBldmFsdWF0ZWQKICAgICsgbWFrZSBzdXJlIHdlIGFsd2F5cyBoYXZlIHRoZSBsYXRlc3QgZmlndXJlcywgcC12YWx1ZXMgZXRjCi0gU2VlIGV4YW1wbGUgYGdlbmUtZXhwcmVzc2lvbi1hbmFseXNpcy5SbWRgCgojIEVuZCBvZiBDb3Vyc2UKCiMjIFdyYXAtdXAKCi0gKipUaGFua3MgZm9yIHlvdXIgYXR0ZW50aW9uKioKLSBQcmFjdGljZSwgcHJhY3RpY2UsIHByYWN0aWNlCiAgICArIC4uLiAmIHBlcnNldmVyZQotIE5lZWQgaW5zcGlyYXRpb24/IFIgY29kZSBpcyBmcmVlbHktYXZhaWxhYmxlLCBzbyByZWFkIG90aGVyIHBlb3BsZSdzIGNvZGUhCiAgICArIFJlYWQgW2Jsb2dzXShodHRwOi8vd3d3LnItYmxvZ2dlcnMuY29tLykKICAgICsgRm9sbG93IHRoZSBbZm9ydW1zXShodHRwOi8vc3RhY2tvdmVyZmxvdy5jb20vcXVlc3Rpb25zL3RhZ2dlZC9yKQogICAgKyBEb3dubG9hZCBbZGF0YXNldHNdKGh0dHA6Ly92aW5jZW50YXJlbGJ1bmRvY2suZ2l0aHViLmlvL1JkYXRhc2V0cy9kYXRhc2V0cy5odG1sKSB0byBwcmFjdGljZSB3aXRoCiAgICArIEJvb2ttYXJrIHNvbWUgW3JlZmVyZW5jZV0oaHR0cHM6Ly9lbi53aWtpYm9va3Mub3JnL3dpa2kvUl9Qcm9ncmFtbWluZykgZ3VpZGVzCiAgICArIG9uIHR3aXR0ZXIgQHJzdHVkaW8sIEBSYmxvZ2dlcnMsIEBSTGFuZ1RpcAogICAgKyBBdHRlbmQgdGhlIFtmb2xsb3ctb24gY291cnNlXShodHRwOi8vdHJhaW5pbmcuY3N4LmNhbS5hYy51ay9iaW9pbmZvcm1hdGljcy9ldmVudC8xODAwMDY2KSBvbiBkYXRhIG1hbmlwdWxhdGlvbiBhbmQgZ3JhcGhpY3MKLSBQbGVhc2UgZmlsbCBpbiB0aGUgZmVlZGJhY2sgZm9ybSBmb3IgdXMgdG8gaW1wcm92ZSB0aGUgY291cnNlCiAgICAK