R devel - Feb 2023 - Documentation bug?

Dead R developers,

In R-devel  2023-02-11 and older R versions, there is a note in the "lm
{stats}" help page specifying that:
> Offsets specified by offset will not be included in predictions by
predict.lm<http://127.0.0.1:12534/library/stats/help/predict.lm>, whereas
those specified by an offset term in the formula will be.
However, the source code as well as basic tests seem to show that both types of
offset terms are always used in predictions.
a<-data.frame(off=1:4, outcome=4:1)
mod<-lm(data=a, outcome~1, offset=off)
coef(a) # intercept is zero
predict(mod) # returns 1:4, which uses offset
predict(mod, newdata=data.frame(off=c(3,2,5))) # returns c(3,2,5) which uses the
new offset

When looking at the history of R source code, this note seems to exist from R
1.0.0 while the source code of predict.lm already called
eval(object$call$offset, newdata)
https://github.com/SurajGupta/r-source/blob/1.0.0/src/library/base/R/lm.R
https://github.com/SurajGupta/r-source/blob/1.0.0/src/library/base/man/lm.Rd

Version 0.99.0 did not contain the note, but already had the call to
eval(object$call$offset, newdata)
https://github.com/SurajGupta/r-source/blob/0.99.0/src/library/base/man/lm.Rd
https://github.com/SurajGupta/r-source/blob/0.99.0/src/library/base/R/lm.R

The actual behavior of R seems to be sane to me, but unless I miss something,
this looks like a documentation bug.
It seems to have bugged someone before:
https://stackoverflow.com/questions/71264495/why-is-predict-not-ignoring-my-offset-from-a-poisson-model-in-r-no-matter-how-i

Digging deeper in R history, it seems that this note was also found in "glm
{stats}" in R 1.0.0 but was removed in R 1.4.1. Maybe somebody forgot to
remove it in "lm {stats}" too.

--
Sincerely
Andr? GILLIBERT

	[[alternative HTML version deleted]]

Thanks. The note is indeed outdated since at least R 2.9.0 with NEWS

     o	predict.lm() now works correctly when the fit had more than
	one offset (possibly specified both in the formula and as an
	argument).  This function is called by predict.glm(), so the
	same isses are corrected there.

It has now been removed from ?lm in r83832 in the trunk (ported to 
R-patched).

	Sebastian Meyer


Am 14.02.23 um 09:31 schrieb GILLIBERT, Andre via
R-devel:
> Dead R developers,
> 
> In R-devel  2023-02-11 and older R versions, there is a note in the
"lm {stats}" help page specifying that:
>> Offsets specified by offset will not be included in predictions by
predict.lm<http://127.0.0.1:12534/library/stats/help/predict.lm>, whereas
those specified by an offset term in the formula will be.
> 
> However, the source code as well as basic tests seem to show that both
types of offset terms are always used in predictions.
> a<-data.frame(off=1:4, outcome=4:1)
> mod<-lm(data=a, outcome~1, offset=off)
> coef(a) # intercept is zero
> predict(mod) # returns 1:4, which uses offset
> predict(mod, newdata=data.frame(off=c(3,2,5))) # returns c(3,2,5) which
uses the new offset
> 
> When looking at the history of R source code, this note seems to exist from
R 1.0.0 while the source code of predict.lm already called
eval(object$call$offset, newdata)
> https://github.com/SurajGupta/r-source/blob/1.0.0/src/library/base/R/lm.R
>
https://github.com/SurajGupta/r-source/blob/1.0.0/src/library/base/man/lm.Rd
> 
> Version 0.99.0 did not contain the note, but already had the call to
eval(object$call$offset, newdata)
>
https://github.com/SurajGupta/r-source/blob/0.99.0/src/library/base/man/lm.Rd
> https://github.com/SurajGupta/r-source/blob/0.99.0/src/library/base/R/lm.R
> 
> The actual behavior of R seems to be sane to me, but unless I miss
something, this looks like a documentation bug.
> It seems to have bugged someone before:
>
https://stackoverflow.com/questions/71264495/why-is-predict-not-ignoring-my-offset-from-a-poisson-model-in-r-no-matter-how-i
> 
> Digging deeper in R history, it seems that this note was also found in
"glm {stats}" in R 1.0.0 but was removed in R 1.4.1. Maybe somebody
forgot to remove it in "lm {stats}" too.
> 
> --
> Sincerely
> Andr? GILLIBERT
> 
> 	[[alternative HTML version deleted]]
> 
> 
> ______________________________________________
> R-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel