The purpose of this lab is to learn the basics of formatting Quarto documents. This includes general Markdown concepts like sections, links, text styling, lists, images, footnotes, and styled mathematics using \(\LaTeX\). Additionally, you will learn the basics of how to control the rendered output by specifying global options via YAML and local options in specific chunks.
After completing this lab, you should be able to use formatting to make your documents more professional and easier to read.
For this lab, you will be using the data you selected for your final project. You are tasked with creating a document that will import the data into R so that the next member of your group can work with it for the next rotation. Start by opening your Rotation 0 document in your SDS 100 project folder. Make sure you have the SDS 100 project open in your RStudio session.
You will know that you are done when your document contains at least one of each of the following items:
Styling text
one italicized word
one bold word
one variable or function styled as code
text stylized as code
Structuring a document
five sections
one link
one image
one footnote
Setting global options
at least one new YAML option
Controlling code output
at least one R chunk that overrides the global options set in YAML
Why are we here?
A critical aspect of conducting research is that you can clearly communicate your work to a wider audience and make it easily digestible. The average person will not understand (or likely care) about seeing your code, and only needs to see the output. Additionally, the thoughtful use of formatting elements such as section headings, mathematical expressions, links, and images help to make your report look professional and understood more easily. At the end of the day, we want our rendered documents to look visually appealing so people can read and understand them. With Quarto, you can can render your results to many different formats, including HTML or PDF reports, presentations, or even websites.
Lab instructions
Throughout this lab and in the future, we recommend that you check out the R Markdown Cheat Sheet that includes helpful information about a variety of ways you can customize your document.
Styling Text
There are many ways to stylize your text. Note that these stylizing options only apply to text outside of chunks. Below are some of the most common stylizing features:
Putting a single * around a word or words will italicize text.
For example, typing *R for Data Science* will italicize the text to look like R for Data Science
Similarly, a double ** around a word or words will bold the text.
For example, typing **Hello World** will italicize the text to look like Hello World
A single ` around a word or words will make the text styled as code. - For example, typing `library(tidyverse)` will italicize the text to look like library(tidyverse)
Please see Markdown Basics for more information and examples.
Question
Reproduce the following sentences to match the formatting:
Today, I will be using the tidyverse() package to wrangle my own data frame.
Structuring the Document
Headings
Structuring the document is also an important piece of writing reports. Sections heading are very helpful for helping you break up your work into digestable chunks, and also organize your writing in clear, separate thoughts. You can generate headings with a # in front of the text, and subheadings by adding additional #. Each additional # makes the subheading go down another level.
In addition to providing a dataset for your group to evaluate, your job in the first rotation in the final project is to prepare a document for each rotation in the project. You will be working under the Rotation 1 header for this submission. Include the following headers:
Rotation 1: Initial Data Proposal
Rotation 2: Variable Selection & Description
Rotation 3: Summary Statistics & Tables
Rotation 4: Data Visualization
Rotation 5: Ethics
Question
Make headings for each of the rotations listed above. Additionally, make a subheader for Rotation 1 that introduces the data.
Links, images, and footnotes
Links to URLs are also a helpful tool when crafting reports to guide the reader to outside resources. The basic structure of a link is the following: [here](https://www.google.com/). This will produce a link that takes readers to the specified URL when they click on the text. For example if you click here you will be taken to Google’s home page.
Similarly, you can link to an image with the code . The link can be either to an image saved locally on your computer, or a link to the image online. For example,  links to the rmarkdown hex logo shown below.
Footnotes are also a useful tool to provide the reader with more information/context that isn’t central to your text, but is easily accessible. Footnotes require two parts:
First, you put [^footnote-name] where you want the footnote symbol to appear. In place of footnote-name, choose a word that is unique in your document, and is informative to you.
Second, put [^footnote-name]: The text of the footnote somewhere nearby. Quarto will find it and place it appropriately at the end of your rendered file. 1 Please read the Quarto guide to footnotes for more examples.
Question
Using the sample code above, include the following in your write up:
A link to the page you downloaded the data from.
Include an image by linking to an online image related to your project
Include a footnote that includes information on the year(s) the data were collected
Setting global options
Every Quarto document starts with a block of settings written in a language called YAML. Many, many different options can be set in the YAML header, which then apply to the whole document. YAML headers are demarcated by three dashes (---) at the top and bottom.
For example, the YAML header for this document looks like this:
title: whatever you write here will appear in a large font at the top of the rendered document
editor: here we have specified that we want this file to be opened in a text editor, as opposed to the visual editor. We strongly recommend that you NOT use the visual editor in RStudio.
format: note how the items here are nested by indentation. This is important! YAML is not very forgiving, so messing up the indentation, or even spacing, can cause the build process to fail. Note that the HTML format can take many options. We recommend that you keep code-fold: true for your work in this course.
execute: these options control the execution of code chunks. Here, setting echo: true means that unless specified otherwise, all chunks will print their code in the output.
knitr: these options are similar to those under execute, but whereas the execute option apply to all languages, the knitr options only apply to R chunks.
editor_options: these options control how the source file is displayed in a text editor.
You are welcome to experiment with setting different global options in YAML.
Embedding resources
One option not set above is important to add, especially for your final project: embed-resources: true. Adding this directive bundles images, JavaScript libraries, and other dependencies right into the HTML output document. If you send your HTML document to someone else over email, or upload it to Moodle without including the option embed-resources: true, the document will lose all of its formatting, and none of the figures will show up. This means its very important to use embed-resources: true in the global YAML header if you plan on sending your document to other people.
Controlling code output
In addition to formatting text, there are also a variety of options for formatting your code chunks. These chunks allow you to run code in your document to import data, create figures and tables, or conduct some analysis. When creating code chunks, you will need to think carefully about what you want the reader to see. Do you want them to see the code? Just the output? Neither? Today we will review the most common customization options. Each of these options are written as part of the chunk header (the text between the brackets at the start of a chunk). Setting an option to true enables that option, and setting it to false turns it off. Generally when writing report, we do not want the reader to see code or messages, but just the cleaned output.
eval: true: Whether to evaluate a code chunk.
include: true: Whether to include anything from a code chunk in the rendered document. If include: false, the code will still be evaluated but the neither the code nor the output will be displayed.
echo: true: Whether to make the code visible in the rendered document. If set to false then only the output (but not the code) will be shown.
message: true: Whether to show any messages that appear when running a chunk.
warning: true: Whether to show any warnings that appear when running a chunk.
results: hide: Whether to hide the output from R.
These customization go at the beginning of an R chunk. In the chunk below, the chunk will be evaluated, but the code will not be shown and any warning messages that could appear are hidden.
Hide the code in the chunk that loads your chosen dataset into R, and hide any warning/messages.
Submitting this lab
Step 1: Final Project Prep, Rotation 1 - Setup and Introducing the Data
Step 1.1: Create Rotation Schedule
Each person in the group should have already selected one of the data sets they looked at in the pre-rotation last week. This will be one of the data sets your group works on for the final.
Next, use the code and instructions below to create a schedule for rotating your documents between group members.
Question
Use the c() function to create two vectors:
The first vector will be called my_group, and will contain the names of the members of your group. Put the first names of your group members in alphabetical order.
The second vector will be called group_datasets, where each team member will put the name of the one data set they want to contribute to the group. Make sure that the dataset names are in the same order as the corresponding group members in my_group.
Note: Each element should be in quotes. For example: c("Ben", "Rosie", "Scott")
Question
The below code is a function that will create a rotation schedule. Copy it into your rotation .qmd and run it. Do not modify it.
Create a schedule for rotations by running create_rotation_table(my_group, group_datasets).
This will return a table showing who will write about what dataset for each of the remaining labs.
Check: The schedule should be set up so that each person completes Rotation 1 for the dataset they chose (the same one that they completed Rotation 0 for). If this isn’t the case, your vectors likely aren’t in the same order. Make any necessary changes and run the code to create the table again.
Code
create_rotation_table <-function(group_vector, dataset_vector,labs =c("Lab 8: Formatting","Lab 9: Ethics","Lab 10: Figures","Lab 11: Ethics Codes","Lab 12: Bibliography")){# error checkif(length(group_vector) !=length(dataset_vector)){stop("Something is wrong. The number of data sets and team members do not match!")}# get number of team members members =length(group_vector)# create rotation for labs rotation_1 = group_vector rotation_2 = dplyr::lead(rotation_1, default =head(rotation_1, 1)) rotation_3 = dplyr::lead(rotation_2, default =head(rotation_2, 1)) rotation_4 = dplyr::lead(rotation_3, default =head(rotation_3, 1)) rotation_5 = dplyr::lead(rotation_4, default =head(rotation_4, 1))# turn into table rotation_table =t(data.frame(rotation_1, rotation_2, rotation_3, rotation_4, rotation_5))# rename rows/colsrow.names(rotation_table) = labscolnames(rotation_table) = dataset_vector# returnreturn(rotation_table)}
Under the header for Rotation 1, introduce your dataset. You should include the following information to give the next person who works on this document a clear idea of the data source.
Include a formatted hyperlink to the source.
Describe the source of the data and how data were generated. Is it a survey? Lab data? A Government report?
Explain what a row represents in your data. In other words, what is the unit of analysis?
For example, each row in the palmerpenguins data set represents a penguin.
Pick a single row in your data set, and interpret what each variable of interest represents.
For example, a specific row in your data may represent a 21-year-old female college student living in Northampton, Massachusetts with 15 years of education and who prefers dogs over cats.
Footnotes are also a useful tool to provide the reader with more information/context that isn’t central to your text, but is easily accessible. Footnotes require two parts: