From jfox @ending from mcm@@ter@c@  Mon Dec 17 16:23:07 2018
From: jfox @ending from mcm@@ter@c@ (Fox, John)
Date: Mon, 17 Dec 2018 15:23:07 +0000
Subject: [Rd] Documentation examples for lm and glm
In-Reply-To: <29561_1545059944_wBHFJ3fx032296_c129d4c4-4578-4999-4682-98dbd06dae43@gmx.at>
References: <b0027661-4c72-864d-7dea-a78ade7bf808@auckland.ac.nz>
 <3aee4716-f0d2-c683-0ad8-90ae6c5894ef@gmail.com>
 <b578698e1aac4d26b75c3f2dc0f560cc@GBDCVPEXC04.corp.lgc-group.com>
 <CAARY7khwiMrFAH0NUfhKA=L++xn-ygQHcRng7vojj4epSv36gg@mail.gmail.com>
 <4050_1545033965_wBH8640d000633_23575.22728.140810.518108@stat.math.ethz.ch>
 <6705BFA6-2208-435D-BA4A-8259C80BCA4C@mcmaster.ca>
 <29561_1545059944_wBHFJ3fx032296_c129d4c4-4578-4999-4682-98dbd06dae43@gmx.at>
Message-ID: <5D482A98-398A-4210-AE22-219E9A4A4FD3@mcmaster.ca>

Dear Heinz,

  ----------------------------------------------
> On Dec 17, 2018, at 10:19 AM, Heinz Tuechler <tuechler at gmx.at> wrote:
> 
> Dear All,
> 
> do you think that use of a data argument is best practice in the example below?

No, but it is *normally* or *usually* the best option, in my opinion.

Best,
 John

> 
> regards,
> 
> Heinz
> 
> ### trivial example
> plotwithline <- function(x, y) {
>    plot(x, y)
>    abline(lm(y~x)) ## data argument?
> }
> 
> set.seed(25)
> df0 <- data.frame(x=rnorm(20), y=rnorm(20))
> 
> plotwithline(df0[['x']], df0[['y']])
> 
> 
> 
> Fox, John wrote/hat geschrieben on/am 17.12.2018 15:21:
>> Dear Martin,
>> 
>> I think that everyone agrees that it?s generally preferable to use the data argument to lm() and I have nothing significant to add to the substance of the discussion, but I think that it?s a mistake not to add to the current examples, for the following reasons:
>> 
>> (1) Relegating examples using the data argument to ?see also? doesn?t suggest that using the argument is a best practice. Most users won?t bother to click the links.
>> 
>> (2) In my opinion, an new initial example using the data argument would more clearly suggest that this is the normally the best option.
>> 
>> (3) I think that it would also be desirable to add a remark to the explanation of the data argument, something like, ?Although the argument is optional, it's generally preferable to specify it explicitly.? And similarly on the help page for glm().
>> 
>> My two (or three) cents.
>> 
>> John
>> 
>>  -------------------------------------------------
>>  John Fox, Professor Emeritus
>>  McMaster University
>>  Hamilton, Ontario, Canada
>>  Web: http::/socserv.mcmaster.ca/jfox
>> 
>>> On Dec 17, 2018, at 3:05 AM, Martin Maechler <maechler at stat.math.ethz.ch> wrote:
>>> 
>>>>>>>> David Hugh-Jones
>>>>>>>>   on Sat, 15 Dec 2018 08:47:28 +0100 writes:
>>> 
>>>> I would argue examples should encourage good
>>>> practice. Beginners ought to learn to keep data in data
>>>> frames and not to overuse attach().
>>> 
>>> Note there's no attach() there in any of these examples!
>>> 
>>>> otherwise at their own risk, but they have less need of
>>>> explicit examples.
>>> 
>>> The glm examples are nice in sofar they show both uses.
>>> 
>>> I agree the lm() example(s) are  "didactically misleading" by
>>> not using data frames at all.
>>> 
>>> I disagree that only data frame examples should be shown.
>>> If  lm()  is one of the first R functions a beginneR must use --
>>> because they are in a basic stats class, say --  it may be
>>> *better* didactically to focus on lm()  in the very first
>>> example, and use data frames in a next one ...
>>> .... and instead of next one, we have the pretty clear comment
>>> 
>>> ### less simple examples in "See Also" above
>>> 
>>> I'm not convinced (but you can try more) we should change those
>>> examples or add more there.
>>> 
>>> Martin
>>> 
>>>> On Fri, 14 Dec 2018 at 14:51, S Ellison
>>>> <S.Ellison at lgcgroup.com> wrote:
>>> 
>>>>> FWIW, before all the examples are changed to data frame
>>>>> variants, I think there's fairly good reason to have at
>>>>> least _one_ example that does _not_ place variables in a
>>>>> data frame.
>>>>> 
>>>>> The data argument in lm() is optional. And there is more
>>>>> than one way to manage data in a project. I personally
>>>>> don't much like lots of stray variables lurking about,
>>>>> but if those are the only variables out there and we can
>>>>> be sure they aren't affected by other code, it's hardly
>>>>> essential to create a data frame to hold something you
>>>>> already have.  Also, attach() is still part of R, for
>>>>> those folk who have a data frame but want to reference
>>>>> the contents across a wider range of functions without
>>>>> using with() a lot. lm() can reasonably omit the data
>>>>> argument there, too.
>>>>> 
>>>>> So while there are good reasons to use data frames, there
>>>>> are also good reasons to provide examples that don't.
>>>>> 
>>>>> Steve Ellison
>>>>> 
>>>>> 
>>>>>> -----Original Message----- > From: R-devel
>>>>> [mailto:r-devel-bounces at r-project.org] On Behalf Of Ben >
>>>>> Bolker > Sent: 13 December 2018 20:36 > To:
>>>>> r-devel at r-project.org > Subject: Re: [Rd] Documentation
>>>>> examples for lm and glm
>>>>>> 
>>>>>> 
>>>>>> Agree.  Or just create the data frame with those
>>>>> variables in it > directly ...
>>>>>> 
>>>>>> On 2018-12-13 3:26 p.m., Thomas Yee wrote: > > Hello,
>>>>>>> 
>>>>>>> something that has been on my mind for a decade or
>>>>> two has > > been the examples for lm() and glm(). They
>>>>> encourage poor style > > because of mismanagement of data
>>>>> frames. Also, having the > > variables in a data frame
>>>>> means that predict() > > is more likely to work properly.
>>>>>>> 
>>>>>>> For lm(), the variables should be put into a data
>>>>> frame.  > > As 2 vectors are assigned first in the
>>>>> general workspace they > > should be deleted afterwards.
>>>>>>> 
>>>>>>> For the glm(), the data frame d.AD is constructed but
>>>>> not used. Also, > > its 3 components were assigned first
>>>>> in the general workspace, so they > > float around
>>>>> dangerously afterwards like in the lm() example.
>>>>>>> 
>>>>>>> Rather than attached improved .Rd files here, they
>>>>> are put at > > www.stat.auckland.ac.nz/~yee/Rdfiles > >
>>>>> You are welcome to use them!
>>>>>>> 
>>>>>>> Best,
>>>>>>> 
>>>>>>> Thomas
>>>>>>> 
>>>>>>> ______________________________________________ > >
>>>>> R-devel at r-project.org mailing list > >
>>>>> https://stat.ethz.ch/mailman/listinfo/r-devel
>>>>>> 
>>>>>> ______________________________________________ >
>>>>> R-devel at r-project.org mailing list >
>>>>> https://stat.ethz.ch/mailman/listinfo/r-devel
>>>>> 
>>>>> 
>>>>> *******************************************************************
>>>>> This email and any attachments are confidential. Any
>>>>> u...{{dropped:12}}
>>> 
>>>> ______________________________________________
>>>> R-devel at r-project.org mailing list
>>>> https://stat.ethz.ch/mailman/listinfo/r-devel
>>> 
>>> ______________________________________________
>>> R-devel at r-project.org mailing list
>>> https://stat.ethz.ch/mailman/listinfo/r-devel
>> 
>> ______________________________________________
>> R-devel at r-project.org mailing list
>> https://stat.ethz.ch/mailman/listinfo/r-devel
> 
> ______________________________________________
> R-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel



[Rd] Documentation examples for lm and glm
Fox, John