[R-pkg-devel] Re-exporting S3 generics

[Lenth, Russell V]

Dear package developers:

My 'lsmeans' package provides, among other things, 'as.mcmc' and 'as.mcmc.list' methods for its 'ref.grid' objects. Those methods allow obtaining posterior predictions, or averages thereof, from certain models fitted using MCMC methods.

My question concerns this: the S3 generics for 'as.mcmc' and 'as.mcmc.list' exist in the 'coda' package. Therefore, 'coda' is listed in the Imports field of the DESCRIPTION file, and the NAMESPACE file imports these generics and registers my corresponding methods for the 'ref.grid' class. However, to use those methods, the user must either have the 'coda' package attached, or name it explicitly in calling as.mcmc -- even if the user doesn't want to use the coda package for anything else. For concreteness, consider the following illustration:

    library("rstanarm")
    example("stan_glm")
    # ... (output suppressed) ...

    library("lsmeans")
    ref.grid(fit3)
    ## 'ref.grid' object with variables:
    ##     outcome = 1, 2, 3
    ##     treatment = 1, 2, 3
    ## Transformation: “log”

    outcome.lsm <- lsmeans(fit3, "outcome")  # averages predictions over treatments
    outcome.post <- as.mcmc(outcome.lsm)
    ## Error in as.mcmc(fit3) : could not find function "as.mcmc"

    outcome.post <- coda::as.mcmc(outcome.lsm)

    library(bayesplot)
    mcmc_areas(outcome.post, prob = .9)

In this illustration, the user could have used the plot routines in the coda package to display the results; but instead, opted for the cooler ones in the 'bayesplot' package. The user had no need at all for the 'coda' package except to locate the generic for 'as.mcmc'. This seems kind of user-unfriendly. 

But suppose I modify and rebuild the package so that it exports the generic 'as.mcmc'. Then it would be visible to the user and the first 'as.mcmc' call above would have worked. This looks like it potentially could mess up the S3 dispatching of this method. However, if I try it ...

    # ... (Package rebuilt adding  'export(as.mcmc)'  to NAMESPACE) ...
    as.mcmc
    ## function (x, ...) 
    ## UseMethod("as.mcmc")
    ## <environment: namespace:coda>

... it appears that it 'lsmeans' is not exporting a copy, but the exact same generic in the exact same namespace. So this re-exporting  seems harmless, and is a convenience to the user. (I'll comment that several older versions of 'lsmeans' did export 'as.mcmc' and to my knowledge, nothing bad happened). Am I missing something?

Russ


Russell V. Lenth  -  Professor Emeritus
Department of Statistics and Actuarial Science   
The University of Iowa  -  Iowa City, IA 52242  USA   
Voice (319)335-0712 (Dept. office)  -  FAX (319)335-3017