튜토리얼: 계산

개요

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를 실행한 다음, 편집기와 미리보기 브라우저를 나란히 배치하세요.

Terminal
quarto preview computations.qmd

왼쪽에 텍스트 편집기, 오른쪽에 브라우저의 라이브 미리보기가 나란히 표시된 모습.

셀 출력

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

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

변경 후 파일을 저장하세요. 미리보기가 업데이트되어 코드 없이 출력만 표시됩니다.

computations.qmd에 'echo: false'를 설정한 출력. 제목과 NumPy 섹션의 배열, Matplotlib 섹션의 선 그래프, Plotly 섹션의 대화형 버블 차트가 보입니다.

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

```{python}
#| echo: true

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

파일을 저장하면 NumPy 셀에 코드가 포함되어 표시됩니다.

computations.qmd의 NumPy 섹션을 렌더링한 결과. 코드와 결과 배열이 함께 표시됩니다.

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

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

코드 접기

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

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

파일을 저장하세요. 이제 각 셀 출력 위에 “Code” 위젯이 나타납니다.

computations.qmd의 NumPy 섹션을 렌더링한 결과. 'Code'로 표시된 접기 위젯과 결과 배열이 함께 보입니다.

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

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

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

computations.qmd를 렌더링한 결과. 문서 오른쪽 상단에 코드 위젯이 새로 생겼고, 클릭하면 Show All Code, Hide All Code, View Source 항목이 있는 드롭다운 메뉴가 나타납니다. 배경에는 렌더링된 문서가 보이며, 제목 아래 텍스트와 접힌 Code 위젯, 그리고 코드 출력이 이어집니다.

그림

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

파일을 저장해 다시 렌더링하면 업데이트된 플롯이 보입니다.

computations.qmd의 Matplotlib 섹션 렌더링 결과. 코드 접기 위젯, 그림, 그리고 아래에 'Figure 1: Errorbar limit selection.' 캡션이 표시됩니다.

여러 그림

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)

파일을 저장하면 미리보기가 다음과 같이 업데이트됩니다.

Plotly 섹션 출력. 두 개의 차트가 나란히 표시됩니다. 첫 번째 캡션은 '(a) Gapminder: 1957', 두 번째 캡션은 '(b) Gapminder 2007'이며, 두 그림 아래에는 'Figure 1: Life Expectancy and GDP (Data from World Bank via gapminder.org).' 캡션이 있습니다.

여기에서 사용한 새 옵션을 살펴보겠습니다. 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 문서에서 실행 가능한 코드의 동작과 출력을 사용자화하는 기본을 살펴보았습니다.

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