README.md

Writing with Rmarkdown

We can create versioned (ie in Github), live (ie output directly from data with R), documents in various formats (ie pdf, html, docx) with formatting, figures, tables, equations and references. All using Rmarkdown. This is in the vein of generating truly reproducible research.

Example

Here's an example of using a single Rmarkdown file test.Rmd and rendering it in the following formats:

• test.pdf. Portable document format for pretty professional output.

• test.docx. Microsoft Word doc for sharing with collaborators who can use Track Changes for providing feedback.

• test.html. All you need is a web browser to view this. Works well with linking out to source of References via DOI and links within document. Since Github doesn't natively show HTML, you'll need to right-click on link, Save Link as... to download and open from your computer.

• test.md. Great for tracking changes in Github (ie rendered differences) and figuring out who changed what when (ie blame). Equations maintain their latex format, so not prettily rendered like other formats.

You can variously render different formats in RStudio and set options in the metadata header.

Check out test.Rmd differences between commits as it gets built up:

1. Initial. In RStudio, File > New File > R Markdown ...

2. Add table of contents & bibliography

---
output:
 html_document:
   toc: true
   number_sections: true
bibliography: test.bib
csl: apa.csl
---

...

The Ocean Health Index [@halpern_index_2012; @selig_assessing_2013] derives most of its pressures from Halpern et al. [-@halpern_global_2008].

1. Add equation

$$
x_{FIS} =  (\prod_{g=1}^{6} SS_{i,g}^{C_{i,g}})^\frac{1}{\sum{C_{i,g}}}
$$ 

1. Add format options for pdf and docx

output:
  pdf_document:
    fig_caption: yes
    number_sections: yes
    toc: yes
  word_document:
    fig_caption: yes

1. Add github markdown

output:
  md_document:
    variant: markdown_github

1. Add OHI figure, pretty table and inline values

Hats off to the top scoring region of **`r filter(d, goal=='Index') %>% head(1) %>% select(region_label)`** 
with a score of `r filter(d, goal=='Index') %>% head(1) %>% select(score)`! Here are the top 10 scoring 
regions of `r n_distinct(d$region_label) - 1 # remove GLOBAL` globally:

{r top10, echo=FALSE, results='asis'}
kable(
  d %>%
    filter(region_label != 'GLOBAL' & goal=='Index') %>%
    head(10) %>%
    select(
      Region = region_label,
      Score  = score),
  format='pandoc', caption='Top 10 scoring regions.')

Software

Here are the key pieces of software:

• RStudio: excellent free, cross-platform R integrated development environment for writing code and text.

• Rmarkdown: versatile "literate programming" R package for weaving chunks of R code with formatted text (markdown), built into RStudio.

• Pandoc: the standalone conversion engine used by the rmarkdown package, comes bundled inside rmarkdown package.

• Zotero: excellent free bibliographic management software, like Endnote. I can simply drag and drop from a Zotero collection to get the inline citation and pandoc will later generate the full bibliography at the end of the document. To get this to work, after installing Zotero:

  • Install Zotero Better Bibtex

  • In Zotero Preferences, set:

    1. Export: "Default Output Format" to Pandoc citation

    2. Better Bib(La)tex: "Citation key format" to [auth:lower]_[veryshorttitle:lower]_[year]

Process

After installing RStudio and Zotero, here are the steps for adding citations and generating a bibliography. You can use citation styles from any journal (*.csl files available for preview and download at zotero.org/styles).

1. New Rmd. In RStudio, File > New File > R Markdown... and choose type and format, eg document, HTML document. This will generate a sample *.Rmd file with metadata header specifying default output format (eg output: html_document).

1. Gather references. In Zotero, place all references used for the paper into its own dedicated collection (eg "test").

1. Add references. Drag and drop references from this collection into the document editor (I like RStudio or Sublime). This will add a text citation, eg @halpern_index_2012.

2. Export references. Right-click on Zotero collection > Export Collection and choose Better BibTex and export to a file in the same folder as the *.Rmd (eg test.bib).

3. Render. You can render the document as you write with the 'Knit' button (or Ctrl+Shift+Y of RStudio shortcuts). You can specify one ore more formats in the metadata output: option to one of: pdf_document, html_document, word_document, md_document, ioslides_presentation and more. The top format will render by default. Or you can use rmarkdown::render at the console to specify format like so:

render("test.Rmd", "pdf_document")`

The bibliography is automatically added to the end. See rmarkdown.rstudio.com and pandoc citations for details.

1. Repeat. Repeat as you write.

Aside. It is possible to sync your entire Zotero library using AutoZotBib, but my library is too large to practically use this.

Note. Besides the *.Rmd and *.md files, the outputs are binary in format and therefore just bloat the repository without adding novel information. Simply add entries like *.pdf and *.docx and *.html to .gitignore to prevent these files from being tracked and uploaded to the github repository.

More. For a deeper example of customization with figure/ table numbering, check out bbest/dissertation.

Zotero Tips

• Be sure to also install a Zotero web browser extension, aka Zotero "connector"", so you can easily pull a reference being browsed into the already selected Zotero folder with the single click of the icon in the right hand side of the address bar. I've had great success with the Chrome connector.

  

• In the Preferences... General tab, I also like to tick the box to "Automatically attach associated PDFs...".

  

• For automatically downloaded PDFs, right-click on the PDF and "Rename File from Parent Metadata".

  

Google Scholar Tips

• The Zotero web browser extension also works great with Google Scholar. You get a folder icon from search results allowing you to tick and save many references at once.

  

• I like making a Chrome shortcut so I simply type "s " in the address bar and it gives me a prompt to search Google Scholar.

  

• Finally, when using Google Scholar, be sure to go into the Settings and And add UCSB to provide journal access to full articles.

  

  

Bibliography

We can use this or another Zotero group library to sync references:

zotero.org/groups/ohi

You just need to send bbest your Zotero username after you register. Membership is private, and currently viewing is public. This shows up in the Zotero app separately from your private library under "Group Libraries".