튜토리얼: 계산

개요

Quarto는 마크다운 안에서 실행 가능한 코드 블록을 지원합니다. 이를 통해 완전히 재현 가능한 문서와 보고서를 만들 수 있습니다. 출력물을 만드는 데 필요한 코드는 문서 자체에 포함되며, 문서를 렌더링할 때마다 자동으로 다시 실행됩니다.

이 튜토리얼에서는 RStudio에서 Quarto로 완전히 재현 가능한 계산 문서를 작성하는 방법을 보여드립니다.

자신의 환경에서 단계별로 따라 하려면 아래 Quarto 문서(.qmd)를 다운로드해 RStudio에서 열고 Render를 클릭하거나 단축키 ⇧⌘K를 사용하세요. 변경 사항을 실시간으로 미리 보려면 Render on Save 체크박스를 활성화하는 것도 권장합니다.

Download computations.qmd

이 문서를 열려면 RStudio v2022.07 이상이 필요하며, 여기에서 다운로드할 수 있습니다.

셀 출력

기본적으로 코드는 렌더링된 문서에 출력과 함께 표시됩니다.

RStudio 창에서 computations.qmd가 시각적 편집기(오른쪽)와 렌더링된 문서(왼쪽)에 표시되어 있습니다. 문서 제목은 Quarto Computations이며 텍스트와 코드가 포함되어 있고, 렌더링된 버전에는 시각화도 보입니다.

그러나 어떤 문서에서는 코드를 모두 숨기고 출력만 보여주고 싶을 수 있습니다. 이를 위해 YAML의 execute 옵션에 echo: false를 지정하세요.

---
title: "Quarto Computations"
execute:
  echo: false
---

앞에서 Render on Save를 체크했다면 이 변경 후 문서를 저장하기만 하면 실시간 미리 보기가 갱신됩니다. 그렇지 않다면 렌더링을 실행해 변경 사항을 확인하세요. 결과는 다음과 같이 보입니다.

Quarto Computations 제목과 설명 텍스트, 플롯이 있는 computations.qmd 렌더링 결과. 코드는 표시되지 않습니다.

일부 셀에서만 코드 echo를 선택적으로 활성화하고 싶을 수도 있습니다. 이 경우 echo: true 셀 옵션을 추가합니다. scatterplot 레이블이 있는 청크로 실습해 보세요.

#| label: scatterplot
#| echo: true

ggplot(mpg, aes(x = hwy, y = cty, color = cyl)) +
  geom_point(alpha = 0.5, size = 2) +
  scale_color_viridis_c() +
  theme_minimal()

문서를 다시 저장하고 scatterplot 청크에 코드가 포함되는지 확인하세요.

Quarto Computations 제목과 설명 텍스트, 플롯이 있는 computations.qmd 렌더링 결과. 플롯 코드는 보이지만 패키지 로딩 코드는 보이지 않습니다.

echo 옵션은 true, false, fenced로 설정할 수 있습니다. 마지막 옵션은 문서 및 교육 자료를 작성할 때 특히 유용한데, 실행 가능한 코드에는 fenced 코드 구분자가 필요하다는 점을 강조할 수 있기 때문입니다. 자세한 내용은 Fenced Echo 문서를 참고하세요.

셀 출력에 사용할 수 있는 옵션은 매우 많습니다. 예를 들어 warning은 경고 표시 여부를 제어하며(패키지 로딩 메시지에 특히 유용), include는 코드나 결과가 출력에 포함되지 않도록 하는 포괄 옵션이고, error는 코드 실행 오류가 문서 렌더링을 중단하지 않도록 하면서 오류를 렌더링된 문서에 출력합니다.

자세한 내용은 Knitr 셀 옵션 문서를 참고하세요.

코드 접기

코드를 완전히 숨기기보다 접어 두고 독자가 필요할 때 펼쳐보게 할 수도 있습니다. 이는 code-fold 옵션으로 설정할 수 있습니다. 앞에서 추가한 echo 옵션을 제거하고 HTML 형식 옵션에 code-fold를 추가하세요.

---
title: "Quarto Computations"
format:
  html:
    code-fold: true
---

문서를 다시 저장하면 각 코드 청크에 새로운 Code 위젯이 포함된 것을 확인할 수 있습니다.

RStudio에서 computations.qmd가 열려 있습니다. 오른쪽은 시각적 편집기이며 YAML에 title과 format이 정의되어 있습니다. 제목은 Quarto Computations이고 format은 html이며 code-fold가 true로 설정되어 있습니다. 오른쪽 렌더링된 문서에서는 제목과 텍스트, Code 위젯, 추가 텍스트, 또 다른 Code 위젯, 플롯이 순서대로 표시되며 Code 위젯은 접혀 있어 코드는 보이지 않습니다.

코드 접기를 전역으로 제어할 수도 있습니다. HTML 형식 옵션에 code-tools: true를 추가해 보세요.

---
title: "Quarto Computations"
format:
  html:
    code-fold: true
    code-tools: true
---

문서를 저장하면 렌더링된 문서 오른쪽 상단에 코드 메뉴가 나타나 모든 코드를 표시하거나 숨기는 전역 제어를 제공합니다.

computations.qmd를 렌더링한 결과. 문서 오른쪽 상단에 새 코드 위젯이 나타나며, 클릭하면 Show All Code, Hide All Code, View Source가 있는 드롭다운 메뉴가 표시됩니다. 배경에는 렌더링된 문서가 보이며 제목, 텍스트, Code 위젯, 추가 텍스트, 또 다른 Code 위젯, 플롯이 순서대로 표시되고 Code 위젯은 접혀 있어 코드는 보이지 않습니다.

코드 링크

code-link 옵션을 사용하면 코드 블록 안의 함수가 온라인 문서로 하이퍼링크됩니다. HTML 형식 옵션에 code-link: true를 추가해 보세요.

---
title: "Quarto Computations"
format:
  html:
    code-link: true
---

문서를 저장하고 함수 이름이 클릭 가능한 하이퍼링크로 바뀌었는지 확인하세요.

computations.qmd를 렌더링한 결과. 문서에는 제목(Quarto Computations), 텍스트, 코드 청크, 플롯이 포함되어 있습니다. 코드 청크의 함수 이름이 클릭 가능한 링크로 표시되며, 클릭하면 패키지 웹사이트의 문서(이미지 전면에 표시됨)로 이동합니다. 예시는 ggplot2의 theme_minimal()입니다.

코드 링크는 현재 downlit 패키지를 통해 knitr 엔진에서만 구현되어 있습니다. downlit의 현재 제한으로 code-line-numbers 및/또는 code-annotations가 true일 경우 코드 링크가 동작하지 않습니다.

그림

플롯의 모양과 접근성을 개선할 수 있습니다. fig-width와 fig-height로 종횡비를 변경하고, fig-cap으로 캡션을 제공하며, 상호 참조를 위해 label을 수정하고, fig-alt로 대체 텍스트를 추가할 수 있습니다.

다음 청크 옵션을 추가합니다.

#| label: fig-scatterplot
#| fig-cap: "City and highway mileage for 38 popular models of cars."
#| fig-alt: "Scatterplot of city vs. highway mileage for cars, where points are colored by the number of cylinders. The plot displays a positive, linear, and strong relationship between city and highway mileage, and mileage increases as the number of cylinders decreases."
#| fig-width: 6
#| fig-height: 3.5

문서를 저장해 업데이트된 플롯을 확인하세요. 아래와 같이 상호 참조를 사용해 내러티브도 업데이트했습니다.

@fig-scatterplot shows a positive, strong, and linear relationship between the city and highway mileage of these cars.

RStudio에서 computations.qmd가 열려 있습니다. 오른쪽은 시각적 편집기이며 YAML에 title과 format이 정의되어 있습니다. 제목은 Quarto Computations이고 format은 html이며 code-fold가 true로 설정되어 있습니다. 이전 이미지와 비교해 코드 청크에 새로운 옵션이 추가되어 있으며, 오른쪽 렌더링된 문서에는 캡션이 표시됩니다. Code 위젯은 접혀 있어 코드는 보이지 않습니다.

여러 그림

청크에 플롯을 하나 더 추가해 보겠습니다. 이번에는 다른 색상 스케일을 사용해 엔진 배기량에 따라 색이 구분되는 산점도를 추가합니다. 목표는 두 플롯을 나란히(즉, 두 열) 표시하고 각 플롯에 설명용 서브캡션을 붙이는 것입니다. 이렇게 하면 시각화가 더 넓어지므로 column 옵션으로 본문 열에 제한되지 않고 페이지 전체 너비를 사용하도록 하겠습니다.

이 청크에는 변경 사항이 꽤 많습니다. 따라 하려면 아래의 옵션을 Quarto 문서에 복사해 붙여 넣으세요.

#| label: fig-mpg
#| fig-cap: "City and highway mileage for 38 popular models of cars."
#| fig-subcap:
#|   - "Color by number of cylinders"
#|   - "Color by engine displacement, in liters"
#| layout-ncol: 2
#| column: page

ggplot(mpg, aes(x = hwy, y = cty, color = cyl)) +
  geom_point(alpha = 0.5, size = 2) +
  scale_color_viridis_c() +
  theme_minimal()

ggplot(mpg, aes(x = hwy, y = cty, color = displ)) +
  geom_point(alpha = 0.5, size = 2) +
  scale_color_viridis_c(option = "E") +
  theme_minimal()

또한 시각화를 설명하는 기존 텍스트를 아래 내용으로 바꾸세요.

The plots in @fig-mpg show the relationship between city and highway mileage for 38 popular models of cars.
In @fig-mpg-1 the points are colored by the number of cylinders while in @fig-mpg-2 the points are colored by engine displacement.

그다음 문서를 저장하고 렌더링된 결과를 확인하세요. 결과는 다음과 같아야 합니다.

computations.qmd를 렌더링한 결과에 새 플롯이 추가되었습니다. 문서에는 제목(Quarto Computations), 텍스트, 코드 청크, 그리고 나란히 배치된 두 개의 산점도 서브그림이 포함됩니다. 텍스트에는 Figure 1, Figure 1a, Figure 1b로 연결되는 상호 참조 링크가 표시됩니다.

여기에서 사용한 새 옵션을 살펴보겠습니다. fig-cap은 이전에 보았고, 이제 fig-subcap 옵션을 추가했습니다.

#| fig-cap: "City and highway mileage for 38 popular models of cars."
#| fig-subcap:
#|   - "Color by number of cylinders"
#|   - "Color by engine displacement, in liters"

여러 출력이 있는 코드 셀에서는 fig-subcap 옵션을 추가하면 서브그림으로 처리할 수 있습니다.

또한 여러 그림의 배치를 제어하는 옵션을 추가했습니다. 이번에는 두 열로 나란히 배치했습니다.

#| layout-ncol: 2

패널에 3개, 4개 이상의 그림이 있는 경우 레이아웃을 사용자화하는 다양한 옵션이 있습니다. 자세한 내용은 그림 레이아웃 문서를 참고하세요.

마지막으로 그림이 차지하는 페이지 범위를 제어하는 옵션을 추가했습니다.

#| column: page

이 옵션을 사용하면 그림 표시가 일반적인 본문 텍스트 열보다 더 넓게 펼쳐집니다. 사용 가능한 레이아웃 옵션에 대해서는 문서 레이아웃 문서를 참고하세요.

데이터 프레임

df-print 문서 옵션으로 데이터 프레임의 기본 출력 방식을 제어할 수 있습니다. 사용 가능한 옵션은 다음과 같습니다.

옵션 설명
default 데이터 프레임의 기본 S3 메서드를 사용합니다.
kable knitr::kable() 함수를 사용한 마크다운 표입니다.
tibble tibble 패키지를 사용한 일반 텍스트 표입니다.
paged 행과 열이 넘칠 때 페이징되는 HTML 표입니다(rmarkdown::paged_table() 사용).

예를 들어 데이터 프레임을 paged로 출력하려면 다음과 같이 지정합니다.

---
title: "Document"
format: 
   html:
     df-print: paged
---

인라인 코드

마크다운 안에 실행 가능한 표현식을 넣으려면 `{r} `로 표현식을 감싸세요.1 인라인 코드 표현식에 대한 추가 정보는 인라인 코드 문서를 참고하세요.

예를 들어 인라인 코드를 사용해 데이터의 관측치 수를 설명할 수 있습니다. 다음 마크다운 텍스트를 Quarto 문서에 추가해 보세요.

There are `{r} nrow(mpg)` observations in our data.

문서를 저장하고 렌더링된 결과를 확인하세요. 백틱 안의 표현식이 실행되어 문장에 실제 관측치 수가 포함됩니다.

데이터에는 234개의 관측치가 있습니다.

인라인으로 넣고 싶은 표현식이 복잡하거나 여러 함수/파이프라인을 포함한다면, echo: false로 설정한 코드 청크에서 계산하고 결과를 객체에 저장하는 것을 권장합니다. 그런 다음 인라인 코드에서 그 객체를 호출하세요.

예를 들어 데이터의 평균 시내 및 고속도로 연비를 설명하고 싶다고 합시다. 먼저 코드 청크에서 값을 계산합니다.

#| echo: false

mean_cty <- round(mean(mpg$cty), 2)
mean_hwy <- round(mean(mpg$hwy), 2)

그다음 아래 마크다운 텍스트를 Quarto 문서에 추가하세요.

The average city mileage of the cars in our data is `{r} mean_cty` and the average highway mileage is `{r} mean_hwy`.

문서를 저장하고 렌더링된 결과를 확인하세요.

데이터에 있는 차량의 평균 시내 연비는 16.86이고 평균 고속도로 연비는 23.44입니다.

캐시

문서에 계산 시간이 오래 걸리는 코드 청크가 포함되어 있다면, 해당 청크 결과를 캐시하고 싶을 수 있습니다. 문서 수준에서는 YAML의 execute 옵션을 사용해 cache 옵션을 설정할 수 있습니다.

execute:
  cache: true

하지만 문서의 모든 코드 청크를 캐시하는 것이 항상 바람직한 것은 아닙니다. 청크 옵션으로 어떤 청크를 캐시할지 직접 지정할 수도 있습니다.

#| cache: true

플롯을 생성하는 코드 청크 중 하나에 이 옵션을 추가해 저장해 보세요. 문서를 렌더링하면 작업 디렉터리에 문서 이름과 _cache 접미사가 붙은 새 폴더가 생성됩니다. 이 폴더에는 캐시된 결과가 저장됩니다. Quarto 문서 캐시에 대한 자세한 내용은 캐시 문서를 참고하세요.

이 튜토리얼을 단계별로 따라 했다면 이제 우리가 다룬 모든 내용을 구현한 Quarto 문서를 갖게 되었을 것입니다. 그렇지 않다면 아래에서 computations.qmd의 완료 버전을 다운로드할 수 있습니다.

Download computations-complete.qmd

다음 단계

이제 Quarto 문서에서 실행 가능한 코드의 동작과 출력을 사용자화하는 기본을 살펴보았습니다.

다음으로는 튜토리얼: 작성을 확인하여 출력 형식과 인용, 상호 참조, 고급 레이아웃 같은 기술 문서 작성 기능을 더 알아보세요.

Footnotes

  1. Quarto는 Knitr 구문 `r `도 지원합니다. 자세한 내용은 인라인 코드를 참고하세요.↩︎