Skip to contents

Getting started with R and Quarto notebooks

Source: vignettes/articles/tutorial-13-getting-started-r-quarto.Rmd
tutorial-13-getting-started-r-quarto.Rmd

Tutorial

A MRMhub analysis is written as a document that mixes prose with the R code that produces the results, so the report and the analysis are one file. This tutorial assumes no prior experience with R or Quarto: it starts from an empty computer, installs the software, sets up the project and notebook to work in, and shows how to read and run the code. Once your machine is set up, Getting started with MRMhub runs a complete analysis in the project you create here.

1. Install R and an editor

Two pieces of software are needed. R is the language the analysis runs in; an integrated development environment (IDE) is the editor you write and run it in. Install R first — the IDE looks for it on startup.

  • Install R from CRAN (version 4.1 or newer). Pick the download for your operating system and accept the defaults.
  • Install an IDE. RStudio is the most common choice and the one this tutorial follows. If you already work in VS Code, Positron is an RStudio-like alternative built on the same editor.

Both are installed once per machine and shared by every project you create afterwards.

2. RStudio

When RStudio opens it shows four panes, each used at some point in an analysis:

  • Source (top-left) — where you edit the notebook and run its code. Its toolbar carries the Render button, and each code chunk gets a green ▶ arrow that runs it.
  • Console (bottom-left) — runs a single line of R immediately, without saving it in the notebook. This is where software is installed and where MRMhub’s step messages appear.
  • Environment (top-right) — lists the objects that currently exist in the session, such as the mexp data object once the notebook has created it.
  • Files / Plots / Help (bottom-right) — browses the project folder, shows figures, and displays function help pages.
my_study — RStudioanalysis.qmdRenderSource▶edit prose and code chunks here```{r}mexp <- normalize_by_istd(mexp)```▶ runs a chunk, Render builds the reportEnvironmentNameValuemexpMRMhubExperimentd_conc84 obs. of 12 variablesn_featuresint 84the objects that exist right now,empty again in a fresh sessionConsole> pak::pak("SLINGhub/MRMhub")> mrmhub::build_workflow()✔ Normalized 84 features by ISTDruns a single line of R immediately;MRMhub’s step messages arrive hereFiles & Plotsmy_study/data/output/analysis.qmdmy_study.Rprojfigures open in Plots, help pages in HelpRStudio’s default four-pane layout, with the project folder open as my_study

The panes can be resized or rearranged, but the defaults are fine to start; nothing here needs configuring.

3. Install MRMhub

With R and RStudio installed, open RStudio and install MRMhub from the Console (the bottom-left pane). The first line installs pak, a package installer; the second uses it to fetch MRMhub and its dependencies:

if (!require("pak")) install.packages("pak")
pak::pak("SLINGhub/MRMhub")

Installing is a once-per-machine step, and running the same two lines again later updates MRMhub to the current version. Making its functions available is a separate, per-session step — library(mrmhub) — which belongs in the notebook rather than the Console, so that every render loads the package itself.

If the installation reports an error, the Installation guide lists the common causes (a missing compiler on Windows or macOS, a firewall blocking the download) and their fixes.

4. Create a Quarto project

A project keeps everything for one analysis — data, code, and results — in a single folder that the IDE treats as a unit. In RStudio, choose File → New Project → New Directory → Quarto Project, give it a name, and create it. Quarto itself ships with RStudio, so nothing further needs installing; if the Quarto Project entry is missing, update RStudio or install Quarto from quarto.org. Quarto’s project documentation covers the dialog in detail.

The dialog creates the folder, a first .qmd document, and an .Rproj file. That .Rproj file is how the project is reopened later — by double-clicking it, or through the project menu at the top-right of the RStudio window. Opening the project, rather than the .qmd on its own, is what points R at the right folder.

Inside the new project, add two folders to keep raw inputs separate from generated results — the convention MRMhub’s own workflows follow:

my_study/
├── my_study.Rproj   # opens the project
├── data/            # raw INTEGRATOR output and metadata files
├── output/          # exported CSVs, PDFs, and reports
└── analysis.qmd     # this document

Paths in your code are written relative to this project folder: RStudio treats it as the working directory, so data/my_file.csv points to the same place on any machine, without a full path. This is why the data/ and output/ folders above are all the analysis needs to find its files, and why the whole folder can be zipped and shared as a self-contained unit.

5. Write text and code in a .qmd

A .qmd file is plain text with three kinds of content: a header, prose, and code chunks.

At the top, a short header fenced by --- sets the title and the output format — html, pdf, or docx. A new project starts with a sensible HTML header, and Quarto workflows covers the options that matter for a MRMhub report.

Below the header, prose is written in Markdown — plain paragraphs, with # for headings, **bold**, and - for lists. Quarto’s Markdown basics is the full reference for tables, figures, cross-references, and citations.

Code lives in chunks: R code fenced between ```{r} and ```. In RStudio, Insert → Code Chunk (or Ctrl/Cmd + Alt + I) adds an empty one. A chunk that loads the MRMhub package, with a sentence of prose introducing it, looks like this:

Load the package before calling any of its functions.

```{r}
library(mrmhub)
```

Chunk options

Each chunk can carry options that control whether its code runs, whether the code itself is shown, and which parts of its output reach the report. They are written as #| comment lines directly below the chunk’s opening fence, one per line, as option: value:

```{r}
#| label: normalize
#| message: true
mexp <- normalize_by_istd(mexp)
```

The options a processing notebook needs are few:

Option What it controls
#| label: A unique name for the chunk; also names any figure it produces.
#| eval: Whether the code runs. false shows the code without executing it.
#| echo: Whether the code itself appears in the report.
#| output: Whether the results appear — printed values, tables, figures.
#| message: Whether messages appear. MRMhub’s step feedback travels here.
#| warning: Whether warnings appear.
#| include: false runs the chunk but hides both code and output — used for setup chunks.
#| cache: Stores the result, so an unchanged chunk is not re-run on the next render.
#| fig-width:, #| fig-height: Size, in inches, of the figures the chunk produces.

MRMhub reports what each processing step did as a console message — a count, and a truncated list of the features or analyses affected — so keeping #| message: true on the chunks that run a step turns the rendered report into a record of the processing. Defaults for the whole document are set in the header instead of chunk by chunk:

execute:
  warning: true
  message: true

Quarto’s execution options page is the complete reference for both forms.

RStudio offers two ways to edit a .qmd: the Source editor shows the raw Markdown, while the Visual editor (the Visual toggle, top-left of the document) shows a formatted, word-processor-like view. Both edit the same file, and Quarto’s authoring guide introduces both. You may also meet the older R Markdown format (.Rmd), which Quarto renders unchanged; it writes the same options inside the fence, as {r, message=TRUE}.

6. Run code and render the report

There are two distinct actions. Running a chunk executes its code immediately and shows the result inline: click the green ▶ arrow at the chunk’s top-right, or press Ctrl/Cmd + Shift + Enter with the cursor inside it. Because each chunk builds on the objects the earlier ones created, Run → Run All Chunks Above (Ctrl/Cmd + Alt + P) is the way back to a working state after reopening the project, when the session starts with an empty Environment.

Rendering turns the whole document into a finished report: click Render (Ctrl/Cmd + Shift + K), and Quarto runs every chunk in order and assembles the output — analysis.html alongside the document — which opens in the Preview pane and refreshes on each render.

Rendering runs in a fresh R session, top to bottom, so the report is built from what the document itself contains and nothing else. A chunk that works interactively because a needed object is still in the Environment pane will fail on render if no chunk creates it. This is the point of rendering: it proves the analysis reproduces from the raw data. While developing, run chunks one at a time to check each step; render at the end to produce the shareable report.

Try it now: insert a chunk into your document, put library(mrmhub) in it, and run it. Loading MRMhub without error confirms the installation worked.

If a chunk stops with an error, the Console prints the message under the offending call; the last line is usually the informative one. Troubleshooting & FAQ collects the errors that come up most often, and what each one means.

7. Reading the code you’ll run

The next tutorial uses MRMhub functions and no custom R, but three pieces of R syntax recur throughout. Recognising them is enough to follow along:

  • Assignment (<-) stores a result under a name. mexp <- MRMhubExperiment() creates a data object and names it mexp; writing mexp again later refers back to it.
  • Function calls with named arguments. In import_data_mrmhub(mexp, path = demo_file), the function acts on mexp, and path = names which input the file is. Most MRMhub functions take the data object first and options as named arguments.
  • The pipe (|>) passes a result straight into the next function, so plot_pca(mexp) |> save_plot("pca.pdf") plots and then saves in one line, with no temporary name.

Each processing step follows the same shape — take the data object, return an updated one, and store it back under the same name: mexp <- normalize_by_istd(mexp). The functions do not modify the object in place, so the assignment is what carries the result forward; running normalize_by_istd(mexp) on its own leaves mexp as it was. All the documentation names the object mexp, and keeping that one name throughout a notebook avoids running a later step on an earlier version of the data.

8. Getting help

To see what a function does and which arguments it takes, type ? followed by its name in the Console:

?plot_pca

Its help page opens in the Help pane, listing every argument with an explanation and, usually, examples that can be copied and run. The same pages for every function are in the function reference, the MRMhub overview introduces the concepts they build on, and problems that look like a bug belong in the issue tracker.

The editor and the notebook format are documented by their own projects:

  • RStudio user guide: panes: Posit’s reference for the four panes, including how to resize and rearrange them
  • Hello, Quarto: Quarto’s own walkthrough of writing and rendering a .qmd in RStudio

With the software installed, the project set up, and the syntax demystified, you are ready to run a real analysis. Continue with Getting started with MRMhub, which imports the demo data and takes it through to an exported report.

Next steps