Individual assignment 4

Instructions

The purpose of this assignment is to ensure that everyone gains hands-on practice creating reproducible reports using Quarto.

Throughout the pre-requisites for DSCI 310, you have become familiar with using Jupyter Notebooks to interweave narration and runnable code into a single document. This allowed you to pass your analysis over to a co-worker or reviewer, who could reproduce your work by running your notebook from top to bottom.

But are Jupyter Notebooks all there is to creating reproducible reports? Not entirely… For example, Jupyter Notebooks struggle with organization and configuration. Imagine you have an extremely long and complicated report packed into a single Jupyter Notebook. Writing out a table of contents, formatting a bibliography, and adding labels to figures can become extremely cumbersome, especially as they evolve with your analysis during the review process.

Imagine you have 25 figures and tables labelled 1 to 25 and you decide to add a new figure at the very start of your report; figure 1 now needs to be renamed to figure 2, table 2 now needs to be renamed to table 3, figure 3 now needs to be renamed to figure 4…

This is where Quarto (and related tools) can come in handy. Although they have their own set of disadvantages, they are certainly an improvement over plain Jupyter Notebooks. They allow for the automatic creation and formatting of a table of contents, a bibliography, and those pesky figure labels, among many other features. During this individual assignment, you will start to familiarize yourself with Quarto reports, start to understand their advantages and disadvantages, and begin to recognize their similarities and differences from basic Jupyter notebooks.

Exercise instructions - Quarto

We suggest you read through the instructions first before doing them in sequence.

Step 1

Goal: Create a copy from the template repository.

• Create a copy of either the R template repository or the Python template repository on GitHub.com under your personal username

Notes:

• Do not create it under the DSCI-310 organization
• We, the teaching team, also need to be able to see this repository in order to grade it so we strongly suggest making it public.

Step 2

Goal: Get familiar with the repository

Inside the the R template repository or the Python template repository, there are several directories and files. Here is a quick rundown of each:

• data: contains data used in the analysis (do not edit)
• reports: contains the Quarto report file (ends in qmd_example.qmd) that contains the narrative of the analysis report and the code to display the analysis artifacts (tables and figures) (incomplete - you will need to edit this), and the BibTeX references file (references.bib) for the report (do not edit)
• Makefile: declares commands used to build the Quarto report (do not edit)
  • This file has all the commands you need to do this assignment.
• results: output of the script in source
• source/generate_figures.R or source/generate_figures.py: a script that performs the analysis and outputs various plots and a table that are to be used in the report (do not edit)

Step 3

Goal: Familiarize yourself with the Makefile targets

• The Makefile has all the targets needed to render the final Quarto report.
• You will want to have GNU Make build the qmd target to do this.

Notes:

• The HTML version of the report is saved to docs/qmd_example.html
• The PDF version will be saved to docs/qmd_example.pdf
• The Makefile commands will help you

Step 4

Goal: Create the example report so that it is a polished academic manuscript.

Edit reports/qmd_example.rmd (using either R or Python Quarto syntax, the choice is yours) so that:

1. Add header formatting to sections (e.g., “Aim”, “Data”, “Methods”, “Results”, “References”) and Quarto configuration so that a table of contents that is automatically generated from the document headers will be created when the document is rendered (docs on how to do this)
2. Add correctly formatted inline bibtex references so that a nicely formatted reference list will be present at the end of the document (docs on how to do this)
3. Edit the figure formatting (docs on how to do this) so that Quarto:
   • automatically numbers them
   • has a label for easy cross referencing
   • controls the figure sizes so the figures are not too big (in particular the second figure in the report should be only 60-70% of the default width)
4. add a table description argument so that they are automatically numbered by Quarto and use cross referencing to link to the table if/when it is discussed in the text (docs on how to do this)
5. Edit the narrative so it uses cross-referencing to refer to the figures and tables instead of having their reference hardcode the figure and table numbers.
6. replace the ??? in the Quarto report narrative text with inline Quarto code, so that the text will be automatically updated with the correct value (docs on how to do this)
7. change the code chunk options so that no code is viewable in the rendered report, just the code outputs where needed (e.g., figures and tables) (docs on how to do this)
8. (optional) Turn on GitHub pages so that it serves up the docs directory so that the report is viewable on the web.

Submission instructions

You will submit a PDF to Gradescope for individual assignment 3 that includes:

1. A link to the GitHub.com repository that you create for this assignment.

2. (optional) link to the HTML report served on GitHub pages.

Rubric

This assignment will be graded for completion as follows:

Grade	Description
110%	All 6 of the required edits to the .qmd document above were met and the HTML version of the report was served up on GitHub pages
100%	All 6 of the required edits to the .qmd document above were met and the report generates a working PDF and HTML file via the Makefile.
85%	5/6 of the required edits to the .qmd document listed above were met.
70%	4/6 of the required edits to the .qmd document listed above were met.
55%	3/6 of the required edits to the .qmd document listed above were met.
40%	2/6 of the required edits to the .qmd document listed above were met.
25%	1/6 of the required edits to the .qmd document listed above were met.
0%	The assignment was not attempted.

• You will only get the extra points for serving up the HTML version of the report on GitHub pages if all of the main assignment components were completed.