stats::median
I agree it seems sensible to add an ellipsis to the formal arguments of the generic median().
The spatstat package has
median.im(x, na.rm=TRUE)
median.linim(x, ...)
These are both accepted by the package checker.
During the transition, perhaps methods for 'median' could have formals like 'median.linim'.
Of course this means that under older R versions, a call to the generic will not recognise/pass the new additional arguments. So, during the transition, other code in the package would need to explicitly call the method rather than the generic when the extra arguments are needed..
Alternatively - if we want to define the method differently according to the version number of R - isn't there a way to use Rd macros to include/exclude an \item declaration?
cheers
Adrian
Prof Adrian Baddeley DSc FAA
John Curtin Distinguished Professor
Department of Mathematics and Statistics
Curtin University, Perth, Western Australia
From: Martin Maechler <maechler at stat.math.ethz.ch>
Sent: Thursday, 2 March 2017 4:37 AM
To: Rob J Hyndman; r-devel at r-project.org
Cc: Martin Maechler
Subject: Re: [Rd] stats::median
Sent: Thursday, 2 March 2017 4:37 AM
To: Rob J Hyndman; r-devel at r-project.org
Cc: Martin Maechler
Subject: Re: [Rd] stats::median
>>>>> Martin Maechler <maechler at stat.math.ethz.ch>
>>>>> on Mon, 27 Feb 2017 10:42:19 +0100 writes:
>>>>> Rob J Hyndman <Rob.Hyndman at monash.edu>
>>>>> on Wed, 15 Feb 2017 21:48:56 +1100 writes:
>> The generic stats::median method is defined as median <-
>> function (x, na.rm = FALSE) {UseMethod("median")}
>> I suggest that this should become median <- function (x,
>> na.rm = FALSE, ...) {UseMethod("median")}
>> This would allow additional S3 methods to be developed
>> with additional arguments.
> and S4 methods, too.
>> Currently I have to over-ride this generic definition in
>> the demography package because median.demogdata has
>> several other arguments.
>> This shouldn't break any code, and will make it easier
>> for new S3 methods to be developed. It is also consistent
>> with almost all other S3 methods which do include an
>> ellipsis.
> "shouldn't break any code" is almost always quite
> optimistic nowadays,....
For CRAN, the change leads 13 packages (out of > 10000) to
"regress" to status: WARN.
I've checked 10 of them, and all these define median() S3
methods, and currently of course have not had the '...' in their
formal argument list(s).
They (and all other useRs who define median() S3 methods and
want their code to work both in R <= 3.3.x _and_ R >= 3.4.0
could use code such as
(for package 'sets' in R/summary.R )
median.set <-
function(x, na.rm = FALSE, ...)
{
median(as.numeric(x), na.rm = na.rm, ...)
}
## drop '...' in R versions <= 3.4.0 :
if((!any("..." == names(formals(median)))) {
formals(median.set) <- formals(median.set)[names(formals(median.set)) != "..."]
body(median.set)[[2]] <- body(median.set)[[2]][-4]
}
or simply
median.cset <-
if("..." %in% names(formals(median))) {
function(x, na.rm = FALSE, ...) median.gset(x, na.rm = na.rm, ...)
} else
function(x, na.rm = FALSE) median.gset(x, na.rm = na.rm)
which is R code that will work fine in both current (and older)
R and in R-devel and future R versions.
For packages however, this will leave a 'R CMD check <pkg>'
warning (for now) because code and documentation mismatch
either in R-devel (and future) R or in current and previous R versions.
It is less clear what to do for these man i.e. *.Rd pages [if you
have them for your median method(s): Note that they *are* optional for
registered S3 methods; package 'sets', e.g., documents 2 out of
4 median methods].
It may (or may not) make sense to tweak R-devel's own 'R CMD check'
to _not_ warn for the missing '...' in median methods for a
while and consequently you'd get away with continued use of no
'...' in the help page \usage{ ... } section.
One solution of course, would be to wait a bit and then release
such package only with
Depends: R (>= 3.4.0)
where you'd use '...' and keep the previous CRAN version of
the package for all earlier versions of R.
That is a maintenance pain however, if you want to change your
package features, because then you'd have to start releasing to
versions of the package: an "old" one with
Depends: R (< 3.4.0)
and a "new" one with R (>= 3.4.0).
Probably easiest would be to comment the \usage{.} / \arguments \item{...}
parts for the time being {as long as you don't want R (>= 3.4.0)
in your package DESCRIPTION "unconditionally"}.
--
Tweaking R-devel's tools::codoc() for this special case may
be a solution liked more by package maintainers for this case.
OTOH, we can only change R-devel's version of codoc(), so it
would be that platform which would show slightly inaccurate
"Usage:" for these (by not showing "...") which also seems a
kludgy solution.
> Actually it probably will break things when people start
> using the new R version which implements the above *AND*
> use packages installed with a previous version of R. I
> agree that this does not count as "breaking any code".
> In spite of all that *and* the perennial drawback that a
> '...' will allow argument name typos to go unnoticed
> I agree you have a good argument nowadays, that median()
> should be the same as many similar "basic statistics" R
> functions and so I'll commit such a change to R-devel (to
> become R 3.4.0 in April).
> Thank you for the suggestion! Martin Maechler, ETH Zurich
>> -------------------------------------------------------------
>> Rob J Hyndman Professor of Statistics, Monash University
>> www.robjhyndman.com<http://www.robjhyndman.com>
>> ______________________________________________
>> R-devel at r-project.org mailing list
>> https://stat.ethz.ch/mailman/listinfo/r-devel<https://stat.ethz.ch/mailman/listinfo/r-devel>
> ______________________________________________
> R-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel<https://stat.ethz.ch/mailman/listinfo/r-devel>