::use_course("njtierney/qmd4sci-materials") usethis
Quarto for Scientists
For a scientific report to be completely credible, it must be reproducible. The full computational environment used to derive the results, including the data and code used for statistical analysis should be available for others to reproduce. Quarto is a tool that allows you integrate your code, text and figures in a single file in order to make high quality, reproducible reports. A paper published with an included quarto file and data sets can be reproduced by anyone with a computer.
About this
This is a book on using Quarto for writing and document preparation, aimed for scientists. It was initially developed as a 3 hour workshop, “Rmarkdown for scientists”. This focusses on Quarto, which is a next-generation rmarkdown. It is now developed into a resource that will grow and change over time as a living book.
This book aims to teach the following:
- Getting started with your own Quarto document
- Using Rstudio
- Visual Studio Code
- Improve workflow:
- RStudio
- Demonstrate rstudio projects
- Using keyboard shortcuts
- Quarto projects
- RStudio
- Export your Quarto documents to PDF, HTML, and Microsoft Word
- Better manage figures and tables
- Reference figures and tables in text so that they dynamically update
- Create captions for figures and tables
- Change the size and type of figures
- Save the figures to disk when rendering a document
- Work with equations
- Inline and display
- Caption equations
- Reference equations
- Manage bibliographies
- Cite articles in text
- Generate bibliographies
- Change bibliography styles
- Debug and handle common errors with Quarto
- Next steps in working with Quarto:
- How to extend yourself to other formats, such as slides, websites, books, and more
Why write this as a book?
This book started out its first life being around rmarkdown. There are many great books on R Markdown and it’s various features, such as “Rmarkdown: The definitive guide”, “bookdown: Authoring Books and Technical Documents with R Markdown”, and “Dynamic Documents with R and knitr, Second edition”, and Yihui Xie’s thesis, “Dynamic Graphics and Reporting for Statistics”.
With the release of Quarto, I wanted to translate the materials I developed in “Rmarkdown for scientists” to cover the same material. Here are some resources that I really liked for learning Quarto:
- The Quarto “get started” guide
- The Quarto guide “Quarto manuscripts”
- The Quarto chapter in “R for data science”
- Making shareable documents with Quarto from, from OpenScapes
- Alison Hill’s blog post: “we don’t talk about Quarto”
- Mine Çentinkaya-Rundel’s talk “Quarto for academics”
While the Quarto guide is extensive, and indeed their “Quarto manuscripts” guide covers a lot of the ground in this book.
So, why write a book?
Good question. The answer is that writing this as a book provides a nice way to structure the content in the form of a workshop, in a way suitable for learning in a few hours. It is not to say that there aren’t already great resources out there; there are. It is instead adding to the list of other useful information out there on the internet. I considered the Rmarkdown for Scientsts book and course a success, and it helped myself and others understand and better use rmarkdown. So I guess, to answer a question with another question:
Why NOT write this as a book?
How to use this book
This book was written to provide course materials for a 3 hour course on Quarto
We worked through the following sections in the book in 3 hours:
- Why use Quarto
- Installation
- what is RStudio?
- suggested workflow and hygiene
- how to use R Markdown
- using R Markdown with pdf, html, and Word
- what are some useful keyboard shortcuts
- Adding captions to tables and figures
- Changing figures
- Adding mathematics
- Citing figures and tables
- Changing citations and styles
With the remaining sections being used as extra material, or have since been written after the course:
- Fixing some common problems in R Markdown
- What are some alternative outputs of R Markdown?
- Where to go next?
- Suggested references
Course materials can be downloaded by using the following command from the usethis
package:
Licence
This work is licensed under a Creative Commons Attribution-NonCommercial 4.0 International License.