Reproducible scientific manuscripts and reports
Serrapilheira/ICTP-SAIFR Training Program in Quantitative Biology and Ecology
Andrea Sánchez-Tapia & Sara Mortara
10 August 2022
1 / 30

Writing and data analysis workflowsNon-linear: Come back and forth between coauthors, updating with updated results
2 / 30

Writing and data analysis workflows

Non-linear: Come back and forth between coauthors, updating with updated results
Copy and pasting results is error prone!

2 / 30

Writing and data analysis workflows

Non-linear: Come back and forth between coauthors, updating with updated results
Copy and pasting results is error prone!
Formatting, reference citing, adding figures can be cumbersome

2 / 30

Writing and data analysis workflows

Non-linear: Come back and forth between coauthors, updating with updated results
Copy and pasting results is error prone!
Formatting, reference citing, adding figures can be cumbersome
Depending on the area, we are mostly used to MS Office, Google docs and similar for collaborative writing

2 / 30

Writing and data analysis workflows

Non-linear: Come back and forth between coauthors, updating with updated results
Copy and pasting results is error prone!
Formatting, reference citing, adding figures can be cumbersome
Depending on the area, we are mostly used to MS Office, Google docs and similar for collaborative writing
In some areas, researchers use $L A T E X$ but it has a learning curve

2 / 30

A friendly writing workflow would allow us to3 / 30

A friendly writing workflow would allow us toWrite as we analyze
3 / 30

A friendly writing workflow would allow us to

Write as we analyze
Integrate code and text: Literate programming (Knuth 1984)

3 / 30

A friendly writing workflow would allow us to

Write as we analyze
Integrate code and text: Literate programming (Knuth 1984)
Facilitate coauthors revision

3 / 30

A friendly writing workflow would allow us to

Write as we analyze
Integrate code and text: Literate programming (Knuth 1984)
Facilitate coauthors revision
Update if there are changes

3 / 30

A friendly writing workflow would allow us to

Write as we analyze
Integrate code and text: Literate programming (Knuth 1984)
Facilitate coauthors revision
Update if there are changes
Allow citing, formatting and submitting

3 / 30

A friendly writing workflow would allow us to

Write as we analyze
Integrate code and text: Literate programming (Knuth 1984)
Facilitate coauthors revision
Update if there are changes
Allow citing, formatting and submitting

We can use the pros of working with scripts + version control and be transparent

3 / 30

Where are you today?

Do you use already a reference manager?
Do you use .bib and know how to create one?
Do you know about rmarkdown?
Do you know how to cite from .bib in markdown?
Do you know about $L A T E X$ ?
Do you use $L A T E X$ locally or using Overleaf?
Do you use git to version control your writing process?

4 / 30

 LATEXLATEX Document preparation system with high typographic quality
5 / 30

$L A T E X$

Document preparation system with high typographic quality
Text files with .tex extension. Output format: PDF

5 / 30

$L A T E X$

Document preparation system with high typographic quality
Text files with .tex extension. Output format: PDF
Text files: can be used with version control such as git

5 / 30

$L A T E X$

Document preparation system with high typographic quality
Text files with .tex extension. Output format: PDF
Text files: can be used with version control such as git
Deals correctly with math, scientific, algebraic notation

5 / 30

$L A T E X$

Document preparation system with high typographic quality
Text files with .tex extension. Output format: PDF
Text files: can be used with version control such as git
Deals correctly with math, scientific, algebraic notation
Typesetting (pagination, figure posititoning, general formatting)

5 / 30

$L A T E X$

Document preparation system with high typographic quality
Text files with .tex extension. Output format: PDF
Text files: can be used with version control such as git
Deals correctly with math, scientific, algebraic notation
Typesetting (pagination, figure posititoning, general formatting)
$L A T E X$ files can be submitted directly to some journals + dissertation templates in many institutions

5 / 30

$L A T E X$

Document preparation system with high typographic quality
Text files with .tex extension. Output format: PDF
Text files: can be used with version control such as git
Deals correctly with math, scientific, algebraic notation
Typesetting (pagination, figure posititoning, general formatting)
$L A T E X$ files can be submitted directly to some journals + dissertation templates in many institutions

A good way to learn and collaborate: Overleaf https://www.overleaf.com/

5 / 30

markdown and rmarkdown

https://bookdown.org/yihui/rmarkdown-cookbook/rmarkdown-process.html

6 / 30

Markdown markup

text
__bold__ and **bold**
superscript^2^
~~strikethrough~~
[link](www.rstudio.com)
# Heading 1
## Heading 2

text bold and bold
superscript²
~~strikethrough~~
link

Heading 1

Heading 2

7 / 30

Markdown markup

+ unnumbered list
+ unnumbered list

1. numbered list
1. numbered list

unnumbered list
unnumbered list

numbered list
numbered list

And all html commands!

<center> </center>

You can hide text 

You can hide text

8 / 30

help when writing: package remedy

Documentation: https://github.com/ThinkR-open/remedy
Installs as an RStudio addin
You can modify the keyboard shortcuts

Tools > Modify keyboard shortcuts

ctrl + b -> bold
ctrl + i -> italic
ctrl + k -> link
ctrl + 1 -> h1 (level 1 header)
ctrl + 2 -> h1 (level 2 header)
ctrl + r -> insert chunk

9 / 30

To add external figuresNative markdown: ![alt-text](/figs/fig.png)
10 / 30

To add external figures

Native markdown: ![alt-text](/figs/fig.png)
HTML: <img src ---->

10 / 30

To add external figures

Native markdown: ![alt-text](/figs/fig.png)
HTML: <img src ---->
$L A T E X$ : \includegraphics{}

10 / 30

To add external figures

Native markdown: ![alt-text](/figs/fig.png)
HTML: <img src ---->
$L A T E X$ : \includegraphics{}
For all formats: knitr::include_graphics(/figs/fig.png) (inside a chunk)

10 / 30

To add external figures

Native markdown: ![alt-text](/figs/fig.png)
HTML: <img src ---->
$L A T E X$ : \includegraphics{}
For all formats: knitr::include_graphics(/figs/fig.png) (inside a chunk)

Markdown has support for alternative text! `fig.alt =` parameter

10 / 30

Tables

Format

| name1 | name2 | name3 |
|:-----:|:-----:|:-----:|
| text1 | text2 | text3 |
| text1 | text2 | text3 |

Result

name1	name2	name3
text1	text2	text3
text1	text2	text3

11 / 30

Tables

Format

| name1 | name2 | name3 |
|:-----:|:-----:|:-----:|
| text1 | text2 | text3 |
| text1 | text2 | text3 |

Result

name1	name2	name3
text1	text2	text3
text1	text2	text3

From R chunks:
- knitr::kable()
- Package kableExtra

11 / 30

Tables

Format

| name1 | name2 | name3 |
|:-----:|:-----:|:-----:|
| text1 | text2 | text3 |
| text1 | text2 | text3 |

Result

name1	name2	name3
text1	text2	text3
text1	text2	text3

From R chunks:
- knitr::kable()
- Package kableExtra

Some services to create tables with the format: markdown table generator and HackMD (good support for tables).

11 / 30

Bibliographical reference management12 / 30

Reference managersSave citations, publication files (optional), assist in the citation and bibliographies
13 / 30

Reference managers

Save citations, publication files (optional), assist in the citation and bibliographies
Zotero, Mendeley, EndNote, Reference Manager

13 / 30

Reference managers

Save citations, publication files (optional), assist in the citation and bibliographies
Zotero, Mendeley, EndNote, Reference Manager
To cite in $L A T E X$ and markdown: BibTeX, File format: .bib

13 / 30

Reference managers

Save citations, publication files (optional), assist in the citation and bibliographies
Zotero, Mendeley, EndNote, Reference Manager
To cite in $L A T E X$ and markdown: BibTeX, File format: .bib

## @Manual{,
##   title = {vegan: Community Ecology Package},
##   author = {Jari Oksanen and F. Guillaume Blanchet and Michael Friendly and Roeland Kindt and Pierre Legendre and Dan McGlinn and Peter R. Minchin and R. B. O'Hara and Gavin L. Simpson and Peter Solymos and M. Henry H. Stevens and Eduard Szoecs and Helene Wagner},
##   year = {2020},
##   note = {R package version 2.5-7},
##   url = {https://CRAN.R-project.org/package=vegan},
## }

13 / 30

Using zotero or mendeleyReference storage and management in a local app
14 / 30

Using zotero or mendeley

Reference storage and management in a local app
A browser extension downloads citation and PDF if available

14 / 30

Using zotero or mendeley

Reference storage and management in a local app
A browser extension downloads citation and PDF if available
A connector for MS Word and LibreOffice

14 / 30

Using zotero or mendeley

Reference storage and management in a local app
A browser extension downloads citation and PDF if available
A connector for MS Word and LibreOffice
A citation styles repository: Zotero style repository. File extension: .csl

14 / 30

Using zotero or mendeley

Reference storage and management in a local app
A browser extension downloads citation and PDF if available
A connector for MS Word and LibreOffice
A citation styles repository: Zotero style repository. File extension: .csl
A site that creates citations from URL or DOI https://zbib.org/

14 / 30

Using zotero or mendeley

Reference storage and management in a local app
A browser extension downloads citation and PDF if available
A connector for MS Word and LibreOffice
A citation styles repository: Zotero style repository. File extension: .csl
A site that creates citations from URL or DOI https://zbib.org/
A way to create bibliographies in .bib BiBTex, Zotero(BetterBibTex), and Mendeley: create .bib for each collection, keeps updated

14 / 30

To cite documents in rmarkdownWith refs.bib and style.csl in /citation folder include .bib and .csl in the YAML header:bibliography: ../citation/refs.bib
csl: ../citation/nature.csl

15 / 30

To cite documents in rmarkdown

With refs.bib and style.csl in /citation folder include .bib and .csl in the YAML header:
- bibliography: ../citation/refs.bib
- csl: ../citation/nature.csl
Cite format: @name_word_year (check in the reference manager for the citation key)

15 / 30

To cite documents in rmarkdown

With refs.bib and style.csl in /citation folder include .bib and .csl in the YAML header:
- bibliography: ../citation/refs.bib
- csl: ../citation/nature.csl
Cite format: @name_word_year (check in the reference manager for the citation key)
- Ex. [@dignazio_data_2020] -> (D'Ignazio & Klein 2020)
- Ex. @dignazio_data_2020 -> D'Ignazio & Klein (2020)
- Ex. [@noble_algorithms_2018, @dignazio_data_2020] -> (Noble 2018, D'Ignazio & Klein 2020)

15 / 30

To cite documents in rmarkdown

With refs.bib and style.csl in /citation folder include .bib and .csl in the YAML header:
- bibliography: ../citation/refs.bib
- csl: ../citation/nature.csl
Cite format: @name_word_year (check in the reference manager for the citation key)
- Ex. [@dignazio_data_2020] -> (D'Ignazio & Klein 2020)
- Ex. @dignazio_data_2020 -> D'Ignazio & Klein (2020)
- Ex. [@noble_algorithms_2018, @dignazio_data_2020] -> (Noble 2018, D'Ignazio & Klein 2020)
Default: the bibliography is added at the end of the text, but can be placed anywhere with: <div id="refs"></div>

15 / 30

Creating a `.bib` in Mendeley

16 / 30

Creating a `.bib` in Zotero

17 / 30

Create the collection

18 / 30

You can download directly from the internet, even Amazon

19 / 30

Click to save

20 / 30

In the app, BetterBibTex creates the key

21 / 30

Export the collection

22 / 30

BetterBibTeX - keep updated!

23 / 30

the .bib is a text file

24 / 30

download citation styles

25 / 30

26 / 30

Other packages based in markdown

bookdown create whole books from several .Rmd
pagedown templates for thesis, CVs, in html
rticles: $L A T E X$ templates, accepted by journals (plos, Elsevier, Frontiers, etc.) only PDF!

remotes::install_github("rstudio/rticles")
rticles::journals()

thesisdown with university templates. Some variations: coppedown, ufscdown

27 / 30

Some final tips

Resist the temptation to create a single document mixing text and code (Don't do things just because you can)
- Scripts and outputs in separate folders than documents

28 / 30

Some final tips

Resist the temptation to create a single document mixing text and code (Don't do things just because you can)
- Scripts and outputs in separate folders than documents
- Several chapters - several folders, don't write in a single .Rmd

28 / 30

Some final tips

Resist the temptation to create a single document mixing text and code (Don't do things just because you can)
- Scripts and outputs in separate folders than documents
- Several chapters - several folders, don't write in a single .Rmd
Don't choose formats too early but don't leave this to the end

28 / 30

References

Rosanna van Hespen: Writing your thesis with R https://www.rosannavanhespen.nl/2016/02/16/writing-your-thesis-with-r-markdown-1-getting-started/

R Markdown: The Definitive Guide https://bookdown.org/yihui/rmarkdown/
R markdown cookbook: https://bookdown.org/yihui/rmarkdown-cookbook/
https://rmarkdown.rstudio.com https://bookdown.org/yihui/rmarkdown/interactive-documents.html

29 / 30

¡Thanks!

andreasancheztapia@gmail.com | saramortara@gmail.com

@SanchezTapiaA | @MortaraSara

andreasancheztapia | saramortara

30 / 30

↑, ←, Pg Up, k	Go to previous slide
↓, →, Pg Dn, Space, j	Go to next slide
Home	Go to first slide
End	Go to last slide
Number + Return	Go to specific slide
b / m / f	Toggle blackout / mirrored / fullscreen mode
c	Clone slideshow
p	Toggle presenter mode
t	Restart the presentation timer
?, h	Toggle this help

Reproducible scientific manuscripts and reports

Serrapilheira/ICTP-SAIFR Training Program in Quantitative Biology and Ecology

Andrea Sánchez-Tapia & Sara Mortara

10 August 2022

Writing and data analysis workflows

Writing and data analysis workflows

Writing and data analysis workflows

Writing and data analysis workflows

Writing and data analysis workflows

A friendly writing workflow would allow us to

A friendly writing workflow would allow us to

A friendly writing workflow would allow us to

A friendly writing workflow would allow us to

A friendly writing workflow would allow us to

A friendly writing workflow would allow us to

A friendly writing workflow would allow us to

We can use the pros of working with scripts + version control and be transparent

Where are you today?

LATEXLATEX

LATEXLATEX

LATEXLATEX

LATEXLATEX

LATEXLATEX

LATEXLATEX

LATEXLATEX

A good way to learn and collaborate: Overleaf https://www.overleaf.com/

markdown and rmarkdown

Markdown markup

Heading 1

Heading 2

Markdown markup

help when writing: package remedy

To add external figures

To add external figures

To add external figures

To add external figures

To add external figures

Markdown has support for alternative text! fig.alt = parameter

Tables

Tables

Tables

Bibliographical reference management

Reference managers

Reference managers

Reference managers

Reference managers

Using zotero or mendeley

Using zotero or mendeley

Using zotero or mendeley

Using zotero or mendeley

Using zotero or mendeley

Using zotero or mendeley

To cite documents in rmarkdown

To cite documents in rmarkdown

To cite documents in rmarkdown

To cite documents in rmarkdown

Creating a .bib in Mendeley

Creating a .bib in Zotero

Other packages based in markdown

Some final tips

Some final tips

Some final tips

References

¡Thanks!

Writing and data analysis workflows

Help

$L A T E X$

$L A T E X$

$L A T E X$

$L A T E X$

$L A T E X$

$L A T E X$

$L A T E X$

Markdown has support for alternative text! `fig.alt =` parameter

Creating a `.bib` in Mendeley

Creating a `.bib` in Zotero