Background: This blog post is going to show you how to write a reproducible article in the field of clinical chemistry using R Mardkown. The only thing that will change for journal to journal will be the reference fomating and perhaps section numbering. The source code itself will be provided so that you can use it as a template.

Methods: The paper will use R, R-Markdown, bookdown and pandoc. The references will be taken care of using BibTeX and reference formatting will be managed with Zotero csl files.

Results: The result will be a manuscript that anyone can reproduce.

Conclusions: R Markdown makes reproducible research through literate programming pretty easy.

2.1 YAML

RMarkdown articles require a YAML header to instruct R Markdown how to process your article. This is the YAML code that worked for me. I am sure there are other ways to do this:

---
title: "Reproducible Research: Write your Clinical Chemistry paper using R Markdown"
author: 
- Daniel Holmes, MD
date: "February 04, 2018"
documentclass: "article"
header-includes:
   - \usepackage{amsmath}
output:
  #bookdown::pdf_document2:
  #bookdown::word_document2
  bookdown::html_document2:
    toc: no
    pandoc_args: [
      "--csl", "clinical-chemistry.csl" , "--citation-abbreviations", "abbreviations.json"
    ]
bibliography: bibliography.bib
abstract: |
  **Background:** Put
  
  **Methods:** Your
  
  **Results:** Abstract
  
  **Conclusions:** Here
  
keywords: "bla bla bla"
---

Indenting and spacing really matter a lot in YAML so don’t mess with them. You can generate PDF, MS Word or HTML output as needed by uncommenting and commenting out the output type as appropriate in the YAML above.

2.2 CSL Files

CSL files take care of citation formatting for you. Depending on what journal you are making submission to, you will need a different .csl file. They exist for every conceivable journal. In the world of non-reproducible reports, this process is taken care of by reference managers in GUI word processors but since GUI word processors do not produce reproducible research, we must break up with them.

From the YAML, you will see that you need a file called “clinical-chemistry.csl” which I downloaded from here. Put this file in the same folder as your R Markdown file. The Clinical Chemistry .csl depends on the .csl file of the American Association for Cancer Research but it will be downloaded for you on the fly. If you need a different reference format, search the CSL GitHub repository for the appropriate file.

2.3 BibTeX

Reference management in R Markdown is taken care of by BibTeX. You can see from the YAML that we need a bibliography text file called “bibliography.bib”. You can name it whatever you like but you will need to change the YAML accordingly. In any case, any citation you intend to make will have to be in the .bib file. I am going to cite Shannon Haymond because this article was her idea and I will toss in a couple of other references so you can see that they get cited in order as we would like.

Below is my bibliography.bib file. I put it in the same folder as my R Markdown file. You make a .bib file using a text file editor (or RStudio) by cutting and pasting the BibTex citations from Google Scholar

@article{shannon2017,
  title={Contribution of symmetric dimethylarginine to GFR decline in pediatric chronic kidney disease},
  author={Brooks, Ellen R and Haymond, Shannon and Rademaker, Alfred and Pierce, Christopher and Helenowski, Irene and Passman, Rod and Vicente, Faye and Warady, Bradley A and Furth, Susan L and Langman, Craig B},
  journal={Pediatric Nephrology},
  pages={1--8},
  year={2017},
  publisher={Springer}
}

@article{li2017wellness,
  title={Wellness Initiatives: Benefits and Limitations},
  author={Li, Michelle and Diamandis, Eleftherios P and Paneth, Nigel and Yeo, Kiang-Teck J and Vogt, Henrik and Master, Stephen R},
  journal={Clinical Chemistry},
  volume={63},
  number={6},
  pages={1063--1068},
  year={2017},
  publisher={Clinical Chemistry}
}

@article{holmes2005preanalytical,
  title={Preanalytical influences on DPC IMMULITE 2000 intact PTH assays of plasma and serum from dialysis patients},
  author={Holmes, Daniel T and Levin, Adeera and Forer, Barry and Rosenberg, Frances},
  journal={Clinical Chemistry},
  volume={51},
  number={5},
  pages={915--917},
  year={2005},
  publisher={Clinical Chemistry}
}

2.4 Journal Abbreviations

Now, the fussiest thing I had to do was get the references abbreviating properly. We need an abbreviation database. Fortunately, I could download the abbreviation database from the Web of Science as a .csv file and then convert it to a JSON file. This was Stephen’s idea. I had to deal with a couple of badly behaving characters from some journal titles. This script, if embedded in your document, will download the .csv for you and then make the abbreviation database for you. That way your citations will say, “J Clin Pathol” and not “Journal of Clinical Pathology” etc.

```{r, echo = FALSE}
library(RJSONIO)
if(!file.exists("abbreviations.json")){
download.file("https://ndownloader.figshare.com/files/5212423","wos_abbrev_table.csv")
  abbrev <- read.csv("wos_abbrev_table.csv", sep = ";", header = TRUE, stringsAsFactors = FALSE)
  abbrev$full <- gsub("\\", "\\\\",abbrev$full, fixed = TRUE)
  abbrev.list <- list('default' = list('container-title' = abbrev$abbrev.dots))
  names(abbrev.list$default$`container-title`) = abbrev$full
  write(toJSON(abbrev.list), "abbreviations.json")
  rm(abbrev)
  rm(abbrev.list)
}
```

2.5 Citation Management

Now we can proceed to cite articles from our .bib file freely inserting syntax like this: [@shannon2017]. Shannon wrote this interesting article on symmetric dimethylarginine (1), Stephen wrote about wellness initiatives with Dr. Diamandis (2) and Dan wrote a paper about PTH when he was a resident (3). That makes for a total of 3 citations in this manuscript. (1–3)

3.1 Figures

You can embed figures in R Markdown as local images or hyperlinks as follows:

![Grumpy Cat does not care about reproducibility](grumpy.jpg)

If you need to do cross-referencing of figures in your document which will change automatically for you if you insert another figure, you can do this by inserting your figure with an R code-chunk and giving the code-chunk a name.

```{r ancient-aliens, fig.height=3, fig.width=2, fig.cap="This is the ancient aliens guy.", echo = FALSE}
knitr::include_graphics('ancient_aliens.jpg')
```

Figure 3.1: This is the ancient aliens guy.

Then you can reference your code chunk using syntax like this: See figure \@ref(fig:ancient-aliens)

and you will automatically create appropriately cross-referenced figures that get automatically numbered like this: See figure 3.1. Of course the hallmark of the reproducibility to embed R code right into the document. See for example figure 3.2

```{r example-code, fig.cap = "This is a reproducible figure"}
set.seed(10)
x <- runif(100,0,100)
y <- x + rnorm(100,0,0.10)*x
plot(x,y,
main = "Reproducible Figure",
pch = 16,
col = "blue",
xlab = "Current Method (mmol/L)",
ylab = "New Method (mmol/L)")
abline(lm(y~x), col = "red", pch = 2)
```

3.2 Inline Calculations

When you are reporting your amazing results you can have inline code calculations by syntax that looks like this: `r round(median(x),1)` and would result in the median value of \(x\) being reported as 43.9 mmol/L.

3.3 Tables

Tables are not a problem either and can be made with the kable() function of the knitr package or with the xtable package. Tables can be crossreferenced analogously to figures. See table 3.1

```{r example-table, echo = FALSE, results = 'asis'}
library(knitr)
a <- 1:5
b <- 2:6
c <- a*b
z <- data.frame(a,b,c)
kable(z,
  caption = "This is a great table", 
  col.names = c("First","Second", "Third"))
```

3.4 Math

Math works pretty magically using \(\LaTeX\) syntax. For example inline math can be done like so $\sin^2x + \cos^2x = 1$. This will result in: \(\sin^2x + \cos^2x = 1\). And math can also be done as a code block like so:

$$
\oint_S {E_n dA = \frac{1}{{\varepsilon _0 }}} Q_{inside}
$$

Gauss’ Law says: \[
\oint_S {E_n dA = \frac{1}{{\varepsilon _0 }}} Q_{inside}
\]

Equations can be cross-referenced just like tables and figures.