The Intersection Between Data Sharing and Code: Version Control Best Practices With GitHub

class: center, middle, inverse, title-slide

.title[
# The Intersection Between Data Sharing and Code: Version Control Best Practices With GitHub
]
.subtitle[
## Fall RT2 - Online
]
.author[
### Fernando Hoces de la Guardia, BITSS
]
.date[
### 29 November 2023, <a href="https://bitss.github.io/gh_rt2_2023/">slides</a>
]

---

count:true
# Before We Begin

.font150[

- [GitHub desktop app](https://desktop.github.com/) installed?

- Create an account at [GitHub.com](http://www.github.com/)?

- If no to any, please do it now

- Structure of the presentation: 
  - Brief overview data sharing. 
  - Hands-on tutorial on Git/GitHub for non-programmers.

]

---
background-image: url("Images/iceberg.jpg")
background-size: 50%
background-position: 100% 50%
# Motivation: Share The Entire Scholarly Output

.pull-left[
.font120[
 Clarebout Principle:
 
 “An article about computational science in a scientific publication is not the scholarship itself, it’s merely scholarship advertisement. The actual scholarship is the complete software development environment and the complete set of instructions which generated the figures.”
.right[ <cite> Buckheit and D.L. Donoho (1995, [2009](https://academiccommons.columbia.edu/doi/10.7916/D8QZ2MDS/download))</cite>]

Relates to *Communality*, and *Organized Skepticism*, as discussed in [Ted Miguel's presentation](https://youtu.be/v6-RRirNPFQ?si=58mI1TjV1Iuvn2gU)

]
]

---
background-image: url("Images/3s.png")
background-size: 70%
background-position: 50% 85%
# Data Sharing: Past

.font120[
- Distant past: In economics data was rarely available until the early 2000's (Dewalt et. al. 1986, McCullough et al. 2006, [Vilhuber 2020](https://hdsr.mitpress.mit.edu/pub/fgpmpj1l/release/5#vlxgrqs1os))

- Not so distant past: But even after the first policies were put in place most data sets where incomplete (Gertler et. al. 2018)

- However a clear change in norms has taken place over the last decade (Ferguson et. al. 2023):

]

---
# Data Sharing: Present 
 
.font140[

- Founders are playing a key role by requiring data availability 
  - Latest milestone: [Nelson Memo](https://www.whitehouse.gov/wp-content/uploads/2022/08/08-2022-OSTP-Public-access-Memo.pdf)

- Ever-growing infrastructure with solutions. For example: 
  - [Dataverse](https://dataverse.org/)
  - [Zenodo](https://zenodo.org/)
  - [Dryad (larger datasets)](https://datadryad.org/stash)
  - [OSF](https://osf.io/)
  - [ICPSR](https://www.icpsr.umich.edu/icpsrweb/)
  - See [here](https://www.agu.org/-/media/files/publications/generalist-data-repository-grid.pdf) for a comparison and more alternatives of trusted data repositories

]
---
# Data Sharing: Future

.font120[
- Rise of administrative data sets in economics
  - Recent revelations of high profile fraud (Harvard, Duke) where only possible because the data was available. 
  - For a large fraction of research in economics, we have no way of detecting such irregularities.

- Data citations
 - Increasing the practice of citing data sets in addition to the paper could help align incentives even more. 
 
- Data provenance 
 - Tracing and documenting the origin of different data sets can serve two purposes: (i) share more effectively the knowledge of what it takes to build a given data sets, and (ii) give credit to the proper sources in the process of doing this. 
]
---
# Code Sharing: Git/Github for Non-Programmers 
.font150[
 
- Version Control Software (VCS) is an increasingly popular tool for computational reproducibility

- Git is a type of VCS and Github company that build on top of.

- They are very popular among programmers, but not so much among non-programmers.

- Why? I believe it has to do with GUIs.

]
---

# What is a GUI and why the bad reputation

.font150[
 
**G**raphical **U**ser **I**nterface

- For most of us (non-programmers): *GUI = Software*.

- GUIs are behind the popularization of personal computers.

- Unfortunately GUIs are pretty bad at keeping a record of actions taken (bad for reproducibility).
]

---

# What is not a GUI?

.font140[

- Any software that is run in the command line (aka terminal, shell, bash, etc).

]

![](Images/command_line.png)

.font140[

- Git was designed to run in the command line.

- Today we will learn Git **without** the command line.
]

---

# What is Git 1/2
.font150[
 
- Git is a software designed to track the **entire** history of the code of a project.

- Designed originally for software development, it has gained important traction in the research community.

- Main appeal: facilitates full reproducibility and collaboration.

- Git is mainly meant to work as a non-GUI (in the command line) software.   
**However:** most of the key features can be used through a GUI. 
]
---

# What is Git 2/2

.font150[ 
 
- By code Git understands any type of plain text file (`myfile.R`, `myfile.do`, `.tex/.md/.txt/.csv/.etc`).

- This type of file can be understood as "human readable" as machine and human see the same fie.

- Files that are "non-human readable" are called binary files (`myfile.docx`, `myfile.xlxs`, `.pdf/.exe/.dta/.etc`).

- Git can also detect changes in binary files, but it cannot show those changes.
]

---

# What is Github
.font150[
 
- Github is a company that provides two services (that we care of): 
 - A web hosting service for all our files track with Git (public free/private $ or free if academic). 
 - A GUI software (Desktop App) that provides user friendly access to Git.

- Others hosting ss include: Bitbucket, GitLab, Gitkraken, etc.

- Other GUIs include: SourceTree, Gitkraken, VS Code, RStudio.

]

---

# The Primary Goal of Version Control (for us)

.font150[
 
**The Goal:** keep track of any *potentially meaningful* modification to your code. 
]
--
.font150[
**Secondary Goal:** learn how to collaborate with others using Github. 
]

---
# Strategy 1:

.font150[
 
1. Agree on a naming convention with your co-authors (eg: YYYYMMDDfilename_INITALS).

2. Begin working from the last saved version (eg: `20180325demo_FH.do`).  
3. At the end of the day, save on a new version (eg: `20180327demo_FH.do`).

**Pros:** Easy adoption.

**Cons:** Error prone, hard to document, lots of files for each document.     
]
---

# Strategy 2:

.font150[

1. Name your file `filename` (ideally `01_filename`)  
2. Take a snapshot of your work every time you complete relevant change (day, hour or minutes).  
3. Update your entire working folder to the cloud.

**Pros:** Error proof, seamless documentation, one file per document, track differences across all versions, meant to work with the cloud.

**Cons:** Harder adoption.   
]
---
background-image: url("Images/phdcomics.png")
background-size: contain

# We want to avoid this situation:

---
background-image: url("Images/version_control_diagram.svg")
background-size: contain

# Comparison of Workflows

---

# Other reasons to use Git

.font150[
 
- To access a whole new world of knowledge!

- Great tool for collaboration.

- Easier to test all sorts of ideas/models. 
]
---
# Demos

## Three Demos: 
 
.font140[

1 - **Simple but instructive.**

2 - Repeat with collaboration: shared ownership.

3 - Repeat with branches.

]
---

# Demo #1: We Start in the Cloud 
 
.font130[

1 -  Create [github.com](github.com) account and sign in.

2 -  Let's look at some **repos:**  
  - Papers: [Labor](https://github.com/tyleransom/AES-Roy-Majors), [Health](https://github.com/mkiang/opioid_treatment_distance), [Public Finance](https://github.com/OpportunityInsights/welfare_analysis)    
  - Courses: [So](https://github.com/edrubin/EC607S21), [many](https://github.com/floswald/ScPo-Labor/), [methods](https://github.com/woerman/ResEcon703), [courses](https://github.com/paulgp/applied-methods-phd) 
  - Covid: [JHU](https://github.com/CSSEGISandData/COVID-19), [Imperial](https://github.com/ImperialCollegeLondon/covid19model), [NYT](https://github.com/nytimes/covid-19-data), [The Economist](https://github.com/TheEconomist/covid-19-excess-deaths-tracker), [EconTracker](https://github.com/OpportunityInsights/EconomicTracker)
  - and more: [nice diagrams](https://github.com/grantmcdermott/tikzexamples), [meta-guides](https://github.com/Alalalalaki/Guide2EconRA), [books](https://github.com/BITSS/ACRE), [guaguas!](https://github.com/rivaquiroga/guaguas)

3 -  First way to access content: download.

4 -  What if you want to have your own copy of the repo? **Fork** it!

]
---
# Demo #1: We move to our local computer 
 
.font130[
5 - Now create your own repo. Initiate readme and make some edits.

6 - **Clone** the repo. Explore the files and location.

7 - Create new files, edit. And **commit**. Edit again, and commit again.

8 - **Push.** Edit on github.com, and **pull.**

9 - For this tutorial, best way to access previous version: explore in github.com and download.

]

.right[
[here is some help with the lingo](handout.pdf)
]

---
# Three Demos 2/3: 
 
.font140[

1 - Simple but instructive.   
    *Review: def repo, github.com, download, clone, destination folder, fork, create repo, commit, push, pull, delete, search repo, download old version.*

2 - **Repeat with collaboration: shared ownership.**

3 - Repeat with branches.  
  ]

---
# Two formats of collaboration 
 
.font140[

- Many owners, all can push.   
    - **Very** important to pull at the beginning and at before each push. 
    
- One owner, many pull requests (not covered here).  
    - Easier to control, requires constant updating of forks.

]
  
---
# Demo #2: Many owners

.font140[

1 - Let's pretend that each of you represents two individuals: one working on your computer ("You-you"), and an alter-ego working on a different computer ("Alter-you").

2 - Only for the purpose of this tutorial, we will edit the content of a repo on GitHub.com, as-if it was done by your alter-ego in a different computer.

]
--
.font140[
3 - You-you: edits, commits and **does not push.**  
]
--
.font140[
4 - Alter-You commits and pushes in **different lines** (in GitHub.com).     
]
--
.font140[
5 - Now you-you (the one on your local machine) pushes.
]
--
.font140[
6 - Repeat 3 - 5 but now both of you in the same lines.    
]

---
# Fatal Error!
 
<img src="Images/error_image.png" width="50%" style="display: block; margin: auto;" />

---
background-image: url("Images/calm_burn.jpg")
background-size: contain

# Burn it and start with a fresh copy!

.right[
  [Jenny Bryan's Advice](https://speakerdeck.com/jennybc/happy-git-and-github-for-the-user)
]
---
# Three Demos: 2/3

.font140[

1 - Simple but instructive.   
    Review: def repo, github.com, download, clone, destination folder, fork, create repo, commit, push, pull, delete, search repo, download old version.

2 - Repeat with collaboration: shared ownership.     
    *Review: Simulate collaboration, resolve conflicts.*
    
3 - Repeat with branches.

]

---
# .font80[Demo #3: Branches and collaboration (we wil be here a while)]
 
.font140[

1 - Create a branch from previous repo.

2 - Add new content (do not replace), commit a few times, and go back and forth to the main branch.

3 - Go back to main branch (master), observe file, merge.

4 - Look at the history of the main branch.

5 - Push and inspect visual tool from GitHub

6 - Repeat 1-3 but now replace instead of adding content.    
 
]

---
# Three Demos: 3/3 
.font140[
1 - Simple but instructive.   
    Review: def repo, github.com, download, clone, destination folder, fork, create repo, commit, push, pull, delete, search repo, download old version.  
   
2 - Repeat with collaboration: shared ownership.     
    Review: Simulate collaboration, resolve conflicts.
    
3 - Repeat with branches.  
    *Review: All of the above, plus: branch, merge, resolve conflicts.*  
]

---
# Now go and explore!
 
.font140[

Some good habits: 
- Commit often (<1hr)

- Always pull before you start a new session of work. Also good to pull before pushing.

- Think of your remote as the most important set of files. Get used to deleting things in your local machine.    
]

---
# Want to Learn More: Version Control

## Tutorials

.font140[

- [Great 20 min intro to Git by Alice Bartlett](https://www.youtube.com/watch?v=eWxxfttcMts)  
- [Great 2hr tutorial to Github by Jenny Bryan (git ninja)](https://www.rstudio.com/resources/videos/happy-git-and-gihub-for-the-user-tutorial/)  
- Software Carpentry's [step-by-step tutorial (command line)](https://swcarpentry.github.io/git-novice/). 
]

## Documentation

.font140[

- Jenny Bryan's [Happy Git](http://happygitwithr.com/)
- [Documentation from Matthew Gentzkow and Jesse Shapiro](http://web.stanford.edu/~gentzkow/research/CodeAndData.pdf)
- Karthik Ram's paper on [Git for Research](https://scfbm.biomedcentral.com/articles/10.1186/1751-0473-8-7) 
]

---
# .font80[Economists Doing Highly Reproducible Work1]

.pull-left[

**People**
- [Nick Huntingon](https://github.com/NickCH-K) 
- [Shoshana Vasserman](https://github.com/shoshievass)  
- [Lars Vilhuber](https://github.com/larsvilhuber)
- [Grant McDermott](https://github.com/grantmcdermott)
- [Tyler Ransom](https://github.com/tyleransom)
- [Ed Rubin](https://github.com/edrubin)
- [Luiza Andrade](https://github.com/luizaandrade)
- [Max Kasy](https://github.com/maxkasy)
- [Matt Jensen](https://github.com/MattHJensen)
- [Jason DeBacker](https://github.com/jdebacker)
- [John Horton](https://github.com/johnjosephhorton)
- [Cora Kingdon](https://github.com/ckingdon95)
- [Chandler Lester](https://github.com/chandlerlester)

]
.pull-right[
- [Alvaro Carril](https://github.com/acarril)
- [Andrew Heiss](https://github.com/andrewheiss)
- [Lisa Rennels](https://github.com/lrennels)
- [Michael Stepner](https://github.com/michaelstepner)
- [Lachlan Deer](https://github.com/lachlandeer) 
- [Rebekah Din](https://github.com/rebekahanne)

**Organizations**
- [LOST](https://lost-stats.github.io/)
- [Opportunity Lab](https://github.com/Opportunitylab)
- [Congressional Budget Office](https://github.com/US-CBO)
- [Policy Simulation Library](https://github.com/PSLmodels)
- [Gentzkow & Shapiro Lab](https://github.com/gslab-econ)
- [Urban Institute](https://github.com/UrbanInstitute)
]

.footnote[
[1]: Non-exhaustive list of people and organizations doing amazing reproducible work on github (other than us!)
]