Sourcing external code

Quarto has the option to include code from external files, such as R and Python scripts, .qmd or .ipynb files. It can be desirable to leave code in files separated from the main manuscript file.

This can help to:

• Prevent manual, error-prone work copy-pasting code from one file to another
• Allow easier debugging of code
• Make the Quarto document easier to digest, both for you and for non-coding collaborators in your project
• Adhere to good coding practices to keep different files meant for different purposes separated (e.g., 1 script should preferably only do 1 thing)

What can you do in Quarto?

1. Run a script before or after rendering a Quarto document to a manuscript.
2. Use (parts of) a script within the Quarto document, for example to use objects that were created within that script.
3. Use code chunks from existing Quarto documents or Jupyter notebooks.
4. Include entire Quarto documents or Jupyter notebooks within your current Quarto document.

1. Run a script before or after rendering

You can run a script before or after rendering a Quarto document or project in 2 ways:

1. Run a script via the terminal:

quarto run your-script.py

2. Include the script(s) in the project yaml:

project:
  type: website
  pre-render: prepare.py
  post-render: 
    - compress.ts
    - fix-links.py

These kinds of scripts should perform some independent preparatory or finishing work, for which the objects do not have to be available in the Quarto document itself. If you want to use objects from an R or Python script within the Quarto document, proceed to the next step!

2. Use an external script

R

You can include the code from an existing script in your Quarto document by using the #| file: chunk option. This includes the code in the Quarto document, which can then be used further.

```{{r}}
#| file: "your-script.R"
#| eval: true 
```

Run sections of code one by one

In R, it is also possible to use specific sections from a script. This is handy when the script contains multiple functions or anaysis steps that you want to execute step by step.

The following instructions were adjusted from the R markdown cookbook:

1. Include section indicators in your code. These section indicators allow us to select which parts of the R script to run in a specific Quarto code chunk:

# Content of your-script-with-chunks.R
## ---- test-a --------
1 + 1

## ---- test-b --------
if (TRUE) {
  plot(cars)
}

2. Read the chunks from the script into your Quarto file:

```{r}
#| include: false
#| cache: false
knitr::read_chunk('your-script-with-chunks.R')
```

3. Execute the chunks that you want to execute from the external script in an empty labelled code chunk:

```{r}
#| label: test-a
```

If your external code also contains functions, instead of only directly executable code, you should in step 2 source the file instead of reading the individual chunks!

```{r}
#| file: "scripts/plot-data.R"
```

Python

You can include the code from an existing script in your Quarto document by using the #| file: chunk option. This includes the code in the Quarto document, which can then be used further.

```{python}
#| file: "your-script.py"
```

3. Use code chunks from another Quarto document

You can also reuse code chunks from existing Quarto files (.qmd) or Jupyter notebooks (.ipynb). This feature is new Quarto v1.4, so make sure you have the newest version of Quarto installed. The basic code to do so is:

{{< embed sourcequartofile.qmd#code-chunk-label >}}.

or (source)

{{< embed source.ipynb#code-chunk-label >}}.

This does not yet work in the current Quarto version, because Quarto v1.4 is still just a prerelease!

4. Include child Quarto documents

You can include child Quarto documents within a “master” document to keep things separate (source).

{{< include _childdocument.qmd >}}

These child documents can also include computational chunks, as long as they use the same engine (e.g. knitr or jupyter).

For a Jupyter notebook, simply paste:

{{< embed source.ipynb >}}

Exercises

Exercise 1

The R script do_addition.R and the Python script do_addition.py in the scripts folder contain a function to perform simple addition. The function takes two numbers as arguments, adds them together, and outputs the result to the console.

1. Complete the following code to include the do_addition function into your Quarto document:

R

```{r}
#| label: Include the do_addition.R function in the current file
# Replace this line with your answer
```

Python

```{python}
#| label: Include the do_addition.py function in the current file
# Replace this line with your answer
```

2. Use the do_addition function to add two numbers of your choice to test whether your answer in a was correct!

R

```{r}
#| label: perform an addition to check whether the sourcing worked
# Replace this line with your answer
```

Python

```{python}
#| label: perform an addition to check whether the sourcing worked
# Replace this line with your answer
```

Exercise 2

Include the fig-scatter chunk from the source_r.qmd or source_py.qmd file in this Quarto file.

{{< YOUR-CODE-HERE > }}

Answers

Exercise 1

R

```{r}
#| label: Include the do_addition.R function in the current file
#| file: "scripts/do_addition.R"
```

and

```{r}
#| label: perform an addition to check whether the sourcing worked
a <- 4
b <- 3
do_addition(a, b)
```

Python

```{python}
#| label: Include the do_addition.py function in the current file
#| file: "scripts/do_addition.py"
```

and

```{python}
#| label: perform an addition to check whether the sourcing worked
a = 4
b = 3
do_addition(a, b)
```

Exercise 2

R

{{< embed scripts/source_r.qmd#fig-scatter> }}

Python

{{< embed scripts/source_py.qmd#fig-scatter> }}