Quarto for Academics | Mine Çetinkaya-Rundel
This video highlights some of Quarto's features that are especially useful for academics, as educators and as researchers. 00:00 Introduction 01:06 Linking to documentation from code with code-link 02:27 Informative YAML errors and YAML completion 03:41 Creating Quarto slides with revealjs 04:20 PDF export of HTML slides 05:03 Annotating slides with chalkboard 06:40 Advancing slides for your audience with multiplex 07:38 Revealing code in slides with echo 08:16 Highlighting code with code-line-numbers 09:37 Customizing output location with output-location 10:42 Showing code chunk fences with echo: fenced 12:03 Code annotation 14:11 Authoring manuscripts with Quarto templates 16:49 Inserting citations from Zotero or from a DOI with the RStudio Visual Editor 19:59 Wrap up and learning resources
image: thumbnail.jpg
Transcript#
This transcript was generated automatically and may contain errors.
Hi, I'm Mine Çetinkaya-Rundel. I'm a professor at Duke University and a developer educator at Posit. And in this video, I'd like to talk to you a little bit about how I use Quarto as an academic. We're going to focus on sort of two parts of my life as an academic, how I use Quarto as part of my teaching, and how I use Quarto as part of my research. So let's start with the teaching. We're going to turn to RStudio and take a look at this document, a simple HTML document with some code chunks where we create a figure and then a table.
So let's go ahead and render this document to take a quick look at the output. We're doing a very simple data analysis with the lovely Palmer Penguins package here. And we'll be able to see that there are already some things built into the document. I'm using some hyperlinks and whatnot in my document. I have some cross-references in my document as well. And what we're going to do next is sort of enhance this document for teaching use.
Linking to documentation with code-link
Now, let's suppose that you are teaching coding to your students. One of the things that's often helpful to do is to encourage them to read the documentation for functions whenever possible. And generally, we tell our students, why don't you Google the function? I think we can do one better. So one of the nice functionalities of Quarto is that we can actually add automatic hyperlinks to each of our functions. So what I'm doing is in the YAML, I am adding a new field called code link. And let's go ahead and render that.
And here we go. We can see that each of our R functions are now hyperlinked. So if I was to click on a function like library, I get directed to the HTML documentation for that function. And let's go ahead and click on something that is from the tidyverse. For example, what does geom point do? So for one of these packages that has a package down site, the code link takes me directly to the documentation for that function. And particularly for ggplot functions, these are extremely helpful because then your students can scroll down to the examples and not only see the examples as part of the documentation, but the rendered versions of those plots as well.
Informative YAML errors and completion
Next, let's go and do something else. We are going to add a code chunk option. And I am going to say I want to hide this code chunk. And I want to hide any of its warnings and messages as well. So in order to do that, I will say include false. And let's go ahead and render this. We can see that it doesn't render because I have made a syntax error. But the nice thing in the context of teaching, particularly your students learning Quarto, and particularly if they're coming at it from having learned R Markdown previously, is that when you make a syntax error like this, the message that you get from Quarto is really, really useful. And it tells you exactly where the issue is.
And so let me go ahead and fix that. I should be using a semicolon instead. And once I do that, if I click on the tab, I can actually use YAML completion to make sure that I am typing false in exactly the way Quarto expects me to. And we can see here now that that code chunk where we're loading packages is not in our output anymore.
Creating slides with revealjs
So as a professor, one of the things I do regularly is go from writing course notes or a book at times to writing slides for in-class teaching. And it's really useful when I can use the same source document as a starting point for each of these different venues. And with Quarto, it's really neat that you can, without having to change any of the text in your document, simply by changing your format. So in this case, we will make this revealjs to create HTML-based slides. It's going to ask us to reload our visual editor. And let's go ahead and render and see what that looks like.
All right. And now we have a slide deck version of our document with a handy sidebar tool. And one of the things that I really enjoy here is that I can not only make my slides full screen or take a look at a speaker view, but a question I get asked very often from my students is, can we get a PDF version of the slides so that they can annotate on it, say, on their tablets or something? And there is a neat PDF export mode that they can click on, and they can immediately get the PDF export should they want to print it or save it as a PDF file.
Annotating slides with chalkboard
Next, let's take a look at how might I use Quarto in the context of teaching in the classroom. Oftentimes, I am teaching in a classroom where there's a projector screen behind me that happens to cover the whiteboard, for example, or a student asks a question. And what I really want to do is draw on my slides, maybe something like if I scroll to the figure here, maybe something where I want to annotate my slides and show the three clusters of penguins. I can do this by adding fields to my YAML again. So under revealjs, let's do chalkboard true and render this again.
And you can see that in addition to the little hamburger menu for the tools on the sidebar, I have gained two new tools here. One of them is an annotation tool. I'm going to go ahead and click on that, click a color that I might want to use. And I can then use that to annotate my slides. And the neat thing is you can actually save an annotated version of your slides as well. So if you tend to sort of annotate on your slides a lot, maybe do some derivations as you go through the class, and then would like to post an annotated version of your slides, you could save those. I'm going to go ahead and remove these annotations by clicking on just the delete button on my keyboard.
And now let's get to that point where I actually want to write something on the board, maybe not just annotate my slides, but there is no board to be seen in the classroom. So I can click on the chalkboard option and basically start typing, start writing and annotating on my chalkboard as well. And I'm going to go ahead and get rid of that too now.
Advancing slides with multiplex
Another handy tool is one where as you advance your slides, the posted version of your slides advance along with you as well. This can be particularly helpful for students maybe who may have lost where you were at in the lecture so that as you advance through your slides, if they have it open on their computers, they can follow along. In order to do that, I'm going to add the multiplex option to my slides. And when we render this, we can see that we have now gained two outputs to our slide deck. One of them is just penguins.html, which is what we had before as well. And the other one is penguins-speaker.html. So what you want to do is you want to be posting the .html version on say your course website, but you want to be presenting from your dash speaker version. And therefore, and that way, as you advance your slides, they will advance for your audience as well.
Revealing and highlighting code in slides
By default, when we look at our HTML slides, you'll see that the code is not visible here. The revealjs mode by default hides your code, which is not helpful if you're actually trying to teach the code. So let's go ahead and turn all of that code on using the execute option in our document .html. You can see that I can control here a bunch of things about how the code is executed. So I'm going to go ahead and set that to true. And let's go ahead and render the document one more time. I can see my code and underneath it, I can see the table output.
If we go back to the previous slide where I have some lengthy ggplot code, and suppose that I want to give some insight into this code. Suppose that I want to talk a little bit about what the scale color, colorblind function does, and then maybe a little bit about what these theme functions do. So I might want to highlight my code. So let's go ahead and see how we can do that. In the code chunk, in the relevant code chunk, I'm going to add a code chunk option that says code line numbers. And in here, I am going to say that a vertical bar to indicate a pause, I want to first talk about line number nine, that's the scale color, colorblind. And then I want to talk about lines 10 to 11. And let's render this again.
If I now advance my slides, I'll see that first line number nine is highlighted. So I can talk a little bit about that. And then I advance again. And I can see that now lines 10 and 11 are highlighted, and I can render them again. The neat thing about this is that we are able to specify this as one of our chunk options, as opposed to having to edit our code, and add syntax to the code chunk itself.
we are able to specify this as one of our chunk options, as opposed to having to edit our code, and add syntax to the code chunk itself.
Customizing output location
Now, the problem here, though, is that my plot is really, really squished, because revealjs is giving the space for the code chunk itself, and then using whatever space is available that's left over in the slide for that plot, which is not very helpful. One approach to solving this would be to create another code chunk that references this one using its label. But a neat Quarto solution to this is to use the code chunk option output location. And I can choose to the default fragment means that the output is going to show up underneath your code chunk. Fragment means it's going to show up appear when you advance the slides. And the slide option says to put the output on the next slide. So let's select that so that we can get a nice big plot on our on the next slide.
Alright, so I have just my code on the slide, I can advance through and see the highlighted versions, portions of that code. And now my plot itself has moved to the next slide.
Showing code chunk fences with echo fenced
Now suppose that you are actually using Quarto to teach Quarto, you actually want to show your students how you can add all of these code chunk options. In the rendered document, they are impossible to see since they're hidden from the output, but we can easily reveal those by adding a new code chunk option called eco fenced.
And let's go ahead and render that too. And now our code chunk actually prints on not just the code itself, but all of the code chunks, code chunk options as well. So I didn't have to create a new sort of indented code chunk or something to be able to reveal these. And you can see that the only code chunk option that's not visible here is the eco fence. So it's smart enough to hide that one and show the rest of the code chunk options. So you can easily talk about how to write Quarto documents with your learners as well.
Code annotation for teaching
Now we've added a lot of options to these slides that are very much slide specific. Let's go back and turn things back to an HTML document. So I'm going to change my format to HTML, which asks me to reload the visual editor one more time. And let's go ahead and render that again. All right. And let's talk about one last code chunk option that can be really helpful in a teaching context, particularly if you are writing a sort of long form documents, course notes, or a book where you might want to annotate your code further. I'm going to scroll down to the very last code chunk here where we're creating a table. And I'm going to add some annotation to it.
So I might say, this is my line number one. So the hash sign and then one, and we're going to basically annotate each one of these line numbers. And let's go ahead and say, this is four and right underneath my code chunk, I'm going to start writing up my annotation. So something like, start with the penguins data frame, then slice the top 10 rows, select some variables, and make a table with GT.
This code annotation feature that's available with Quarto 1.3 onwards allows you to annotate lines, each line of code, and basically add some text to it so that you can, if you were teaching in person, these are probably the words you would say about the code, but now it's really easy to capture them in a written document as well. And it doesn't have to be one line per code. So I could do something like give the same annotation number to that last line of code and say that I want to capture both of those comments in a single item in the list underneath it. And here we go, that item four has gone away. And now I have an item three that basically covers everything that's underneath it.
Writing papers with journal templates
So we've showcased a bunch of Quarto features that are helpful for teaching. But what about the research or the publication side of an academic's life? So let's talk about that a little bit next. The neat thing about writing papers with Quarto is that it comes with some article templates. So I'm on the Quarto documentation page here, and I am going to scroll down here a little bit and go to the GitHub repository where we can find a bunch of journal templates here. I tend to write papers that use the American Statistical Association journals template.
So we're going to take a look at that here. If the sort of template that you tend to use for your papers is already listed here, that's fantastic. You can get started right away. And if not, I encourage you to open an issue in the repository, or if you're interested, contribute the template to the repository so that others can use as well. So for the JASA template, it says to install it. We're going to use Quarto use template and then Quarto journals JASA. So I'm going to copy that line of code and let's go to that page here as well. Go to my RStudio and open up my terminal. And let's go ahead and paste that there. It asked me if I trust the authors of this template. Yes. The directory name can be my awesome paper. And let's go ahead and see what we got.
In my files pane here, I can see a new directory called my awesome paper. And there is a Quarto file in there with a very extensive YAML. And if you have written papers before that, whether either with our markdown with the articles package or just using LaTeX, know that the preamble tends to be pretty long. So I am going to give it a new title. My awesome paper about data science. And maybe I can just add my name quickly here. And let's go ahead and render the document. And here we go. The output looks like something I'm actually pretty used to seeing when I write papers using other tools as well. And the neat thing with this template is that it comes with some pre-filled in text that tells me exactly how I might sort of include figures or tables in my output and how I can even include some citations as well.
Adding citations
So let's switch over to the visual editor and let's talk a little bit about citations. So I would like to add a citation to my paper. Let's say that I want to add something right at the end of my introduction. And I can do this in one of two ways. I can either use the insert menu and say that I want to add a citation or I can use my insert anything tool and say citation. And you can see that I have even linked up my Zotero library here. And so I can click on that. I happen to have one of my papers saved in my Zotero library. So if you use a tool like Zotero or Crossref or something like that, you can actually link these up to your RStudio. And as long as you have them running on your computer, on the same computer, they sort of automatically link up anyway. And I can go ahead and insert that.
So let's go ahead and save that and render this document one more time. Right. So at the end of my introduction, the new citation is there. I can click on it and I can see that it has been added to my list of references. And what RStudio also did for me at the same time is it added that entry to my bib file as well. So I can see that that has already been inserted into my bib file.
What if you don't use a tool like Zotero? Maybe you are looking for a paper on Google Scholar. So how about we look for the Welcome to the Tidyverse paper? And I'm going to go ahead and open that up and we're going to grab the DOI of this paper. I have copied that from here. Let's go back to RStudio and let's say that we want to add that citation, suppose here, using the insert anything tool again and citation. I'm going to say this time that I want to find a paper by its DOI. So I paste the DOI here and it goes out and searches for that. And it allows me to insert that citation either as an in-text citation or not. Let's go ahead and hit insert. And once I have done that, that has also been added to my bib file. You can see that that's been added to my bib file and a reference has been created for it as well. And if I render my document one last time, I'll be able to see that that citation has been inserted to the appropriate location as well. And I can find the paper in the list of references at the end of my document.
So we've talked a bit about using Quarto for teaching and a little bit about using Quarto as part of your research. If you've been intrigued or if you've already been a Quarto user and have enjoyed these features that I highlighted here, there is an abundant number of features available in Quarto that we haven't gotten a chance to touch on in this video. So if you would like to learn more, I encourage you to go to Quarto.org. If you are just getting started with Quarto, the get started menu will be helpful where you can learn about how to use Quarto using your editor of choice, whichever one is your favorite. And if you have already dived into Quarto and know the basics, I suggest going to the guide to dive further into any of the different outputs that you might be interested in creating, like a website or a book or adding interactivity to your documents. And to stay up to date with what's happening in Quartoland, the blog is a great place to go, particularly when there are new features, they're generally documented here. Thank you very much.
