[R] First R Package --- Advice?

[ivo welch]

thanks for the responses.  this is what I have learned so far:
primarily, I need to learn roxygen2 and devtools, because they do what
I was planning to reinvent.

roxygen2 allows R users to write R code that embeds its documentation.
 the .R user source file has a family semblance with POD (perl's plain
old documentation), although pod looks cleaner because it does not
need the '#' comments.  all roxygen2 documentation commands are
interspersed as comments, and presumably devtools creates the .Rd
files from such .R files in devtool's package build stage.  it is not
clear to me whether every function must or should get its own .R file
now (just like each R function has its own .Rd file).  in "Getting
Started with RStudio", there is a brief 1-pager on roxygen2, which
gave me a flavor of what it is.  there is also a stackoverflow with
links at http://stackoverflow.com/questions/4523513/good-reference-for-roxygen
, but this is for oxygen not oxygen2, I think.  then there is the
standard roxygen2 standard documentation, but this is just the
function man set and not a "how to get started" description.  I don't
think roxygen2 has a vignette, either.  right now, I am wondering
whether there is a skeleton creator for an existing function for
roxygen2, which generates all the required .Rd fields as appropriate
'#@' directives in the comments, just like the vanilla package
skeleton creator in R creates them in the .Rd files.

devtools is a package that can take roxygen2 .R files, compile the
embedded comments into .Rd files into the man/ directory, and then
rebuilds and reloads the package on the fly.  (possibly also
repackages them.)  roughly speaking, I think it translates the more
convenient new doc format into the old standard basic way to package
packages, and also obviates the need to restart R.  again, this is
what I gleamed from the rstudio guide.

so, the combination of devtools and oxygen2 seem to be exactly what I
wanted, but I did not find the starter docs. what I would love to see
is someone pointing me to a 1-page example of how a new user should
take two real simple functions, say

# my old sum remark
sum1 <- function(x,y) (x+y)
# my old difference remark
difference1 <- function(x,y) (x-y)
stopifnot( sum1(5,5) == 10 )  ## should become a testthat

and make a (silly) package out of it.  this intro should describe how
the user should start by creating the package skeleton (say, package
sumdiff), how one gets the roxygen2 skeletons for the two functions,
how one builds and loads it (for testing), then how one would change
it, e.g., by changing both functions to square the inputs, rebuild and
reload.  someone has probably already written this up, but it is
difficult to find.

I read some other package introductions, too, but they end up
overbuilding the example and/or are better references than "get
started guides."  for example, the Leisch packaging introduction
spends more than half of its space and the user's attention span (and
in my case, brain cells) on peripheral aspects.  yes, S3 and S4
functions, extending lm() etc., is all nice and useful, but teaching
the basic logic of the R packaging system may be better done with
functions that do almost nothing.  contemplating the core logic of
lm() extensions is distracting at the first baby steps.  similarly,
rstudio is a really nice IDE, but I don't think that roxygen2 and
devtools need rstudio.

could someone point me to a simpler "starting" document for roxygen2
and devtools, if such exists?

regards,

/iaw
----
Ivo Welch (ivo.welch at gmail.com)
http://www.ivo-welch.info/
J. Fred Weston Professor of Finance
Anderson School at UCLA, C519
Director, UCLA Anderson Fink Center for Finance and Investments
Free Finance Textbook, http://book.ivo-welch.info/
Editor, Critical Finance Review, http://www.critical-finance-review.org/


On Tue, Feb 5, 2013 at 4:43 PM, ivo welch <ivo.welch at anderson.ucla.edu> wrote:
> Dear R experts---
>
> after many years, I am planning to give in and write my first R
> package.  I want to combine my collection of collected useful utility
> routines.
>
> as my guide, I am planning to use Friedrich Leisch's "Creating R
> Packages: A Tutorial" from Sep 2009.  Is there a newer or better
> tutorial?  this one is 4 years old.
>
> I also plan on one change---given that the package.skeleton() function
> writes all the individual man[ual] functions, I am thinking it would
> be a good idea to put the doc and the R code together in the same
> file, one for each function.  Interestingly enough, the code is by
> default in the \examples{} section, so I am thinking of writing a perl
> program that takes every .Rd file and writes the function into the R/
> directory, overwriting anything else that is already there.  this way,
> I maintain only one file for each function, and the docs and code are
> together.  sort of like knuth's literate programming and the
> numerical-recipees approach to keeping each function in its own file
> with equal name.
>
> I believe my "try-out and debug cycle" will then be
>
>    $ cd iaw  ## the package name and top directory is iaw
>    $ perl weaveall.pl   ## extract all man/*.Rd files code examples
> and place them in R/
>    $ R CMD INSTALL iaw
>    $ R CMD check iaw
>
> good idea?  bad idea?  common?  uncommon?
>
> I do not understand the namespace mechanism yet.  I understand the
> NAMESPACE file, and I think this lists the routines that become
> visible when a later program of mine contains 'library(iaw)'.  I think
> I want to explicitly declare what packages are actually imported.
> ?importIntoEnv tells me that it is not intended to be used.  how can
> another program declare exactly what functions it wants to import?
> (frankly, I would love to turn all default autovivification off in my
> program, but that's not possible.)
>
> /iaw
> ----
> Ivo Welch (ivo.welch at gmail.com)