Re-render book for O'Reilly
This commit is contained in:
Hadley Wickham
@@ -48,7 +48,7 @@ The distribution of the remainder is shown below:
|
||||
#| echo: false
|
||||
|
||||
smaller |>
|
||||
ggplot(aes(carat)) +
|
||||
ggplot(aes(x = carat)) +
|
||||
geom_freqpoly(binwidth = 0.01)
|
||||
```</code></pre>
|
||||
</div>
|
||||
@@ -235,7 +235,7 @@ Chunk options</h2>
|
||||
<li><p><code>message: false</code> or <code>warning: false</code> prevents messages or warnings from appearing in the finished file.</p></li>
|
||||
<li><p><code>results: hide</code> hides printed output; <code>fig-show: hide</code> hides plots.</p></li>
|
||||
<li><p><code>error: true</code> causes the render to continue even if code returns an error. This is rarely something you’ll want to include in the final version of your report, but can be very useful if you need to debug exactly what is going on inside your <code>.qmd</code>. It’s also useful if you’re teaching R and want to deliberately include an error. The default, <code>error: false</code> causes rendering to fail if there is a single error in the document.</p></li>
|
||||
</ul><p>Each of these chunk options get added to the header of the chunk, following <code>#|</code>, e.g., in the following chunk the result is not printed since <code>eval</code> is set to false.</p>
|
||||
</ul><p>Each of these chunk options get added to the header of the chunk, following <code>#|</code>, e.g. in the following chunk the result is not printed since <code>eval</code> is set to false.</p>
|
||||
<div class="cell">
|
||||
<pre data-type="programlisting" data-code-language="markdown">```{r}
|
||||
#| label: simple-multiplication
|
||||
@@ -311,7 +311,7 @@ Global options</h2>
|
||||
<pre data-type="programlisting" data-code-language="yaml">title: "My report"
|
||||
execute:
|
||||
echo: false</pre>
|
||||
<p>Since Quarto is designed to be multi-lingual (works with R as well as other languages like Python, Julia, etc.), all of the knitr options are not available at the document execution level since some of them only work with knitr and not other engines Quarto uses for running code in other languages (e.g., Jupyter). You can, however, still set these as global options for your document under the <code>knitr</code> field, under <code>opts_chunk</code>. For example, when writing books and tutorials we set:</p>
|
||||
<p>Since Quarto is designed to be multi-lingual (works with R as well as other languages like Python, Julia, etc.), all of the knitr options are not available at the document execution level since some of them only work with knitr and not other engines Quarto uses for running code in other languages (e.g. Jupyter). You can, however, still set these as global options for your document under the <code>knitr</code> field, under <code>opts_chunk</code>. For example, when writing books and tutorials we set:</p>
|
||||
<pre data-type="programlisting" data-code-language="yaml">title: "Tutorial"
|
||||
knitr:
|
||||
opts_chunk:
|
||||
@@ -344,7 +344,7 @@ comma(.12358124331)
|
||||
<section id="exercises-3" data-type="sect2">
|
||||
<h2>
|
||||
Exercises</h2>
|
||||
<ol type="1"><li><p>Add a section that explores how diamond sizes vary by cut, colour, and clarity. Assume you’re writing a report for someone who doesn’t know R, and instead of setting <code>echo: false</code> on each chunk, set a global option.</p></li>
|
||||
<ol type="1"><li><p>Add a section that explores how diamond sizes vary by cut, color, and clarity. Assume you’re writing a report for someone who doesn’t know R, and instead of setting <code>echo: false</code> on each chunk, set a global option.</p></li>
|
||||
<li><p>Download <code>diamond-sizes.qmd</code> from <a href="https://github.com/hadley/r4ds/tree/main/quarto" class="uri">https://github.com/hadley/r4ds/tree/main/quarto</a>. Add a section that describes the largest 20 diamonds, including a table that displays their most important attributes.</p></li>
|
||||
<li><p>Modify <code>diamonds-sizes.qmd</code> to use <code>label_comma()</code> to produce nicely formatted output. Also include the percentage of diamonds that are larger than 2.5 carats.</p></li>
|
||||
</ol></section>
|
||||
@@ -353,14 +353,14 @@ Exercises</h2>
|
||||
<section id="sec-figures" data-type="sect1">
|
||||
<h1>
|
||||
Figures</h1>
|
||||
<p>The figures in a Quarto document can be embedded (e.g., a PNG or JPEG file) or generated as a result of a code chunk.</p>
|
||||
<p>The figures in a Quarto document can be embedded (e.g. a PNG or JPEG file) or generated as a result of a code chunk.</p>
|
||||
<p>To embed an image from an external file, you can use the Insert menu in RStudio and select Figure / Image. This will pop open a menu where you can browse to the image you want to insert as well as add alternative text or caption to it and adjust its size. In the visual editor you can also simply paste an image from your clipboard into your document and RStudio will place a copy of that image in your project folder.</p>
|
||||
<p>If you include a code chunk that generates a figure (e.g., includes a <code>ggplot()</code> call), the resulting figure will be automatically included in your Quarto document.</p>
|
||||
<p>If you include a code chunk that generates a figure (e.g. includes a <code>ggplot()</code> call), the resulting figure will be automatically included in your Quarto document.</p>
|
||||
|
||||
<section id="figure-sizing" data-type="sect2">
|
||||
<h2>
|
||||
Figure sizing</h2>
|
||||
<p>The biggest challenge of graphics in Quarto is getting your figures the right size and shape. There are five main options that control figure sizing: <code>fig-width</code>, <code>fig-height</code>, <code>fig-asp</code>, <code>out-width</code> and <code>out-height</code>. Image sizing is challenging because there are two sizes (the size of the figure created by R and the size at which it is inserted in the output document), and multiple ways of specifying the size (i.e., height, width, and aspect ratio: pick two of three).</p>
|
||||
<p>The biggest challenge of graphics in Quarto is getting your figures the right size and shape. There are five main options that control figure sizing: <code>fig-width</code>, <code>fig-height</code>, <code>fig-asp</code>, <code>out-width</code> and <code>out-height</code>. Image sizing is challenging because there are two sizes (the size of the figure created by R and the size at which it is inserted in the output document), and multiple ways of specifying the size (i.e. height, width, and aspect ratio: pick two of three).</p>
|
||||
<!-- TODO: https://www.tidyverse.org/blog/2020/08/taking-control-of-plot-scaling/ -->
|
||||
<p>We recommend three of the five options:</p>
|
||||
<ul><li><p>Plots tend to be more aesthetically pleasing if they have consistent width. To enforce this, set <code>fig-width: 6</code> (6”) and <code>fig-asp: 0.618</code> (the golden ratio) in the defaults. Then in individual chunks, only adjust <code>fig-asp</code>.</p></li>
|
||||
@@ -420,7 +420,7 @@ Tables</h1>
|
||||
<pre data-type="programlisting" data-code-language="r">knitr::kable(mtcars[1:5, ], )</pre>
|
||||
<div class="cell-output-display">
|
||||
<div id="tbl-kable" class="anchored">
|
||||
<table class="table table-sm table-striped"><caption>Table 27.1: A knitr kable.</caption>
|
||||
<table class="table table-sm table-striped"><caption>Table 30.1: A knitr kable.</caption>
|
||||
<colgroup><col style="width: 26%"/><col style="width: 7%"/><col style="width: 5%"/><col style="width: 7%"/><col style="width: 5%"/><col style="width: 7%"/><col style="width: 8%"/><col style="width: 8%"/><col style="width: 4%"/><col style="width: 4%"/><col style="width: 7%"/><col style="width: 7%"/></colgroup><thead><tr class="header"><th style="text-align: left;"/>
|
||||
<th style="text-align: right;">mpg</th>
|
||||
<th style="text-align: right;">cyl</th>
|
||||
@@ -497,7 +497,7 @@ Tables</h1>
|
||||
</div>
|
||||
</div>
|
||||
<p>Read the documentation for <code><a href="https://rdrr.io/pkg/knitr/man/kable.html">?knitr::kable</a></code> to see the other ways in which you can customize the table. For even deeper customization, consider the <strong>gt</strong>, <strong>huxtable</strong>, <strong>reactable</strong>, <strong>kableExtra</strong>, <strong>xtable</strong>, <strong>stargazer</strong>, <strong>pander</strong>, <strong>tables</strong>, and <strong>ascii</strong> packages. Each provides a set of tools for returning formatted tables from R code.</p>
|
||||
<p>There is also a rich set of options for controlling how figures are embedded. You’ll learn about these in <a href="#chp-communicate-plots" data-type="xref">#chp-communicate-plots</a>.</p>
|
||||
<p>There is also a rich set of options for controlling how figures are embedded. You’ll learn about these in <span class="quarto-unresolved-ref">?sec-graphics-communication</span>.</p>
|
||||
|
||||
<section id="exercises-5" data-type="sect2">
|
||||
<h2>
|
||||
@@ -565,18 +565,28 @@ rawdata <- readr::read_csv("a_very_large_file.csv")
|
||||
<h2>
|
||||
Exercises</h2>
|
||||
<ol type="1"><li>Set up a network of chunks where <code>d</code> depends on <code>c</code> and <code>b</code>, and both <code>b</code> and <code>c</code> depend on <code>a</code>. Have each chunk print <code><a href="https://lubridate.tidyverse.org/reference/now.html">lubridate::now()</a></code>, set <code>cache: true</code>, then verify your understanding of caching.</li>
|
||||
</ol></section>
|
||||
</section>
|
||||
|
||||
<section id="troubleshooting" data-type="sect1">
|
||||
<h1>
|
||||
Troubleshooting</h1>
|
||||
</ol><blockquote class="blockquote">
|
||||
<blockquote class="blockquote">
|
||||
<blockquote class="blockquote">
|
||||
<blockquote class="blockquote">
|
||||
<blockquote class="blockquote">
|
||||
<blockquote class="blockquote">
|
||||
<blockquote class="blockquote">
|
||||
<p>7ff2b1502187f15a978d74f59a88534fa6f1012e ## Troubleshooting</p>
|
||||
</blockquote>
|
||||
</blockquote>
|
||||
</blockquote>
|
||||
</blockquote>
|
||||
</blockquote>
|
||||
</blockquote>
|
||||
</blockquote>
|
||||
<p>Troubleshooting Quarto documents can be challenging because you are no longer in an interactive R environment, and you will need to learn some new tricks. Additionally, the error could be due to issues with the Quarto document itself or due to the R code in the Quarto document.</p>
|
||||
<p>One common error in documents with code chunks is duplicated chunk labels, which are especially pervasive if your workflow involves copying and pasting code chunks. To address this issue, all you need to do is to change one of your duplicated labels.</p>
|
||||
<p>If the errors are due to the R code in the document, the first thing you should always try is to recreate the problem in an interactive session. Restart R, then “Run all chunks” (either from Code menu, under Run region), or with the keyboard shortcut Ctrl + Alt + R. If you’re lucky, that will recreate the problem, and you can figure out what’s going on interactively.</p>
|
||||
<p>If that doesn’t help, there must be something different between your interactive environment and the Quarto environment. You’re going to need to systematically explore the options. The most common difference is the working directory: the working directory of a Quarto is the directory in which it lives. Check the working directory is what you expect by including <code><a href="https://rdrr.io/r/base/getwd.html">getwd()</a></code> in a chunk.</p>
|
||||
<p>Next, brainstorm all the things that might cause the bug. You’ll need to systematically check that they’re the same in your R session and your Quarto session. The easiest way to do that is to set <code>error: true</code> on the chunk causing the problem, then use <code><a href="https://rdrr.io/r/base/print.html">print()</a></code> and <code><a href="https://rdrr.io/r/utils/str.html">str()</a></code> to check that settings are as you expect.</p>
|
||||
</section>
|
||||
</section>
|
||||
|
||||
<section id="yaml-header" data-type="sect1">
|
||||
<h1>
|
||||
@@ -586,7 +596,7 @@ YAML header</h1>
|
||||
<section id="self-contained" data-type="sect2">
|
||||
<h2>
|
||||
Self-contained</h2>
|
||||
<p>HTML documents typically have a number of external dependencies (e.g. images, CSS style sheets, JavaScript, etc.) and, by default, Quarto places these dependencies in a <code>_files</code> folder in the same directory as your <code>.qmd</code> file. If you publish the HTML file on a hosting platform (e.g., QuartoPub, <a href="https://quartopub.com/" class="uri">https://quartopub.com/</a>), the dependencies in this directory are published with your document and hence are available in the published report. However, if you want to email the report to a colleague, you might prefer to have a single, self-contained, HTML document that embeds all of its dependencies. You can do this by specifying the <code>embed-resources</code> option:</p>
|
||||
<p>HTML documents typically have a number of external dependencies (e.g. images, CSS style sheets, JavaScript, etc.) and, by default, Quarto places these dependencies in a <code>_files</code> folder in the same directory as your <code>.qmd</code> file. If you publish the HTML file on a hosting platform (e.g. QuartoPub, <a href="https://quartopub.com/" class="uri">https://quartopub.com/</a>), the dependencies in this directory are published with your document and hence are available in the published report. However, if you want to email the report to a colleague, you might prefer to have a single, self-contained, HTML document that embeds all of its dependencies. You can do this by specifying the <code>embed-resources</code> option:</p>
|
||||
<p>By default these dependencies are placed in a <code>_files</code> directory alongside your document. For example, if you render <code>report.qmd</code> to HTML:</p>
|
||||
<pre data-type="programlisting" data-code-language="yaml">format:
|
||||
html:
|
||||
@@ -620,7 +630,7 @@ class <- mpg |> filter(class == params$my_class)
|
||||
```{r}
|
||||
#| message: false
|
||||
|
||||
ggplot(class, aes(displ, hwy)) +
|
||||
ggplot(class, aes(x = displ, y = hwy)) +
|
||||
geom_point() +
|
||||
geom_smooth(se = FALSE)
|
||||
```</code></pre>
|
||||
|
||||
Reference in New Issue
Block a user