3  Preparing and formatting assignments

This material provides instructions on how to prepare and format R Markdown documents for assignments.

Once you’ve worked through this tutorial, the Preparing and Submitting Your Assignment cheatsheet condenses these same steps onto one page — a quick reference to come back to for every assignment after this one.

3.1 Get your assignment file ready

Before you can start answering questions, you need to get the assignment file set up on your computer. That takes three steps.

3.1.1 Open your assignment RStudio project

In a previous tutorial it was suggested you set up a working root directory called “BIOL202_assignments” to host all your assignment work. You may have also created sub-directories, one for each of the three assignments. Regardless, in your root “BIOL202_assignments” directory locate the RStudio project file (it has a “Rproj” extension in the filename), and open it by double-clicking it.

3.1.2 Download the assignment Rmd file

The assignment file will be available to you for download from Canvas under the “Assignments” section. The file is actually an R Markdown file, and therefore has an “Rmd” extension. It is simply a text document (meaning it contains only text), but the syntax used therein is “markdown” syntax, and the file extension (Rmd) specifies it as an R Markdown file. You might recall reading about Markdown in the Biology Procedures and Guidelines document.

Make sure you save the Rmd file into your root “BIOL202_assignments” directory, or alternatively into the appropriate sub-directory.

A small assignment has been set up on Canvas, with the aim of you getting use to the assignment procedure. It is located under “Lab_materials” module. Download the file, and make sure it’s saved into your root directory (where your RStudio project is).

3.1.3 Open the assignment Rmd file

In RStudio, look in the “files” pane (bottom right) and locate your downloaded assignment Rmd file. Then click it to open.

This Markdown document includes the assignment questions, and serves as a starter document for your assignment.

Once you have opened the document, you’ll see the following text at the top:

Figure 3.1: Assignment markdown file header

Complete the following steps:

  • keeping the quotation marks, replace the “Practice assignment” text with the current assignment name
  • keeping the quotation marks, replace the “Firstname Lastname, Section YY” with your own Firstname Lastname and section number (e.g. ” Jason Pither, Section 04”)
  • keeping the quotation marks, replace the “Due date” with the due date of the current assignment, e.g. “September 21, 2025”
Warning

Don’t alter anything else at the top of the document, including the R Chunk that you see below the header.

  • save the Rmd file using a new name (so select file > “save as”), according to appropriate file naming conventions, such as “Pither_BIOL202_lab-assignment-01_V0.Rmd”. Recall that if you’re saving this on OneDrive, or in your local directory that is synced to OneDrive, then your file will be version controlled, so you don’t need to include a version number (“_V0”) in the filename.

You’re now ready to start working on your assignment, and doing literate programming using R Markdown.

Note

In RStudio, under the “Help” menu, you’ll find “Cheat Sheets” > R Markdown Cheat Sheet and R Markdown Reference Guide. Have a look at those!

3.2 What to include in your answers

The general approach is to enter your text answers and associated R chunks with code underneath each question.

Note

TIP: You will almost always need dplyr, ggplot2 and readr, plus the biol202 package that holds the course datasets. It’s advisable to include one R chunk right at the beginning of your document that loads them.

Note

TIP: To insert a new code chunk, you can either: Use the shortcut: Mac = Command+Option+I; Windows = Ctrl+Alt+I. Click on the Insert a new code chunk icon. You can also specify the coding language of the chunk using the drop-down menu.

3.2.1 Code chunk headers

Here’s an example code chunk in which packages are being loaded. You’ll notice some extra text in the header of the chunk.

Figure 3.2: Code chunk header with message suppression

The “load_packages” text is simply giving a name or “tag” to this R chunk. It is good practice to provide a unique name to each R chunk.

After the comma is message = FALSE. This tells R markdown to NOT display any messages associated with the R commands in this chunk when knitting the R Markdown document. For example, when loading some libraries R will provide a long list of messages in the process. When you “knit” the R Markdown document, R will run each R chunk in your document. By including the message = FALSE heading argument, you can avoid including this extra output in your knitted document (see also Common errors and their solutions).

Warning

The message = FALSE header argument is NOT something to include in all chunks by default. It should only be included if the code within the associated code chunk outputs a lot of unnecessary information that would otherwise clutter your knitted PDF document.

There will be routine steps to take for each question.

3.2.2 Import data

Each assignment question will indicate which dataset(s) you’ll need to answer the question, and where to locate / download these. In many instances multiple questions will use the same dataset, in which case you don’t need to load data for each question; just load it once.

Most course datasets come from the biol202 package, so loading one takes a single line — data() followed by the dataset’s name:

library(biol202)
data(example_data)

Some questions will instead ask you to import a CSV file (comma-separated values file) from a web address or from your own rawdata folder. That uses the read_csv function from the readr package, which you will meet in the importing data tutorial.

3.2.3 Load packages

Once you’ve loaded the data, you’ll now need to figure out how to answer the question by looking through the tutorials for the answer. And typically, to answer the question you’ll need to make sure you’ve loaded some packages.

If you’ve forgotten what “packages” are, refresh your memory at this tutorial.

For example, it’s likely you’ve already loaded dplyr, ggplot2 and readr (as advised above), but if a tutorial indicates you need another package, say the janitor package, then insert a code chunk with the following:

library(janitor)
Note

When working on your own computer, you only need to install a package once (unless you want to update an already installed package to the latest version, which is a rare event). If you’re working on a school computer (in a computer lab), you may need to install packages each time you log on to a computer, because the school computers delete local files daily. If you’re unsure what packages are already installed, consult the “packages” tab in the lower-right RStudio pane when you start up RStudio; installed packages are listed there.

3.2.4 Answer the questions

After you’ve imported the required data and loaded required packages, it’s time to answer the questions!

You simply insert any required text and R code (in R Chunks) after each question. The tutorials will provide the information required to answer the questions.

Note

TIP: The way to test out your code once it’s inserted in the R chunk is to press the green play button at the top right of the code chunk. This will run what’s in the chunk. You’ll be provided error statements if something goes wrong. If it works, it will provide you the output (and hopefully the answer!), and this is what you use to inform your written (typed) answer.

Here’s what you need to include in your answers:

  • Answer each question clearly and in full sentences. Make sure you answer specifically the question asked.

  • Verify that the code you used to answer the question is included in an R chunk and appears in the knitted document (this should happen automatically)

  • Verify that the output from each R chunk is included in your knitted document (this should happen automatically)

  • For any figures (graphs) that you produce, you must include a figure caption. See the next section for instructions.

  • If you use a graph to answer a question, refer to that graph in your answer

Note

REMINDER: As you work on your document, save frequently, and also knit your document frequently.

Note

TIP: You will often need/want to preview the document you are working on to ensure that everything is being formatted as you expected in the knitting process. The default setting is for the preview to open in a new pop-up window outside of RStudio, although you may find it useful to have it open in the Viewer panel within RStudio itself (particularly if you’re only working with one screen!). To change the preview location, click the Settings icon in the toolbar and select the option to “Preview in Viewer Pane”.

3.3 Setting up R Markdown for graphing

There are some special code chunk header arguments that need to be set in your Markdown document in order to:

  • include proper Figure captions with your figures (a necessity!)
  • set the dimensions of your figures

In each code chunk that includes code to construct a graph, your chunk header options should look like this in the top of the chunk, and there should be one blank line underneath before the main code starts. The following chunk produced the figure below. And recall that in the example below, the “bill_fig” text is simply the name I’ve given to this code chunk.

Figure 1: Histogram of bill depth among 151 Adelie penguins

The key parts are the “fig.cap =” argument, to which you provide the text you want to use as the figure caption. Then there’s the “fig.width =” and “fig.height =” arguments, which indicate the size of the figure when knitted. This will likely require some trial-and-error to get a good size, but start with the values in this example (4 for each).

Automated figure numbering

When you knit the document to PDF, you’ll see the “Figure X:” (with a number in place of the “X”) text was appended at the beginning of the caption phrase that was included in the chunk header, “Histogram of bill depth among 151 Adelie penguins”.

This feature - automatic figure numbering - was set within the header of the assignment markdown document:

Figure 3.3: Assignment markdown file header with figure caption option

The line “fig_caption = true” tells R Markdown and the knitting process to automatically include this part of a figure caption, “Figure X”, underneath each figure you produce. Where “X” will automatically be replaced with the appropriate number. For example, it will use “Figure 1:” for your first figure, “Figure 2” for your second, and so on.

Note

The figure captions will only appear correctly once you knit to PDF; captions do not appear in the preview provided within the editor pane. If a caption still doesn’t show up after knitting, see Common errors and their solutions.

3.4 Example question / answer

Below is an example of how to answer a question. You haven’t yet learned some of the functions we use here, but follow along for now, it’s just an example!

Note

There are almost always multiple coding approaches to get the right answer, some better than others. As long as your code and answer are accurate and make sense, you’ll get the marks!

Question 1. What are the minimum and maximum heights (variable name is “height_cm”) of students in the students dataset, which comes with the biol202 package?

As we learned in the [fictitious] “importing and exploring data” tutorial, the datasets we use in this course come with the biol202 package, so I load that package and then use the data function to make the dataset available. It gives me a “tibble” object called students:

library(biol202)
data(students)

The next step is to get an overview of the dataset. To do this, use the glimpse function from the dplyr package, which is already loaded.

glimpse(students)
#> Rows: 154
#> Columns: 6
#> $ height_cm          <dbl> 157, 165, 165, 163, 173, 170, 168, 157, 159, 182, 1…
#> $ head_circum_cm     <dbl> 55.50, 56.00, 55.00, 57.00, 60.50, 56.00, 56.00, 59…
#> $ number_of_siblings <dbl> 1, 3, 0, 2, 1, 1, 2, 3, 1, 3, 2, 2, 1, 0, 2, 1, 3, …
#> $ dominant_hand      <fct> Right, Right, Right, Right, Right, Right, Right, Ri…
#> $ dominant_foot      <fct> Right, Right, Right, Right, Left, Right, Right, Rig…
#> $ dominant_eye       <fct> Right, Right, Right, Right, Left, Right, Left, Righ…

This shows we have 154 rows (observations) and 6 columns (variables) total.

We can use the summary function to get some basic descriptive statistics, including the minimum and maximum of numeric variables. The summary function is part of the base R package, so no additional packages need to be loaded.

We also use the select function from the dplyr package to select which variable in the students tibble we wish to summarize.

The use of the “%>%” syntax is described in a later tutorial.

summary.height <- students %>% 
  select(height_cm) %>%
  summary
summary.height
#>    height_cm    
#>  Min.   :150.0  
#>  1st Qu.:165.0  
#>  Median :171.5  
#>  Mean   :172.0  
#>  3rd Qu.:180.0  
#>  Max.   :210.8

As shown in the output above, the minimum height was 150.0 cm and the maximum student height was 210.8 cm.

Note

TIP: You’ll note that functions and package names above are highlighted in grey. When writing in markdown, it’s good practice to encompass function names and package names in single backticks, i.e.`dplyr`. Backticks are typically located with the tilden (“~”) key on your keyboard.

3.5 Knitting your assignment to PDF

All assignments are to be submitted to Canvas as PDF documents.

As you learned in a previous tutorial, simply click on the “knit” button and select PDF. Your PDF file will adopt the same name as your markdown file, but it will have a “pdf” extension rather than an “Rmd” extension.

Once you have knitted your assignment to PDF, open up the PDF document, and verify that it looks correct, and be sure to check all your spelling, and that figures / tables are appropriately formatted etc…

If you need to fix something, close your PDF file, go back to your R Markdown document and do the edits there. Save, then knit again! If you hit an error while knitting, check Common errors and their solutions.

3.6 Submit your assignment

Once you’re happy with the PDF you created, it’s time to submit both your markdown file (.Rmd file) and your PDF document to the appropriate place in Canvas. Submitting both files enables markers to check where things went wrong if there are any knitting errors.

It’s a good idea also to verify afterwards that your PDF document did indeed upload correctly.