💻 Week 03 - Quarto, Zotero and Git tutorial

2025/26 Autumn Term

Figure 1: Images generated with Microsoft Designer

📚 Learning Objectives

In this tutorial:

• we will learn how to use Zotero to manage our references.
• we will learn a language called Quarto Markdown, which will allow us to create documents that are both reproducible and interactive.
• and finally, we will practice using GitHub

Preparation

1. Before you start this tutorial, make sure you have installed (or updated if they’re already installed!) the following:

• Quarto
• R
• VSCode (+Quarto and R extensions) or RStudio

2. You also need to install Zotero.

Zotero is a free, open-source reference management software that allows you to collect, organize, cite, and share your research sources. It lives as an extension in your browser and allows you to save references from online databases, websites, and books. It also has a desktop application that allows you to organize your references into collections and create bibliographies.

• Create a Zotero account
• Install the Zotero extension in your browser and install the desktop application following this guide.

3. Create a GitHub account

🛣️ Roadmap

Step 1: Collecting and saving academic references

Familiarizing yourselves with Zotero

To tackle this part of the drop-in session, you need to have a Zotero account and at least one of the Zotero browser extension and/or the Zotero desktop application installed.

1. Log in to your Zotero account.

2. To make things organized and tidy, we recommend you create collections of references within Zotero, e.g one specific to the references linked to the DS101A module. Head to this page to see how to create a references collection in Zotero; create a new collection under your account and give it a name that is easily recognizable and understandable.

3. Using the Zotero extension in your browser, save a few relevant references to the new collection you created (check out the 📔 syllabus for some suggestions). Have a look at this tutorial to see how you can add references via your web browser in Zotero.

4. Download the pdf article below:

Head to the section “Adding PDFs and Other Files” of this tutorial and add this pdf to your Zotero collection.

5. Download the zip archive below:

Place the archive in the folder you want to unzip it in and unzip the archive. Use this guide to add the metadata of the PDFs from the unzipped archive into your Zotero collection.

Creating a bibliography reference file to include in a Quarto document

In this part of the drop-in session, we are going to use Zotero to create a bibliography reference file that will help us include references in the Quarto document we will be editing and formatting later in the drop-in session (see Step 2).

1. In Zotero, add the following articles to a new collection:
   • https://academic.oup.com/biomet/article/63/3/581/270932?login=true
   • https://hbr.org/2019/10/gdp-is-not-a-measure-of-human-well-being
   • https://www.imf.org/external/pubs/ft/fandd/2017/03/coyle.htm
   • Make sure to include the name of the author(s), (article) title, journal/magazine, number, issue, page range, and DOI. Make your information as complete as possible
2. Right-click on the bibliography and select “Export Collection”. Create a BibLaTeX document called references.bib and save it in the same directory where you’ll be putting the skeleton Quarto document from the next step.

This concludes the Zotero part of the session. We’ll now move on to Quarto Markdown practice.

Step 2 : Formatting documents with Quarto Markdown

To tackle this part, you need to have RStudio or VSCode as well as Quarto and R installed.

1. Open a VSCode workspace (see how here)

2. Download the .zip archive below that contains a skeleton Quarto Markdown (.qmd) file and place the .qmd file in your workspace. Quarto Markdown files have a .qmd extension.

3. Open the skeleton Markdown file in VSCode or RStudio.

You will see a file with placeholders for R code chunks.

Note

You will see that there is a series of short headings and sentences without any formatting. We are going to turn this into an appropriately formatted document with three sections.

There are many ways in which you can format your documents in Quarto, please refer to this page as a user guide throughout.

Formatting document sections - Section 1

Let’s start by formatting the first section of the document, Section 1: Understanding missing data mechanisms.

🎯 ACTION POINTS:

Note

To check the results of the changes you make to your .qmd file:

• open a terminal in VSCode or RStudio
• go to the folder where your .qmd file is located using the cd command e.g if your DS202_tutorial_skeleton.qmd file is in /users/lovelace/Documents (i.e the full path to your file is /users/lovelace/Documents/DS202A_tutorial_skeleton.qmd) then you would type this command on the terminal cd /users/lovelace/Documents/DS202A_tutorial_skeleton.qmd followed by the Enter key.
• then on the terminal, type this command quarto preview DS202A_tutorial_skeleton.qmd --no-browser. A browser tab will open and you will see how your document would look, once it is rendered in HTML format.

Alternatively, to preview your document, you could press on the Render button (blue arrow) if you are on RStudio or use the preview button in VSCode (if you are on VSCode and have installed the Quarto extension).

⚠️ The quarto preview command does not render your document yet (i.e no output HTML is created). To render your document (once you are done modifying it!), use the quarto render DS202A_tutorial_skeleton.qmd command on the terminal. You will see that a DS202A_tutorial_skeleton.html file is created in the same folder as your .qmd file: you can open this new file in your favorite browser (e.g Firefox, Chrome).

1. Turn the line “Understanding missing data mechanisms” into a section header.

2. Add the following to the YAML header:

   bibliography: references.bib

3. Click on references.bib to see the reference Zotero created for the Rubin article.

4. Directly reference the article using @ArticleReference or [@ArticleReference].

5. Turn the paragraph about missing data into bullet points.

Formatting your document - Section 2 - Part 1

Now, let’s format the second section of the document, Data Analysis Case Study: GDP (OECD data).

🎯 ACTION POINTS:

1. Turn the line “Data Analysis Case Study: GDP (OECD data)” into a section header and the lines “Trends in GDP per capita, 1972 to 2022”, “GDP table for selected countries”,“GDP barplot for selected countries” and “Criticism of the GDP measure” into subsection headers.

2. Go the OECD website:

• https://data.oecd.org/gdp/gross-domestic-product-gdp.htm

Download the GDP (dollars/per capita) table (CSV file) from 1972 to 2022 (full indicator data version) and place the CSV file in the same folder as your Quarto file.

3. Let’s write some simple R code. Go to the skeleton R code chunks at the top of the file.

Fill in the blanks in the code chunk calling for library loading then write a line of code to read the csv file you’ve just downloaded into a data frame.

4. Check out the following documentation:
   • https://quarto.org/docs/get-started/computations/rstudio.html#inline-code
5. In the code chunk dedicated to it, write a function that takes a year and the data as parameters and returns the average GDP for that year. Now use inline R code to replace the ellipses (…) with the dollar/capita amounts using the function you’ve written.

Formatting your document - Section 2 - Part 2

We’ll now continue formatting the second section of the document, Data Analysis Case Study: GDP (OECD data) but turn our attention to the last three subsections of it i.e GDP table for selected countries,GDP barplot for selected countries and Criticism of the GDP measure.

1. We want to create a table that shows the GDP between 2018 and 2020 for the following countries: the UK, India, China, Spain, the US, Italy and France.

In the skeleton Markdown file, you’ll see a blank code chunk asking you to to get the GDP of the UK, India, China, Spain, the USA, Italy and France between 2028 and 2020 and present the GDP per country per year as a table.

Write this function in the chunk. Make sure your code chunk is executable.

For the code to be executed, you need to replace the FALSE in the #| eval : FALSE line by TRUE and to allow the result of the execution to be printed out, you need to replace the FALSE in the #| echo : FALSE line by TRUE.

If your function is not already a Markdown table, write a Markdown table (see how here) that shows the GDP of the UK, India, China, Spain, the US, Italy and France between 2018 and 2020 and add it to the section GDP table for selected countries. Don’t forget to add a caption to the table. Once you’re done adding the table, change back the options in the R code snippet to what they originally were i.e #| eval : FALSE and #| echo : FALSE to only leave the Markdown table you’ve written visible.

2. Next, we’ll move to the GDP barplot for selected countries subsection of the skeleton Markdown file.

What we want to do now is create a barplot to visualize the GDP of the UK, India, China, Spain, the USA, Italy and France in 2020. So, within the blank code snippet provided, try to write the code for a barplot that shows the GDP per capita per country for 2020 for each of the countries mentioned.

You can either:

• keep your code executable (but not visible) and let it insert the needed barplot in the document for you
• or export the barplot as an image (e.g .png or .jpg) and include it in the subsection as a figure (follow the instructions in this guide) to do this. Once you’re done including your figure, make sure the code snippet you used to generate the figure is no longer executable (i.e you modify the eval option value back to FALSE so that the line reads as #| eval : FALSE).

3. In subsection Criticism of the GDP measure, cite the two references from your bibliography relative to GDP that you added to references.bib earlier using the [@ArticleReference] notation. On the web look for an image that illustrates the content of the section and insert it in the subsection in the same way you inserted the barplot you created previously.

4. When you are done editing your .qmd, you can render it using the quarto render command to generate an HTML file. Visualise your HTML output and check everything is in order.

Step 3: Getting to grips with GitHub

Now let’s turn our attention to GitHub.

🎯 ACTION POINTS:

1. Make sure you have created your GitHub account by now. If you have, you can start by following this tutorial and this one

2. Try and have a go at this tutorial on merge conflicts

3. Once you’re comfortable with this, accept this GitHub Classroom assignment and upload the .qmd file you filed in previously, the .html file rendered from it as well as any file that was necessary to render the .qmd (e.g images, bibliography)

4. To go further, have a go at the material on this website (and if you need to set things up with VSCode instead of RStudio, look at this page).