실행 옵션

출력 옵션

실행된 코드의 출력을 사용자 정의하는 다양한 옵션이 있습니다. 모든 옵션은 전역(문서 front matter) 또는 코드 블록별로 지정할 수 있습니다. 예를 들어 아래는 Python 예제를 수정해 코드가 출력 문서에 “에코”되지 않도록 설정한 것입니다.

---
title: "My Document"
execute:
  echo: false
jupyter: python3
---

이 옵션은 코드 블록마다 덮어쓸 수 있습니다. 예:

```{python}
#| echo: true

import matplotlib.pyplot as plt
plt.plot([1,2,3,4])
plt.show()
```

코드 블록 옵션은 블록 상단의 특수 주석에 포함됩니다(상단에서 #|로 시작하는 줄은 옵션으로 간주됩니다).

출력 사용자 정의 옵션은 다음과 같습니다.

옵션	설명
eval	코드 청크를 평가합니다(false면 코드만 출력에 표시합니다).
echo	소스 코드를 출력에 포함합니다.
output	코드 실행 결과를 출력에 포함합니다(true, false, 또는 asis로 설정하면 출력이 원시 마크다운이며 Quarto의 표준 래핑 마크다운을 추가하지 않습니다).
warning	경고를 출력에 포함합니다.
error	오류를 출력에 포함합니다(이 옵션을 켜면 코드 실행 중 오류가 발생해도 문서 처리가 중단되지 않습니다).
include	코드나 결과를 포함하지 않도록 하는 포괄 옵션입니다(예: include: false는 코드 블록의 모든 출력을 숨깁니다).
renderings	셀의 플롯 또는 표 출력에 대한 렌더링 이름을 지정합니다(예: [light, dark]).

다음은 이러한 추가 옵션을 포함한 Knitr 예시입니다.

---
title: "Knitr Document"
execute:
  echo: false
---

```{r}
#| warning: false

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

```{r}
summary(airquality)
```

셀 렌더링

renderings를 사용해 플롯의 라이트/다크 버전을 제공하는 예시는 다음과 같습니다. 셀 출력 수는 렌더링 수와 일치해야 합니다.

---
title: "Dark mode"
format: 
  html:
    theme:
      light: flatly
      dark: darkly
---

```{r}
#| renderings: [light, dark]
par(bg = "#FFFFFF", fg = "#000000")
plot(1:10) # Shown in `light` mode

par(bg = "#000000", fg = "#FFFFFF", col.axis = "#FFFFFF")
plot(1:10) # Shown in `dark` mode
```

light rendering

dark rendering

renderings 셀 옵션은 현재 셀 상호 참조 옵션(label이 fig-, tbl- 등으로 시작)이나 셀 캡션 옵션(fig-cap, tbl-cap 등)과 함께 올바르게 동작하지 않습니다.

renderings를 상호 참조 및/또는 캡션과 함께 사용하려면 펜스 div 문법을 사용하세요.

---
title: "Dark mode"
format:
  html:
    theme:
      light: flatly
      dark: darkly
---

::: {#fig-caption-crossref}

```{r}
#| label: caption-crossref
#| renderings: [light, dark]
par(bg = "#FFFFFF", fg = "#000000")
plot(1:10) # Shown in `light` mode


par(bg = "#000000", fg = "#FFFFFF", col.axis = "#FFFFFF")
plot(1:10) # Shown in `dark` mode
```

Light and dark renderings with a caption and crossref

:::

여기서 label은 상호 참조 레이블이 아니라는 점에 주목하세요. 즉, 상호 참조 유형 중 하나로 시작하지 않습니다. 디버깅과 안정적인 리소스 이름을 위해 label이 있는 셀에 이름을 붙이는 것은 좋은 습관입니다. 하지만 fig-, tbl- 등으로 시작하는 상호 참조 레이블은 renderings와 함께 사용할 수 없습니다.

Tip

Knitr 엔진을 사용할 때는 사용 가능한 네이티브 옵션(예: collapse, tidy, comment 등)도 사용할 수 있습니다. 자세한 내용은 Knitr 옵션 문서를 참고하세요. 위와 같이 옵션 주석 블록에 포함하거나, Knitr 문서에서처럼 {r}와 같은 줄에 포함할 수 있습니다.

Tip

Knitr 엔진은 객체나 표현식을 사용해 코드 청크를 조건부로 평가할 수도 있습니다. Using R: Knitr Options을 참고하세요.

그림 옵션

코드에서 생성되는 그림의 기본 너비와 높이를 제어하는 방법은 여러 가지가 있습니다. 먼저 Quarto는 대상 출력 포맷에 맞는 기본 너비와 높이를 설정한다는 점이 중요합니다. 기본값은 다음과 같습니다(단위: 인치).

포맷	기본값
기본	7 x 5
HTML 슬라이드	9.5 x 6.5
HTML 슬라이드 (reveal.js)	9 x 5
PDF	5.5 x 3.5
PDF 슬라이드 (Beamer)	10 x 7
PowerPoint	7.5 x 5.5
MS Word, ODT, RTF	5 x 4
EPUB	5 x 4
Hugo	8 x 5

이 기본값은 보기 좋은 비율의 그림을 제공하도록 선택된 것이지만, 다른 기본 크기를 선호한다면 자유롭게 실험해도 됩니다. fig-width와 fig-height 옵션으로 기본 크기를 변경할 수 있습니다. 예:

---
title: "My Document"
format: 
  html:
    fig-width: 8
    fig-height: 6
  pdf:
    fig-width: 7
    fig-height: 5
---

이 크기 값이 엔진 수준의 기본값에 어떻게 반영될까요? 이는 엔진마다 다릅니다.

• Knitr 엔진에서는 이 값이 fig.width, fig.height 청크 옵션의 기본값이 됩니다. 청크 수준 옵션으로 기본값을 덮어쓸 수 있습니다.

• Python에서는 이 값이 Matplotlib의 figure.figsize rcParam을 설정하는 데 사용됩니다(물론 특정 플롯에서 기본값을 수동으로 덮어쓸 수 있습니다).

• Julia에서는 이 값이 Plots.jl GR 백엔드의 기본 그림 크기를 초기화하는 데 사용됩니다.

  Jupyter에서 다른 그래픽 라이브러리를 사용하면서 이 값을 활용하려면 환경 변수 QUARTO_FIG_WIDTH, QUARTO_FIG_HEIGHT에서 값을 읽어올 수 있습니다.

Caution

Jupyter 엔진에서는 fig-width와 fig-height가 문서 또는 프로젝트 수준에서 지정된 경우에만 지원됩니다. 반면 Knitr 엔진에서는 이 옵션을 셀별 코드 옵션으로도 사용할 수 있습니다.

캡션과 대체 텍스트

fig-cap과 fig-alt 옵션을 사용해 코드로 생성된 그림의 캡션과 대체 텍스트를 지정할 수 있습니다. 예를 들어 아래는 플롯을 만드는 Python 코드 셀에 옵션을 추가한 것입니다.

```{python}
#| fig-cap: "Polar axis plot"
#| fig-alt: "A line plot on a polar axis"

import numpy as np
import matplotlib.pyplot as plt

r = np.arange(0, 2, 0.01)
theta = 2 * np.pi * r
fig, ax = plt.subplots(subplot_kw={'projection': 'polar'})
ax.plot(theta, r)
ax.set_rticks([0.5, 1, 1.5, 2])
ax.grid(True)
plt.show()
```

인라인 코드

Jupyter, Knitr, OJS는 모두 마크다운 안에서 인라인 코드를 실행할 수 있습니다(예: 서술형 텍스트에 최신 계산 결과를 자동 반영). 자세한 내용은 인라인 코드를 참고하세요.

원시 출력

output: asis 옵션을 사용하면 원시 마크다운 출력을 생성할 수 있습니다. output: asis가 지정되면 Quarto의 표준 래핑 div가 포함되지 않습니다. 예를 들어 아래는 output: asis로 두 개의 제목을 생성합니다.

Jupyter

```{python}
#| echo: false
#| output: asis

print("# Heading 1\n")
print("## Heading 2\n")
```

Knitr

```{r}
#| echo: false
#| output: asis

cat("# Heading 1\n")
cat("## Heading 2\n")
```

출력 결과는 다음과 같습니다.

# Heading 1

## Heading 2

마크다운을 생성하는 코드가 최종 출력에 포함되지 않도록 echo: false 옵션도 함께 사용했습니다.

만약 output: asis를 지정하지 않았다면, 중간 마크다운에서 출력은 Quarto의 .cell-output div에 포함됩니다.

::: {.cell-output-stdout}
```
# Heading 1

## Heading 2
  
```
:::

Jupyter 엔진에서는 IPython.display의 함수를 사용해 원시 마크다운 출력을 만들 수도 있습니다. 예:

```{python}
#| echo: false
radius = 10
from IPython.display import Markdown
Markdown(f"The _radius_ of the circle is **{radius}**.")
```

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 파일에도 추가할 수 있습니다.

Jupyter 옵션

표현식 출력

코드 셀에 여러 표현식이 있을 때 기본적으로는 마지막 최상위 표현식만 렌더링 결과에 포함됩니다. 예를 들어 다음 코드 셀을 보겠습니다.

```{python}
"first"
"last"
```

HTML로 렌더링하면 출력은 다음과 같습니다.

'last'

이 동작은 Jupyter shell interactivity의 last_expr 설정에 해당합니다.

ipynb-shell-interactivity 옵션으로 이 동작을 제어할 수 있습니다. 예를 들어 최상위 표현식을 모두 캡처하려면 all로 설정합니다.

---
title: All expressions
format: html
ipynb-shell-interactivity: all
---

이제 위 코드 셀은 다음과 같이 출력됩니다.

'first'

'last'

Note대시보드에서는 모든 표현식을 출력

대시보드에서는 ipynb-shell-interactivity의 기본값이 all입니다.

중간 파일

마크다운 입력에서 최종 출력으로 가는 과정에서 중간 파일이 생성되며, 렌더링이 끝나면 자동으로 삭제됩니다. 다음 옵션을 사용하면 중간 파일을 유지할 수 있습니다.

옵션	설명
keep-md	코드 실행으로 생성된 마크다운 파일을 유지합니다.
keep-ipynb	코드 실행으로 생성된 노트북 파일을 유지합니다(마크다운 입력 파일에만 적용).

예를 들어 렌더링 이후 Jupyter 중간 파일을 유지하려면 다음과 같이 지정합니다.

---
title: "My Document"
execute:
  keep-ipynb: true
jupyter: python3
---

펜스 에코

Quarto 코드 블록 사용법을 설명하는 튜토리얼이나 문서를 작성할 때는 코드 출력에 펜스 구분자(예: ```{python})를 포함해 실행 가능한 코드가 해당 구분자를 필요로 한다는 점을 강조하고 싶을 수 있습니다. 이때 echo: fenced 옵션을 사용합니다. 예를 들어 다음 코드 블록은:

```{python}
#| echo: fenced
1 + 1
```

다음과 같이 렌더링됩니다.

```{python}
1 + 1
```

2

이는 셀 옵션 사용법을 보여줄 때 특히 유용합니다. 예를 들어 output과 code-overflow 옵션을 사용하는 방법을 다음처럼 보여줄 수 있습니다.

```{python}
#| echo: fenced
#| output: false
#| code-overflow: wrap
1 + 1
```

이 코드 블록은 렌더링 문서에서 다음처럼 보입니다.

```{python}
#| output: false
#| code-overflow: wrap
1 + 1
```

모든 YAML 옵션이 펜스 코드 출력에 포함되지만, echo: fenced는 예외입니다(독자에게 혼란을 줄 수 있기 때문입니다).

이 동작은 문서 수준에서도 지정할 수 있습니다. 모든 실행 코드 블록에 펜스 구분자와 YAML 옵션을 포함하려면 다음과 같이 설정합니다.

---
title: "My Document"
format: html
execute:
  echo: fenced
---

실행되지 않은 블록

문서용(비실행) 펜스 코드 블록을 포함하고 싶은 경우가 많습니다. 이때 언어(예: python, r 등)를 한 쌍이 아니라 두 쌍의 중괄호로 감싸면 됩니다. 예:

```{{python}}
1 + 1
```

그러면 문서에는 다음과 같이 출력됩니다.

```{python}
1 + 1
```

여러 코드 블록과 다른 마크다운이 포함된 예시를 보여주려면, 예시 전체를 4개의 백틱으로 감싸고, 내부 코드 블록에는 두 겹 중괄호 문법을 사용하세요. 예:

````
---
title: "My document"
---

Some markdown content.

```{{python}}
1 + 1
```

Some additional markdown content.

````

엔진 바인딩

앞에서 계산에 사용되는 엔진은 자동으로 결정된다고 설명했습니다. 하지만 이를 사용자 정의하고 싶을 수 있습니다. 예를 들어 Knitr 대신 Jupyter R 커널을 사용하고 싶거나, reticulate를 통해 Python 코드를 Knitr로 실행하고 싶을 수 있습니다.

자동 바인딩의 기본 규칙은 다음과 같습니다.

확장자	엔진 바인딩
.qmd	파일에 {r} 코드 블록이 있으면 Knitr 엔진을 사용합니다. 파일에 그 외 실행 가능한 코드 블록(예: {python}, {julia}, {bash} 등)이 있으면 Jupyter 엔진을 사용합니다. 사용 커널은 처음 발견된 실행 코드 블록의 언어에 따라 결정됩니다. | 실행 가능한 코드 블록이 없으면 엔진을 사용하지 않습니다.
.ipynb	Jupyter 엔진
.Rmd	Knitr 엔진
.md	엔진 없음(md 문서에 실행 가능한 코드 블록이 있으면 오류가 발생합니다) |

Notepython과 r을 함께 사용하기

quarto 문서에 {python}과 {r} 코드 블록이 모두 있으면, quarto는 Knitr 엔진과 reticulate R 패키지를 사용해 python 콘텐츠를 실행합니다.

특히 .qmd 파일에서는 engine 옵션으로 사용할 엔진을 덮어쓸 수 있습니다. 예:

engine: jupyter

engine: knitr

또는 engine: markdown으로 실행 엔진을 사용하지 않도록 지정할 수도 있습니다.

knitr 또는 jupyter 옵션을 지정해도 기본 엔진을 덮어씁니다.

knitr: true

jupyter: python3

추가 엔진 전용 옵션을 포함하는 변형도 기본 엔진을 덮어씁니다.

knitr:
  opts_knit:
    verbose: true

jupyter:
  kernelspec:
    display_name: Python 3
    language: python
    name: python3

셸 명령

Quarto 계산 문서에서 셸 명령(Bash, Zsh 등)을 사용하는 방법은 엔진에 따라 다릅니다. Jupyter 엔진을 사용하는 경우 Jupyter 셸 매직을 사용할 수 있습니다. 예:

---
title: "Using Bash"
engine: jupyter
---

```{python}
!echo "foo"
```

echo 앞의 !가 Python 셀이 셸 명령을 실행할 수 있게 해줍니다.

Knitr 엔진을 사용하는 경우 ```{bash} 셀을 사용할 수 있습니다. 예:

---
title: "Using Bash"
engine: knitr
---

```{bash}
echo "foo" 
```

Knitr 엔진은 ```{python} 셀도 지원하므로, 같은 문서에서 R, Python, Bash를 함께 사용할 수 있습니다.