パッケージの作成

R のパッケージの作成はそれほど難しくないが、準備するファイル数が非常に多い。また、Windows でもパッケージの作成は可能だが、Linux 上で作成することでビルドチェックなどが便利になる。

パッケージの作成はおおよそ次のような手順で行う。

  1. パッケージに入れたいデータセットや関数、クラスの定義などをファイルに書く。(複数のファイルに書いても良い。)
  2. パッケージのひな形を作成する。
  3. マニュアル(help で呼び出す関数の説明)などを編集する。
  4. パッケージの名前空間や説明などを編集する。
  5. ビルドチェックする。コードにミスがあると、エラーまたは警告が生じる。エラーが無くなるまで、ビルドチェックを行う。(警告もできるだけ減らす。)
  6. ビルドして公開する。

パッケージは次のようなディレクトリ構成になっている。

Asagao                        # トップディレクトリ
   |--- NAMESPACE             ## 名前空間の設定
   |--- DESCRIPTION           ## パッケージの説明や依存関係など
   |---R                      ## R のコードが保存されているディレクトリ
   |   |--- code1.R           ### コードは複数のファイルに分割しても構いません
   |   |--- code2.R
   |
   |---man                    ## help によって呼び出される関数の説明や使い方などのマニュアルの保存ディレクトリ
   |   |--- func1.Rd          ### 関数1つに付き1ファイルで作成する
   |   |--- func2.Rd          
   |   |--- func3.Rd
   |
   |---data                   ## データをパッケージに入れたい場合はこのディレクトリに保存する
   |   |--- mydata.RData      ### data(mydata)のように呼び出して使う
   |
   |---inst                   ## その他のメタ情報(省略可)
   |   |--- CITATION          ### 引用文献がある場合はこのファイルに BiText 形式書く
   |   |--- doc               ## その他ドキュメント類(省略可)
   |   |     |--- Asagao.Rnw  ### vignette と呼ばれる詳細マニュアル(省略可)
   |   |--- README
   |
   |---tests                  ## パッケージ中に書かれている関数が正しく実行できるかどうかチェックするテストスクリプトを保存するディレクトリ
       |--- test_func1.R
       |--- test_func2.R
       |--- test_func3.R 

コードの準備

パッケージに入れたいデータセットや関数、クラスの定義をファイルに書く。複数ファイルに分けて書いてもよい。

ひな形を作成(スケルトンを生成)

R を立ち上げて、package.skeleton を実行してスケルトンを作成する。このとき、code_files に作成した関数やクラスの定義などのファイルを与える。ただし、上に示してあるツリー構造を手動で作成する場合は、package.skeleton を実行する必要はない。

package.skeleton("Asagao", code_files = c("code1.R", "code2.R"))

man ファイルの編集

R では、help 関数を利用するとその関数の説明や使用方法などが表示される。このようなヘルプ情報に関わるファイルは man ディレクトリ下に保存する。基本的に 1 つの関数につき 1 つのヘルプファイルを用意する必要がある。(複数の関数を 1 つのファイルにまとめることもできる。)

ファイルは基本的に次のパーツで構成されている。

\name{関数名}
\alias{関数名}
\title{関数のタイトル}
\description{関数に関する短い説明文}
\usage{
関数の使い方
}
\arguments{
    \item{引数1}{引数の意味と使い方}
    \item{引数2}{引数の意味と使い方}
    \item{...}{引数の意味と使い方}
}
\details{
関数に対する詳細な説明
詳しい動作や継承などの説明
}
\value{
関数の返り値に対する説明
}
\examples{
関数を使ったサンプルコード
}

パッケージの名前空間や説明集

パッケージの名前空間は NAMESPACE ファイル、パッケージに関する説明やバージョン情報、依存関係などは DESCRIPTION に書く。

NAMESPACE

NAMESPACE を package.skeleton で作成した場合はとくに編集しなくても良い。NAMESPACE には、依存関係のパッケージのリロード、定義されているクラス名や関数名などを記載する。

# 依存パッケージをインポート
import(rgl)

# クラスが定義されている場合はここでエクスポート
exportClasses(
    "Asagao" 
)

# 関数をエクスポート
export(
  func1,
  func2,
)

DESCRIPTION

パッケージの説明文やバージョン情報、著者などの情報を DESCRIPTION ファイルに記載する。

Package: Asagao
Type: Package
Title: The package title ...
Version: 2.1.0
Author: Jianqiang Sun
Maintainer: Jianqiang Sun 
Description: This package provides ...
   and ...
   The ...
Depends: R (>= 2.15), methods
Imports: EBSeq, samr
Suggests: RUnit
Enhances: snow
License: GPL-2

ビルドチェックとビルド

ビルドチェックは R のバッチモードで行う。

ビルドチェック

ターミナルを起動して、パッケージが保存されているディレクトリに移動し、次のコマンドを実行しビルドチェックを行う。Error や Warning が出た場合は、指摘された箇所を修正して、再度チェックする。

R CMD check Asagao

ビルド

Error がなくなればパッケージをビルドする。Warning についてはできるだけ減らす。ビルドが完了すると「Asagao.tar.gz」が生成される。これが R のパッケージファイルになる。

R CMD build Asagao

エラーチェックがうまくいかないとき

エラー対策 texi2pdf: not fountd

TeX 関連のライブラリーが足りないと思われる。TeX Liveを利用してインストールする。(Tex Live)。場合によって texinfo も必要。

sudo apt-get install texinfo

inconsolata.sty が足りないとき

ビルド時に TeX により PDF の作成が行われる、この際に inconsolata スタイルを利用する。このスタイルをダウンロードしてインストールする必要がある。

generic '[' and siglist

総称的関数を再定義して利用したとき、パッケージのチェックで以下のような警告が生じることがある。

* checking for missing documentation entries ... WARNING
Undocumented S4 methods:
  generic '[' and siglist 'TCC,ANY'
All user-level objects in a package (including S4 classes and methods)
should have documentation entries.
See the chapter ‘Writing R documentation files’ in the ‘Writing R
Extensions’ manual.

Rd ファイルに alias を追加することで解決できる。例えば、この場合は TCC クラスについて '[' を定義したので、TCC-class.Rd ファイルにて次のような alias を追加する。カンマ前後にはスペースを入れないこと。

\alias{[}
\alias{[,TCC,ANY-method}

データをパッケージに保存したい場合

オリジナルデータをパッケージに入れたい場合、データを R に読み込んでからバイナリー形式で保存する。ここでは、alphaMatrix データを例にする。

# データを作成 / またはファイルから取り込む
alphaMatrix <- matrix(1:100, ncol = 2)

# R 形式でデータを保存
save(alphaMatrix, file = "alphaMatrix.RData")

こうして保存された「alphaMatrix.RData」を「/Asagao/data/」ディレクトリの下に置くことで、ビルド時にパッケージに取り込まれる。