README.ja.md

pipeR

pipeR は、関数を連鎖的に適用する方法を、様々なスタイルで提供します：

• パイプ演算子
• パイプオブジェクト
• pipeline 関数

これらは、それぞれ異なる方法でパイプラインを実現していますが、機能としてほぼ同じものを提供します。ある値を次の演算にパイプするときに、

• 関数の最初の引数として渡す
• 表現式中のドット記号(.)として渡す
• モデル式(formula)によって定義された変数として渡す
• 入力を次へ持ち越しながら、副作用を起こす
• パイプラインの途中で生成された値を変数に代入(保存)する

といったことができます。

pipeR の文法は、パイプラインの読みやすさと、広く様々な演算との親和性を考えて設計されています。

pipeR の完全なガイドとしては、pipeR Tutorial を強くお勧めします。

インストール

最新の開発バージョンを GitHub からインストールするには：

devtools::install_github("renkun-ken/pipeR")

CRAN からインストールするには：

install.packages("pipeR")

はじめよう

次のコードは従来のアプローチで書かれたものです：

plot(density(sample(mtcars$mpg, size = 10000, replace = TRUE), 
  kernel = "gaussian"), col = "red", main="density of mpg (bootstrap)")

R の組み込みデータセットである mtcars の変数 mpg に対して、ブートストラップ法でリサンプリングし、ガウシアンカーネルを用いて推定した密度関数をプロットしています。

このコードは深くネストされているため、読むのもコードをメンテナンスするのも一苦労です。次のコードは、この従来のコードを、パイプ演算子、Pipe() 関数、pipeline() 関数で書き直したものです。

• 演算子によるパイプライン

mtcars$mpg %>>%
  sample(size = 10000, replace = TRUE) %>>%
  density(kernel = "gaussian") %>>%
  plot(col = "red", main = "density of mpg (bootstrap)")

• オブジェクトによるパイプライン(Pipe())

Pipe(mtcars$mpg)$
  sample(size = 10000, replace = TRUE)$
  density(kernel = "gaussian")$
  plot(col = "red", main = "density of mpg (bootstrap)")

• 引数によるパイプライン

pipeline(mtcars$mpg,
  sample(size = 10000, replace = TRUE),
  density(kernel = "gaussian"),
  plot(col = "red", main = "density of mpg (bootstrap)"))

• 表現式によるパイプライン

pipeline({
  mtcars$mpg
  sample(size = 10000, replace = TRUE)
  density(kernel = "gaussian")
  plot(col = "red", main = "density of mpg (bootstrap)")  
})

使い方

%>>%

パイプ演算子 %>>% は、基本的に、左辺の値を右辺の計算式に渡します。右辺の計算式は、その文法に従って評価されます。

関数の最初の引数として渡す

多くの R 関数は、データを最初の引数として受け取るため、パイプとの親和性が高いです。このような引数配置であれば、パイプにより操作の流れを作ることができます。つまり、一つのデータソースを関数の最初の引数として入力し、関数を適用し、次の関数の最初の引数として渡すことができます。このようなコマンドの連鎖をパイプラインと呼びます。

%>>% の右側が、関数名か関数呼び出しである場合、左側の値は常にその関数の最初の引数になります。

rnorm(100) %>>%
  plot

rnorm(100) %>>%
  plot(col="red")

左辺の値が複数の箇所で必要となる場合もあります。その場合、関数呼び出しの中で . を使うことで表現することができます。

rnorm(100) %>>%
  plot(col="red", main=length(.))

関数を名前空間を指定して呼び出す場合、関数の終わりには必ず () をつけて呼び出して下さい。

rnorm(100) %>>%
  stats::median()
  
rnorm(100) %>>%
  graphics::plot(col = "red")

表現式中の . にパイプする

R の全ての関数がパイプに適合するとは限りません。いくつかの関数は、データを最初の引数として受け取りません。そのような場合には、関数呼び出しを {} もしくは () で囲み、表現式にしてから . を使ってパイプするとよいでしょう。

mtcars %>>%
  { lm(mpg ~ cyl + wt, data = .) }

mtcars %>>%
  ( lm(mpg ~ cyl + wt, data = .) )

モデル式(formula)を用いたラムダ式でパイプする

. を使ったパイプでは、時々混乱が起こります。例えば：

mtcars %>>%
  (lm(mpg ~ ., data = .))

これはちゃんと動きますが、二つの . が別の意味を持っているため、紛らわしく感じます。

このような場合、pipeR ではラムダ式を使うことができます。ラムダ式は () の中にモデル式(formula)を書くことで表現されます。例えば、(x ~ f(x)) というラムダ式を書けば、パイプで受け取った値を変数 x に入れ、関数 f(x) を評価して次に受け渡すという意味になります。

mtcars %>>%
  (df ~ lm(mpg ~ ., data = df))

mtcars %>>%
  subset(select = c(mpg, wt, cyl)) %>>%
  (x ~ plot(mpg ~ ., data = x))

副作用をパイプに含める

パイプラインでは、最終的な結果だけを必要とするのではなく、中間結果も出したい場合があります。中間結果をプリントしたり、プロットしたり、保存したりするためには、メインストリームのパイプラインを壊さずに、副作用を持たせる必要があります。例えば、散布図を描くために plot() を呼び出すと、結果として NULL が返されます。もし、パイプラインの中で何の工夫もなく plot() を呼び出せば、次に渡すべき結果が NULL になってしまい、パイプラインが壊れてしまいます。

パイプラインを壊さずに副作用を持たせるには、~ で始まる片側モデル式 (~ f(x)) を使います。これにより、右辺の式 f(x) は副作用のために評価されるだけであり、その結果は無視され、もともと入力された値が結果としてパイプラインに渡されるという意味になります。

mtcars %>>%
  subset(mpg >= quantile(mpg, 0.05) & mpg <= quantile(mpg, 0.95)) %>>%
  (~ cat("rows:",nrow(.),"\n")) %>>%   # cat() はNULL を返す
  summary

mtcars %>>%
  subset(mpg >= quantile(mpg, 0.05) & mpg <= quantile(mpg, 0.95)) %>>%
  (~ plot(mpg ~ wt, data = .)) %>>%    # plot() は NULL を返す
  (lm(mpg ~ wt, data = .)) %>>%
  summary()

~ によって、メインストリームパイプラインと副作用操作を容易に区別することができます。

中間結果をプリントする糖衣構文も用意されています。(? expr) は (~ print(expr)) と同様の動きをします。

mtcars %>>% 
  (? ncol(.)) %>>%
  summary

代入ありパイプ

プリントやプロットに加えて、中間結果を変数に代入したい場合もあります。

パイプした結果を変数 symbol に代入したい場合は、(~ symbol) と書けばいいだけです。そうすることで、現在の環境中の symbol という変数に、パイプで渡された値を代入することになります。

mtcars %>>%
  (lm(formula = mpg ~ wt + cyl, data = .)) %>>%
  (~ lm_mtcars) %>>%
  summary

パイプした値をそのまま変数に代入するのではなく、何か変換をかけてから代入したい場合は、= や <- が使えます。より自然に、ラムダ式風に書くには、-> を使います(提案してくれた @yanlinlin82 ありがとう)。

mtcars %>>%
  (~ summ = summary(.)) %>>%  # 副作用 代入
  (lm(formula = mpg ~ wt + cyl, data = .)) %>>%
  (~ lm_mtcars) %>>%
  summary

mtcars %>>%
  (~ summary(.) -> summ) %>>%
  
mtcars %>>%
  (~ summ <- summary(.)) %>>%

途中の結果を変数に代入しつつ、パイプで次に送るには、単に (symbol = expression) のように書けばできます：

mtcars %>>%
  (~ summ = summary(.)) %>>%  # 副作用 代入
  (lm_mtcars = lm(formula = mpg ~ wt + cyl, data = .)) %>>%  # パイプを続ける
  summary

もしくは (expression -> symbol) と書けばより自然です：

mtcars %>>%
  (~ summary(.) -> summ) %>>%  # side-effect assignment
  (lm(formula = mpg ~ wt + cyl, data = .) -> lm_mtcars) %>>%  # パイプを続ける
  summary

オブジェクトから要素を抽出する

x %>>% (y) と書けば、オブジェクト x から要素 y を抜き出すことができます。x としては、ベクトルでもリストでも環境でも、[[]] が定義されているものならなんでも OK です。さらには S4 オブジェクトでも OK です。

mtcars %>>%
  (lm(mpg ~ wt + cyl, data = .)) %>>%
  (~ lm_mtcars) %>>%
  summary %>>%
  (r.squared)

互換性

• dplyr と一緒に使えます：

library(dplyr)
mtcars %>>%
  filter(mpg <= mean(mpg)) %>>%  
  select(mpg, wt, cyl) %>>%
  (~ plot(.)) %>>%
  (model = lm(mpg ~ wt + cyl, data = .)) %>>%
  (summ = summary(.)) %>>%
  (coefficients)

• ggvis と一緒に使えます：

library(ggvis)
mtcars %>>%
  ggvis(~mpg, ~wt) %>>%
  layer_points()

• rlist と一緒に使えます：

library(rlist)
1:100 %>>%
  list.group(. %% 3) %>>%
  list.mapv(g ~ mean(g))

Pipe()

Pipe() 関数はパイプオブジェクトを作成します。パイプオブジェクトでは、外部演算子を使わない軽量チェインが使えます。これによるパイプラインは、典型的には Pipe() で始まり、$value または [] によりパイプの最終的な値を取り出すことで終わります。

パイプオブジェクトは内部関数 .(...) を提供します。この関数は、x %>>% (...) と全く同じ動きをします。また、%>>% には無い機能を持っています。

注： .() は = による代入をサポートしていません。~, <-, -> はサポートしています。

パイプ

Pipe(rnorm(1000))$
  density(kernel = "cosine")$
  plot(col = "blue")

Pipe(mtcars)$
  .(mpg)$
  summary()

Pipe(mtcars)$
  .(~ summary(.) -> summ)$
  lm(formula = mpg ~ wt + cyl)$
  summary()$
  .(coefficients)

サブセットと抽出

pmtcars <- Pipe(mtcars)
pmtcars[c("mpg","wt")]$
  lm(formula = mpg ~ wt)$
  summary()
pmtcars[["mpg"]]$mean()

値の代入

plist <- Pipe(list(a=1,b=2))
plist$a <- 0
plist$b <- NULL

副作用

Pipe(mtcars)$
  .(? ncol(.))$
  .(~ plot(mpg ~ ., data = .))$    # 副作用： plot
  lm(formula = mpg ~ .)$
  .(~ lm_mtcars)$                  # 副作用： 代入
  summary()

互換性

• dplyr と一緒に使えます：

Pipe(mtcars)$
  filter(mpg >= mean(mpg))$
  select(mpg, wt, cyl)$
  lm(formula = mpg ~ wt + cyl)$
  summary()$
  .(coefficients)$
  value

• ggvis と一緒に使えます：

Pipe(mtcars)$
  ggvis(~ mpg, ~ wt)$
  layer_points()

• rlist と一緒に使えます：

Pipe(1:100)$
  list.group(. %% 3)$
  list.mapv(g ~ mean(g))$
  value

pipeline()

pipeline() 関数は、引数ベースおよび表現式ベースのパイプライン評価メカニズムを提供します。pipeline() 関数の動作は、引数をどのように与えるかによって変わります。最初の引数のみを与えた場合、その引数は、{} で囲まれた表現式である必要があり、各行がパイプラインの 1 ステップであるとみなされます。複数の引数が与えられた場合、各引数がパイプラインの 1 ステップであるとみなされます。全てのパイプラインステップは、最終的に %>>% によって結合されるため、どちらの動作も全く同じものになります。

pipeline() 関数の引数や表現式において、注目すべき点があります。パイプライン上で特別な仕事(例えば副作用)を行うためのステップは、もはや () で囲む必要はありません。これは、%>>% を用いた場合には問題となる、演算子の優先順位について考える必要がなくなるためです。

pipeline({
  mtcars
  lm(formula = mpg ~ cyl + wt)
  ~ lmodel
  summary
  ? .$r.squared
  coef
})

ありがとう @hoxo_m pipeline() のアイデアはこの投稿で提示されました。

ライセンス

このパッケージは MIT License の下で公開されています。