Reproducible Reports

Overview

At this point in the course, we anticipate that your synthesis project is–if not finished–in a state where some amount of external-facing products would be beneficial (see our suggested milestones page). “Computational notebooks” (e.g., Quarto documents, Jupyter Notebooks, R Markdown files, etc.) are an excellent choice for creating reproducible documentation that has direct ties to scripts or data files relevant to your project. Effective notebook files allow you to leverage both your technical skills and your scientific communication skills.

This module focuses on the structure and content of these notebooks from a primarily technical lens, so please consult the communicating findings module for the team science perspective.

Learning Objectives

After completing this module you will be able to:

  • Describe contexts where computational notebooks are useful
  • Identify the three fundamental elements of a typical notebook
  • Use Markdown syntax to accomplish text styling
  • Create notebooks that include a blend of plain text and embedded code chunks
  • Make a Quarto website
  • Define the purpose of GitHub Actions
  • Deploy a notebook with GitHub Pages

Preparation

  1. Install Quarto
  2. Double check that your group’s GitHub repository is up to date

Networking Session

To Be Determined!

Making a Website with Notebooks

Many of you are likely already familiar with the fundamentals of notebook files. So, while we could practice these skills making relatively simple notebook versions of your most important scripts, instead we’ll be making individual or team websites! This is only a little more work than making a single file and will give you a valuable portfolio addition while you practice these skills.

Notebook Structure & Value

Files that combine plain text with embedded code chunks are an excellent way of reproducibly documenting workflows and faciliating conversations about said workflows (or their outputs). Examples of notebook files include Quarto documents, Jupyter Notebooks, and R Markdown files. Regardless of the specific type, all of them function in the same way. Each of them allows you to use code chunks in the same way that you might use a typical script but between the code chunks you can add–and format–plain, human-readable text. Arguably you could do this with comments in a script but this format is built around the idea that this plain text is intended to be interpretable without any prior coding experience. The plain text can be formatted with Markdown syntax (we’ll discuss that in greater depth later) but even unformatted text outside of code chunks is visually ‘easier on the eyes’ than comment lines in scripts.

Another shared facet of notebook interfaces is that they are meant to be “rendered” (a.k.a. “knit”) to produce a different file type that translates code chunks and Markdown-formatted text into something that looks much more similar to what you might produce in Microsoft Word or a Google Doc. Typically such files are rendered into PDFs or HTMLs though there are other output options. These rendered files can then be shared (and opened) outside of coding platforms and thus make their content even more accessible to non-coders.

In synthesis work these reports can be especially valuable because your team may include those with a wealth of discipline insight but not necessarily coding literacy. Creating reports with embedded code can enable these collaborators to engage more fully than they might otherwise be able to if there was essentially a minimum threshold of coding literacy required in order to contribute. These reports can also be useful documentation of past coding decisions and serve as reminders for judgement calls for which no one in the team remembers the rationale.

LTER SciComp Workshop Materials

The workshop materials we will be working through live here but for convenience we have also embedded the workshop directly into the SSECR course website (see below).

Activity: Making a Team / Personal Website

Note that you do not need to keep your website up after you make it if you already have one or don’t want one but this activity will still be good practice regardless.

Eventually you will likely want a team-wide website. You are absolutely welcome to make this during today’s module but because the first draft must be made by a single person, all but one member of your group must work on individual sites instead. You can (and should!) revisit your site as a group to make sure all of you are happy with it but creating individual sites today will help all of you develop ‘muscle memory’ in this arena.

Customizing Your Quarto Website

You can customize a Quarto website by editing the _quarto.yml file. There are a lot of options in this realm so we recommend that you cannibalize elements from other Quarto websites you like as you find them. You may find some of the later modules in the above workshop useful in this regard. Feel free to explore those materials and reach out to SSECR design team members if you have questions!

Activity: Customize Your Website

Revisit the Quarto website you created for the prior module and

  • Decide on your ideal color palette
  • Create both a light theme and a dark theme

Additional Resources

Papers & Documents

Workshops & Courses

Websites