assignment_template.rmd

---
title: "BDA - Assignment X"
author: "Anonymous" # The report should be submited anonymously.
output: 
  pdf_document: 
    toc: yes
    toc_depth: 1
urlcolor: blue
---

# Introduction

This is a template with format instructions for Assignments in the Bayesian Data Analysis course at Aalto University. R markdown is a convenient way of writing exercise reports by combining text and R code using markdown syntax. To create your assignment, remove the formatting instructions and use this file as a template. Keep the header (the first lines of this file between two lines of ---) as it sets the author name to be anonymous, and you can set the title to match the assignment number.

R markdown makes it easy to make a structured document with section and subsection titles, textual explanations, equations, code and figures in logical order. When you make changes to the code and re-run the notebook or "knit" (render) it to PDF, the relevant code is re-run and the figures and results are updated without need to copy and past (which is probe to errors).

To edit R Markdown you can use any editor, but RStudio's visual R markdown editor is probably easiest, as you immediately see how it looks and can choose formatting (e.g. section headings, bolding, lists, figures, etc.) from the toolbar.

More information on how to use markdown, see <https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet> and more information on R markdown can be found at <https://www.rstudio.com/wp-content/uploads/2015/02/rmarkdown-cheatsheet.pdf>.

Also, *R Markdown: The Definite Guide*, an extensive book on R Markdown can be found at <https://bookdown.org/yihui/rmarkdown/>.

**Note** The report should be anonymous and submitted to [peergrade.io](peergrade.io) as `assignmentX.pdf`. If you have problem with creating a PDF file directly from R markdown, start by creating an HTML file and the just print the HTML to a PDF. You may also use other software to create the report pdf, but follow the general instructions in this file (see the [pdf version this file](https://github.com/avehtari/BDA_course_Aalto/blob/master/templates/assignment_template.pdf)).

```{r setup, include=FALSE}
# This chunk sets echo = TRUE as default, that is print all code.
# knitr::opts_chunk$set can be used to set other notebook generation options, too.
# include=FALSE inside curly brackets makes this block not be included in the pdf.
knitr::opts_chunk$set(echo = TRUE)
```

# Loaded packages

Below are examples of how to load packages that are used in the assignment. After installing the `aaltobda` package, you need to also load it in the beginning of every notebook where you want to use it with `library()` function:

```{r}
# To install aaltobda, see the General information in the assignment.
library(aaltobda)
```

# Including source code

In general, all code needed to produce the essential parts needs to be included, so that it is possible to see, for peer reviewers (and TAs), where errors may have happened.

You can always look at the open rubrics to see how and what is asked for in each exercise.

Try to avoid printing an excessive amount of code and think about what is essential for showing how did you get the result.

Write clear code. The code is also part of your report and clarity of the report affects your score. If the code is not self-explanatory, add comments. In a notebook, you can interleave explaining text and code.

If in doubt additional source code can be included in an appendix.

# Format instructions

All exercises in the assignment should start with a header fully specifying that it is exercise X, as (in rmd use \#):

# Exercise 1)

Subtasks in each assignments should be numbered and use header (in rmd use \##).

## a)

For each subtask include necessary textual explanation, equations, code and figures so that the answer to the question flows naturally. You can think what kind of report would you like to review, and what kind of information would make it easier where there is error (if there are errors).

# Code

We can easily add R code as chunks in the following way:

```{r}
5 + 5
```

This R code is evaluated when running the notebook or when rendering to PDF.

If you want to show and run the code, but the output is very long or messy and you prefer to hide the output from the rendered report you can use option results='hide'. This is useful especially later as Stan may output many lines.

```{r, results='hide'}
5 + 5
```

If you want to use some code in the notebook, but think it's not helpful for the reviewers you can exclude it from the generated PDF with option `include=FALSE`. You will see the next block in rmd, but not in the generated PDF.

```{r, include=FALSE}
5 + 5
```

# Plots

Include plots, where we can specify the width and height of the figure.

```{r drowning1, fig.height=3, fig.width=4, fig.cap="Number of drownings per year."}
data("drowning") # Access the data in aaltobda package
plot(drowning$year, drowning$drownings)
```

Or using `qplot()` from `ggplot2` package:

```{r drowning2, fig.height=3, fig.width=4, fig.cap="Number of drownings per year with qplot."}
library(ggplot2)
# see themes at https://ggplot2.tidyverse.org/reference/ggtheme.html
theme_set(theme_classic())
qplot(drowning$year, drowning$drownings)+
  labs(x="Year", y="Drownings")
```

Or using ggplot from ggplot2 package with pipe `|>`

```{r drowning3, fig.height=3, fig.width=4, fig.cap="Number of drownings per year with ggplot."}
drowning |>
  ggplot(aes(x=year, y=drownings)) + 
    geom_point() +
    labs(x='Year', y='Number of drownings')
```

Or using ggplot from ggplot2 package without pipe. In the following code bloc `eval=FALSE` is used to show the code, but not display the same plot again.

```{r, eval=FALSE, fig.height=3, fig.width=4}
ggplot(data=drowning, aes(x=year, y=drownings)) + 
  geom_point() +
  labs(x='Year', y='Number of drownings')
```

# Images

You can include an existing image (e.g. scanned copy of pen and paper equations).

![Parts of Bayesian workflow](bayes_workflow.jpg){#fig-workflow width="350"}

# Equations

You can write equations using LaTeX syntax, or you can include them as images if, for example, you use Microsoft Equations.

In Markdown, equations can easily be formulated using LaTeX in line as $f(k) = {n \choose k} p^{k} (1-p)^{n-k}$. Or use the math environment as follows:

$$
\begin{array}{ccc}
x_{11} & x_{12} & x_{13}\\
x_{21} & x_{22} & x_{23}.
\end{array}
$$

The above example illustrated also multicolumn 'array'. Alternative way to make multiline equations with alignment is to use 'aligned' as follows;

$$
\begin{aligned}
y & \sim \mathrm{normal}(\mu,1) \\
\mu & \sim \mathrm{normal}(0,1).
\end{aligned}
$$

If you are new to LaTeX equations, you could use the [latext4technics](https://www.latex4technics.com/) equation editor to create LaTeX equations to include in the report.

More information on using LaTeX in R markdown can be found in 2.5.3 in [R Markdown: The Definite Guide](https://bookdown.org/yihui/rmarkdown/).

A short introduction to equations in LaTeX can be found at <https://www.overleaf.com/learn/latex/Mathematical_expressions>.

# Tables

You can use `knitr::kable` to add formatted tables. Captioning and labeling works similarly as with plots.

```{r tbl-drownings, tbl.cap="First five rows of the drowning data."}
knitr::kable(head(drowning))

```

Compare this to raw output:

```{r drowning}
# Raw output
head(drowning)

```

# Language

The language used in the course is English. Hence the report needs to be written in English.

# Jupyter Notebook and other report formats

You are allowed to use any format to produce your report, such as Jupyter Notebook, as long as you follow the formatting instructions in this template.