Who am I?

Resul Umit

• post-doctoral researcher in political science at the University of Oslo

• teaching and studying representation, elections, and parliaments

  • a recent publication: the effects of casualties in terror attacks on elections

• teaching workshops, also on

  • version control and collaboration
  • automated web scraping
  • working with Twitter data
  • creating academic websites

• more information available at resulumit.com

How did I use to write?

First, with Stata + Word, I was ...

• frustrated with Word

  • formatting tables, figures, citations, and equations
  • managing references

• tired of switching between programmes/screens

  • and, worried about making mistakes in between

• paying for programme licences

How did I use to write?

Then, with Stata + R + LaTeX, I was ...

• frustrated with Word

  • formatting tables, figures, citations, and equations
  • managing references

• tired of switching between programmes/screens

  • and, worried about making mistakes in between

• paying for the Stata licence

• converting PDF documents to Word manually

  • coordinating work with co-authors who don't use LaTeX/PDF
  • submitting to journals which don't accept LaTeX/PDF

How do I write now?

Now, with R Markdown, I am ... happy!

• frustrated with Word

  • formatting tables, figures, citations, and equations
  • managing references

• tired of switching between programmes/screens

  • and, worried about making mistakes in between

• paying for the Stata licence

• converting PDF documents to Word, manually

  • coordinating work with co-authors who don't use LaTeX/PDF
  • submitting to journals which don't accept LaTeX/PDF

R Markdown

• Efficient

  • write text, cite sources, tidy data, analyse, table, and plot it in one programme/screen
  • re-do one, more, or all of these with ease
    • decrease the possibility of making mistakes in the process

• Flexible

  • output to various formats
    • e.g., HTML, LaTeX, PDF, Word

• Open access/source

  • use for free
  • create documents accessible to anyone with a computer and internet connection
  • benefit from the work of a great community of users/developers

Reproducibilty — Before Publication

• Having written a complete draft

  • with data including re-coded variables, tables, figures, and text with references to specific results (e.g., numbers from summary and/or regression statistics)

• If you and/or your co-authors decide

  • to reverse a re-coded variable to its previous/original measure
  • and/or, to exclude a subgroup of observations from analysis

• How resource intensive would this revision be?

  • how long would this revision take?
  • how many programmes would be needed for this revision, and how much would they cost?
  • there is an inverse relationship between this resource intensity and reproducibilty

Reproducibilty — After Publication

• After your paper is published, if others, including your future self, would like to test how robust the results are

  • to reversing a re-coded variable to its previous/original measure
  • and/or, to excluding a subgroup of observations from analysis

• How resource intensive would this test be?

  • how accessible is the data, documentation (how was the variable re-coded in the first place?), and the code?
  • how long would the test take?
  • how many programmes would be needed for this revision, and how much would they cost?
  • there is an inverse relationship between this resource intensity and reproducibilty

The Workshop — Overview

• Two days, on how to write reproducible research papers with R Markdown

  • 200+ slides, 40+ exercises, and time for converting a real project

• Based on converting a mock manuscript written in Word to R Markdown

  • plus, improving its reproducibility and version-controlling it
  • with a PDF output in mind

• Designed for researchers with basic knowledge of R programming language

  • does not cover programming with R
    • e.g., writing functions
      
      
  • ability to regress, plot, and table in R will be very helpful
    • but not absolutely necessary — these skills can be developed after learning R Markdown as well

The Workshop — Contents

The Workshop — Organisation

• Sit in groups of two

  • participants learn as much from their partner as from instructors
  • switch partners after every second part

• Type, rather than copy and paste, the code that you will find on these slides

  • typing is a part of the learning process

• When you have a question

  • ask your partner
  • google together
  • ask me

The Workshop — Organisation — Slides

• Codes and texts that go in R Markdown documents appear as such — in a different font, on gray background

  • long codes and texts will have their own line(s)

```{r, scatterplot, fig.cap = "A scatterplot of journal metrics."}
ggplot(data = df, mapping = aes(x = h5_median, y = h5_index, color = subfield)) +
       geom_point() +
       facet_wrap(. ~ branch) +
       scale_colour_discrete(name = "Journal Type", breaks = c(0, 1), labels = c("Generalist", "Subfield"))    
```

The Workshop — Organisation — Slides

• Codes and texts that go in R Markdown documents appear as such — in a different font, on gray background

  • long codes and texts will have their own line(s)

• Results that come out in output files appear as such — in the same font, on green background

  • except very obvious results, such as figures and tables

• Specific sections are highlighted yellow as such for emphasis

  • these could be for anything — codes and texts in input, results in output, and/or texts on slides

• The slides are designed for self-study as much as for the workshop

  • accessible, in substance and form, to go through on your own

The Workshop — Aims

• To make you aware what is possible with R Markdown

  • we will cover a large breath of issues, not all of it is for long-term memory
    • one reason why the slides are designed for self study as well
      
      
  • awareness of what is possible, Google, and perseverance are all we need

• To encourage you to convert into R Markdown

  • practice with a mock manuscript (Parts 3–9)
  • start converting a real one (Part 10)

Course Materials — Overview

Notice that the folder has the following structure

YOURNAME-rmd
   |
   |- manuscript
   |  |
   |  |- reproduce_this.pdf
   |  |- journals.Rmd
   |  |- references.bib
   |  |- apa_7th.csl
   |
   |- data
   |  |
   |  |- journals.csv
   |
   |- image
   |  |
   |  |- google_scholar.png

Course Materials — Contents

• manuscript\reproduce_this.pdf

  • the document, formatted in Word but saved as PDF, that we will re-create with R Markdown
  • randomly generated sentences, with figures and tables from randomly a generated dataset^*
  • key sections in need of attention are highlighted yellow

Course Materials — Contents

• manuscript\reproduce_this.pdf

  • the document, formatted in Word but saved as PDF, that we will re-create with R Markdown
  • randomly generated sentences, with figures and tables from randomly generated dataset
  • key sections in-need of attention are highlighted

• manuscript\journals.Rmd

  • the R Markdown document that we will work on
  • includes unformatted text from reproduce_this.pdf to save time
  • major components, such as paragraphs and tables, are numbered and marked in comments to facilitate navigation

• manuscript\references.bib

  • a BibTeX document with three fabricated references

• manuscript\apa_7th.csl

  • a Citation Style Language document, with APA (7th Edition) referencing style (Wiernik, 2020)

Course Materials — Contents

data\journals.csv

• a dataset created with the fabricatr package (Blair, Cooper, Coppock, et al., 2022), imagined to explore the Google Scholar rankings of fictitious journals

• includes the following variables

  • name: journals (1090 random titles)
  • origin: geographic origins (five continents)
  • branch: major discipline of journals (four branches)
  • since: time of first publication (years)
  • h5_index: H5 Index (integers)
  • h5_median: H5 Median (integers)
  • english: English (1) vs. other-language (0) journals
  • subfield: subfield (1) vs. generalist (0) journals
  • issues: number of issues published per year (integers)

Course Materials — Contents

• image\google_scholar.png

  • a screeenshot image of the Google Scholar homapage

RStudio — R Markdown Options

RStudio — R Markdown Options

Other Resources^*

• Pandoc User's Guide

  • available at https://pandoc.org/MANUAL.html

• R Markdown: The Definitive Guide (Xie, Allaire, and Grolemund, 2018)

  • open access at https://bookdown.org/yihui/rmarkdown

• R for Data Science (Wickham and Grolemund, 2021)

  • open access at https://r4ds.had.co.nz

R Markdown Document — Components

R Markdown Document — Components

R Markdown Document — Components

R Markdown Document — Document Toolbar

Observe also that the document toolbar offers extended tools for .Rmd documents

These include, most impotantly,

• the button to compile .Rmd documents

R Markdown Document — Compilation Process

• When you Knit, the following happens:

  .Rmd --knitr--> .md --pandoc--> output

  • knitr^* executes the code if there is any, converts the resulting document from .Rmd (R Markdown) into .md (Markdown)

  • pandoc^** transforms the .md document into your preferred output format(s)

    • e.g., HTML, LaTeX, PDF, Word

• This process is automated by the rmarkdown package

R Markdown Document — Notes

• Behind the scenes, each .Rmd file is compiled in its own session, and therefore

  • the code needs to stand alone, for reproducibility reasons
  • e.g., if you load a package in the Console, it will not be available to a given .Rmd file — even in the same R session

• R Markdown can produce more than documents,^* including

  • presentations, again with rmarkdown
  • books, with bookdown (Xie, 2022a)
  • websites, with blogdown (Xie, Dervieux, and Presmanes Hill, 2022)

YAML — Overview

.Rmd documents start^* with YAML

• includes the metadata variables
  • e.g., title, output format
    
    
• written between a pair of three hyphens -

---
title: 
output:
---

YAML — Variables

• title and output are the basic variables of YAML

  • variable names are typed in lower case, followed by a colon :
    
  • the list of available variables, as well as options and sub-options for these variables, depends on the output format
    • Pandoc User's Guide provides a comprehensive documentation
    • R Markdown Cheat Sheet provides a helpful list

• Typical YAML variables for an research paper are as follows:

---
title: 
author: 
date: 
bibliography: 
csl: 
output: 
---

YAML — Variables

Variables can take strings

---
title: "Journals: Random Words With Random Data"
output:
---

YAML — Variables

Variables can take strings, options

---
title: "Journals: Random Words With Random Data" 
output: pdf_document
---

YAML — Variables

Variables can take strings, options, sub-options

---
title: "Journals: Random Words With Random Data" 
output: 
    pdf_document:
        keep_tex: true
---

YAML — Variables

Variables can take strings, options, sub-options, and code

---
title: "Journals: Random Words With Random Data" 
output: 
    pdf_document:
        keep_tex: true
date: "`r format(Sys.Date(), '%d %B %Y')`"
---

YAML — Variables — Output Formats

---
title: "Journals: Random Words With Random Data" 
output: html_document
---

YAML — Variables — Output Formats

---
title: "Journals: Random Words With Random Data" 
output: latex_document
---

YAML — Variables — Output Formats

---
title: "Journals: Random Words With Random Data" 
output: pdf_document
---

YAML — Variables — Output Formats

---
title: "Journals: Random Words With Random Data" 
output: word_document
---

YAML — Variables — Output Formats

YAML — Strings

---
title: "Journals: Random Words With Random Data"
output: pdf_document                                  
---

YAML — Strings

---
title: "Journals: Random Words With Random Data" 
subtitle: A Mock Paper for an R Markdown Workshop
author: Jane Doe
date: 4 March 2020
output: pdf_document                                  
---

YAML — Strings — Footnotes

---
title: "Journals: Random Words With Random Data^[Preliminary draft. Please do not cite or circulate without permission from the author.]"
subtitle: A Mock Paper for an R Markdown Workshop
author: "Jane Doe^[Department of Science, University of Random. Email: jane.doe@random.edu. Website: http://www.janedoe.com.]"
date: 4 March 2020                                
output: pdf_document                                    
---

YAML — Strings — External Files

The bibliography and csl variables take strings as well

---
title: "Journals: Random Words With Random Data^[Preliminary draft. Please do not cite or circulate without permission from the author.]"
subtitle: A Mock Paper for an R Markdown Workshop
author: "Jane Doe^[Department of Science, University of Random. Email: jane.doe@random.edu. Website: http://www.janedoe.com.]"                                    
date: 4 March 2020 
bibliography: references.bib
csl: apa_7th.csl
output: pdf_document                                    
---

YAML — Strings — External Files

The strings for external files indicate (a) where the files are located and (b) how they are named

---
...
bibliography: references/ref_library.bib                                    
csl: "../../styles/chicago_manual_17.csl"
...
---

YAML — Strings — External Files

The strings for external files indicate (a) where the files are located and (b) how they are named

---
...
bibliography: references/ref_library.bib                                    
csl: "../../styles/chicago_manual_17.csl"
...
---

Notice that

• the locations above are specified as relative to the working directory

  • the former (references) is a sub-directory, or folder, one level down while the latter (styles) is two levels up

• for reproducibility reasons, hard-coded stings should be avoided

  • e.g., "C:/Users/resulumit/Dropbox/styles/chicago_manual_17.csl"

YAML — Strings — External Files

The strings indicate (a) where the files are located and (b) how they are named

---
...
bibliography: references/ref_library.bib                                    
csl: "../../styles/chicago_manual_17.csl"
...
---

YAML — Options and Sub-Options

---
title: "Journals: Random Words With Random Data^[Preliminary draft. Please do not cite or circulate without permission from the author.]"
subtitle: A Mock Paper for an R Markdown Workshop
author: "Jane Doe^[Department of Science, University of Random. Email: jane.doe@random.edu. Website: http://www.janedoe.com.]"
date: 4 March 2020  
bibliography: references.bib
csl: apa_7th.csl   
output:
    pdf_document:
        keep_tex: true
---

YAML — Options and Sub-Options

---
title: "Journals: Random Words With Random Data^[Preliminary draft. Please do not cite or circulate without permission from the author.]"
subtitle: A Mock Paper for an R Markdown Workshop
author: "Jane Doe^[Department of Science, University of Random. Email: jane.doe@random.edu. Website: http://www.janedoe.com.]"                                    
date: 4 March 2020  
bibliography: references.bib
csl: apa_7th.csl   
output:
    pdf_document:
        keep_tex: true
---

YAML — R Code

---
title: "Journals: Random Words With Random Data^[Preliminary draft. Please do not cite or circulate without permission from the author.]"
subtitle: A Mock Paper for an R Markdown Workshop
author: "Jane Doe^[Department of Science, University of Random. Email: jane.doe@random.edu. Website: http://www.janedoe.com.]"
date: "`r format(Sys.Date(), '%d %B %Y')`"
bibliography: references.bib
csl: apa_7th.csl   
output: pdf_document
---

YAML — R Code

---
title: "Journals: Random Words With Random Data^[Preliminary draft. Please do not cite or circulate without permission from the author.]"
subtitle: A Mock Paper for an R Markdown Workshop
author: "Jane Doe^[Department of Science, University of Random. Email: jane.doe@random.edu. Website: http://www.janedoe.com.]"
date: "`r format(Sys.Date(), '%d %B %Y')`"
bibliography: references.bib
csl: apa_7th.csl   
output: pdf_document
---

YAML — R Code

---
title: "Journals: Random Words With Random Data^[Preliminary draft. Please do not cite or circulate without permission from the author.]"
subtitle: A Mock Paper for an R Markdown Workshop
author: "Jane Doe^[Department of Science, University of Random. Email: jane.doe@random.edu. Website: http://www.janedoe.com.]"
date: "First version: 4 March 2020. This version: `r format(Sys.Date(), '%d %B %Y')`."
bibliography: references.bib
csl: apa_7th.csl   
output: pdf_document
---

YAML — Some Further Settings for PDF Outputs

• fontsize

  • the default is 10pt
  • the other options are 11pt and 12pt

• linkcolor, urlcolor, citecolor

  • the default is the colour of the text
  • the other options are white, red, green, blue, cyan, magenta, yellow

• link-citations

  • the default is no
  • the other option is yes — a click on an citation will take the screen to the relevant entry in the list of references

Syntax — Overview

• There are not one, but several different versions of Markdown

  • e.g., Pandoc, MultiMarkdown, CommonMark
  • each might implement the same things (e.g., citations) slightly differently, and each might offer unique functionalities

• R Markdown follows the syntax in Pandoc's Markdown

  • for the complete rules of the syntax, see Pandoc User's Guide
  • for a useful summary of the syntax, see the R Markdown Cheat Sheet

Syntax — Lines

Multiple spaces on a given line are reduced to one

This is a sentence followed by four spaces.    This is another sentence on the same line.

This is a sentence followed by four spaces. This is another sentence on the same line.

Line endings with fewer than two spaces are ignored

This is a sentence followed by one space.
This is another sentence on a new line.

This is a sentence followed by one space. This is another sentence on a new line.

Syntax — Hard Breaks

Two or more spaces at the end of lines introduce hard breaks, forcing a new line

This is a sentence followed by two spaces.  
This is another sentence on a new line.

Syntax — Line Blocks

Spaces on lines that start with a vertical line | are kept

| a one-space indent
|     a five-space indent
|          a ten-space indent

Syntax — Block Quotes

Lines starting with the greater-than sign > introduce block quotes^*

> In God, we trust. All others must bring data. 
>
> --- Anonymous

Syntax — Paragraphs

One or more^* blank lines introduce a new paragraph

This is the first sentence of a paragraph as it is preceded by a blank line. This is the second 
sentence of that paragraph, which is followed by a blank line. 
This is the first sentence of a *new paragraph* as it is preceded by a blank line. This is the 
second sentence of that paragraph, which is followed by a blank line.

Syntax — Comments

Text with the syntax <!--comments --> is omitted from output

<!-- This paragraph needs re-writing -->
This is the first sentence of a paragraph as it is preceded by a blank line. This is the second 
sentence of that paragraph, which is followed by a blank line. 
This is the first sentence of a new paragraph <!-- I've removed italics --> as it is preceded 
by a blank line. This is the second sentence of that paragraph, which is followed by a blank 
line.

Syntax — Headers

The number sign # introduces headers; lower levels are created with additional signs — up to total five levels

Syntax — Emphases

A pair of single asterisk * or underscores _ introduces italics

*italics* becomes italics

_italics_ becomes italics as well

A pair of double asterisk or underscores introduces bold

**bold** becomes bold

__bold__ becomes bold as well

These two rules can be combined

**_bolditalics_** becomes bolditalics

_**bolditalics**_ becomes bolditalics as well

Syntax — Strikethrough

A pair of double tildes ~ introduces strikethrough

~~strikethrough~~ becomes strikethrough

Strikethrough can be combined with italics or bold

**~~strikebold~~** or __~~strikebold~~__, they both become strikebold

~~**strikebold**~~ or ~~__strikebold__~~, they both become strikebold as well

*~~strikeitalitcs~~* or _~~strikeitalitcs~~_, they both become strikeitalitcs

~~*strikeitalitcs*~~ or ~~_strikeitalitcs_~~, they both become strikeitalitcs as well

Syntax — Links — Internal^*

You can link text to section headers in the same document

[Conclusion](#conclusion) becomes Conclusion, and a click takes the screen to that section

Multi-word headers need hyphenation

[Literature Review](#literature-review) becomes Literature Review, and it works only if the second part is hyphenated

Syntax — Links — External

You can link text to URLs

[visit my website](https://resulumit.com/) becomes visit my website

[https://resulumit.com](https://resulumit.com/) becomes https://resulumit.com

<https://resulumit.com> becomes https://resulumit.com as well

You can also link text to an email address

[email me](mailto:resuluy@uio.no)^* becomes email me

<resuluy@uio.no> becomes resuluy@uio.no

Syntax — Equations

Inline equations go between a pair of single dollar signs $ — with no space between the signs and the equation itself

$E = mc^{2}$ becomes E = mc²

Block equations go in between a pair of double dollar signs — with or without spaces, it works

$$ E = mc^{2}$$ becomes

$$E = mc_{2}$$ becomes

Syntax — Footnotes — Inline Notes

For inline footnotes, use the ^[footnote] syntax

Jane Doe^[Corresponding author.] becomes Jane Doe¹

Notice that

• the caret sign ^ comes before the left square bracket [
• this syntax works in YAML as well as in text
  • footnotes in YAML get symbols, in text they get numbers

Syntax — Footnotes — Notes with Identifiers

An alternative is to use the [^identifier] syntax, with identifiers defined elsewhere in the same document

Dr Doe holds a PhD in rock science.[^defence_date]
[^defence_date]: She defended her thesis in 2017.

Dr Doe holds a PhD in rock science.¹

Notice that

• the caret sign comes after the left square bracket
• this syntax works in text, but not in YAML

Syntax — Lists

Lines starting with asterisk * as well as plus + or minus − signs introduce lists

- books
- articles
- reports

Syntax — Lists — Nesting

Lists can be nested within each other, with indentation

+ books
+ articles
    - published
    - under review
        + revised and resubmitted
    - work in progress

Syntax — Lists — Numbering

List items can be numbered

1. books
2. articles
    - published
    - under review
        + revised and resubmitted
    - work in progress

Syntax — Dashes

Two hyphens grouped together introduce an en-dash

‐‐ becomes –

Three hyphens grouped together introduce an em-dash

‐‐‐ becomes —

Syntax — Subscripts and Superscripts

Syntax — Subscripts and Superscripts

References — Bibliography Database

References — Bibliography Database — Entries

References — Bibliography Database — Entries

• One could create entries by hand

  • requires knowing the BibTeX format, entry types, tags, and related information about references to be cited
  • neither efficient nor necessary

• A good alternative is to use Google Scholar, which provides BibTeX entries

  • follow cite -> BibTex and copy
  • paste into .bib, edit if necessary, and save

• Some publishers and journals provide BibTeX entries on their website as well

References — Style

References — In-text Citation Syntax — Author-Date Styles^*

All citations keys take the 'at' sign @ while square brackets and/or minus signs introduce variation

References — In-text Citation Syntax — Numerical Styles

All citations keys take the 'at' sign @

A clever sentence.[@bennett2015] becomes A clever sentence.^[1] in certain numerical sytles

A clever sentence.[@bennett2015; @gilbert2019] becomes A clever sentence.^[1,2]

Individual styles may or may not use additional information, such as page numbers

A clever sentence.[@bennett2015 35] might become A clever sentence.^[1] as well

Individual styles may or may not be sensitive to variation, such as square brackets

A clever sentence. @bennett2015 might become A clever sentence.^[1] as well

Citations — Reference List

The list of references appears after the last line of the output document, with no section header

• so that you can choose the header yourself, by ending .Rmd documents with a header of your choice

This is the last sentence of an APA style manuscript.
## References

References — Internal Links

For internal links from in-text citations to the reference list, set link-citations: yes in YAML

• a click on these links takes the screen to the relevant entry in the list
• the linkcolor variable make these links explicit
  • setting this is not necessary for the links to work — the default is black

---
...
bibliography: references.bib
csl: apa_7th.csl
link-citations: yes
linkcolor: blue
...
---

Code — Overview

Most codes go inside code chunks

• e.g., code that imports and cleans data, and/or produces tables and/or figures

```{r}
df <- read.csv("rmd_workshop_files/images_data/journals.csv") %>% 
      mutate(age = 2020 - since,
             english = factor(english),
             subfield = factor(subfield))
```

Codes can also go in line with text

• e.g., code that results in a single statistic

The average H5 Index for the journals in the dataset is `r mean(df$h5_index)`.

Code Chunks — Overview

```
```

Code Chunks — Overview

```{r}
```

Code Chunks — Overview

```{r, setup}
```

Code Chunks — Overview

```{r, setup, echo=FALSE}
```

Code Chunks — Lenguage Engines

The first item in code chunks indicates the engine to run the code

```{r}
```

Note that

• indicating an engine for each chunk is a must

  • otherwise, any code^* in these chunks cannot be executed

• r is the specified engine, indicating that the code in the chunk above should be run by R

  • it could have been python, which we will not cover in this workshop

Code Chunks — Labels

It is recommended, but optional, to label the code chunks

```{r, data_import}
df <- read_csv("data/journals.csv")
```

Note that

• labels are written after the language engine, separated by a comma

  • in the example above, the chunk is labelled as data_import

• chunks without labels are otherwise automatically numbered

  • specifying informative labels can be helpful for, e.g., navigating through error messages

• duplicate labels lead to errors during compilation

Code Chunks — Options

Code chunks can take further options

```{r, setup, include=FALSE}
```

Note that

• in the example above, the include option is set to FALSE

  • with this option and value, nothing from this chunk will be included in the output document

• The complete list of options is available at https://yihui.org/knitr/options

  • R Markdown Cheat Sheet provides a helpful list as well

• leaving spaces around the equal sign =, between option tags and values, should be avoided

  • such spaces might lead to errors

Code Chunks — Options — Alternative Syntax

Options can be specified inside code chunks as well, after a number sign and a vertical line #|

• therefore the following chunks have the same function

```{r, echo=FALSE, eval=TRUE}
```

```{r}
#| echo = FALSE, eval = TRUE
```

```{r}
#| echo = FALSE
#| eval = TRUE
```

Code Chunks — Options — Defaults

Options have default values

• e.g., for echo, the default is TRUE
  • echo: should the source code printed in the output?
  • TRUE: yes it should
    
    
• therefore the following two chunks have the same function

```{r}
```

```{r, echo=TRUE}
```

Code Chunks — Options — Defaults

This chunk prints two things in the output document — (a) the code and (b) the head of the data frame

```{r}
head(df)
```

##                name   origin   branch h5_index h5_median english subfield
## 1  Journal of Bears Americas Physical       73        97       1        1
## 2   Journal of Moon     Asia   Social       72       106       1        0
## 3 Journal of Lumber Americas Physical       72       100       1        1
## 4 Journal of Houses   Europe   Social       72       102       1        0
## 5  Journal of Water   Europe   Social       70       100       1        0
## 6  Journal of Jeans Americas Physical       69       101       1        1
##   issues age
## 1      7  61
## 2      6  64
## 3      8  30
## 4      8  38
## 5      5  33
## 6      5  64

Code Chunks — Options — Examples

Setting echo=FALSE prevents the code from being displayed in the output document

```{r ... echo=FALSE}
head(df)
```

This chunk therefore prints one thing in the output document — the head of the data frame

##                name   origin   branch h5_index h5_median english subfield
## 1  Journal of Bears Americas Physical       73        97       1        1
## 2   Journal of Moon     Asia   Social       72       106       1        0
## 3 Journal of Lumber Americas Physical       72       100       1        1
## 4 Journal of Houses   Europe   Social       72       102       1        0
## 5  Journal of Water   Europe   Social       70       100       1        0
## 6  Journal of Jeans Americas Physical       69       101       1        1
##   issues age
## 1      7  61
## 2      6  64
## 3      8  30
## 4      8  38
## 5      5  33
## 6      5  64

Code Chunks — Options — Examples

Prevent the result(s) of the source code from being displayed in the output document

```{r ... results="hide"}
head(df)
```

This chunk therefore prints one thing in the output document — the source code

Setting results="asis" passes the results as they are produced by the code — pandoc does not transform these. In creating tables for PDF output with the stargazer package, this option is a must.

Code Chunks — Options — Examples

Cache results for future compilations

```{r ... cache=TRUE}
```

Note that caching

• is useful especially for chunks that take a long time to execute

  • it can speed up the compilation process

• avoids executing the chunks at every compilation

  • unless the chunk is newly created or edited since the last cached compilation

• creates a new folder in your working directory

  • an alternative location can be specified with the cache.path option

Code Chunks — Options — Examples

Prevent R from running the code in the chunk altogether

```{r ... eval=FALSE}
```

Prevent messages and/or warnings from being displayed in the output

```{r ... error=FALSE, message=FALSE, warning=FALSE}
```

Code Chunks — Options — Examples

Define the actual dimensions of figures, in inches

```{r ... fig.height=6, fig.width=9}
```

Define the size of figures as they appear in the output document, with out.width and/or out.height

```{r ... out.width="50%"}
```

Define the alignment of figures — left, right, or center

```{r ... fig.align="center"}
```

Code Chunks — Options — Examples

Define captions for figures

```{r ... fig.caption="A Scatter Plot"}
```

Set the resolution for figures

```{r ... dpi=300}
```

Set extra options, such as angle, that output format would accept for figures

```{r ... out.extra="angle=45"}
```

Code Chunks — The Setup Chunk

It is recommended to use the first code chunk for general setup, where you can

• define your own defaults for chunk options, with knitr::opts_chunk$set()
  • avoids repeating chunk options
    
    
• load the necessary packages
  
  
• import raw data

```{r, setup, include=FALSE}
# chunk option defaults
knitr::opts_chunk$set(echo=FALSE, message=FALSE)
# packages
library(dplyr)
library(ggplot2)
library(stargazer)
# data
df_raw <- read.csv("journals.csv")
```

Code Chunks — The Data Chunk

I recommend using the second chunk for the main operations^* on raw data

• e.g., for data cleaning and other transformations
• some minor transformations could be left to lower chunks
  • e.g., capitalizing variable names for figures

```{r, data, ...}
df <- df_raw %>%
      mutate(subfield = as.factor(subfield), 
             english = as.factor(english),
             age = 2020 - since) %>%
      select(-since)
```

Inline Code — Overview

Code can also be incorporated in text, with the `r ` syntax

• unlike chunks, these do not take options
  
  
• the output document will display the result of the code
  • in the exact place of the source code
    
    
• the result of the code will have the same formatting with the text

Inline Code — Examples

If we multiply _pi_ by 5, we get `r pi * 5`.

If we multiply pi by 5, we get 15.7079633.

The average H5 Index for the journals in the dataset is `r mean(df$h5_index)`, which would 
round to `r round(mean(df$h5_index), digits = 1)`.

The average H5 Index for the journals in the dataset is 26.3611366, which would round to 26.4.

__Only `r nrow(subset(df, english == 0))` journals__ in the dataset are published in a language
other than English.

Only 113 journals in the dataset are published in a language other than English.

Figures — Images — Markdown Syntax

The syntax  embeds images, and/or figures produced elsewhere,^* into .Rmd documents

• similar to the link syntax, only this time it is preceded by an exclamation mark !
• goes outside code chunks, on a new line
• simple, but not very customisable

Figures — Images — Markdown Syntax

![A screenshot of the Google Scholar homepage](../image/google_scholar.png)

Figures — Images — Markdown Syntax

Figures are numbered automatically

![A screenshot of the Google Scholar homepage](../image/google_scholar.png)

Figures — Images — Markdown Syntax

The syntax can accept width or height attributes as follows

![A screenshot of the Google Scholar homepage](../image/google_scholar.png){ width=40% }

Figures — Images — knitr

The knitr package offers a capable alternative with the include_graphics() function

• this goes inside code chunks

  • use the function with the double-colon operator ::
    • e.g., knitr::include_graphics("figure.extension")
      
      

• this is more customisable, through the use of code chunks

  • size is defined with the out.width or out.hight options
    • rather than fig.height and/or fig.width

Figures — Images — knitr

The knitr package offers a capable alternative with the include_graphics() function

```{r, screenshot, echo=FALSE, fig.cap="A screenshot of the Google Scholar homepage."}
knitr::include_graphics("../image/google_scholar.png")
```

Figures — Images — knitr

Size is defined with the chunk options out.width or out.hight

```{r ... out.width="40%"}
knitr::include_graphics("../image/google_scholar.png")
```

Figures — Images — knitr

Most other chunk options are common with figures plotted within R Markdown, such as fig.align

```{r ... fig.align="center"}
knitr::include_graphics("../image/google_scholar.png")
```

Figures — ggplot2 — Overview

• A powerful package for visualising data

• Used widely, not only by academics, but also by large corporations such as the New York Times

• A huge amount is written on this package. See, for example,

  • the package documentation
  • this book by its creator Hadley Wickham
  • this reference page
  • this webinar by one of its authors, Thomas Lin Pedersen
  • these extensions, maintained by the ggplot2 community

• Among its alternatives are the base and plotly packages

Figures — ggplot2 — Basics

1) The ggplot function and the data argument

• specify a data frame in the main ggplot function

ggplot(data = df)

2) The mapping aesthetics, or aes; most importantly, the variable(s) that we want to plot

• specify as an additional argument in the same ggplot function

ggplot(data = df, mapping = aes(x = h5_median, y = h5_index, color = subfield))

3) The geometric objects, or geom; the visual representations

• specify, after a plus sign +, as an additional function

ggplot(data = df, mapping = aes(x = h5_median, y = h5_index, color = subfield)) +
       geom_point()

Figures — ggplot2

Put the code in a chunk, and give it a caption

```{r, scatterplot, fig.cap = "A scatterplot of journal metrics."}
ggplot(data = df, mapping = aes(x = h5_median, y = h5_index, color = subfield)) +
       geom_point()
```

Figures — ggplot2

Add facets for subgroups, e.g., branch

```{r, scatterplot, fig.cap = "A scatterplot of journal metrics."}
ggplot(data = df, mapping = aes(x = h5_median, y = h5_index, color = subfield)) +
       geom_point() +
       facet_wrap(. ~ branch)
```

Figures — ggplot2

Scale the colour to improve the legend

```{r, scatterplot, fig.cap = "A scatterplot of journal metrics."}
ggplot(data = df, mapping = aes(x = h5_median, y = h5_index, color = subfield)) +
       geom_point() +
       facet_wrap(. ~ branch) +
       scale_colour_discrete(name = "Journal Type", breaks = c(0, 1), labels = c("Generalist", "Subfield"))    
```

Figures — ggplot2

Change the theme

```{r, scatterplot, fig.cap = "A scatterplot of journal metrics."}
ggplot(data = df, mapping = aes(x = h5_median, y = h5_index, color = subfield)) +
       geom_point() +
       facet_wrap(. ~ branch) +
       scale_colour_discrete(name = "Journal Type", breaks = c(0, 1), labels = c("Generalist", "Subfield")) +
       theme_bw()
```

Figures — ggplot2

Improve the axis labels, e.g., with capital first letters

```{r, scatterplot, fig.cap = "A scatterplot of journal metrics."}
ggplot(data = df, mapping = aes(x = h5_median, y = h5_index, color = subfield)) +
       geom_point() +
       facet_wrap(. ~ branch) +
       scale_colour_discrete(name = "Journal Type", breaks = c(0, 1), labels = c("Generalist", "Subfield")) +
       theme_bw() +
       labs(x = "H5 Median", y = "H5 Index")
```

Figures — ggplot2 — Notes

geom_point is one of many geoms avilable

• see this https://ggplot2.tidyverse.org/reference for other options, including
  • geom_bar for bar charts
  • geom_boxplot for box and whiskers plots

Tables — Markdown Syntax

The following syntax, outside code chunks, introduces tables that pandoc can recognise

First Column  Second Column 
------------  ------------- 
First cell    First cell      
Second cell   Second cell   
Third cell    Third cell

Tables — Markdown Syntax

The position of headers, relative to their line underneath, defines column alignments

Left-Aligned          Centered   
----------------  ----------------
First cell        First cell      
Second cell       Second cell   
Third cell        Third cell

Tables — Markdown Syntax

A line starting with a colon, placed before or after tables, introduces captions

    Centered         Right-Aligned 
----------------  ----------------
First cell        First cell      
Second cell       Second cell   
Third cell        Third cell  
: A hand-made table with R Markdown

Tables — Markdown Syntax

The caption line itself needs to be surrounded by empty lines

    Centered         Right-Aligned 
----------------  ----------------
First cell        First cell      
Second cell       Second cell   
Third cell        Third cell  
   
: A hand-made table with R Markdown                                      

Tables — Markdown Syntax

Tables are numbered automatically

: A hand-made table with R Markdown 
    Centered         Right-Aligned 
----------------  ----------------
First cell        First cell      
Second cell       Second cell   
Third cell        Third cell

Tables — Markdown Syntax

Grid tables, with the following syntax, can handle complex cells with multiple lines and/or lists

+--------------------+--------------------+
| First Column       | Second Column      | 
+====================+====================+
| - First item       | First cell         | 
| - Second item      |                    | 
| - Third item       |                    |
+--------------------+--------------------+
|Second cell         | Second cell with a | 
|                    | long text          | 
+--------------------+--------------------+
| Third cell         | Third cell         | 
|                    |                    | 
+--------------------+--------------------+
: A grid table with multi-line cells

Tables — Markdown Syntax

Grid tables can be aligned as well, with colons at the boundaries of the header separator^*

+--------------------+--------------------+
| Left-Aligned       | Centered           | 
+:===================+:==================:+
| - First item       | First cell         | 
| - Second item      |                    | 
| - Third item       |                    |
+--------------------+--------------------+
|Second cell         | Second cell with a | 
|                    | long text          | 
+--------------------+--------------------+
| Third cell         | Third cell         | 
|                    |                    | 
+--------------------+--------------------+
: A grid table with multi-line cells

Tables — stargazer — Overview

• A capable package for creating at least three kinds of tables

  • raw data, in columns and rows
  • descriptive/summary statistics
  • regression models

• Used widely by academics, even tough it has not been updated since 2018

• Creates LaTeX code, HTML/CSS code, and ASCII text to be knitted

• A lot is written on this package. See, for example,

  • the package documentation
  • this vignette by its author Marek Hlavac
  • this tutorial by Jake Russ

• Among its alternatives are the knitr, kableExtra, and huxtable packages

Tables — stargazer — Notes

• The stargazer package requires specific settings

  • in the chunk options
  • and, in the type argument of the stargazer() function

• These settings depend on the desired output format,^* as shown below

Tables — stargazer — Notes

• stargazer tables look slightly different in different output formats

  • on the following slides, they will have the HTML look
  • even if the slides display the setting for LaTex and PDF outputs

• In fact, it is currently not quite possible to knit stargazer code into tables in Word documents

  • though it can knit ASCII text, looking like a table
  • some popular workarounds:
    • knit to HTML as well as Word, copy the tables from HTML to Word
    • knit to PDF, open the PDF in Word
    • use a different package to create tables, such as huxtable

Tables — stargazer — Basics

• The stargazer() function

  • this is probably the only fuction you will ever use from this package
    • but it accepts many, many arguments to customise tables

• The data argument of that function, with two main options

  1. a data frame for data or summary statistics tables
     • e.g., df, here coming from df <- read_csv(journals.csv)
       
       
  2. one or more regression models for regression tables
     • e.g., lm1, here coming from lm1 <- lm(h5_index ~ issues, data = df)

Tables — stargazer — Data Tables

Table the first four rows of the dataset

```{r, data_table, echo=FALSE, results="asis"}
stargazer(data = head(df, n = 4), type = "latex", summary = FALSE)
```

Notice the options of the chunk and the arguments of the function

• with echo=FALSE, the code will not be displayed in the output document

• with results="asis", knitr will pass through results without reformatting them

  • these results are produced in LaTeX, due to type = "latex"
  • they should remain LaTeX because our outcome document is PDF, converted from LaTeX

• with summary = FALSE, the table will present the data, not its descriptive statistics

Tables — stargazer — Data Tables

Table the first four rows of the dataset

```{r, data_table, echo=FALSE, results="asis"}
stargazer(data = head(df, n = 4), type = "latex", summary = FALSE)
```

Tables — stargazer — Data Tables

Set header = FALSE to remove the note preceding tables

```{r, data_table, echo=FALSE, results="asis"}
stargazer(data = head(df, n = 4), type = "latex", summary = FALSE, header = FALSE)
```

Tables — stargazer — Data Tables

Define a caption with the title argument

```{r, data_table, echo=FALSE, results="asis"}
stargazer(data = head(df, n = 4), type = "latex", summary = FALSE, header = FALSE,
          title = "First four rows of the dataset")
```

Tables — stargazer — Summary Statistics Tables

Create a table of summary statistics instead, for the complete dataset

```{r, summary_table, echo=FALSE, results="asis"}
stargazer(data = df, type = "latex", summary = TRUE, header = FALSE,
          title = "Descriptive statistics")
```

Tables — stargazer — Summary Statistics Tables

Keep only a selection of statistics

```{r, summary_table, echo=FALSE, results="asis"}
stargazer(data = df, type = "latex", summary = TRUE, header = FALSE,
          title = "Descriptive statistics", summary.stat = c("n", "mean", "sd", "min", "max"))
```

Tables — stargazer — Summary Statistics Tables

Omit a selection of statistics for the same effect

```{r, summary_table, echo=FALSE, results="asis"}
stargazer(data = df, type = "latex", summary = TRUE, header = FALSE,
          title = "Descriptive statistics", omit.summary.stat = c("p25", "p75"))
```

Tables — stargazer — Summary Statistics Tables

Flip the table

```{r, summary_table, echo=FALSE, results="asis"}
stargazer(data = df, type = "latex", summary = TRUE, header = FALSE, flip = TRUE,
          title = "Descriptive statistics", omit.summary.stat = c("p25", "p75"))
```

Tables — stargazer — Regression Tables

```{r, regression_table, echo=FALSE, results="asis"}
stargazer(data = lm(h5_index ~ issues, data = df), 
          type = "latex", header = FALSE,
          title = "Regression Results")
```

Tables — stargazer — Regression Tables

```{r, regression_table, echo=FALSE, results="asis"}
 lm1 <- lm(h5_index ~ issues, data = df)
 stargazer(data = lm1, type = "latex", header = FALSE,
           title = "Regression Results")
```

Tables — stargazer — Regression Tables

```{r, regression_table, echo=FALSE, results="asis"}
stargazer(data = lm1, type = "latex", header = FALSE,
          title = "Regression Results", 
          keep.stat = c("n", "rsq"))
```

Tables — stargazer — Regression Tables

```{r, regression_table, echo=FALSE, results="asis"}
stargazer(data = list(lm1, lm2), type = "latex", 
          header = FALSE, title = "Regression Results", 
          keep.stat = c("n", "rsq"))
```

Tables — stargazer — Regression Tables

```{r, regression_table, echo=FALSE, results="asis"}
stargazer(data = list(lm1, lm2), type = "latex", 
          header = FALSE, title = "Regression Results", 
          keep.stat = c("n", "rsq"),
          dep.var.labels = "H5 Index",
          covariate.labels = c("Issues", "English"))
```

Tables — stargazer — Regression Tables

```{r, regression_table, echo=FALSE, results="asis"}
stargazer(data = list(lm1, lm2), type = "latex", 
          header = FALSE, title = "Regression Results", 
          keep.stat = c("n", "rsq"),
          dep.var.labels = "H5 Index",
          covariate.labels = c("Issues", "English"),
          star.cutoffs = c(0.05, 0.01, 0.001))
```

Functionality Gaps

• Not everything is possible to achieve with R Markdown syntax, code chunks, and/or code

  • e.g., centering text, increasing the space between the lines of text

• Workarounds available through inclusion of other languages and/or syntaxes in .Rmd documents

  • e.g., incorporating HTML or LaTeX code into R Markdown
  • workarounds might be output specific
    • e.g., LaTeX-based workarounds may work only for LaTeX and PDF outputs

• There are no exclusive list of gaps or workarounds

  • these are specific to the output you want to achieve, problems you encounter
  • after writing a few manuscripts with R Markdown, you will have addressed most typical gaps in your workflow

Functionality Gaps — Examples

Problem:

How can we cross-reference figures, tables, and equations in R Markdown?

Solution:

Insert a LaTeX label into the targets (figures, tables, and equations), and then use the \autoref{figure_caption} syntax in text

Functionality Gaps — Examples — Cross-references

For figures, insert a LaTeX label into the fig.caption option, and use the \autoref{latex_label} syntax in text

\autoref{scatter_plot} visualises the relationship between the two journal metrics.
```{r ... fig.caption = "A Scatter Plot \\label{scatter_plot}"}
ggplot(data = df) + 
       geom_point(...
```

Figure 1 visualises the relationship between the two journal metrics.

Functionality Gaps — Examples — Cross-references

For Markdown tables, insert a LaTeX label after the table caption, and use the \autoref{latex_label} syntax in text

See \autoref{handmade_table} for further details.
: A hand-made table with R Markdown \label{handmade_table}
+--------------------+--------------------+
| Left-Aligned       | Centered           | 
...

See Table 1 for further details.

Functionality Gaps — Examples — Cross-references — Note

Note that there is a difference in the label syntax for figures and R Markdown tables

• we use a double backslash \ \ to label figures

  • e.i., \\label{scatter_plot} because the label goes into a string

  • the first is an escape operator for the second, LaTeX backslash

• we use single backslash \ to label R Markdown tables

  • e.i., \label{handmade_table} because the label is not in any string

  • there is no need for the escape operator

Functionality Gaps — Examples — Cross-references

For stargazer tables, define a label with the label argument, and use the \autoref{latex_label} syntax in text

```{r, regression_table, echo=FALSE, results="asis"}
stargazer(data = list(lm1, lm2), type = "latex", 
          ...
          label = "regression_results")
```
\autoref{regression_results} provides results from two OLS models.

Functionality Gaps — Examples — Cross-references — Note

Note that we can cross-reference specific results in tables as well

• there is no gap here — this possible with inline code

In Model 1, the coefficient for _Issues_ is 
`r round(coef(summary(lm1))["issues", "Estimate"], digits = 2)`.

In Model 1, the coefficient for Issues is 1.91.

Functionality Gaps — Examples — Cross-references

For equations, insert a LaTeX label in an equation environment, and use the \autoref{latex_label} syntax in text

\begin{equation}
\label{special_relativity}
E = mc_{2}
\end{equation}
According to \autoref{special_relativity}, space and time are linked.

According to Equation 1, space and time are linked.

Functionality Gaps — Examples

Problem:

R Markdown adds the list of references to the end of documents. This might be undesirable for some manuscripts, for example those with an appendix. Similarly, some journals require tables and figures to be added after references.

Solution:

Define where exactly the list of references should appear with the HMTL code <div id="refs">

# References
<div id = "refs"></div>
# Appendix

Functionality Gaps — Examples

Problem:

R Markdown produces outputs with single-line-spaced text while we might prefer or be required (e.g., by journal submission rules) to double-space our manuscripts.

Solution:

Use the doublespacing command from the LaTeX package setspace (Carlisle, Fairbairns, Harris, and Tobin, 2011)

• because the command comes from a package, we need to add it to YAML with header-includes
• including commands in YAML ensures they are applied through the output^*

---
...
header-includes:
    - \usepackage{setspace}\doublespacing
---

Functionality Gaps — Examples

Problem:

Pages, tables, figures etc. are numbered continuously across an output. We might prefer or be required (e.g., by journal submission rules) to change this behaviour, for example for appendices.

Solution:

Use the setcounter in combination with the renewcommand command, outside code chunks

\setcounter{page}{1}
\renewcommand*{\thepage}{A\arabic{page}}
\setcounter{table}{0}
\renewcommand*{\thetable}{A\arabic{table}}
\setcounter{figure}{0}
\renewcommand*{\thefigure}{A\arabic{figure}}

Version Control

• Research papers have many versions before publication

  • typically written over a long period of time, in numerous sittings
  • at the end of every sitting, essentially a different version of the same manuscript is created^*

Version Control

• Research papers have many versions before publication

  • typically written over a long period of time, in numerous sittings
  • at the end of every sitting, essentially a different version of the same manuscript is created

• With many versions created over time, there emerge at least two challenges

  • keeping track of changes and versions
  • reverting to a previous version when necessary

• We all version control, in different ways, such as

  • edit, rename, and save the files
  • use applications or websites such as Dropbox, Google Docs, Overleaf
  • use distributed version control systems such as Git and GitHub

Version Control — Manual Attempts

Typically, hand-made attemps to version control lead to cluttered folders

manuscript
   |
   |- journals_FINAL_19May.Rmd
   |- journals_FINAL.Rmd
   |- journals_26APRIL_newliterature.Rmd
   ...
   |- journals.Rproj
   |- references.bib  
   |- apa_7th.csl

Version Control — Git and GitHub — Definitions

• Git
  • a software that keeps track of versions of a set of files
  • it is local to you; the records are kept on your computer

• GitHub
  • a hosting service, or a website, that can keep the records
  • it is remote to you, like the Dropbox website
  • but unlike Dropbox, GitHub is specifically structured to keep records with Git

• Repository, or repo
  • a set of files whose records are kept together, by Git and/or on GitHub
  • it is like a folder, which can keep files and other folders containing files

Version Control — Git and GitHub — Definitions

• To commit
  • to take a snapshot of, or to version, a repository
  • it is like saving a new version of all files and sub-folders in your project folder with a new name
  • it is local, the records are kept on your computer unless you push

• To push
  • to move a copy of the records from Git to GitHub, from your computer to online server
  • it is like uploading (the new versions of) your files and sub-folders to a website
  • it also involves merging, if this not the first push

Version Control — Git and GitHub

Version control with Git and GitHub requires

1. initial setup, done once^*

   • unless for a new computer or, if ever, a new GitHub account
   • a bit technical, but worth the hassle

2. project setup, repeated for every RStudio project

   • shorter, less complicated

Version Control — Git and Github — .gitignore

• .gitignore specifies which file(s) and/or folder(s) should be excluded from version control

  • a set of project-specific files are ignored by default
    • see your .gitignore file

• .gitignore lists one item per line

  • each line has a pattern, which determines whether one or more files or folders are to be ignored

• See the documentation at https://git-scm.com/docs/gitignore

  • for pattern formats and further details

Version Control — Git and Github — .gitignore

There are good reasons to ignore some others, including files

• that contain information that we do not want others to see
  • e.g., personal API keys
    
    
• that we do not have the right to share with others
  • e.g., secondary data with user agreements otherwise
    
    
• that we (re-)create automatically as outputs
  • e.g., journals.pdf, as opposed to journals.Rmd

Version Control — Git and Github — .gitignore

.Rproj.user
.Rhistory
.RData
.Ruserdata

Version Control — Git and Github — .gitignore

.Rproj.user
.Rhistory
.RData
.Ruserdata
/manuscript/

Version Control — Git and Github — .gitignore

.Rproj.user
.Rhistory
.RData
.Ruserdata
/manuscript/
/manuscript/journals.pdf

Version Control — Git and Github — .gitignore

.Rproj.user
.Rhistory
.RData
.Ruserdata
/manuscript/
/manuscript/journals.pdf
journals.pdf

Version Control — Git and Github — .gitignore

.Rproj.user
.Rhistory
.RData
.Ruserdata
/manuscript/
/manuscript/journals.pdf
journals.pdf               
*.pdf

Version Control — Git and Github — .gitignore — Notes

• There are many other pattern formats

  • see the documentation at https://git-scm.com/docs/gitignore

• Starting to ignore a file or folder that is already being tracked requires clearing the cache

  • after changing and saving .gitignore, enter the following line in the Terminal
  • with your speficic /path/to/file

git rm --cached /path/to/file

• The following command clears all cache

  • might be useful after changes to .gitignore that involves several files or folders
  • but should be used with care, on an otherwise up-to-date repository

git rm -r --cached .

Collaboration

• Many research papers are written by multiple authors and/or on multiple computers

  • yourself on a different computer (e.g., laptop at home, desktop at office), poses similar challenges as collaboration

• With multiple authors and/or computers, there emerges at least two additional challenges beyond version control

  • communicating the versions to other authors and/or computers
  • working on the same project with co-authors at the same time

• We all manage collaboration, in different ways, such as

  • edit, rename, save, e-mail
  • use applications or websites such as Dropbox, Google Docs, Overleaf
  • use distributed version control systems such as Git and GitHub

Collaboration — Git and GitHub — Definitions

• To pull

  • to move the (presumably) up-to-date records from GitHub to your computer
  • it is like downloading a zipped folder of files

• To merge

  • to integrate different versions into a single version
    • e.g., the old version on your laptop, with (the changes in) the new version from GitHub
  • except the first push or pull, pushing and pulling necessiate merging

• Merge conflict

  • emerges when versions to be merged include edits on the same line of the same file
    • edits on different lines are not a problem as changes are tracked line by line
      
      
  • less likely to occur in one-author-multiple-computer setting
    • more likely while collaborating with others
      
      
  • requires human intervention, to decide which edit to keep and which one to discharge

Collaboration — Git and GitHub — Definitions

• Branch

  • a line of development in a repository; a copy of the repository, with all its versions, at a given time
  • by default, repositories have one branch, called master

• Pull request

  • a proposal to pull and merge
    • e.g., a proposal from one co-author to another, -e.g., tp merge a branch into master
  • it allows a review of changes on GitHub before merge, to deal with potential merge conflicts

Collaboration — Git and GitHub — Project Setup

• The setup depends on the users' role, on whether they are
  • the owner who creates the GitHub repository, or
  • the collaborator who is then added to that repository