3 Using Quarto Documents & Completing Assignments
3.1 What is a Quarto Document?1
This semester you will be using the statistical programming language R in RStudio, an integrated development environment (or IDE). But where will we put the code? We will use an interactive document, Quarto. Quarto documents can contain both code, that we can execute to run data analysis and create graphs, and text that discusses the work we have done.
Quarto documents are interactive in that we can run our analysis and then write up explanations of it. Quarto documents can be rendered, running the code and producing a report in a specific format such as Word, .PDF, .HTML, and many other formats.
3.1.1 Creating a Quarto Document
We will mostly be working with templates that you can work to fill in. But creating a Quarto document is easy. Starting and Naming a New Quarto Document Start a new Quarto document in RStudio by clicking File > New File > Quarto Document…
You may name your Quarto document as “my_first_first_qmd”.
New Quarto files will have a generic template unless you click the “Create Empty Document” in the bottom left-hand corner of the dialog box.
We will keep all pre-selected options: HTML as the output, knitr engine and the visual editor. The output might be changed at anytime and we can easily switch between the visual and the source editor. Knitr will be the engine used to execute the R codes and to render the document in Rstudio.
If you see this default text you’re good to go:
3.2 Working in Quarto Documents
You can work in two modes: the visual editor or the source editor. Most of you will want to work in visual editor mode.
3.2.1 The Visual Editor vs. the Source Editor
The visual editor follows the WYSIWYG “what you see is what you get” approach similarly to Word or Google docs that lets you choose styling options from the menu (before you had to either have the markdown code memorized or look it up for each of your styling choices). Another major benefit is that the new editor renders the styling in real time so you can preview your paper before rendering to your output format. The image directly above shows the visual editor.
In the visual editor you can use editor tool bar at the top of the document to format your document. Here are the options.
If you toggle the source button, you will display your Quarto document in the “source editor” mode. Notice the symbols scattered throughout the text (#, *, <>). Those are examples of Markdown syntax, an easy and quick, human-readable markup language for document styling.
3.2.2 Writing in Markdown
If you prefer to write in the source editor, you will need to use a version of Markdown, called RMarkdown. Moving between the source and visual editor should help you get a sense of the code.
3.2.3 Code Chunks
Whether you are working in the visual or the source editor, you need to put place your R code in sections that are marked to run the code named “code chunks”.
You will need to put everything you need to complete an assignment in a code chunk. This includes loading packages and data, and the code for the analyses and graphs you want to run.
You can run individual code chunks by clicking on the green triangles in each code chunk.
Creating a New Code Chunk
You may need to add a new code chunk. This is easy to do. In the top right of the upper-right quadrant, click on the add code chunk button.
3.3 Rendering Quarto Documents
Simply put, rendering is the process of converting a document into a file format or a medium that is paginated or has the concept of pages. Clicking the render button will compile the code, check for errors, and finally, output the type of file indicated in your yaml header. You may select the option “Render on Save” to see a preview of your document every time you save edits. Attention: your qmd document may not run and render as your indicated output if there are any errors in the document so it also functions somewhat as a code checker.
The rendered document will appear in the right side of RStudio in the Viewer area.
3.4 Creating a PDF for Assignment Submission
Each skill assignment requires that you upload a PDF of your completed Quarto document. Here is how you do this. After this description there is a 45 second video that shows you how to do it.
- Before rendering your Quarto document go to the gear button in the upper left quadrant next to the Rnder button and make sure that you are set up to “Preview in the Viewer Pane.”
- Render your document by clicking on the Render button in the upper left quadrant. This should open your document in the right panel.
- Click on the open in a new window above your document on the right side of your screen. This should open your file in a web browser. It should look the same as it does in RStudio.
- In the browser window print your document as a PDF. You can print from the menu or by using the command-P keys for Macs or control-P for PCs. Give your file a name you will remember and take note where the file is located in One Drive.
- In Brightspace, upload your file in the assignment dropbox.
3.5 Importing Files into an Assignment
Each assignment will include most of the files you need to complete your work. As you refine your dataset, however, you may need to save your dataset file and upload it to future assignments. To upload a file:
go the lower-right quadrant,
make sure you are in the “Files” tab,
click on the “Upload” button,
navigate to the file on your computer or in OneDrive that you want to upload, and
click the “OK” button.
3.6 Exporting Files from an Assignment
There are two reasons you will need to export a file from Posit Cloud:
- You must turn in an rendered Quarto document for each Skill Assignment. You will need to download this HTML file first.
- You have to move your dataset from one assignment to the next assignment.
These are the steps to export a file:
go the lower-right quadrant,
make sure you are in the “Files” tab (1),
select the file you wish to export by selecting the check box to the right of the file name (2),
click on the “More” button (3, it has a gear to the right of it),
choose “Export” from the list of options (4), and
click the “Download” button. The file should go to downloads folder on your computer or in OneDrive.
3.7 Learning More About Quarto
Much of this section has been used under Creative Commons license from the Data Carpentry course, Introduction to Reproducible Publications in Rstudio.↩︎