Foo Save

R package foo is a toy R package to serve as an example for statistical confusing classes. (Actually now two packages, see the end of this README.)

It illustrates calling C or Fortran from R.

Each function that calls C from R needs both the C function and an R function that calls it (so users don't have to know about this). To illustrate this we have an R function foo (package/foo/R/foo.R) that calls either C or FORTRAN depending on an optional argument type. The functions that it calls are

• foo.f called via the R function .Fortran
• bar.c called via the R function .C
• baz.c called via the R function .Call (which allows manipulating R objects of all types in C, but which is harder to use than the .C interface)

All of these functions do the same completely boring task (squaring the elements of a vector). The point is just to show computation moving from R to C and back.

This package also illustrates using the R uniform and nonuniform random number generators inside C or FORTRAN called from R. Again all three interfaces are illustrated

• quf.f called via the R function .Fortran
• qux.c called via the R function .C
• quux.c called via the R function .Call

The FORTRAN one is a bit tricky because there is no R FORTRAN API for calling the random number generators, so we write stub C functions that look like FORTRAN functions to FORTRAN (a C function fred called from FORTRAN must be wrapped with a macro F77_SUB(fred), see Section 6.6 of the book Writing R Extensions). Then we call these stub functions from FORTRAN and these stub functions call the correct functions from the R C API. These stub functions are in

• crandom.c

The other question is how does one know that the function in the R C API that generates beta random variates is called rbeta? And how does one know what the arguments of this function mean?

Section 6.3 and Section 6.7.1 of the book Writing R Extensions are the authoritative documentation of the R API for random number generation and for the R "distribution functions" (like dnorm, pnorm, qnorm, and rnorm except that "norm" can be replaced by something else, for example, dbeta, pbeta, qbeta, or rbeta), but I find these so sketchy that I also look at the headers and source code.

You can find all of the include files for R (the entire public API) by doing

R CMD config --cppflags

Take off the -I (a C compiler flag) and the rest is the directory where all the include files are found. Look in them for functions that have beta in the name. It turns out that there are a lot of them in the file

• Rmath.h

which can be found on-line or in the R source (if you have it). We see functions pbeta, qbeta, dbeta, rbeta that according to the comments in Rmath.h are for the beta distribution and also pnbeta and so forth that are for the noncentral beta distribution. We probably want rbeta (actually Section 6.7.1 of the book Writing R Extensions says that certainly rbeta is the name of the C function we want to call). So we look at the source for that

• rbeta.c

Although it is not totally clear from the comments, it seems that the arguments are the two shape parameters and each call returns one beta random variate So that's what we need to know to use this function.

R package foo illustrates the way you write this stuff as a beginner (at writing R packages, not a beginner at R). R package fooRegister illustrates the way you write this stuff as an expert. The difference is registration of native routines. Comparing the two packages shows what is required to do it the hard way (the expert way). The expert way really is better, but it is not recommended for beginners.

CRAN package checks now complain if you do not do this registration of native routines as illustrated in R package fooRegister.

These packages check with --use-valgrind and --use-gct. These options to R CMD check should be used when changes are made to C or Fortran or C++ source code. (The --use-gct only needs to be used when the .Call interface is being used.