Day 1

Objectives

  • Identify purpose and scope of workshop
  • Learn how R markdown can be used to enhance {asar} reports
  • Understand how Quarto is used to structure an {asar} report
  • Install software necessary to build an {asar} report

Introduction

Icebreaker

Welcome! Please open the Day 1 communal notes doc and participate in the icebreaker exercise.

Code of conduct

Everyone participating in this workshop is required to abide by the terms of our Code of Conduct. We encourage you to contribute to a positive environment for our community by:

  • Demonstrating empathy and kindness toward other people
  • Being respectful of differing opinions, viewpoints, and experiences
  • Giving and gracefully accepting constructive feedback
  • Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
  • Focusing on what is best not just for us as individuals, but for the overall community

If you believe that someone is in violation of the Code of Conduct, please report the incident to the workshop instructors and/or the community leaders responsible for enforcement using this form.

Who are we?

Sam Schiano and Sophie Breitbart are contractors with ECS Federal working in support of the NOAA Fisheries National Stock Assessment Program. Our work primarily focuses on stock assessment workflows by creating tools to help stock assessment scientists increase throughput. We are developing two R packages, {asar} and {stockplotr}, using an open science framework that prioritizes transparency and reproducibility.

How to engage with us

Questions: Please raise your hand, or write your question in the chat, at any time. Depending on our schedule, we may ask that you save larger questions for breaks.

Materials for today’s lesson

Break for questions

Workshop overview

Purpose and benefits to you

By the end of this workshop, we hope that you come away with the knowledge and confidence to write your next stock assessment report using a reproducible, efficient, and transparent workflow based on {asar} and {stockplotr}.

{asar} is designed to:

  • Reduce the barriers of entry to using Quarto
  • Familiarize stock assessment scientists with reproducible workflows
  • Shift towards a more concise reporting format
  • Move towards a more centralized workflow across NOAA Fisheries

An {asar} workflow can help ease the following challenges:

Challenges faced by stock assessment scientists

  • Achieving accessibility standards (section 508 compliance)
  • Iteratively changing a report during review
  • Meeting variable expectations for report structure and language
  • Following structure of inherited assessments
  • Collaborating

Challenges from a national perspective

  • Differences in reporting among regions
  • Divergent expectations from associated councils
Note

We have communicated with representatives from each council and all have expressed support for our proposed standardized report template.

Scope of workshop

During this workshop, we will cover the following topics:

  • Markdown
  • Quarto basics
  • How to set up a reporting workflow using {asar}
  • How to create semi-automated figures and tables with {stockplotr}

Markdown

According to RStudio, markdown is “an easy-to-write plain text format”; not exactly a language, but a formatting style.

Common uses in {asar} reports

Formatting

R Markdown uses a simple syntax for formatting your text. Here are some of the most common formatting options:

  • Headers
    • # signifies a top-level header
    • ## signifies a second-level header (etc.)
  • Emphasis
    • *italic* for italic text
    • **bold** for bold text
  • Lists
    • Unordered lists: Use * or - at the beginning of a line.
    • Ordered lists: Use numbers followed by a period.
  • Links
    • [link text](URL)

Math and Equations

You can include LaTeX-style math equations in your report.

  • Inline math: Wrap your equation in single dollar signs: $A = \pi * r^2$
  • Block equations: Wrap your equation in double dollar signs to display it on its own line: $$ E = mc^2 $$

Quarto

Why use Quarto for reports?

Quarto is an ideal platform for building reproducible reports, many of which contain markdown. These reports are denoted with a .qmd (Quarto Markdown) extension type. For those familiar with R markdown, Quarto is like a more flexible and powerful version of that.

So, why should you Quarto to build reports?

  • It allows you to combine narrative text, source code (like R, Python, LaTeX, and more), and the outputs of that code (like tables and figures) into a single, polished, dynamic document. When you “knit” the document, the code is executed, and all of those components are inserted into the final report.

  • Anyone with the same files can reproduce that document, which goes a long way in promoting scientific integrity.

  • You can produce reports in several formats like HTML, PDF, and Word.

  • Using a platform like Quarto saves time and reduces errors. If your data changes, you don’t have to manually rerun your analysis and copy/paste the results. You just re-knit the document, and everything is updated automatically.

Components of Quarto reports

YAML

The YAML is the block of text at the very top of your main .qmd file, enclosed by triple dashes (—). It provides metadata for your document– i.e., how to build the report.

Common settings in the YAML include:

  • title
  • author
  • date
  • format (For {asar}, this will be PDF or HTML)

Here is an example of a basic YAML:

---
title: "Stock Assessment Report"
author: "Patrick Star"
date: today
---

Code Chunks

As we previously mentioned, the beauty of using Quarto is that it allows the user to integrate text and code throughout their reports making them super reproducible.

The basics of a code chunk (chunk) are:

  • the language (R or python)
  • chunk options
  • code

These three things get wrapped together within two sets of three back ticks (```) to allow a user to run code.

```{r}
#| label: ex-chunk
#| eval: false
#| warning: false
#| echo: false
#| fig-cap: This is my figure caption.
#| fig-alt: This is my alternative text.
#| tbl-cap: This is my table caption.
x <- 1 + 1
```

There are a variety of chunk options, but the ones you will see consistently throughout this workshop are listed in the example above. See more chunk options in the markdown vignette.

Note

In the “label” option, for tables and figures, you will need to prefix the label with either “fig-” for a figure or “tbl-” for a table.

For those familiar with R markdown, the code chunk structure in R markdown documents will work with Quarto. The main difference is that the chunk options are now brought into the code chunk itself with a “#|” proceeding each option.

Parameters

Parameters allow you to create dynamic reports. You can define parameters in the YAML header and then reference them in your text and code.

For example, you could have a parameter for the species you’re writing about:

---
title: "Stock Assessment Report"
author: "Patrick Star"
date: today
params:
  species: "Petrale sole"
---

Then, in the body of your report, you can reference this parameter like this:

“The native range of `params$species` spans from…”

When you knit the document, `params$species` will be replaced with “Petrale sole”.

References and Bibliography

You can easily add citations to your report. We provide an asar_references.bib file in the “report” folder with hundreds of citations for you to reference, though you can add your own to the file too. Here are resources to export BibTex from Google Scholar, EndNote, Zotero, and a guide for connecting Zotero with RStudio.

To cite a reference in the text, use the @ symbol followed by the citation key (e.g., @Biddle_1992). Quarto will automatically format the citation and add it to the “References” section towards the end of your report. The bib file will be referenced in your {asar} report’s YAML.

Here’s an example entry from the .bib file:

@article{Biddle_1992,
  title={Repton and the Vikings},
  volume={66},
  DOI={10.1017/S0003598X00081023},
  number={250}, journal={Antiquity},
  author={Biddle, Martin and Kjølbye-Biddle, Birthe},
  year={1992},
  pages={36–51}
}

Glossary and survey names

Maintaining a consistent list of acronyms (i.e., a glossary) is essential for reader clarity and accessibility. However, maintaining a glossary manually poses multiple challenges:

  • Tracking the first, defined usage vs. subsequent, shorthand usages of acronyms in reports
  • Capturing every acronym in a glossary at the end of your report
  • Ensuring the acronym will be read properly by a screen reader

Use our automated system to ease this step! It performs these tasks for you:

  • Automatically spell out the full meaning of each acronym upon its first usage
  • Use the shorthand version of each acronym after its first usage
  • Add each acronym to a glossary table at the end of your report
  • Format acronyms such that they’re pronounced correctly by screen readers

Finding the glossary

When you run asar::create_template(), you’ll see a glossary (“report_glossary.tex”) in your “report” folder. Take a look at the uploaded version, here.

Glossary structure

Order: The glossary is sorted alphabetically. Case can differentiate entries (e.g., “M” (natural mortality) is different from “m” (meter(s)).)

Structure: Each acronym has its own line, structured like this:

\newacronym{<"label" or "key">}{<"short form" or "acronym">}{<"long form">}

  • “label” (or “key”): The term written in the report body. The label links the short form (see below) to the glossary entry. In our glossary, labels are typically lowercase. Examples: bcurrent, noaa.

  • “short form” (or “acronym”): The term actually shown when the report is rendered. The short form may have formatting applied to it. Examples: $B_{current}$ (which will render as \(B_{current}\)), NOAA.

  • “long form”: The meaning of the short form. Examples: current biomass of stock, National Oceanic and Atmospheric Administration.

Here are two entries using the examples mentioned above:

\newacronym{bcurrent}{$B_{current}$}{current biomass of stock}

\newacronym{noaa}{NOAA}{National Oceanic and Atmospheric Administration}

Note

You can edit the glossary by altering, adding, or removing entries in the “report_glossary.tex” file.

Using acronyms in reports

First, check if the glossary contains your acronym; if it doesn’t, you can edit the file and add it yourself.

Once your acronym is in the glossary, find your acronym in your report and encase it in curly brackets ({}), with “\gls” preceding it. For example, to indicate “ABC” is an acronym, you would write \gls{ABC}. Use this notation each time you use the acronym in your text.

Your text will look like this:

This is the first instance of \gls{ABC}. Here, \gls{ABC} is used a second time.

And it will render like this:

This is the first instance of Acceptable Biological Catch (ABC). Here, ABC is used a second time.

Survey names

Many people refer to surveys with nicknames or “informal” names that do not match up with administrative documentation. To facilitate communication in the reporting process, we have added survey names to the glossary.

Informal survey names (i.e., nicknames used to refer to surveys that are not correct) are listed in the “Acronym” column.

Formal survey names (i.e., the correct survey names) are listed in the “Meaning” column.

For example, the “Atlantic Surf Clam & Ocean Quahog Dredge” is sometimes called the “clam survey”.

\newacronym{clam survey}{Clam Survey}{Atlantic Surf Clam & Ocean Quahog Dredge}

This text…

In 2025, the \gls{clam survey}…

…will render like this:

In 2025, the Atlantic Surf Clam & Ocean Quahog Dredge (Clam Survey)…

Tips for Quarto documents

Modular setup with a skeleton

When you run asar::create_template(), you will receive a “report” folder with several files within it. One of the most important files is what we call the “skeleton”: a .qmd file containing chunks that run other files, then places the rendered contents of those files within one report.

Those other files are what we call “child documents”. For example, your report introduction will be written in a child document. Your figures and tables will be placed in respective child docs, too.

This setup avoids placing your entire report in one massive .qmd file, facilitates asynchronous collaboration with your colleagues, and keeps your project organized (in a “modular” fashion).

Relative pathnames

Important

Only files with paths relative to the Quarto doc will load!

Quarto projects are self-contained such that it can only find files if you tell it where to look relative to the location of the .qmd file. To Quarto, the location of that .qmd file essentially becomes the root of your directory.

For example, imagine your project has this structure:

report/
├── SAR_species_skeleton.qmd
├── 01_executive_summary.qmd
├── 02_introduction.qmd
└── extra_data/
    └── red_fish.csv
    └── blue_fish.csv

To load ‘red_fish.csv’ inside SAR_species_skeleton.qmd, you would use a relative path:

my_data <- read.csv("extra_data/red_fish.csv")

This would work even if your working directory is not the “report” folder.

NoteTesting your understanding

True or False: If you define a variable (e.g., x <- 10) in the R console while you are working, that variable will be automatically available and usable inside your Quarto code chunks when you render your report.

20 minute break for questions & practicing

  1. Create a new quarto document
  2. Add the following elements:
  • Level 1 header (call it “Sandwiches”)
  • Level 2 header (call it “My favorite sandwich”)
  1. Under heading level 2, add a sentence that describes your favorite sandwich. Italicize “favorite” and bold the sandwich name.
  2. Add an unordered list with the sandwich’s ingredients.
  3. Add an ordered list with the steps needed to make the sandwich.
  4. Find the first ingredient in the list and add a link to its wikipedia page.
  5. Your instructors are hungry, and they’re demanding that you split your sandwich with them. Use an inline mathematical notation to write the fraction necessary to feed the three of you.
  1. Create a new quarto document

Answer: Follow directions in the Day 1 “Opening a Document” section

  1. Add the following elements:
  • Level 1 header (call it “Sandwiches”)
  • Level 2 header (call it “My favorite sandwich”)
  1. Under heading level 2, add a sentence that describes your favorite sandwich. Italicize “favorite” and bold the sandwich name.
  2. Add an unordered list with the sandwich’s ingredients.
  3. Add an ordered list with the steps needed to make the sandwich.
  4. Find the first ingredient in the list and add a link to its wikipedia page.
  5. Your instructors are hungry, and they’re demanding that you split your sandwich with them. Use an inline mathematical notation to write the fraction necessary to feed the three of you.

Answers: Add code like the following:

# Sandwiches

## My favorite sandwich

My *favorite* sandwich is a **peanut butter and jelly sandwich**.

Ingredients:

- [peanut butter (PB)](https://en.wikipedia.org/wiki/Peanut_butter)
- jelly
- bread

Steps:

1. Get two slices of bread
2. Spread PB on one side of one slice of bread
3. Spread jelly on one side of the other bread slice
4. Stack the PB slice on top of the jelly slice so that PB and J meet in the middle of the sandwich.
5. Eat!

I'll split my sandwich into three pieces so that each person can get $1/3$ of the sandwich.

Install packages and get ready for tomorrow’s material (if need be)

Important

Before we begin using {asar} and {stockplotr} tomorrow, we highly suggest that you ensure that you’ve completed the pre-workshop checklist.

Final reminders

  • We offer two weekly “office hours”. For the Google Meet links, please see the National Fish Assessment Chat Space or the Assessments Events Google Calendar.
    • Monday, 4–5 PM ET: Drop in for 1-on-1 help with using {asar} or {stockplotr} for your stock assessment reports.
    • Wednesday, 2–3 PM ET: Join us to help develop these tools and/or learn about the development process. No package development experience is necessary- only an interest to learn. We’ll post the specific weekly topic every Wednesday morning. We’re also available for regular 1-on-1 help.
  • NOAA Open Science offers several “help desk” hours on Wednesdays. Jon Peake hosts. This time is great for general questions about markdown, Quarto, Git and GitHub, and more
  • We will be holding office hours tomorrow 30 minutes before the next session starts for any questions.