29 Các định dạng Quarto

29.1 Giới thiệu

Cho đến nay, bạn đã thấy Quarto được sử dụng để tạo tài liệu HTML. Chương này sẽ giới thiệu tổng quan ngắn gọn về một số trong nhiều loại đầu ra (output) khác mà bạn có thể tạo với Quarto.

Có hai cách để thiết lập định dạng đầu ra của một tài liệu:

Cố định, bằng cách chỉnh sửa phần YAML header:
```
title: "Diamond sizes"
format: html
```
Tạm thời, bằng cách gọi quarto::quarto_render() thủ công:
```
quarto::quarto_render("diamond-sizes.qmd", output_format = "docx")
```
Cách này hữu ích khi bạn muốn tạo nhiều loại đầu ra theo chương trình vì argument output_format cũng có thể nhận một list các giá trị.
```
quarto::quarto_render("diamond-sizes.qmd", output_format = c("docx", "pdf"))
```

29.2 Tùy chọn đầu ra

Quarto cung cấp nhiều định dạng đầu ra khác nhau. Bạn có thể tìm list đầy đủ tại https://quarto.org/docs/output-formats/all-formats.html. Nhiều định dạng chia sẻ một số tùy chọn đầu ra chung (ví dụ: toc: true để thêm mục lục), nhưng một số tùy chọn khác chỉ dành riêng cho từng định dạng (ví dụ: code-fold: true thu gọn các khối mã (code chunk) vào thẻ <details> cho đầu ra HTML để người dùng có thể hiển thị khi cần, tùy chọn này không áp dụng được cho tài liệu PDF hay Word).

Để ghi đè các tùy chọn mặc định, bạn cần sử dụng trường format mở rộng. Ví dụ, nếu bạn muốn biên dịch (render) một tài liệu html với mục lục nổi, bạn sẽ dùng:

format:
  html:
    toc: true
    toc_float: true

Bạn thậm chí có thể biên dịch sang nhiều định dạng đầu ra bằng cách cung cấp một list các định dạng:

format:
  html:
    toc: true
    toc_float: true
  pdf: default
  docx: default

Lưu ý cú pháp đặc biệt (pdf: default) nếu bạn không muốn ghi đè bất kỳ tùy chọn mặc định nào.

Để biên dịch tất cả các định dạng được chỉ định trong YAML của một tài liệu, bạn có thể sử dụng output_format = "all".

quarto::quarto_render("diamond-sizes.qmd", output_format = "all")

29.3 Tài liệu

Chương trước tập trung vào định dạng đầu ra html mặc định. Có một số biến thể cơ bản từ đó, tạo ra các loại tài liệu khác nhau. Ví dụ:

pdf tạo tệp PDF bằng LaTeX (một hệ thống trình bày tài liệu mã nguồn mở), mà bạn sẽ cần cài đặt. RStudio sẽ nhắc bạn nếu bạn chưa cài đặt nó.
docx cho tài liệu Microsoft Word (.docx).
odt cho tài liệu OpenDocument Text (.odt).
rtf cho tài liệu Rich Text Format (.rtf).
gfm cho tài liệu GitHub Flavored Markdown (.md).
ipynb cho Jupyter Notebooks (.ipynb).

Hãy nhớ rằng, khi tạo tài liệu để chia sẻ với người ra quyết định, bạn có thể tắt hiển thị mã mặc định bằng cách thiết lập tùy chọn toàn cục trong YAML của tài liệu:

execute:
  echo: false

Với tài liệu html, một tùy chọn khác là ẩn các khối mã theo mặc định, nhưng cho phép hiển thị khi nhấp chuột:

format:
  html:
    code: true

29.4 Bài trình bày

Bạn cũng có thể sử dụng Quarto để tạo bài trình bày (presentation). Bạn có ít quyền kiểm soát trực quan hơn so với công cụ như Keynote hay PowerPoint, nhưng việc tự động chèn kết quả từ mã R vào bài trình bày có thể tiết kiệm rất nhiều thời gian. Bài trình bày hoạt động bằng cách chia nội dung thành các slide, với một slide mới bắt đầu tại mỗi tiêu đề cấp hai (##). Ngoài ra, tiêu đề cấp một (#) đánh dấu phần đầu của một phần mới với slide tiêu đề phần, mặc định được căn giữa.

Quarto hỗ trợ nhiều định dạng bài trình bày, bao gồm:

revealjs - Bài trình bày HTML với revealjs
pptx - Bài trình bày PowerPoint
beamer - Bài trình bày PDF với LaTeX Beamer.

Bạn có thể đọc thêm về cách tạo bài trình bày với Quarto tại https://quarto.org/docs/presentations.

29.5 Tính tương tác

Giống như bất kỳ tài liệu HTML nào, tài liệu HTML được tạo bằng Quarto cũng có thể chứa các thành phần tương tác. Ở đây chúng tôi giới thiệu hai tùy chọn để thêm tính tương tác (interactivity) vào tài liệu Quarto của bạn: htmlwidgets và Shiny.

29.5.1 htmlwidgets

HTML là một định dạng tương tác, và bạn có thể tận dụng tính tương tác đó với htmlwidgets, các function R tạo ra các visualization HTML tương tác. Ví dụ, hãy xem bản đồ leaflet bên dưới. Nếu bạn đang xem trang này trên web, bạn có thể kéo bản đồ, phóng to thu nhỏ, v.v. Rõ ràng bạn không thể làm điều đó trong sách, vì vậy Quarto tự động chèn ảnh chụp tĩnh cho bạn.

library(leaflet)
leaflet() |>
  setView(174.764, -36.877, zoom = 16) |>
  addTiles() |>
  addMarkers(174.764, -36.877, popup = "Maungawhau")

Điều tuyệt vời của htmlwidgets là bạn không cần biết gì về HTML hay JavaScript để sử dụng chúng. Tất cả chi tiết được đóng gói bên trong package, nên bạn không cần phải lo lắng về điều đó.

Có nhiều package cung cấp htmlwidgets, bao gồm:

dygraphs cho visualization string thời gian tương tác.
DT cho bảng tương tác.
threejs cho biểu đồ 3d tương tác.
DiagrammeR cho sơ đồ (như lưu đồ và sơ đồ nút-liên kết đơn giản).

Để tìm hiểu thêm về htmlwidgets và xem list đầy đủ các package cung cấp chúng, hãy truy cập https://www.htmlwidgets.org.

29.5.2 Shiny

htmlwidgets cung cấp tính tương tác phía máy khách (client-side) — toàn bộ tương tác diễn ra trong trình duyệt, độc lập với R. Một mặt, điều đó rất tuyệt vì bạn có thể phân phối tệp HTML mà không cần kết nối với R. Tuy nhiên, điều đó về cơ bản giới hạn những gì bạn có thể làm trong phạm vi những thứ đã được triển khai bằng HTML và JavaScript. Một cách tiếp cận thay thế là sử dụng shiny, một package cho phép bạn tạo tính tương tác bằng mã R, không phải JavaScript.

Để gọi mã Shiny từ một tài liệu Quarto, hãy thêm server: shiny vào YAML header:

title: "Shiny Web App"
format: html
server: shiny

Sau đó bạn có thể sử dụng các function “input” để thêm các thành phần tương tác vào tài liệu:

library(shiny)

textInput("name", "What is your name?")
numericInput("age", "How old are you?", NA, min = 0, max = 150)

Two input boxes on top of each other. Top one says, "What is your name?", the bottom, "How old are you?".

Và bạn cũng cần một khối mã với tùy chọn khối context: server chứa mã cần chạy trong máy chủ Shiny.

Sau đó bạn có thể tham chiếu đến các giá trị bằng input$name và input$age, và mã sử dụng chúng sẽ tự động được chạy lại mỗi khi chúng thay đổi.

Chúng tôi không thể hiển thị một ứng dụng shiny trực tiếp ở đây vì các tương tác shiny diễn ra phía máy chủ (server-side). Điều này có nghĩa là bạn có thể viết ứng dụng tương tác mà không cần biết JavaScript, nhưng bạn cần một máy chủ để chạy chúng. Điều này dẫn đến một vấn đề hậu cần: ứng dụng Shiny cần một máy chủ Shiny để chạy trực tuyến. Khi bạn chạy ứng dụng Shiny trên máy tính của mình, Shiny tự động thiết lập một máy chủ Shiny cho bạn, nhưng bạn cần một máy chủ Shiny công khai nếu muốn xuất bản loại tương tác này trực tuyến. Đó là sự đánh đổi cơ bản của shiny: bạn có thể làm bất cứ điều gì trong một tài liệu shiny mà bạn có thể làm trong R, nhưng nó yêu cầu ai đó phải chạy R.

Để tìm hiểu thêm về Shiny, chúng tôi khuyên bạn đọc Mastering Shiny của Hadley Wickham, https://mastering-shiny.org.

29.6 Website và sách

Với một chút cơ sở hạ tầng bổ sung, bạn có thể sử dụng Quarto để tạo một website hoàn chỉnh hoặc một cuốn sách:

Đặt các tệp .qmd của bạn trong một thư mục duy nhất. index.qmd sẽ trở thành trang chủ.
Thêm một tệp YAML có tên _quarto.yml cung cấp điều hướng cho trang web. Trong tệp này, thiết lập loại project là book hoặc website, ví dụ:
```
project:
  type: book
```

Ví dụ, tệp _quarto.yml sau đây tạo một website từ ba tệp nguồn: index.qmd (trang chủ), viridis-colors.qmd, và terrain-colors.qmd.

project:
  type: website

website:
  title: "A website on color scales"
  navbar:
    left:
      - href: index.qmd
        text: Home
      - href: viridis-colors.qmd
        text: Viridis colors
      - href: terrain-colors.qmd
        text: Terrain colors

Tệp _quarto.yml cần cho một cuốn sách có cấu trúc rất tương tự. Ví dụ sau cho thấy cách bạn có thể tạo một cuốn sách với bốn chương biên dịch sang ba định dạng đầu ra khác nhau (html, pdf, và epub). Một lần nữa, các tệp nguồn là các tệp .qmd.

project:
  type: book

book:
  title: "A book on color scales"
  author: "Jane Coloriste"
  chapters:
    - index.qmd
    - intro.qmd
    - viridis-colors.qmd
    - terrain-colors.qmd

format:
  html:
    theme: cosmo
  pdf: default
  epub: default

Chúng tôi khuyên bạn nên sử dụng một dự án RStudio (RStudio project) cho website và sách của bạn. Dựa trên tệp _quarto.yml, RStudio sẽ nhận diện loại dự án bạn đang làm việc, và thêm tab Build vào IDE để bạn có thể biên dịch và xem trước website và sách của mình. Cả website và sách cũng có thể được biên dịch bằng quarto::quarto_render().

Đọc thêm tại https://quarto.org/docs/websites về website Quarto và https://quarto.org/docs/books về sách.

29.7 Các định dạng khác

Quarto còn cung cấp thêm nhiều định dạng đầu ra nữa:

Bạn có thể viết bài báo khoa học sử dụng Quarto Journal Templates: https://quarto.org/docs/journals/templates.html.
Bạn có thể xuất tài liệu Quarto sang Jupyter Notebooks với format: ipynb: https://quarto.org/docs/reference/formats/ipynb.html.

Xem https://quarto.org/docs/output-formats/all-formats.html để biết list thêm nhiều định dạng khác.

29.8 Tóm tắt

Trong chương này chúng tôi đã giới thiệu cho bạn nhiều tùy chọn khác nhau để truyền đạt kết quả của bạn với Quarto, từ tài liệu tĩnh và tương tác đến bài trình bày đến website và sách.

Để tìm hiểu thêm về cách truyền đạt hiệu quả trong các định dạng khác nhau này, chúng tôi khuyên bạn tham khảo các tài nguyên sau:

Để cải thiện kỹ năng trình bày, hãy thử Presentation Patterns của Neal Ford, Matthew McCollough, và Nathaniel Schutta. Cuốn sách cung cấp một tập hợp các mẫu hiệu quả (cả cấp thấp và cấp cao) mà bạn có thể áp dụng để cải thiện bài trình bày của mình.
Nếu bạn thuyết trình học thuật, bạn có thể thích Leek group guide to giving talks.
Chúng tôi chưa tự mình tham gia, nhưng đã nghe nhiều điều tốt về khóa học trực tuyến về diễn thuyết trước công chúng của Matt McGarrity: https://www.coursera.org/learn/public-speaking.
Nếu bạn tạo nhiều console (dashboard), hãy chắc chắn đọc Information Dashboard Design: The Effective Visual Communication of Data của Stephen Few. Cuốn sách sẽ giúp bạn tạo các console thực sự hữu ích, không chỉ đẹp mắt.
Truyền đạt ý tưởng hiệu quả thường được hỗ trợ bởi một số kiến thức về thiết kế đồ họa. The Non-Designer’s Design Book của Robin Williams là một nơi tuyệt vời để bắt đầu.