[Rd] stats::median

[Martin Maechler]

>>>>> 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

    >> ______________________________________________
    >> R-devel at r-project.org mailing list
    >> https://stat.ethz.ch/mailman/listinfo/r-devel

    > ______________________________________________
    > R-devel at r-project.org mailing list
    > https://stat.ethz.ch/mailman/listinfo/r-devel