Einführung in Markdown und Git

# Einführung in Markdown und Git
## Git together: Dynamische Dokumente erstellen mit Werkzeugen des 21. Jahrhunderts. <br>
### <br><br> ifes/iwp | FOM | Sebastian Sauer

---

# Gliederung

1. .xxxlarge[.bold[[Reproduzierbarkeit](#repro)]]

2. [Markdown](#partMD)

3. [Git](#partGIT)

4. [Fazit](#partFINAL)

---

# Ihre Erwartungen an diesen Workshop

---

# Lernziele

TEIL .bold[*EINFÜHRUNG*]

1. Relevanz von Reproduzierbarkeit vermitteln

TEIL .bold[*MARKDOWN*]

2. Nützlichkeit/Anwendungsfälle von Markdown vermitteln
  3. Kompetenz für typische Anwendungsfälle (für Markdown) vermitteln

TEIL .bold[*GIT*]

4. Nützlichkeit/Anwendungsfälle von Git vermitteln
  5. *Grund*kompetenz (von Git) vermitteln

---

# Was ist das Wesensmerkmal der Wissenschaft?

]

~~Das~~ Ein Wesensmerkmal der Wissenschaft ist *Transparenz*.

Wissenschaft heißt *zeigen*, nicht *glauben*.

---

# Transparenz ist notwendig für *Reproduzierbarkeit*

>   reproducibility refers to the ability of a researcher to duplicate the results of a prior study using the same materials as were used by the original investigator. [GFI16].

Ein Forschungsbericht sollte wie ein *Kochrezept* sein: Alle Informationen sind enthalten, um das Gericht jeweils (ausreichend) gleich nachzukochen.

⚡ Ist ein Forschungsergebnis nicht reproduzierbar, sind wir zum (Nicht-)Glauben gezwungen. Das ist keine Wissenschaft.

*Open Science*: Open data, open materials, open code, literate programming ...

---

# Beispiel: Projekt [TIER](https://www.projecttier.org/about/about-project-tier/)

>    Project TIER (Teaching Integrity in Empirical Research) promotes the integration of principles and practices related to transparency and replicability in the research training of social scientists.

>    Our goal is to reach a day in which training in research transparency becomes standard and ubiquitous in the education of social scientists.

---

# Aber haben wir ein Problem mit geringer Reproduzierbarkeit?

[Bak16]

Ja.

---

# Was sind die Ursachen geringer Reproduzierbarkeit?

- *Fehlende Informationen*
- Fehlende Nachvollziehbarkeit
- Copy-Paste-Fehler
- Keine Syntax
- Keine frei nutzbaren Messinstrumente
- Software-Updates
- Verwendete Software nicht mehr verfügbar
- Verwendete Werkzeuge zu teuer
- ...

---

# Reproduzierbarkeit in typischer Forschungsarbeit

.center[
<video width="320" height="240">
<source src="https://www.youtube.com/watch?v=s3JldKoA0zw&feature=youtu.be" type="video/mp4">
</video>
]

---

# Ein prominenter Forscher zu "Point-and-Click"

.middle[
<img src="https://xcelab.net/rm/wp-content/uploads/2012/01/9781482253443.jpg" width="70%" style="display: block; margin: auto;" />
]
]

.right-column[
>    [The command line] also saves you time and fulfills ethical obligations. With command scripts, each analysis documents itself, so that years from now you can come back to your analysis ans replicate it exactly. You can re-use your old files and send them to colleagues. Pointing and clicking, however, leaves no trail of breadcrumps. [...] Once you get in the habit of planning, running and preserving your statistical analysis in this way, it pays for itself many times over. With point-and-click, you pay down the road, rather than only up front. [McE16]

]

---

# Wäre es nicht schön ... 1/2

.pull-left[
>   .xxlarge["Die mittlere Reaktionszeit betrug **\[.blue[hier automatisch das Ergebnis der Berechnung einfügen]\]** Sekunden."]
]

.pull-right[
<a href="https://imgflip.com/i/39nb0w"><img src="https://i.imgflip.com/39nb0w.jpg" title="made at imgflip.com"/></a>
]

---

# Wäre es nicht schön ... 2/2

Bla bla bla ...

```r
x1 = rechne(Input_Data)
x2 = rechne_mehr(x1)
x3 = irgendwas(x2)
x4 = wildes_zeugs(x3)
```

Die mittlere Reaktionszeit betrug `x4` Sekunden.

Bla bla bla ...
]

Bla bla bla ...

Die mittlere Reaktionszeit betrug .red[.bold[3.141]] Sekunden.

Bla bla bla ...

]

---

# Gliederung

1. [Reproduzierbarkeit](#repro)

2. .xxxlarge[.bold[[Markdown](#partMD)]]

3. [Git](#partGIT)

4. [Fazit](#partFINAL)

---

# Es geht: Z.B. mit Markdown <i class="ion  ion-social-markdown "></i>

```markdown

# Ich bin ein Titel.

Ich bin ein Satz.

Eine Liste beginnt.
  
- ja
- nein
- vielleicht
  
Eine nummerierte Liste:
  
1. 3.4145
2. 2.7182
3. 42

```
]

Eine Liste beginnt.
  
- ja
- nein
- vielleicht
  
Eine nummerierte Liste:

1. 3.4145
2. 2.7182
3. 42

]

---

# Markdown ist fast WYSIWYG

```markdown

__fett__,

_kursiv_,

~~durchgestrichen~~
```
]

**fett**,

*kursiv*,

~~durchgestrichen~~

]

---

# Noch mehr Markdown

```markdown
# Title level 1

## Title level 2

Link:  [my blog](https://data-se.netlify.com/)

Citation: [@Xie2018]

Image: ![my image](imgs/R-logo_small.png)

```
]

## Title level 2

Link:  [my blog](https://data-se.netlify.com/).

Citation: (Xie & Allaire, 2018)

Image: <img src="imgs/R-logo_small.png" width="40">

---

# Bilder einfügen

- via Markdown: 
```md
![my image](imgs/R-logo_small.png)
```

- via HTML: 
```html
<img src="http://bit.ly/wiki-toddy" width="15%" align="right" />
```
- via R:
```r
knitr::include_images("path_to_image")
```

Tipp: [RStudio-Snippets](https://support.rstudio.com/hc/en-us/articles/204463668-Code-Snippets) anlegen für häufige Idiome.

---

# Markdown ist eine Markup-Sprache

*Markup-Sprachen* nutzen Auszeichungen zur Formatierung von Text. Sie basieren auf Textdateien.

Bekannte Beispiele:

- HTML
- LaTeX
- XML
- Word (ist XML)
- Powerpoint (ist XML)
- ...

Markdown ist eine sehr einfache Markup-Sprache (daher "Mark-Down").

---

# 🏋 Übung: Erstellen Sie ein Markdown-Dokument in RStudio!

1. In RStudio: File > New File > R Markdown > ... OK
2. Löschen Sie alles, was in der Datei schon steht
3. Schreiben Sie ein paar Zeilen in Markdown
4. Klicken Sie auf "Knit" (engl. für stricken) oder drücken Sie Strg-Shift-K

[Erklärvideo](https://youtu.be/XWmOF1arO3I)

---

# Markdown is nicht Latex

```tex
\makeatletter
\newenvironment{kframe}{%
\medskip{}
\setlength{\fboxsep}{.8em}
 \def\at@end@of@kframe{}%
 \ifinner\ifhmode%
  \def\at@end@of@kframe{\end{minipage}}%
  \begin{minipage}{\columnwidth}%
 \fi\fi%
 \def\FrameCommand##1{\hskip\@totalleftmargin \hskip-\fboxsep
 \colorbox{shadecolor}{##1}\hskip-\fboxsep
     % There is no \\@totalrightmargin, so:
     \hskip-\linewidth \hskip-\@totalleftmargin \hskip\columnwidth}%
 {\par\unskip\endMakeFramed%
 \at@end@of@kframe}
\makeatother
```

Zum Glück.

---

# Ich, als ich neulich kurz was in meiner Latex-Präambel ändern wollte

---

# Markdown als *lingua franca* der Markup-Sprachen

Mit dem Programm [Pandoc](http://pandoc.org/MANUAL.html) lassen sich Markup-Sprachen ineinander übersetzen.

---

# Kurz mal Pause ...

Wir haben uns *nicht* mit Formatierung des Textes beschäftigt, nur mit seinem Inhalt.

*Jemand* (etwas) hat uns die Formatierung abgenommen.

]

<a href="https://imgflip.com/i/39nh45"><img src="https://i.imgflip.com/39nh45.jpg" title="made at imgflip.com"/></a>
]

---

# R + Markdown = RMarkdown

.left-column[
<img src="https://www.rstudio.com/wp-content/uploads/2014/04/rmarkdown-200x232.png" width="100" height="116">
]

````

# Überschrift Ebene 1

Bla bla bla.
__Fettdruck, weil dicke Hose__

```{r}
x <- 2^10
```

Die Lösung ist `r x`.
````

]

---

# R-Diagramme

Auf dem üblichen Weg:

```r
gf_point(mpg ~ hp, data = mtcars) %>% 
  gf_lm()
```

---

# 🏋 Übung: Erstellen Sie ein RMarkdown-Dokument in RStudio!

Sie können mit diesem Code beginnen und dann nach eigenem Belieben anpassen:

````

# Überschrift Ebene 1

Bla bla bla.
__Fettdruck, weil dicke Hose__

```{r}
x <- 2^10
```

Die Lösung ist `r x`.
````

---

# Markdown ist schon ziemlich cool

---

# Was sind die Metadaten eines Dokuments?

Metadaten sind Daten über Daten (hier: über ein Dokument), z.B.

--
- Titel

- Autor

- Papiergröße

- ...

---

# Metadaten in RMarkdown

Metadaten werden in RMarkdown in einem Bereich, der mit `---` vorne und hinten abgegrenzt ist, definiert:

```
--- 
title: "Das ist der Titel des Dokuments"
author: "Hier steht der Name des Authors"
date: 2019-09-16  # Man kann auch R-Inline-Befehle einflechten
--- 
  
```

Das Format ist i.d.R. `Variable = Wert`.

Genauer gesagt wird das ([YAML-](https://en.wikipedia.org/wiki/YAML))Format verwendet.

Meist steht dieser Bereich zu Beginn des Dokuments (daher "YAML-Header").

---

# 🏋 Übung: Fügen Sie Ihrem Rmd-Dokument einen YAML-Header hinzu!

````
---
title: "Das ist der Titel des Dokuments"
author: "Hier steht der Name des Authors"
date: `r Sys.Date()`
---

# Überschrift Ebene 1

Bla bla bla.
__Fettdruck, weil dicke Hose__

```{r}
x <- 2^10
```

Die Lösung ist `r x`.
````

---

# RMarkdown-Ablauf

---

# Wofür kann man (R)Markdown alles verwenden?

---

# Websites/Blogs

![](imgs/data-se-screenshot.png)

---

# Berichte

![](imgs/report-screenshot.png)

---

# Bücher

![](imgs/modar.png)

---

background-image: url("https://user-images.githubusercontent.com/163582/45438104-ea200600-b67b-11e8-80fa-d9f2a99a03b0.png")
background-size: 100px
background-position: 90% 8%

# Folien (z.B. mit [Xaringan](https://slides.yihui.name/xaringan/))

# Beipiele für Xaringan-Präsentationen

1. [Alison Hill - RStudio Conf 2019](https://arm.rbind.io/slides/xaringan.html#1)
2. [Yongfu Liao - Chocolate Theme](https://yongfu.name/slides/xaringan/#1)
3. [Yihui Xie - Presentation Ninja](https://slides.yihui.name/xaringan/#1)
4. [Science Communication with Xaringan/R](https://abichat.github.io/Slides/ScienceCommunicationSOTR/ScienceCommunicationSOTR.html#1)
5. [Emi Tanaka - Kunoichi Theme](https://emitanaka.org/ninja-theme/themes/kunoichi/kunoichi-theme-example.html#1)
---

# [Papaja](https://github.com/crsh/papaja): Eine Vorlage für APA-Manuskripte

![](imgs/oom.png)

---

# [yart](https://github.com/sebastiansauer/yart): Eine Vorlage für Forschungsberichte

![](https://raw.githubusercontent.com/sebastiansauer/yart/master/docs/yart_screenshot.png)

---

# Poster mit [posterdown](https://github.com/brentthorne/posterdown)

]

<img src="https://pythonawesome.com/content/images/2019/04/example_poster1.png" width="70%" style="display: block; margin: auto;" />
]

---

# Interaktive Diagramme in HTML

<div id="htmlwidget-b331b69d6b1dfa41ffe6" style="width:100%;height:1112.4px;" class="widgetframe html-widget"></div>
<script type="application/json" data-for="htmlwidget-b331b69d6b1dfa41ffe6">{"x":{"url":"WS-MD-Git-2019_files/figure-html//widgets/widget_leaflet.html","options":{"xdomain":"*","allowfullscreen":false,"lazyload":false}},"evals":[],"jsHooks":[]}</script>

---

# Ja, aber - Sollte *ich* Markdown verwenden?

---

# Markdown hat mehr Power

---

# Ja, aber - ich liebe MS Word ...

Eine Seite mit Word, noch ein paar Seiten, und irgendwann ...

Markdown verkraftet auch große Dokumente.

---

# Animationen

---

# Buch "Moderne Datenanalyse mit R" (MODAR)

- ca. 500 Seiten
- ca. 200 Abbildungen
- ca. 200 R-Codes

Relativ großes Doukument.

Keine Schnapp-Atmung beim Bearbeiten/Erstellen, aber relativ lange Kompilationsdauer (ca. 2 Minuten).

---

# Pro MODAR-Kapitel eine Datei

```

rmd_files: 
[
  "index.Rmd",
  "01_Statistik_heute.Rmd",
  "02_Hallo_R.Rmd",
  "03_R_starten.Rmd",
  "04_Erstkontakt.Rmd",
  # "05_Datenstrukturen.Rmd",
  "06_Datenimport_und_export.Rmd",

...

]
```

---

# MODAR-Metadaten-Datei

```
title: "Moderne Datenanalyse mit R"
subtitle: "Entwurf"
author: "Sebastian Sauer"
lang: de-De
documentclass: book
classoption: a4paper
fontsize: 11pt
fontfamily: mathpazo

...

```

---

# MODAR-Beispielseite

---

#  🏋 Übung: HTML-Stylesheets

Vorab sind 13 HTML-Formatvorlagen (Stylesheets, Themes) installiert: “cerulean”, “cosmo”, “flatly”, “journal”, “lumen”, “paper”, “readable”, “sandstone”, “simplex”, “spacelab”, “united”, und “yeti”. [Hier](http://www.datadreaming.org/post/r-markdown-theme-gallery/) einige Beispiele.

Probieren Sie verschiedene aus!

```yaml
---
title: "test"
output:
  html_document:
    theme: united
---
```

---

# Snytax-Highlighting

Es gibt auch verschiedene Syntax-Highlight-Stile:

>   highlight specifies the syntax highlighting style. Supported styles include  default, tango, pygments, kate, monochrome, espresso, zenburn, haddock, and textmate. Pass null to prevent syntax highlighting.

[Überblick](https://www.garrickadenbuie.com/blog/pandoc-syntax-highlighting-examples/)

Passen Sie Ihren YAML-Header entsprechend an:

```yaml
---
title: "test"
output:
  html_document:
    # theme: united
    highlight: tango
---
```

---

#  🏋 Übung: Prettydoc-Stylesheets (für HTML)

1. Installieren Sie das R-Paket `prettydoc` mit `install.packages("prettydoc")`.
2. Öffnen Sie eine neue Rmd-Datei "from Template"
3. Wählen Sie die `prettydoc`-Vorlage
4. Basteln Sie nach Herzenslust daran herum.
5. Wählen Sie weitere Vorlagen etc.

[Projektseite](https://github.com/yixuan/prettydoc)

---

# 🏋 Übung: Chunk-Options

R-Chunks kann man mit Optionen versehen, um die Ausgabe zu steuern.

Entschlüsseln Sie die Bedeutung der Chunk-Optionen!

````
```{r demo-plot, out.width="70%", fig.align = "center", 
      echo = FALSE, eval = FALSE}
knitr::include_graphics("imgs/modar-sample1.png")
```
````

Lesen Sie [hier](https://yihui.name/knitr/options/) mehr über Chunk-Optionen!

---

# Ein Credo zum Textschreiben

**Ich glaube, dass man beim Schreiben ...**

1. nur schreiben soll, sich nicht schon mit der Formatierung beschäftigen soll.

2. immer nur eine Sache zu einer Zeit tun soll. Man beginne mit der Gliederung, es folgen stichpunktartige Notizen , schließlich formuliere man Sätze , danach erst beginne man mit Formatierung.

3. reichlich von Metatext Gebrauch machen soll, in Sinne von Kommentaren über seinen Text (als Gedankenstütze).

4. zum Schluss auf anspruchsvolle Typografie achten soll (Ästhetik und Lesbarkeit). Allerdings verzichte man auf Schnörkel.

5. nicht einen 500-Seiten-Haufen schreiben soll, sondern intensiv und auf mehreren Ebenen gliedern soll (Ordner, Dateien, Dateien für Bilder oder Daten, Kapitel, Absätze, ...).

---

# Grundlagen des Zitierens

.pull-left[
- Zitations-Infos sollten im Bib-Format in einer Datei abgelegt sein (s. rechte Seite).
- Im YAML-Header wird der Dateiname mit den Zitationsinfos festgelegt.
- Außerdem wird im YAML-Header etwaige Zitationsstile (z.B. APA6) definiert. 
- Im Text kann dann mit `[@ID]` zitiert werden, z.B. `[@baker_1500_2016]`
]

.pull-right[
```
@article{baker_1500_2016,
  title = {1,500 Scientists Lift ...},
  volume = {533},
  issn = {0028-0836, 1476-4687},
  language = {en},
  number = {7604},
  journal = {Nature},
  doi = {10.1038/533452a},
  author = {Baker, Monya},
  month = may,
  year = {2016},
  pages = {452-454}
}
```
]

---

#  🏋 Übung: Zitieren

1. Erstellen Sie eine Datei namens  `Literatur.bib` im Verzeichnis Ihrer Rmd-Datei.
2. Kopieren Sie einen Zitationseintrag im Bib-Format (s. vorherige Seite) in Ihre Literatur-Datei (oder nehmen Sie [diese](https://data-se.netlify.com/slides/WS-MD-Git-2019/input/bib.bib)).
3. Fügen Sie den Namen ihrer Literaturdatei in den YAML-Header ein mit dem Parameter `bibliography: <name.bib>`.

Wenn Sie keinen Pfad (zu Ihrer Literaturdatei) angeben, so muss diese im gleichen Verzeichnis wie die Rmd-Datei liegen.

```yaml
---
blablabla
bibliography: Literatur.bib
blablabla
---
```

[Hier](https://data-se.netlify.com/slides/WS-MD-Git-2019/input/Demo-Zitieren.Rmd) finden Sie einen Lösungsvorschlag.

---

# Zitationsstil wählen

Böse Zungen behaupten, es gäbe mehr Zitationsstile als Journals ...

Eine gängige Variante zur Definition von Zitationsstilen ist das [CSL](https://citationstyles.org/)-Format.

Um einen Zitationsstil zur Formatierung Ihrer Zitationen anzuwenden, müssen Sie:

- Den Zitationsstil als CSL-Datei herunterladen (z.B. von [hier](https://citationstyles.org/) oder von [hier, schon als APA6](https://data-se.netlify.com/slides/WS-MD-Git-2019/input/apa.csl))
- Die CSL-Datei in Ihr Verzeichnis stellen (dort, wo sich auch die Rmd-Datei befindet)
- Im YAML-Header mit dem Parameter `csl: <csl-datei.csl>` auf die Datei verweisen.

---

# Tabellen 1

Es gibt viele Optionen für Tabellen in Markdown via R, z.B. `knitr::kable()`

```r
knitr::kable(head(iris), format = "html")
```

<table>
 <thead>
  <tr>
   <th style="text-align:right;"> Sepal.Length </th>
   <th style="text-align:right;"> Sepal.Width </th>
   <th style="text-align:right;"> Petal.Length </th>
   <th style="text-align:right;"> Petal.Width </th>
   <th style="text-align:left;"> Species </th>
  </tr>
 </thead>
<tbody>
  <tr>
   <td style="text-align:right;"> 5.1 </td>
   <td style="text-align:right;"> 3.5 </td>
   <td style="text-align:right;"> 1.4 </td>
   <td style="text-align:right;"> 0.2 </td>
   <td style="text-align:left;"> setosa </td>
  </tr>
  <tr>
   <td style="text-align:right;"> 4.9 </td>
   <td style="text-align:right;"> 3.0 </td>
   <td style="text-align:right;"> 1.4 </td>
   <td style="text-align:right;"> 0.2 </td>
   <td style="text-align:left;"> setosa </td>
  </tr>
  <tr>
   <td style="text-align:right;"> 4.7 </td>
   <td style="text-align:right;"> 3.2 </td>
   <td style="text-align:right;"> 1.3 </td>
   <td style="text-align:right;"> 0.2 </td>
   <td style="text-align:left;"> setosa </td>
  </tr>
  <tr>
   <td style="text-align:right;"> 4.6 </td>
   <td style="text-align:right;"> 3.1 </td>
   <td style="text-align:right;"> 1.5 </td>
   <td style="text-align:right;"> 0.2 </td>
   <td style="text-align:left;"> setosa </td>
  </tr>
  <tr>
   <td style="text-align:right;"> 5.0 </td>
   <td style="text-align:right;"> 3.6 </td>
   <td style="text-align:right;"> 1.4 </td>
   <td style="text-align:right;"> 0.2 </td>
   <td style="text-align:left;"> setosa </td>
  </tr>
  <tr>
   <td style="text-align:right;"> 5.4 </td>
   <td style="text-align:right;"> 3.9 </td>
   <td style="text-align:right;"> 1.7 </td>
   <td style="text-align:right;"> 0.4 </td>
   <td style="text-align:left;"> setosa </td>
  </tr>
</tbody>
</table>

---

# Tabellen 2

```r
DT::datatable(
  head(iris, 5),
  fillContainer = FALSE, options = list(pageLength = 8)
)
```

<div id="htmlwidget-0271755b4c5e6d44c3ce" style="width:100%;height:auto;" class="datatables html-widget"></div>
<script type="application/json" data-for="htmlwidget-0271755b4c5e6d44c3ce">{"x":{"filter":"none","fillContainer":false,"data":[["1","2","3","4","5"],[5.1,4.9,4.7,4.6,5],[3.5,3,3.2,3.1,3.6],[1.4,1.4,1.3,1.5,1.4],[0.2,0.2,0.2,0.2,0.2],["setosa","setosa","setosa","setosa","setosa"]],"container":"<table class=\"display\">\n  <thead>\n    <tr>\n      <th> <\/th>\n      <th>Sepal.Length<\/th>\n      <th>Sepal.Width<\/th>\n      <th>Petal.Length<\/th>\n      <th>Petal.Width<\/th>\n      <th>Species<\/th>\n    <\/tr>\n  <\/thead>\n<\/table>","options":{"pageLength":8,"columnDefs":[{"className":"dt-right","targets":[1,2,3,4]},{"orderable":false,"targets":0}],"order":[],"autoWidth":false,"orderClasses":false,"lengthMenu":[8,10,25,50,100]}},"evals":[],"jsHooks":[]}</script>

---

# Referenzieren von Abschnitten

```markdown
# Wichtiges Kapitel {#wichtig}

blablabla

# Unwichtiges Kapitel

Man lese im Kapitel \@ref(wichtig).
```

Das Referenzieren von Kapiteln ist [hier](https://bookdown.org/yihui/bookdown/cross-references.html) nachzulesen.

<i class="fas  fa-exclamation "></i> Um Referenzier-Funktionen der Art `@ref(id)` nutzen zu können, passen Sie bitte Ihren YAML-Header wie folgt an:

```markdown
blablabla
output:
  bookdown::pdf_document2
    <weitere-output-angaben>

blablabla
```

---

# Referenzieren von Abbildungen

<div class="figure" style="text-align: center">
<img src="WS-MD-Git-2019_files/figure-html/demo-plot-1.png" alt="Ein Beispiel" width="70%" />
<p class="caption">Ein Beispiel</p>
</div>

```md
Wie in Abbildung \@ref(fig:demo-plot) ersichtlich ...
```

---

# Referenzieren von Tabellen

```r
mtcars %>% 
  head(3) %>% 
  knitr::kable(caption = "Tabellen-Beschriftung", format = "html")
```

<table>
<caption>Tabellen-Beschriftung</caption>
 <thead>
  <tr>
   <th style="text-align:left;">   </th>
   <th style="text-align:right;"> mpg </th>
   <th style="text-align:right;"> cyl </th>
   <th style="text-align:right;"> disp </th>
   <th style="text-align:right;"> hp </th>
   <th style="text-align:right;"> drat </th>
   <th style="text-align:right;"> wt </th>
   <th style="text-align:right;"> qsec </th>
   <th style="text-align:right;"> vs </th>
   <th style="text-align:right;"> am </th>
   <th style="text-align:right;"> gear </th>
   <th style="text-align:right;"> carb </th>
  </tr>
 </thead>
<tbody>
  <tr>
   <td style="text-align:left;"> Mazda RX4 </td>
   <td style="text-align:right;"> 21.0 </td>
   <td style="text-align:right;"> 6 </td>
   <td style="text-align:right;"> 160 </td>
   <td style="text-align:right;"> 110 </td>
   <td style="text-align:right;"> 3.90 </td>
   <td style="text-align:right;"> 2.620 </td>
   <td style="text-align:right;"> 16.46 </td>
   <td style="text-align:right;"> 0 </td>
   <td style="text-align:right;"> 1 </td>
   <td style="text-align:right;"> 4 </td>
   <td style="text-align:right;"> 4 </td>
  </tr>
  <tr>
   <td style="text-align:left;"> Mazda RX4 Wag </td>
   <td style="text-align:right;"> 21.0 </td>
   <td style="text-align:right;"> 6 </td>
   <td style="text-align:right;"> 160 </td>
   <td style="text-align:right;"> 110 </td>
   <td style="text-align:right;"> 3.90 </td>
   <td style="text-align:right;"> 2.875 </td>
   <td style="text-align:right;"> 17.02 </td>
   <td style="text-align:right;"> 0 </td>
   <td style="text-align:right;"> 1 </td>
   <td style="text-align:right;"> 4 </td>
   <td style="text-align:right;"> 4 </td>
  </tr>
  <tr>
   <td style="text-align:left;"> Datsun 710 </td>
   <td style="text-align:right;"> 22.8 </td>
   <td style="text-align:right;"> 4 </td>
   <td style="text-align:right;"> 108 </td>
   <td style="text-align:right;"> 93 </td>
   <td style="text-align:right;"> 3.85 </td>
   <td style="text-align:right;"> 2.320 </td>
   <td style="text-align:right;"> 18.61 </td>
   <td style="text-align:right;"> 1 </td>
   <td style="text-align:right;"> 1 </td>
   <td style="text-align:right;"> 4 </td>
   <td style="text-align:right;"> 1 </td>
  </tr>
</tbody>
</table>

```md
Wie in Tabelle \@ref(tab:demo-tab) ersichtlich ...
```

# 🏋 Übung: Referenzieren

Erstellen Sie eine Dokument, in dem Sie (Kapitel, Abbildungen und/oder Tabellen) referenzieren!

[Hier](https://data-se.netlify.com/slides/WS-MD-Git-2019/input/Demo-Zitieren.Rmd) finden Sie einen Lösungsvorschlag.

---

# Weitere Formatierungsoptionen

- Im Buch [RMarkdown - The Definitive Guide](https://bookdown.org/yihui/rmarkdown/html-document.html) finden sich (in Kapitel 3.1) weitere Hinweise zum Formatieren von HTML-Dokumenten mit RMarkdown.

- Dieses [Cheatsheet "Rmarkdown 2.0"](https://github.com/rstudio/cheatsheets/raw/master/rmarkdown-2.0.pdf) gibt einen guten Überblick über Optionen mit RMarkdown.

- RStudio bietet einige gute Tutorials, z.B. [hier](https://rmarkdown.rstudio.com/lesson-1.html).

---

# [Buch](https://bookdown.org/yihui/rmarkdown/) zum Einstieg

---

# [Dieses](https://bookdown.org/yihui/bookdown/) ist auch gut

---

# Gliederung

1. [Reproduzierbarkeit](#repro)

2. [Markdown](#partMD)

3. .xxxlarge[.bold[[Git](#partGIT)]]

4. [Fazit](#partFINAL)

---

# Jungwissenschaftler Sebastian S. -- Ein Drama in 3 Akten (1/3)

Jung-
Forscher
Sebastian S.
]

- Unser Jungwissenschaftler schreibt als brave Fleißbiene 🐝 einen Entwurf für einen Fachartikel 📜.

- Den Text (als Word) schickt er an seine Betreuer 👩‍🔬 👨‍🔬 (und weitere wichtige Menschen 🧝‍♀️ 🦸‍♂️ 👩‍💻, die auf dem Paper als Coautoren erscheinen möchten). Insgesamt an fünf Menschen.

<img src="imgs/email1-crop.png" width="50%" style="display: block; margin: auto;" />
]

---

# 2. Akt

Jung-
Forscher
Sebastian S.
]

- Die wichtigen Menschen tun, was Sie immer tun, und manche schicken irgendwann irgendetwas an den Jungwissenschaftler zurück.

- Der Jungwissenschaftler versucht, die fünf Beiträge mit seinem Entwurf zusammenzufassen.

]

---

# 3. Akt

Jung-
Forscher
Sebastian S.

läuft AMOK
]

- Beim Jungwissenschaftler ist eine nervöse Selbstauflösung zu beobachten.

]

---

# Wie können wir den Jungwissenschaftler glücklich machen?

Desiderata der Änderungsnachverfolgung beim Texte schreiben

<table>
 <thead>
  <tr>
   <th style="text-align:right;"> Nr </th>
   <th style="text-align:left;"> Desideratum </th>
   <th style="text-align:left;"> Word </th>
   <th style="text-align:left;"> Git </th>
  </tr>
 </thead>
<tbody>
  <tr>
   <td style="text-align:right;"> 1 </td>
   <td style="text-align:left;"> Übersichtlichkeit </td>
   <td style="text-align:left;"> Nein </td>
   <td style="text-align:left;"> Ja </td>
  </tr>
  <tr>
   <td style="text-align:right;"> 2 </td>
   <td style="text-align:left;"> Exakte Kontrolle </td>
   <td style="text-align:left;"> Nein </td>
   <td style="text-align:left;"> Ja </td>
  </tr>
  <tr>
   <td style="text-align:right;"> 3 </td>
   <td style="text-align:left;"> Schutz vor versehentlichem Überschreiben </td>
   <td style="text-align:left;"> Nein </td>
   <td style="text-align:left;"> Ja </td>
  </tr>
  <tr>
   <td style="text-align:right;"> 4 </td>
   <td style="text-align:left;"> Mehrpersonentoleranz (Kollaboration) </td>
   <td style="text-align:left;"> Nein </td>
   <td style="text-align:left;"> Ja </td>
  </tr>
  <tr>
   <td style="text-align:right;"> 5 </td>
   <td style="text-align:left;"> Varianten </td>
   <td style="text-align:left;"> Nein </td>
   <td style="text-align:left;"> Ja </td>
  </tr>
  <tr>
   <td style="text-align:right;"> 6 </td>
   <td style="text-align:left;"> Robustheit bei großen Dokumenten </td>
   <td style="text-align:left;"> Nein </td>
   <td style="text-align:left;"> Ja </td>
  </tr>
  <tr>
   <td style="text-align:right;"> 7 </td>
   <td style="text-align:left;"> Technische Ausfallsicherheit </td>
   <td style="text-align:left;"> Nein </td>
   <td style="text-align:left;"> Ja </td>
  </tr>
  <tr>
   <td style="text-align:right;"> 8 </td>
   <td style="text-align:left;"> Produktunabhängigkeit </td>
   <td style="text-align:left;"> Nein </td>
   <td style="text-align:left;"> Ja </td>
  </tr>
  <tr>
   <td style="text-align:right;"> 9 </td>
   <td style="text-align:left;"> Flache Lernkurve </td>
   <td style="text-align:left;"> Ja </td>
   <td style="text-align:left;"> Nein </td>
  </tr>
</tbody>
</table>

---

# Dateien versionieren -- kann helfen

---

# Wäre es nicht schön ... 1/2

Wenn man Änderungen am Text in zusammengehörigen Bündeln schön übersichtlich sehen könnte?

Betrachten Sie dieses Beispiel-Repo:

https://github.com/sebastiansauer/test_ses

---

# Wäre es nicht schön ... 2/2

Wenn man dann für jedes "Änderungsbündel" die Änderungen schön übersichtlich sehen könnte?

Natürlich sollte Autor und Zeitpunkt der Änderung auch dokumentiert sein.

---

# Je größer das Projekt,

... desto wichtiger ist ein gutes Werkzeug zur Änderungskontrolle

Ein "Änderungsbündel" wird in Git als *Commit* bezeichnet. Ein Git-Ordner mit allem Drum und Dran wird als *Repo(sitorium)* bezeichnet.

---

# Beispielprojekt: Statistik-Vorlesungen an der FOM

196 Dokumente in 63 Ordnern, 825 Mb

---

# Solch große Projekten sind nicht gut in Word aufgehoben

Dafür ist Word nicht gemacht.

---

# Auszug aus den Commits im Repo `Vorlesungen`

---

# Quiz mit Word

1. Wer hat "liegt eine Stichprobe geändert"?
2. Was stand an dieser Stelle davor?
3. Handelt es sich bei der Änderung um eine Ergänzung oder eine Modifikation oder eine Löschung?
1. Ist "Autor" ein Name oder der Urheber des Dokuments?
4. Wann wurden die Änderungen vorgenommen?
5. Wie kann man den Verlauf der Änderungen sehen?

---

# Git-Workflow 1

1. Git starten (Odner für Git initialsieren)
2. Änderungen vornehmen (ggf. an mehreren Dateien)
3. Dateien auswählen, deren Änderungen dokumentiert werden sollen ("adden" oder "stagen")
4. Änderungen einstellen ("committen")
5. Änderungen zum Server replizieren ("pushen")
6. Ggf. Änderungen prüfen und kommentieren

---

# Komponenten eines Git-Projekts

- *Repository*: Der Container, der alle Dateien und alle Änderungen eines Projekt enthält.

- *Working Tree*: Dateisystem der Repos in aktueller (oder frühere) Version

- *Staging Area* (*Index*): Dokumentiert Dateien mit Änderungen, die noch nicht eingestellt sind.

- *Head*: Aktuellste Version des Projekts (neuester Commit) im aktuellen Branch

- *Branch*: Variante des Projekts

---

# Git-Workflow mit Fachbegriffen

---

# Aber lohnt sich Git für mich?

>    A solo data analyst, working on a single computer, will benefit from adopting version control. But not nearly enough to justify the pain of installation and workflow upheaval. There are much easier ways to get versioned back ups of your files, if that’s all you’re worried about.

In my opinion, for new users, the pros of Git only outweigh the cons when you factor in the overhead of .xlarge[communicating and collaborating with other people].

---

# Github

.left-column[
<img src="https://upload.wikimedia.org/wikipedia/commons/5/58/Octocat_GitHub_Mascot.png" width="70%" style="display: block; margin: auto;" />
]

- Hosting-Anbieter für Git-Repos

- 2018 von Microsoft gekauft (7.5 Mrd. USD)

- Neben reinem Git werden noch ergänzende Funktionen wie *Issues* (Art Ticketsystem) etc. angeboten

- Größte Sammlung von Source Code in der Welt

]

---

# Git* installieren

1. Account (kostenlos) bei [Github](https://github.com) anlegen
2. RStudio herunterladen bzw. aktualisieren
3. Git herunterladen/installieren [Hinweise](https://happygitwithr.com/install-git.html)
4. Bei Git [anmelden](https://happygitwithr.com/hello-git.html)
5. Git-Editor (z.B. [Github Desktop](https://desktop.github.com/)) installieren

---

# Ein erstes Repo anlegen 1/2

1. Loggen Sie sich bei Github ein.
2. Klicken Sie bei "Repositories" auf New (grüner Knopf).

---

# Ein erstes Repo anlegen 2/2

1. Füllen Sie die Maske aus.
2. Grünen Knopf drücken ("Create Repository"). Fertig!

---

# Das Repo "clonen" 1/2

1. Gehen Sie in das Repo.
2. Klicken Sie auf den grünen Knopf ("Clone or Download"), wählen Sie "Clone".
3. Kopieren Sie den Git-Link heraus, z.B. "git@github.com:sebastiansauer/test_ses.git".

---

# Das Repo "clonen" 2/2

1. Öffnen Sie RStudio
2. Legen Sie ein Git-Projekt an: File > New Project ... > Version Control > Git.
3. Kopieren Sie bei "Repository Url" die Git-Url Ihres Repos ein.
4. Verzeichnisname etc. können Sie nach Belieben wählen.

---

# 🏋 Übung: Legen Sie sich ein Github-Repo in RStudio an

Jetzt haben Sie Ihr Repo in RStudio verfügbar.

Vertiefung: [Passwörter-Cache mit Git/Github](https://happygitwithr.com/credential-caching.html)

---

# 🏋 Übung: Stellen Sie Änderungen in Ihr Repo ein.

---

# Mögliche Probleme

Das Buch von Jenny Bryant *Happy Git with R* gibt eine gute Einführung in das Thema.

[Dort](https://happygitwithr.com/troubleshooting.html) finden Sich auch Hinweise bei Problemen.

---

# 🏋 Übung: Arbeiten Sie im Team

1. Fügen Sie sich in Ihrem Github-Repo gegenseitig als Mitarbeiter hinzu: Settings > Collaborators.
2. Sie müssen dazu die entsprechenden Nutzernamen wissen.
3. Ändern Sie nun etwas an einem Repo, zu dem Sie eingeladen wurden.

---

# Einige Git-Befehle für die Kommandozeile (Terminal)

- `git init`: Legt in einem Ordner die Git-Infrastruktur an.
- `git status`:  Gibt einen Überblick über den Status eines Repos.
- `git add .`: Fügt alle Dateien dem Index zu (staged die Dateien).
- `git commit -m "meine nachricht"`. Committed die gestageden Dateien und fügt eine (hoffentlich aussagekräftige) Nachricht hinzu
- `git pull`: Zieht das Repo vom zentralen Server und mergt es in das lokale Repo.
- `git push`: Lädt das lokale Repo zum zentraler Server hoch.
- `git stash`: Speichert die aktuellen Änderungen (sofern noch nicht committed) temporär.
- `git blame`: Zeigt, wer als letztes eine bestimmte Zeile einer Datei verändert hat.

---

# frühere Zustände betrachten - `git checkout <id>`

Mit

```
git checkout a1e8fb5
```

versetzt man den Working Tree in dem Zustand des Commits mit der ID a1e8fb5.

<i class="fas  fa-exclamation "></i> Man kann jetzt keine Änderungen vornehmen (*detached head*), sondern nur alte Zustände betrachten<sup>1</sup>.

Mit `git checkout master` kommt man wieder zum aktuellen Stand auf dem Branch *master*.

.footnote[1: Aber man kann von diesem Zustand aus einen neuen Branch öffnen mit z.B `git checkout -b my_new_branch`.]

---

# Frühere Zustände wiederherstellen 3/3 - `git checkout <commit-hash> <file>`

```git
git checkout git checkout bdcd88fdf18bce554046b4188e0a8aee0b5f1b0a Tweets-Data/party_tweets.Rda
```

Damit wird eine Datei/ein Ordner aus dem Commit `<commit-hash>` im Working Directory wiederhergestellt.

Mit 
```git
git reset HEAD~2 foo.R
```

Wird die Datei `foo.R` aus dem 2. letzten Commit wiederhergestellt.

---

# Frühere Zustände wiederherstellen 2/3 - `git revert`

Einen früheren Commit *wiederherstellen*:

```git
git revert HEAD
```

Damit wird der Zustand

Anstelle von `HEAD` kann man auch eine Commit-ID angeben.

---

# Frühere Zustände wiederherstellen 3/3 - `git reset`

<i class="fas  fa-bomb "></i> So widerrufen Sie Änderungen *unwiderruflich*:

```git
git reset --hard HEAD~
```

Working Tree und HEAD werden auf den Vorfahren des Heads zurückgesetzt. Der Index ist leer (keine Dateien auf der Staging Area).

So löscht man Änderungen im Working Directory (d.h. nicht committed)

```git
git reset --hard
```

---

# [Buch *Pro Git*](https://git-scm.com/book/en/v2) zum Einstieg und Vertiefen

freie [Online-Version](https://git-scm.com/book/en/v2)

---

# Wir brauchen eine Pause.

---

---

# Gliederung

1. [Reproduzierbarkeit](#repro)

2. [Markdown](#partMD)

3. [Git](#partGIT)

4. .xxxlarge[.bold[[Fazit](#partFINAL)]]

---

# OK, es kann auch Probleme geben

<i class="fab  fa-stack-overflow "></i> [StackOverflow](https://stackoverflow.com/) ist der Retter in Not.

---

# Danke für die Aufmerksamkeit

Sebastian Sauer

<i class="fab  fa-github "></i> [sebastiansauer](https://github.com/sebastiansauer)

<i class="fas  fa-envelope "></i> ssauer@posteo.de

<i class="fab  fa-linkedin-in "></i> [Sebastian Sauer](https://www.linkedin.com/in/dr-sebastian-sauer-4791762)

<i class="fas  fa-file "></i> Get slides here:

<http://data-se.netlify.com/slides/WS-MD-Git-2019/WS-MD-Git-2019.html>

<i class="fas  fa-code "></i> Get source code here:

<http://data-se.netlify.com/slides/WS-MD-Git-2019/WS-MD-Git-2019.Rmd>

---

# Literatur

Baker, M. (2016). "1,500 Scientists Lift the Lid on
Reproducibility". En. In: _Nature_ 533.7604, pp. 452-454. ISSN:
0028-0836, 1476-4687. DOI:
[10.1038/533452a](https://doi.org/10.1038%2F533452a).

Goodman, S. N, D. Fanelli, and J. P. A. Ioannidis (2016). "What
Does Research Reproducibility Mean?" In: _Science Translational
Medicine_ 8.341, pp. 341ps12-341ps12. ISSN: 1946-6234, 1946-6242.
DOI:
[10.1126/scitranslmed.aaf5027](https://doi.org/10.1126%2Fscitranslmed.aaf5027).

McElreath, R. (2016). _Statistical Rethinking_. New York City, NY:
Apple Academic Press Inc.. ISBN: 1-4822-5344-5.

---

# Jetzt sind Sie dran

---

# Reproducibility

- Versions of employed software as of 2019-09-16, running this OS: macOS Mojave 10.14.6.
- Built with [R](https://www.r-project.org/), R version 3.6.0 (2019-04-26), [RStudio](https://www.rstudio.com/) 1.2.1335, [xaringan](https://github.com/yihui/xaringan), on the shoulders of giants
- Icons are from [FontAwesome](https://fontawesome.com/), licenced under CC-BY-4 ([details](https://fontawesome.com/license/free))
- R-Packages used: .small[assertthat_0.2.1, backports_1.1.4, bibtex_0.4.2, brew_1.0-6, broom_0.5.2, cellranger_1.1.0, cli_1.1.0, codetools_0.2-16, colorspace_1.4-1, crayon_1.3.4, crosstalk_1.0.0, curl_3.3, data.table_1.12.2, DiagrammeR_1.0.1, DiagrammeRsvg_0.1, digest_0.6.20, downloader_0.4, dplyr_0.8.3, DT_0.7, emo_0.0.0.9000, evaluate_0.14, forcats_0.4.0, generics_0.0.2, ggdendro_0.1-20, ggformula_0.9.1, ggplot2_3.2.0, ggrepel_0.8.1, ggstance_0.3.2, glue_1.3.1.9000, gridExtra_2.3, gtable_0.3.0, haven_2.1.1, here_0.1, highr_0.8, hms_0.5.0, htmltools_0.3.6, htmlwidgets_1.3, httpuv_1.5.1, httr_1.4.0, icon_0.1.0, igraph_1.2.4.1, influenceR_0.1.0, jsonlite_1.6, knitr_1.23, later_0.8.0, lattice_0.20-38, lazyeval_0.2.2, leaflet_2.0.2, lubridate_1.7.4, magrittr_1.5, MASS_7.3-51.4, Matrix_1.2-17, mime_0.7, modelr_0.1.4, mosaic_1.5.0.9001, mosaicCore_0.6.0, mosaicData_0.17.0, munsell_0.5.0, nlme_3.1-140, pillar_1.4.2, pkgconfig_2.0.2, plotly_4.9.0, plyr_1.8.4, promises_1.0.1, purrr_0.3.2, R6_2.4.0, RColorBrewer_1.1-2, Rcpp_1.0.1, readr_1.3.1, readxl_1.3.1, RefManageR_1.2.12, rgexf_0.15.3, rlang_0.4.0, rmarkdown_1.14, Rook_1.1-1, rprojroot_1.3-2, rstudioapi_0.10, rvest_0.3.4, scales_1.0.0, sessioninfo_1.1.1.9000, shiny_1.3.2, stringi_1.4.3, stringr_1.4.0, tibble_2.1.3, tidyr_0.8.3, tidyselect_0.2.5, tidyverse_1.2.1, V8_2.3, vctrs_0.2.0, viridis_0.5.1, viridisLite_0.3.0, visNetwork_2.0.7, widgetframe_0.3.1, withr_2.1.2, xaringan_0.11, xaringanthemer_0.2.0, xfun_0.8, XML_3.98-1.20, xml2_1.2.0, xtable_1.8-4, yaml_2.2.0, zeallot_0.1.0]
- Last update 2019-09-16 09:55:13