튜토리얼: 계산

개요

Quarto에는 렌더링된 문서에서 코드와 계산 출력이 표시되는 방식을 제어할 수 있는 다양한 옵션이 있습니다. 이 튜토리얼에서는 숫자 출력과 플롯이 포함된 .qmd 파일을 가지고 이러한 옵션을 적용하는 방법을 다룹니다.

이 튜토리얼에서는 matplotlib과 plotly 파이썬 패키지를 사용합니다. 설치에 사용할 수 있는 명령은 아래 표에 정리되어 있습니다.

플랫폼	명령
Mac/Linux	Terminal python3 -m pip install jupyter matplotlib plotly pandas
Windows	Terminal py -m pip install jupyter matplotlib plotly pandas

자신의 환경에서 단계별로 따라 하려면 computations.qmd 파일을 만들고 다음 내용을 복사해 넣으세요.

---
title: Quarto Computations
jupyter: python3
---

## NumPy

```{python}
import numpy as np
a = np.arange(15).reshape(3, 5)
a
```

## Matplotlib

```{python}
import matplotlib.pyplot as plt

fig = plt.figure()
x = np.arange(10)
y = 2.5 * np.sin(x / 20 * np.pi)
yerr = np.linspace(0.05, 0.2, 10)

plt.errorbar(x, y + 3, yerr=yerr, label='both limits (default)')
plt.errorbar(x, y + 2, yerr=yerr, uplims=True, label='uplims=True')
plt.errorbar(x, y + 1, yerr=yerr, uplims=True, lolims=True,
             label='uplims=True, lolims=True')

upperlimits = [True, False] * 5
lowerlimits = [False, True] * 5
plt.errorbar(x, y, yerr=yerr, uplims=upperlimits, lolims=lowerlimits,
             label='subsets of uplims and lolims')

plt.legend(loc='lower right')
plt.show(fig)
```

## Plotly

```{python}
import plotly.express as px
import plotly.io as pio
gapminder = px.data.gapminder()
gapminder2007 = gapminder.query("year == 2007")
fig = px.scatter(gapminder2007, 
                 x="gdpPercap", y="lifeExp", color="continent", 
                 size="pop", size_max=60,
                 hover_name="country")
fig.show()
```

그 다음 Quarto: Preview 명령을 실행하세요. 또는 Ctrl+Shift+K 단축키나 편집기 오른쪽 상단의 Preview 버튼()을 사용할 수 있습니다.

Mac에서는 모든 Quarto 단축키의 접두사로 Ctrl 대신 Cmd를 사용해야 합니다.

VS Code 안에서 다음과 같은 화면이 보일 것입니다.

셀 실행

문서를 작성하면서 전체 문서를 다시 렌더링하지 않고도 하나 이상의 셀을 실행하고 싶을 때가 있습니다. 이때 코드 셀 위의 Run Cell 버튼을 사용할 수 있습니다. 해당 버튼을 클릭하면 셀이 실행되며(출력은 Jupyter 인터랙티브 콘솔에 나란히 표시됩니다):

셀 실행에 사용할 수 있는 다양한 명령과 단축키는 다음과 같습니다.

Quarto 명령	키보드 단축키
Run Current Cell	⇧⌘ Enter
Run Selected Line(s)	⌘ Enter
Run Next Cell	⌥⌘ N
Run Previous Cell	⌥⌘ P
Run All Cells	⌥⌘ R
Run Cells Above	⇧⌥⌘ P
Run Cells Below	⇧⌥⌘ N

셀 출력

소스 파일의 모든 코드는 렌더링된 문서에 표시됩니다. 하지만 어떤 경우에는 코드를 숨기고 출력만 보여주고 싶을 수 있습니다. 코드가 출력되지 않도록 문서의 execute 옵션에 echo: false를 지정해 보겠습니다.

---
title: Quarto Computations
execute:
  echo: false
jupyter: python3
---

문서를 다시 렌더링하면 미리보기가 코드 없이 출력만 보여주도록 업데이트됩니다(렌더링 시 자동으로 저장되므로 별도로 저장할 필요가 없습니다).

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

```{python}
#| echo: true

import numpy as np
a = np.arange(15).reshape(3, 5)
a
```

문서를 다시 렌더링하면 NumPy 셀에 코드가 포함되는 것을 확인할 수 있습니다.

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

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

코드 접기

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

---
title: Quarto Computations
format:
  html:
    code-fold: true
jupyter: python3
---

문서를 렌더링하세요. 이제 각 셀 출력 위에 “Code” 위젯이 나타납니다.

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

---
title: Quarto Computations
format:
  html:
    code-fold: true
    code-tools: true
jupyter: python3
---

문서를 렌더링하면 문서 오른쪽 상단에 코드 메뉴가 나타나 전체 코드 표시/숨김을 전역으로 제어할 수 있습니다.

그림

Matplotlib 출력의 모양을 개선해 보겠습니다. 좀 더 넓게 만들고, 상호 참조를 위한 캡션과 레이블도 추가하면 좋습니다.

Matplotlib 셀을 수정하여 label과 fig-cap 옵션을 추가하고, fig.set_size_inches() 호출로 그림 크기를 넓은 비율로 조정하세요.

```{python}
#| label: fig-limits
#| fig-cap: "Errorbar limit selector"

import matplotlib.pyplot as plt

fig = plt.figure()
fig.set_size_inches(12, 7)
```

문서를 다시 렌더링하면 업데이트된 플롯이 보입니다.

여러 그림

Plotly 셀은 단일 연도(2007)의 GDP와 기대 수명 데이터를 시각화합니다. 비교를 위해 다른 연도를 나란히 그려보고 캡션과 서브캡션을 추가해 봅시다. 이렇게 하면 시각화가 더 넓어지므로 column 옵션으로 본문 열에 제한되지 않고 페이지 전체 너비를 사용하도록 하겠습니다.

이 셀에는 변경 사항이 많습니다. 로컬에서 실습하려면 아래 코드를 computations.qmd에 복사해 붙여 넣으세요.

#| label: fig-gapminder
#| fig-cap: "Life Expectancy and GDP"
#| fig-subcap:
#|   - "Gapminder: 1957"
#|   - "Gapminder: 2007"
#| layout-ncol: 2
#| column: page

import plotly.express as px
import plotly.io as pio
gapminder = px.data.gapminder()
def gapminder_plot(year):
    gapminderYear = gapminder.query("year == " + 
                                    str(year))
    fig = px.scatter(gapminderYear, 
                     x="gdpPercap", y="lifeExp",
                     size="pop", size_max=60,
                     hover_name="country")
    fig.show()
    
gapminder_plot(1957)
gapminder_plot(2007)

문서를 렌더링하면 미리보기가 다음과 같이 업데이트됩니다.

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

#| fig-cap: "Life Expectancy and GDP"
#| fig-subcap:
#|   - "Gapminder: 1957"
#|   - "Gapminder: 2007"

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

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

#| layout-ncol: 2

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

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

#| column: page

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

다음 단계

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

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