This week will shift gears and talk about writing reports using markdown via Quarto (the next-gen R Markdown). There are many on-line tutorials for R Markdown (which is compatible with Quarto) which will cover the basics. I’ll focus on some of the aspects that can really speed up your work:

  • automating the making of tables and figures
  • duplicating tables or figures by looping over a variable
  • using Work templates to change the look and formatting

AND today I will show Quarto, which fixes many of the things that were hard with R Markdown reports. Note Quarto is part of RStudio 4.2.1 now; not a separate software that you have to install.

Today’s topics

  • Quatro book orientation. Book is what we want for a big report with multiple chapters.
  • How to tackle your big report: strategy and workflow.
  • A repo set up to do a big report with lots of tables, list of figure and tables, figures, references, etc.

Intro to R Markdown/Quarto?

Today is not an intro lecture. I am focusing on big reports with Quarto/R Markdown.

How do I learn R Markdown?

  • Google “R Markdown tutorial”. There are so many.
  • In RStudio, go to File > New File > R Markdown… to create a blank template. Click Knit in the in the navbar (icon is a ball of yarn).
  • In RStudio, click Help > Cheatsheets. Start there and learn by doing.
  • Next, start copying from your colleagues who post on GitHub and use R Markdown/Quarto. Look for the GitHub icon on their online material to see source code.

Set-up

I will be using RStudio Cloud so that you can follow along and you won’t have to install anything.

But when you are ready, upgrade (or have your IT upgrade) RStudio to the latest version. Then do New Project (little arrow in top right) -> New directory -> Quarto xyz (choose any you want to play with). Then click Render and install any necessary packages. Note RStudio now installs {tinytex} (fingers crossed) so rendering to PDF should work.

Let’s dive in!

Structure

  • index.qmd file. Our first page. Must have this.
  • .qmd files. Our content. Chapters etc.
  • _quarto.yml file. How to put our chapters together.
  • references.bib

Knit to different formats

  • Word, PDF, HTML are defaults. *I had to add docx: default to _quarto.yml
  • You can customize this as you wish.

Adding content

I am going to use the visual editor mostly, though I’ll jump to the source code as needed.

  • Text
  • Figures + cross-references
  • Tables + cross-references
  • References

How did I set up the Quarto book workspace and repo?

In RStudio Cloud, I can easily create Quarto (qmd) documents, but what I am showing today is a Quarto project. I don’t think I can do that (yet) in RStudio Cloud, so let me show you how I created what you see at the hello_quarto_book RStudio Cloud workspace.

  • Open RStudio on my laptop. I have RStudio 2022.07.1+554 for Intel Mac (not M1) installed on my M1 Mac Air.
  • File > New Project > New Directory > Select Quarto book from the templates. Select to make it a Git repository.
  • This creates a project everything set up for a Quarto book
  • I did add some extra bib entries to references.bib.
  • Then I published this new repo on GitHub.
  • Then I opened RStudio Cloud, clicked new workspace and clicked “from Git repository”. Default sharing is private, so I clicked on the little lock icon to change that to public.
The exact steps for publish to GitHub step

Next I pushed this new Git repo up to GitHub and the RVerse GitHub organization. This is my actual work (as opposed to teaching) workflow. * First I added a main branch because RStudio doesn’t do that by default (???). Click on the Git tab, look for the branch icon (diamond with some rectangles), add a branch called main. * Then I switched to GitHub Desktop. added the repo in GitHub Desktop. File > Add local repository. * Now a button to Publish to GitHub pops up (in GitHub Desktop top nav bar) and I clicked that. * Now everything is synced up to GitHub.

Note, I teach the following workflow: Create repo on GitHub and make sure to check the button to add Readme file. Clone that repo onto your computer via GitHub Desktop or RStudio, say. Add your new files to the clone on your computer. Push changes up to GitHub. Why do I teach it this way? It is basically bombproof and the last thing you want when learning to work with Git is tie yourself in knots. It uses only the 3 core Git+GitHub skills that I teach so no need to learn more stuff.

A government report

Follow along on RStudio Cloud

Get organized

General set-up

  • Be as modular and simple as you can.
  • Don’t make everyone in your team be the markdown/Quarto wizard. You only need one person to build the framework.
  • Use simple child qmd (or Rmd) files so that other team members work only on simple qmd/Rmd flat files.
  • Copy reports built by others who are doing something similar to you. TALK within your center or across centers and share work.

Plan figures and tables

Putting raw code for figures and tables in your documents is not a good long-term strategy. Saves time now (maybe) but equals suffering and wasted time later.

  • Plan what types of figures or tables you need
  • Write a separate qmd/Rmd files, script or functions.
  • Try to be modular rather than custom figures and tables for every use.
  • Don’t put all your tables or figures in one huge file: Table xyz.Rmd/qmd, Table abc.Rmd/qmd. Have your dedicated markdown wizard figure out the automatic numbering.
Note, in practice, you need a proto-typing phase while working on the report when tables and figures source code is in the chapter files. Try to move out of that sooner than later.

Cross-references

This used to be horribly and is now easy with Quarto.

For example, we can make a figure with the chunk label fig-plot like so. You must use the fig- prefix.

```{r}
#| label: fig-plot
#| fig-cap: "Plot"

plot(cars)
```

The later in the text we use @fig-plot to get @fig-plot.

This is a plot of some data

This is a plot of some data

See the Quarto cross-ref page for how to do cross-references for images, figures, and table.

References

This used to be hard. Now easy with Quarto. Go into visual mode and type @ and it’ll auto-suggest based on your .bib files in your project or any Zotero bibs you have on your computer. Or you can paste in a DOI and it’ll add that to your references.

Chunk labels

Don’t duplicate chunk labels across your documents.

When using Quarto (or R Markdown), it is best not to use chunk labels in the your Rmd/qmd children unless you need to for figures and tables. It’s too easy to get duplicate labels accidentally.

File paths

  • If you need to reference a file in a folder, let R create the path so that it is compatible across operating systems.
file.path('figures', 'figure1.Rmd')
  • I use the {here} package so that my code doesn’t break if I happen to issue a change workspace directory command.
here::here('images', 'logo.png')

This way if you have a reference to an image in the images folder at the base level of your project, you can move the document anywhere deep into some folders, and it’ll still find the image.

Tables in for loops

Making tables within for loops is tricky and it is different if you are outputting to Word versus html and also depends on what package that you use. See my qmd/Rmd files in the tables folder for examples of how to set it up.

Working with Word

For many of us, Word is part of our team’s workflow. Here are some tips if that is the case for you:

  • Check out the officeverse: officedown and flextable R packages.
  • Quarto has greatly improved Word integration so many of the problems we faced with Word output may soon be solved.
  • Use templates to make your Word doc look the way you want. The default Word template is bare bones. See my example and read about using Word templates with Quartro here and R Markdown here.

Nice tables in Word

The example in Table_Counts.Rmd and Table_Counts_flex.Rmd shows you tricks to make nice Word tables.

  • how to include a page break in your Word doc between tables.
  • using format="pandoc" for the table
  • using results='asis' and print() so you can use for loops.
  • centering your tables is next to impossible with kable(). Use the {flextable} package if you need that.

New pages in Word

This is how to get a new page in Word. Make sure you are in print view on the word doc, otherwise you won’t see any of the pages.

```{=openxml}
<w:p><w:r><w:br w:type="page"/></w:r></w:p>
```

PDF templates

  • Use document classes.
  • Quarto makes it easier to pass in class options.
  • See Quarto PDF guide

Fisheries reports using R Markdown

Here are some real examples of NOAA Fisheries reproducible reports created with R Markdown.

The RStudio Cloud workspace (above) is cloned from https://github.com/RVerse-Tutorials/hello_quarto_book

this link. The example qmd files are in https://github.com/RVerse-Tutorials/QmdReport.

NWFSC Math Bio Program, NOAA Fisheries