Oxford DSPI RG SPP, 08/02/2022

Overview

  1. Transparency and reproducibility
    1. Markdown for reproducibility
    2. Git for version control
  2. Outreach
    1. Markdown + Git for your academic website + CV
    2. Twitter for outreach

1. Why Markdown?

  • Who has used Markdown previously? What for?
  • Markdown, an easy way to:
  • take notes,
    • create content for a website (HTML),
    • produce printable documents (PDFs).
  • → All in one language.

1. Markdown (.md or .markdown) - a lightweight markup language

  • Pros
    • Easier than Word, Latex, HTML
    • Transferability of file formats
    • Integration with R via R Markdown (Rmd)

 

  • Cons (ostensible)
    • less formating options than Word, Latex, HTML
      → But Latex and HTML can be used within Markdown
    • Submission in Word or Latex required
      → Transfer file format with one click using Pandoc

1. Markdown - a lightweight markup language

1. Markdown: why should I create my slides in HTML?

1. Markdown - formatting

  • **Bold**: Bold
  • *Italic*: Italic
  • ~~Striketrough~~: Strikethrough
1. first point
2. second point
   - one sub-item
   - another sub-item
3. third point
  1. first point
  2. second point bold
    • one sub-item
    • another sub-item
  3. third point

1. Markdown - rendering

1. Markdown - YAML header

  • Sets global parameters of the document

1. Markdown Resources

  • Markdown Guide

  • Cheat Sheet

  • Templates for R Markdown by Steven Miller include:

    • Academic Manuscript
    • Slides
    • Syllabus
    • Memos
    • Academic CV
    • Non academic Resume

  • Use reproducR by Julia Schulte-Cloos to automatically anonymise your manuscript

1. Markdown - getting started

  • Choose a text editor; any will do. I use RStudio and VSC.

  • Start by taking your notes in Markdown instead of Word,
    f or instance in this research group.

1. Additions

  • RMarkdown: integrates R code into Markdown language.

  • Knitr: changes file formats from RMarkdown to Markdown.

  • Pandoc: converts between different markup languages (docx, HTML, LaTeX, and Markdown).

2. Git

  • Who has used Git previously? What for?
  • Who has used any kind of version control previously?

2. Why should I learn yet another tool?

2. Git as Version Control

  • “Save early, save often”.
  • Easiest version control: the back-button.
  • “Track-changes” in MS Word: rudimentary form of version control.

 

Git is sophisticated version control:

  • Single, updated version of each file.
  • Record of all previous versions.
  • Record of exact changes between the versions.
  • Collaborators can work simultaneously.
  • Documents who made changes, when and why.

2. Why should I learn yet another tool? Git as Version Control

  • Maintain an overview
  • Access previous versions

 

  • Strengthen Collaboration
  • Foster Transparency

 

  • Create an academic CV
  • Create an academic website
  • → Rmd allows you to use the same document for both

2. Git: Terminiology (1)

  • repository (repo)
  • commit
  • diff

 

  • branch
  • remote
  • local
  • commit message and tag
  • gist

2. Git: Terminiology (1)

  • repository (repo): directory of files
  • commit: snapshot of directory
  • diff: difference between two commits

 

  • branch: detour from main stream without changing main stream
  • remote: repo hosted online
  • local: repo on your hard drive (offline)
  • commit message and tag: notes assigned to commits
  • gist: small repo to share one code file

2. Git: Terminiology (2)

  • to commit
  • to merge
  • to fork
  • to clone
  • to push
  • to pull

2. Git: Terminiology (2)

  • to commit: create a commit
  • to merge: merge on branch into another branch
  • to fork: create a copy of someone else’s repo in your GitHub account
  • to clone: create your local copy of the repo
  • to push: upload changes from your local to your remote
  • to pull: update local from remote

2. Git: Getting started