[Rd] aic() component in GLM-family objects

[Ben Bolker]

  Is it generally known/has it been previously discussed here that the
$aic() component in GLM-family objects (e.g. results of binomial(),
poisson(), etc.) does not as implemented actually return the AIC, but
rather -2*log-likelihood + 2*(model_has_scale_parameter) ?  Can anyone
in this forum gauge how a documentation patch would be received?

This behaviour does not seem to be documented in ?family (or anywhere
else I can find), which says:

  aic: function giving the AIC value if appropriate (but ‘NA’ for
          the quasi- families).  See ‘logLik’ for the assumptions made
          about the dispersion parameter.

For a demonstration that e.g. binomial()$aic() is really -2*log L and
not the AIC, see:

https://github.com/wch/r-source/blob/trunk/src/library/stats/R/family.R#L317

This document
  <https://github.com/lme4/lme4/blob/master/misc/notes/deviance.rmd>
explicates the details a bit more ('L' denotes log-likelihood):

   * family()$aic computes $-2L$, which glm.fit translates to an AIC by
adding $2k$ and storing it in model$aic
   * logLik.default retrieves model$aic and converts it back to a
log-likelihood
   * stats:::AIC.default retrieves the log-likelihood and converts it
back to an AIC (!)
   * family()$dev.resid() computes the squared deviance residuals
   * stats:::residuals.glm retrieves these values and takes the signed
square root

  cheers
    Ben Bolker