튜토리얼: 계산

개요

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

자신의 환경에서 단계별로 따라 하려면 아래 노트북을 다운로드하세요.

Download computations.ipynb

그런 다음 새 작업 디렉터리를 만들고 노트북을 해당 디렉터리로 복사하세요.

이 작업이 완료되면 터미널에서 해당 디렉터리로 이동하고(필요한 경우) 노트북 의존성을 설치한 뒤 Jupyter Lab을 열어 노트북 작업을 시작하세요. 설치 및 Jupyter Lab 실행에 사용할 수 있는 명령은 아래 표에 정리되어 있습니다.

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

시작 시 노트북은 아래와 같이 보입니다. 아직 어떤 셀도 실행되지 않은 상태입니다.

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

다음으로 Jupyter Lab에서 Quarto 명령을 실행할 새 터미널을 만드세요.

마지막으로 터미널에서 quarto preview를 실행하고, Jupyter Lab과 미리보기 브라우저를 나란히 배치하세요.

Terminal

quarto preview computations.ipynb

이제 모든 셀을 실행한 다음 노트북을 저장하세요. 미리보기가 즉시 업데이트되는 것을 확인할 수 있습니다.

셀 출력

노트북의 모든 코드는 렌더링된 문서에 표시됩니다. 하지만 어떤 경우에는 코드를 숨기고 출력만 보여주고 싶을 수 있습니다. 코드가 출력되지 않도록 문서의 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
execute:
   code-fold: true
jupyter: python3
---

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

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

---
title: Quarto Computations
execute:
   code-fold: true
   code-tools: true
jupyter: python3
---

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

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

import matplotlib.pyplot as plt

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

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

셀을 실행해 업데이트된 플롯을 확인하세요. 그런 다음 노트북을 저장해 Quarto 미리보기가 업데이트되도록 합니다.

여러 그림

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

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

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

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