41 ルーチンで作成するレポートの整理
この章は、reportfactory パッケージについて解説します。このパッケージは R Markdown でレポートを作成する場合に補助的に利用するものとなります。
日次、週次などで、日常的にレポートを作成するような場合、reportfactory パッケージを利用すると複数の R Markdown ファイルを簡単に編集できたり、その出力結果を簡単に整理できたりします。手短にまとめると、このパッケージは R Markdown レポートを実行するための「ファクトリー」を用意してくれます。「ファクトリー」が、自動的に日付と時間が付加された出力用フォルダを作成してくれるので、「手軽に」バージョン管理を行えます。
reportfactory パッケージは RECON (R Epidemics Consortium) が開発したパッケージの 1 つです。RECON のウェブサイトと Github ページにパッケージの詳細があります。
41.1 準備
パッケージの読み込み
RStudio で、Github から最新版の reportfactory パッケージをインストールしましょう。
インストールは、pacman パッケージの p_load_curreng_gh() を利用します。この関数を利用すると Github からパッケージの最新バージョンを強制的にインストールします。 関数に、“reconverse/reportfactory” という文字を引数として与えましょう。“reconverse” は Github 上の “organization”（リポジトリの所有権を持つアカウント名）を表し、“reportfactory” がパッケージのリポジトリ名を表します。 別のインストール方法としては、remotes パッケージの install_github() も利用できます。
# Github からパッケージの最新版をインストールして読み込む
pacman::p_load_current_gh("reconverse/reportfactory")
#remotes::install_github("reconverse/reportfactory") # remotes パッケージを利用した別の方法はこちら41.2 新規ファクトリーの作成
new_factory() を実行して、新規ファクトリーを作りましょう。実行すると、必要なものが含まれた新規 R プロジェクトフォルダが作成されます。デフォルトでは以下の動作となります。
- 現在のワーキングフォルダに新規ファクトリー（new_factory フォルダ）が追加されます
- 新規ファクトリー（new_factory フォルダ）内に “new_factory.Rproj” として新規 R プロジェクトが作成されます
- RStudio のセッションは、“new_factory.Rproj” に「移動」し、新たなセッションが開かれます
# 以下のコマンドを実行すると現在の作業フォルダ配下に新規ファクトリー（new_factory フォルダ）が作成されます
new_factory()新規ファクトリー（new_facrtory フォルダ）の中には、自動的に以下のサブフォルダやファイルが作成されています。
- report_sources フォルダ：レポートを生成する R Markdown スクリプトを保存する場所です。
- outputs フォルダ：生成されたレポートが保存される場所です。（例：HTML、Word、PDF などのファイル）
-
scripts フォルダ：レポート作成時に呼び出される R スクリプトを保存する場所として利用できます。（例：R markdown スクリプトから呼び出されるスクリプトなど）
- data フォルダ：データを保存する場所として利用できます。（サブフォルダとして “raw” と “clean” フォルダが含まれています）
-
.here ファイル：here パッケージを使用して、サブフォルダ内のファイルを、
.hereファイルが置かれているフォルダをルートフォルダとして相対的なパスを指定できます（詳細は R プロジェクトの設定 の章を参照してください）。 - gitignore ファイル：このファクトリーの R プロジェクトを Github リポジトリと関連付けた場合に備えて作成されています。（詳細は、Git と Github を使用したバージョン管理と共同作業 の章を参照してください）。
- README ファイル（空）：Github リポジトリを利用した場合に備えて作成されています。
注意: “.here” ファイルなどのいくつかのドットで始まるファイルは、フォルダに存在していたとしてもコンピューターの設定によっては表示されない場合があります。
new_factory() コマンドのデフォルト設定のうち、実行時の動作を変更する引数をいくつか紹介します。
-
factory =： 新しく生成するファクトリーのフォルダ名を変更できます (デフォルトは “new_factory” です) -
path =：新規ファクトリーフォルダが作成されるパスを指定できます（デフォルトは現在の作業フォルダ） -
report_sources =：レポート生成用の R Markdown スクリプトを保存するサブフォルダの名前を指定できます（デフォルトは “report_sources”） -
outputs =：生成されたレポートを保存するフォルダの名前を指定できます（デフォルトは “outputs”）
全ての設定可能な引数リストは ?new_factory でヘルプファイルを参照してください。
新規ファクトリーを作成すると、R のセッションは新しく作成された R プロジェクトに移されるので、再度 reportfactory パッケージを読み込む必要があります。
pacman::p_load(reportfactory)これで準備が整いました。factory_overview() コマンドを実行すると、ファクトリーの構造（すべてのフォルダとファイル）を見ることができます。
factory_overview() # コンソールにファクトリーフォルダのツリー構造を表示する以下の図のように、ファクトリーに含まれるフォルダとファイルが R コンソールに表示されます。“data” フォルダの中に “raw” と “clean” サブフォルダと例示用の CSV データが含まれています。また、同じく例示用の “example_report.Rmd” ファイルが “report_sources” フォルダに含まれています。
41.3 レポートの作成
ファクトリー用 R プロジェクトの中で、普段行うように R Markdown ファイルを作成して、“report_sources” フォルダに保存してみましょう。 R Markdown ファイルの作成方法は、R Markdown で作るレポートの章を参照してください。例示のため、ここでは次のようにファクトリーを変更しています。
- “daily_sitrep.Rmd” というファイル名の新規 R Markdown スクリプトを “report_sources” フォルダ内に保存します。（翻訳者注：ここで、sitrepとは、状況報告などを意味する英単語。“situation report” の略）
- レポート用のデータ（“linelist_cleaned.rds”）は、“data” フォルダ内の “clean” サブフォルダに保存します。
factory_overview() を実行すると、R Markdown ファイルが “report_sources” フォルダに、レポート用のデータファイルが “clean” サブフォルダに格納されています（以下の画像でのハイライト部分）。
下記の画像は、R Markdown ファイル、“daily_sitrep.Rmd” の冒頭部分のスクリーンショットです。YAML ヘッダの output: html_document パラメータで、出力形式が HTML ファイルに設定されています。
この単純なスクリプトの中には以下のコマンドが記述されています。
- 必要なパッケージを読み込むコード
- here パッケージでファイルパスを指定して、“linelinst_cleaned.rds” データをインポートするコード（詳しくはデータのインポート・エクスポートの章を参照）
- 症例ラインリストの要約表を表示し、
export()で表を .csv ファイルとしてエクスポートするコード - 流行曲線（エピカーブ）を表示し、
ggsave()で .png ファイルとしてエクスポートするコード
次のコマンドで「report_sources」フォルダ内の R Markdown ファイルのリストを確認できます。
list_reports()41.4 コンパイル、レポートの生成
reportfactory パッケージにおいて、R Markdown ファイルを「コンパイル」するとは、R markdown スクリプトが実行され、出力結果が作成されるという意味となります。（出力結果は、YAML ヘッダに記載されている出力形式となります。例、 HTML、Word、PDF など）
ファクトリーは、“outputs” フォルダ内に、日付とタイムスタンプ付きの出力用フォルダを自動生成します。
出力レポート本体と、スクリプトからエクスポートされたファイル（csv、png、xlsx など）は、この自動生成されたフォルダに保存されます。さらに、R markdown スクリプトファイルそのものも、この自動生成されたフォルダに保存されます。そのため、スクリプトのバージョン履歴を管理できます。
コンパイルによる出力生成は、R Markdown ファイルにおける、Knit して作成される通常の出力生成とは明確に異なります。Knit した場合は R markdown スクリプトが存在するフォルダに出力が保存されます。結果的に、この Knit の出力動作はフォルダが乱雑で整理されていない状態になりやすいのです。ファクトリーの目的は、頻繁にレポートを出力する必要がある場合の出力結果の整理整頓です。
ファイル名を指定してコンパイル
特定のレポートをコンパイルするには、compile_reports() を実行し、reports = に R markdown スクリプト名（.Rmd 拡張子は含めない）を指定します。スクリプト名を指定する簡単な方法に、以下のように reports = を省略して、R Markdown スクリプト名を引用符（"や'）で囲んで書く方法もあります。
上記のコマンドは、“daily_sitrep.Rmd” レポートのみをコンパイルします。出力結果として HTML レポート、病院ごとの症例数の .csv、epicurve の .png 画像を、“outputs” フォルダ内のレポート専用のサブフォルダに保存します。また、保存フォルダ名にコマンド実行日付とタイムスタンプが付加されます。
なお、スクリプト名の指定時に .Rmd 拡張子をつけた場合は、ファイル拡張子を正確に入力する必要があります（.rmd と .Rmd は別ファイルとして扱われます）。
さらに、コンパイル時に “report_sources” フォルダにいくつかのファイルが一時的に表示されることがありますが、これらは最終出力時にあるべき “outputs” フォルダに転送されるため、すぐに消えるということに注意してください。
リストインデックスを指定してコンパイル
reports = に数字または数字ベクトルを指定することで、コンパイルする R markdown スクリプトを指定できます。これらの数字は list_reports() を実行した際に表示されるレポートリストのインデックスと一致している必要があります。
# "report_sources" フォルダ内の 2 番目と 4 番目の R markdown ファイルをコンパイルする
compile_reports(reports = c(2, 4))
サブフォルダ内のファイルをコンパイルする
レポートの目的ごとに “report_sources” フォルダに追加でサブフォルダを作成できます。サブフォルダ内の R markdown レポートをコンパイルするには、subfolder = 引数にサブフォルダ名を指定するだけです。下記は “report_sources” のサブフォルダ “for_partners” フォルダに存在する R markdown レポート（“summary_for_partners.Rmd”）をコンパイルするコード例です。
compile_reports(
reports = "summary_for_partners.Rmd",
subfolder = "for_partners")以下のようにサブフォルダ名を reports = 引数に指定し、最後にスラッシュ（ / ）を付けることで、サブフォルダ内の全ての R markdown レポートをコンパイルできます。
compile_reports(reports = "for_partners/")パラメータ化
R Markdown で作るレポート の章で述べたように、パラメータを指定してレポートを作成できます。 これらのパラメータは、引数 params = にリスト型としてまとめることで compile_reports() に渡すことができます。下記例の架空レポートでは、R Markdown スクリプトに 3 つのパラメータ（“most_recent_data”、“region”、“rates_denominator”）が指定されています。
compile_reports(
reports = "daily_sitrep.Rmd",
params = list(most_recent_data = TRUE,
region = "NORTHERN",
rates_denominator = 10000),
subfolder = "regional"
)41.5 出力結果
下記の画像は、何度かレポートをコンパイルした “outputs” フォルダの様子です（わかりやすくするためにハイライトを追加しています）。
- “outputs” フォルダ（緑でハイライト）の中には、“daily_sitrep”（青でハイライト）、“example_report”（黄でハイライト）、各 R markdown レポート出力用のサブフォルダが作成されています。
- 各レポート出力用サブフォルダの中に、コンパイルを実行する度にタイムスタンプ付きサブフォルダが作られます。
- これらのサブフォルダには、コンパイルを実行した日付と時間が記録されています (“2021-04-23_T11-07-36” は 2021 年 4 月 23 日 11 時 7 分 36 秒を表します)
- サブフォルダ名に付加される日付と時間のフォーマットは編集可能です。詳しくは
?compile_reportsを確認してください。
- これらのサブフォルダには、コンパイルを実行した日付と時間が記録されています (“2021-04-23_T11-07-36” は 2021 年 4 月 23 日 11 時 7 分 36 秒を表します)
- コンパイルで生成された各サブフォルダ内には、R markdown スクリプトの出力結果（ HTML 、PDF、Word など）と R markdown スクリプト（バージョン管理されています！）、その他のエクスポートされたファイル（table.csv、epidemic_curve.png など）が格納されます。
下記の画像は、“daily_sitrep” レポートの日付と時刻のタイムスタンプが付加されたフォルダの中身です。フォルダへのファイルパスは強調のために、黄色でハイライトしています。
最後に、以下のスクリーンショットに、HTML で出力されたレポートを示します。
出力の一覧を確認するには、list_outputs()を使用してください。
41.6 その他
Knit
必要であれば、“Knit” ボタンを押して、R Markdown レポートの 1 つを “Knit” できます。“Knit” した場合、デフォルトでは R markdown レポートが保存されている “report_sources” フォルダに出力されます。 以前のバージョンの reportfactory パッケージでは、“report_sources” に R markdown 以外のファイルがあるとコンパイルができませんでしたが、現在はそのようなことはありません。compile_reports() を実行してもエラーにはなりません。
scripts フォルダ
“scripts” フォルダには “runfiles”（実行ファイル）や R markdown スクリプトに読み込める .R スクリプトを格納することをお勧めします。複数のファイルにまたがるコードの構造化のためのヒントは、R Markdown で作るレポートの章をご覧ください。