28  Quarto

28.1 소개

Quarto는 코드, 결과, 산문을 결합하여 데이터 과학을 위한 통합 저작 프레임워크를 제공합니다. Quarto 문서는 완전히 재현 가능하며 PDF, Word 파일, 프레젠테이션 등과 같은 수십 가지 출력 형식을 지원합니다.

Quarto 파일은 세 가지 방식으로 사용하도록 설계되었습니다:

  1. 분석 배후의 코드가 아니라 결론에 집중하고 싶은 의사 결정권자에게 소통하기 위해.

  2. 결론뿐만 아니라 결론에 도달한 방법(즉, 코드)에도 관심이 있는 다른 데이터 과학자(미래의 자신 포함!)와 협업하기 위해.

  3. 수행한 작업뿐만 아니라 생각했던 내용도 캡처할 수 있는 현대적인 실험실 노트로서 데이터 과학을 수행하는 환경으로.

Quarto는 R 패키지가 아니라 명령줄 인터페이스 도구입니다. 즉, ?를 통해 도움말을 거의 이용할 수 없다는 의미입니다. 대신 이 장을 진행하면서, 그리고 나중에 Quarto를 사용할 때 Quarto 문서를 참조해야 합니다.

R Markdown 사용자라면 “Quarto는 R Markdown과 매우 비슷하게 들리는데”라고 생각할 수 있습니다. 틀리지 않습니다! Quarto는 R Markdown 생태계(rmarkdown, bookdown, distill, xaringan 등)의 많은 패키지 기능을 하나의 일관된 시스템으로 통합할 뿐만 아니라 R 외에도 Python 및 Julia와 같은 여러 프로그래밍 언어에 대한 기본 지원으로 확장합니다. 어떤 의미에서 Quarto는 10년 동안 R Markdown 생태계를 확장하고 지원하면서 배운 모든 것을 반영합니다.

28.1.1 선수 지식

Quarto 명령줄 인터페이스(Quarto CLI)가 필요하지만, 명시적으로 설치하거나 로드할 필요는 없습니다. RStudio가 필요할 때 자동으로 두 가지를 모두 수행하기 때문입니다.

28.2 Quarto 기초

이것은 Quarto 파일입니다 – 확장자가 .qmd인 일반 텍스트 파일입니다:

---
title: "다이아몬드 크기"
date: 2022-09-12
format: html
---

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

library(tidyverse)

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

우리는 `r nrow(diamonds)`개의 다이아몬드 데이터를 가지고 있습니다.
그중 `r nrow(diamonds) - nrow(smaller)`개만이 2.5캐럿보다 큽니다.
나머지의 분포는 아래와 같습니다:

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

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

여기에는 세 가지 중요한 유형의 콘텐츠가 포함되어 있습니다:

  1. ---로 둘러싸인 (선택적) YAML 헤더.
  2. ```로 둘러싸인 R 코드 청크.
  3. # heading 및 _italics_와 같은 간단한 텍스트 서식이 섞인 텍스트.

Figure 28.1 은 코드와 출력이 인터리브된 노트북 인터페이스가 있는 RStudio의 .qmd 문서를 보여줍니다. Run 아이콘(청크 상단의 재생 버튼처럼 생김)을 클릭하거나 Cmd/Ctrl + Shift + Enter를 눌러 각 코드 청크를 실행할 수 있습니다. RStudio는 코드를 실행하고 결과를 코드와 함께 인라인으로 표시합니다.

왼쪽에는 "diamond-sizes.qmd"라는 제목의 Quarto 문서가 있고 오른쪽에는 빈 뷰어 창이 있는 RStudio 창. Quarto 문서에는 무게가 2.5캐럿 미만인 다이아몬드의 빈도 플롯을 생성하는 코드 청크가 있습니다. 플롯은 무게가 증가함에 따라 빈도가 감소함을 보여줍니다.
Figure 28.1: RStudio의 Quarto 문서. 코드와 출력이 문서에 인터리브되어 있으며, 플롯 출력이 코드 바로 아래에 나타납니다.

문서에서 플롯과 출력을 보는 것이 마음에 들지 않고 RStudio의 콘솔 및 플롯 창을 사용하는 것을 선호한다면 “Render” 옆의 기어 아이콘을 클릭하고 Figure 28.2 에 표시된 대로 “Chunk Output in Console”로 전환할 수 있습니다.

왼쪽에는 "diamond-sizes.qmd"라는 제목의 Quarto 문서가 있고 오른쪽 하단에는 플롯 창이 있는 RStudio 창. Quarto 문서에는 무게가 2.5캐럿 미만인 다이아몬드의 빈도 플롯을 생성하는 코드 청크가 있습니다. 플롯은 플롯 창에 표시되며 무게가 증가함에 따라 빈도가 감소함을 보여줍니다. Chunk Output in Console을 표시하는 RStudio 옵션도 강조 표시되어 있습니다.
Figure 28.2: 플롯 창에 플롯 출력이 있는 RStudio의 Quarto 문서.

모든 텍스트, 코드 및 결과가 포함된 전체 보고서를 생성하려면 “Render”를 클릭하거나 Cmd/Ctrl + Shift + K를 누르세요. quarto::quarto_render("diamond-sizes.qmd")를 사용하여 프로그래밍 방식으로 수행할 수도 있습니다. 그러면 Figure 28.3 에 표시된 대로 뷰어 창에 보고서가 표시되고 HTML 파일이 생성됩니다.

왼쪽에는 "diamond-sizes.qmd"라는 제목의 Quarto 문서가 있고 오른쪽 하단에는 플롯 창이 있는 RStudio 창. 렌더링된 문서는 코드를 보여주지 않지만 소스 문서에서는 코드를 볼 수 있습니다.
Figure 28.3: 뷰어 창에 렌더링된 문서가 있는 RStudio의 Quarto 문서.

문서를 렌더링할 때 Quarto는 .qmd 파일을 knitr(https://yihui.org/knitr/)로 보내고, knitr는 모든 코드 청크를 실행하고 코드와 그 출력을 포함하는 새 마크다운(.md) 문서를 만듭니다. knitr에 의해 생성된 마크다운 파일은 pandoc(https://pandoc.org)에 의해 처리되어 완성된 파일을 만드는 역할을 합니다. 이 프로세스는 Figure 28.4 에 나와 있습니다. 이 2단계 워크플로우의 장점은 Chapter 29 에서 배우게 될 것처럼 매우 광범위한 출력 형식을 만들 수 있다는 것입니다.

qmd 파일로 시작하여 knitr, md, pandoc, 그리고 PDF, MS Word 또는 HTML로 이어지는 워크플로우 다이어그램.
Figure 28.4: qmd에서 knitr, md, pandoc, 그리고 PDF, MS Word 또는 HTML 형식의 출력으로 이어지는 Quarto 워크플로우 다이어그램.

자신만의 .qmd 파일로 시작하려면 메뉴 모음에서 File > New File > Quarto Document…를 선택하세요. RStudio는 Quarto의 주요 기능이 작동하는 방식을 상기시켜주는 유용한 콘텐츠로 파일을 미리 채우는 데 사용할 수 있는 마법사를 시작합니다.

다음 섹션에서는 Quarto 문서의 세 가지 구성 요소인 마크다운 텍스트, 코드 청크, YAML 헤더에 대해 자세히 설명합니다.

28.2.1 연습문제

  1. File > New File > Quarto Document를 사용하여 새 Quarto 문서를 만드세요. 지침을 읽으세요. 청크를 개별적으로 실행하는 연습을 하세요. 그런 다음 적절한 버튼을 클릭하고 적절한 키보드 단축키를 사용하여 문서를 렌더링하세요. 코드를 수정하고 다시 실행하여 수정된 출력을 볼 수 있는지 확인하세요.

  2. 세 가지 내장 형식인 HTML, PDF, Word 각각에 대해 하나의 새 Quarto 문서를 만드세요. 세 문서를 각각 렌더링하세요. 출력은 어떻게 다릅니까? 입력은 어떻게 다릅니까? (PDF 출력을 빌드하려면 LaTeX를 설치해야 할 수 있습니다. 필요한 경우 RStudio가 알려줄 것입니다.)

28.3 비주얼 에디터

RStudio의 비주얼 에디터는 Quarto 문서를 작성하기 위한 WYSIWYM 인터페이스를 제공합니다. 내부적으로 Quarto 문서(.qmd 파일)의 산문은 일반 텍스트 파일 서식을 지정하기 위한 가벼운 규칙 집합인 Markdown으로 작성됩니다. 실제로 Quarto는 테이블, 인용, 상호 참조, 각주, div/span, 정의 목록, 속성, 원시 HTML/TeX 등을 포함한 Pandoc 마크다운(Quarto가 이해하는 약간 확장된 버전의 Markdown)을 사용하며 코드 셀 실행 및 출력 인라인 보기를 지원합니다. Markdown은 읽고 쓰기 쉽도록 설계되었지만 Section 28.4 에서 볼 수 있듯이 여전히 새로운 구문을 배워야 합니다. 따라서 .qmd 파일과 같은 계산 문서가 처음이지만 Google Docs나 MS Word와 같은 도구를 사용한 경험이 있는 경우 RStudio에서 Quarto를 시작하는 가장 쉬운 방법은 비주얼 에디터입니다.

비주얼 에디터에서는 메뉴 모음의 버튼을 사용하여 이미지, 표, 상호 참조 등을 삽입하거나 포괄적인 ⌘ + / 또는 Ctrl + / 단축키를 사용하여 거의 모든 것을 삽입할 수 있습니다. 줄의 시작 부분에 있는 경우(Figure 28.5 에 표시된 대로) /만 입력하여 단축키를 호출할 수도 있습니다.

텍스트 서식(기울임꼴, 굵게, 밑줄, 작은 대문자, 코드, 위첨자 및 아래첨자), 1~3단계 제목, 글머리 기호 및 번호 매기기 목록, 링크, 연결된 문구, 이미지(이미지 크기 사용자 정의, 캡션 및 대체 텍스트 추가 등을 위한 팝업 창 포함), 헤더 행이 있는 표, R 코드 청크, Python 코드 청크, div, 글머리 기호 목록, 번호 매기기 목록 또는 1단계 제목(도구의 상위 몇 가지 선택 사항)을 삽입하는 옵션이 있는 모든 항목 삽입 도구와 같은 비주얼 에디터의 다양한 기능을 보여주는 Quarto 문서.
Figure 28.5: Quarto 비주얼 에디터.

이미지 삽입 및 표시 방식 사용자 정의도 비주얼 에디터로 용이하게 수행할 수 있습니다. 클립보드의 이미지를 비주얼 에디터에 직접 붙여넣거나(그러면 RStudio가 프로젝트 디렉토리에 해당 이미지의 사본을 배치하고 링크함) 비주얼 에디터의 Insert > Figure / Image 메뉴를 사용하여 삽입할 이미지를 찾아보거나 URL을 붙여넣을 수 있습니다. 또한 동일한 메뉴를 사용하여 이미지 크기를 조정하고 캡션, 대체 텍스트 및 링크를 추가할 수 있습니다.

비주얼 에디터에는 여기에 나열하지 않은 더 많은 기능이 있으며, 작성 경험을 쌓으면서 유용하게 사용할 수 있습니다.

가장 중요한 점은 비주얼 에디터가 콘텐츠를 서식과 함께 표시하지만 내부적으로는 콘텐츠를 일반 Markdown으로 저장하며 비주얼 에디터와 소스 에디터 사이를 전환하며 두 도구 중 하나를 사용하여 콘텐츠를 보고 편집할 수 있다는 것입니다.

28.3.1 연습문제

  1. 비주얼 에디터를 사용하여 Figure 28.5 의 문서를 다시 만드세요.
  2. 비주얼 에디터를 사용하여 Insert 메뉴와 무엇이든 삽입 도구를 사용하여 코드 청크를 삽입하세요.
  3. 비주얼 에디터를 사용하여 다음 방법을 알아내세요:
    1. 각주 추가.
    2. 수평선 추가.
    3. 인용구 블록 추가.
  4. 비주얼 에디터에서 Insert > Citation으로 이동하여 Welcome to the Tidyverse 논문에 대한 인용을 DOI(디지털 객체 식별자) 10.21105/joss.01686을 사용하여 삽입하세요. 문서를 렌더링하고 참조가 문서에 어떻게 나타나는지 관찰하세요. 문서의 YAML에서 어떤 변화를 관찰할 수 있습니까?

28.4 소스 에디터

비주얼 에디터의 도움 없이 RStudio의 소스 에디터를 사용하여 Quarto 문서를 편집할 수도 있습니다. 비주얼 에디터가 Google docs와 같은 도구로 작성한 경험이 있는 사람들에게 친숙하게 느껴진다면, 소스 에디터는 R 스크립트나 R Markdown 문서를 작성한 경험이 있는 사람들에게 친숙하게 느껴질 것입니다. 소스 에디터는 일반 텍스트에서 이러한 오류를 잡는 것이 더 쉬운 경우가 많으므로 Quarto 구문 오류를 디버깅하는 데 유용할 수 있습니다.

아래 가이드는 소스 에디터에서 Quarto 문서를 작성하기 위해 Pandoc의 Markdown을 사용하는 방법을 보여줍니다.

## 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  |

이것들을 배우는 가장 좋은 방법은 단순히 시도해 보는 것입니다. 며칠이 걸리겠지만 곧 제2의 천성이 되어 생각할 필요가 없게 될 것입니다. 잊어버린 경우 Help > Markdown Quick Reference를 통해 편리한 참조 시트를 얻을 수 있습니다.

28.4.1 연습문제

  1. 간단한 이력서를 만들어 배운 내용을 연습하세요. 제목은 이름이어야 하며, (적어도) 교육 또는 고용에 대한 제목을 포함해야 합니다. 각 섹션에는 직업/학위의 글머리 기호 목록이 포함되어야 합니다. 연도를 굵게 강조하세요.

  2. 소스 에디터와 Markdown 빠른 참조를 사용하여 다음 방법을 알아내세요:

    1. 각주 추가.
    2. 수평선 추가.
    3. 인용구 블록 추가.

  3. https://github.com/hadley/r4ds/tree/main/quarto에서 diamond-sizes.qmd의 내용을 로컬 R Quarto 문서에 복사하여 붙여넣으세요. 실행할 수 있는지 확인한 다음, 가장 눈에 띄는 특징을 설명하는 텍스트를 빈도 다각형 뒤에 추가하세요.

  4. Google doc이나 MS Word에서 문서를 만들거나(또는 이전에 만든 문서를 찾아서) 제목, 하이퍼링크, 서식이 있는 텍스트 등과 같은 콘텐츠를 넣으세요. 이 문서의 내용을 복사하여 비주얼 에디터의 Quarto 문서에 붙여넣으세요. 그런 다음 소스 에디터로 전환하여 소스 코드를 검사하세요.

28.5 코드 청크

Quarto 문서 내에서 코드를 실행하려면 청크를 삽입해야 합니다. 세 가지 방법이 있습니다:

  1. 키보드 단축키 Cmd + Option + I / Ctrl + Alt + I.

  2. 에디터 도구 모음의 “Insert” 버튼 아이콘.

  3. 청크 구분 기호 ```{r} 및 ```를 수동으로 입력.

키보드 단축키를 배우는 것을 추천합니다. 장기적으로 많은 시간을 절약해 줄 것입니다!

이제 알게 되어 좋아하게 되었기를 바라는 키보드 단축키 Cmd/Ctrl + Enter를 사용하여 코드를 계속 실행할 수 있습니다. 그러나 청크에는 새로운 키보드 단축키가 있습니다: Cmd/Ctrl + Shift + Enter는 청크의 모든 코드를 실행합니다. 청크를 함수처럼 생각하세요. 청크는 비교적 독립적이어야 하며 단일 작업에 집중해야 합니다.

다음 섹션에서는 ```{r}로 구성되고 뒤에 선택적 청크 레이블과 #|로 표시된 각 줄에 있는 다양한 기타 청크 옵션이 오는 청크 헤더에 대해 설명합니다.

28.5.1 청크 레이블

청크에는 선택적 레이블을 지정할 수 있습니다. 예:

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

이것은 세 가지 장점이 있습니다:

  1. 스크립트 에디터 왼쪽 하단의 드롭다운 코드 탐색기를 사용하여 특정 청크로 더 쉽게 이동할 수 있습니다:

    세 개의 청크를 보여주는 드롭다운 코드 탐색기만 보여주는 RStudio IDE의 일부분. 청크 1은 setup입니다. 청크 2는 cars이며 Quarto라는 섹션에 있습니다. 청크 3은 pressure이며 Including plots라는 섹션에 있습니다.

  2. 청크에 의해 생성된 그래픽은 다른 곳에서 사용하기 더 쉬운 유용한 이름을 갖게 됩니다. 이에 대해서는 Section 28.6 에서 자세히 설명합니다.

  3. 캐시된 청크의 네트워크를 설정하여 실행할 때마다 비용이 많이 드는 계산을 다시 수행하지 않도록 할 수 있습니다. 이에 대해서는 Section 28.8 에서 자세히 설명합니다.

청크 레이블은 짧지만 기억에 남아야 하며 공백을 포함해서는 안 됩니다. 단어를 구분할 때는 밑줄(_) 대신 대시(-)를 사용하고 청크 레이블에 다른 특수 문자를 사용하지 않는 것이 좋습니다.

일반적으로 원하는 대로 청크에 레이블을 지정할 수 있지만 특별한 동작을 부여하는 청크 이름이 하나 있습니다: setup. 노트북 모드에 있을 때 setup이라는 이름의 청크는 다른 코드가 실행되기 전에 한 번 자동으로 실행됩니다.

또한 청크 레이블은 중복될 수 없습니다. 각 청크 레이블은 고유해야 합니다.

28.5.2 청크 옵션

청크 출력은 청크 헤더에 제공되는 필드인 옵션으로 사용자 정의할 수 있습니다. Knitr는 코드 청크를 사용자 정의하는 데 사용할 수 있는 거의 60개의 옵션을 제공합니다. 여기서는 자주 사용하는 가장 중요한 청크 옵션을 다룰 것입니다. 전체 목록은 https://yihui.org/knitr/options에서 볼 수 있습니다.

가장 중요한 옵션 세트는 코드 블록이 실행되는지 여부와 완성된 보고서에 삽입되는 결과를 제어합니다:

  • eval: false는 코드가 평가되는 것을 방지합니다. (그리고 분명히 코드가 실행되지 않으면 결과가 생성되지 않습니다). 이것은 예제 코드를 표시하거나 각 줄을 주석 처리하지 않고 큰 코드 블록을 비활성화하는 데 유용합니다.

  • include: false는 코드를 실행하지만 최종 문서에 코드나 결과를 표시하지 않습니다. 보고서를 어지럽히고 싶지 않은 설정 코드에 이것을 사용하세요.

  • echo: false는 코드가 완성된 파일에 나타나지 않도록 방지하지만 결과는 나타납니다. 기본 R 코드를 보고 싶어하지 않는 사람들을 대상으로 보고서를 작성할 때 이것을 사용하세요.

  • message: false 또는 warning: false는 메시지나 경고가 완성된 파일에 나타나지 않도록 방지합니다.

  • results: hide는 인쇄된 출력을 숨깁니다; fig-show: hide는 플롯을 숨깁니다.

  • error: true는 코드가 오류를 반환하더라도 렌더링을 계속하도록 합니다. 이것은 보고서의 최종 버전에 포함하고 싶은 경우는 거의 없지만, .qmd 내부에서 정확히 무슨 일이 일어나고 있는지 디버깅해야 하는 경우 매우 유용할 수 있습니다. R을 가르치고 의도적으로 오류를 포함하려는 경우에도 유용합니다. 기본값인 error: false는 문서에 오류가 하나라도 있으면 렌더링이 실패하도록 합니다.

이러한 각 청크 옵션은 #| 뒤에 청크 헤더에 추가됩니다. 예를 들어, 다음 청크에서는 eval이 false로 설정되어 있으므로 결과가 인쇄되지 않습니다.

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

다음 표는 각 옵션이 억제하는 출력 유형을 요약합니다:

Option Run code Show code Output Plots Messages Warnings
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 전역 옵션

knitr로 더 많은 작업을 수행하면 기본 청크 옵션 중 일부가 필요에 맞지 않아 변경하고 싶을 때가 있습니다.

문서 YAML의 execute 아래에 선호하는 옵션을 추가하여 이를 수행할 수 있습니다. 예를 들어, 코드는 볼 필요가 없고 결과와 서술만 필요한 청중을 위해 보고서를 준비하는 경우 문서 수준에서 echo: false를 설정할 수 있습니다. 그렇게 하면 기본적으로 코드가 숨겨지므로 의도적으로 표시하도록 선택한 청크(echo: true 사용)만 표시됩니다. message: false 및 warning: false를 설정하는 것을 고려할 수 있지만, 그러면 최종 문서에 메시지가 표시되지 않기 때문에 문제를 디버깅하기가 더 어려워집니다.

title: "My report"
execute:
  echo: false

Quarto는 다국어(R뿐만 아니라 Python, Julia 등과 같은 다른 언어와도 작동)로 설계되었으므로, 문서 실행 수준에서는 모든 knitr 옵션을 사용할 수 없습니다. 일부 옵션은 knitr에서만 작동하고 Quarto가 다른 언어로 코드를 실행하는 데 사용하는 다른 엔진(예: Jupyter)에서는 작동하지 않기 때문입니다. 그러나 knitr 필드 아래, opts_chunk 아래에서 문서에 대한 전역 옵션으로 이것들을 설정할 수 있습니다. 예를 들어, 책과 튜토리얼을 작성할 때 우리는 다음과 같이 설정합니다:

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

이것은 우리가 선호하는 주석 형식을 사용하고 코드와 출력이 밀접하게 얽혀 있도록 합니다.

28.5.4 인라인 코드

Quarto 문서에 R 코드를 삽입하는 또 다른 방법이 있습니다: 텍스트에 직접 `r `을 사용합니다. 텍스트에서 데이터의 속성을 언급할 때 매우 유용할 수 있습니다. 예를 들어, 장의 시작 부분에서 사용된 예제 문서에는 다음이 있었습니다:

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:

보고서가 렌더링되면 이러한 계산 결과가 텍스트에 삽입됩니다:

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

텍스트에 숫자를 삽입할 때 format()은 당신의 친구입니다. digits 수를 설정하여 터무니없는 정밀도로 인쇄하지 않도록 하고, 숫자를 더 읽기 쉽게 만들기 위해 big.mark를 설정할 수 있습니다. 이것들을 도우미 함수로 결합할 수 있습니다:

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

28.5.5 연습문제

  1. 다이아몬드 크기가 컷, 색상 및 투명도에 따라 어떻게 달라지는지 탐구하는 섹션을 추가하세요. R을 모르는 사람을 위해 보고서를 작성하고 있다고 가정하고 각 청크에 echo: false를 설정하는 대신 전역 옵션을 설정하세요.

  2. https://github.com/hadley/r4ds/tree/main/quarto에서 diamond-sizes.qmd를 다운로드하세요. 가장 중요한 속성을 표시하는 표를 포함하여 가장 큰 20개의 다이아몬드를 설명하는 섹션을 추가하세요.

  3. diamonds-sizes.qmd를 수정하여 label_comma()를 사용하여 보기 좋게 포맷된 출력을 생성하세요. 또한 2.5캐럿보다 큰 다이아몬드의 비율을 포함하세요.

28.6 그림

Quarto 문서의 그림은 임베디드(예: PNG 또는 JPEG 파일)되거나 코드 청크의 결과로 생성될 수 있습니다.

외부 파일의 이미지를 삽입하려면 RStudio의 비주얼 에디터에서 Insert 메뉴를 사용하고 Figure / Image를 선택하세요. 그러면 삽입할 이미지를 찾아보고 대체 텍스트나 캡션을 추가하고 크기를 조정할 수 있는 메뉴가 팝업됩니다. 비주얼 에디터에서 클립보드의 이미지를 문서에 붙여넣기만 하면 RStudio가 해당 이미지의 사본을 프로젝트 폴더에 배치합니다.

그림을 생성하는 코드 청크(예: ggplot() 호출 포함)를 포함하면 결과 그림이 Quarto 문서에 자동으로 포함됩니다.

28.6.1 그림 크기 조정

Quarto에서 그래픽의 가장 큰 과제는 그림의 크기와 모양을 올바르게 만드는 것입니다. 그림 크기를 제어하는 다섯 가지 주요 옵션이 있습니다: fig-width, fig-height, fig-asp, out-width 및 out-height. 이미지 크기 조정은 두 가지 크기(R이 생성한 그림의 크기와 출력 문서에 삽입되는 크기)와 크기를 지정하는 여러 방법(즉, 높이, 너비, 가로세로 비율: 셋 중 두 개 선택)이 있기 때문에 까다롭습니다.

다섯 가지 옵션 중 세 가지를 권장합니다:

  • 플롯은 너비가 일관적일 때 미적으로 더 보기 좋은 경향이 있습니다. 이를 강제하려면 기본값에서 fig-width: 6 (6”) 및 fig-asp: 0.618 (황금비)을 설정하세요. 그런 다음 개별 청크에서 fig-asp만 조정하세요.

  • out-width로 출력 크기를 제어하고 출력 문서 본문 너비의 백분율로 설정하세요. out-width: "70%" 및 fig-align: center를 제안합니다.

    이렇게 하면 플롯이 너무 많은 공간을 차지하지 않으면서 숨 쉴 공간을 줍니다.

  • 여러 플롯을 한 행에 넣으려면 두 플롯의 경우 layout-ncol을 2로, 세 플롯의 경우 3 등으로 설정하세요. 이렇게 하면 layout-ncol이 2인 경우 각 플롯에 대해 out-width가 사실상 “50%”로 설정되고 layout-ncol이 3인 경우 “33%” 등으로 설정됩니다. 설명하려는 내용(예: 데이터 표시 또는 플롯 변형 표시)에 따라 아래에서 설명하는 것처럼 fig-width를 조정할 수도 있습니다.

플롯의 텍스트를 읽기 위해 눈을 가늘게 뜨고 봐야 한다면 fig-width를 조정해야 합니다. fig-width가 최종 문서에서 렌더링되는 그림 크기보다 크면 텍스트가 너무 작아집니다. fig-width가 작으면 텍스트가 너무 커집니다. 문서의 fig-width와 최종 너비 사이의 올바른 비율을 파악하기 위해 약간의 실험을 해야 할 때가 많습니다. 원리를 설명하기 위해 다음 세 플롯은 각각 4, 6, 8의 fig-width를 가집니다:

자동차의 고속도로 마일리지 대 배기량의 산점도. 점들은 보통 크기이고 축 텍스트와 레이블은 주변 텍스트와 비슷한 글꼴 크기입니다.

자동차의 고속도로 마일리지 대 배기량의 산점도. 점들은 이전 플롯보다 작고 축 텍스트와 레이블은 주변 텍스트보다 작습니다.

자동차의 고속도로 마일리지 대 배기량의 산점도. 점들은 이전 플롯보다 훨씬 작고 축 텍스트와 레이블은 주변 텍스트보다 훨씬 작습니다.

모든 그림에서 글꼴 크기가 일관되도록 하려면 out-width를 설정할 때마다 기본 out-width와 동일한 비율을 유지하도록 fig-width도 조정해야 합니다. 예를 들어 기본 fig-width가 6이고 out-width가 “70%”인 경우 out-width: "50%"로 설정할 때 fig-width를 4.3(6 * 0.5 / 0.7)으로 설정해야 합니다.

그림 크기 조정 및 스케일링은 예술이자 과학이며 올바르게 수행하려면 반복적인 시행착오 접근 방식이 필요할 수 있습니다. 플롯 스케일링 제어하기 블로그 게시물에서 그림 크기 조정에 대해 자세히 알아볼 수 있습니다.

28.6.2 기타 중요한 옵션

이 책에서처럼 코드와 텍스트를 섞을 때 fig-show: hold를 설정하여 플롯이 코드 뒤에 표시되도록 할 수 있습니다. 이것은 큰 코드 블록을 설명과 함께 나누도록 강제하는 즐거운 부작용이 있습니다.

플롯에 캡션을 추가하려면 fig-cap을 사용하세요. Quarto에서 이것은 그림을 인라인에서 “플로팅(floating)”으로 변경합니다.

PDF 출력을 생성하는 경우 기본 그래픽 유형은 PDF입니다. PDF는 고품질 벡터 그래픽이므로 좋은 기본값입니다. 그러나 수천 개의 점을 표시하는 경우 매우 크고 느린 플롯을 생성할 수 있습니다. 이 경우 fig-format: "png"를 설정하여 PNG 사용을 강제하세요. 품질은 약간 낮지만 훨씬 더 컴팩트합니다.

다른 청크에 일상적으로 레이블을 지정하지 않더라도 그림을 생성하는 코드 청크에는 이름을 지정하는 것이 좋습니다. 청크 레이블은 디스크의 그래픽 파일 이름을 생성하는 데 사용되므로 청크 이름을 지정하면 플롯을 골라내고 다른 상황(예: 이메일에 단일 플롯을 빠르게 넣으려는 경우)에서 재사용하기가 훨씬 쉽습니다.

28.6.3 연습문제

  1. 비주얼 에디터에서 diamond-sizes.qmd를 열고 다이아몬드 이미지를 찾아 복사하여 문서에 붙여넣으세요. 이미지를 두 번 클릭하고 캡션을 추가하세요. 이미지 크기를 조정하고 문서를 렌더링하세요. 이미지가 현재 작업 디렉토리에 어떻게 저장되는지 관찰하세요.
  2. diamond-sizes.qmd에서 플롯을 생성하는 코드 청크의 레이블을 접두사 fig-로 시작하도록 편집하고 청크 옵션 fig-cap으로 그림에 캡션을 추가하세요. 그런 다음 코드 청크 위의 텍스트를 편집하여 Insert > Cross Reference로 그림에 대한 상호 참조를 추가하세요.
  3. 다음 청크 옵션을 한 번에 하나씩 사용하여 그림의 크기를 변경하고 문서를 렌더링한 다음 그림이 어떻게 변하는지 설명하세요.

    1. fig-width: 10

    2. fig-height: 3

    3. out-width: "100%"

    4. out-width: "20%"

28.7 표

그림과 마찬가지로 Quarto 문서에 두 가지 유형의 표를 포함할 수 있습니다. Quarto 문서에서 직접(표 삽입 메뉴 사용) 만드는 마크다운 표일 수도 있고 코드 청크의 결과로 생성된 표일 수도 있습니다. 이 섹션에서는 후자, 즉 계산을 통해 생성된 표에 초점을 맞출 것입니다.

기본적으로 Quarto는 콘솔에서 보는 것처럼 데이터 프레임과 행렬을 인쇄합니다:

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

추가 서식이 지정된 데이터가 표시되기를 원한다면 knitr::kable() 함수를 사용할 수 있습니다. 아래 코드는 Table 28.1 을 생성합니다.

knitr::kable(mtcars[1:5, ], )
Table 28.1: 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

표를 사용자 정의할 수 있는 다른 방법을 보려면 ?knitr::kable 설명서를 읽어보세요. 더 깊은 사용자 정의를 위해서는 gt, huxtable, reactable, kableExtra, xtable, stargazer, pander, tables, ascii 패키지를 고려해 보세요. 각각은 R 코드에서 서식이 지정된 표를 반환하기 위한 도구 세트를 제공합니다.

28.7.1 연습문제

  1. 비주얼 에디터에서 diamond-sizes.qmd를 열고 코드 청크를 삽입한 다음 diamonds 데이터 프레임의 처음 5행을 보여주는 knitr::kable()이 있는 표를 추가하세요.
  2. 대신 gt::gt()로 같은 표를 표시하세요.
  3. 접두사 tbl-로 시작하는 청크 레이블을 추가하고 청크 옵션 tbl-cap으로 표에 캡션을 추가하세요. 그런 다음 코드 청크 위의 텍스트를 편집하여 Insert > Cross Reference로 표에 대한 상호 참조를 추가하세요.

28.8 캐싱

일반적으로 문서의 각 렌더링은 완전히 깨끗한 상태에서 시작합니다. 이것은 모든 중요한 계산을 코드로 캡처했음을 보장하기 때문에 재현성에 좋습니다. 그러나 시간이 오래 걸리는 계산이 있는 경우 고통스러울 수 있습니다. 해결책은 cache: true입니다.

표준 YAML 옵션을 사용하여 문서의 모든 계산 결과를 캐싱하기 위해 문서 수준에서 Knitr 캐시를 활성화할 수 있습니다:

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

또한 특정 청크의 계산 결과를 캐싱하기 위해 청크 수준에서 캐싱을 활성화할 수도 있습니다:

```{r}
#| cache: true
# 시간이 오래 걸리는 계산 코드...
```

설정되면 청크의 출력을 디스크의 특별한 이름의 파일에 저장합니다. 후속 실행에서 knitr는 코드가 변경되었는지 확인하고 변경되지 않았으면 캐시된 결과를 재사용합니다.

캐싱 시스템은 주의해서 사용해야 합니다. 기본적으로 종속성이 아닌 코드에만 기반하기 때문입니다. 예를 들어, 여기서 processed_data 청크는 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))
```

processed_data 청크를 캐싱한다는 것은 dplyr 파이프라인이 변경되면 다시 실행되지만 read_csv() 호출이 변경되면 다시 실행되지 않음을 의미합니다. 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은 캐시된 청크가 의존하는 모든 청크의 문자 벡터를 포함해야 합니다. Knitr는 종속성 중 하나가 변경된 것을 감지할 때마다 캐시된 청크의 결과를 업데이트합니다.

knitr 캐싱은 .qmd 파일 내의 변경 사항만 추적하기 때문에 a_very_large_file.csv가 변경되어도 청크가 업데이트되지 않습니다. 해당 파일의 변경 사항도 추적하려면 cache.extra 옵션을 사용할 수 있습니다. 이것은 변경될 때마다 캐시를 무효화하는 임의의 R 표현식입니다. 사용하기 좋은 함수는 file.mtime()입니다: 마지막으로 수정된 시간을 반환합니다. 그러면 다음과 같이 쓸 수 있습니다:

``` {{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")
```

우리는 David Robinson의 조언에 따라 청크 이름을 지정했습니다: 각 청크는 생성하는 기본 객체의 이름을 따서 명명됩니다. 이렇게 하면 dependson 사양을 이해하기 더 쉬워집니다.

캐싱 전략이 점점 더 복잡해짐에 따라 정기적으로 knitr::clean_cache()로 모든 캐시를 지우는 것이 좋습니다.

28.8.1 연습문제

  1. d가 c와 b에 의존하고 b와 c 모두 a에 의존하는 청크 네트워크를 설정하세요. 각 청크가 lubridate::now()를 인쇄하고 cache: true를 설정한 다음 캐싱에 대한 이해를 확인하세요.

28.9 문제 해결

Quarto 문서 문제 해결은 더 이상 대화형 R 환경에 있지 않기 때문에 어려울 수 있으며 몇 가지 새로운 요령을 배워야 합니다. 또한 오류는 Quarto 문서 자체의 문제이거나 Quarto 문서 내의 R 코드 문제일 수 있습니다.

코드 청크가 있는 문서에서 흔히 발생하는 오류 중 하나는 중복된 청크 레이블이며, 코드 청크를 복사하여 붙여넣는 워크플로우를 사용하는 경우 특히 만연합니다. 이 문제를 해결하려면 중복된 레이블 중 하나를 변경하기만 하면 됩니다.

오류가 문서의 R 코드로 인한 것이라면 가장 먼저 시도해야 할 것은 대화형 세션에서 문제를 재현하는 것입니다. R을 다시 시작한 다음 Code 메뉴의 Run region 아래에서 “Run all chunks”를 실행하거나 키보드 단축키 Ctrl + Alt + R을 사용하세요. 운이 좋다면 문제가 재현되어 대화형으로 무슨 일이 일어나고 있는지 파악할 수 있습니다.

도움이 되지 않는다면 대화형 환경과 Quarto 환경 사이에 뭔가 다른 점이 있는 것입니다. 옵션을 체계적으로 탐색해야 합니다. 가장 흔한 차이점은 작업 디렉토리입니다: Quarto의 작업 디렉토리는 파일이 있는 디렉토리입니다. 청크에 getwd()를 포함하여 작업 디렉토리가 예상한 것인지 확인하세요.

다음으로 버그를 유발할 수 있는 모든 것을 브레인스토밍하세요. R 세션과 Quarto 세션에서 동일한지 체계적으로 확인해야 합니다. 가장 쉬운 방법은 문제를 일으키는 청크에 error: true를 설정한 다음 print()와 str()을 사용하여 설정이 예상대로인지 확인하는 것입니다.

28.10 YAML 헤더

YAML 헤더의 매개변수를 조정하여 다른 많은 “전체 문서” 설정을 제어할 수 있습니다. YAML이 무엇을 의미하는지 궁금할 수 있습니다: “YAML Ain’t Markup Language”의 약자로, 사람이 읽고 쓰기 쉬운 방식으로 계층적 데이터를 표현하도록 설계되었습니다. Quarto는 이를 사용하여 출력의 많은 세부 사항을 제어합니다. 여기서는 자체 포함 문서, 문서 매개변수, 참고 문헌의 세 가지를 논의하겠습니다.

28.10.1 자체 포함

HTML 문서는 일반적으로 여러 외부 종속성(예: 이미지, CSS 스타일 시트, 자바스크립트 등)을 가지며, 기본적으로 Quarto는 이러한 종속성을 .qmd 파일과 같은 디렉토리의 _files 폴더에 배치합니다. HTML 파일을 호스팅 플랫폼(예: QuartoPub, https://quartopub.com/)에 게시하면 이 디렉토리의 종속성이 문서와 함께 게시되므로 게시된 보고서에서 사용할 수 있습니다. 그러나 보고서를 동료에게 이메일로 보내려면 모든 종속성을 포함하는 단일 자체 포함 HTML 문서를 선호할 수 있습니다. embed-resources 옵션을 지정하여 이를 수행할 수 있습니다:

format:
  html:
    embed-resources: true

결과 파일은 브라우저에서 올바르게 표시하기 위해 외부 파일이나 인터넷 액세스가 필요하지 않도록 자체 포함됩니다.

28.10.2 매개변수

Quarto 문서에는 보고서를 렌더링할 때 값을 설정할 수 있는 하나 이상의 매개변수가 포함될 수 있습니다. 매개변수는 다양한 주요 입력에 대해 고유한 값으로 동일한 보고서를 다시 렌더링하려는 경우 유용합니다. 예를 들어 지점별 판매 보고서, 학생별 시험 결과 또는 국가별 인구 통계 요약을 생성할 수 있습니다. 하나 이상의 매개변수를 선언하려면 params 필드를 사용하세요.

이 예제에서는 my_class 매개변수를 사용하여 표시할 자동차 클래스를 결정합니다:

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

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

library(tidyverse)

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

# `r params$my_class`의 연비

```{r}
#| message: false

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

보시다시피 매개변수는 코드 청크 내에서 params라는 읽기 전용 리스트로 사용할 수 있습니다.

원자 벡터를 YAML 헤더에 직접 쓸 수 있습니다. 매개변수 값 앞에 !expr를 붙여 임의의 R 표현식을 실행할 수도 있습니다. 이것은 날짜/시간 매개변수를 지정하는 좋은 방법입니다.

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

28.10.3 참고 문헌 및 인용

Quarto는 여러 스타일의 인용 및 참고 문헌을 자동으로 생성할 수 있습니다. Quarto 문서에 인용 및 참고 문헌을 추가하는 가장 간단한 방법은 RStudio의 비주얼 에디터를 사용하는 것입니다.

비주얼 에디터를 사용하여 인용을 추가하려면 Insert > Citation으로 이동하세요. 인용은 다양한 소스에서 삽입할 수 있습니다:

  1. DOI (디지털 객체 식별자) 참조.

  2. Zotero 개인 또는 그룹 라이브러리.

  3. Crossref, DataCite 또는 PubMed 검색.

  4. 문서 참고 문헌(문서 디렉토리의 .bib 파일)

내부적으로 시각적 모드는 인용에 대해 표준 Pandoc 마크다운 표현(예: [@citation])을 사용합니다.

처음 세 가지 방법 중 하나를 사용하여 인용을 추가하면 비주얼 에디터가 자동으로 bibliography.bib 파일을 만들고 참조를 추가합니다. 또한 문서 YAML에 bibliography 필드를 추가합니다. 참조를 더 추가하면 이 파일이 인용으로 채워집니다. BibLaTeX, BibTeX, EndNote, Medline을 포함한 많은 일반적인 참고 문헌 형식을 사용하여 이 파일을 직접 편집할 수도 있습니다.

소스 에디터의 .qmd 파일 내에 인용을 생성하려면 ‘@’ + 참고 문헌 파일의 인용 식별자로 구성된 키를 사용하세요. 그런 다음 인용을 대괄호 안에 넣으세요. 몇 가지 예는 다음과 같습니다:

여러 인용을 `;`로 구분: Blah blah [@smith04; @doe99].

대괄호 안에 임의의 주석 추가: 
Blah blah [see @doe99, pp. 33-35; also @smith04, ch. 1].

대괄호를 제거하여 텍스트 내 인용 생성: @smith04 
says blah, or @smith04 [p. 33] says blah.

인용 앞에 `-`를 추가하여 저자 이름 억제: 
Smith says blah [-@smith04].

Quarto가 파일을 렌더링할 때 참고 문헌을 빌드하고 문서 끝에 추가합니다. 참고 문헌에는 참고 문헌 파일의 각 인용된 참조가 포함되지만 섹션 제목은 포함되지 않습니다. 결과적으로 # References 또는 # Bibliography와 같은 참고 문헌에 대한 섹션 제목으로 파일을 끝내는 것이 일반적입니다.

csl 필드에서 CSL(인용 스타일 언어) 파일을 참조하여 인용 및 참고 문헌의 스타일을 변경할 수 있습니다:

bibliography: rmarkdown.bib
csl: apa.csl

bibliography 필드와 마찬가지로 csl 파일에는 파일 경로가 포함되어야 합니다. 여기서는 csl 파일이 .qmd 파일과 같은 디렉토리에 있다고 가정합니다. 일반적인 참고 문헌 스타일에 대한 CSL 스타일 파일을 찾기에 좋은 곳은 https://github.com/citation-style-language/styles입니다.

28.11 워크플로우

앞서 우리는 콘솔에서 대화형으로 작업한 다음 스크립트 에디터에서 작동하는 것을 캡처하는 R 코드를 캡처하기 위한 기본 워크플로우를 논의했습니다. Quarto는 콘솔과 스크립트 에디터를 하나로 묶어 대화형 탐색과 장기 코드 캡처 사이의 경계를 모호하게 만듭니다. Cmd/Ctrl + Shift + Enter로 편집하고 다시 실행하면서 청크 내에서 빠르게 반복할 수 있습니다. 만족하면 다음으로 이동하여 새 청크를 시작합니다.

Quarto는 산문과 코드를 매우 긴밀하게 통합하기 때문에 중요합니다. 이것은 코드를 개발하고 생각을 기록할 수 있게 해주기 때문에 훌륭한 분석 노트북이 됩니다. 분석 노트북은 물리 과학의 고전적인 실험실 노트와 많은 동일한 목표를 공유합니다. 그것은:

  • 수행한 작업과 수행한 이유를 기록합니다. 기억력이 아무리 좋아도 수행한 작업을 기록하지 않으면 중요한 세부 사항을 잊어버릴 때가 올 것입니다. 잊지 않도록 적어 두세요!

  • 엄격한 사고를 지원합니다. 진행하면서 생각을 기록하고 계속해서 반성하면 강력한 분석을 내놓을 가능성이 더 큽니다. 이것은 나중에 분석을 작성하여 다른 사람들과 공유할 때도 시간을 절약해 줍니다.

  • 다른 사람들이 당신의 일을 이해하도록 돕습니다. 혼자서 데이터 분석을 하는 경우는 드물며, 종종 팀의 일원으로 일하게 됩니다. 실험실 노트는 수행한 작업뿐만 아니라 왜 그렇게 했는지 동료나 실험실 친구들과 공유하는 데 도움이 됩니다.

실험실 노트를 효과적으로 사용하는 것에 대한 좋은 조언의 대부분은 분석 노트북으로도 번역될 수 있습니다. 우리는 우리 자신의 경험과 실험실 노트에 대한 Colin Purrington의 조언(https://colinpurrington.com/tips/lab-notebooks)을 바탕으로 다음 팁을 만들었습니다:

  • 각 노트북에 설명적인 제목, 기억하기 쉬운 파일 이름, 분석의 목표를 간략하게 설명하는 첫 번째 단락이 있는지 확인하세요.

  • YAML 헤더 날짜 필드를 사용하여 노트북 작업을 시작한 날짜를 기록하세요:

    date: 2016-08-23

    모호함이 없도록 ISO8601 YYYY-MM-DD 형식을 사용하세요. 평소에 날짜를 그렇게 쓰지 않더라도 사용하세요!

  • 분석 아이디어에 많은 시간을 할애했는데 막다른 골목으로 판명되더라도 삭제하지 마세요! 실패한 이유에 대한 짧은 메모를 작성하고 노트북에 남겨 두세요. 그러면 나중에 분석으로 다시 돌아올 때 같은 막다른 골목으로 가는 것을 피할 수 있습니다.

  • 일반적으로 데이터 입력은 R 외부에서 하는 것이 좋습니다. 하지만 데이터의 작은 스니펫을 기록해야 하는 경우 tibble::tribble()을 사용하여 명확하게 레이아웃하세요.

  • 데이터 파일에서 오류를 발견하면 직접 수정하지 말고 값을 수정하는 코드를 작성하세요. 수정한 이유를 설명하세요.

  • 하루를 마치기 전에 노트북을 렌더링할 수 있는지 확인하세요. 캐싱을 사용하는 경우 캐시를 지우세요. 그러면 코드가 아직 마음에 생생할 때 문제를 해결할 수 있습니다.

  • 코드를 장기적으로 재현 가능하게 하려면(즉, 다음 달이나 내년에 다시 실행할 수 있도록) 코드가 사용하는 패키지의 버전을 추적해야 합니다. 엄격한 접근 방식은 프로젝트 디렉토리에 패키지를 저장하는 renv(https://rstudio.github.io/renv/index.html)를 사용하는 것입니다. 빠르고 더러운 해킹은 sessionInfo()를 실행하는 청크를 포함하는 것입니다 — 이것은 오늘날 그대로 패키지를 쉽게 다시 만들 수는 없지만 적어도 무엇이었는지는 알 수 있습니다.

  • 경력 과정에서 아주, 아주, 아주 많은 분석 노트북을 만들게 될 것입니다. 나중에 다시 찾을 수 있도록 어떻게 정리하시겠습니까? 개별 프로젝트에 저장하고 좋은 명명 체계를 만드는 것을 추천합니다.

28.12 요약

이 장에서는 코드와 산문을 한곳에 포함하는 재현 가능한 계산 문서를 작성하고 게시하기 위한 Quarto를 소개했습니다. 비주얼 에디터나 소스 에디터로 RStudio에서 Quarto 문서를 작성하는 방법, 코드 청크가 작동하는 방식과 옵션을 사용자 정의하는 방법, Quarto 문서에 그림과 표를 포함하는 방법, 계산을 위한 캐싱 옵션에 대해 배웠습니다. 또한 자체 포함 또는 매개변수화된 문서를 만들기 위해 YAML 헤더 옵션을 조정하는 방법과 인용 및 참고 문헌을 포함하는 방법에 대해 배웠습니다. 또한 몇 가지 문제 해결 및 워크플로우 팁을 제공했습니다.

이 소개는 Quarto를 시작하기에 충분하지만 아직 배워야 할 것이 훨씬 더 많습니다. Quarto는 아직 비교적 젊고 빠르게 성장하고 있습니다. 혁신을 파악하기 가장 좋은 곳은 공식 Quarto 웹사이트입니다: https://quarto.org.

여기서 다루지 않은 두 가지 중요한 주제가 있습니다: 협업과 아이디어를 다른 사람들에게 정확하게 전달하는 세부 사항입니다. 협업은 현대 데이터 과학의 중요한 부분이며 Git 및 GitHub와 같은 버전 제어 도구를 사용하면 삶을 훨씬 더 쉽게 만들 수 있습니다. Jenny Bryan의 R 사용자를 위한 Git 및 GitHub에 대한 사용자 친화적인 소개인 “Happy Git with R”을 추천합니다. 이 책은 온라인에서 무료로 볼 수 있습니다: https://happygitwithr.com.

또한 분석 결과를 명확하게 전달하기 위해 실제로 무엇을 써야 하는지에 대해서는 다루지 않았습니다. 글쓰기를 향상시키려면 Joseph M. Williams & Joseph Bizup의 Style: Lessons in Clarity and Grace 또는 George Gopen의 The Sense of Structure: Writing from the Reader’s Perspective를 읽는 것을 강력히 추천합니다. 두 책 모두 문장과 단락의 구조를 이해하고 글을 더 명확하게 만드는 도구를 제공하는 데 도움이 될 것입니다. (이 책들은 새 것으로 구입하면 꽤 비싸지만 많은 영어 수업에서 사용되므로 저렴한 중고 사본이 많이 있습니다). George Gopen은 또한 https://www.georgegopen.com/litigation-articles.html에 글쓰기에 대한 짧은 기사를 많이 가지고 있습니다. 변호사를 대상으로 하지만 거의 모든 것이 데이터 과학자에게도 적용됩니다.