/* terashim.com */

システム開発・データエンジニアリング・データ分析についての個人的なノート

{fusen} で RMarkdown からパッケージを生成

要約

  • fusen というパッケージを使うと RMarkdown ファイルからパッケージをビルドすることができます
  • ドキュメントを最初に書く "Rmd ファースト" なパッケージ開発スタイルが実現できます
  • 関数の定義・例・テスト・vignette が散在せずひとまとめに書けるので、保守性が高くなります
  • RMarkdown さえ書ければパッケージを作ることができるので、パッケージ開発のハードルが低くなります

RMarkdown からパッケージへ

R パッケージを開発する際、関数定義は R/ フォルダ、ユニットテストは tests/testthat/ フォルダ、vignette は vignettes/ フォルダなど、規則に沿った場所にソースを配置していく必要があります。

fusen を使えば、開発者は RMarkdown ファイルを書くだけでパッケージが開発できるようになります。 このとき RMarkdown の内容は例えば以下のようになります。

# ベクトルの中央値を計算する

```{r function}
#' 中央値の計算
#'
#' @param x 数値ベクトル
#' @inheritParams stats::median
#'
#' @return
#' ベクトル x の中央値
#' @export
#'
#' @examples
my_median <- function(x, na.rm = TRUE) {
  if (!is.numeric(x)) {stop("x は数値型である必要があります")}
  stats::median(x, na.rm = na.rm)
}
```

```{r examples}
my_median(1:12)
```

```{r tests}
test_that("my_median が正しく動作し、必要なときにはエラーが発生すること", {
  expect_true(my_median(1:12) == 6.5)
  expect_error(my_median("text"))
})
```

このように、コードチャンクに function, examples, tests など適切な名前を付けておくと、 後は fusen::inflate() 関数を実行すればパッケージのソースとして適切な場所にファイルが生成されます(下図参照)。

図: fusen によるパッケージ生成

図: fusen によるパッケージ生成

ちなみに fusen の名前は折り紙の「風船」に由来しています。 1つの RMarkdown ファイルからパッケージができる様子を、1枚の折り紙が立体的な箱にふくらむイメージになぞらえて名付けたそうです。

サンプルコードとドキュメントサイト

細かい fusen の使い方については、サンプルコード https://github.com/terashim/fusen.example で検証しました。また、そのパッケージのドキュメントサイトを https://terashim.github.io/fusen.example/ で公開しています。

具体的なパッケージ開発の進め方や注意点についてはこれらのサンプルをご覧ください。

"Rmd ファースト" な開発スタイル

パッケージを開発する際、ドキュメントを作ることは大切ですが後回しになりがちです。 これに対して fusen 作者の Sébastien Rochette 氏はかねてから "Rmd ファースト" な開発スタイルを提唱してきました。 この開発スタイルでは

  1. まず Rmd ファイルにやりたいことを書き出し、
  2. 次にそれを実現するための関数定義、テスト、例などをすべて同じ Rmd ファイルに書いていきます。
  3. そのまま Rmd 上で修正・実行しながら推敲していき、
  4. 最後にパッケージとして整える

という手順を踏みます。 こうすることで自然と開発中の考えがドキュメントとして残り、後から見た人が理解しやすくなるというわけです。 fusen はこの開発スタイルで Rmd ファイルをパッケージに変換するプロセスを自動で行うために作られたツールです。

関心事の近さとソースの近さ

fusen 流の開発スタイルでは、開発者にとっての関心事の近さとコードやドキュメントの近さが一致するようになります。 それによって、例えば関数を修正したとき、その関数についてのドキュメンテーションやテストコードも自然に見直すようになります。 こうした特徴は他の言語や開発ツールでもなかなか類を見ないのではないでしょうか。

パッケージ開発の入り口に

初めて R パッケージを開発する人にとって、fusen は間違いなく良い入り口になるはずです。

R パッケージ開発には固有の作法があり、自力ですべてを守りながら開発を進めるのは大変です。 そのため {usethis}{devtools} など便利な開発支援パッケージが存在しています。 しかし最初はそれを正しく使って開発していく作業フローを身につけるだけでも難しく感じるでしょう。

fusen なら RMarkdown ファイルを書くだけで良いので、パッケージ開発のハードルが大きく下がります。 これからパッケージ開発にチャレンジしたいという方にはぜひ使ってみていただきたいと思います。

参考資料