-
Notifications
You must be signed in to change notification settings - Fork 16
/
week 1.qmd
237 lines (182 loc) · 15 KB
/
week 1.qmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
# Markup Languages {#sec-wk1}
::: callout-tip
## Lecture Week 1
We start this course about markup languages with a deep dive into $\LaTeX$ - the master of all publication platforms. The first week's slides can be found [here](slides/lec-1.html)
Use [this meeting link](https://teams.microsoft.com/l/meetup-join/19%3ameeting_NTUzYjBkZTctMDkwOS00MjhlLWFkZmQtMmM0MzE0MjE0MDli%40thread.v2/0?context=%7b%22Tid%22%3a%22d72758a0-a446-4e0f-a0aa-4bf95a4a10e7%22%2c%22Oid%22%3a%22cc7d7fcd-73aa-4668-936a-2ca38cace0f3%22%7d) to join online to be more zeNS.
:::
---
## Introduction
Dear all,
Welcome to `MLaRPiS`. In this course you will learn a great deal about presenting and
structuring your research. We start doing so with $\LaTeX$, an environment for typesetting
documents that is particularly useful for complex content, such as graphics, tables
and equations. The result of a `LaTeX` document is a perfectly typeset `pdf` that adheres to a set of predefined rules. Many journals and preprint services in our field require `LaTeX` documents. This is why you have to learn it. The resulting flexibility and customizability when using `LaTeX` is why you should learn it.
I will take you through the basics of the scientific `LaTeX` family in a couple of walkthroughs and optional exercises. In these exercises we will treat:
1. the introduction to `LaTeX`
2. managing references with BibTeX
3. including equations
4. creating tables and displaying figures
Mastering a new *scripting* or *programming* environment is not done by simple exercises, but requires practice and repetition. Don't worry, the documents you will have to produce during this course will require you to repeat the `LaTeX` process (Wk1) and the processes and skills in other weeks over and over. However, you should work together with others and share your insights, findings and documents. We'll cover those bases in other weeks.
Of course you will run into problems and/or difficulties. In general: the internet is your friend. Chances are that someone else encountered the same issue and, most likely, a solution has been posed by an expert user. If, however, you seem stuck; please post an issue on GitHub. Collectively, we can then troubleshoot your problem and help you reach a solution. Just remember that outside of class hours, answers may take a bit longer.
`LaTeX` is extremely flexible and allows you to typeset documents with 'surgical precision'. There are however languages that allow you to create basic documents much quicker, but without the level of detail that `LaTeX` offers. One such a language is `Markdown`. This document is created with `quarto`, an implementation that goes far beyond `Markdown` and can be compiled from within `RStudio`. Of course it is required that you learn `LaTeX`, but since `Markdown` and `Quarto` allow for direct integration of `LaTeX` and `Html5`, it can be a very valuable tool. If you'd like to see the `Quarto` files (`.qmd`), feel free to browse around the course materials repository at [github.com/gerkovink/markup](https://github.com/gerkovink/markup).
Enough general intro. Let's start,
[Gerko](https://www.gerkovink.com) and [Hanne](https://hanneoberman.github.io)
---
## The `TeX` framework
TeX's structure bares close resemblance to that of the `R-project`. The core functionality can easily be expanded by users by means of packages. These packages are stored in a centralized location called the [Comprehensive TeX Archive Network (CTAN)](https://www.ctan.org/). The `TexLive` and `MacTex` distributions contain an image of many of the available packages, meaning that you will have most functionality available at all times (even offline).
Just like with `R`, `TeX` is a software implementation that requires an editor to work with. `LaTeX` is a set of macros that make `TeX` easier for the users. From this moment on, if I speak about `TeX`, I am most likely refering to `LaTeX`.
`TeX` is widely used by publishers as it give the user full control about the appearance of the document. It is designed to *write* in such a way that a minimum of attention is required by the user to typeset the document (as opposed to e.g. ~~typesetting hell~~ MS Word).
---
### Installing a `TeX` framework
If you are on Windows or Linux, I suggest you install the easy to install [ProTeXt](http://tug.org/protext/) distribution or the [TexLive distribution](http://www.tug.org/texlive/). If you are on a Mac, the [MacTex distribution](http://www.tug.org/mactex/) will give you everything you need. If you use the default installation parameters, everything you might ever need is included in these distributions. Both distributions come with an excellent (but basic) editor (`Texworks` in `Texlive` and `TexShop` in `MacTex`), but if you want to go the fancy way: there are very good alternatives. See [this page](https://en.wikipedia.org/wiki/Comparison_of_TeX_editors) for a comprehensive overview of all `TeX` editors and code editors with `TeX` capabilities.
Alternatively, you can use the online `TeX` editor [Overleaf](https://www.overleaf.com). Please pay attention to any data privacy regulations. It may not be an option for all your research endeavors.
---
## The structure of a `LaTeX` document
Open the file [`LaTeX_template.tex`](documents/Wk1/LaTeX_template.tex) from the course page. This file is a template that you may use for your documents in this course. The file [`LaTeX_template.pdf`](documents/Wk1/LaTeX_template.pdf) is the typeset version of this document (the output result). We will go through the document line-by-line:
```{r eval=FALSE}
\documentclass[10pt, fullpage, a4paper, titlepage]{article}
```
This is the line that tells `TeX` what the class of the document is and how it should be interpreted dimension-wise. In this situation, we use a 10 point font size (options are 10, 11 and 12 point), use the full page, use A4 paper size (as opposed to e.g. US letter format) and require a titlepage. The class of the document is set to be `article`. There are many deviations from the defaults. A simple online search usually gets you the option you desire.
```{r eval=FALSE}
\usepackage{graphicx, latexsym}
\usepackage{setspace}
\usepackage{apalike}
\usepackage{amssymb, amsmath, amsthm}
\usepackage{bm}
\usepackage{epstopdf}
\usepackage[]{hyperref}
```
We load these packages by default, because they sum up pretty much everything needed to begin working with `LaTeX` as a statistician. They govern devices such as graphics, mathematical notation (normal and bold face), and so on. Package `hyperref` is particularly interesting, because it allows you to set the meta-info for your document and it allows you to specify the way links and references in your document are treated. Meta-info is needed to make your documents indexable and, hence, more visible to you and everyone on the internet (if your document is on the internet).
```{r eval=FALSE}
\hypersetup{
pdftitle={title of the pdf},
pdfauthor={your name},
pdfsubject={cool stuff},
pdfkeywords={koala, chuck norris},
bookmarksnumbered=true,
bookmarksopen=true,
bookmarksopenlevel=1,
colorlinks=true,
pdfstartview=Fit,
pdfpagemode=UseOutlines,
pdfpagelayout=TwoPageRight
}
```
These are the options set for package `hyperref`. You can specify the document and author information and add keywords. The other options are also relevant, but we will not discuss them now.
```{r eval=FALSE}
%\singlespacing
%\onehalfspacing
\doublespacing
```
If you like to have a single-spaced document (commented out by `%`, so not executed), a one-and-a-half-spaced document (commented out by `%`, so also not executed) or a double-spaced document (not commented out by `%`, so executed), these options from package `setspace` are very handy.
```{r eval=FALSE}
\title{title of your paper\\ \small subtitle of your paper}
\author{name}
%\date{\today}
\date{}
```
Give titlepage information. We have set a title and a smaller subtitle. A line-break in `tex` is denoted by `\\`, although most of the times you won't need to use this as `tex` takes care of this for you in most situations. The `\small` command tells `tex` that the remainder of this textbox is to be printed in a smaller font. All functions in `tex` are preceded by `\`. So, `\author{}` is the function for author, `\date{}` the function for the date and `\today` the function that prints todays date.
Up until now, we have not done anything. No code is executed. We have just been considering the preamble of a `tex` document. To start a document, we use `\begin{document}`.
```{r eval=FALSE}
\begin{document}
```
We can then tell `tex` to print the titlepage information that we assigned (title, author, date)
```{r eval=FALSE}
\maketitle
```
and continue the document on a new page:
```{r eval=FALSE}
\newpage
```
We start the first section, labelled `abstract`:
```{r eval=FALSE}
\section*{Abstract}
text of abstract
```
Then a section called `Introduction`:
```{r eval=FALSE}
\section{Introduction}
text introduction
```
With a subsection called `sub introduction`:
```{r eval=FALSE}
\subsection{sub introduction}
text text text
```
And we end the document by the `\end{}` command.
```{r eval=FALSE}
\end{document}
```
---
::: {.callout-tip collapse="false"}
## Exercise on `TeX` classes - optional
In this optional exercise you can make yourself familiar with some of the `TeX` classes. A class is a clear definition of the type of document. There are classes for books, articles, letters, resumes, and so on. There are even classes for journals and bookseries by publishers, such as Springer, Elsevier, CRC and Sage.
Classes are usually linked to style files, the files that define the looks of a document. Have a look at the [`LaTeX background`](documents/Wk1/LaTeX background.zip) archive if you'd like to know more about how classes and styles make documents look different. It is important to realize that not every document by default accommodates for the type of content. Some classes make some content look ridiculous. Imagine printing an A5 document on an A1 canvas, or submitting a job application as a statistical journal manuscript. Choosing a proper class is therefore essential. The good thing with `LaTeX` is that different classes can easily be applied to the same content.
---
### Exercise
Use the text in the [`Virgil - Aeneid.txt`](documents/Wk1/Virgil - Aeneid.txt) file as the content for the following five documents:
1. An article with 12 point font size on US letter paper.
2. A book with 10 point font size on A4 paper.
3. A book with 10 point font size on A5 paper.
4. A minimal document with 12 point font size on A5 paper.
5. A letter with 12 point font size on A5 paper.
You just need to specify the paragraphs correctly. The solution to this exercise can be found [here](documents/Wk1/Answers_box1.zip)
:::
---
## Getting jumpstarted with `LaTeX`, bibliographies, citing and compiling
I have created many documents and walkthroughs about `TeX` and `LaTeX`, most of which are already outdated.
- [Bibliographies in `LaTeX`](https://www.gerkovink.com/oldmarkup/Archive/2019/index.html#week-1) with [Answers](https://www.gerkovink.com/oldmarkup/Archive/2019/Wk1/Solutions.zip)
- [Figures and Tables](https://www.gerkovink.com/oldmarkup/Archive/2019/Wk3/Exercise_4.html) with [Answers](https://www.gerkovink.com/oldmarkup/Archive/2019/Wk3/Answer/2.%20Solution%20in%20Tex.tex)
- [Mathematical notation and presentations](https://www.gerkovink.com/oldmarkup/Archive/2019/Wk2/Exercise%203/Exercise_3.html) with [Answers](https://www.gerkovink.com/oldmarkup/Archive/2019/Wk2/Solution.zip)
The folks at [Overleaf](https://www.overleaf.com/learn/latex/Learn_LaTeX_in_30_minutes) have provided a much more up-to-date series. I suggest that you go throught the following chapters:
1. [Learn `LaTeX` in 30 minutes](https://www.overleaf.com/learn/latex/Learn_LaTeX_in_30_minutes)
2. Because most of you are new to LaTeX, I suggest you learn `biblatex`: [Bibliography management with biblatex](https://www.overleaf.com/learn/latex/Bibliography_management_in_LaTeX)
3. [Choosing a `LaTeX` compiler](https://www.overleaf.com/learn/latex/Choosing_a_LaTeX_Compiler)
4. [Mathematical notation in `LaTeX`](https://www.overleaf.com/learn/latex/Mathematical_expressions)
If - like me (Gerko) - you still come across new notation conventions and would like to know how to write expressions with it in `LaTeX`: use [`detexify`](https://detexify.kirelabs.org/classify.html) to draw the symbol and obtain the `LaTeX` code.
---
## Further Reading
Chances are that you will struggle at some point with a problem or a compilation error that will lead to much frustration. The internet is your friend: search for the error or problem and you will most likely find the solution. Additionally, these are good resources to study:
- [`LaTeX` Wikibook](https://en.wikibooks.org/wiki/LaTeX)
- [Math symbols cheatsheet](https://www.gerkovink.com/oldmarkup/Archive/2019/Wk2/Exercise%203/LaTeX%20background/Math%20in%20LaTeX/Math%20Symbols.pdf)
- [Short math guide](https://www.gerkovink.com/oldmarkup/Archive/2019/Wk2/Exercise%203/LaTeX%20background/Math%20in%20LaTeX/short-math-guide.pdf)
- [The Not So Short Introduction to `LaTeX` ](http://tug.ctan.org/info/lshort/english/lshort.pdf)
Even though the internet may hold most answers to your problem, please don't struggle for too long. [Post an issue on GitHub](https://github.com/gerkovink/markup).
---
## Exercise for this week
Create a document that contains [1-5] and then change the document with [6]. Submit both documents as well as the `LaTeXdiff`.
1. A titlepage
2. An equation
3. A section and a subsection
4. The resulting figure and table with captions from [this file](documents/Wk1/Recreate This File.pdf) to be generated by the below code:
```{r eval=FALSE}
#load package lattice
library(lattice)
library(xtable) # generate the LaTeX code for tables
#fix the random generator seed
set.seed(123)
#create data
data <- rnorm(1000)
#plot histogram
histogram(data)
#plot density
densityplot(data^12 / data^10, xlab = expression(data^12/data^10))
#plot stripplot
stripplot(data^2, xlab = expression(data^2))
#plot boxplot
bwplot(exp(data))
#matrix with all data used
data.all <- cbind(data = data,
squared1 = data^12 / data^10,
squared2 = data^2,
exponent = exp(data))
```
5. The text from [this AI-generated fairytale](documents/Wk1/Clara.txt)
6. Also create another document with `LaTeXdiff` version where the text in fairytale is replaced by [this slight variation on the same fairytale](documents/Wk1/Peter.txt)
---
### Handing in the exercise
1. Fork the template repository detailed in @sec-deliv.
2. Add your files to the respective folder in the `dev` branch. Not in the main branch!
3. Share your repository link as an issue in the [course repository](https://github.com/gerkovink/markup/issues).
If you know how to use `git`, go ahead. If you don't, no panic. We'll cover that in week 3. In the meantime you can use the `> add file` functionality on GitHub as illustrated below.
