5  ドキュメントの作成

データ分析の成果物はレポートやプレゼンテーションでまとめることが多いです。 その際、プログラムのソースコードとともに結果に至るまでの過程を記録しておくことは成果物の透明性を高めるために重要です。 そこで大事なのがドキュメントの作成です。 ソースコードと結果、さらに結果に対する解説や処理内容を文章にまとめることで、他の人が成果物を理解しやすくなります。 ここでは、データ分析におけるドキュメントの作成方法について紹介します。

5.1 文芸的プログラミング

通常のコンピュータプログラミングでは、プログラムのソースコードと実行結果は別々に扱われます。 コードと結果の関連性が失われている状態です。

例えばRの場合、スクリプトファイルにコードを書いて実行すると、コンソールに結果が表示されます。 コンソールに表示された結果をコピーして、別のファイルに貼り付けることで、ソースコードと結果を一つのファイルにまとめることができますが、コピーをし忘れたり、間違って貼り付けたりすることがあります。 またこのような作業では、データや処理内容を変更する度に上書きの必要性が生じるので手間がかかります。

文芸的プログラミングは、ソースコードと結果を含めた関連するドキュメントを一つのファイルにまとめることで、コードと結果の関連性を保ちながらドキュメントを作成する方法です。 コードの変更に伴って出力結果も自動的に更新されるため、手作業でのコピー&ペースト作業が不要になります。 このように動的に生成されるドキュメントを作成するツールとして、R MarkdownやJupyter Notebook(Jupyter)が有名です。

5.2 Quarto

QuartoはPositがオープンソースで開発している動的ドキュメント作成システムです。 Jupyterやプレーンテキストで書かれたファイルをもとに、HTMLやPDF、Wordなどのさまざまな形式でのドキュメントを作成することができます。 Rだけでなく、PythonやJuliaなどのプログラミング言語にも対応しています。

Rユーザにとっては、動的ドキュメントの作成にR Markdownを使うことが一般的ですが、QuartoはR Markdownの後継としても位置づけられています。 そのため、R Markdownの機能をほぼそのまま利用することができます。 実際、QuartoでのR言語の評価はR Markdown同様、knitrパッケージを介して行われます。

ここではQuartoの基本的な使い方として単一のドキュメント生成の手順を紹介します。 一方、Quartoにはウェブサイト、ブログ、書籍執筆をサポートする機能もあります。 これらのQuartoの詳細については公式ドキュメントを参照してください。

R Markdownの基礎は 松村優哉 ほか (2021) にまとまっています。

5.2.1 Quartoによるドキュメントの作成

Quartoでは、.qmdという拡張子のファイルを作成し、その中にコードと必要な文章を記述します。 .qmdファイルをもとに任意の形式でのドキュメントを生成します。 .qmdファイルの基本構成は以下の通りです。

  • フロントマター… ドキュメントのメタデータ（タイトルや著者名、出力形式などの実行オプション等）を記述する部分。YAML形式で記述します。
  • 文章… ドキュメントの本文。プレーンテキストに加えて、Markdown記法による文字装飾、LaTeX記法による数式記述が可能です。
  • コードブロック（コードセル）1 …

Quartoの基本構成要素

ファイルの先頭にYAMLの形式でメタデータを記述します。 以降はドキュメントの文章とコードとなります。

コードブロックの宣言は、R Markdown同様、バッククォート(`)を使います。 コードブロックの宣言部分には {} の中に言語名を記述します。 Rの場合はr、Pythonではpython、Juliaではjuliaとなります。

コードブロックには、プログラムやその出力に関する挙動を制御する実行オプションを記述できます2。 指定可能なオプションとして、echo（コードの表示有無）、eval（コードの評価有無）、図のサイズやキャプションなどがあります。

コードブロックの実行オプションは以下のように記述します。 コードブロックの上部に#|を記述し、その後にオプション名とパラメータを記述します。 論理値での指定が必要な実行オプションはtrueまたはfalseで指定します。 Rの論理値の指定はすべて大文字で行いますが、ここではすべて小文字で表記するので注意してください。

```{r}
#| eval: true
#| echo: false
#| fig-width: 5
#| fig-height: 5
#| fig-cap: "グラフの描画"
library(ggplot2)

mtcars |> 
  ggplot(aes(x = wt, y = mpg)) +
  geom_point() +
  labs(title = "燃費と重量の関係")
```

必要な文章とコードを記載したら、Quartoのコマンドを使ってドキュメントを生成します。 .qmdファイルからのドキュメント生成の工程を、Quartoではレンダーと呼びます。 レンダーは.qmdファイルだけでなく、Jupyterで使われる.ipynbファイルからも行うことができます。

レンダーはコマンドラインを使って以下のように行います。

quarto render document.qmd --to html

このコマンドを実行するとdocument.qmdファイルをもとにHTML形式のドキュメントを生成します。 出力形式をWordファイルに変更する場合は、--toオプションの引数をdocxに変更するだけです。

quarto render document.qmd --to docx

RStudioやVS Codeなどのアプリケーションでは、Quartoのコマンドを実行するためのインターフェースが提供されています。 これにより、コマンドの入力の手間がなくなり、より直感的にQuartoを使うことができます。

5.2.2 RStudioでのQuartoの利用

Quartoの機能を試すために、RStudioで新しい.qmdファイルを作成してみましょう。 Quartoが利用可能な状況であれば、RStudioからQuartoを使うことができます。 メニューから「File」、「New File」、「Quarto Document…」の順に進むと以下のような画面が表示されます。

RStudioでのqmdファイルの新規作成。Editorの箇所にチェックを入れるとビジュアルモードでの編集が可能となる（後述）

タイトルや出力形式を指定して「Create」ボタンをクリックすると新しい.qmdファイルが作成されます。 また、エンジンとしてKnitrかJupyterが選択可能です。Knitr、つまりRのエンジンであってもreticulateパッケージにより Pythonの実行ができますが、Jupyterを指定することで直接Pythonの実行が可能になります。

ソースペインに新たに作成されたファイル内にコードと文章を記述して、レンダーを行います。 レンダーはソースペイン上の「Render」ボタンより実行します。ボタンをクリックすると、バックグラウンドでquartoのコマンドが実行され、.qmdファイル中のソースコードの実行結果をもとに指定した形式のドキュメントが生成されます。

RStudioでは、Ctrl+Alt+I（macOSではCommand+Option+I）のショートカットキーを使うことで、コードブロックを追加できます。 このショートカットキーを使うと、コードブロックのエンジンとして{r}が自動的に挿入されます。

レンダーのとき、通常コードブロックの評価はコードの上部に記載されたものから行われますが、 その場での実行も可能です。 これはレンダーをする前に結果を確認するのに役立ちます。 対象のコードが書かれた行にカーソルを置いてCtrl+Enter（macOSではCommand+Enter）を押すことで、そのコードを実行できます。 コードブロック全体のコードを実行するには、Ctrl+Shift+Enter（macOSではCommand+Shift+Enter）を使います。 あるいは、コードブロックの右上にある右向きの三角形ボタンをクリックすることでも実行できます。

RStudioでのqmdファイルのインタラクティブ操作

文字装飾、図や数式、参考文献等の挿入結果を表示しながら、ファイルを編集するときにはビジュアルモードの利用が便利です。 ビジュアルモードは、ソースペイン中にある編集中のqmdファイルのタブで「Visual」を選択すると切り替わります。 あるいはフロントマターでeditor: visualを宣言しておくことで、ファイルを開いたときにビジュアルモードが自動的に適用されます。

5.2.3 PositronでのQuartoの利用

PositronもRStudio同様に、qmdファイルのインタラクティブな編集と実行をサポートしています。 レンダーやビジュアルモードの切り替えも可能です。 RStudioと異なるのは、Positronではipynbファイルの編集・実行ができる点です。

Positronでのqmdファイルの編集。コードブロック中のコード実行、レンダーボタンの配置はRStudioと同様。

5.3 PDFの出力

Quartoで日本語のPDFを生成する場合、2つの選択肢があります。 一つは出力形式を指定する際にpdfを指定する方法です。これはLaTeXを使ってPDFを生成する方法です。 もう一つの方法はtypstを出力形式として指定する方法です。 まずは一般的なLaTeXによるPDF出力方法を見てみましょう。

5.3.1 LaTeX

LaTeXを使ったPDF出力を行う場合、事前にLaTeXの環境を揃える必要があります。

QuartoのコマンドからもLaTeX環境を導入可能です。

quarto install tinytex

このコマンドを実行すると、TinyTeXというLaTeXディストリビューションがインストールされます。 ここまでで最低限のPDF出力環境が整います。

新規で.qmdファイルを作成する手順を思い出し、出力形式をPDFにして作成してみましょう。 フロントマターのformatの項目がpdfになっていることを確認してください。 ファイルを編集してレンダーを行ってファイルを出力する点はこれまでの手順と同じです。

LaTeXでの日本語のPDF出力

LaTeXを使ったPDF出力を行う際、いくつか追加設定が必要な場合があります。 以下は日本語を扱うPDFの生成のためのフロントマターの指定例です。

---
title: "日本語を含んだPDF"
format: 
  pdf:
    include-in-header:
      text: |
        \usepackage{zxjatype}
        \usepackage[ipaex]{zxjafont}
        \setmainfont{IPAexGothic}
---

LaTeXのパッケージであるzxjatypeとzxjafontを使って日本語の組版、フォントを指定しています。 日本語フォントの種類としてIPAexGothicを指定していますが、他のフォントを指定することも可能です。 詳細はzxjafontのドキュメントをご覧下さい。

5.3.2 Typst

次にTypstを利用したPDF出力方法を紹介します。 TypstはHTMLなどと同じマークアップ言語の一種です。 LaTeXの高度で柔軟な組版システムとWordやGoogleドキュメントなどのツールの代替となるように設計された新しい組版システムです。

バージョン1.4以降のQuartoでは、標準的にTypstが利用可能です。 フロントマターでformat: typstを指定するか、コマンドラインで--to typstを指定することでTypstによるPDFの生成が可能です。

Typstでの日本語のPDF出力

LaTeXを使ったPDF出力を行う際、いくつか追加設定が必要な場合があります。 以下は日本語を扱うPDFの生成のためのフロントマターの指定例です。

---
title: "日本語を含んだPDF"
format: 
  typst:
    mainfont: "Noto Sans JP"
---

5.4 gtパッケージによる表出力

ドキュメントで表を利用することは、目的が学術的であろうとビジネス向けであろうと頻繁に行われます。 Rには、R MarkdownやQuartoで表を出力するパッケージが豊富に存在します。 これらのパッケージを使うことで、綺麗な表出力が可能になります。

gtパッケージはデータフレーム形式のオブジェクトを表として出力します。 HTMLやLaTeX、RTFでの出力が可能で、さまざまなドキュメントで利用可能です。 表に求められるタイトルやキャプションの表示はもちろん、出力時のフォーマットや塗りつぶしの色の指定などが柔軟に行える特徴があります。

データフレームを対象として、gt()関数を適用します。 mtcarsデータを例に、gt()関数を適用してみましょう。

library(gt)

gttbl <- 
  head(mtcars) |> 
  gt()

gttbl
mpg cyl disp hp drat wt qsec vs am gear carb
21.0 6 160 110 3.90 2.620 16.46 0 1 4 4
21.0 6 160 110 3.90 2.875 17.02 0 1 4 4
22.8 4 108 93 3.85 2.320 18.61 1 1 4 1
21.4 6 258 110 3.08 3.215 19.44 1 0 3 1
18.7 8 360 175 3.15 3.440 17.02 0 0 3 2
18.1 6 225 105 2.76 3.460 20.22 1 0 3 1

表の見た目の変更は、作成したgt_tblオブジェクトに対して、処理を追加する形で行います。 例えば表の見出し、副見出しを指定するにはtab_header()関数を追加し、 列の見出しの背景色を指定するにはtab_options()関数を追加します。

gttbl |> 
  tab_header(
    title = "mtcars",
    subtitle = "先頭6行を表示"
  ) |> 
   tab_options(
    column_labels.background.color = "gray"
  )
mtcars
先頭6行を表示
mpg cyl disp hp drat wt qsec vs am gear carb
21.0 6 160 110 3.90 2.620 16.46 0 1 4 4
21.0 6 160 110 3.90 2.875 17.02 0 1 4 4
22.8 4 108 93 3.85 2.320 18.61 1 1 4 1
21.4 6 258 110 3.08 3.215 19.44 1 0 3 1
18.7 8 360 175 3.15 3.440 17.02 0 0 3 2
18.1 6 225 105 2.76 3.460 20.22 1 0 3 1

gtパッケージはグループ化

library(dplyr)

Attaching package: 'dplyr'
The following objects are masked from 'package:stats':

    filter, lag
The following objects are masked from 'package:base':

    intersect, setdiff, setequal, union
mtcars |> 
  select(cyl, disp, hp, drat, wt, qsec) |>
  group_by(cyl) |>
  gt() |> 
   summary_rows(
    groups = everything(),
    columns = c(disp, disp, hp, drat, wt, qsec),
    fns = list(
      average = "mean",
      total = "sum",
      SD = "sd"
    )
  ) |> 
  grand_summary_rows(
    columns = c(disp, disp, hp, drat, wt, qsec),
    fns = list(
      average = "mean",
      total = "sum",
      SD = "sd"
    )
  ) |> 
  tab_options(
    summary_row.background.color = "lightblue",
    grand_summary_row.background.color = "lightgreen")
disp hp drat wt qsec
6
160.0 110 3.90 2.620 16.46
160.0 110 3.90 2.875 17.02
258.0 110 3.08 3.215 19.44
225.0 105 2.76 3.460 20.22
167.6 123 3.92 3.440 18.30
167.6 123 3.92 3.440 18.90
145.0 175 3.62 2.770 15.50
mean 183.31429 122.28571 3.5857143 3.1171429 17.977143
sum 1283.20000 856.00000 25.1000000 21.8200000 125.840000
sd 41.56246 24.26049 0.4760552 0.3563455 1.706866
4
108.0 93 3.85 2.320 18.61
146.7 62 3.69 3.190 20.00
140.8 95 3.92 3.150 22.90
78.7 66 4.08 2.200 19.47
75.7 52 4.93 1.615 18.52
71.1 65 4.22 1.835 19.90
120.1 97 3.70 2.465 20.01
79.0 66 4.08 1.935 18.90
120.3 91 4.43 2.140 16.70
95.1 113 3.77 1.513 16.90
121.0 109 4.11 2.780 18.60
mean 105.13636 82.63636 4.0709091 2.2857273 19.137273
sum 1156.50000 909.00000 44.7800000 25.1430000 210.510000
sd 26.87159 20.93453 0.3654711 0.5695637 1.682445
8
360.0 175 3.15 3.440 17.02
360.0 245 3.21 3.570 15.84
275.8 180 3.07 4.070 17.40
275.8 180 3.07 3.730 17.60
275.8 180 3.07 3.780 18.00
472.0 205 2.93 5.250 17.98
460.0 215 3.00 5.424 17.82
440.0 230 3.23 5.345 17.42
318.0 150 2.76 3.520 16.87
304.0 150 3.15 3.435 17.30
350.0 245 3.73 3.840 15.41
400.0 175 3.08 3.845 17.05
351.0 264 4.22 3.170 14.50
301.0 335 3.54 3.570 14.60
mean 353.10000 209.21429 3.2292857 3.9992143 16.772143
sum 4943.40000 2929.00000 45.2100000 55.9890000 234.810000
sd 67.77132 50.97689 0.3723618 0.7594047 1.196014
mean 230.7219 146.68750 3.5965625 3.2172500 17.848750
sum 7383.1000 4694.00000 115.0900000 102.9520000 571.160000
sd 123.9387 68.56287 0.5346787 0.9784574 1.786943

  1. コードを記述する箇所。Jupyterではコードセルと呼ばれます。↩︎

  2. ドキュメント全体での制御はフロントマター内で行います。個別のコードブロックに対して記述したオプションが優先されます。実行オプションの詳細はQuarto公式ページのドキュメントに記載されています。↩︎