Summary and Schedule

This workshop explores the powerful combination of Quarto and RStudio to author scientific publications. We aim to enhance researchers’ adoption of open and reproducible practices while improving their project and data management skills. This workshop is structured into three modules. The modular format encourages instructors to view the workshop as a comprehensive but flexible curriculum, allowing them to focus on specific areas of interest. Recognizing variations in proficiency levels and familiarity with RStudio among learners, we have designed this workshop to be flexible, allowing for the abbreviation or skipping of episodes to cater to specific needs:

Module 1 - Reproducibility and Project Organization: This module consists of two episodes (1. Scientific reproducibility: What is it for?, and 2. Good Practices for Managing Projects in RStudio) which introduce learners to reproducible research and project management fundamentals. It lays the groundwork for a robust and transparent workflow, ensuring that all participants, whether beginners or those seeking a refresher, are on the same page before delving into the specifics of Quarto and RStudio Posit.

Module 2 - Quarto and RStudio: This module focuses on Quarto and its features for creating dynamic and reproducible documents. We guide learners through the ins and outs of Quarto, helping them harness this authoring framework and the tool’s potential to create visually appealing, easily reproducible, and shareable documents. This central module forms the bulk of the workshop, consisting of eight sessions that guide participants from the fundamentals of RStudio to advanced Quarto document features. Participants will build practical skills for creating reproducible, well-structured documents, including integrating code, styling content, managing projects, and handling references. Episodes included in this module are: 3. Navigating RStudio and Quarto Documents, 4. Working with Projects in RStudio, 5. Introduction to Working with Quarto Documents, 6. Writing and Styling Qmd Documents, 7. Adding Code to Quarto Documents, 8. Rendering & Customizing Code Outputs, 9. Advanced Code Chunk Options, and 10. Bibliography, Citations & Cross-Referencing

Module 3 - Collaboration: This final module includes the remaining file episodes (i.e., 11. Using Git in RStudio, 12. Collaborating via GitHub, 13. Managing Dependencies in R/RStudio, 14. Publishing your project, 15. Creating and sharing reproducible environments with renv) shifts the focus to collaboration and publishing. It explores effective collaboration with others, using version control within RStudio, pushing local changes to a remote repository, managing dependencies for R/Quarto projects, and sharing reproducible research with a broader audience.

Prerequisite

Experience in R/RStudio is recommended but not required. Experience, if not familiarity, with using your Unix Shell Terminal, and Version Control with Git is required. You will need a GitHub Account to fork and pull the example repo.

	Setup Instructions	Download files required for the lesson
Duration: 00h 00m	1. Scientific reproducibility: What is it for?	What is reproducible research? How can RStudio help research be more reproducible? What are the benefits of using RStudio for writing academic essays and papers?
Duration: 00h 10m	2. Good Practices for Managing Projects in RStudio	What are good research project management practices? What is an R Project file? How do you start a new R Project or open an existing one? How do you use version control to keep track of your work?
Duration: 00h 40m	3. Navigating RStudio and Quarto Documents	How do you find your way around RStudio? How do you start a Quarto document in RStudio? How is a Quarto document configured, and how do I work with it?
Duration: 01h 00m	4. Working with projects in RStudio	How do I start or continue a project with Git versioning? How does RStudio support version control?
Duration: 01h 30m	5. Introduction to Working with Quarto documents	What is Quarto? What is the breakdown of a Quarto document? How can you render the input file to the specified output format?
Duration: 01h 55m	6. Writing and Styling Quarto Documents	What is the Visual Editor in RStudio? Which features does the Visual Editor have? How can one apply styling and formatting to Qmd documents in RStudio more easily? How to add inline code?
Duration: 02h 15m	7. Adding Code to Quarto Documents	What is Knitr and how does it work? What are code chunks, and how are they structured? How do you add and run code chunks? How can I avoid issues with relative paths?
Duration: 02h 45m	8. Rendering and Customizing Code Outputs	How do you render code in Quarto documents? How do you apply code chunk options at the document level to customize your code? How do you label and caption code chunks? What is inline code, and when should it be used?
Duration: 03h 15m	9. Advanced Code Chunk Options	How do you apply global options at the project level? How do you globally load data and packages? How do you run code from an external script in a code chunk? How do I run external scripts in a Quarto document?
Duration: 03h 35m	10. Bibliography, Citations and Cross-Referencing	How can you insert citations into your manuscripts using RStudio’s visual editor? How can you change citation styles? What are the options to display cited and uncited bibliography? How can you cross-reference content?
Duration: 04h 10m	11. Using Git in RStudio	How do I use version control in RStudio? How do I track and commit changes?
Duration: 04h 25m	12. Collaborating via GitHub	How do I authenticate with GitHub? How do I put my project on GitHub? How do I “push” my latest changes to GitHub?
Duration: 05h 00m	13. Managing Dependencies in R/RStudio	How can I avoid the dependency hell problem and make my code reproducible in the future? How can I document my computational environment? How can I manage package and software dependencies in RStudio?
Duration: 05h 20m	14. Publishing your project	What are the options for you to publish your project? What free and open publishing resources are available? What aspects should guide your choice? How can you create QMD documents using journal templates?
Duration: 05h 30m	15. Creating and sharing reproducible environments with renv	How can I manage package and software dependencies in RStudio? What is the renv package and how does it work?
Duration: 06h 00m	Finish

The actual schedule may vary slightly depending on the topics and exercises chosen by the instructor.

PART I: Install Git and create a GitHub Account

---

We will need the following accounts and software for this workshop:

• Create GitHub account (use existing or create a new account)
• Install Git
• Install R & RStudio (Two separate installations: if you are on a Windows device, you may need Rtools.

For the most up-to-date instructions for creating your GitHub account and installing Git, please follow the steps described in Software Carpentry’s Version Control with Git lesson.

Git

Git is a version control system that lets you track who made changes to what, when, and has options for easily updating a shared or public version of your code on GitHub.

Additional GitHub information

Through the Github education program, students get additional free services beyond the basic free account.

If you are concerned about what personal information (specifically contact information) is revealed through GitHub you may review these instructions for keeping your email address private provided by GitHub.

PART II: Install R/Rstudio and Quarto

---

R

R is a powerful programming language for data exploration, visualization, and statistical analysis. To interact with R, we use RStudio.

Follow the installation instructions provided here to install R and RStudio.

Quarto

Quarto is a scientific and technical publishing system built on Pandoc that we will use in RStudio. Quarto has been bundled with RStudio in recent versions. If you have the most up-to-date RStudio version, you shouldn’t to install Quarto.

Key Points

Version clarifications on Quarto and R/Rstudio

If you already have RStudio and R installed, please check if you have the most recent RStudio version and at least R version 4.3, along with Quarto version 1.3.45 at least. The quarto document will not render without the most up-to-date versions. The Quarto Package is not the CLI.

You can check if you have the correct Quarto version by typing the following in the RStudio terminal:

quarto --version

Your output should be:

OUTPUT

quarto --version
1.4

R Packages

Install the following packages in RStudio: rmarkdown, tidyverse,BayesFactor, patchwork. We will be covering the purpose of using packages and recap different ways to install and manage them in RStudio. Nonetheless, pre-installing the packages we will use for this workshop will save us some precious time, since installation time may vary among learners. Here are the steps for two possible approaches you may follow for completing this process:

Using Menus and Tabs

Using the Console

Open RStudio

Select from the upper menu Tools > Install packages... or click on the Packages tab in the bottom-right section and then click on install. Either action will prompt a box dialog.

In the Install Packages dialog box, copy this text rmarkdown, tidyverse, BayesFactor, patchwork under the Packages field, make sure the option install dependencies is selected, keep other information unchanged, and then click install.

Don’t be alarmed by the stop sign that will blink (and do not click on it, otherwise you will cancel the process) or the red text messages. Once the process completes, the cursor will be preceded by a greater-than sign >.

1. Open RStudio

2. Select from the upper menu Tools > Install packages... or click on the Packages tab in the bottom-right section and then click on install. Either action will prompt a box dialog.

3. In the Install Packages dialog box, copy this text rmarkdown, tidyverse, BayesFactor, patchwork under the Packages field, make sure the option install dependencies is selected, keep other information unchanged, and then click install.

4. Don’t be alarmed by the stop sign that will blink (and do not click on it, otherwise you will cancel the process) or the red text messages. Once the process completes, the cursor will be preceded by a greater-than sign >.

Copy and paste each of the following functions to the console and wait for the process to complete:

R

 install.packages("rmarkdown")
 install.packages("tidyverse") 
 install.packages("BayesFactor") 
 install.packages("patchwork")

or instead

R

 install.packages(c("rmarkdown", "tidyverse", "BayesFactor", "patchwork"))