28  Quarto

28.1 Giới thiệu

Quarto cung cấp một khung soạn thảo thống nhất cho khoa học dữ liệu, kết hợp mã nguồn, kết quả và phần trình bày văn bản của bạn. Tài liệu Quarto hoàn toàn có thể tái tạo (reproducible) và hỗ trợ row chục định dạng đầu ra, như PDF, tệp Word, bài thuyết trình, và nhiều hơn nữa.

Tệp Quarto được thiết kế để sử dụng theo ba cách:

  1. Để truyền đạt đến người ra quyết định, những người muốn tập trung vào kết luận, không phải mã nguồn đằng sau phân tích.

  2. Để cộng tác với các nhà khoa học dữ liệu khác (bao gồm cả chính bạn trong tương lai!), những người quan tâm đến cả kết luận của bạn và cách bạn đạt được chúng (tức là mã nguồn).

  3. Như một environment để thực hiện khoa học dữ liệu, như một cuốn sổ phòng thí nghiệm hiện đại nơi bạn có thể ghi lại không chỉ những gì bạn đã làm, mà còn cả những gì bạn đang suy nghĩ.

Quarto là một công cụ giao diện dòng lệnh (command line interface), không phải một package R. Điều này có nghĩa là trợ giúp, nhìn chung, không có sẵn thông qua ?. Thay vào đó, khi bạn làm việc qua chương này, và sử dụng Quarto trong tương lai, bạn nên tham khảo tài liệu Quarto.

Nếu bạn là người dùng R Markdown, bạn có thể nghĩ “Quarto nghe giống R Markdown quá”. Bạn không sai! Quarto hợp nhất chức năng của nhiều package từ hệ sinh thái R Markdown (rmarkdown, bookdown, distill, xaringan, v.v.) thành một hệ thống nhất quán, đồng thời mở rộng thêm hỗ trợ gốc cho nhiều ngôn ngữ lập trình như Python và Julia ngoài R. Theo một cách nào đó, Quarto phản ánh tất cả những gì đã được học từ việc mở rộng và hỗ trợ hệ sinh thái R Markdown trong suốt một thập kỷ.

28.1.1 Điều kiện tiên quyết

Bạn cần giao diện dòng lệnh Quarto (Quarto CLI), nhưng bạn không cần cài đặt hay tải nó một cách rõ ràng, vì RStudio tự động thực hiện cả hai khi cần thiết.

28.2 Cơ bản về Quarto

Đây là một tệp Quarto – một tệp văn bản thuần có phần mở rộng .qmd:

---
title: "Diamond sizes"
date: 2022-09-12
format: html
---

```{r}
#| label: setup
#| include: false

library(tidyverse)

smaller <- diamonds |> 
  filter(carat <= 2.5)
```

We have data about `r nrow(diamonds)` diamonds.
Only `r nrow(diamonds) - nrow(smaller)` are larger than 2.5 carats.
The distribution of the remainder is shown below:

```{r}
#| label: plot-smaller-diamonds
#| echo: false

smaller |> 
  ggplot(aes(x = carat)) + 
  geom_freqpoly(binwidth = 0.01)
```

Nó chứa ba loại nội dung quan trọng:

  1. Một phần đầu YAML (tùy chọn) được bao quanh bởi ---.
  2. Các khối mã (chunk) R được bao quanh bởi ```.
  3. Văn bản kết hợp với định dạng văn bản đơn giản như # heading và _italics_.

Hình 28.1 cho thấy một tài liệu .qmd trong RStudio với giao diện notebook nơi mã nguồn và kết quả được xen kẽ nhau. Bạn có thể chạy từng khối mã bằng cách nhấp vào biểu tượng Run (trông giống nút phát ở đầu khối mã), hoặc bằng cách nhấn Cmd/Ctrl + Shift + Enter. RStudio thực thi mã nguồn và hiển thị kết quả ngay trong dòng cùng với mã.

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 than 2.5 carats. The plot shows that the frequency decreases as the weight increases.
Hình 28.1: Một tài liệu Quarto trong RStudio. Mã nguồn và kết quả được xen kẽ trong tài liệu, với biểu đồ đầu ra hiển thị ngay bên dưới mã nguồn.

Nếu bạn không thích nhìn thấy biểu đồ và kết quả đầu ra trong tài liệu và muốn sử dụng bảng Console và Plot của RStudio, bạn có thể nhấp vào biểu tượng bánh răng bên cạnh “Render” và chuyển sang “Chunk Output in Console”, như được hiển thị trong Hình 28.2.

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 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.
Hình 28.2: Một tài liệu Quarto trong RStudio với biểu đồ đầu ra trong bảng Plots.

Để tạo một báo cáo hoàn chỉnh chứa tất cả văn bản, mã nguồn và kết quả, nhấp “Render” hoặc nhấn Cmd/Ctrl + Shift + K. Bạn cũng có thể thực hiện điều này bằng lập trình với quarto::quarto_render("diamond-sizes.qmd"). Thao tác này sẽ hiển thị báo cáo trong bảng viewer như được chỉ ra trong Hình 28.3 và tạo một tệp HTML.

RStudio window with a Quarto document titled "diamond-sizes.qmd" on the left and the Plot pane on the bottom right. The rendered document does not show any of the code, but the code is visible in the source document.
Hình 28.3: Một tài liệu Quarto trong RStudio với tài liệu đã biên dịch trong bảng Viewer.

Khi bạn biên dịch (render) tài liệu, Quarto gửi tệp .qmd đến knitr, https://yihui.org/knitr/, nơi thực thi tất cả các khối mã và tạo một tài liệu markdown (.md) mới bao gồm mã nguồn và kết quả đầu ra. Tệp markdown được tạo bởi knitr sau đó được xử lý bởi pandoc, https://pandoc.org, chịu trách nhiệm tạo tệp hoàn chỉnh. Quy trình này được minh họa trong Hình 28.4. Ưu điểm của workflow hai bước này là bạn có thể tạo rất nhiều định dạng đầu ra khác nhau, như bạn sẽ tìm hiểu trong Chương 29.

Workflow diagram starting with a qmd file, then knitr, then md, then pandoc, then PDF, MS Word, or HTML.
Hình 28.4: Sơ đồ workflow Quarto từ qmd, đến knitr, đến md, đến pandoc, đến đầu ra ở các định dạng PDF, MS Word, hoặc HTML.

Để bắt đầu với tệp .qmd của riêng bạn, chọn File > New File > Quarto Document… trong thanh menu. RStudio sẽ khởi chạy một trình hướng dẫn mà bạn có thể sử dụng để điền trước nội dung hữu ích nhắc nhở bạn cách các tính năng chính của Quarto hoạt động.

Các phần tiếp theo sẽ đi sâu vào ba thành phần của tài liệu Quarto chi tiết hơn: văn bản markdown, các khối mã, và phần đầu YAML.

28.2.1 Bài tập

  1. Tạo một tài liệu Quarto mới bằng File > New File > Quarto Document. Đọc hướng dẫn. Thực hành chạy từng khối mã riêng lẻ. Sau đó biên dịch tài liệu bằng cách nhấp nút thích hợp và sau đó sử dụng phím tắt thích hợp. Xác minh rằng bạn có thể sửa đổi mã, chạy lại và xem kết quả đã thay đổi.

  2. Tạo một tài liệu Quarto mới cho mỗi trong ba định dạng có sẵn: HTML, PDF và Word. Biên dịch mỗi tài liệu trong ba tài liệu đó. Kết quả đầu ra khác nhau như thế nào? Đầu vào khác nhau như thế nào? (Bạn có thể cần cài đặt LaTeX để tạo đầu ra PDF — RStudio sẽ nhắc bạn nếu điều này cần thiết.)

28.3 Trình soạn thảo trực quan

Trình soạn thảo trực quan (Visual editor) trong RStudio cung cấp giao diện WYSIWYM để soạn thảo tài liệu Quarto. Bên dưới, văn bản trong tài liệu Quarto (tệp .qmd) được viết bằng Markdown, một tập hợp quy ước nhẹ để định dạng tệp văn bản thuần. Trên thực tế, Quarto sử dụng Pandoc markdown (một phiên bản mở rộng hơi của Markdown mà Quarto hiểu được), bao gồm bảng, trích dẫn, tham chiếu chéo, comment cuối trang, div/span, list định nghĩa, thuộc tính, HTML/TeX thô, và nhiều hơn nữa cũng như hỗ trợ thực thi các ô mã và xem kết quả đầu ra ngay trong dòng. Mặc dù Markdown được thiết kế để dễ đọc và viết, như bạn sẽ thấy trong Phần 28.4, nó vẫn yêu cầu học cú pháp mới. Do đó, nếu bạn mới làm quen với tài liệu tính toán như tệp .qmd nhưng có kinh nghiệm sử dụng các công cụ như Google Docs hay MS Word, cách dễ nhất để bắt đầu với Quarto trong RStudio là trình soạn thảo trực quan.

Trong trình soạn thảo trực quan, bạn có thể sử dụng các nút trên thanh menu để chèn hình ảnh, bảng, tham chiếu chéo, v.v. hoặc bạn có thể sử dụng phím tắt tổng hợp ⌘ + / hoặc Ctrl + / để chèn hầu như mọi thứ. Nếu bạn đang ở đầu dòng (như được hiển thị trong Hình 28.5), bạn cũng có thể chỉ nhập / để gọi phím tắt.

A Quarto document displaying various features of the visual editor such as text formatting (italic, bold, underline, small caps, code, superscript, and subscript), first through third level headings, bulleted and numbered lists, links, linked phrases, and images (along with a pop-up window for customizing image size, adding a caption and alt text, etc.), tables with a header row, and the insert anything tool with options to insert an R code chunk, a Python code chunk, a div, a bullet list, a numbered list, or a first level heading (the top few choices in the tool).
Hình 28.5: Trình soạn thảo trực quan Quarto.

Việc chèn hình ảnh và tùy chỉnh cách hiển thị chúng cũng được hỗ trợ bởi trình soạn thảo trực quan. Bạn có thể dán hình ảnh từ clipboard trực tiếp vào trình soạn thảo trực quan (và RStudio sẽ đặt một bản sao của hình ảnh đó trong thư mục dự án và liên kết đến nó) hoặc bạn có thể sử dụng menu Insert > Figure / Image của trình soạn thảo trực quan để duyệt đến hình ảnh bạn muốn chèn hoặc dán URL của nó. Ngoài ra, sử dụng cùng menu đó, bạn có thể thay đổi kích thước hình ảnh cũng như thêm comment, văn bản thay thế, và liên kết.

Trình soạn thảo trực quan có nhiều tính năng khác mà chúng tôi chưa liệt kê ở đây mà bạn có thể thấy hữu ích khi tích lũy kinh nghiệm soạn thảo với nó.

Quan trọng nhất, mặc dù trình soạn thảo trực quan hiển thị nội dung của bạn với định dạng, bên dưới nó lưu nội dung dưới dạng Markdown thuần và bạn có thể chuyển đổi qua lại giữa trình soạn thảo trực quan và trình soạn thảo mã nguồn để xem và chỉnh sửa nội dung bằng cả hai công cụ.

28.3.1 Bài tập

  1. Tạo lại tài liệu trong Hình 28.5 bằng trình soạn thảo trực quan.
  2. Sử dụng trình soạn thảo trực quan, chèn một khối mã bằng menu Insert và sau đó công cụ insert anything.
  3. Sử dụng trình soạn thảo trực quan, tìm hiểu cách:
    1. Thêm comment cuối trang.
    2. Thêm đường kẻ ngang.
    3. Thêm khối trích dẫn.
  4. Trong trình soạn thảo trực quan, vào Insert > Citation và chèn một trích dẫn cho bài báo có tiêu đề Welcome to the Tidyverse sử dụng DOI (mã định danh đối tượng số) của nó, là 10.21105/joss.01686. Biên dịch tài liệu và quan sát cách tham chiếu hiển thị trong tài liệu. Bạn quan sát thấy thay đổi gì trong YAML của tài liệu?

28.4 Trình soạn thảo mã nguồn

Bạn cũng có thể chỉnh sửa tài liệu Quarto bằng trình soạn thảo mã nguồn (Source editor) trong RStudio, mà không cần sự hỗ trợ của trình soạn thảo trực quan. Trong khi trình soạn thảo trực quan sẽ quen thuộc với những ai có kinh nghiệm viết trong các công cụ như Google Docs, trình soạn thảo mã nguồn sẽ quen thuộc với những ai có kinh nghiệm viết tập lệnh R hoặc tài liệu R Markdown. Trình soạn thảo mã nguồn cũng hữu ích để gỡ lỗi bất kỳ lỗi cú pháp Quarto nào vì thường dễ phát hiện chúng hơn trong văn bản thuần.

Hướng dẫn bên dưới cho thấy cách sử dụng Markdown của Pandoc để soạn thảo tài liệu Quarto trong trình soạn thảo mã nguồn.

## Text formatting

*italic* **bold** ~~strikeout~~ `code`

superscript^2^ subscript~2~

[underline]{.underline} [small caps]{.smallcaps}

## Headings

# 1st Level Header

## 2nd Level Header

### 3rd Level Header

## Lists

-   Bulleted list item 1

-   Item 2

    -   Item 2a

    -   Item 2b

1.  Numbered list item 1

2.  Item 2.
    The numbers are incremented automatically in the output.

## Links and images

<http://example.com>

[linked phrase](http://example.com)

![optional caption text](quarto.png){fig-alt="Quarto logo and the word quarto spelled in small case letters"}

## Tables

| First Header | Second Header |
|--------------|---------------|
| Content Cell | Content Cell  |
| Content Cell | Content Cell  |

Cách tốt nhất để học những điều này là đơn giản thử chúng. Sẽ mất vài ngày, nhưng sớm thôi chúng sẽ trở thành thói quen tự nhiên, và bạn sẽ không cần phải nghĩ về chúng. Nếu bạn quên, bạn có thể truy cập bảng tham khảo nhanh tiện dụng bằng Help > Markdown Quick Reference.

28.4.1 Bài tập

  1. Thực hành những gì bạn đã học bằng cách tạo một CV ngắn gọn. Tiêu đề nên là tên của bạn, và bạn nên bao gồm các đề mục cho (ít nhất) học vấn hoặc kinh nghiệm làm việc. Mỗi phần nên bao gồm một list có dấu đầu dòng các công việc/bằng cấp. Đánh đậm năm.

  2. Sử dụng trình soạn thảo mã nguồn và bảng tham khảo nhanh Markdown, tìm hiểu cách:

    1. Thêm comment cuối trang.
    2. Thêm đường kẻ ngang.
    3. Thêm khối trích dẫn.

  3. Sao chép và dán nội dung của diamond-sizes.qmd từ https://github.com/hadley/r4ds/tree/main/quarto vào một tài liệu R Quarto cục bộ. Kiểm tra rằng bạn có thể chạy nó, sau đó thêm văn bản sau đa giác tần suất mô tả các đặc điểm nổi bật nhất của nó.

  4. Tạo một tài liệu trong Google Docs hoặc MS Word (hoặc tìm một tài liệu bạn đã tạo trước đó) với một số nội dung như tiêu đề, siêu liên kết, văn bản định dạng, v.v. Sao chép nội dung của tài liệu này và dán vào một tài liệu Quarto trong trình soạn thảo trực quan. Sau đó, chuyển sang trình soạn thảo mã nguồn và kiểm tra mã nguồn.

28.5 Khối mã

Để chạy mã bên trong một tài liệu Quarto, bạn cần chèn một khối mã (chunk). Có ba cách để làm điều đó:

  1. Phím tắt Cmd + Option + I / Ctrl + Alt + I.

  2. Nút biểu tượng “Insert” trên thanh công cụ trình soạn thảo.

  3. Bằng cách gõ thủ công các dấu phân cách khối mã ```{r} và ```.

Chúng tôi khuyên bạn nên học phím tắt. Nó sẽ tiết kiệm cho bạn rất nhiều thời gian về lâu dài!

Bạn có thể tiếp tục chạy mã bằng phím tắt mà đến giờ (chúng tôi hy vọng!) bạn đã biết và yêu thích: Cmd/Ctrl + Enter. Tuy nhiên, khối mã có thêm một phím tắt mới: Cmd/Ctrl + Shift + Enter, chạy tất cả mã trong khối mã. Hãy nghĩ về khối mã như một function. Một khối mã nên tương đối độc lập và tập trung vào một nhiệm vụ duy nhất.

Các phần tiếp theo mô tả phần đầu khối mã bao gồm ```{r}, theo sau là nhãn khối mã tùy chọn và các tùy chọn khối mã khác nhau, mỗi tùy chọn trên dòng riêng, được đánh dấu bằng #|.

28.5.1 Nhãn khối mã

Các khối mã có thể được gán một nhãn (label) tùy chọn, ví dụ:

```{r}
#| label: simple-addition
1 + 1
```
#> [1] 2

Điều này có ba ưu điểm:

  1. Bạn có thể dễ dàng điều hướng đến các khối mã cụ thể bằng trình điều hướng mã thả xuống ở góc dưới bên trái của trình soạn thảo tập lệnh:

    Snippet of RStudio IDE showing only the drop-down code navigator which shows three chunks. Chunk 1 is setup. Chunk 2 is cars and it is in a section called Quarto. Chunk 3 is pressure and it is in a section called Including plots.

  2. Đồ họa được tạo bởi các khối mã sẽ có tên hữu ích giúp chúng dễ sử dụng ở nơi khác hơn. Thêm về điều này trong Phần 28.6.

  3. Bạn có thể thiết lập mạng lưới các khối mã được lưu bộ nhớ đệm (cache) để tránh thực hiện lại các phép tính tốn kém mỗi lần chạy. Thêm về điều này trong Phần 28.8.

Nhãn khối mã của bạn nên ngắn gọn nhưng gợi nhớ và không nên chứa khoảng trắng. Chúng tôi khuyên sử dụng dấu gạch ngang (-) để phân tách các từ (thay vì dấu gạch dưới, _) và tránh các ký tự đặc biệt khác trong nhãn khối mã.

Bạn thường được tự do đặt tên khối mã theo ý muốn, nhưng có một tên khối mã mang hành vi đặc biệt: setup. Khi bạn ở chế độ notebook, khối mã có tên setup sẽ được chạy tự động một lần, trước bất kỳ mã nào khác được chạy.

Ngoài ra, nhãn khối mã không thể bị trùng iterate. Mỗi nhãn khối mã phải là duy nhất.

28.5.2 Tùy chọn khối mã

Kết quả đầu ra của khối mã có thể được tùy chỉnh bằng các tùy chọn (option), các trường được cung cấp cho phần đầu khối mã. Knitr cung cấp gần 60 tùy chọn mà bạn có thể sử dụng để tùy chỉnh các khối mã của mình. Ở đây chúng tôi sẽ đề cập đến các tùy chọn khối mã quan trọng nhất mà bạn sẽ sử dụng thường xuyên. Bạn có thể xem list đầy đủ tại https://yihui.org/knitr/options.

Tập hợp tùy chọn quan trọng nhất kiểm soát liệu khối mã của bạn có được thực thi hay không và kết quả nào được chèn vào báo cáo hoàn chỉnh:

  • eval: false ngăn mã không được thực thi. (Và hiển nhiên nếu mã không được chạy, không có kết quả nào được tạo ra). Điều này hữu ích để hiển thị mã ví dụ, hoặc để vô hiệu hóa một khối mã lớn mà không cần comment từng dòng.

  • include: false chạy mã, nhưng không hiển thị mã hoặc kết quả trong tài liệu cuối cùng. Sử dụng điều này cho mã thiết lập mà bạn không muốn làm rối báo cáo.

  • echo: false ngăn mã, nhưng không ngăn kết quả, xuất hiện trong tệp hoàn chỉnh. Sử dụng điều này khi viết báo cáo nhắm đến những người không muốn xem mã R bên dưới.

  • message: false hoặc warning: false ngăn thông báo hoặc cảnh báo xuất hiện trong tệp hoàn chỉnh.

  • results: hide ẩn kết quả in ra; fig-show: hide ẩn biểu đồ.

  • error: true cho phép quá trình biên dịch tiếp tục ngay cả khi mã trả về lỗi. Đây hiếm khi là điều bạn muốn bao gồm trong phiên bản cuối cùng của báo cáo, nhưng có thể rất hữu ích nếu bạn cần gỡ lỗi chính xác điều gì đang xảy ra bên trong tệp .qmd của bạn. Nó cũng hữu ích nếu bạn đang dạy R và muốn cố tình bao gồm một lỗi. Mặc định, error: false khiến quá trình biên dịch thất bại nếu có một lỗi duy nhất trong tài liệu.

Mỗi tùy chọn khối mã này được thêm vào phần đầu của khối mã, theo sau #|, ví dụ, trong khối mã sau kết quả không được in ra vì eval được đặt thành false.

```{r}
#| label: simple-multiplication
#| eval: false
2 * 2
```

Bảng sau tóm tắt loại kết quả đầu ra nào mà mỗi tùy chọn triệt tiêu:

Tùy chọn Chạy mã Hiện mã Kết quả Biểu đồ Thông báo Cảnh báo
eval: false X X X X X
include: false X X X X X
echo: false X
results: hide X
fig-show: hide X
message: false X
warning: false X

28.5.3 Tùy chọn toàn cục

Khi bạn làm việc nhiều hơn với knitr, bạn sẽ phát hiện rằng một số tùy chọn khối mã mặc định không phù hợp với nhu cầu của bạn và bạn muốn thay đổi chúng.

Bạn có thể làm điều này bằng cách thêm các tùy chọn ưa thích trong YAML của tài liệu, dưới execute. Ví dụ, nếu bạn đang chuẩn bị báo cáo cho đối tượng không cần xem mã của bạn mà chỉ cần kết quả và phần trình bày, bạn có thể đặt echo: false ở cấp tài liệu. Điều đó sẽ ẩn mã theo mặc định, chỉ hiển thị các khối mã mà bạn chủ ý chọn hiển thị (với echo: true). Bạn có thể cân nhắc đặt message: false và warning: false, nhưng điều đó sẽ khiến việc gỡ lỗi khó khăn hơn vì bạn sẽ không thấy bất kỳ thông báo nào trong tài liệu cuối cùng.

title: "My report"
execute:
  echo: false

Vì Quarto được thiết kế đa ngôn ngữ (hoạt động với R cũng như các ngôn ngữ khác như Python, Julia, v.v.), không phải tất cả tùy chọn knitr đều có sẵn ở cấp thực thi tài liệu vì một số chỉ hoạt động với knitr chứ không hoạt động với các engine khác mà Quarto sử dụng để chạy mã trong các ngôn ngữ khác (ví dụ, Jupyter). Tuy nhiên, bạn vẫn có thể đặt chúng làm tùy chọn toàn cục cho tài liệu dưới trường knitr, trong opts_chunk. Ví dụ, khi viết sách và hướng dẫn, chúng tôi đặt:

title: "Tutorial"
knitr:
  opts_chunk:
    comment: "#>"
    collapse: true

Điều này sử dụng định dạng comment ưa thích của chúng tôi và đảm bảo rằng mã nguồn và kết quả đầu ra được giữ gắn kết chặt chẽ.

28.5.4 Mã nội tuyến

Có một cách khác để nhúng mã R vào tài liệu Quarto: trực tiếp vào văn bản, với: `r `. Điều này có thể rất hữu ích nếu bạn đề cập đến các thuộc tính của dữ liệu trong văn bản. Ví dụ, tài liệu mẫu được sử dụng ở đầu chương có:

We have data about `r nrow(diamonds)` diamonds. Only `r nrow(diamonds) - nrow(smaller)` are larger than 2.5 carats. The distribution of the remainder is shown below:

Khi báo cáo được biên dịch, kết quả của các phép tính này được chèn vào văn bản:

We have data about 53940 diamonds. Only 126 are larger than 2.5 carats. The distribution of the remainder is shown below:

Khi chèn số vào văn bản, format() là người bạn đồng hành của bạn. Nó cho phép bạn đặt số chữ số digits để không in với độ chính xác quá mức, và big.mark để làm cho số dễ đọc hơn. Bạn có thể kết hợp chúng thành một function trợ giúp:

comma <- function(x) format(x, digits = 2, big.mark = ",")
comma(3452345)
#> [1] "3,452,345"
comma(.12358124331)
#> [1] "0.12"

28.5.5 Bài tập

  1. Thêm một phần khám phá cách kích thước kim cương thay đổi theo cut, color, và clarity. Giả sử bạn đang viết báo cáo cho người không biết R, và thay vì đặt echo: false trên mỗi khối mã, hãy đặt tùy chọn toàn cục.

  2. Tải diamond-sizes.qmd từ https://github.com/hadley/r4ds/tree/main/quarto. Thêm một phần mô tả 20 viên kim cương lớn nhất, bao gồm một bảng hiển thị các thuộc tính quan trọng nhất của chúng.

  3. Sửa đổi diamonds-sizes.qmd để sử dụng label_comma() để tạo kết quả đầu ra được định dạng đẹp. Cũng bao gồm phần trăm kim cương lớn hơn 2.5 carat.

28.6 Hình ảnh

Hình ảnh trong tài liệu Quarto có thể được nhúng (ví dụ, tệp PNG hoặc JPEG) hoặc được tạo ra từ kết quả của một khối mã.

Để nhúng hình ảnh từ tệp bên ngoài, bạn có thể sử dụng menu Insert trong trình soạn thảo trực quan của RStudio và chọn Figure / Image. Thao tác này sẽ mở ra một menu nơi bạn có thể duyệt đến hình ảnh bạn muốn chèn cũng như thêm văn bản thay thế hoặc comment và điều chỉnh kích thước. Trong trình soạn thảo trực quan, bạn cũng có thể đơn giản dán hình ảnh từ clipboard vào tài liệu và RStudio sẽ đặt một bản sao của hình ảnh đó trong thư mục dự án của bạn.

Nếu bạn bao gồm một khối mã tạo ra hình ảnh (ví dụ, chứa lệnh gọi ggplot()), hình ảnh kết quả sẽ tự động được bao gồm trong tài liệu Quarto của bạn.

28.6.1 Kích thước hình ảnh

Thách thức lớn nhất của đồ họa trong Quarto là đạt được kích thước và hình dạng phù hợp cho hình ảnh. Có năm tùy chọn chính kiểm soát kích thước hình ảnh: fig-width, fig-height, fig-asp, out-width và out-height. Kích thước hình ảnh là một thách thức vì có hai kích thước (kích thước hình ảnh do R tạo ra và kích thước khi nó được chèn vào tài liệu đầu ra), và nhiều cách chỉ định kích thước (tức là chiều cao, chiều rộng, và tỷ lệ khung hình: chọn hai trong ba).

Chúng tôi khuyên dùng ba trong năm tùy chọn:

  • Biểu đồ có xu hướng đẹp hơn về mặt thẩm mỹ nếu chúng có chiều rộng nhất quán. Để thực thi điều này, đặt fig-width: 6 (6”) và fig-asp: 0.618 (tỷ lệ vàng) trong giá trị mặc định. Sau đó trong từng khối mã riêng lẻ, chỉ điều chỉnh fig-asp.

  • Kiểm soát kích thước đầu ra với out-width và đặt nó thành phần trăm chiều rộng phần thân của tài liệu đầu ra. Chúng tôi gợi ý out-width: "70%" và fig-align: center.

    Điều đó cho biểu đồ không gian thoáng, mà không chiếm quá nhiều chỗ.

  • Để đặt nhiều biểu đồ trong một row, đặt layout-ncol thành 2 cho hai biểu đồ, 3 cho ba biểu đồ, v.v. Điều này thực tế đặt out-width thành “50%” cho mỗi biểu đồ nếu layout-ncol là 2, “33%” nếu layout-ncol là 3, v.v. Tùy thuộc vào những gì bạn đang cố minh họa (ví dụ, hiển thị dữ liệu hoặc hiển thị các biến thể biểu đồ), bạn cũng có thể điều chỉnh fig-width, như được thảo luận bên dưới.

Nếu bạn thấy mình phải nheo mắt để đọc chữ trong biểu đồ, bạn cần điều chỉnh fig-width. Nếu fig-width lớn hơn kích thước mà hình ảnh được biên dịch trong tài liệu cuối cùng, chữ sẽ quá nhỏ; nếu fig-width nhỏ hơn, chữ sẽ quá lớn. Bạn thường sẽ cần thử nghiệm một chút để tìm ra tỷ lệ phù hợp giữa fig-width và chiều rộng cuối cùng trong tài liệu của bạn. Để minh họa nguyên tắc, ba biểu đồ sau có fig-width lần lượt là 4, 6, và 8:

Scatterplot of highway mileage vs. displacement of cars, where the points are normally sized and the axis text and labels are in similar font size to the surrounding text.

Scatterplot of highway mileage vs. displacement of cars, where the points are smaller than in the previous plot and the axis text and labels are smaller than the surrounding text.

Scatterplot of highway mileage vs. displacement of cars, where the points are even smaller than in the previous plot and the axis text and labels are even smaller than the surrounding text.

Nếu bạn muốn đảm bảo cỡ chữ nhất quán trên tất cả hình ảnh, mỗi khi bạn đặt out-width, bạn cũng cần điều chỉnh fig-width để duy trì cùng tỷ lệ với out-width mặc định. Ví dụ, nếu fig-width mặc định là 6 và out-width là “70%”, khi bạn đặt out-width: "50%" bạn sẽ cần đặt fig-width thành 4.3 (6 * 0.5 / 0.7).

Kích thước và tỷ lệ hình ảnh vừa là nghệ thuật vừa là khoa học và việc đạt được kết quả đúng có thể yêu cầu phương pháp thử-và-sai iterate đi iterate lại. Bạn có thể tìm hiểu thêm về kích thước hình ảnh trong bài viết blog về kiểm soát tỷ lệ biểu đồ.

28.6.2 Các tùy chọn quan trọng khác

Khi kết hợp mã và văn bản, như trong cuốn sách này, bạn có thể đặt fig-show: hold để biểu đồ được hiển thị sau mã. Điều này có tác dụng phụ tốt là buộc bạn chia nhỏ các khối mã lớn với phần giải thích của chúng.

Để thêm comment cho biểu đồ, sử dụng fig-cap. Trong Quarto, điều này sẽ thay đổi hình ảnh từ dạng nội tuyến sang dạng “nổi” (floating).

Nếu bạn đang tạo đầu ra PDF, loại đồ họa mặc định là PDF. Đây là mặc định tốt vì PDF là đồ họa vector chất lượng cao. Tuy nhiên, chúng có thể tạo ra các biểu đồ rất lớn và chậm nếu bạn hiển thị row nghìn điểm. Trong trường hợp đó, đặt fig-format: "png" để buộc sử dụng PNG. Chúng có chất lượng hơi thấp hơn, nhưng sẽ nhỏ gọn hơn nhiều.

Đặt tên cho các khối mã tạo ra hình ảnh là một ý tưởng tốt, ngay cả khi bạn không thường xuyên đặt nhãn cho các khối mã khác. Nhãn khối mã được sử dụng để tạo tên tệp của đồ họa trên đĩa, vì vậy việc đặt tên khối mã giúp dễ dàng hơn nhiều để chọn ra các biểu đồ và tái sử dụng trong các trường hợp khác (ví dụ, nếu bạn muốn nhanh chóng đưa một biểu đồ đơn lẻ vào email).

28.6.3 Bài tập

  1. Mở diamond-sizes.qmd trong trình soạn thảo trực quan, tìm một hình ảnh viên kim cương, sao chép nó, và dán vào tài liệu. Nhấp đúp vào hình ảnh và thêm comment. Thay đổi kích thước hình ảnh và biên dịch tài liệu. Quan sát cách hình ảnh được lưu trong thư mục làm việc hiện tại.
  2. Chỉnh sửa nhãn của khối mã trong diamond-sizes.qmd tạo ra biểu đồ để bắt đầu bằng tiền tố fig- và thêm comment cho hình ảnh bằng tùy chọn khối mã fig-cap. Sau đó, chỉnh sửa văn bản phía trên khối mã để thêm tham chiếu chéo đến hình ảnh bằng Insert > Cross Reference.
  3. Thay đổi kích thước hình ảnh bằng các tùy chọn khối mã sau, từng cái một, biên dịch tài liệu và mô tả hình ảnh thay đổi như thế nào.

    1. fig-width: 10

    2. fig-height: 3

    3. out-width: "100%"

    4. out-width: "20%"

28.7 Bảng

Tương tự như hình ảnh, bạn có thể bao gồm hai loại bảng trong tài liệu Quarto. Chúng có thể là bảng markdown mà bạn tạo trực tiếp trong tài liệu Quarto (sử dụng menu Insert Table) hoặc chúng có thể là bảng được tạo ra từ kết quả của một khối mã. Trong phần này, chúng ta sẽ tập trung vào loại sau, bảng được tạo thông qua tính toán.

Theo mặc định, Quarto in data frame và ma trận như bạn thấy chúng trong console:

mtcars[1:5, ]
#>                    mpg cyl disp  hp drat    wt  qsec vs am gear carb
#> Mazda RX4         21.0   6  160 110 3.90 2.620 16.46  0  1    4    4
#> Mazda RX4 Wag     21.0   6  160 110 3.90 2.875 17.02  0  1    4    4
#> Datsun 710        22.8   4  108  93 3.85 2.320 18.61  1  1    4    1
#> Hornet 4 Drive    21.4   6  258 110 3.08 3.215 19.44  1  0    3    1
#> Hornet Sportabout 18.7   8  360 175 3.15 3.440 17.02  0  0    3    2

Nếu bạn muốn dữ liệu được hiển thị với định dạng bổ sung, bạn có thể sử dụng function knitr::kable(). Mã bên dưới tạo ra Bảng 28.1.

knitr::kable(mtcars[1:5, ], )
Bảng 28.1: A knitr kable.
mpg cyl disp hp drat wt qsec vs am gear carb
Mazda RX4 21.0 6 160 110 3.90 2.620 16.46 0 1 4 4
Mazda RX4 Wag 21.0 6 160 110 3.90 2.875 17.02 0 1 4 4
Datsun 710 22.8 4 108 93 3.85 2.320 18.61 1 1 4 1
Hornet 4 Drive 21.4 6 258 110 3.08 3.215 19.44 1 0 3 1
Hornet Sportabout 18.7 8 360 175 3.15 3.440 17.02 0 0 3 2

Đọc tài liệu cho ?knitr::kable để xem các cách khác mà bạn có thể tùy chỉnh bảng. Để tùy chỉnh sâu hơn, hãy cân nhắc các package gt, huxtable, reactable, kableExtra, xtable, stargazer, pander, tables, và ascii. Mỗi package cung cấp một bộ công cụ để trả về bảng đã định dạng từ mã R.

28.7.1 Bài tập

  1. Mở diamond-sizes.qmd trong trình soạn thảo trực quan, chèn một khối mã, và thêm một bảng bằng knitr::kable() hiển thị 5 row đầu tiên của data frame diamonds.
  2. Hiển thị cùng bảng đó bằng gt::gt() thay thế.
  3. Thêm nhãn khối mã bắt đầu bằng tiền tố tbl- và thêm comment cho bảng bằng tùy chọn khối mã tbl-cap. Sau đó, chỉnh sửa văn bản phía trên khối mã để thêm tham chiếu chéo đến bảng bằng Insert > Cross Reference.

28.8 Bộ nhớ đệm

Thông thường, mỗi lần biên dịch tài liệu bắt đầu từ một trang hoàn toàn mới. Điều này tuyệt vời cho tính tái tạo, vì nó đảm bảo rằng bạn đã ghi lại mọi phép tính quan trọng trong mã. Tuy nhiên, nó có thể gây khó chịu nếu bạn có một số phép tính mất nhiều thời gian. Giải pháp là cache: true.

Bạn có thể bật bộ nhớ đệm (cache) Knitr ở cấp tài liệu để lưu kết quả của tất cả phép tính trong tài liệu bằng các tùy chọn YAML tiêu chuẩn:

---
title: "My Document"
execute:
  cache: true
---

Bạn cũng có thể bật bộ nhớ đệm ở cấp khối mã để lưu kết quả tính toán trong một khối mã cụ thể:

```{r}
#| cache: true
# code for lengthy computation...
```

Khi được đặt, điều này sẽ lưu kết quả đầu ra của khối mã vào một tệp có tên đặc biệt trên đĩa. Trong các lần chạy tiếp theo, knitr sẽ kiểm tra xem mã có thay đổi không, và nếu không, nó sẽ tái sử dụng kết quả đã lưu trong bộ nhớ đệm.

Hệ thống bộ nhớ đệm phải được sử dụng cẩn thận, vì theo mặc định nó chỉ dựa trên mã, không phải các phụ thuộc của nó. Ví dụ, ở đây khối mã processed_data phụ thuộc vào khối mã raw-data:

``` {{r}}
#| label: raw-data
#| cache: true
rawdata <- readr::read_csv("a_very_large_file.csv")
```
``` {{r}}
#| label: processed_data
#| cache: true
processed_data <- rawdata |>
  filter(!is.na(import_var)) |>
  mutate(new_variable = complicated_transformation(x, y, z))
```

Lưu bộ nhớ đệm cho khối mã processed_data có nghĩa là nó sẽ được chạy lại nếu pipeline dplyr thay đổi, nhưng nó sẽ không được chạy lại nếu lệnh gọi read_csv() thay đổi. Bạn có thể tránh vấn đề đó với tùy chọn khối mã dependson:

``` {{r}}
#| label: processed-data
#| cache: true
#| dependson: "raw-data"
processed_data <- rawdata |>
  filter(!is.na(import_var)) |>
  mutate(new_variable = complicated_transformation(x, y, z))
```

dependson nên chứa một vector ký tự của mọi khối mã mà khối mã được lưu đệm phụ thuộc vào. Knitr sẽ cập nhật kết quả cho khối mã được lưu đệm bất cứ khi nào nó phát hiện rằng một trong các phụ thuộc đã thay đổi.

Lưu ý rằng các khối mã sẽ không cập nhật nếu a_very_large_file.csv thay đổi, vì bộ nhớ đệm knitr chỉ theo dõi thay đổi trong tệp .qmd. Nếu bạn muốn cũng theo dõi thay đổi của tệp đó, bạn có thể sử dụng tùy chọn cache.extra. Đây là một biểu thức R tùy ý sẽ vô hiệu hóa bộ nhớ đệm bất cứ khi nào nó thay đổi. Một function tốt để sử dụng là file.mtime(): nó trả về thời điểm tệp được sửa đổi lần cuối. Khi đó bạn có thể viết:

``` {{r}}
#| label: raw-data
#| cache: true
#| cache.extra: !expr file.mtime("a_very_large_file.csv")
rawdata <- readr::read_csv("a_very_large_file.csv")
```

Chúng tôi đã tuân theo lời khuyên của David Robinson để đặt tên cho các khối mã này: mỗi khối mã được đặt tên theo đối tượng chính mà nó tạo ra. Điều này giúp dễ hiểu hơn đặc tả dependson.

Khi chiến lược bộ nhớ đệm của bạn ngày càng phức tạp hơn, bạn nên thường xuyên xóa tất cả bộ nhớ đệm bằng knitr::clean_cache().

28.8.1 Bài tập

  1. Thiết lập một mạng lưới các khối mã trong đó d phụ thuộc vào c và b, và cả b lẫn c đều phụ thuộc vào a. Cho mỗi khối mã in lubridate::now(), đặt cache: true, sau đó xác minh hiểu biết của bạn về bộ nhớ đệm.

28.9 Khắc phục sự cố

Khắc phục sự cố cho tài liệu Quarto có thể khó khăn vì bạn không còn ở trong environment R tương tác, và bạn sẽ cần học một số mẹo mới. Ngoài ra, lỗi có thể do vấn đề với chính tài liệu Quarto hoặc do mã R trong tài liệu Quarto.

Một lỗi phổ biến trong tài liệu có khối mã là nhãn khối mã bị trùng iterate, đặc biệt hay gặp nếu workflow của bạn liên quan đến việc sao chép và dán khối mã. Để giải quyết vấn đề này, tất cả những gì bạn cần làm là thay đổi một trong các nhãn bị trùng.

Nếu lỗi do mã R trong tài liệu, điều đầu tiên bạn nên luôn thử là tái tạo vấn đề trong một phiên tương tác. Khởi động lại R, sau đó “Run all chunks”, từ menu Code, dưới Run region hoặc với phím tắt Ctrl + Alt + R. Nếu may mắn, điều đó sẽ tái tạo vấn đề, và bạn có thể tìm hiểu chuyện gì đang xảy ra một cách tương tác.

Nếu điều đó không giúp ích, phải có điều gì đó khác biệt giữa environment tương tác và environment Quarto. Bạn sẽ cần khám phá các tùy chọn một cách có hệ thống. Sự khác biệt phổ biến nhất là thư mục làm việc: thư mục làm việc của Quarto là thư mục chứa nó. Kiểm tra thư mục làm việc có đúng như bạn mong đợi bằng cách thêm getwd() vào một khối mã.

Tiếp theo, liệt kê tất cả những thứ có thể gây ra lỗi. Bạn sẽ cần kiểm tra một cách có hệ thống rằng chúng giống nhau trong phiên R và phiên Quarto. Cách dễ nhất để làm điều đó là đặt error: true trên khối mã gây ra vấn đề, sau đó sử dụng print() và str() để kiểm tra rằng các cài đặt đúng như bạn mong đợi.

28.10 Phần đầu YAML

Bạn có thể kiểm soát nhiều cài đặt “toàn bộ tài liệu” khác bằng cách điều chỉnh các parameter của phần đầu YAML. Bạn có thể thắc mắc YAML là viết tắt của gì: đó là “YAML Ain’t Markup Language”, được thiết kế để biểu diễn dữ liệu phân cấp theo cách dễ đọc và viết cho con người. Quarto sử dụng nó để kiểm soát nhiều chi tiết của đầu ra. Ở đây chúng ta sẽ thảo luận ba nội dung: tài liệu độc lập, parameter tài liệu, và thư mục tham khảo.

28.10.1 Tài liệu độc lập

Tài liệu HTML thường có một số phụ thuộc bên ngoài (ví dụ, hình ảnh, bảng định kiểu CSS, JavaScript, v.v.) và theo mặc định, Quarto đặt các phụ thuộc này trong thư mục _files cùng thư mục với tệp .qmd của bạn. Nếu bạn xuất bản tệp HTML trên một nền tảng lưu trữ (ví dụ, QuartoPub, https://quartopub.com/), các phụ thuộc trong thư mục này được xuất bản cùng tài liệu của bạn và do đó có sẵn trong báo cáo đã xuất bản. Tuy nhiên, nếu bạn muốn gửi email báo cáo cho đồng nghiệp, bạn có thể muốn có một tệp HTML đơn lẻ, độc lập, nhúng tất cả phụ thuộc. Bạn có thể làm điều này bằng cách chỉ định tùy chọn embed-resources:

format:
  html:
    embed-resources: true

Tệp kết quả sẽ hoàn toàn độc lập, không cần tệp bên ngoài và không cần truy cập internet để hiển thị đúng trong trình duyệt.

28.10.2 Tham số

Tài liệu Quarto có thể bao gồm một hoặc nhiều parameter (parameter) mà giá trị của chúng có thể được đặt khi bạn biên dịch báo cáo. Tham số hữu ích khi bạn muốn biên dịch lại cùng một báo cáo với các giá trị khác nhau cho các đầu vào chính. Ví dụ, bạn có thể đang tạo báo cáo bán row theo chi nhánh, kết quả thi theo sinh viên, hoặc tóm tắt nhân khẩu học theo quốc gia. Để khai báo một hoặc nhiều parameter, sử dụng trường params.

Ví dụ này sử dụng parameter my_class để xác định lớp xe nào sẽ hiển thị:

---
format: html
params:
  my_class: "suv"
---

```{r}
#| label: setup
#| include: false

library(tidyverse)

class <- mpg |> filter(class == params$my_class)
```

# Fuel economy for `r params$my_class`s

```{r}
#| message: false

ggplot(class, aes(x = displ, y = hwy)) + 
  geom_point() + 
  geom_smooth(se = FALSE)
```

Như bạn có thể thấy, parameter có sẵn trong các khối mã dưới dạng list chỉ đọc có tên params.

Bạn có thể viết vector nguyên tử trực tiếp vào phần đầu YAML. Bạn cũng có thể chạy biểu thức R tùy ý bằng cách thêm tiền tố !expr trước giá trị parameter. Đây là cách tốt để chỉ định parameter ngày/giờ.

params:
  start: !expr lubridate::ymd("2015-01-01")
  snapshot: !expr lubridate::ymd_hms("2015-01-01 12:30:00")

28.10.3 Thư mục tham khảo và trích dẫn

Quarto có thể tự động tạo trích dẫn và thư mục tham khảo (bibliography) theo nhiều kiểu. Cách đơn giản nhất để thêm trích dẫn và thư mục tham khảo vào tài liệu Quarto là sử dụng trình soạn thảo trực quan trong RStudio.

Để thêm trích dẫn bằng trình soạn thảo trực quan, vào Insert > Citation. Trích dẫn có thể được chèn từ nhiều nguồn khác nhau:

  1. Tham chiếu DOI (Document Object Identifier).

  2. Thư viện cá nhân hoặc nhóm Zotero.

  3. Tìm kiếm Crossref, DataCite, hoặc PubMed.

  4. Thư mục tham khảo tài liệu của bạn (tệp .bib trong thư mục tài liệu)

Bên dưới, chế độ trực quan sử dụng biểu diễn Pandoc markdown tiêu chuẩn cho trích dẫn (ví dụ, [@citation]).

Nếu bạn thêm trích dẫn bằng một trong ba phương pháp đầu tiên, trình soạn thảo trực quan sẽ tự động tạo tệp bibliography.bib cho bạn và thêm tham chiếu vào đó. Nó cũng sẽ thêm trường bibliography vào YAML của tài liệu. Khi bạn thêm nhiều tham chiếu hơn, tệp này sẽ được điền các trích dẫn. Bạn cũng có thể chỉnh sửa trực tiếp tệp này bằng nhiều định dạng thư mục tham khảo phổ biến bao gồm BibLaTeX, BibTeX, EndNote, Medline.

Để tạo trích dẫn trong tệp .qmd bằng trình soạn thảo mã nguồn, sử dụng khóa gồm ‘@’ + mã định danh trích dẫn từ tệp thư mục tham khảo. Sau đó đặt trích dẫn trong ngoặc vuông. Dưới đây là một số ví dụ:

Separate multiple citations with a `;`: Blah blah [@smith04; @doe99].

You can add arbitrary comments inside the square brackets:
Blah blah [see @doe99, pp. 33-35; also @smith04, ch. 1].

Remove the square brackets to create an in-text citation: @smith04
says blah, or @smith04 [p. 33] says blah.

Add a `-` before the citation to suppress the author's name:
Smith says blah [-@smith04].

Khi Quarto biên dịch tệp, nó sẽ xây dựng và thêm thư mục tham khảo vào cuối tài liệu. Thư mục tham khảo sẽ chứa mỗi tham chiếu được trích dẫn từ tệp thư mục tham khảo, nhưng nó sẽ không chứa tiêu đề phần. Do đó, thực hành phổ biến là kết thúc tệp bằng tiêu đề phần cho thư mục tham khảo, như # References hoặc # Bibliography.

Bạn có thể thay đổi kiểu trích dẫn và thư mục tham khảo bằng cách tham chiếu tệp CSL (citation style language) trong trường csl:

bibliography: rmarkdown.bib
csl: apa.csl

Giống như trường bibliography, tệp csl của bạn nên chứa đường dẫn đến tệp. Ở đây chúng ta giả sử rằng tệp csl nằm trong cùng thư mục với tệp .qmd. Một nơi tốt để tìm tệp kiểu CSL cho các kiểu thư mục tham khảo phổ biến là https://github.com/citation-style-language/styles.

28.11 Quy trình làm việc

Trước đó, chúng ta đã thảo luận về một workflow cơ bản để ghi lại mã R nơi bạn làm việc tương tác trong console, sau đó ghi lại những gì hoạt động trong trình soạn thảo tập lệnh. Quarto kết hợp console và trình soạn thảo tập lệnh, làm mờ ranh giới giữa khám phá tương tác và ghi lại mã lâu dài. Bạn có thể iterate nhanh trong một khối mã, chỉnh sửa và thực thi lại với Cmd/Ctrl + Shift + Enter. Khi bạn hài lòng, bạn chuyển sang và bắt đầu một khối mã mới.

Quarto cũng quan trọng vì nó tích hợp chặt chẽ văn bản và mã. Điều này làm cho nó trở thành một sổ phân tích (analysis notebook) tuyệt vời vì nó cho phép bạn phát triển mã và ghi lại suy nghĩ. Sổ phân tích chia sẻ nhiều mục tiêu giống với sổ phòng thí nghiệm cổ điển trong khoa học vật lý. Nó:

  • Ghi lại những gì bạn đã làm và tại sao bạn làm điều đó. Bất kể trí nhớ của bạn tốt đến đâu, nếu bạn không ghi lại những gì mình làm, sẽ có lúc bạn quên những chi tiết quan trọng. Viết chúng ra để bạn không quên!

  • Hỗ trợ tư duy nghiêm ngặt. Bạn có khả năng đưa ra phân tích mạnh mẽ hơn nếu bạn ghi lại suy nghĩ trong quá trình và tiếp tục suy ngẫm về chúng. Điều này cũng tiết kiệm thời gian khi cuối cùng bạn viết phân tích để chia sẻ với người khác.

  • Giúp người khác hiểu công việc của bạn. Hiếm khi bạn phân tích dữ liệu một mình, và bạn thường sẽ làm việc trong một nhóm. Sổ phòng thí nghiệm giúp bạn chia sẻ không chỉ những gì bạn đã làm, mà còn tại sao bạn làm điều đó với đồng nghiệp hoặc bạn cùng phòng thí nghiệm.

Nhiều lời khuyên tốt về việc sử dụng sổ phòng thí nghiệm hiệu quả cũng có thể được áp dụng cho sổ phân tích. Chúng tôi đã rút ra từ kinh nghiệm của mình và lời khuyên của Colin Purrington về sổ phòng thí nghiệm (https://colinpurrington.com/tips/lab-notebooks) để đưa ra các mẹo sau:

  • Đảm bảo mỗi sổ có tiêu đề mô tả, tên tệp gợi nhớ, và đoạn đầu tiên mô tả ngắn gọn mục tiêu của phân tích.

  • Sử dụng trường date trong phần đầu YAML để ghi lại ngày bạn bắt đầu làm việc trên sổ:

    date: 2016-08-23

    Sử dụng định dạng ISO8601 YYYY-MM-DD để không có sự nhầm lẫn. Sử dụng nó ngay cả khi bạn thường không viết ngày theo cách đó!

  • Nếu bạn dành nhiều thời gian cho một ý tưởng phân tích và hóa ra nó là ngõ cụt, đừng xóa nó! Viết một ghi chú ngắn về lý do nó thất bại và để nó trong sổ. Điều đó sẽ giúp bạn tránh đi vào cùng ngõ cụt khi quay lại phân tích trong tương lai.

  • Nói chung, bạn nên nhập dữ liệu bên ngoài R. Nhưng nếu bạn cần ghi lại một đoạn dữ liệu nhỏ, hãy trình bày rõ ràng bằng tibble::tribble().

  • Nếu bạn phát hiện lỗi trong tệp dữ liệu, đừng bao giờ sửa trực tiếp, mà thay vào đó viết mã để sửa giá trị. Giải thích tại sao bạn thực hiện sửa chữa đó.

  • Trước khi kết thúc ngày làm việc, hãy đảm bảo bạn có thể biên dịch sổ. Nếu bạn đang sử dụng bộ nhớ đệm, hãy đảm bảo xóa bộ nhớ đệm. Điều đó sẽ cho phép bạn sửa bất kỳ vấn đề nào khi mã vẫn còn tươi mới trong tâm trí.

  • Nếu bạn muốn mã của mình có thể tái tạo lâu dài (tức là để bạn có thể quay lại chạy nó vào tháng sau hoặc năm sau), bạn sẽ cần theo dõi phiên bản của các package mà mã sử dụng. Một cách tiếp cận nghiêm ngặt là sử dụng renv, https://rstudio.github.io/renv/index.html, lưu trữ các package trong thư mục dự án. Một cách nhanh và đơn giản là thêm một khối mã chạy sessionInfo() — điều đó sẽ không cho phép bạn dễ dàng tái tạo các package như chúng ở hiện tại, nhưng ít nhất bạn sẽ biết chúng là gì.

  • Bạn sẽ tạo rất nhiều, rất nhiều sổ phân tích trong suốt sự nghiệp. Bạn sẽ tổ chức chúng như thế nào để có thể tìm lại trong tương lai? Chúng tôi khuyên lưu trữ chúng trong các dự án riêng lẻ, và đưa ra một sơ đồ đặt tên tốt.

28.12 Tổng kết

Trong chương này, chúng tôi đã giới thiệu Quarto để soạn thảo và xuất bản tài liệu tính toán tái tạo bao gồm mã nguồn và văn bản của bạn ở cùng một nơi. Bạn đã học về cách viết tài liệu Quarto trong RStudio với trình soạn thảo trực quan hoặc trình soạn thảo mã nguồn, cách khối mã hoạt động và cách tùy chỉnh các tùy chọn cho chúng, cách bao gồm hình ảnh và bảng trong tài liệu Quarto, và các tùy chọn bộ nhớ đệm cho tính toán. Ngoài ra, bạn đã học về cách điều chỉnh các tùy chọn phần đầu YAML để tạo tài liệu độc lập hoặc tài liệu có parameter cũng như bao gồm trích dẫn và thư mục tham khảo. Chúng tôi cũng đã cung cấp một số mẹo khắc phục sự cố và workflow.

Mặc dù phần giới thiệu này đủ để giúp bạn bắt đầu với Quarto, vẫn còn rất nhiều điều để học. Quarto vẫn còn tương đối mới, và vẫn đang phát triển nhanh chóng. Nơi tốt nhất để cập nhật các tính năng mới là trang web chính thức của Quarto: https://quarto.org.

Có hai theme quan trọng mà chúng tôi chưa đề cập ở đây: cộng tác và chi tiết truyền đạt chính xác ý tưởng đến người khác. Cộng tác là một phần quan trọng của khoa học dữ liệu hiện đại, và bạn có thể làm cuộc sống dễ dàng hơn nhiều bằng cách sử dụng các công cụ quản lý phiên bản, như Git và GitHub. Chúng tôi khuyên đọc “Happy Git with R”, một giới thiệu thân thiện về Git và GitHub dành cho người dùng R, bởi Jenny Bryan. Cuốn sách có sẵn miễn phí trực tuyến: https://happygitwithr.com.

Chúng tôi cũng chưa đề cập đến những gì bạn thực sự nên viết để truyền đạt rõ ràng kết quả phân tích. Để cải thiện kỹ năng viết, chúng tôi rất khuyên bạn đọc Style: Lessons in Clarity and Grace của Joseph M. Williams & Joseph Bizup, hoặc The Sense of Structure: Writing from the Reader’s Perspective của George Gopen. Cả hai cuốn sách sẽ giúp bạn hiểu cấu trúc của câu và đoạn văn, và cung cấp cho bạn công cụ để làm cho bài viết rõ ràng hơn. (Những cuốn sách này khá đắt nếu mua mới, nhưng chúng được sử dụng bởi nhiều lớp tiếng Anh nên có rất nhiều bản cũ giá rẻ). George Gopen cũng có một số bài viết ngắn về kỹ năng viết tại https://www.georgegopen.com/litigation-articles.html. Chúng nhắm đến luật sư, nhưng hầu hết mọi thứ đều áp dụng được cho nhà khoa học dữ liệu.