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 our 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

Day 1 communal notes doc
- Contains resources (from us and you!) and areas for note-taking
Sample data
- Sample model output data for coding demonstrations

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.

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 language
Quarto basics
How to set up a reporting workflow using asar
How to create semi-automated figures and tables with stockplotr

Overview of `asar`-based reporting workflow

Main steps for creating a stock assessment report with asar:

Install packages
Convert model output into format usable by asar
Create the report skeleton
Make child docs containing figures and tables (made with stockplotr or by other means)
Fill in child docs with text
Render report
Add accessibility features (PDF tags and alternative text for figures)

Tip

Open the asar cheatsheet for a visual overview of the main workflow!

Markdown

What is markdown?

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

Why use R markdown?

R markdown, or “Rmd” for short, allows you to create amazingly dynamic reports. With R markdown, you can embed your R code directly into your documents. When you “knit” the document, the code is executed, and the results— like figures, tables, parameters, citations, and other outputs— are automatically inserted into the final report.

A major reason why R markdown is incredibly useful: it 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.

Opening a document

Let’s open a new document. We’ll open a Quarto document (Qmd) because it also runs Rmd code; it’s a newer document type that can handle more than Rmd can.

In RStudio, go to File > New File > Quarto document….
A dialog box will appear. If you wish, you can give your document a title and author.
For the output format, you can select HTML, PDF, or Word. Let’s choose HTML.
Click OK.

You’ll now see a new Quarto file with some default text. Let’s explore some ways you can take advantage of this powerful document type.

The core components

The YAML Header: This is the section at the top of the file, enclosed by triple dashes (---). It contains metadata about the document, like the title, author, and output format.
Text and Formatting: This is where you’ll write the narrative of your report using Markdown syntax.
Code Chunks: These are sections of the document where you can embed and run your R code.

Common uses in `asar` reports

Now, let’s dive into some of the most common features you’ll be using when creating asar reports.

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”.

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 $$

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.

To cite a reference in the text, use the @ symbol followed by the citation key (e.g., @Biddle_1992). R Markdown will automatically format the citation and add it to the “References” section towards the end of your report.

20 minute break for questions & practicing

Practice exercises: Markdown

Create a new quarto document
Add the following elements:

Level 1 header (call it “Sandwiches”)
Level 2 header (call it “My favorite sandwich”)

Under heading level 2, add a sentence that describes your favorite sandwich. Italicize “favorite” and bold the sandwich name.
Add an unordered list with the sandwich’s ingredients.
Add an ordered list with the steps needed to make the sandwich.
Find the first ingredient in the list and add a link to its wikipedia page.
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 for Practice exercises: Markdown

Create a new quarto document

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

Add the following elements:

Level 1 header (call it “Sandwiches”)
Level 2 header (call it “My favorite sandwich”)

Under heading level 2, add a sentence that describes your favorite sandwich. Italicize “favorite” and bold the sandwich name.
Add an unordered list with the sandwich’s ingredients.
Add an ordered list with the steps needed to make the sandwich.
Find the first ingredient in the list and add a link to its wikipedia page.
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.

Quarto

Why use Quarto for reports?

Quarto is an ideal platform for building reproducible reports, which are denoted with a .qmd (Quarto Markdown) extension type. Why?

It allows you to combine narrative text, source code (like R), and the outputs of that code (like tables and figures) into a single, polished document.
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.

Skeleton setup

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.

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.

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 an asar YAML:

---
title: 'Stock Assessment Report Template'
author:
  - name: 'FIRST LAST'
    affiliations: 
      - name: 'NOAA Fisheries' 
        address: 'ADDRESS' 
        city: 'CITY' 
        state: 'STATE' 
        postal-code: 'POSTAL CODE' 
date: today
keep-tex: true 
mainfont: 'Latin Modern Sans' 
cover: 
pdf-engine: lualatex
format: 
  pdf: 
    documentclass: article
    papersize: letter
    number-sections: true
    template-partials:
      - 'support_files/before-body.tex'
      - 'support_files/_titlepage.tex'
    include-in-header:
      - 'support_files/in-header.tex'
    toc: true
    sansfont: 'Latin Modern Sans'
    lof: true
    lot: true
    titlepage-geometry: 
      - top=2in
      - bottom=1in
      - right=1in
      - left=1in
output-file: 'species_SAR_2025' 
params:
   office: ''
   species: 'species'
   spp_latin: ''
bibliography:  
  - asar_references.bib
csl: support_files/cjfas.csl
---

We will explore the components of the yaml in the Day 2 curriculum.

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.

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 Rmarkdown, the code chunk structure in Rmarkdown 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.

Break for questions

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.

Questions, comments, and feedback

Please navigate to the Feedback heading and tell us what you thought about today’s workshop. Only 3 simple questions!

What went well?
What could be improved?
What is a question you still have?

Objectives

Introduction

Icebreaker

Code of conduct

Who are we?

How to engage with us

Materials for today’s lesson

Workshop overview

Purpose and benefits to you

Challenges faced by stock assessment scientists

Challenges from a national perspective

Scope of workshop

Overview of asar-based reporting workflow

Markdown

What is markdown?

Why use R markdown?

Opening a document

The core components

Common uses in asar reports

Parameters

Formatting

Math and Equations

References and Bibliography

Quarto

Why use Quarto for reports?

Skeleton setup

Relative pathnames

YAML

Code Chunks

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

Questions, comments, and feedback

Overview of `asar`-based reporting workflow

Common uses in `asar` reports