I read with interest the the Transparency and Openness Promotion (TOP) Committee templates for guidelines to enhance transparency in the science that journals publish.
Citation
Supplementary Materials for Nosek, B. A., Alter, G., Banks, G. C.,
Borsboom, D., Bowman, S. D., Breckler, S. J., … Yarkoni,
T. (2015). Promoting an open research culture. Science, 348(6242),
1422–1425. doi:10.1126/science.aab2374
I think though that guidelines like the suggestion to copy-paste bits of the manuscript leave a bit to be desired:
Quote;
Authors document compliance by copy-pasting the relevant passages
in the paper that address the question into the form. For example,
when indicating how sample size was determined, authors copy paste
into the form the text in the paper that describes how sample size
was determined.
Reproducible Research Reports solve this problem by ensuring that the data preparation and analysis are executed in the same script that produces the manuscript, therefore a one-stop-shop for documentation of the entire study.
There is a need for Templates of Reproducible Research Reports (that look good!)
Rstudio provides very easy support for these documents if you use R. In particular the option of a menu button to create a new report populates that report with the required header information and some example script to work off. But the easiest option does not look so good. This is the Rmarkdown option and it is very user friendly in terms of the markup language needed to write the descriptive language around your analysis (mostly plain text with a few simple options for heading styles etc) rather than the Sweave option which leads to the full blown LaTeX markup language that is a lot more complicated.
Boilerplate Rmarkdown header from Rstudio:
---
title: "Untitled"
author: "Ivan C. Hanigan"
date: "16 September 2015"
output: html_document
---
This is great for quick reporting of work as you go, but I primarily write for output that will be printed (e.g. pdf docs). More specifically, I need the concept of a page, and to have full control over the placement of table and figure ‘environments’, stuff that is easy in LaTeX (once you figure out some of the esoteric parts of that language).
To achieve a simple writing environment in Markdown but with the powerful layout options of LaTeX I reviewed this guys work but I think it takes it to an uneccessary level of complicated-ness https://github.com/jhollist/manuscriptPackage.
So I went back to some of the old Sweave/Latex templates I had put together and ported it into a markdown header.
Boilerplate Rmarkdown header for pretty report
---
title: "Untitled"
author: "Ivan C. Hanigan"
date: "16 September 2015"
header-includes:
- \usepackage{graphicx}
- \usepackage{fancyhdr}
- \pagestyle{fancy}
- \usepackage{lastpage}
- \usepackage{float}
- \floatstyle{boxed}
- \restylefloat{figure}
- \usepackage{url}
- \usepackage{color}
- \lhead{Left Header}
- \chead{Rmarkdown Rocks}
- \rhead{\today}
- \lfoot{Left Footer}
- \cfoot{Centre Footer}
- \rfoot{\thepage\ of \pageref{LastPage}}
output:
pdf_document:
toc: false
documentclass: article
classoption: a4paper
bibliography: references.bib
---
Now the layout of tables and figures is done with latex
Code
Using the xtable package allows results to be displyed in tables
and has built in support for some R objects, so summrising the
linear fit above in ~\ref{ATable}
```{r, results='asis', type = 'tex'}
library(xtable)
print(xtable(fit, caption="Example Table",
digits=4,table.placement="ht",label="ATable"), comment = F)
```
## A Plot
Plots intergrate most easily if made seperately as can be seen in figure ~\ref{test}
```{r}
png("Rmarkdownfig.png")
plot(x,y,main="Example Plot",xlab="X Variable",ylab="Y Variable")
abline(fit,col="Red")
dev.off()
```
\begin{figure}[H]
\begin{center}
\includegraphics[width=.5\textwidth]{Rmarkdownfig.png}
\end{center}
\caption{Some Plot}
\label{test}
\end{figure}
\clearpage
I also realised that if this was to be a full report of a scientific study it would need to include some of the machinery needed for bibliographies.
Stuff for bibliographies
```{r, echo=F, results = 'hide', message = F, warning=F}
library("knitcitations")
library("bibtex")
cleanbib()
cite_options(citation_format = "pandoc", check.entries = FALSE)
bib <- read.bibtex("C:/Users/Ivan/Dropbox/references/library.bib")
```
<!--Put data analysis and reporting here, then at the end of the doc-->
```{r, echo=F, message=F, eval=T}
write.bibtex(file="references.bib")
```
# References
<!--The bib will then be written following the final subheading-->
Conclusion
I hope this might help others develop their own templates for RRR that look great.
