Summary and Setup

This is lesson is designed for professionals involved in scholarly communication analytics, e.g. in the areas of research, data analysis, library and information science and policy, looking to enhance their technical skills in dashboard creation for open access monitoring activities using the open-source tool Quarto with R as an example programming language in the RStudio integrated development environment.

Learners will become familiar with Quarto for dashboard creation. Quarto, as an open-source scientific and technical publishing system, allows you to generate multiple output formats from a single source file, seamlessly integrating text and dynamic content. While Quarto is a versatile tool with applications ranging from data visualization to reproducible documentation, this lesson will focus specifically on using it for creating (interactive) dashboards tailored to open access monitoring.

Learning Objectives

By the end of this lesson, learners will be able to:

  1. Describe what Quarto is and explain how Quarto documents are structured.
  2. Describe what Quarto dashboards are, their key features, and the components they consist of.
  3. Apply Markdown syntax to define components and structure content within a Quarto dashboard.
  4. Use R functions to load libraries and import data into the dashboard.
  5. Apply R functions to generate calculations and plots as dashboard content.
  6. Use YAML syntax to style and customize the appearance of the dashboard.
  7. Use YAML syntax and apply R functions to generate interactive dashboard content.
Callout

If you are a novice learner with little to no experience in programming this lesson might be hard to follow. In this case it is highly recommended to visit a training for novices first, e.g. Library Carpentry OpenRefine training to learn about data cleaning, Library Carpentry Introduction to R to get acquainted with R, Library Carpentry Introduction to Python to get acquainted with Python.

Prerequisite

Before joining this training, learners should meet the following criteria.

R (or Python)

  • You have basic knowledge of coding in R (loading libraries and data, transforming data, computing values, creating tables and visualizations).
  • Alternatively you have basic knowledge of coding in Python. Although we will use R as an example programming language, Quarto works with Python as well.
  • You have installed R and RStudio along with some packages before the lesson.
  • You have basic knowledge of markdown syntax (creating headings, links and importing images)
  • You have basic knowledge of YAML syntax (strings, booleans, nesting, files)

Data Set

Download the data zip file and unzip it to your Desktop.

This file is based on the Journal Checker Tool articles file from the OPENBIB: Selected curated open metadata based on OpenAlex data set published on Zenodo under a CC0 license. The data file was enhanced with open access related data from OpenAlex which are also available under a CC0 license.

The compiled teaching dataset used in this lessons is a CSV formatted dataset containing the following variables:

column name description
openalex_id article identifier given within the OpenAlex database
doi digital object identifier of the article
issn_l linking ISSN of the journal the article was published in
ror Reasearch Organisation Registry identifier of the corresponding author’s affiliated institution
esac_id ESAC Registry identifier for the transformative agreement under which the article was published
start_date transformative agreement term start date
end_date transformative agreement term end date
publication_date article publication date
oa_status article open access status
field primary subject field the article was assigned to based on the classification of OpenAlex
domain primary subject domain the article was assigned to based on the classification of OpenAlex
institution display name of the corresponding author’s affiliated institution
publisher display name of the publisher the article was published by
publication_year article publication year

Software Setup

To follow this lesson learners must have R and RStudio installed on their computers. They also need to be able to install a number of R packages, create directories, and download files.

A stable release of Quarto is bundled with RStudio v2022.07.1, and later. Upgrading to new versions of RStudio in the future will also upgrade the bundled Quarto version (Posit user guide).

Learners won’t need to install Quarto seperately unless to upgrade Quarto out of sync with the bundled version in RStudio. For this training we will use the bundled version.

To avoid troubleshooting during the lesson, learners should follow the instructions below to download and install everything beforehand. If the computer is managed by their organization’s IT department they might need help from an IT administrator.

Install R and RStudio

Discussion

Details

R and RStudio are two separate pieces of software:

  • R is a programming language and software used to run code written in R.
  • RStudio is an integrated development environment (IDE) that makes using R easier. In this course we use RStudio to interact with R.

If you don’t already have R and RStudio installed, follow the install instructions for your operating system provided by the Carpentries.

You have to install R before you install RStudio.

Update R and RStudio

Discussion

Details

If you already have R and RStudio installed, first check if your R version is up to date:

  • When you open RStudio your R version will be printed in the console on the bottom left. Alternatively, you can type sessionInfo() into the console. If your R version is 4.0.0 or later, you don’t need to update R for this lesson. If your version of R is older than that, download and install the latest version of R from the R project website for Windows, for MacOS, or for Linux
  • It is not necessary to remove old versions of R from your system, but if you wish to do so you can check How do I uninstall R?
  • After installing a new version of R, you will have to reinstall all your packages with the new version. For Windows, there is a package called installr that can help you with upgrading your R version and migrate your package library. A similar package called pacman can help with updating R packages across platforms.
  • To update RStudio to the latest version, open RStudio and click on Help > Check for Updates. If a new version is available follow the instruction on screen. By default, RStudio will also automatically notify you of new versions every once in a while.
Callout

The changes introduced by new R versions are usually backwards-compatible. That is, your old code should still work after updating your R version. However, if breaking changes happen, it is useful to know that you can have multiple versions of R installed in parallel and that you can switch between them in RStudio by going to Tools > Global Options > General > Basic.

While this may sound scary, it is far more common to run into issues due to using out-of-date versions of R or R packages. Keeping up with the latest versions of R, RStudio, and any packages you regularly use is a good practice.

Install required R packages

Discussion

Details

During the course we will need a number of R packages. Packages contain useful R code written by other people. We will use the packages here, tidyverse, plotly, DT, shiny, bslib and bsicons.

To try to install these packages, open RStudio and copy and paste the following command into the console window (look for a blinking cursor on the bottom left), then press the Enter (Windows and Linux) or Return (MacOS) to execute the command.

R 

install.packages(c("here", "tidyverse", "plotly", "DT","shiny","bslib","bsicons","lubridate"))

Alternatively, you can install the packages using RStudio’s graphical user interface by going to Tools > Install Packages and typing the names of the packages separated by a comma.

R tries to download and install the packages on your machine.

When the installation has finished, you can try to load the packages by pasting the following code into the console:

R 

library(here)
library(tidyverse)
library(plotly)
library(DT)
library(shiny)
library(bslib)
library(bsicons)
library(lubridate)

If you do not see an error like there is no package called ‘...’ you are good to go!

Updating R packages

Discussion

Details

Generally, it is recommended to keep your R version and all packages up to date, because new versions bring improvements and important bug fixes. To update the packages that you have installed, click Update in the Packages tab in the bottom right panel of RStudio, or go to Tools > Check for Package Updates...

You should update all of the packages required for the lesson, even if you installed them relatively recently.

Sometimes, package updates introduce changes that break your old code, which can be very frustrating. To avoid this problem, you can use a package called renv. It locks the package versions you have used for a given project and makes it straightforward to reinstall those exact package version in a new environment, for example after updating your R version or on another computer. However, the details are outside of the scope of this lesson.

Credits for the installation instructions: Data Carpentry R Ecology Lesson, Posit User Guide, Quarto Get Started Documentation