2014-04-29

骨格文書を編集する

R Rstudio パッケージ

『骨格文書を編集して、終わったらビルド』と言うのは簡単で、これが、まあ、面倒臭いわけだけれど、その部分も、手を拱かずに、目を瞑って駆け抜けられるよう、実施の経過をメモにして、「駆け抜けるコツ」を獲得したい
まずDESCRIPTIONファイル
- 既存の、よく知っているパッケージのDESCRIPTIONファイルをひとまずコピーして、どのくらい、どんな風に書くかを確認。もちろん、中身は違うので書き換えが必要だけれど、書くべき内容の雰囲気は悪くない状況に持ち込みやすい。たとえば、MCMCpackのそれなら、

library(MCMCpack)
help(rdirichlet)

- よく使う関数のヘルプ記事を開く。こうして関数のヘルプを表示させ、その後、ヘルプ記事の末尾に行って、"index"に飛ぶ。そうすると、記事を持つ関数のリストよりも上にDESCRIPTIONファイルがあるので開く。見てみよう。そして真似して書いてみる。

Package: MCMCpack
Version: 1.3-3
Date: 2013-5-1
Title: Markov chain Monte Carlo (MCMC) Package
Author: Andrew D. Martin, Kevin M. Quinn, and Jong Hee Park
Maintainer: Jong Hee Park <jongheepark@snu.ac.kr>
Depends: R (>= 2.10.0), coda (>= 0.11-3), MASS, stats
Description: This package contains functions to perform Bayesian
        inference using posterior simulation for a number of
        statistical models. Most simulation is done in compiled C++
        written in the Scythe Statistical Library Version 1.0.3. All
        models return coda mcmc objects that can then be summarized
        using the coda package.  MCMCpack also contains some useful
        utility functions, including some additional density functions
        and pseudo-random number generators for statistical
        distributions, a general purpose Metropolis sampling algorithm,
        and tools for visualization.
License: GPL-3
SystemRequirements: gcc (>= 4.0)
URL: http://mcmcpack.wustl.edu
Packaged: 2013-05-01 00:37:02 UTC; parkjonghee
NeedsCompilation: yes
Repository: CRAN
Date/Publication: 2013-05-01 07:02:08
Built: R 3.0.2; x86_64-w64-mingw32; 2013-12-20 22:58:58 UTC; windows
Archs: i386, x64

次に関数ごとのman(マニュアル文書)を編集しよう
- 書くべきmanファイルとそれに帰属する関数の対応を決める
  - まずは、パッケージの利用者が何をやっているのか、使うときに引数・オプション・出力を理解できるように、(基本的に独立した関数として、)きっちり書きたい関数と、利用者が意識せずに背後で動く関数(そのman記事はごく簡素に)とに分ける。簡素に書く関数はさらに、一枚のmanファイルで説明してもＯＫかどうかを検討し、グループ化をする。「きっちり書く」関数も場合によってはまとめたいので、そんなまとめについて確定する
- １関数、１ファイルの場合
  - 骨格ファイルはつぎのような感じ
  - いじるのは、\title,\description,\arguments,\value,\author,\examples
  - examplesには、説明するべき関数がちゃんと動くように作る

\name{calc.chisq}
\alias{calc.chisq}
%- Also NEED an '\alias' for EACH other topic documented here.
\title{
%%  ~~function to do ... ~~
}
\description{
%%  ~~ A concise (1-5 lines) description of what the function does. ~~
}
\usage{
calc.chisq(A)
}
%- maybe also 'usage' for other objects documented here.
\arguments{
  \item{A}{
%%     ~~Describe \code{A} here~~
}
}
\details{
%%  ~~ If necessary, more details than the description above ~~
}
\value{
%%  ~Describe the value returned
%%  If it is a LIST, use
%%  \item{comp1 }{Description of 'comp1'}
%%  \item{comp2 }{Description of 'comp2'}
%% ...
}
\references{
%% ~put references to the literature/web site here ~
}
\author{
%%  ~~who you are~~
}
\note{
%%  ~~further notes~~
}

%% ~Make other sections like Warning with \section{Warning }{....} ~

\seealso{
%% ~~objects to See Also as \code{\link{help}}, ~~~
}
\examples{
##---- Should be DIRECTLY executable !! ----
##-- ==>  Define data, use random,
##--	or do  help(data=index)  for the standard data sets.

## The function is currently defined as
function (A) 
{
    E <- make.exp.table(A)
    D <- make.diff.table(A)
    sum(c(D)^2/c(E))
  }
}
% Add one or more standard keywords, see file 'KEYWORDS' in the
% R documentation directory.
\keyword{ ~kwd1 }
\keyword{ ~kwd2 }% __ONLY ONE__ keyword per line

\name{calc.chisq}
\alias{calc.chisq}
%- Also NEED an '\alias' for EACH other topic documented here.
\title{
chi-square of multi-way table
}
\description{
Calculates chi-square value of multi-way table
}
\usage{
calc.chisq(A)
}
%- maybe also 'usage' for other objects documented here.
\arguments{
  \item{A}{
A array
}
}
\details{
%%  ~~ If necessary, more details than the description above ~~
}
\value{
chi-square value
}
\references{
%% ~put references to the literature/web site here ~
}
\author{
Ryo Yamada
}
\note{
%%  ~~further notes~~
}

%% ~Make other sections like Warning with \section{Warning }{....} ~

\seealso{
%% ~~objects to See Also as \code{\link{help}}, ~~~
}
\examples{
A <- matrix(1:6,2,3)
calc.chisq(A)
B <- array(1:24,c(2,3,4))
calc.chisq(B)
% Add one or more standard keywords, see file 'KEYWORDS' in the
% R documentation directory.
\keyword{ ~kwd1 }
\keyword{ ~kwd2 }% __ONLY ONE__ keyword per line

- 次に複数の関数を１つのmanファイルで説明しよう
  - 複数の関数を１つのmanファイルに紐づける仕組みは\alias
  - たとえば、rmway.table()とpmway.table()という２つの関数をmway.table()というヘルプファイルで説明するには、
    - 骨格として作成されているrmway.table.Rdとpmway.table.Rdという2つのファイルのうち、片方のrmway.table.Rdのコピーを"mway.table.Rd"として保存し、その中を紐づける両方の関数のためとしてきちんと書くとともに
    - \aliasを加える
    - 引数は複数の関数で統一的に使っておく
    - たとえば、pmway.table.Rdを基にする場合は、以下のように\nameも\aliasもともにpmway.tableとなっているものを

\name{pmway.table}
\alias{pmway.table}

- - - 次のように、\nameを修正し、\aliasを付け加える

\name{mway.table}
\alias{pmway.table}
\alias{rmway.table}

- - pmway.table.Rdとrmway.table.Rdは(多分、最後に)削除すればよい(のだと思う)。作業の途中では、Rstudioで当該hoge.RdファイルのチェックボックスをＯＮにして、Renameで削除予定として名称変更しておいて、最後にまとめて削除するのが失敗がなくてよさそう