primer.tutorials/README.Rmd at main · PPBDS/primer.tutorials · GitHub

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
---
output: github_document
---

<!-- README is generated from README.Rmd, edit ONLY this file if needed. But, after you edit it, you NEED TO KNIT IT BY HAND in order to create the new README.md, which is the thing which is actually used. -->

```{r, include = FALSE}

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/README-",
  out.width = "100%"
)
```

# Tutorials for *Primer for Bayesian Data Science* <img src="man/figures/ulysses_hex_tutorials.png" align = "right"  width="160">

<!-- badges: start -->
[![R build status](https://github.com/PPBDS/primer.tutorials/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/PPBDS/primer.tutorials/actions)
<!-- badges: end -->


## About this package

`primer.tutorials` provides the tutorials used in the *[Primer for Bayesian Data Science](https://ppbds.github.io/primer)*.


## Installation

You can install the development version from [GitHub](https://github.com/) with:

``` r
# install.packages("remotes")
remotes::install_github("PPBDS/primer.tutorials")
```

For suggested updates during installation, though you do not have to have the latest versions of packages, it is recommended you update them. For packages that need compilation, feel free to answer "no".

Then **restart your R session** or **restart RStudio**.

## Accessing tutorials

In order to access the tutorials, start by loading the package.

``` r
library(primer.tutorials)
```

&nbsp;

You can access the tutorials via the Tutorial pane in the top right tab in RStudio.

If any of the following is happening to you
<ul>
<li>Cannot find the Tutorial pane</li>
<li>Cannot find a tutorial called "Getting Started"</li>
</ul>

Then **remember to restart your R session** after installing the package.

Click “Start tutorial”. If you don’t see any tutorials, try clicking the “Home” button – the little house symbol with the thin red roof in the upper right.

&nbsp;

```{r, echo = FALSE, out.width='75%', fig.align='center'}
knitr::include_graphics("man/figures/tutorial_pane.gif")
```

&nbsp;

In order to expand the window, you can drag and enlarge the tutorial pane inside RStudio. In order to open a pop-up window, click the "Show in New Window" icon next to the home icon.

You may notice that the Jobs tab in the lower left will create output as the tutorial is starting up. This is because RStudio is running the code to create the tutorial. If you accidentally clicked "Start Tutorial" and would like to stop the job from running, you can click the back arrow in the Jobs tab, and then press the red stop sign icon. Your work will be saved between RStudio sessions, meaning that you can complete a tutorial in multiple sittings. Once you have completed a tutorial, follow the instructions on the tutorial `Submit` page and (if you're a student) submit the downloaded `rds` file as instructed.

## Working environments and repo setup

**The primary supported environment is VS Code on GitHub Codespaces, started from the [`PPBDS/codespace-starter`](https://github.com/PPBDS/codespace-starter) devcontainer.** The tutorial text is written assuming this setup. R, Quarto, and all the dependencies are installed in the container, so there is nothing to install on your own machine. Two local alternatives — Positron and VS Code running on your own machine — are supported but require you to install R, Quarto, and the tutorial packages yourself.

**Before you start any exercise tutorial, create a GitHub repo named after that tutorial.** Use the tutorial's *name*, not its number — `nhanes`, `trains`, `colleges`, `biden`, `shaming`, `nes`, `ces`, `governors`, `stops`. The repo should be **empty**: do *not* check the "Add a README" box, do *not* add a `.gitignore`, do *not* add a license. The tutorial walks you through creating those files once you're inside the repo.

### Starting a tutorial on Codespaces (primary)

Go to [`PPBDS/codespace-starter`](https://github.com/PPBDS/codespace-starter), click **Use this template → Create a new repository**, and name the new repository after the tutorial you're about to do (e.g. `nhanes`). Leave all the optional boxes unchecked — you want an empty copy of the template, not one with a README/gitignore/license added on top. Once the repo is created, open it in a Codespace from the **Code → Codespaces** button on the repo page. The dev container boots with R and Quarto already configured; proceed to Exercise 2 of the tutorial inside that Codespace.

### Starting a tutorial locally (Positron or VS Code)

If you prefer to work on your own machine, install R, Quarto, and `primer.tutorials` (see the Installation section above). Then create an empty GitHub repo named after the tutorial (no README, no `.gitignore`, no license), clone it to your machine with your usual workflow (`File → New Folder from Git` in Positron; `git clone` followed by opening the folder in VS Code), and open the repo in your editor. Proceed to Exercise 2.

Regardless of mode, by the time you reach Exercise 2 you should be sitting inside an empty repo whose name matches the tutorial.

## Re-installation

Since these tutorials are constantly being updated, it is likely that updates will come out as you use these tutorials.

If you wish to stay up-to-date with the latest version, it is recommended that you regularly re-install this tutorial package by running the following 2 lines of code in your **R Console**:

```r
remove.packages("primer.tutorials")
remotes::install_github("PPBDS/primer.tutorials")
```

For version updates for dependency packages please follow the same considerations as discussed above in the Installation section.

And remember to **RESTART YOUR R SESSION** after you re-installed the package.