course
/
r4ds
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Quarto editor comments

This commit is contained in:
mine-cetinkaya-rundel 2023-03-11 11:25:58 -05:00
parent da0d03fd1b
commit 4815ed1bd3
1 changed files with 29 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

40
quarto.qmd
View File

@ -15,15 +15,15 @@ Quarto documents are fully reproducible and support dozens of output formats, li
Quarto files are designed to be used in three ways:
1. For communicating to decision makers, who want to focus on the conclusions, not the code behind the analysis.
1. For communicating to decision-makers, who want to focus on the conclusions, not the code behind the analysis.
2. For collaborating with other data scientists (including future you!), who are interested in both your conclusions, and how you reached them (i.e. the code).
3. As an environment in which to *do* data science, as a modern day lab notebook where you can capture not only what you did, but also what you were thinking.
3. As an environment in which to *do* data science, as a modern-day lab notebook where you can capture not only what you did, but also what you were thinking.
Quarto is a command line interface tool, not an R package.
This means that help is, by-and-large, not available through `?`.
Instead, as you work through this chapter, and use Quarto in the future, you should refer to the Quarto documentation page at [https://quarto.org](https://quarto.org/){.uri} for help.
Instead, as you work through this chapter, and use Quarto in the future, you should refer to the [Quarto documentation](https://quarto.org).
If you're an R Markdown user, you might be thinking "Quarto sounds a lot like R Markdown".
You're not wrong!
@ -57,33 +57,40 @@ It contains three important types of content:
2. **Chunks** of R code surrounded by ```` ``` ````.
3. Text mixed with simple text formatting like `# heading` and `_italics_`.
When you open a `.qmd`, you get a notebook interface where code and output are interleaved.
@fig-diamond-sizes-notebook shows a `.qmd` document in RStudio with notebook interface where code and output are interleaved.
You can run each code chunk by clicking the Run icon (it looks like a play button at the top of the chunk), or by pressing Cmd/Ctrl + Shift + Enter.
RStudio executes the code and displays the results inline with the code:
RStudio executes the code and displays the results inline with the code.
```{r}
#| label: fig-diamond-sizes-notebook
#| echo: false
#| out-width: "90%"
#| fig-cap: |
#| A Quarto document in RStudio. Code and output interleaved in
#| the document, with the plot output appearing right underneath the code.
#| fig-alt: |
#| RStudio window with a Quarto document titled "diamond-sizes.qmd"
#| on the left and a blank Viewer window on the right. The Quarto
#| document has a code chunk that creates a frequency plot of diamonds
#| that weigh less then 2.5 carats. The plot shows that the frequency
#| that weigh less than 2.5 carats. The plot shows that the frequency
#| decreases as the weight increases.
knitr::include_graphics("quarto/diamond-sizes-notebook.png")
```
If you don't like seeing your plots and output in your document and would rather make use of RStudio's console and plot panes, you can click on the gear icon next to "Render" and switch to "Chunk Output in Console".
If you don't like seeing your plots and output in your document and would rather make use of RStudio's console and plot panes, you can click on the gear icon next to "Render" and switch to "Chunk Output in Console", as shown in @fig-diamond-sizes-console-output.
```{r}
#| label: fig-diamond-sizes-console-output
#| echo: false
#| out-width: "90%"
#| fig-cap: |
#| A Quarto document in RStudio with the plot output in the Plots pane.
#| fig-alt: |
#| RStudio window with a Quarto document titled "diamond-sizes.qmd"
#| on the left and the Plot pane on the bottom right. The Quarto
#| document has a code chunk that creates a frequency plot of diamonds
#| that weigh less then 2.5 carats. The plot is displayed in the Plot
#| that weigh less than 2.5 carats. The plot is displayed in the Plot
#| pane and shows that the frequency decreases as the weight increases.
#| The RStudio option to show Chunk Output in Console is also
#| highlighted.
@ -93,11 +100,15 @@ knitr::include_graphics("quarto/diamond-sizes-console-output.png")
To produce a complete report containing all text, code, and results, click "Render" or press Cmd/Ctrl + Shift + K.
You can also do this programmatically with `quarto::quarto_render("diamond-sizes.qmd")`.
This will display the report in the viewer pane and create an HTML file.
This will display the report in the viewer pane as shown in @fig-diamond-sizes-report and create an HTML file.
```{r}
#| label: fig-diamond-sizes-report
#| echo: false
#| out-width: "90%"
#| fig-cap: |
#| A Quarto document in RStudio with the rendered document in the
#| Viewer pane.
#| fig-alt: |
#| RStudio window with a Quarto document titled "diamond-sizes.qmd"
#| on the left and the Plot pane on the bottom right. The rendered
@ -109,7 +120,8 @@ knitr::include_graphics("quarto/diamond-sizes-report.png")
When you render the document, Quarto sends the `.qmd` file to **knitr**, [https://yihui.name/knitr](https://yihui.name/knitr/){.uri}, which executes all of the code chunks and creates a new markdown (`.md`) document which includes the code and its output.
The markdown file generated by knitr is then processed by **pandoc**, [https://pandoc.org](https://pandoc.org/){.uri}, which is responsible for creating the finished file.
This process is shown in @fig-quarto-flow. The advantage of this two step workflow is that you can create a very wide range of output formats, as you'll learn about in @sec-quarto-formats.
This process is shown in @fig-quarto-flow.
The advantage of this two step workflow is that you can create a very wide range of output formats, as you'll learn about in @sec-quarto-formats.
```{r}
#| label: fig-quarto-flow
@ -820,8 +832,14 @@ We've drawn on our own experiences and Colin Purrington's advice on lab notebook
How are you going to organize them so you can find them again in the future?
We recommend storing them in individual projects, and coming up with a good naming scheme.
## Learning more
## Summary
In this chapter introduced you to Quarto for authoring and publishing reproducible computational documents that include your code and your prose in one place.
You've learned about writing Quarto documents in RStudio with the visual or the source editor, how code chunks work and how to customize options for them, how to include figures and tables in your Quarto documents, and options for caching for computations.
Additionally, you've learned about adjusting YAML header options for creating self-contained or parametrized documents as well as including citations and bibliography.
We have also given you some troubleshooting and workflow tips.
While this introduction should be sufficient to get you started with Quarto, there is still a lot more to learn.
Quarto is still relatively young, and is still growing rapidly.
The best place to stay on top of innovations is the official Quarto website: [https://quarto.org](https://quarto.org/){.uri}.