To receive notifications about scheduled maintenance, please subscribe to the mailing-list gitlab-operations@sympa.ethz.ch. You can subscribe to the mailing-list at https://sympa.ethz.ch

README.Rmd 7.7 KB
Newer Older
lorenzwalthert's avatar
lorenzwalthert committed
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "figures/README-",
  out.width = "100%"
)
```

# A few words from the authors {-}

lorenzwalthert's avatar
lorenzwalthert committed
18
19
This repository is a bookdown template, derived from the LaTeX template from the
semiar for statistics, ETH Zurich.
lorenzwalthert's avatar
lorenzwalthert committed
20
21

**How bookdown works**
lorenzwalthert's avatar
lorenzwalthert committed
22

lorenzwalthert's avatar
lorenzwalthert committed
23
In a nutshell, bookdown works as follows:
lorenzwalthert's avatar
lorenzwalthert committed
24
25
26
27
28

* use knitr to convert Rmd to markdown.
* use pandoc to convert markdown to latex, pdf, word, html books (with featuers
  like font size, background selection, full text search etc), epub.

Lorenz Walthert's avatar
Lorenz Walthert committed
29
The basic workflow in RStudio is as follows:
lorenzwalthert's avatar
lorenzwalthert committed
30

Lorenz Walthert's avatar
Lorenz Walthert committed
31
* Open the RStudio project.
lorenzwalthert's avatar
lorenzwalthert committed
32
* Change a source file: In our template, the source of the body of the thesis
Lorenz Walthert's avatar
Lorenz Walthert committed
33
34
35
36
  is under `./rmd/`. For example, change `02-features.Rmd`. To make sure only
  files from this directory are used, get the devel versio of bookdown  and 
  add a corresponding confirugartion 
  (for details, see https://github.com/rstudio/bookdown/issues/242).
lorenzwalthert's avatar
lorenzwalthert committed
37
38
* Re-compile the book using Cmd + Shift + B (for build) on a Mac and Ctrl + 
  Shift + B on Windows / Linux.
lorenzwalthert's avatar
lorenzwalthert committed
39
* You can customize the build in the RStudio Build Tab, where you can specify
lorenzwalthert's avatar
lorenzwalthert committed
40
  which output (html, pdf, etc.) you want to generate. This is remembered for the
Lorenz Walthert's avatar
Lorenz Walthert committed
41
  next build you are doing.
lorenzwalthert's avatar
lorenzwalthert committed
42

lorenzwalthert's avatar
lorenzwalthert committed
43
44
45
**Getting started**

Fork the upstream repository and clone the fork. Then, you will have one remote
lorenzwalthert's avatar
lorenzwalthert committed
46
repository: origin, which refers to the fork. Add the upstream repo as an
lorenzwalthert's avatar
lorenzwalthert committed
47
48
49
upstream remote so you can later rebase on it in case you need. We recommend
using ssh over https.

Lorenz Walthert's avatar
Lorenz Walthert committed
50
51
52
If you are not familar with git, you can also simply download the repo.
However, we strongly recommend using version control for your thesis.

lorenzwalthert's avatar
lorenzwalthert committed
53
54
**Why using bookdown**

lorenzwalthert's avatar
lorenzwalthert committed
55
The advantages of using bookdown instead of plain LaTeX are, in the eyes of the
lorenzwalthert's avatar
lorenzwalthert committed
56
creator of this template:
lorenzwalthert's avatar
lorenzwalthert committed
57

lorenzwalthert's avatar
lorenzwalthert committed
58
* Generalization. Not just latex or PDF output, but any output supported by
lorenzwalthert's avatar
lorenzwalthert committed
59
60
61
  Pandoc, e.g. Word and html, epub. If you at some point decide to work with 
  LaTeX only, just render to LaTeX and continue. You don't loose anything 
  compared to status quo.
lorenzwalthert's avatar
lorenzwalthert committed
62
* The best of two worlds. Use intuitive markdown syntax where possible, use the
lorenzwalthert's avatar
lorenzwalthert committed
63
64
  full power of LaTeX syntax where needed. This includes bibtex reference, LaTeX 
  cross-, text- and figure reference.
lorenzwalthert's avatar
lorenzwalthert committed
65
66
67
* It's native R. Integrate R code and R output such as plots, tables, figures
  directly in your writing has never been easier than with bookdown. You can turn
  a data frame into a latex table using the power of R packages such as
lorenzwalthert's avatar
lorenzwalthert committed
68
69
  `kableExtra`. You can change the data subset, re-compile the whole book and 
  all figures, tables and other data dependent elements will be udpated.
lorenzwalthert's avatar
lorenzwalthert committed
70
71
72
* The power of RStudio. Use the same IDE for programming and writing. Leverage
  the advantages of a real-time latex  equation previewer right in your R
  Markdown, a git GUI, spell checking, file browser and more.
lorenzwalthert's avatar
lorenzwalthert committed
73
* You can also use other languages supported by knitr such as
lorenzwalthert's avatar
lorenzwalthert committed
74
75
  python, stan etc. You can even use R code to control the behavior of chunk 
  evaluation. Below, we even used the bash command `tree` to show the
lorenzwalthert's avatar
lorenzwalthert committed
76
77
  directory structure of this repo. Since unicode is not suppored with pdflatex,
  we used R code to tell knitr to use the tree command with the option `charset
lorenzwalthert's avatar
lorenzwalthert committed
78
79
  unicode` for pdf output and without it for html output. Check the Rmd source 
  of the README to learn more.
lorenzwalthert's avatar
lorenzwalthert committed
80
81
82
83
* Because it's native R, you can place R variables in the floating text. Check
  out the Rmd source of this document to see that we used R to compute the square
  root of three (`r sqrt(3)`), print todays date with `Sys.Date()` right into the
  text: `r Sys.Date()`
lorenzwalthert's avatar
lorenzwalthert committed
84
85
86

**How this template works**

lorenzwalthert's avatar
lorenzwalthert committed
87
There are different directories in this template:
lorenzwalthert's avatar
lorenzwalthert committed
88

lorenzwalthert's avatar
lorenzwalthert committed
89
```{bash, include = knitr::is_html_output()}
lorenzwalthert's avatar
lorenzwalthert committed
90
91
92
tree -d -L 2
```

lorenzwalthert's avatar
lorenzwalthert committed
93
94
95
96
97
98
```{bash, include = !knitr::is_html_output()}
tree -d -L 2 --charset unicode
```

* _book: Contains the compiled book, e.g. a PDF or html version.
* _bib: Contains BibTeX reference data bases.
lorenzwalthert's avatar
lorenzwalthert committed
99
* figure: Contains figures you created from your (R) code in the rmd source.
lorenzwalthert's avatar
lorenzwalthert committed
100
101
* images: Put images you want to include in your thesis in this folder.
* pdf: Put PDFs you want to include in your thesis in this folder.
lorenzwalthert's avatar
lorenzwalthert committed
102
103
104
105
106
* rmd: The source folder of thesis. When you build a book, the following
  happens: By default, all rmd files in this folder get merged into one big rmd
  file, according to their name. We suggest to use one file per chapter. Then, the
  file containing all the rmd sources will get processed by knitr and later by
  Pandoc.
lorenzwalthert's avatar
lorenzwalthert committed
107
* scratch: A random directory which is not tracked by git by default. The idea
lorenzwalthert's avatar
lorenzwalthert committed
108
109
  is that you can put things that are not ready to commit or that have a temporary
  character here.
lorenzwalthert's avatar
lorenzwalthert committed
110
* style: Latex .sty files. Taken from the sfs LaTeX template.
lorenzwalthert's avatar
lorenzwalthert committed
111
112
113
114
115
* tex: All tex data, most importantly, the sfs LaTeX template itself. Note that
  the abstract, preface, epilogue, summary, notation are still in tex, i.e. you
  need to change these files if you want the PDF output to change. This will
  **not** affect the html output. You can create chapters that show up in a
  particular output and not in the other forms as shown in
lorenzwalthert's avatar
lorenzwalthert committed
116
  `rmd/99-references.Rmd`.
lorenzwalthert's avatar
lorenzwalthert committed
117

lorenzwalthert's avatar
lorenzwalthert committed
118
119
120
Furthermore, we want to highlight a few files in the root directory of the
project:

lorenzwalthert's avatar
lorenzwalthert committed
121
122
123
124
125
* `DESCRIPTION`: You can use it to declare dependent packages of your thesis in
  the `Imports:` field. If someone want's to rebuild you thesis from scratch, the
  can use `remotes::install_deps()` to satisfy all R package dependencies.
* `index.Rmd`: Contains a YAML header where a few important variables are
  defined. You can also put markdown below the header.
lorenzwalthert's avatar
lorenzwalthert committed
126
* `README.(R)md`: This document.
lorenzwalthert's avatar
lorenzwalthert committed
127
* `thesis-template-bookdown.Rproj`: An RStudio project. We recommend using
lorenzwalthert's avatar
lorenzwalthert committed
128
129
130
131
  RStudio for authoring your master thesis with bookdown.

**A few recommendations**

lorenzwalthert's avatar
lorenzwalthert committed
132
133
134
135
136
137
* We strongly suggest to use a different folder for the data / code of your
  thesis and reserve this directory for the thesis document only. You can reaname
  this directory `analysis-communication` (since this will be the means used for
  communicating the results and process of your thesis) and use `analysis-raw` for
  the code and `data` for all data. Ideally, you place them in the same directory
  so you can still work with relative paths, e.g. `../data`.
lorenzwalthert's avatar
lorenzwalthert committed
138
* We suggest to use git version control for the thesis and the raw analsyis.
lorenzwalthert's avatar
lorenzwalthert committed
139
140
141
142
143
* If your thesis is open source, you can use netlify.com to deploy it, i.e. for
  every commit you push to a remote repo like GitHub, you can use netlify's CLI to
  build your book on a CI machine like travis. See file `travis.yml` for the
  bookdown book [Advanced
  R](https://github.com/hadley/adv-r/tree/88dcb07e2b2ae634af6cdeafff2f3ea976077064)
lorenzwalthert's avatar
lorenzwalthert committed
144
145
146
147
  for an example. That makes tracking the `_book` folder in git redundant.

**Further material**

lorenzwalthert's avatar
lorenzwalthert committed
148
This is obviously a very short introduction to the template and it is in no way
lorenzwalthert's avatar
lorenzwalthert committed
149
150
151
152
153
154
155
156
157
158
159
160
161
comprehensive. To learn more about bookdown, we encourage the reader to have a
look at the [bookdown guide](https://bookdown.org/yihui/bookdown/) as well as
searching through stack overflow / Google for particular questions. In addition,
inspect the different files in this repo, in particular the ones in the rmd
directory to develop a deeper understanding of the template.

As of early 2018, this template is still in alpha testing phase, so you may
experience unexpected behavior. Please file an issue on the git repository where
you have obtained the source of this template in case you are stuck for some
time with a problem or if you found a solution to a problem you believe others
are likely to encounter in the future. Pull requests on typos are also welcome.
We want to make sure that students working this template have a great experience
writing their master thesis.
lorenzwalthert's avatar
lorenzwalthert committed
162
163
164
165

Best,

Nicola Gnecco and Lorenz Walthert
lorenzwalthert's avatar
lorenzwalthert committed
166