---
title: Class Notes for FSCI 2018, July 30 - August 4, 2018
---

## Reproducible Research Reporting and Dynamic Documents with Open Authoring Tools: Toward the Paper of the Future

### About this Document

This is our collaborative course document to which you all are invited to contribute by adding questions, notes, and comments in markdown! (_Practice makes perfect, right?_). [The Carpentries](https://carpentries.org) have been using Etherpad for this purpose, but [AuthorCarpentry](https://authorcarpentry.github.io/) prefers HackMD because it reinforces core skills we teach. 😄

Please refer to the headings delineated in this document to add contributions to the most seemingly relevant section. If not sure, punt to __Miscellanea__ at the bottom of the document!

*****

## Course Information

1. Course syllabus on FSCI2018 Google Docs platform: not entirely up to date, so best to use (2) below
1. Course website on AuthorCarpentry GitHub platform with daily objectives, lesson plan, exercises. This is the most up-to-date!
https://authorcarpentry.github.io/FSCI-2018/

1. Course exercise files: `FSCI-2018-files.zip`
__NOTE__: These files will be finalized over the weekend preceding FSCI2018 so please don't download them until Day 1 of the class. We'll do it together to make sure we all have the exact same versions and that everything installs properly.

3. Course folders
The Instructors have prepared folders with printed materials most useful and relevant to the course discussions and exercises. We felt the paper was worth it to provide additional reading real-estate in a busy, technology-dominant class environment. There are additional supplemental materials you may find helpful but those are provided as online urls in the next section.

4. Online resources to supplement the printed folder
- General for the Course
- Getting used to R, RStudio, and R Markdown (Chester Ismay), https://ismayc.github.io/rbasics-book/
- RMarkdown Reference Guide, https://www.rstudio.com/wp-content/uploads/2015/03/rmarkdown-reference.pdf
- RMarkdown, the Definitive Guide <https://bookdown.org/yihui/rmarkdown/>
- Knitr (Xie), https://yihui.name/knitr/
- Pandoc - a universal document converter, https://pandoc.org/
- Day 1, Introduction to the Course (Monday, July 30)
- Journal pretty much the same since 1600's
- http://rstl.royalsocietypublishing.org/
- https://onlinelibrary.wiley.com/doi/abs/10.1111/ele.13085
- _OR is it?_
- https://github.com/cboettig/noise-phenomena

*****
## Whos Who?

### Course Instructors
1. __Tom Morrell__ | Research Data Specialist, Caltech Library. | Email: tmorrell at caltech dot edu. | Twitter and GitHub username: @temorrell | hates to reformat for different publisher requirements
3. __Gail Clement__ | Head of Research Services, Caltech Library. Email: gperetsm at caltech dot edu. Twitter and GitHub username: @Repositorian. _Relinquished pet peeves on joining [Carpentries community](https://carpentries.org/)_
4. __Other contributors to the course content__: Author Carpentry supporters Sebastian Karcher, Donna Wrublewski, Robert Doiel, and Patrick from our Mozilla Sprint whose guidance on lesson planning have made a YUGE difference in how we teach this material.

### Participants

- Katie, Harvard-Smithsonian CFA, software citation and archiving
- Gana, MongoliaJOL manager, Mongolia, software citation and publication
- Amy, BMJ Editor, Oxford, software not reproducible; how to manage clinical documents for citation
- Kimberly, U Az Libraries, software citation and integration with repositories, long-term access and preservation; publication formats dictate the form of the communication eg pdf
- Jackie, Postdoc CS UMD, Improve authoring for reproducibility
- Taylor, UH Libraries, Publisher of Hums journal, lack of transparency in review
- Pei-Ying, Phd student at IU-schol comm, open authoring practices
- Annelise, UCSD Lib, Pol Sci, cost of journals and cost of APCS, poorly described methodologies
- Corinne, Research Associate at SIO, improving authoring and reproducibility
- Nina like China, Lib at VCU, Phd Student at UNC SILS, limit in practical tips
- Dan, Data science Gatorland, Code aesthetics; GitHub repo practices
- Steve, LIS Prof at Bama, next gen publishing for next gen librarians. Changing meaning of 'paper'
- Frank, Health Sci Librarian at UMn/Reprod/Software Carpentry, library lit is terrible on methodology, poor reporting practices in clinical med. Pet peeve: citation styles: lets get rid of them completely. Most things most times can be easily found with just some basic information. Too much time and intellectual effort is wasted on citation styles. fight me.
- Zoe, Science Librarian, peeveless

*****

## Day 1 Questions, Comments, or Corrections

## Day 2 Questions, Comments, or Corrections

### What journal styles are available and do they have two column layouts?

This (probably) requires a LaTex install and the R package `rticles`.

https://cran.r-project.org/web/packages/rticles/readme/README.html

An example two column style is an IEEE conference paper. After installing rticle, you can load the template with:

library(rmarkdown)
draft("~/Desktop/MyArticle.Rmd", template = "ieee_article", package = "rticles")

## Day 3 Questions, Comments, or Corrections

Research Compendium: https://research-compendium.science/

####

Supported html themes at the time of this writing
- "cerulean"
- "journal"
- "flatly"
- "readable"
- "spacelab"
- "united"
- "cosmo"
- "lumen"
- "paper"
- "sandstone"
- "simplex"
- "yeti"

Good reading with tips on knitting to Word: "Happy collaboration with Rmd to docx"
<https://rmarkdown.rstudio.com/articles_docx.html>

#### Extra reference chunk for YAML:

references:
- id: Xie_2018
  title: R Markdown - The Definitive Guide
  author:
  - family: Xie
    given: Yihui
  - family: Allaire
    given: J. J.
  - family: Grolemund
    given: Garrett  
  URL: 'http://dx.doi.org/10.1038/nmat3283'
  ISBN: 9781138359338
  publisher: Chapman & Hall/CRC
  type: book
  issued:
    year: 2018
    month: 6

Are the files created in RMarkdown directly useable in GitHub?
- HTML output: Yes!
- You can rename the final output html as index.html, move it to a /docs folder, and then create a website from the GitHub repo, specifying that the files will be found in the /docs subfolder on GitHub.
- Markdown output: No.
- You need to specify in the YAML that you want to keep the .md file created during the knit process and it needs to be github flavored markdown as shown below:
- ---

output:
  md_document:
    variant: markdown_github
    keep_md: true

#### How to call references from Zotero database using RefManageR package
<https://tclavelle.github.io/blog/reference_tips/>

## Day 4 Questions, Comments, or Corrections

To add a citation style (CSL) to your report, follow these steps:
1. Visit the [Zotero Style Repository](https://www.zotero.org/styles) and select a citation style of interest
2. From that site, download the desired style file to your working folder (where your exercise files live)
3. In the yaml for your exercise file, add a new line `csl: name-of-file.csl`
4. Knit and review the references in your document: did the new style get applied?

The R package ProjectTemplate is just one tool to help keep all of your data and analysis organized.

---

## Day 5 Questions, Comments, or Corrections

*****

## Parking Lot to capture questions and comments needing follow-up

Pulling citations from one's Mendeley/Refworks/Endnote/Zotero (Amy)
- See Day 3 Notes

## Resources for Learning More

- CODATA-RDA Legal Interoperability of Research Data Group <https://rd-alliance.org/groups/rdacodata-legal-interoperability-ig.html>
- Principles and Guidelines for Legal Interoperability <https://www.rd-alliance.org/rda-codata-legal-interoperability-research-data-principles-and-implementation-guidelines-now>
- RMarkdown hub at RStudio <https://rmarkdown.rstudio.com/>
- Software Carpentry's Lesson on Repro Reporting <https://swcarpentry.github.io/swc-releases/2016.06/r-novice-gapminder/15-knitr-markdown/>
- DataCamp's Reporting with RMarkdown <https://www.datacamp.com/courses/reporting-with-r-markdown>
- Yihui's Blog <https://yihui.name/en/>
- Karl Broman's Tutorials <https://kbroman.org/pages/tutorials.html>
- Chris Hartergink's site <https://www.tilburguniversity.edu/webwijs/show/c.h.j.hartgerink.htm>
- AuthorCarpentry <https://authorcarpentry.github.io/>
- All course content from this week <https://github.com/AuthorCarpentry/FSCI-2018>

## Next Steps
- Author day to day docs in Rmarkdown
- Connect with colleagues teaching data science
- Introduce this authoring workflow into discussions about new forms of the thesis
- Parlay understanding of what is possible to Jupyter Notebooks
- Introduce the markdown workflow to early career researchers and to those preparing manuscripts for publication
- Share with affinity groups on campus, RLadies, Carpentry Club
- Think through application of this workflow versus RNotebooks, which are easier to start with.