[Rd] RFC: sigma() in package:stats ?

[Martin Maechler]

I'm proposing to add something like this to the  stats package :

----------------------------------------------------------

### "The" sigma in lm/nls - "like" models:

sigma <- function(object, ...) UseMethod("sigma")

## works whenever deviance(), nobs() and coef() do fine:
sigma.default <- function (object, use.fallback=TRUE, ...)
    sqrt(deviance(object, ...) /
             (nobs(object, use.fallback=use.fallback) - length(coef(object))))

----------------------------------------------------------

[Yes, even though I am known to love S4 classes, and also
 methods, I propose an S3 generic here because it should go
 along with other typical S3 generics and methods, such as 
 coef(), vcov(), ...
]

The main reason/motivation for (something like) this is to
provide encapsulation / abstraction for the following :

Different (S3 and S4) fitted model objects use different ways to store
the \hat\sigma (or \sqrt{\hat{\sigma^2}} - formally not quite
the same !) as part of their object, and if I use methods which
compare models, putting these into tables, etc,
it is much nicer to use sigma(.) instead of having to use
model-specific extractors.

If I'm searching in our large collection of installed packages,
I'm seeing

  > help.search("^sigma$")
  Help files with alias or concept or title matching ‘^sigma$’ using regular
  expression matching:


  AdaptFitOS::sigma           Extract estimated varying residual variance
    Aliases: sigma
  distrEllipse::MVNormParameter-class
			      Paramter of a multivariate normal distribution
    Aliases: sigma
  dlmodeler::dlmodeler.fit    Fitting function for a model (MLE, MSE, MAD, sigma)
    Concepts: sigma
  elliptic::WeierstrassP      Weierstrass P and related functions
    Aliases: sigma
  gcExplorer::sigma           E. coli Sigma Factors and Global Regulators
    Aliases: sigma
  investr::Sigma              Extract residual standard error
    Aliases: Sigma
  lme4::sigma                 Extract residual standard error
    Aliases: sigma
  mbest::predict.mhglm        Prediction
    Aliases: sigma
  nlmeU::sigma                Extract scale parameter sigma from a model fit
    Aliases: sigma
  numbers::sigma              Divisor Functions
    Aliases: sigma
  pmclust::PARAM              A Set of Parameters in Model-Based Clustering.
    Aliases: SIGMA
  qualityTools::sigma         Get and set methods
    Aliases: sigma
  robustbase::sigma           Extract Residual Standard Error 'Sigma'
    Aliases: sigma
  rugarch::uGARCHfit-class    class: Univariate GARCH Fit Class
    Aliases: sigma
  shapes::distCholesky        Internal function(s)
    Aliases: sigma

which also shows to the curious why I am making this
proposition: I'm co-author of both the  'lme4' and 'robustbase' packages
which already make use of this.

Note that the default method would already work for
lm(), nls(), and (some) glm() model fits.
It may still make sense to use a slightly faster more explicit 
sigma.ls() method,  but that's not the topic of this
conversation, I think.

Martin Maechler,
ETH Zurich and R Core