---
title: "Get started"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Get started}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

This guide takes you from a blank computer to your first lesson. It assumes no prior experience with R. Set aside about fifteen minutes the first time.

## 1. Install R and RStudio

Both are free.

- **R** is the engine. Download it from [CRAN](https://cran.r-project.org/) and install it like any other program.
- **RStudio** is the comfortable workspace you run R in. Download [RStudio Desktop](https://posit.co/download/rstudio-desktop/) and install that too.

Open RStudio once both are in place. You will see a panel called the **Console**, with a `>` prompt. That is where the commands below go: type or paste a line, then press Enter.

## 2. Install the course

The course is an R package called `r4clinstats`. It is not on CRAN, the server R looks in by default, so the command below names the course's own server alongside it. Paste the whole thing into the Console, all four lines together:

```r
install.packages("r4clinstats",
                 repos = c("https://apsmunro.r-universe.dev",
                           CRAN = "https://cloud.r-project.org"),
                 dependencies = TRUE)
```

Keep the `dependencies = TRUE` part. Without it you get the course but none of the packages it runs on.

This takes a few minutes the first time, and red progress text along the way is normal.

Near the end R will note that one package, `gradethis`, is not available. That is expected and step 3 installs it. `gradethis` is the part that marks your answers, and it is the one piece of the course that is not on CRAN, so it comes from elsewhere and is fetched on its own rather than with everything else.

## 3. Check your setup

Load the package and run the built-in check:

```r
library(r4clinstats)
check_setup()
```

This confirms the install worked. It looks at your R version, where your packages are stored, and whether your network can reach the package servers. If step 2 went cleanly you will see a column of `[OK ]` and nothing to do. If anything is missing, `check_setup()` names it and offers to install it, so say yes to any prompts. This is where `gradethis` arrives, so expect it to install something the first time you run it.

You will also meet commands written as `r4clinstats::check_setup()`. The two colons look stranger than they are: `package::function()` is R's way of saying "this function, out of this package", and it saves loading the package first. It is a command to type, not a web address, and there is nothing to click or search for.

## 4. Start learning

```r
learn()        # list the lessons
learn("m0")    # open the first one
```

`learn()` lists the lessons and hands you back the `>` prompt. To open one, type `learn()` with the lesson's id in quotes: `learn("m0")` for the first, `learn("m10")` for Describing data. It opens in your browser, where you read a little, run real code in the boxes, and get feedback as you go. Start at **m0** and work along in order.

That is everything. The rest you learn by doing.

## Keep the crib sheet open

One habit worth starting with. Open the [Crib sheet](crib-sheet.html) in a second browser tab and leave it there while you work. It lists every function the course teaches, grouped by the job you want done, with the lesson each came from.

You will want it from about Lesson 4 onwards, when you start needing something taught two lessons ago. A running lesson keeps hold of your R console, so you cannot look things up there, and hunting back through earlier lessons breaks your flow.

## Finishing a lesson

This one catches nearly everyone the first time. While a lesson is open it holds on to your R console, so the console shows no `>` prompt and looks frozen. Closing the browser tab does not release it, because the lesson is running in R, not in the browser.

To finish with a lesson, click into the **Console** and press `Esc`, or click the red stop button at the top right of the Console pane. The `>` prompt comes back, and you are free to move on:

```r
learn()        # list the lessons again
learn("m3")    # open a particular lesson
```

Every lesson ends with a short reminder of this, so there is nothing to memorise.

## If something goes wrong

A few things trip people up. None of them are your fault.

**"No tutorials found for package 'r4clinstats'."** Your R session is holding an older view of the package. In RStudio, choose **Session ▸ Restart R**, then run `library(r4clinstats)` and try `learn("m0")` again.

**Install fails on a work or managed computer.** Some workplaces store your documents in OneDrive, or lock down where programs may write, which R does not get along with. Run this once:

```r
library(r4clinstats)
use_local_library()
```

It sets up a private folder for your R packages in a location that always works, then asks you to restart R. After restarting, repeat step 2.

**A package will not install from CRAN.** Behind some hospital and university firewalls, `check_setup()` reports what it cannot reach and names the fix, usually pointing R at Posit's package mirror.

More problems, and their fixes, are on the [Troubleshooting page](troubleshooting.html), written for hospital and university computers. Still stuck? Open an issue at the [project page](https://github.com/apsmunro/r4clinstats/issues) and describe what you saw.