R 사용하기

개요

Quarto는 RStudio의 차세대 다국어 문서 도구로, R Markdown의 다음 세대 버전이며 많은 새로운 기능과 역량을 제공합니다. R Markdown과 마찬가지로 Quarto는 Knitr를 사용해 R 코드를 실행하므로, 기존 Rmd 파일 대부분을 수정 없이 렌더링할 수 있습니다.

먼저 Quarto의 기본을 살펴본 다음, 아래 청크 옵션과 출력 포맷 섹션에서 Quarto와 R Markdown의 차이를 다룹니다.

코드 블록

언어 이름을 중괄호로 감싼 코드 블록(예: ```{r})은 실행 가능하며, 렌더링 시 Quarto가 실행합니다. 아래는 간단한 예시입니다.

---
title: "ggplot2 demo"
author: "Norah Jones"
date: "5/22/2021"
format: 
  html:
    code-fold: true
---

## Air Quality

@fig-airquality further explores the impact of temperature on ozone level.

```{r}
#| label: fig-airquality
#| fig-cap: "Temperature and ozone level."
#| warning: false

library(ggplot2)

ggplot(airquality, aes(Temp, Ozone)) + 
  geom_point() + 
  geom_smooth(method = "loess")
```

코드 블록 상단에 있는 특수 주석은 그림을 상호 참조할 수 있도록 하는 셀 수준 옵션입니다.

이 문서는 다음과 같은 렌더링 결과를 생성합니다.

출력 예시: 제목(ggplot2 demo), 저자(Norah Jones), 날짜(5/22/2021)가 표시되며, Air Quality 제목 아래에 'Figure 1 further explores the impact of temperature on ozone level.' 문장이 있고 코드 접기 영역 및 Figure 1 이미지와 캡션이 보인다.

실행 가능한 코드 블록으로 플롯, 데이터 프레임의 표 출력, 일반 텍스트 출력(예: 통계 요약 결과 출력) 등 다양한 유형의 출력을 생성할 수 있습니다.

코드 실행과 출력 동작을 제어하는 다양한 옵션이 있으며, 자세한 내용은 실행 옵션 문서에서 확인할 수 있습니다.

마크다운 흐름을 끊는 코드 블록 외에도 인라인 코드를 포함할 수 있습니다. 인라인 코드에 대한 자세한 내용은 인라인 코드 문서를 참고하세요.

렌더링

Quarto 문서를 렌더링하면 R 코드 블록이 자동으로 실행됩니다. Quarto 문서를 렌더링하는 방법은 다양합니다.

  1. RStudio의 Render 버튼 사용:

    RStudio에서 qmd 파일 상단이 표시된 화면. 문서 바로 위 툴바에 'Render' 버튼이 있고, 화살표가 이를 가리킨다.

    Render 버튼은 문서 YAML에 나열된 첫 번째 포맷을 렌더링합니다. 포맷이 지정되지 않으면 HTML로 렌더링합니다.

  2. 시스템 셸에서 quarto render 명령 사용:

    Terminal
    quarto render document.qmd # all formats
quarto render document.qmd --to pdf
quarto render document.qmd --to docx

    대상 파일(이 경우 document.qmd)은 항상 명령줄의 첫 번째 인수여야 합니다.

    render 명령은 문서 YAML에 나열된 모든 포맷을 렌더링합니다. 포맷이 지정되지 않으면 HTML로 렌더링합니다. --to 인수로 특정 포맷만 지정할 수도 있습니다.

  3. R 콘솔에서 quarto R 패키지 사용:

    library(quarto)
quarto_render("document.qmd") # all formats
quarto_render("document.qmd", output_format = "pdf")

    quarto_render() 함수는 quarto render의 래퍼이며 기본적으로 문서 YAML에 나열된 모든 포맷을 렌더링합니다.

    Quarto R 패키지는 R에서 명령줄 렌더링을 편리하게 하기 위한 도구이며, R에서 Quarto를 사용하기 위한 필수 요소는 아닙니다.

설치

Quarto를 R과 함께 사용하려면 rmarkdown R 패키지를 설치해야 합니다.

install.packages("rmarkdown")

rmarkdown 패키지를 설치하면 knitr 패키지도 함께 설치되므로 R 코드를 포함한 문서를 렌더링하는 데 필요한 모든 것이 준비됩니다.

Quarto는 시스템 PATH에서 R 버전을 선택합니다. Windows에서는 PATH에서 R을 찾지 못할 경우 레지스트리를 확인해 현재 R 버전을 찾습니다. Quarto가 사용하는 R 버전은 QUARTO_R 환경 변수를 R 바이너리 RScript가 있는 디렉터리로 설정해 변경할 수 있습니다.

RStudio

RStudio v2022.07 이상 버전에는 Quarto 문서를 편집하고 미리보기할 수 있는 지원이 포함되어 있습니다(아래 문서는 이 빌드 또는 이후 버전을 사용한다고 가정합니다).

RStudio에서 Quarto를 사용한다면 RStudio의 최신 릴리스를 사용하는 것을 강력히 권장합니다.

RStudio는 https://posit.co/download/rstudio-desktop/에서 다운로드할 수 있습니다.

Creating Documents

새 Quarto 문서를 만들려면 File : New File : Quarto Document… 명령을 사용하세요:

The 'New Quarto Document' dialog menu in RStudio.

Render and Preview

문서를 편집하면서 미리보려면 Render 버튼을 사용하세요:

The top section of a qmd file as displayed in RStudio. There is a toolbar right above the document containing various options, including 'Render.' There is a stylized, segmented blue arrow pointing at the word.

저장할 때마다 자동으로 렌더링하고 싶다면 편집기 도구 모음의 Render on Save 옵션을 선택하면 됩니다.

미리보기는 편집기 옆에 표시됩니다:

An RStudio window. On the left half of the page is a Quarto document and the 'Jobs' pane open underneath that. There is messages in green text in the 'Jobs' pane that say: 'Watching files for changes. Browse at http://localhost:4064'. On the right half of the window is the Quarto output of the document on the left, as rendered by Knitr.

문서를 다시 렌더링할 때마다 미리보기가 갱신됩니다. 나란히 미리보기는 HTML과 PDF 출력 모두에서 작동합니다.

Projects

Quarto 문서(또는 문서 모음)를 위한 새 프로젝트를 만들려면 File : New Project… 명령을 사용하고, New Directory를 지정한 다음 Quarto Project를 선택하세요:

A section of the 'New Project Wizard' menu from Rstudio. This section is titled 'Create Quarto Project'. The Quarto logo is displayed on the left. ON the right are fields for 'Type', 'Directory name', and 'Create project as subdirectory of:'. Underneath that are options for 'Engine', 'Create a git repository', and 'Use renv with this project'. The option for 'Engine' is set to 'Knitr'. There are buttons for 'Create Project' and 'Cancel' arranged side-by-side in the bottom right of the window. There is an option to 'Open in new session' in the button left corner.

이 UI로 기본 프로젝트뿐 아니라 웹사이트와 책도 만들 수 있습니다. git 저장소를 생성하고 프로젝트에 renv 환경을 초기화하는 옵션도 제공합니다.

Positron

Quarto 확장은 Positron에 포함되어 있으며, .qmd 파일 작업을 위한 다양한 도구를 제공합니다. 이 확장은 Positron의 기본 R 지원과 직접 통합되어 코드 완성, 셀 실행, Quarto 문서의 나란히 미리보기를 제공합니다.

편집기 패널에 소스 마크다운이 표시되고, 뷰어 패널에 렌더링된 문서가 표시된 Positron의 qmd 파일 스크린샷.편집기 패널에 소스 마크다운이 표시되고, 뷰어 패널에 렌더링된 문서가 표시된 Positron의 qmd 파일 스크린샷.

이 확장은 명령 팔레트, 단축키 , 또는 편집기 툴바의 Preview 버튼(Preview iconPreview icon)을 통해 사용할 수 있는 Quarto: Preview 명령을 제공합니다. 렌더링 후 미리보기는 Positron의 Viewer 패널에 표시됩니다.

Positron 사용법에 대한 자세한 내용은 도구: Positron에서 확인하세요.

VS Code

VS Code용 Quarto 확장은 .qmd 파일 작업을 위한 다양한 도구를 제공합니다. 이 확장은 R Extension과 직접 통합되어 다음과 같은 R 전용 기능을 제공합니다.

  1. 코드 완성
  2. 셀 실행
  3. 문맥 기반 도움말

VS Code에서 qmd 파일이 열려 있고, 왼쪽에는 소스 마크다운이, 오른쪽에는 출력된 플롯이 표시된 스크린샷.

VS Code 확장은 확장 패널에서 ’quarto’를 검색하거나 확장 마켓플레이스에서 설치할 수 있습니다.

VS Code 확장에는 명령 팔레트, 단축키 , 또는 편집기의 Preview 버튼(Preview iconPreview icon)으로 접근할 수 있는 Quarto: Preview 명령이 포함됩니다. 렌더링 후 미리보기는 VS Code에서 문서와 함께 패널에 표시됩니다.

VS Code 사용법에 대한 자세한 내용은 도구: VS Code에서 확인하세요.

Emacs

quarto-mode MELPA 패키지는 Quarto 문서를 편집하기 위한 Emacs 모드입니다. quarto-mode는 다음과 같이 설치합니다.

M-x package-refresh-contents
M-x package-install
  quarto-mode

ESS가 설치되어 있다면 quarto-mode는 R 코드 실행에 ESS를 사용합니다.

M-x quarto-preview를 사용하면 quarto 콘텐츠 변경을 감지하고 자동으로 새로고침되는 quarto preview 서버를 시작할 수 있습니다. 현재 버퍼가 quarto 프로젝트의 파일과 연결되어 있으면 프로젝트 전체를 미리보고, 그렇지 않으면 해당 파일만 미리봅니다.

청크 옵션

R Markdown 문서와 Quarto 문서의 중요한 차이점 중 하나는 Quarto에서 청크 옵션을 보통 청크 시작 줄이 아니라 코드 청크 상단의 특수 주석에 포함한다는 점입니다. 예:

```{r}
#| echo: false
#| fig-cap: "Air Quality"

library(ggplot2)
ggplot(airquality, aes(Temp, Ozone)) + 
  geom_point() + 
  geom_smooth(method = "loess", se = FALSE)
```

Quarto는 fig-cap, fig-subcap, fig-alt 같은 긴 옵션을 더 잘 수용하고, 청크 메타데이터를 쉽게 편집할 수 없는 구조화된 에디터(예: 대부분의 전통적인 노트북 UI)에서 청크 옵션을 쉽게 편집할 수 있도록 이 방식을 사용합니다.

Note

원한다면 청크 옵션을 첫 줄에 포함할 수도 있습니다(예: ```{r, echo = FALSE}). 다만 실행 엔진 간 문서의 이식성과 일관성을 위해 주석 기반 문법을 권장합니다.

이 방식으로 포함된 청크 옵션은 YAML 프론트매터 옵션과의 일관성을 위해 R 문법이 아니라 YAML 문법을 사용합니다. 다만 옵션 값 앞에 !expr를 붙이면 R 코드를 사용할 수 있습니다. 예:

#| fig-cap: !expr 'paste("Air", "Quality")'
Caution

!expr 문법은 YAML “tag” 리터럴의 예이며 직관적이지 않을 수 있습니다. !expr 뒤에는 _단일 YAML “flow scalar”_가 와야 합니다. 큰따옴표/작은따옴표/무따옴표 문자열이 어떻게 동작하는지에 대한 자세한 내용은 YAML spec을 참고하세요.

청크 레이블

label 옵션으로 코드 청크에 레이블을 지정할 수 있습니다.

```{r}
#| label: convert
airquality$TempC <- (5 / 9) * (airquality$Temp - 32)
```

상호 참조를 지정하지 않는 한, 청크 레이블에는 예약된 상호 참조 접두사를 사용하지 마세요.

출력 포맷

R Markdown과 Quarto의 또 다른 차이는 출력 포맷입니다. Quarto에는 더 많은 내장 출력 포맷(및 각 포맷을 사용자 정의하는 더 많은 옵션)이 있습니다. Quarto는 웹사이트, 책, 블로그 같은 특수 프로젝트 유형도 기본 지원합니다(외부 패키지에 의존하지 않음).

Quarto에서 포맷을 사용하려면 R Markdown의 output 대신 format 키를 사용합니다. 다음은 동일한 포맷 지정의 비교입니다.

R Markdown

title: "My Document"
output:
  html_document:
    toc: true
    number_sections: true
    css: styles.css

Quarto

title: "My Document"
format:
  html:
    toc: true
    number-sections: true
    css: styles.css

구문 차이의 한 가지 원인은 Quarto가 Pandoc 포맷 이름과 옵션에 더 밀접하게 맞춰져 있다는 점입니다(그래서 단어 구분자로 _ 대신 -를 사용합니다).

자세한 내용은 지원 포맷 목록과 각 사용자 가이드/레퍼런스를 참고하세요.

또한 더 고급 출력 포맷에 대해서는 웹사이트, 책, 블로그 문서를 참고하세요.

데이터 프레임

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

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

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

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

Knitr 옵션

Knitr 셀 실행 엔진을 사용하는 경우, YAML에서 기본 문서 수준의 Knitr 청크 옵션을 지정할 수 있습니다. 예:

---
title: "My Document"
format: html
knitr:
  opts_chunk: 
    collapse: true
    comment: "#>" 
    R.options:
      knitr.graphics.auto_pdf: true
---

opts_knit로 전역 Knitr 옵션도 추가로 지정할 수 있습니다.

R.options 청크 옵션은 코드 청크 실행 전에 options()로 일시적으로 R 옵션을 설정하고, 실행 직후 원래 값으로 복원할 수 있게 해주는 편리한 방법입니다.

위 예시에서는 단일 문서에 기본 Knitr 청크 옵션을 설정했습니다. 공유 knitr 옵션은 프로젝트 전체 _quarto.yml 파일이나 프로젝트 디렉터리 범위의 _metadata.yml 파일에도 추가할 수 있습니다.

캐싱

Knitr Cache는 문서 전체가 아니라 개별 셀 수준에서 동작합니다. 이는 편리할 수 있지만, 셀 간 의존성 관리에 대한 특별한 요구 사항이 생깁니다.

표준 YAML 옵션으로 문서 또는 프로젝트 수준에서 Knitr 캐시를 활성화할 수 있습니다.

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

셀별로 캐싱을 활성화할 수도 있습니다(이 경우 문서 수준 옵션은 설정하지 않습니다).

```{r}
#| cache: true

summary(cars)
```

Knitr 캐싱 동작에 영향을 주는 다양한 셀 수준 옵션이 있습니다. 자세한 내용은 Knitr 셀 옵션 문서를 참고하세요. 또한 Yihui Xie의 캐시 무효화 글도 좋은 참고 자료입니다.

렌더링

quarto render 명령줄 옵션으로 문서 코드를 변경하지 않고 캐싱 동작을 제어할 수 있습니다. 모든 청크에 캐시를 강제로 사용하거나, 옵션에 지정되어 있더라도 캐시를 비활성화하거나, 캐시가 무효화되지 않았더라도 강제로 새로고침할 수 있습니다.

Terminal
# 캐시 사용(옵션에 활성화되어 있지 않아도)
quarto render example.qmd --cache 

# 캐시 사용 안 함(옵션에 활성화되어 있어도)
quarto render example.qmd --no-cache 

# 캐시 사용 + 강제 새로고침 
quarto render example.qmd --cache-refresh

대안

렌더링 시간이 길어 캐싱을 고려한다면, 캐싱 외에도 아래 대안을 함께 고려할 수 있습니다.

실행 비활성화

서술/마크다운 작업만 하고 있다면 실행을 완전히 비활성화하는 것이 좋습니다. enabled: false 실행 옵션으로 설정합니다. 예:

---
title: "My Document"
format: html
execute: 
  enabled: false
---

Jupyter .ipynb 노트북으로 작성하는 경우(일반 텍스트 .qmd가 아닌), 이는 이미 기본 동작입니다. 즉, quarto render를 호출해도 실행은 되지 않고, 노트북에서 작업할 때 실행이 이루어집니다.

실행 고정

프로젝트에서 여러 문서를 한꺼번에 렌더링할 때 누적 비용이 걱정된다면 freeze 옵션을 고려하세요.

freeze 옵션을 사용하면 전체 프로젝트 렌더링 중 계산 문서를 다시 렌더링하지 않도록 하거나, 소스 파일이 변경될 때만 다시 렌더링하도록 지정할 수 있습니다.

execute:
  freeze: true  # 프로젝트 렌더링 중 다시 렌더링하지 않음
execute:
  freeze: auto  # 소스가 변경될 때만 다시 렌더링

freeze는 전체 프로젝트 렌더링 중 실행 여부를 제어합니다. 단일 문서나 프로젝트 하위 디렉터리를 증분 렌더링하면 코드는 항상 실행됩니다. 예:

Terminal
# 단일 문서 렌더링(항상 코드 실행)
quarto render document.qmd

# 프로젝트 하위 디렉터리 렌더링(항상 코드 실행)
quarto render articles

프로젝트에서 freeze를 사용하는 방법은 프로젝트 실행 관리 문서를 참고하세요.