Four ways to use R

≈ 10 min

R is both a programming language and a program that runs your code. You can work with it in several ways – typing into a console, writing scripts in an editor, writing documents and notebooks, or running commands in a terminal – and the way you choose affects what you can do and what record you keep of your work.

What’s in the workbench

The workbench on the right gives you four different ways of using R. Behind each of them is the same version of R (R 4.6, running in your web browser), but each one suits a different kind of work:

R consoleThe standard R console. You type a command and R answers straight away. It is quick, but apart from the history of your commands, nothing is kept.

RStudioAn editor for scripts that you write, run and keep, with your data, plots, help pages and files alongside.

Documents and notebooksR Markdown, Quarto, R Notebooks and Jupyter notebooks, which combine text, code and results in a single file.

TerminalRunning R from the command line with Rscript or R CMD BATCH, without any window at all.

In this practical you will do a small piece of analysis in each of them, so that you can see what each approach is good for and where it falls short. The data are measurements of 344 penguins from three islands in the Palmer Archipelago, Antarctica. You will find them in your files as ~/data/penguins.csv (there is also an Excel version, penguins.xlsx), and the same data are built into R 4.6 as a dataset called penguins.

How this page works

The instructions are on the left and the workbench is on the right. Use the tabs along the top of the workbench to move between the different ways of using R. The Files tab shows your files, and the AI tab has an AI assistant that you can ask about R.
Each activity is a list of steps. When you complete a step, it is ticked automatically and marked ✓ spotted, but you can also tick steps yourself. Buttons such as type the code in for you, and you then press Enter to run it.
Your answers and files are saved in this web browser, on this computer. To keep a copy, use My answers to download your answers and My files to download all your files as a .zip file. Do this before you clear your browser’s data or move to a different computer.
The first time you open a tab that uses R, R itself has to be downloaded (about 30 MB), so it may take a moment to start. Any packages you install are also only downloaded the first time.

Each tab has its own R session

Just as on your own computer, the R console, RStudio, the notebook and each command you run in the terminal all use separate R sessions. An object you create in one of them doesn’t exist in the others. What they do share is your files (they all use the same home folder, ~) and any packages you install.

AI tools and your data

Anything you type into the AI assistant (and your code, if you allow it) is sent to an AI company. Never paste personal data or patient data into an AI tool.

Find your way around

Open the R console tab and wait until R shows its prompt, >, which means it is ready for a command.
Type 1 + 1 and press Enter.
Have a look at the Files tab . Find data/penguins.csv and click on it to see the data.

The R console

≈ 15 min

The console is the quickest way to try things out in R, but it is also the way that keeps the least record of what you did.

The R console tab shows R as you get it when you install it on your own computer. There is a single window, the console, where you type a command after the prompt (>) and R prints its answer underneath. Plots, help pages and data each open in a separate window.

Talking to R

Commands and objects

Type x <- c(3, 8, 1) . Nothing is printed, because R has simply created an object called x. Now type mean(x) to calculate its mean.
Press ↑ to bring back your last command, change mean(x) to median(x) and press Enter.
Type sum(x , leaving out the closing bracket, and press Enter. R shows a + instead of the usual prompt, because it is waiting for you to finish the command. Type ) and press Enter.

Assignment and printing

x <- value creates an object called x (or replaces it, if it already exists) and doesn’t print anything. A command that isn’t an assignment prints its result. The [1] at the start of a line of output tells you that the line begins with the first value of the result. If R is taking too long, or you get a + prompt by mistake, press Esc to stop and get back to the normal prompt.

Looking at the penguin data

Look at the data

head(penguins) prints the first six rows of the data, and summary(penguins$body_mass) summarises a single column.
View(penguins) opens the data in a separate window, where you can sort the rows by any column or search for a value.
plot(body_mass ~ flipper_len, data = penguins) draws a scatter plot in a graphics window. Try moving the window and changing its size.
?mean opens R’s help page for the mean function. Find out what its na.rm argument does.

mean(penguins$body_mass) returns NA. Why is that, and how can you calculate the mean of the masses that were actually measured?

Two of the penguins have no body mass recorded (NA stands for a missing value), and R treats the mean of a set of numbers that includes a missing value as unknown. mean(penguins$body_mass, na.rm = TRUE) removes the missing values before calculating the mean, which is about 4202 g.

Quitting R, and what is kept

Everything you create in R is held in its memory, which is called the workspace. When you quit R, the workspace is lost unless you choose to save it.

Save the workspace

Type q() . R asks Save workspace image? [y/n/c]:, and you answer y for yes.
Click Start R again in the console. As it starts, R tells you [Previously saved workspace restored].
Type x . Your object is back, because R saved the workspace in a file called ~/.RData and loads that file whenever it starts.

You created x, quit R without saving the workspace, and then started R again. What happens when you type x?

Error: object 'x' not found The value you gave x NULL

What is the console good for? And if you come back next week, what will it not be able to tell you about how you got your results?

The console is good for trying things out quickly, checking a value or reading a help page, because you get an answer straight away. However, it doesn’t keep a tidy record of your work. The history contains every line you typed, mistakes included, and a saved workspace contains objects but not the commands that created them. So next week you may have results that you cannot easily reproduce.

Scripts in RStudio

≈ 20 min

Writing your commands in a script lets you run them as you go, and gives you a record from which you can reproduce your results at any time.

RStudio is an integrated development environment (IDE) for R. Alongside R’s console, it gives you an editor for your scripts and documents (the Source pane, at the top left), a list of the objects in R’s memory (the Environment pane), and panes for your files, plots, packages and help pages, as well as a viewer for web pages. The RStudio tab of the workbench is modelled closely on RStudio, so what you learn here also works in the real program.

A separate R session

RStudio’s Console is a different R session from the one in the R console tab, so the x you created there doesn’t exist here. Everything you run in RStudio, whether it is a single line, a chunk or a whole script, runs in the R session shown in RStudio’s Console.

Writing a script

A script is a plain text file of R commands, saved with the extension .R. While you are working out your analysis, you can run the script one line at a time, and once it works you keep it so that you can run it again whenever you need to.

scripts/penguins.R

# Penguins: body mass by species
penguins <- read.csv("data/penguins.csv")
str(penguins)

# the mean body mass of each species (missing masses left out)
mass <- aggregate(body_mass ~ species, data = penguins, FUN = mean)
mass

boxplot(body_mass ~ species, data = penguins,
        ylab = "Body mass (g)", col = "lightblue")

Create this file saves the script in your files and opens it in RStudio’s Source pane.

Run a script, line by line

Click Create this file above. The script opens in RStudio.
Put the cursor on the line with read.csv and press Ctrl+Enter (⌘+Enter on a Mac). The line is sent to the Console and run, and penguins appears in the Environment pane.
Keep pressing Ctrl+Enter until you reach the end of the script. A command that spans several lines, such as the boxplot( command, is run as a whole. The plot appears in the Plots pane.
In the Environment pane, click the ▶ next to penguins to see its columns, and click the table icon to view the data.

Your script is a record of your analysis

Restarting R clears everything from its memory. If your work is in a script, that doesn’t matter: run the script again and all your objects and plots are recreated, exactly as before.

Start again from your script

Choose Session ▸ Restart R (Ctrl+Shift+F10). The Environment pane is now empty.
Click Source at the top of the script. RStudio runs source("~/scripts/penguins.R"), which runs the whole script in one go.
Add a line at the end of the script that counts the penguins of each species: table(penguins$species). Save the script (Ctrl+S) and run the new line.

Let RStudio write the code for you

RStudio’s Import Dataset button (in the Environment pane) lets you read in a data file using a dialog, and it shows you the R code that it runs to do so. Copy that code into your script, so that reading in the data becomes part of your script too.

Import a dataset

In the Environment pane, choose Import Dataset ▸ From Excel… and use Browse… to find data/penguins.xlsx. Look at the preview and at the code underneath it, then click Import. (The first time you do this, RStudio needs to install the readxl package.)

You have both a script and a saved workspace (.RData). A colleague finds a mistake in the data file, and you correct it. Which of the two will give you corrected results, and why?

The script. When you run it again, every result is recalculated from the corrected file. The saved workspace only holds the old results, and nothing in it tells you how they were produced. (This is why many people set RStudio never to save or restore .RData files, under Tools ▸ Global Options.)

If you have time: a Shiny app

RStudio can also run Shiny apps. These are interactive web pages written in R, in which controls such as sliders and menus change what R calculates and plots. File ▸ New File ▸ Shiny Web App… creates an example app in a new folder, and Run App starts it in the Viewer pane. While the app is running the Console is busy, so click Stop (or press Esc) when you have finished with it.

Run a Shiny app

Create a Shiny web app and run it. Move the slider and watch the plot change.

Documents: R Markdown and Quarto

≈ 20 min

An R Markdown or Quarto document keeps your text, code and results together in one file, and the whole document is run again from the beginning every time you knit it.

A report contains text, code and results, such as tables, plots and numbers quoted in sentences. In an R Markdown document (.Rmd), or in its successor Quarto (.qmd), you write all of these in one file: the text in Markdown, and the code in chunks. When you knit the document, the code is run and the whole thing is turned into a web page. (On a computer with the necessary software installed, it can also produce a PDF or Word document.)

Writing an R Markdown document

Write and knit a report

In RStudio, choose File ▸ New File ▸ R Markdown…. Enter Penguin report as the title and your name as the author, leave the output format as HTML, and click OK.
Save the document (Ctrl+S), typing reports/penguins.Rmd as the file name.
Run one of the chunks by clicking the green ▶ at the right-hand end of its first line. Its output appears in the document, directly underneath the chunk.
Click Knit. The first time you do this, RStudio needs to install the knitr and markdown packages. The finished report opens in the Viewer pane and is saved as reports/penguins.html.

Knitting starts with an empty R session

When you click Knit, the document is run from the beginning in a brand new R session, not in the R session behind RStudio’s Console. This means the document has to create or read in everything it needs by itself. That is what makes a knitted report trustworthy: it shows that the code, exactly as written, produces the results in the report.

Break it on purpose

Create an object called penguin_colours in RStudio’s Console: .
Add a new chunk to the report (with the +C button, or Ctrl+Alt+I) containing barplot(table(penguins$species), col = penguin_colours). Run the chunk with its ▶ button, and you will see that it works.
Now click Knit. This time knitting stops with the error object 'penguin_colours' not found, which you can see in the Background Jobs tab. Fix the report so that it creates penguin_colours itself, and knit it again.

Running the chunk with ▶ worked, but knitting failed. Explain why.

The ▶ button runs the chunk in the R session behind RStudio’s Console, where you had already created penguin_colours by hand. Knit runs the whole document in a new, empty R session, so penguin_colours only exists if the document itself creates it. A report that knits successfully contains everything needed to produce its results.

R Notebooks and Quarto

An R Notebook is an R Markdown document that you run chunk by chunk as you work. Each time you save it, RStudio also saves a web page next to it (.nb.html) containing the text, the code and the outputs exactly as they are at that moment, without running anything again. Quarto documents are written in much the same way as R Markdown, and the Render button does the same job as Knit. Quarto also works with other languages, such as Python and Julia.

Try them both

Choose File ▸ New File ▸ R Notebook. Run its chunk, save the notebook as reports/notes.Rmd, and click Preview.
Choose File ▸ New File ▸ Quarto Document… and click Create. Save the document as reports/quarto.qmd and click Render.

You ran the chunks of an R Notebook in the order 3, 1, 2 and then saved it. What does its .nb.html file show?

The outputs as they were when you ran the chunks in the order 3, 1, 2 The outputs you would get by running the chunks from the beginning No outputs, because they are generated when someone opens the page

Jupyter notebooks

≈ 15 min

A notebook keeps cells of code together with their output in a single file. Notebooks are easy to share, but they are also easy to run in the wrong order.

A Jupyter notebook (.ipynb) is made up of cells. There are code cells, whose output appears underneath them, and text cells written in Markdown. Jupyter started out with Python, but with an R kernel, as here, the code cells contain R. The outputs are saved in the notebook file, so other people can read a notebook without running it, for example on GitHub or in JupyterLab, VS Code or Google Colab.

Another separate R session

The notebooks use their own R session, which is separate from the ones in the R console tab and in RStudio. All the notebooks in this workbench share that one R session, and its working directory is the folder that the notebook is in.

Running cells

Run some cells

Open the Notebook tab . A new, empty notebook has been created for you in ~/notebooks.
In the first code cell, type head(penguins) and press Shift+Enter. The data appear as a table. The number in [1] next to the cell shows that this was the first cell R ran.
In the next cell, type hist(penguins$flipper_len, main = "Flipper length", xlab = "mm") and press Shift+Enter.
Add a text cell (+ Text) and write a sentence about what the histogram shows. Press Shift+Enter to display it as formatted text.

Running cells out of order

You can run the cells of a notebook in any order, and you can change a cell after it has run. When you do, the output shown under a cell may come from code that is no longer there.

Hidden state

Create a cell containing n <- 10 and run it. Below it, create a cell containing n * 2 and run that too. The result is 20.
Change the first cell to n <- 1000, but do not run it. Run only the n * 2 cell. The answer is still 20, so the notebook now shows code and a result that don’t match.
Open the kernel menu (the R button at the top) and choose Restart R and run all cells. Every cell is run again, from top to bottom, in a new R session.
Click Download and choose Jupyter notebook (.ipynb). The downloaded file can be opened, with its outputs, in Jupyter, JupyterLab, VS Code or Colab.

Why is it risky to run a notebook’s cells out of order, and what habit protects you from the problem?

The outputs in the notebook may not come from the code you can see, because each cell’s result depends on whatever was run before it, in whatever order, including cells that have since been changed or deleted. The habit that protects you is to restart R and run all the cells from the top (Restart R and run all cells) before you share a notebook or rely on its results. This is the same check that knitting does automatically for an R Markdown document.

An R Markdown document (.Rmd) and a Jupyter notebook (.ipynb) can both contain text, code and results. Give one practical difference between the two kinds of file.

An .Rmd file is plain text and contains no outputs, so it is easy to read, to compare with other versions and to keep under version control (for example with Git); its results are only produced when it is knitted. An .ipynb file is in JSON format, with the outputs stored inside it (plots are stored as long strings of base64 text). This means it shows its results without being run, but the differences between two versions are hard to read.

Running R from the terminal

≈ 15 min

Rscript, R CMD BATCH and R let you start R with a command. This is how R is used on servers and computing clusters, in pipelines, and for any job that you need to run many times.

You don’t need a window to use R. Servers and computing clusters, where long analyses are often run, usually have no screen at all: R is started with a command, runs a script and then stops. The Terminal tab is a Linux-style terminal (bash) with R’s commands available: Rscript and R CMD BATCH run scripts, and R starts R’s console inside the terminal.

Rscript

Run your script

Open the Terminal tab and type ls scripts . The script you wrote in RStudio is there, because every tab works with the same files.
Run it with Rscript scripts/penguins.R . Anything the script prints appears in the terminal. The plot has no window to go to, so R saves it in a file called Rplots.pdf instead (ls -l Rplots.pdf ).

scripts/count.R

# How many penguins of a species? The species comes from the command line:
#   Rscript scripts/count.R Gentoo
args <- commandArgs(trailingOnly = TRUE)
species <- if (length(args) > 0) args[1] else "Adelie"

penguins <- read.csv("data/penguins.csv")
n <- sum(penguins$species == species)
cat(species, ":", n, "penguins\n")

This script uses commandArgs() to read the name of a species from the command line.

Scripts that take arguments

Create scripts/count.R with the button above.
Run Rscript scripts/count.R Gentoo , then try it again with Chinstrap instead of Gentoo.
Count all three species with a single line of bash: for s in Adelie Chinstrap Gentoo; do Rscript scripts/count.R $s; done
When a script hits an error it stops, and its exit status tells you that something went wrong: Rscript -e 'mean(no_such_thing)'; echo "exit status: $?"

Exit status

Every program tells the shell how it finished by returning a number called its exit status: 0 means success, and anything else means that something failed. In bash, $? holds the exit status of the last command. A script that runs several steps can be told to stop at the first failure (with set -e), rather than carrying on with results that were never produced.

R CMD BATCH and R

Keep a record of a run

R CMD BATCH scripts/penguins.R doesn’t print anything in the terminal. Instead, everything (the commands, their output and how long the run took) is written to a file called penguins.Rout. Have a look at it with cat penguins.Rout .
R -q starts R’s console inside the terminal (-q leaves out the welcome message). Try summary(penguins$bill_len), then quit with q() and answer n when R asks whether to save the workspace.

Describe two situations in which you would run R with Rscript rather than in RStudio.

For example: on a server or computing cluster that has no screen, such as a job submitted to a queue; for a long analysis that runs overnight; to run the same script on many inputs, such as a loop over files or species; as one step in a pipeline, or a scheduled job that runs without anyone watching; or simply to check that a script runs on its own, from start to finish, in a fresh R session.

Which way, when?

≈ 10 min

The same R can be used in five different ways. This chapter compares them and shows how they fit together.

Each way of using R keeps a different kind of record, and each suits a different kind of job. In practice you will often move between them: you might try out a command in the console, add it to a script, knit the analysis into a report, and finally run it on a server with Rscript.

Way of using R	What is kept	Good for
R console	Nothing, apart from the command history and, if you save it, the workspace	Trying things out, quick checks and reading help pages
Script in RStudio	The script, which contains the commands that produce your results	Analyses you will run again, which is most of your work
R Markdown / Quarto	A document that produces its own results each time it is knitted	Reports, papers and theses, where your methods are shared along with your results
Jupyter notebook	The code, together with the output from the last time each cell was run	Exploring data and showing your work, teaching, and projects that mix languages
Rscript / R CMD BATCH	The script, a log of the run (.Rout) and any output files	Servers, clusters, pipelines, and jobs that are scheduled or repeated

You are starting a project to analyse a lab’s measurements. The analysis will be written up as a report for your supervisor, and it will need to be run again whenever new measurements come in. Which ways of using R would you use, and for what?

For example, you could use the console to look at the data and try things out, and write the analysis in R scripts (in RStudio) or directly in an R Markdown or Quarto report, so that the report is rebuilt from the data each time it is knitted. You might also use Rscript to run the analysis again automatically when new data arrive. A notebook would work well for exploring the data, as long as you restart it and run it from the top before you share anything from it.

Asking the AI assistant

The AI tab gives you an AI assistant that knows about this workbench. It can explain an error message, a function or an idea, but it doesn’t always get things right, so check what it tells you and run any code yourself. When you get an error in one of the consoles, a button appears underneath it that lets you ask the assistant about the error.

A prompt for the assistant

Explain the difference between running an R Markdown chunk in RStudio and knitting the whole document. Keep it short and give an example of something that works in one and fails in the other.

Keep your data private

Never paste personal data or patient data into an AI tool.

Which way of using R would you choose for your next piece of work, and why?

There is no single right answer: any choice is fine if your reasons fit the work. Think about whether the work needs a record of how the results were produced (a script or a document), whether other people will read the results (a document or a notebook), and whether it will run unattended or many times (Rscript).