Skip to content

Clarification on generic functions and methods

5 messages · Doran, Harold, Henrik Bengtsson, Ken Knoblauch

Original
Doran, Harold
# 
I have constructed the following functions and need a little clarification:

### function to fit the model parameters
jml.fit <- function(dat, con = 1e-3, bias=FALSE, ...){
	do stuff ...
}

### default function which calls jml.fit
jml.default <- function(dat, con = 1e-3, bias=FALSE, ...){
	result <- jml.fit(dat, con = 1e-3, bias)
	result$call <- match.call()
	class(result) <- "jml"
	result
}

### Function to make use of formula
jml.formula <- function(formula, data, na.action, subset, ...){
	mf <- match.call(expand.dots = FALSE)
    m <- match(c("formula", "data", "na.action", "subset"), names(mf), 0L)
    mf <- mf[c(1L, m)]
    mf$drop.unused.levels <- TRUE
    mf[[1L]] <- as.name("model.frame")
    mf <- eval(mf, parent.frame())
	mt <- attr(mf, "terms")
	dat <- mf
	result <- jml.default(dat, ...)
	result$call <- match.call()
	result$formula <- formula
	result
}

### and the generic function 
jml <- function(dat, con = 1e-3, bias=FALSE, ...) UseMethod("jml")

Writing R Extensions states, "If the generic specifies defaults, all methods should use the same defaults." 

In my example above, the generic function has 2 defaults: one for argument con and another bias. I'm a little confused on exactly how the generic function should be structured for proper package development.

I think the options are:

1) jml <- function(dat, con = 1e-3, bias=FALSE, ...) UseMethod("jml")
2) jml <- function(x, con = 1e-3, bias=FALSE, ...) UseMethod("jml")
3) jml <- function(formula, data, na.action, subset, con = 1e-3, bias = FALSE, ...) UseMethod("jml")

I'm inclined to believe #3 is correct because the .Rd page needs to reflect the args in this function, is that right? Then, this generic function would include the formula, data, na.action, and subset and it includes the proper defaults as the other functions. 

Thank you
Harold
R version 2.10.0 (2009-10-26) 
i386-pc-mingw32 

locale:
[1] LC_COLLATE=English_United States.1252  LC_CTYPE=English_United States.1252   
[3] LC_MONETARY=English_United States.1252 LC_NUMERIC=C                          
[5] LC_TIME=English_United States.1252    

attached base packages:
[1] stats     graphics  grDevices utils     datasets  methods   base     

other attached packages:
[1] scoreFoo_1.1   MiscPsycho_1.4 statmod_1.4.1 

loaded via a namespace (and not attached):
[1] tools_2.10.0
Henrik Bengtsson
# 
Using

jml <- function(...) UseMethod("jml")

will do.

/Henrik
On Wed, Nov 11, 2009 at 4:26 PM, Doran, Harold <HDoran at air.org> wrote:
Doran, Harold
# 
Thank you, Henrik. This actually doesn't work when I build the package, which may only require a slight modification to what I'm doing now. First, I create a NAMESPACE as:

### NAMESPACE FILE CONTENTS
export(jml2)
S3method(jml2, fit)
S3method(jml2, default)
S3method(jml2, formula)
S3method(print, jml)
S3method(summary, jml)
S3method(print, summary.jml)

So, only the generic function (jml) is exported. 

Now, I do as you suggest below for the generic function, but keep all others as they were previously. That creates a situation where jml.formula, jml.default, and jml have different arguments.

Now, in the .Rd file for the jml function I want the user to see the usage for the jml.formula method, which obviously has more args than "...". So, the .Rd file is structured as (for testing purposes only):

\name{jml2}
\alias{jml2}
\title{JML Estimation}
\description{JML Stuff}
\usage{
jml2(formula, data, na.action, subset, con = 1e-3, bias = FALSE, ...)
}
\arguments{
  \item{formula}{Describe later}
  \item{data}{Describe later}
  \item{na.action}{Describe later}
  \item{subset}{Describe later}
  \item{con}{Describe later}
  \item{bias}{Describe later}
  \item{\dots}{Not implemented}
}
\author{Me}
\examples{
\dontrun{jml(~V1 + V2, data)}
}
\keyword{misc}

But, because the args in the generic functions differ from what I have placed in the .Rd file, the check phase yields the following error, which indicates the .Rd file and code are different.

C:\Program Files\R\R-2.10.0\bin>Rcmd check g:\jmlFoo
* checking for working pdflatex ...pdflatex: not found
 NO
* checking for working latex ...latex: not found
 NO
* using log directory 'C:/Program Files/R/R-2.10.0/bin/jmlFoo.Rcheck'
* using R version 2.10.0 (2009-10-26)
* using session charset: ISO8859-1
* checking for file 'jmlFoo/DESCRIPTION' ... OK
* checking extension type ... Package
* this is package 'jmlFoo' version '1.0'
* checking package name space information ... OK
* checking package dependencies ... OK
* checking if this is a source package ... OK
* checking for executable files ... OK
* checking whether package 'jmlFoo' can be installed ... OK
* checking package directory ... OK
* checking for portable file names ... OK
* checking DESCRIPTION meta-information ... OK
* checking top-level files ... OK
* checking index information ... OK
* checking package subdirectories ... OK
* checking R files for non-ASCII characters ... OK
* checking R files for syntax errors ... OK
* checking whether the package can be loaded ... OK
* checking whether the package can be loaded with stated dependencies ... OK
* checking whether the name space can be loaded with stated dependencies ... OK
* checking for unstated dependencies in R code ... OK
* checking S3 generic/method consistency ... OK
* checking replacement functions ... OK
* checking foreign function calls ... OK
* checking R code for possible problems ... NOTE
jml2.fit: no visible binding for global variable 'theta.max'
jml2.fit: no visible global function definition for 'fit.Stats'
* checking Rd files ... OK
* checking Rd metadata ... OK
* checking Rd cross-references ... OK
* checking for missing documentation entries ... OK
* checking for code/documentation mismatches ... WARNING
Codoc mismatches from documentation object 'jml2':
jml2
  Code: function(...)
  Docs: function(formula, data, na.action, subset, con = 0.001, bias =
                 FALSE, ...)
  Argument names in docs not in code:
    formula data na.action subset con bias
  Mismatches in argument names:
    Position: 1 Code: ... Docs: formula

* checking Rd \usage sections ... OK
* checking examples ... OK

WARNING: There was 1 warning, see
  C:/Program Files/R/R-2.10.0/bin/jmlFoo.Rcheck/00check.log
for details

So, what I'm trying to accomplish is to export the jml generic function and make this the only one visible to the user. All others are in the NAMESPACE as S3 methods. But this obviously creates a conflict between what I want in the .Rd file and what args are in the code for the generic jml function.

Can anyone help me understand how this might be resolved?

Harold
Ken Knoblauch
# 
Doran, Harold <HDoran <at> air.org> writes:
which may only require a slight
as they were previously. That
arguments.
the jml.formula method, which
(for testing purposes only):

How about if you document the default method as well as the generic
method in your man page.  See ?lag for an example, and I've come
across several others recently.

HTH,

Ken
Doran, Harold
# 
Hi Ken:

Well, I'm quite pleased with a solution I found. The t.test method and its .Rd file showed me that I can export only the generic method, use \alias{jml2.default} and \alias{jml2.formula} in the .Rd file for jml2, and then use \method{jml2}{default}{args} and \method{jml2}{formula}{args}.

Using this, I was able to build the package in both windows and Ubuntu without error.