29  Quarto 형식

29.1 소개

지금까지 Quarto를 사용하여 HTML 문서를 생성하는 것을 보았습니다. 이 장에서는 Quarto로 생성할 수 있는 다른 많은 출력 유형 중 일부에 대해 간략하게 살펴봅니다.

문서의 출력을 설정하는 방법은 두 가지가 있습니다:

  1. YAML 헤더를 수정하여 영구적으로 설정:

    title: "Diamond sizes"
format: html

  2. quarto::quarto_render()를 직접 호출하여 일시적으로 설정:

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

    output_format 인수는 값 목록을 받을 수도 있으므로 프로그래밍 방식으로 여러 유형의 출력을 생성하려는 경우 유용합니다.

    quarto::quarto_render("diamond-sizes.qmd", output_format = c("docx", "pdf"))

29.2 출력 옵션

Quarto는 광범위한 출력 형식을 제공합니다. 전체 목록은 https://quarto.org/docs/output-formats/all-formats.html에서 찾을 수 있습니다. 많은 형식이 일부 출력 옵션(예: 목차를 포함하기 위한 toc: true)을 공유하지만, 다른 형식은 형식에 특화된 옵션(예: code-fold: true는 HTML 출력의 경우 코드 청크를 <details> 태그로 축소하여 사용자가 요청할 때만 표시할 수 있게 하지만, PDF나 Word 문서에는 적용되지 않음)을 가집니다.

기본 옵션을 재정의하려면 확장된 format 필드를 사용해야 합니다. 예를 들어 플로팅 목차가 있는 html을 렌더링하려면 다음과 같이 사용합니다:

format:
  html:
    toc: true
    toc_float: true

형식 목록을 제공하여 여러 출력으로 렌더링할 수도 있습니다:

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

기본 옵션을 재정의하고 싶지 않은 경우의 특별한 구문(pdf: default)에 유의하세요.

문서의 YAML에 지정된 모든 형식으로 렌더링하려면 output_format = "all"을 사용할 수 있습니다.

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

29.3 문서

이전 장에서는 기본 html 출력에 집중했습니다. 해당 테마에는 여러 가지 기본 변형이 있어 다양한 유형의 문서를 생성합니다. 예를 들어:

  • pdf는 설치가 필요한 오픈 소스 문서 레이아웃 시스템인 LaTeX를 사용하여 PDF를 만듭니다. 아직 없는 경우 RStudio가 알려줄 것입니다.

  • docx는 Microsoft Word(.docx) 문서용입니다.

  • odt는 OpenDocument Text(.odt) 문서용입니다.

  • rtf는 Rich Text Format(.rtf) 문서용입니다.

  • gfm은 GitHub Flavored Markdown(.md) 문서용입니다.

  • ipynb는 Jupyter Notebooks(.ipynb)용입니다.

의사 결정권자와 공유할 문서를 생성할 때 문서 YAML에서 전역 옵션을 설정하여 코드의 기본 표시를 끌 수 있다는 점을 기억하세요:

execute:
  echo: false

html 문서의 경우 또 다른 옵션은 코드 청크를 기본적으로 숨기지만 클릭하면 보이게 하는 것입니다:

format:
  html:
    code: true

29.4 프레젠테이션

Quarto를 사용하여 프레젠테이션을 생성할 수도 있습니다. Keynote나 PowerPoint와 같은 도구보다 시각적 제어는 덜하지만, R 코드의 결과를 프레젠테이션에 자동으로 삽입하면 엄청난 시간을 절약할 수 있습니다. 프레젠테이션은 콘텐츠를 슬라이드로 나누어 작동하며, 각 두 번째(##) 수준 헤더에서 새 슬라이드가 시작됩니다. 또한 첫 번째(#) 수준 헤더는 기본적으로 중앙에 배치되는 섹션 제목 슬라이드와 함께 새 섹션의 시작을 나타냅니다.

Quarto는 다음을 포함하여 다양한 프레젠테이션 형식을 지원합니다:

  1. revealjs - revealjs를 사용한 HTML 프레젠테이션

  2. pptx - PowerPoint 프레젠테이션

  3. beamer - LaTeX Beamer를 사용한 PDF 프레젠테이션.

Quarto로 프레젠테이션을 만드는 방법에 대한 자세한 내용은 https://quarto.org/docs/presentations에서 읽을 수 있습니다.

29.5 대화형 기능 (Interactivity)

모든 HTML 문서와 마찬가지로 Quarto로 만든 HTML 문서에도 대화형 구성 요소가 포함될 수 있습니다. 여기서는 Quarto 문서에 대화형 기능을 포함하기 위한 두 가지 옵션인 htmlwidgets와 Shiny를 소개합니다.

29.5.1 htmlwidgets

HTML은 대화형 형식이며, 대화형 HTML 시각화를 생성하는 R 함수인 htmlwidgets를 사용하여 그 이점을 활용할 수 있습니다. 예를 들어 아래의 leaflet 지도를 살펴보세요. 웹에서 이 페이지를 보고 있다면 지도를 드래그하거나 확대/축소 등을 할 수 있습니다. 책에서는 그렇게 할 수 없으므로 Quarto가 자동으로 정적 스크린샷을 삽입해 줍니다.

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

htmlwidgets의 장점은 이를 사용하기 위해 HTML이나 JavaScript에 대해 전혀 알 필요가 없다는 것입니다. 모든 세부 사항이 패키지 내부에 래핑되어 있으므로 걱정할 필요가 없습니다.

htmlwidgets를 제공하는 많은 패키지가 있으며 다음을 포함합니다:

  • 대화형 시계열 시각화를 위한 dygraphs.

  • 대화형 표를 위한 DT.

  • 대화형 3D 플롯을 위한 threejs.

  • 다이어그램(예: 순서도 및 간단한 노드-링크 다이어그램)을 위한 DiagrammeR.

htmlwidgets에 대해 더 자세히 알아보고 이를 제공하는 패키지의 전체 목록을 보려면 https://www.htmlwidgets.org를 방문하세요.

29.5.2 Shiny

htmlwidgets는 클라이언트 측(client-side) 대화형 기능을 제공합니다 — 모든 상호 작용은 R과 독립적으로 브라우저에서 발생합니다. 한편으로는 R에 연결하지 않고도 HTML 파일을 배포할 수 있기 때문에 훌륭합니다. 그러나 이는 기본적으로 HTML과 JavaScript로 구현된 것들로만 할 수 있는 일을 제한합니다. 대안적인 접근 방식은 JavaScript가 아니라 R 코드를 사용하여 대화형 기능을 만들 수 있게 해주는 패키지인 shiny를 사용하는 것입니다.

Quarto 문서에서 Shiny 코드를 호출하려면 YAML 헤더에 server: shiny를 추가하세요:

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

그런 다음 “input” 함수를 사용하여 문서에 대화형 구성 요소를 추가할 수 있습니다:

library(shiny)

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

두 개의 입력 상자가 서로 위에 있습니다. 위쪽은 "What is your name?", 아래쪽은 "How old are you?"라고 되어 있습니다.

또한 Shiny 서버에서 실행해야 하는 코드가 포함된 청크 옵션 context: server가 있는 코드 청크도 필요합니다.

그런 다음 input$name 및 input$age로 값을 참조할 수 있으며, 이들을 사용하는 코드는 값이 변경될 때마다 자동으로 다시 실행됩니다.

Shiny 상호 작용은 서버 측(server-side) 에서 발생하기 때문에 여기에서 라이브 Shiny 앱을 보여드릴 수 없습니다. 즉, JavaScript를 모르고도 대화형 앱을 작성할 수 있지만, 이를 실행할 서버가 필요합니다. 이로 인해 물류적인 문제가 발생합니다: Shiny 앱을 온라인에서 실행하려면 Shiny 서버가 필요합니다. 자신의 컴퓨터에서 Shiny 앱을 실행할 때 Shiny는 자동으로 Shiny 서버를 설정해 주지만, 이러한 종류의 대화형 기능을 온라인에 게시하려면 공용 Shiny 서버가 필요합니다. 이것이 Shiny의 근본적인 트레이드오프입니다: R에서 할 수 있는 모든 것을 Shiny 문서에서 할 수 있지만, 누군가 R을 실행하고 있어야 합니다.

Shiny에 대해 더 배우고 싶다면 Hadley Wickham이 쓴 Mastering Shiny(https://mastering-shiny.org)를 읽어보시기를 권장합니다.

29.6 웹사이트와 책

약간의 추가 인프라를 사용하면 Quarto를 사용하여 완전한 웹사이트나 책을 생성할 수 있습니다:

  • .qmd 파일을 단일 디렉토리에 넣습니다. index.qmd가 홈 페이지가 됩니다.

  • 사이트 탐색을 제공하는 _quarto.yml이라는 이름의 YAML 파일을 추가합니다. 이 파일에서 project 유형을 book 또는 website로 설정합니다. 예:

    project:
  type: book

예를 들어 다음 _quarto.yml 파일은 세 개의 소스 파일인 index.qmd(홈 페이지), viridis-colors.qmd, 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

책에 필요한 _quarto.yml 파일도 매우 비슷하게 구성됩니다. 다음 예제는 세 가지 다른 출력(html, pdf, epub)으로 렌더링되는 4개의 장으로 구성된 책을 만드는 방법을 보여줍니다. 다시 한번 말씀드리지만 소스 파일은 .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

웹사이트와 책에는 RStudio 프로젝트를 사용하는 것이 좋습니다. _quarto.yml 파일을 기반으로 RStudio는 작업 중인 프로젝트 유형을 인식하고, 웹사이트와 책을 렌더링하고 미리 보는 데 사용할 수 있는 Build 탭을 IDE에 추가합니다. 웹사이트와 책 모두 quarto::quarto_render()를 사용하여 렌더링할 수도 있습니다.

Quarto 웹사이트에 대해서는 https://quarto.org/docs/websites, 책에 대해서는 https://quarto.org/docs/books에서 자세히 읽어보세요.

29.7 기타 형식

Quarto는 더 많은 출력 형식을 제공합니다:

더 많은 형식 목록은 https://quarto.org/docs/output-formats/all-formats.html을 참조하세요.

29.8 요약

이 장에서는 정적 및 대화형 문서에서 프레젠테이션, 웹사이트 및 책에 이르기까지 Quarto로 결과를 전달하기 위한 다양한 옵션을 제시했습니다.

이러한 다양한 형식으로 효과적인 소통을 하는 방법에 대해 더 자세히 배우려면 다음 리소스를 추천합니다:

  • 프레젠테이션 기술을 향상시키려면 Neal Ford, Matthew McCollough, Nathaniel Schutta가 쓴 Presentation Patterns를 시도해 보세요. 프레젠테이션을 개선하기 위해 적용할 수 있는 효과적인 패턴(낮은 수준과 높은 수준 모두) 세트를 제공합니다.

  • 학술 발표를 한다면 Leek group guide to giving talks가 마음에 드실 것입니다.

  • 우리는 직접 들어보지는 못했지만, Matt McGarrity의 대중 연설 온라인 강의에 대해 좋은 이야기를 들었습니다: https://www.coursera.org/learn/public-speaking.

  • 대시보드를 많이 만들고 있다면 Stephen Few의 Information Dashboard Design: The Effective Visual Communication of Data를 꼭 읽어보세요. 단지 예쁘기만 한 것이 아니라 정말로 유용한 대시보드를 만드는 데 도움이 될 것입니다.

  • 아이디어를 효과적으로 전달하는 것은 종종 그래픽 디자인에 대한 약간의 지식으로부터 이득을 얻습니다. Robin Williams의 The Non-Designer’s Design Book은 시작하기에 훌륭한 장소입니다.