BioC 2022 - Hello, Quarto! :: Posit Open Source

Transcript#

This transcript was generated automatically and may contain errors.

All right. Well, thank you, everyone. It is my pleasure to welcome you to the final day of BioC 2022 and to introduce Professor Minna Chetinkaya-Rundell, who is professor at Duke and affiliated at University of Edinburgh and also working with POSIT, and she'll be telling us about the new product called Quarto . Thank you, Minna. Take it away.

All right. Thank you very much. Are you able to see and hear me okay? Yeah? Are you able to see and hear me okay? Yes. Okay, great. I'm seeing yeses. All right. Well, thank you for joining today, and I am very excited to talk to you about Quarto.

So, I have been sort of working with Quarto over the last year, testing it out and teaching it to my students, and today, hopefully, I'll be able to give you a nice overview for it. Before I get started, I want to acknowledge two people who have been kind of critical in preparing this presentation. One of them is Julia Stewart-Lounds, who is with Openscapes, who I'll talk about a bit more in my talk, but I've given a version of this talk with her, and this is sort of my part of the talk, bringing in some of her ideas as well, but she's been critical in kind of planning this talk out, and also the cute artwork that you're going to see throughout the presentation is by Alison Horst, who has made these illustrations for our talk and also open-sourced them, so you also can use these illustrations if you would like, and they're available on her GitHub repository.

I am only going to change my format, nothing in my content. And if I sort of reload my editor and render, you'll see that each of those second level headers are going to be a new slide in my deck. So, I'm able to move between formats really easily, really nimbly.

Demo: building a website in under 10 minutes

Okay. So, I've demoed one document to a slide deck. Let's bring this back to a single document and let's see if we can make a website in less than 10 minutes. If I want to do something like a website, chances are I have more than one document. So, I'm going to create one more document. I am specifically going to remove any computation from this document so we can feature two types. And I'd recorded the demo earlier for another talk, so it says here's a demo site.

Now, I'm creating another text file, a YAML file that will allow me to bring these two things in a Quarto project. So, a quarto.yaml and we're going to write some YAML on the fly. I'm going to define that I'm creating a Quarto project. The type of it is a website. And let's lay out our website. I want a title for it. Maybe let's call it Quarto. And let's say I want a navigation bar. And in that navigation bar, I want the left on the left, I want my index.qmd and I also want that hello.qmd, which we've been working with so far. I now have a Quarto project that defines it as a website. I'm going to restart my RStudio session to get that build tab to appear.

And I can render or preview my website. So, a render or a live preview of my website. Let's go ahead and render it. So, we've brought these two documents together in this very simple minimal YAML. And we basically have a website with multiple pages in it, which I think is a really neat way of putting things together. And this would be exactly the same way if you were making a book, for example.

So, we have created a website. Let's think about the computation in the website. One of my documents has some compute in it. And what I might want to do is say, please don't rerun the compute in that file every time I want to re-create, re-render my website. You know, maybe I'm writing some text. So, what I'm going to add here is a YAML option called freeze. And what it does is it will basically freeze the results of my computation if I set it to true and won't rerun them until I perhaps do something like re-render that particular document again. And you can see that I now have a freeze folder in my files pane where those computations are saved. It will also, a little bit later, allow me to re-render this website in an environment that doesn't have R installed.

So, we have prepared our website and now let's publish it. I'm going to go to the terminal now and I'm going to run my quarto publish command. And I'm going to publish it on a, let's go ahead and see if this will work, on quartopub from my account. And I'm going to maybe call this hello-quartodemo. So, quartopub is a new publishing kind of domain that you can, just like rpubs, if you've used it before. And basically, I can publish directly from the terminal. If you are hearing of quartopub for the first time, it is quite new and you might want to go claim a username for yourself.

I basically have published my website as well. I think all of this is, you know, I didn't have to worry about other places. I could also directly publish to things like GitHub pages or Netlify or something, but obviously that would have required additional authentication. And I think this is a really neat way of just, you know, publishing your documents as quickly as possible.

How Quarto rendering works

All right. So, let's go to kind of recap this. So, what we've seen here is that the quarto-cli , so the quarto command line interface, is the one that's doing the orchestration of each step of rendering. With rmarkdown , the rmarkdown package would do that. So, you would need to have R installed on your system and R, the rmarkdown package would be doing the orchestration. With Quarto, we have a QMD file that, depending on the code you have in that file, or in the execution or in the execution kind of style you have chosen, uses either Knitter or Jupyter under the hood to kind of run the code in the executable code chunks and create a plain text markdown document. And then we rely on Pandoc to do the last bit of kind of putting everything together and give you the outputs that you want.

Quarto also makes moving between formats straightforward. So, I've shown you a single document, like the type of thing I regularly write. It's something like a lesson one in kind of a lecture notes format, maybe in HTML. Next, I might say take that and let's create some lecture slides from that. So, all I have to do is change the format in the YAML. And next, I might say I have maybe one of these and a couple more that I'm going to add on to it, create a YAML file that will call all of these and put them together as a website.

It also facilitates open sharing, because even when it might be so easy to create documents locally, and even if you are going to openly license them, if sharing them and publishing them openly is a hassle, chances are many folks are going to choose not to go there. And I think that tooling that makes it easy to share what you do with the world on the web is incredibly useful. And it's not just useful for you, but to the world, because it facilitates open sharing of knowledge and learning for reuse.

Collaborate: working across languages and tools

In the next act, we're going to talk a little bit about collaboration. I've talked a lot about myself so far. I write slide decks. I write documents. But I obviously don't operate in a silo disconnected from others. I collaborate with a lot of people, and you probably do as well. Well, I collaborate with a lot of people, and some of those people don't use R. Many scientists actually use Python, too.

What is really neat about Quarto is that it enables collaborating across coding languages. So, here you can see a Quarto YAML, just like the one we have created. But this is from my colleague, Julia Lowndes' website that she has kind of put together for kind of a group that she's running. And we can see that there's a lot more pages than the two that we created. Some of those are QMD files, some of them are Python notebooks, and some of them are RMD files, and some of them are plain Markdown files. So, the fact that we don't need everyone to kind of change their tooling, but actually can come together and bring whatever they have created in an environment that they feel comfortable with, I think is a really neat feature of Quarto.

Quarto enables contributing from our current tools. So, you could be working in the RStudio IDE, which is personally my preferred place to be writing code. But you could also edit Quarto documents in Jupyter. You could edit them in VS code, or you could edit them directly on GitHub, for example. And what is really neat about this is that, you know, folks choose where they want to be writing code or where they want to be writing prose and get comfortable with it, right? And when they basically get comfortable with that, asking them to change where they're doing their work, just to collaborate with you, is often faced with resistance. People want to kind of stay at their own home and wish that their collaborator would come to them. So, an alternative is to say you can stay at your own home and you can collaborate with me on the same project from wherever you are.

Demo: editing from Jupyter

Let's look at one other demo here, where we're going to be editing that same site from Jupyter. Okay, so I am in JupyterHub right now, and you can see that on the side, the same files that we created earlier with the website that we have. We're going to do a live preview of this. So, I've run Quarto preview in the terminal, and that gives me a URL where I can go and see the results of my website. And generally, you know, keeping these side by side is a nice way of sort of editing your document live and then seeing the changes. So, we're able to, and note that this Jupyter environment does not have R installed right now. So, it's the freeze feature from earlier that's allowing us to re-render or preview the website without running the R code again.

And here, we have a Jupyter notebook that basically has very similar content to that first hello.qmd file that we had created. We have some text in Markdown, and we also have some code to recreate a similar analysis. And the code chunks have Python code in them. So, we're going to run one of these code chunks, and we can see the results of it directly in the notebook.

And now, we're going to go back to that YAML file where we had said put these two documents together and add this third document into it. So, that is hello in Python. And this time, it's not a QMD file, but it is an IPython notebook. And let's go ahead and watch to see if things are rendered again. And if we go back to our website, we can see that we have added that third file. And so, this could be a collaborator adding to your project basically without leaving their home. They're able to use their preferred computing language, and they're able to use their own preferred computing environment.

So, we've talked about these code chunk options that we can add using the hash pipe. The same syntax works in Jupyter as well. So, we might add a caption to this figure. So, let's go ahead and run it. And you'll see that the caption is going to be visible on the output. So, if we kind of refresh this, you can see that the caption is visible above our plot, but it is not in the Jupyter notebook. So, it's not getting in the way of the notebook, but it is present in the output.

We're going to demo adding one other chunk option, and this would be something for what if we wanted to move this plot to the margin. So, kind of a style that many folks prefer where their plots appear in the margin. So, this allows us to basically change the layout of things to our document in a way that would not necessarily be possible to achieve just within the Jupyter notebook, but we are able to get that in our rendered output.

Teach: Quarto in the classroom

Going back to our slides, we've talked about kind of collaborating across languages, but I want to talk a little bit about the teaching implications of this as well. And I'm going to do this with an example from a student of mine. So, this is Holland Stem, who is an art history and visual media studies student who was in my class in last spring, last spring, where she had only one semester of an interdata science class where she had learned R Markdown, and this was her second class, a regression class, where we were using Quarto. And she is working on a pretty quantitative art history thesis where she's looking at representation in art history textbooks and actually measuring kind of each of the pieces of art featured in the textbook and joining that with demographic information about the artists as well.

And she was working on a thesis that is basically quite quantitative and had a bunch of code and a prose in it. Even though in our class, each of our, we teach Quarto, you know, every single assignment is a single Quarto document, and we don't end up writing something pretty extensive like a thesis that brings a bunch of documents together. But she was able to pretty quickly level up from writing a single document to being able to bring them together because we're able to do that with a single YAML file, which in my opinion has been a challenge for students who learn R Markdown so easily, but then have, you know, struggling with that leveling up to writing more extensive things.

So, sort of kind of the moral of the story that I wanted to tell here is that this leveling up was possible for a student in their second semester of statistics with a very minimal introduction to Quarto, and to me that has been a very pleasant surprise for teaching with it.

So next I want to show you a few things about teaching with Quarto, and we'll try to kind of speed this up a bit. So the first thing that's really neat is that you can just render Quarto documents in RStudio. There is no additional install necessary, and to me that's really, really nice. But beyond that, you can do things like adding, linking to documentation directly by adding a YAML option called code link, and what this will do is in the rendered document, every single function, regardless of which package they come from, is going to link to its documentation. If it can find a package down website, it'll link there, otherwise it'll link to kind of standard R documentation for it. And this comes with, you know, very minimal kind of, very minimal work on your part, which is really neat.

Other things that I create with Quarto are obviously, oh, so let's show the, sorry, the YAML errors as well. Let's try to make a mistake here, like it's hard to make a mistake because it gives you so many suggestions. But let's say that I did make a syntax error and render the document. The syntax, the errors are very human readable, and it even gives you some suggestions around how to fix them, which I think is very helpful for new learners.

I'll show a few other things that are in, so we're going to change this to reveal JS to make some, make our slides from the same document, and I'm going to add a couple things. So, you can see, for example, that we have, there is a kind of a sidebar that allows you to go between things, and also you can do a PDF export, which I think is really nice. Students always ask for, can I get a printable version of your slides? Other things that are really nice that I found is this chalkboard feature, which allows you to kind of annotate your slides as you go, and in the past I've struggled with this sort of thing, you know, needing to bring an iPad with me to write over things, and I think it's really neat to be able to do this on the fly, and you can actually save these things as well, and you can get like a chalkboard to actually write on, which is nice when a student asks a question that you otherwise, you know, don't have space to expand on in the slides.

I'm going to proceed a bit. There's some really neat features here, but I wanted to show you one other thing, because we've been talking about HTML output a lot, but what about the research side of things? So, if I can, there are Quarto templates for a growing number of journal styles, so here I'm going to use JASA, for example, that I can install. This is basically adding something like an extension to my project, and asks me, do you trust the author of this template? Asks you to give it a directory name, and now let's take a look here at the files that it has created for us. I'm going to, you know, adjust my title. I'm going to adjust my, sort of, my author name for it, and we're going to render this document, and you can see, if you have submitted JASA articles, this format should be familiar to you. The fact that we're able to get to this so nicely and quickly, I think, is really neat.

Reimagine: open science and collaboration

All right. So, I think that I'm going to wrap things up quickly here, because we are running out of time, which is a huge shame, but I'll take maybe two more minutes to wrap things up, and then we should have plenty of time for questions. So, the last thing I want to talk about is going beyond what you might be doing, what you might be used to doing, and for this, I want to give a huge shout out and credit to my friend and colleague, Julia Lowndes, who leads this effort called Openscapes with her partner, Aaron Robinson, and their model is to mentor scientific teams kind of towards a culture of open science.

And I would like to read this quote from Ilana Fenwick, who is an Openscapes member. Because of Openscapes, I have renewed hope in how we can bring about a kinder future in science. I see a commitment in the open science community to bridging the gaps where we've left members of our community behind, and it inspires me.

Because of Openscapes, I have renewed hope in how we can bring about a kinder future in science. I see a commitment in the open science community to bridging the gaps where we've left members of our community behind, and it inspires me.

So, the work that, the sort of work that Openscapes is doing and is inspired by things like this. This is an excerpt from the Fay lab manual, which basically says you are coming into our lab, you are going to be a member of our research group, and you might be coming from a variety of backgrounds in terms of what you've seen as part of data science, as part of data analysis. They're an ecology lab, and it basically makes the implicit explicit by saying here's our code of conduct, these are your expectations, but also here's where we keep the files, here is where we run our code. And what the goal here is to be able to get people to contribute to authoring of things at the very beginning, even if they're coming with a minimal background.

And so, how are we going to be able to do this? One way that working with Quarto and RStudio supports this is that visual editor. So, I'm not going to play for you the whole demo, but I am only going to show you one thing that I think will be of super interest to everyone, which is adding a citation to our document. So, what I'm going to do here is I am going to kind of add this at symbol, and it is linked to my Zotero, and I am able to with some just by searching through my Zotero library, insert a citation directly in the visual editor, and when I render my document, I'm able to see that it has created a bib file for me, and it has basically added that citation to my document. It's things like this that basically get the minutiae of the syntax out of the way and allow people to focus on the content and be able to contribute as quickly as possible.

I can even do this with something like a DOI search. So, if I have the DOI for a document or a paper that I am citing, I can simply place that in there, and it will go through and search through the DOI, kind of, search the DOI for me and insert the citation, and it's things that ease, I think, authoring and collaboration like this that, you know, moves things forward, and personally, I really enjoy being able to write like this.

So, we are going to, I'm going to wrap this up with a big thank you to joining this morning. I hope that this has been a good overview and introduction to Quarto. Once again, the slides are at this link, hello-quarto-bioc, and if you scroll to the next slide, you'll be able to see a bunch of resources. You can even get the source code for the demo that I, the website that I created, if you wanted to pick things up right there, and I'd be happy to answer any questions. Thank you very much.