Deprecate pairs, add pairs_profile.

Author: dmurdoch

.Rbuildignore

@@ -7,3 +7,4 @@
 ^pkgdown$
 ^\.github$
 ^CRAN-SUBMISSION$
+^revdep$

.gitignore

@@ -4,3 +4,4 @@
 .httr-oauth
 .DS_Store
 docs
+revdep

DESCRIPTION

@@ -1,5 +1,5 @@
 Package: ellipse
-Version: 0.4.5
+Version: 0.5
 Title: Functions for Drawing Ellipses and Ellipse-Like Confidence Regions
 Author: Duncan Murdoch and E. D. Chow (porting to R by Jesus M. Frias Celayeta)
 Maintainer: Duncan Murdoch <murdoch.duncan@gmail.com>

NAMESPACE

@@ -1,4 +1,4 @@
-export(ellipse,plotcorr,pairs)
+export(ellipse,plotcorr,pairs_profile, pairs)
 
 importFrom("graphics", "axis", "box", "lines", "mtext", "par", "plot",
              "plot.new", "polygon", "strwidth", "text")

NEWS.md

@@ -1,3 +1,8 @@
+## Version 0.5
+
+* The `pairs()` generic and `pairs.profile()` method have both
+been deprecated, and replaced with the `pairs_profile()` function.
+
 ## Version 0.4.5 
 
 * `center` was ignored in `ellipse.default()`.

R/pairs.profile.R

@@ -1,5 +1,7 @@
-pairs <- function(x, ...) 
+pairs <- function(x, ...) {
+  .Deprecated("pairs_profile or graphics::pairs", "ellipse")
   UseMethod("pairs")
+}
 
 .pairs_default <- function(x, ...)
   graphics::pairs(x, ...)
@@ -19,11 +21,13 @@ pairs <- function(x, ...)
   graphics::pairs(mf, ...)
 }
 
-"pairs.profile" <-
+pairs_profile <-
   function (x, labels = c(names(x), "Profile tau"), panel = lines, 
             invert = TRUE, plot.tau = TRUE, plot.trace = TRUE, plot.sketch = TRUE, 
             plot.ellipse = FALSE, level = 0.95, ...) 
 {
+  stopifnot(inherits(x, "profile"))
+    
   doaxis <- function(which, dolabel = TRUE) axis(which, labels = dolabel) # outer = TRUE, line = -0.5, labels = dolabel)
   setup <- function(x, y, ...) plot(range(x[!is.na(x)]), 
                                        range(y[!is.na(y)]), type = "n", axes = FALSE, ...)
@@ -130,3 +134,5 @@ pairs <- function(x, ...)
   }
   invisible()
 }
+
+pairs.profile <- pairs_profile

cran-comments.md

@@ -1,8 +1,9 @@
-### 0.4.5:  A bug fix update:
+### ellipse 0.5: 
 
-Sorry for missing this, but there's a simple error in the 
-new code from the previous submission that needs fixing:  the
-new `center` parameter is completely ignored.
+This change is at the request of Prof. Ripley, to prepare for the 
+move of `MASS::pairs.profile` to `stats`.  In this release, I have
+added a function `pairs_profile`, while deprecating `pairs`.  Before R 4.4.0 comes out, I intend to remove `pairs` and `pairs.profile`, keeping
+only the new function.
 
 ### R CMD check results
 

man/pairs.Rd

@@ -1,5 +1,8 @@
-\name{pairs.profile}
+\name{pairs_profile}
+\alias{pairs_profile}
 \alias{pairs.profile}
+\alias{ellipse-deprecated}
+\alias{pairs}
 \title{
 Profile pairs
 }
@@ -8,14 +11,17 @@ This function produces pairwise plots of profile traces, profile
 sketches, and ellipse approximations to confidence intervals.
 }
 \usage{
-\method{pairs}{profile}(x, labels = c(names(x), "Profile tau"), panel = lines, invert = TRUE, 
+pairs_profile(x, labels = c(names(x), "Profile tau"), panel = lines, invert = TRUE, 
     plot.tau = TRUE, plot.trace = TRUE, plot.sketch = TRUE, 
 	plot.ellipse = FALSE, level = 0.95, \dots)
+	
+# Deprecated generic function.  Use graphics::pairs instead.
+pairs(x, ...)
 }
 \arguments{
 \item{x}{
 An object of class \code{profile}, generally the result of the \code{profile()}
-function.
+function. 
 }
 \item{labels}{
 The labels to use for each variable.  These default to the variable
@@ -53,35 +59,27 @@ profile object.
 This function implements the plots used in Bates and Watts (1988) for
 nonlinear regression diagnostics.
 
-Unfortunately, the \pkg{MASS} package also defines a
-\code{\link[MASS:plot.profile]{pairs.profile}} method.  The \code{ellipse::\link{pairs}}
-generic is supplied to allow users to choose to use
-the version in this package. 
+Prior to \pkg{ellipse} version 0.5,
+the \code{pairs_profile} function was a \code{profile}
+method for the \code{pairs} generic.  This caused
+various conflicts, because \pkg{graphics} also exports a \code{pairs}
+generic, and package \pkg{MASS} exported a \code{profile}
+method for \code{graphics::pairs}.  As of \R version 4.4.0,
+the \pkg{MASS} method will be in \pkg{stats} instead.
 
-If \code{x} is a profile object, then \code{ellipse::pairs(x)} 
-is guaranteed to call the method from this package.  If you'd rather use
-the \pkg{MASS} method, then two steps are needed:  you need to
-be sure that \pkg{MASS} is loaded, then call \code{graphics::pairs(x)}. 
-(If \pkg{MASS} is not loaded, you'll get the default method from the \pkg{graphics} package, which will
-trigger an error since it doesn't know about profile
-objects.)  
-
-If both \pkg{ellipse} and \pkg{MASS} are loaded, then \code{pairs(x)} 
-is slightly ambiguous:  the method that is called depends
-on the ordering of \pkg{ellipse} and \pkg{graphics} (not \pkg{MASS}!) in the search list.  In almost all cases
-\pkg{ellipse} will precede \pkg{graphics}, so the \pkg{ellipse} method will usually be the default.
-
-
-If \code{x} is any object
-other than a profile object, \code{ellipse::pairs(x)}
-will pass the call on to \code{graphics::pairs(x)},
-and the standard method will be called.
+If \code{x} is a profile object then \code{pairs_profile(x)} 
+will call the function from this package.  If you'd rather use
+the \pkg{MASS}/\pkg{stats} method, then make sure the appropriate
+package is loaded, and call \code{pairs(x)}.  (Prior to
+\pkg{ellipse} 0.5, there were complicated rules to determine what
+\code{pairs(x)} would do; those should still work for now, but
+\code{ellipse::pairs} will disappear in a future release.)
 }
 \references{
 Bates and Watts (1988). Nonlinear Regression Analysis and Its Applications. Wiley. \doi{10.1002/9780470316757}.
 }
 \seealso{
-\code{\link{profile}}, \code{\link{ellipse.profile}}, \code{\link{ellipse.nls}}
+\code{\link{pairs}}, \code{\link{profile}}, \code{\link{ellipse.profile}}, \code{\link{ellipse.nls}}
 }
 \examples{
  # Plot everything for the Puromycin data
@@ -90,11 +88,15 @@ Bates and Watts (1988). Nonlinear Regression Analysis and Its Applications. Wile
    * conc)/(K + conc), data = Puromycin,
    start = list(Vm = 160, delV = 40, K = 0.05))
  Pur.prof <- profile(Purboth)
- ellipse::pairs(Pur.prof, plot.ellipse = TRUE)
+ pairs_profile(Pur.prof, plot.ellipse = TRUE)
  
- # Show the corresponding plot from MASS:
- if (requireNamespace("MASS"))
-   graphics::pairs(Pur.prof)
+ # Show the corresponding plot from MASS/stats:
+ if (getRversion() < "4.4.0") {
+   loadNamespace("MASS")
+ } else
+   loadNamespace("stats")
+   
+ graphics::pairs(Pur.prof)
 }
 \keyword{dplot}
 \keyword{regression}