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

[Martin Maechler]

>>>>> Ben Bolker 
>>>>>     on Sun, 3 Jun 2018 17:33:18 -0400 writes:

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

This rings a faint bell from the last millennium with me,
and the following "fortune"  may contain the answer implicitly :

------------------------------------------------------------
  > if(!require("fortunes")) install.packages("fortunes")
  > fortune("bug compatib")

  For quite a while, bug-for-bug compatibility with S-PLUS v 3.x was considered
  important to allow people to port their packages between systems.
     -- Peter Dalgaard
	R-help (February 2009)
  > 
------------------------------------------------------------

Ideally, readers who still have access to a version of S-PLUS / S+
or who have read and internalized or (even co-written !)
"The white book", notably Ch.6, may be able to shed a historic
light on this.

I note that the white book's Appendix B with function help
pages, has a page ?family.object,  accessible here
   https://sites.oxy.edu/lengyel/M150/Sueselbeck/helpfiles/family.object.html

which does *not* mention a  <fam>$dev.resid() component, but instead
allows to use  <fam>$residuals(*, residuals=TRUE)
get the
"
  vector of deviance residual, whose weighted sum of
  squares is the deviance
"

Given the above, and also the ?glm entry

|| Author(s):
|| 
||      The original R implementation of ‘glm’ was written by Simon Davies
||      working for Ross Ihaka at the University of Auckland, but has
||      since been extensively re-written by members of the R Core team.
|| 
||      The design was inspired by the S function of the same name
||      described in Hastie & Pregibon (1992).

actually suggest that it may be hard nowadays to find the
original "design specs" that Simon and Ross had used at the
time, and also that they only were _inspired_ by the white book
chapter 6 (= Hastie & Pregibon (1992)).



    > Can anyone in this forum gauge how a documentation patch
    > would be received?

It depends on further answers to your questions (i.e, this
thread), but I'd currently say  "gratefully".
I'd expect it would be a patch mainly to
  src/library/stats/man/family.Rd

Note that help(AIC) has a non-small 'Details' section, but
indeed it does not mention the family(*)$aic function.

    > 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