On 10/5/2009 1:50 PM, Charles Geyer wrote:
The functions metrop and temper in the mcmc package have a debug = FALSE
argument that when TRUE adds a lot of debugging information to the returned
list. This is absolutely necessary to test the functions, because one
generally knows nothing about the simulated distribution except what what
one learns from MCMC samples. Hence you must expose all details of the
simulation to have any hope of checking that it is doing what it is supposed
to do. However, this information is of interested mostly (perhaps solely)
to developers. So I didn't document it in the Rd files for these functions.
But it has ocurred to me that people might be interested in how these functions
are validated, and I would like to document the debug output somewhere, but I
don't want to clutter up the documentation that ordinary users see. That
suggests a separate help page for debugging. Looking at "Writing R Extensions"
it doesn't seem like there is a type of Rd file for this purpose. I suppose
it could be added in (fairly long) sections titled "Debug Output" in metrop.Rd
and temper.Rd or it could be put in a package help page (although that's not
what that kind of page is really for). Any other possibilities to consider?
I think writing it up in a vignette would probably be most appropriate.
You can link directly to a vignette from a man page (though not,
unfortunately, vice versa). For example, if you look at
package?grid, you'll see a list that was generated by this code:
Further information is available in the following
\link{vignettes}:
\tabular{ll}{
\code{grid} \tab Introduction to \code{grid} (\url{../doc/grid.pdf})\cr
\code{displaylist} \tab Display Lists in \code{grid}
(\url{../doc/displaylist.pdf})\cr
...
Duncan Murdoch
______________________________________________
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
