40  R Markdown で作るレポート

自動化され、再現性があり、かつ、共有する価値のあるアウトプット、すなわちレポートを作成するためにR Markdown は広い分野で利用されています。R Markdown は、静的な出力や、動的な出力を Word や pdf、html、PowerPoint、その他の形式で生成可能です。

R Markdownは、レポートなどの共有する価値のある、自動化され、再現性があるアウトプットを作成するためのツールとして広い分野で利用されています。それは、静的・動的な出力を Word や pdf、html、PowerPoint、その他の形式で生成可能です。

これら文書は、定期的に更新するために生成されたり（e.g. 日毎のサーベイランスレポート）、あるいは、データのサブセットをもとに実行する（e.g. 各管区ごとのレポート）ことが可能です。

このハンドブックの別の章では以下のトピックを追加で取り上げます：

• 定期レポート作成の効率化 の章では、自動生成されるタイムスタンプ付きのフォルダでレポート生成をルーチン化する方法を例示します。
• R Markdownで作るダッシュボード の章では、ダッシュボードとして R Markdown レポートを定型化する方法を説明します。

注釈として、R4Epis プロジェクトは、MSF プロジェクトで遭遇したよくあるアウトブレイクやサーベイシナリオのための R Markdown スクリプトテンプレートを開発してきました。

40.1 準備

R Markdown の背景

関連するコンセプトといくつかのパッケージについての説明として：

• Markdown は、プレーンテキストで文書を記述できる “言語” です。それで、記述された文書は、html や他の形式に変換できます。これは、R 言語に特化したものではありません。Markdown で記載されたファイルは, ’ .md’ 拡張子を持ちます。
• R Markdoen: は、R 言語に特化した markdown 言語の一種です。- それは、markdown 言語を用いて、テキストを生成し R コードを埋め込み、そのアウトプットを表示するための文書を記載することが可能です。 R Markdown ファイルは ‘.Rmd’ 拡張子を持ちます。
• rmarkdown - パッケージ: このパッケージをR上で利用することで、 .Rmd ファイルを希望の形式に描画することができます。このパッケージの目的は、markdown（文書）のシンタクスを変換することです。つまり、更に下記パッケージが必要です…
• knitr: この R パッケージは、コードチャンクを読み取り、実行し、さらに「編み上げて」（knit して）文書に差し込みます。このようにすることで、表やグラフをテキストとともに文書に含むことができます。
• Pandoc: 最後に、pandoc は、word/pdf/powerpoint などに出力を実際に変換します。R とは分離したソフトフェアですが、RStudio とともに自動的にインストールされます。

まとめると、バックグラウンドで 実行されるプロセス（それらのステップを全て知る必要はありません！）は、knitr に .Rmd ファイルを与えることに関わっています。このパッケージは、R コードチャンクを実行し、R コードとその出力を含む、新規の .md (markdown) ファイルを生成します。.md ファイルは、それから、完成品：（Microfoft Word ドキュメント、 HTML ファイル、powerpoint ドキュメント、pdf など）を作成するために pandoc で処理されます。

(ソース： https://rmarkdown.rstudio.com/authoring_quick_tour.html):

インストール

R Markdown の出力を生成するためには以下に挙げるものがインストールされている必要があります：

• rmarkdown パッケージ(knitr も自動的にインストールされます)
• RStudio とともにインストールされる Pandoc。もし RStudio を使用していない場合は、ここから Pandoc をダウンロード可能です： http://pandoc.org
• もし PDF 出力を生成したい場合は（少し変則的ですが）、LaTeX のインストールが必要です。事前に、 LaTeX をインストールしていない R Markdown ユーザには、TinyTex (https:yihui.name/tinytex/) のインストールをおすすめします。下記のコマンドでインストール可能です：

pacman::p_load(tinytex)     # tinytex パッケージのインストール
tinytex::install_tinytex()  # TinyTeX ソフトウェアをインストールするための R コマンド

40.2 はじめに

rmarkdown R パッケージのインストール

rmarkdown R パッケージをインストールします。このハンドブックでは、パッケージを読み込むために、pacman パッケージの p_load() を主に使用しています。p_load() は、必要に応じてパッケージをインストールし、現在の R セッションで使用するためにパッケージを読み込む関数です。また、すでにインストールされたパッケージは、R の基本パッケージである base （以下、base R）の library() を使用して読み込むこともできます。R のパッケージに関する詳細は R basics の章をご覧ください。

pacman::p_load(rmarkdown)

新規 Rmd ファイルの作成

RStudio 内で新規の R markdown ファイルを開には、File を選択し、それから、New file を選択し、R markdown... を選択します。

R Studio は、あなたにどの出力を行うかを選択するオプションを提示します。Html 文書をここでは作りたいので、下記の例では、“HTML” を選択しています。Title と Author は重要ではありません。希望する出力文書形式が選択肢の中になくても心配いりません。いずれかひとつの文書形式を選択した後、文書の中で変更することができます。

この操作で、新規の .Rmd スクリプトが開かれます。

知っておくべき重要事項

ワーキングディレクトリ

マークダウンファイルのワーキングディレクトリは、Rmd ファイル自身が保存された場所になります。例えば、もし R プロジェクトが ~/Docuents/projectX 内にあり、Rmd ファイル自体がサブフォルダ ~/Documents/projectX/markdownfiles/markdown.Rmd にある場合、マークダウン内に記載されたコード read.csv("data.csv") は、プロジェクトに含まれるスクリプトが通常自動的に検索するプロジェクトのルートフォルダではなく、markdownfiles フォルダ内の csv ファイルを検索します。

他の場所のファイルを参照するには、絶対ファイルパス、あるいは、here パッケージのいずれかを使用する必要があるでしょう。here パッケージは、ワーキングディレクトリを R プロジェクトのルートフォルダに設定します。詳細は、このハンドブックのR プロジェクトの設定 および データのインポート・エクスポート の章で説明されています。例えば、projectX フォルダ内にある “data.csv” というファイルをインポートするためのコードは、import(here("data.csv")) となります。

注意、R markdown スクリプト内で setwd() を使用することは推奨されません。このコマンドは、これが書かれたコードチャンク内にのみ適用されます。

共有フォルダ上とローカルコンピュータ上での作業について

共有ネットワークドライブ上で実行するとき、R Markdown は pandoc の問題とぶつかるので、作業フォルダを自身のローカルコンピュータ上のフォルダにすることが推奨されます。例えば、’ My Documents’ 内のプロジェクトなど。もし、Git を使用している（非常におすすめです！）場合、ローカルコンピュータ上で作業することに慣れていると思います。より詳細は、このハンドブックの ネットワークドライブで R を使用する場合 および エラーとヘルプ の章をご覧ください。

40.3 R Markdown を形作る部品

R Markdown 文書は通常の R スクリプトと同じように RStudio 内で編集可能です。新規 R Markdown スクリプトを開いたとき、RStudio は R Markdown スクリプトの様々なセクションを説明するテンプレートを表示することで手助けしようとします。

下記は、html 出力を生成することを目的とした新しい Rmd スクリプトを始めたときに表示される内容です。（前節で説明した通り）

ご覧の通り、Rmd ファイル内には３つの基本コンポーネントがあります：YAML、Markdown テキスト、そして、R コードチャンクです。

これらが生成され、文書の出力になります。下記の図をご覧ください：

YAML メタデータ

「YAML メタデータ」 あるいは単に ‘YAML’ と呼ばれる情報は、R Markdown 文書の冒頭にあります。スクリプトのこのセクションでは、Rmd ファイルに生成する出力の種類、書式設定、および文書の表題、作成者、日付などのメタデータを設定します。ここで言及しきれない他の用途があります。（「出力の生成」 で説明されます）。インデントが重要であることに注意してください。タブは利用できませんが、スペースが使用可能です。

このセクションは、ダッシュ３つ --- のみの行で開始する必要があります。そして、ダッシュ３つ --- のみの行で閉じねばなりません。YAML パラメタは、key:value のペアで設定されます。YAML でのコロンの場所は重要です。key:value ペアは、コロンで区切られます（等号記号ではありません！）。

YAML は文書のメタデータで開始される必要があります。これら、 YAML パラメタ（インデントされていない）の順序は重要ではありません。例えば次のような形です：

title: "My document"
author: "Me"
date: "2024-09-18"

YAML 値の中で R コードを使用するには、インラインコード（バックティック内に r が前置されます）としてだけてなく、引用符内の記述（上記の記述例中の data: 箇所をご覧ください）として記述します。

上記の画像内では、デフォルトの出力が html ファイルになるように選択したため、YAML 中に output: html_document と記述されています。しかしながら、この記述を powerpoint_presentation、word_document や pdf_document にも変更できます。

テキスト

このセクションは、題名と見出しを含めた文書の本文です。この本文は、多くの他のソフトウェアで使用されている “markdown” 言語で記述されています。

下記に本文を記入する核となる方法を記載します。より広範な文書は、RStudio ウェブサイト上の R Markdown “cheatsheet” をご覧ください。

新規行の挿入

R Markdown の特徴として、新しい行を始めるためには、半角スペース２つ を前の行末に入力し、Enter/Return キーを押す必要があります。

強調

本文を下記の記号で囲むことで出力の表示方法を変更します。

• アンダースコアで囲む（_text_）あるいは、１つのアスタリスクで囲む（*text*）ことで イタリック体 になります
• アスタリスク 2 個で囲む（**text**）ことで、ボールド体 になります。
• バックティックで囲む（text）ことで文書をコード片として表示します。

フォントの実際の見た目は特定のテンプレートを使用して設定できます（YAML メタデータの中で指定します。タブの例を参照してください）。

文字色

R Markdown に文字色を変えるためのシンプルな仕組みはありません。回避策の一つとして、もし出力が HTML 文書であれば、markdown テキストに HTML 行を挿入します。下記の HTML コードは、行内のテキストを、ボールド体で赤色に表示します。

<span style="color: red;">**_DANGER:_** This is a warning.</span>  

DANGER: This is a warning.

題名と見出し

R Markdown スクリプト内における本文中のハッシュ記号は、見出しを生成します。これは R コードチャンク内の通常の R スクリプトのコメント / 注釈 / 評価を外すためのハッシュ記号とは違います。

新規行の行頭に、異なる数のハッシュ記号を置くことで、異なるレベルの見出しが生成できます。ハッシュ記号 1 個は、題名や主題となる見出しとなります。ハッシュ記号 2 個は、第２レベルの見出しになります。第３レベル、第４レベルの見出しは、ハッシュ記号を連続で追加することによって生成されます。

# 第１レベルの見出し・題名

## 第２レベルの見出し

### 第３レベルの見出し

箇条書きと番号付き箇条書き

箇条書きを作成するには、アスタリスク（*）を使用します。前段を書き終えたあと、半角スペースを 2 個入力し、Enter/Return キーを 2 回入力します。それから、箇条書きを開始します。アスタリスクと、箇条書きの本文の間に半角スペース 1 個を入力します。各箇条書きの本文を入力し終わるたびに、半角スペース 2 個を入力し、Enter/Return キーを入力します。インデントを加えることで、入れ子の箇条書きが同じように機能します。番号付きの箇条書きも同じように入力しますが、アスタリスクの代わりに、1), 2) などのように入力します。下記は R Markdown スクリプトがどのように見えるかを示しています。

Here are my bullets (there are two spaces after this colon):  

* Bullet 1 (followed by two spaces and Enter/Return)  
* Bullet 2 (followed by two spaces and Enter/Return)  
  * Sub-bullet 1 (followed by two spaces and Enter/Return)  
  * Sub-bullet 2 (followed by two spaces and Enter/Return)  
  

テキストのコメントアウト

“#” を使用して R チャンク内の R コード行をコメントアウトできるように、R Markdown テキストを「コメントアウト」できます。テキストを選択状態にして、Ctrl+Shift+c（Mac の場合は Cmd+Shift+c）を押すだけです。テキストは矢印で囲まれ、文字色が緑に変わります。出力には現れません。

コードチャンク

R コード実行のためのスクリプトのセクションは、「チャンク」と呼ばれます。パッケージをロードしたり、データをインポートしたり、実際のデータ管理と、視覚化を、ここで実行できます。多くのコードチャンクを利用することで、Rコードを部分的に文章によって分けて管理すると便利に使えるでしょう。注意：これらの「チャンク」は文書の本文部分とは若干異なる背景色に見えます。

各チャンクは、バックティック 3 個で始まる行と、チャンクのパラメタを含む中カッコ（{ }）で開始されます。チャンクは、更にバックティック 3 個で終了します。

新しいチャンクを作成するには、自分で入力するか、キーボード・ショートカット、“Ctrl + Alt + i”（Mac では Cmd + Shift + r）を使用するか、スクリプトエディタの上辺にある緑色の ‘insert a new code chunk’ アイコンをクリックします。

中カッコ { } の内容に関する注意事項：

• チャンク内の言語名が R であることを示すため ’ r’ で開始されます
• r のあとに続いて、オプションでチャンクの「名前」を記入することができます。必須ではありませんが、作業を整理するために役立ちます。チャンクに名前をつける場合、常に一意の名前をつける必要があります。そうしない場合、レンダリング時に R からエラーが通知されます
• 中カッコは他に、tag=value と書かれたオプションをつけることが可能です。例えば：
  • eval = FALSE は、R コードを実行しません
  • echo = FALSE は、チャンク内の R ソースコードを出力文書に含めません
  • warning = FALSE は、R コードが生成する警告文を出力しません
  • message = FALSE は、R コードが生成するいかなるメッセージも出力しません
  • include = チャンクの出力（例、プロット）を文書に含めるかどうかを TRUE/FALSE で指定します
  • out.width = と out.height = はスタイルを設定します out.width = "75%"
  • fig.align = "center" は、図がページ全体を通してどのように配置されるかを調整します
  • fig.show='hold' は、チャンクが複数の図を出力し、それらを並べて出力したい場合、次のオプションとペアで使用します（out.width = c("33%", "67%")）。図をそれを生成するコードの下に表示するfig.show='asis' とともに設定可能です。'hide' を指定することで非表示にし、'animate' と指定することで複数の図を一つのアニメーションにします。
• チャンクヘッダは一行で記述されなければいけません
• ピリオド、アンダースコア、半角スペースを使わないようにしてください。セパレータが必要な場合は、ハイフン（ - ）を使用してください

knitr オプションについて詳しくは、こちらをご覧ください。

上記のオプションの一部は、チャンクの右上にある設定ボタンを使用してマウス操作で設定できます。この設定ボタンでは、チャンクのどの部分をレンダリングされた文書に含めるか、つまり、コード、出力、警告文を指定できます。この指定は、中カッコに記述済みの設定として表示されます。例えば、’ Show output only’ を指定した場合、echo=FALSE が中カッコに記述されます。

また、チャンクの右上には、 2 個の矢印があり、チャンク内のコード、または、現在のチャンク以前のチャンク内のコードを実行するのに役立ちます。これらのアイコンにカーソルを合わせると、何を実行するかがわかります。

スクリプト内のすべてのチャンクにグローバルオプションを設定するには、スクリプト内の一番最初の R コードチャンクで設定できます。例えば、コード自体ではなく、各コードのチャンクの出力のみが表示されるように、次のコマンドを R コードチャンクに含めることが可能です：

knitr::opts_chunk$set(echo = FALSE) 

テキスト内 R コード

バックティック内に最小限の R コードを含めることもできます。バックティック内で、コードを “r” と半角スペースで開始します。これにより、RStudio はこのコードを、R コードとして評価します。下記の例を参照してください。

下記の例は、複数の見出しレベルと箇条書きを表示していて、現在の日付を返す R コード（Sys.Date()）を使用して出力された日付を評価しています。

上記の例は、単純（現在の日付を表示する）ですが、同じシンタクスを使用して、より複雑な R コードによって生成された値を表示することができます（例、列の最小値、中央値、最大値を計算する）。スクリプト内のこれ以前の R コードチャンクで生成された R オブジェクトや、値を統合することができます。

例として、下記のスクリプトは、tidyverse 関数を用いて、18 歳未満のケース割合を計算し、オブジェクト less18、total、less18prop を生成します。この動的な値は、後続のテキストに挿入されます。word 文書に組み込んだ場合どのように見えるかを確認しましょう。

画像

次の２つの方法のうちいずれかで R Markdown に画像を埋め込むことができます：

![]("path/to/image.png")  

もし上記の方法がうまく行かなかったら、knitr::include_graphics() を試してください。

knitr::include_graphics("path/to/image.png")

（ファイルパスは、here パッケージを使用して記述できることを覚えていますか？）

knitr::include_graphics(here::here("path", "to", "image.png"))

表

ハイフン（ - ）とバー（ | ）を使用して、表を組みます。バーの前やバー間のハイフンの数で、セル内のテキストが折り返されるまでの空白の数が設定されます。

Column 1 |Column  2 |Column 3
---------|----------|--------
Cell A   |Cell B    |Cell C
Cell D   |Cell E    |Cell F

上記のコードは下記の表を生成します：

Column 1	Column 2	Column 3
Cell A	Cell B	Cell C
Cell D	Cell E	Cell F

タブ分けされたセクション

HTML 出力の場合、セクションを「タブ」に分けることができます。.tabset を見出し直後の中カッコ { } 中に設定するだけです。この設定をした見出しより下位の見出しは（同じレベルに他の見出しが現れるまで）ユーザがクリック可能なタブとして表示されるでしょう。より詳しくは、こちらをご覧ください。

.tabset のあとに、タブに、「積み重ねられた」見た目を付与する追加のオプションである .tabset-pills を追加できます。タブを含む HTML 出力を表示中に、 Ctrl+f 検索は、非表示のタブではなく、「アクティブ」 なタブのみを検索することに注意してください。

40.4 ファイル構造

R Markdown と関連する R スクリプトを構造化するいくつかの方法があります。各方法は、利点と欠点があります：

• 自己内包型 R Markdown - レポートに必要な全ては、R Markdown にインポートもしくは生成されます
  • 他のファイルを取り込む - 外部 R スクリプトを source() コマンドで実行することができ、その出力を Rmd 内で利用できます
  • 子スクリプト - source() のもう一つの方法
• 「runfile」 の活用 - R Markdown にレンダリングする前に、R スクリプト内のコマンドを実行します

自己内包型 Rmd

比較的単純なレポートの場合、R Markdown スクリプトを「自己内包」として、外部スクリプトを含まないように構成することを選択できます。

コードチャンクや、パッケージの読み込みなど、R markdown を実行するために必要なものを全て、Rmd ファイルにインポートあるいは生成して含めます。「自己内包型」アプローチは、多くのデータ処理を行う必要がなく（例えば、クリーンなあるいは、セミクリーンなデータを取り込むとき）、R Markdown をレンダリングするために多くの時間を必要としない場合に適しています。

このシナリオの場合、R Markdown スクリプトの論理的な構成は下記のようになります：

1. グローバルな knitr オプションを設定します
2. パッケージを読み込みます
3. データをインポートします
4. データを処理します
5. 出力を生成します（表、プロットなど）
6. 該当する場合は、出力を保存します（.csv, .png など）

他のファイルを取り込む

「自己内包型」 アプローチのひとつのバリエーションは、R Markdown コードチャンクに他の R スクリプトを “source”（実行）させることです。この方法により R Markdown スクリプトが整理、単純化され、管理しやすくなります。この方法は、レポートの冒頭に、最終的な数値を表示させたいときにも役立ちます。このアプローチでは、最終的な R Markdown スクリプトは、前処理された出力を文書へ組み込むだけです。

このアプローチの一つの方法は、R スクリプト（ファイルパスと拡張子を含むファイル名）を base R コマンドの source() に渡すことです。

source("your-script.R", local = knitr::knit_global())
# or sys.source("your-script.R", envir = knitr::knit_global())

R Markdown 内で source() を使用する場合、外部ファイルは Rmd ファイルがレンダリングされる過程で実行されることに注意してください。そのため、各スクリプトは、レポートをレンダリングするたびに実行されます。ゆえに、これらの source() コマンドを R Markdown 内に記述しても実行時間を短縮することはなく、R Markdown の生成時に出力されたエラーが引き続き出力されるため、デバッグを大幅に支援することもありません。

もう一つの方法は、knitr オプションの child = を活用することです。

様々な R 環境に注意する必要があります。環境内で生成されたオブジェクトは、R Markdown で使用される環境で必ずしも利用可能とは限りません。

Runfile

このアプローチは、render() コマンドを含む R スクリプトを利用し、R Markdown に渡すオブジェクトを前処理します。

例えば、render() を実行する前に、パッケージを読み込んだり、データを読み込みクリーニングにしたり、目的のグラフを生成したりすることさえできます。これらのステップは、R スクリプト、または source() で取り込まれる他のスクリプトで行う必要がある可能性があります。これらのコマンドが同じ RStudio セッションで生成され、オブジェクトが環境に保存されている限り、オブジェクトを Rmd 内で呼び出すことが可能です。そのため、R markdown それ自身は、事前に作成されたオブジェクトを出力に含める、最終行程のためだけに利用されることとなります。この方法は、もし何か誤りがあるときにデバッグがはるかに容易です。

この方法は、下記の理由で便利です：

• より多くの情報を含むエラーメッセージ - エラーメッセージが、 R Markdown ではなく R スクリプトから生成されます。R Markdown ではどのチャンクにエラーがあるか表示されるだけで、どの行であるかは知らせてくれません。
• 該当する場合は、render() コマンドの前に長い処理を実行できます。- この処理は、１回だけしか実行されません。

下記は、分割された R スクリプトの例です。前処理した data オブジェクトを現在の R 環境に取り込み、render() を使用して、“create_output.Rmd” をレンダリングしています。

data <- import("datafile.csv") %>%       # データを読み込み、環境に保存する
  select(age, hospital, weight)          # 限定された列を選択する

rmarkdown::render(input = "create_output.Rmd")   # Rmd ファイルを生成する

フォルダ構成

ワークフローは、作成された文書や図用の ‘output’ フォルダや、クリーンになったデータ用の ‘data’ や ‘inputs’ フォルダなど、全体的なフォルダ構造にも関与します。ここではこれ以上詳細に言及しませんが、定期レポート作成の効率化の章をご覧ください。

40.5 文書の生成

下記の方法で、文書を生成できます：

• RStudio のスクリプトエディタの上辺にある “Knit” ボタンを手動で押す（素早く、簡単です）
• render() コマンドを実行する（R Markdown スクリプトの外部で実行される）

選択肢 1： “Knit” ボタン

Rmd ファイルを開いたら、ファイルの上辺にある ‘Knit’ アイコン（ボタン）を押します。

R Studio は R コンソールの近くにある ’ R Markdown’ タブに進行状況を表示します。処理が完了すると、文書は自動的に開かれます。

文書は、R markdown スクリプトと同じフォルダに、同じ名前で保存されます（拡張子を除く）。この保存方法は、明らかにバージョン管理には理想的ではありません（文書は、手動でファイルを移動させない限り、knit するたびに上書きされます）。ファイルの名前を自分で変更する必要があるでしょう（例、日付を追加する）。

このボタンは、rmarkdown の render() 関数への RStudio のショートカットボタンです。この方法が有効なのは、必要なコンポーネントが存在する、あるいはファイル内で必要なものをソースしている自己内包型のR markdown のみです。

選択肢 2： render() コマンド

R Markdown 出力を生成する別の方法は、（rmarkdown パッケージの）render() 関数を実行することです。このコマンドは、R Markdown スクリプトの外で実行する必要があります。つまり、分割された R スクリプト（“run file” と呼ばれることが多い）で実行するか、R コンソールでスタンドアロンコマンドとして実行する必要があります。

rmarkdown::render(input = "my_report.Rmd")

“knit” と同じように、デフォルト設定では、Rmd 出力は、Rmd スクリプトと同じフォルダに、同じ名前で保存されます（ファイル拡張子を除いて）。例えば、“my_report.Rmd” が knit されると、word 文書に knit する場合 “my_report.docx” が生成されます。render() を使用すると、さまざまなオプションから設定を利用することができます。render() には、次の引数を与えることができます：

• output_format = このオプションは、出力形式を変換します（例えば、"html_document", "pdf_document", "word_document", や "all"）。このオプションを、R Markdown スクリプト内の YAML で指定することも可能です。
• output_file = このオプションは、出力ファイル（とファイルパス）の名前を指定します。以下に示すように、here() や str_glue() などの R 関数を介して生成することが可能です。
• output_dir = このオプションは、ファイルを保存するディレクトリ（フォルダ）を指定します。Rmd ファイルが保存されているディレクトリ以外の代替を指定可能です。
• output_options = スクリプト内の YAML を上書きするオプションのリストを引数として渡せます。
• output_yaml = YAML 設定を含む .yml ファイルへのファイルパスを引数として渡せます。
• params = 下記のパラメタセクションをご覧ください。
• 完全な引数のリストはこちらです。

一例として、バージョン管理を改善するために、下記のコマンドは、ファイル名に現在の日付を付加し、‘outputs’ サブフォルダ内に出力ファイルを保存します。ファイル名を生成するために、stringr パッケージの str_glue() 関数を使用して、（平文で書かれた）静的文字列と（中カッコ内に書かれた）動的 R スクリプトを 「接着」 します。例えば、2021 年 4 月 10 日の場合、下記のファイル名は、 “Report_2021-04-10.docx” となるでしょう。str_glue() についての詳細は、文字型・文字列型データ の章をご覧ください。

rmarkdown::render(
  input = "create_output.Rmd",
  output_file = stringr::str_glue("outputs/Report_{Sys.Date()}.docx")) 

ファイルがレンダリングされると、RStudio コンソールに 100% の進行表示が現れ、レンダリングが完了したことを示す終了メッセージが表示されます。

選択肢 3： reportfactory パッケージ

R パッケージの reportfactory は、レポートを定期的に実行するシナリオ（例、日毎、週毎…）に対応する R Markdown レポートを整理及び、コンパイルするための代替の方法を提供します。このパッケージにより複数の R Markdown ファイルのコンパイルと、それらの出力の管理が容易になります。一言でいうと、このパッケージは、R Markdown レポートを実行し、日付、時刻が自動的に挿入された出力のためのフォルダを生成し、“light” バージョン管理を行うことができる “factory” を提供します。

このワークフローについてより詳しくは、定期レポート作成の効率化 の章をご覧ください。

40.6 パラメタ化されたレポート

レポートを動的にするためにパラメタ化を使用することができます。これにより、特定の設定（例、特定の日付や、場所、特定の knit オプション）でレポートを実行可能です。下記では、基本的な部分を解説します。パラメタ化されたレポートについての詳細はオンラインにあります。

例として、エボラ出血熱の流行をシミュレートした症例ラインリストを使用します。各病院の標準的なサーベイランスレポートを毎日実行するとします。パラメタを使用してどのように実行するかを示します。

重要：動的レポートは、フォルダ内の R スクリプト内の単純な R オブジェクトを使用して正式なパラメタ構造（params: なし）を取らずに構築することも可能です。このことは、このセクションの最後で説明します。

パラメタの設定

R Markdown 出力をパラメタ値を指定するためのいくつかの選択肢があります。

選択肢 1：YAML 内にパラメタを設定する

YAML に params: オプションを含むように編集します。定義したいパラメタごとにステートメントをインデントします。下記の例では、特定の値をもたせたパラメタ data と hospital を生成しています。これらの値は、レポートが実行されるたびに変更の対象になります。出力を生成するために “Knit” ボタンを使用する場合、パラメタは YAML で設定したデフォルト値になります。同じように、render() を使用した場合、render() コマンドで特に値を指定しない限り、パラメタは、YAML で設定したデフォルト値になります。

---
title: Surveillance report
output: html_document
params:
 date: 2021-04-10
 hospital: Central Hospital
---

バックグラウンドでは、上記のパラメタ値は、params と呼ばれる読み込み専用のリストに含まれています。それゆえ、環境内の他の R オブジェクト・値と同じように R コード内にパラメタ値を埋め込むことができます。params$ に続けてパラメタ名を入力するだけです。例えば、病院名を表す params$hospital（デフォルトでは、“Central Hospital” となります）。

パラメタ値は、true や false という値を保持できるため、R チャンクの knitr オプションに埋め込むこともできることに注意してください。例えば、{r, eval=FALSE} の代わりに {r, eval=params$run} を設定できます。チャンクが事項されるかどうかは、run: パラメタの値によって異なります。

日付のパラメタの場合、文字列として埋め込まれることに注意してください。つまり、params$date を R コードとして解釈させる場合は、as.Date() やその他の似た関数に渡して日付型（Date）に変換する必要があります。

選択肢 2： render() 内にパラメタを設定する

前述のように、“Knit” ボタンを押して出力を生成する代わりに、分割したスクリプトから render() 関数を実行することも可能です。後者の場合、そのレンダリングで使用されるパラメタを render() の引数である params = で指定できます。

ここで指定されるパラメタ値は、YAML 内にデフォルト値が記述されていた場合上書きすることに注意してください。この場合、値は character/string 値として定義されるべきなので、引用符で囲んで記述します。

下記のコマンドは、“surveillance_report.Rmd” をレンダリングし、動的に出力ファイル名とフォルダを指定し、そして、２つのパラメタのリストとしてその値とともに params = 引数へ渡します。

rmarkdown::render(
  input = "surveillance_report.Rmd",  
  output_file = stringr::str_glue("outputs/Report_{Sys.Date()}.docx"),
  params = list(date = "2021-04-10", hospital  = "Central Hospital"))

選択肢 3： グラフィカルユーザーインタフェースを使用してパラメタを設定する

よりインタラクティブに操作するために、グラフィカルユーザーインタフェース（GUI: Graphical User Interface）を使用してパラメタの値を手動で選択することもできます。この操作を行うには ‘Knit’ ボタンの隣りにあるドロップダウンメニューをクリックし、‘Knit with parameters’ を選択します。

ポップアップが表示され、文書の YAML で設定したパラメタ値を変更できます。

下記のデモのように、params = "ask" を指定することで render() コマンドを通して同じ操作を実現できます。

rmarkdown::render(
  input = "surveillance_report.Rmd",  
  output_file = stringr::str_glue("outputs/Report_{Sys.Date()}.docx"),
  params = “ask”)

しかしながら、ポップアップウィンドウに値を手入力することは、エラーやスペルミスの影響を受けます。ドロップダウンメニューを利用して、入力できる値に制限を追加することをお勧めします。この操作を行うには、YAML 内の各 params: 項目にいくつかの指定を追加します。

• label: その特定のドロップダウンメニューのタイトル
• value: デフォルト値（開始時の値）
• input: ドロップダウンメニューへ select を設定
• choices: ドロップダウンメニュー内で select の選択肢となる値を指定

下記では、hospital パラメタにこれらの項目を記述しています。

---
title: Surveillance report
output: html_document
params:
 date: 2021-04-10
 hospital: 
  label: “Town:”
  value: Central Hospital
  input: select
  choices: [Central Hospital, Military Hospital, Port Hospital, St. Mark's Maternity Hospital (SMMH)]
---

上記の設定で knit する（‘knit with parameters’ ボタンもしくは、 render() のいずれかを使用する）場合、ポップアップウィンドウにドロップダウンオプションが表示され、そこから選択することができます。

パラメタ化の例

下記のコードは、R Markdown 内で各々 params$date と params$hospital として利用されている date と hospital パラメタを生成します。

レポート出力結果内で、データが特定の病院名でどのようにフィルタされているかを確認します。グラフのタイトルは、正しい病院名と日付を示しています。ここでは、“linelist_cleaned.rds” ファイルを使用しますが、もしラインリストファイル自身にも、パラメタライズされた日付順に並ぶ日付スタンプが含まれている場合に、この方法は特に有効です。

デフォルトのフォントとレイアウトで knit した場合の最終出力は下記です。

params を用いないパラメタ化

分割した別のスクリプトから render() で R Markdown をレンダリングする場合は、params: 機能を使わずにパラメタ化の結果を出力できます。

例えば、render() コマンドを含んだ R スクリプト内で render() コマンドより前に、2 つの R オブジェクト（値）として hospital と date を定義するだけです。R Markdown において、YAML 内に params: セクションは必ずしも必要ではありません。また、params$date ではなく、date オブジェクトとして、params$hospital ではなく、hospital オブジェクトとして参照します。

# R Markdown とは分割された R スクリプトファイル

# R オブジェクトの定義
hospital <- "Central Hospital"
date <- "2021-04-10"

# R markdown のレンダリング
rmarkdown::render(input = "create_output.Rmd") 

このアプローチを実行する場合、“knit with parameters” や、GUI の使用、knit オプションをパラメタに含めるなどができないことを意味します。しかしながら、コードが単純になるため、メリットとなる場合があります。

40.7 レポート生成を繰り返し実行する

各管轄区 / ユニットのレポートを生成するために、入力パラメタを変更して、レポート生成を複数回実行したい場合があります。これは、ループと反復処理・リストの操作 の章で詳細が説明されているイテレーション用のツールを用いることで実行できます。オプションには、purrr パッケージや、下記で説明する for loop の使用が含まれます。

下記では、単純な for ループを用いて、関心のあるすべての病院のサーベイランスレポートを生成します。これは、（hospital パラメタを一つ一つ手動で変更する代わりに）1 つのコマンドで実行されます。レポートをレンダリングするコマンドは、レポート用 Rmd ファイル外に存在する必要があります。このスクリプトには、「ループ処理（loop through）」 するための定義済みオブジェクト - 今日の日付と病院名のベクタも含まれます。

hospitals <- c("Central Hospital",
                "Military Hospital", 
                "Port Hospital",
                "St. Mark's Maternity Hospital (SMMH)") 

次に、ループを使用して、これらの値を render() コマンドへ渡します。このループは、hospitals ベクタの各値ごとに一度コマンドを実行します。文字 i は、現在のイテレーションで使用されている病院のインデクス位置（1 から 4）を表し、hospital_list[1] は ” Central Hospital” になります。この情報は、 render() コマンドの 2 つの位置で使用されます：

1. ファイル名に使用。2021 年 4 月 10 日に生成された場合、最初のイテレーション時のファイル名が “Report_Central Hospital_2021-04-10.docx” になり、作業ディレクトリの ‘output’ サブフォルダに保存される
2. params = に使用。 params$hospital の値が呼び出されるたびに Rmd が内部で病院名を使用するようにする。この例では、各病院で 1 つずつ、合計 4 つのファイルが生成される

for(i in 1:length(hospitals)){
  rmarkdown::render(
    input = "surveillance_report.Rmd",
    output_file = str_glue("output/Report_{hospitals[i]}_{Sys.Date()}.docx"),
    params = list(hospital  = hospitals[i]))
}       

40.8 テンプレート

必要なフォーマットを含むテンプレート文書を使用することで、Rmd 出力の視覚的な外観を調整できます。例えば、必要な寸法、透かし、背景やフォントを含むページ ・スライドを持つ MS Word や Powerpoint ファイルを生成できます。

Word 文書

テンプレートを作成するには、新規 word 文書を開始（または、適切なフォーマットを持つ既存の出力を使用）して、スタイルを定義しフォントを編集します。スタイルにおいて、見出し 1, 2, 3 は個々の markdown 見出しレベルを示します（それぞれ # Header 1, ## Header 2 そして ### Header 3）。スタイルのメニュー上で右クリックし、「変更」 をクリックして、フォントの書式と段落を変更します（例えば、特定のスタイルの前にページ分割を挿入すると、間隔を空けることに役立ちます）。余白、ページサイズ、ヘッダーなどの word 文書の他の要素は、直接作業している通常の word 文書のように変更できます。

Powerpoint 文書

上記と同じように、新しいスライドを生成するか、適切なフォーマットを持つ既存の powerpoint ファイルを使用します。編集するには、「表示」、「スライドマスター」 をクリックします。この編集画面から、テキストボックスのテキストフォーマットと背景・ページのサイズを編集して、「マスター」 スライドの外観を変更できます。

残念ながら、powerpoint ファイルの編集は、やや柔軟性にかけます：

• 第一レベルの見出し（# Header 1）は自動的に新規スライドのタイトルになります
• ## Header 2 テキストはサブタイトルとして表示されませんが、スライドのメインテキストボックスにテキストとして表示されます（スライドマスタで編集する方法を見つけない限りは）
• 出力されたプロットと表は、自動的に新規スライドに表示されます。それらを組み合わせる場合、例として、ggplot を組み合わせるための patchwork 関数を使用して、同一のページに表示されるようにします。多数の画像を一つのスライドに組み合わせるために patchwork パッケージを使う方法は、このブログ記事をご覧ください

powerpoint プレゼンテーションでより深いレベルで機能するツールについては、officer パッケージをご覧ください。

YAML にテンプレートを統合する

テンプレートが準備されたら、Rmd 内 YAML の ‘output’ 行の下、かつ、文書タイプが指定されている行の下に、その詳細を追加できます（分割された行として）。reference_doc は powerpoint のスライドテンプレートに使用できることに注意してください。

テンプレートは、Rmd ファイルが保存されているのと同じフォルダ、もしくは、そのサブフォルダに保存するのが最も簡便です。

---
title: Surveillance report
output: 
 word_document:
  reference_docx: "template.docx"
params:
 date: 2021-04-10
 hospital: Central Hospital
template:
 
---

HTML ファイルのフォーマット

HTML ファイルは、テンプレートを使用しませんが、YAML 内でスタイルを設定できます。HTML はインタラクティブな文書であり、特に柔軟性があります。ここでは、いくつかの基本的なオプションについて説明します。

• 目次：下記の例のように toc: true オプションで目次を追加できます。さらに、toc_float: true オプションを使用することで、スクロールに合わせて、画面に表示される（フロート、“floats”）ように指定できます。

• テーマ：Bootswatch テーマライブラリからのいくつかの既成のテーマを参照可能です。下記の例では、cerulean テーマを使用しています。他には以下のオプションがあります：journal, flatly, darkly, readable, spacelab, united, cosmo, lumen, paper, sandstone, simplex, と yeti。

• ハイライト：このオプションを設定すると、ハイライトされたテキストの外観を変更できます（例、下記ではチャンク内のコード）。サポートされているスタイルは以下のものがあります、デフォルト、tango, pygments, kate, monochrome, espresso, zenburn, haddock, breezedark, や textmate。

上記のオプションを YAML に統合する方法の例を次に示します。

---
title: "HTML example"
output:
  html_document:
    toc: true
    toc_float: true
    theme: cerulean
    highlight: kate
    
---

以下は、フロートした目次があり、それぞれ異なるテーマとハイライトスタイルが選択されている HTML 出力の 2 つの例です：

40.9 動的コンテンツ

HTML 出力では、動的な出力をレポートに含めることができます。下記に例を示します：

表

HTML レポートでは、フィルタとスクロールバーを付加して動的なコンテンツになるようにデータフレームやtibbles を出力できます。

このハンドブックで使用されている DT パッケージを用いて実現するには、次のようなコードチャンクを挿入します：

datatable() は、渡されたデータフレームを読者のために動的な表として出力します。rownames = FALSE を設定して、表の左端を単純化できます。filter = "top" は、各列にフィルタを付加します。option() 引数は、他の指定オプションを渡します。以下に 2 例を示します：pageLength = 5 は表示する行数を 5 行と指定します（残りの行は、矢印を用いてページング表示が可能です）。scrollX=TRUE は、表の最下段にスクロールバーを有効にします（列が右へ長く続く場合）。

もしデータセットが非常に大きい場合、head() をデータフレームに用いて、先頭 X 行のみ表示することを検討してください。

HTML ウィジェット

R のための HTML ウィジェットは、JavaScript ライブラリを利用してインタラクティブ性を向上させる R パッケージの特別な型です。HTML R Markdown 出力にこれらを埋め込み可能です。

これらのウィジェットの一般的な例は下記を含みます：

• Plotly （本章内や、動的な図の作成 の章で使用されています）
• visNetwork （このハンドブックの 感染連鎖の図式化 の章で使用されています）
• Leaflet （このハンドブックの GIS の基礎 の章で使用されています）
• dygraphs （時系列データのインタラクティブ表示に有用です）
• DT （datatable()）（フィルタ、ソート機能などを付加された動的な表の表示に使用されます）

plotly パッケージの ggplotly() 関数は特に簡単です。動的な図の作成 の章をご覧ください。

40.10 参考資料

さらに詳しく学びたい方は、以下のウェブサイトをご覧ください。

• https://bookdown.org/yihui/rmarkdown/
• https://rmarkdown.rstudio.com/articles_intro.html

markdown と knittr, Rmarkdown についての良質な資料はこちらです。 https://stackoverflow.com/questions/40563479/relationship-between-r-markdown-knitr-pandoc-and-bookdown