Request: Documentation of formulae

classic Classic list List threaded Threaded
8 messages Options
Reply | Threaded
Open this post in threaded view
|

Request: Documentation of formulae

Mike Prager
In working through material on p.272 of MASS (4th ed.), I came
across the following model formula:

pet1.lm <- lm(Y ~ No/EP - 1, Petrol)

I was at a loss to understand the use of "/" until I looked in
"An Introduction [!] to R," where I found the explanation.

My request is that more complete material on model formulae be
lifted from "Introduction to R" (or elsewhere) and put into the
main online help files. There are other useful notations that
may not be well known. Since formulae are not limited to any
particular function, perhaps an entry could be made under
"Formula".

More justification:

The help for "lm" does not explain this notation, nor did I find
a cross-reference to anything useful there. The R Reference
Manual seems to explain functions only. The R Language
Definition has no index entry for "formula" or "model formulae".

Looking to print, neither the section on "model formula" on p.56
of MASS nor the section surrounding the above example explains
the notation, nor could I find it in Dalgaard's book, nor in
Maindonald and Braun.  

This seems too nice a feature to keep hidden in plain sight.

--
Mike Prager, NOAA, Beaufort, NC
* Opinions expressed are personal and not represented otherwise.
* Any use of tradenames does not constitute a NOAA endorsement.

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: Request: Documentation of formulae

markleeds
  This isn't particularly helpful because the book is  quite old but
formula notation/functionality is covered in depth in "Statistical
Models in S" by
Chambers and Hastie.  My guess is that there is strong consistency
between what is said in there and how things work in R.



On Fri, May 30, 2008 at  4:19 PM, Mike Prager wrote:

> In working through material on p.272 of MASS (4th ed.), I came
> across the following model formula:
>
> pet1.lm <- lm(Y ~ No/EP - 1, Petrol)
>
> I was at a loss to understand the use of "/" until I looked in
> "An Introduction [!] to R," where I found the explanation.
> My request is that more complete material on model formulae be
> lifted from "Introduction to R" (or elsewhere) and put into the
> main online help files. There are other useful notations that
> may not be well known. Since formulae are not limited to any
> particular function, perhaps an entry could be made under
> "Formula".
>
> More justification:
>
> The help for "lm" does not explain this notation, nor did I find
> a cross-reference to anything useful there. The R Reference
> Manual seems to explain functions only. The R Language
> Definition has no index entry for "formula" or "model formulae".
>
> Looking to print, neither the section on "model formula" on p.56
> of MASS nor the section surrounding the above example explains
> the notation, nor could I find it in Dalgaard's book, nor in
> Maindonald and Braun.
> This seems too nice a feature to keep hidden in plain sight.
>
> --
> Mike Prager, NOAA, Beaufort, NC
> * Opinions expressed are personal and not represented otherwise.
> * Any use of tradenames does not constitute a NOAA endorsement.
>
> ______________________________________________
> [hidden email] mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: Request: Documentation of formulae

Mark Difford
In reply to this post by Mike Prager
Hi Mike,

>> I was at a loss to understand the use of "/" until I looked in "An Introduction [!] to R,"
>> where I found the explanation.

I am not with you on the [!], because the information is basically where you are "complaining" that it isn't, viz in your face --- i.e. in the introductory document ---, but the operator surely deserves a mention in ?formula.  So on that score I agree with you.

Best, Mark.

Mike Prager wrote
In working through material on p.272 of MASS (4th ed.), I came
across the following model formula:

pet1.lm <- lm(Y ~ No/EP - 1, Petrol)

I was at a loss to understand the use of "/" until I looked in
"An Introduction [!] to R," where I found the explanation.

My request is that more complete material on model formulae be
lifted from "Introduction to R" (or elsewhere) and put into the
main online help files. There are other useful notations that
may not be well known. Since formulae are not limited to any
particular function, perhaps an entry could be made under
"Formula".

More justification:

The help for "lm" does not explain this notation, nor did I find
a cross-reference to anything useful there. The R Reference
Manual seems to explain functions only. The R Language
Definition has no index entry for "formula" or "model formulae".

Looking to print, neither the section on "model formula" on p.56
of MASS nor the section surrounding the above example explains
the notation, nor could I find it in Dalgaard's book, nor in
Maindonald and Braun.  

This seems too nice a feature to keep hidden in plain sight.

--
Mike Prager, NOAA, Beaufort, NC
* Opinions expressed are personal and not represented otherwise.
* Any use of tradenames does not constitute a NOAA endorsement.

______________________________________________
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Mark Difford (Ph.D.)
Research Associate
Botany Department
Nelson Mandela Metropolitan University
Port Elizabeth, South Africa
Reply | Threaded
Open this post in threaded view
|

Re: Request: Documentation of formulae

Mike Prager
In reply to this post by Mike Prager
Mike Prager <[hidden email]> wrote:

> I was at a loss to understand the use of "/" until I looked in
> "An Introduction [!] to R," where I found the explanation.
>
> My request is that more complete material on model formulae be
> lifted from "Introduction to R" (or elsewhere) and put into the
> main online help files.

I also request the R Core consider remaining "An Introduction to
R" to something like "R User's Guide." It spans 100 pages and
treats many topics far beyond the introductory level. I was
surprised at the wealth of information it contains, and I expect
that I would have checked it first, not last, among available
resources had it been more accurately named.

--
Mike Prager, NOAA, Beaufort, NC
* Opinions expressed are personal and not represented otherwise.
* Any use of tradenames does not constitute a NOAA endorsement.

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: Request: Documentation of formulae

Martin Maechler
>>>>> "MP" == Mike Prager <[hidden email]>
>>>>>     on Mon, 02 Jun 2008 16:29:16 -0400 writes:

    MP> Mike Prager <[hidden email]> wrote:
    >> I was at a loss to understand the use of "/" until I looked in
    >> "An Introduction [!] to R," where I found the explanation.
    >>
    >> My request is that more complete material on model formulae be
    >> lifted from "Introduction to R" (or elsewhere) and put into the
    >> main online help files.

    MP> I also request the R Core consider remaining "An Introduction to
    MP> R" to something like "R User's Guide." It spans 100 pages and
    MP> treats many topics far beyond the introductory level. I was
    MP> surprised at the wealth of information it contains, and I expect
    MP> that I would have checked it first, not last, among available
    MP> resources had it been more accurately named.

Hi Mike, you make very worthy suggestions; but I assume the word
"request" is really putting off almost all of us "R corers".
You *have* heard that R is a volunteer project, that much of its
development has happened in unpaid time of core team mates.
Why are you not using "Suggestion" instead?

Also, since it's a volunteer project, and you are a capable R
user, you could even consider sending patches, e.g. to the
formula.Rd  help page.

At last, to the renaming suggestion: I see your point, but

1) in "an Intro" one is allowed to be non-comprehensive
   where as a "user's guide" is supposedly touching almost
   everything relevant.  This is not the case, since R has much
   evolved since the "An Intro .." had been compiled, and most
   new features are not mentioned in the intro.

2) I don't know your background, but in the math sciences, there
   exist quite a few comprehensive textbooks called "An
   Introduction to ...".
   One example from my bookshelf is
   @BOOK{AndT84,
     author = {T. W. Anderson},
     title = {An Introduction to Multivariate Statistical Analysis},
     publisher = Wiley,
     address = NY,
     year = 1984
   }


3) "An Introduction to R" is mentioned in many many pieces of
   documentation about R; from instructions to students, to
   online guides, to books, etc.

   For this reason, a new title should reall still contain the
   term.

   Maybe simply
        "An Introduction to R --- User's guide"
?
   
Best regards,
Martin Maechler, ETH Zurich

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: Request: Documentation of formulae

slre
In reply to this post by Mike Prager
Rather than transport quantities of the Introduction to R (a perfectly
sensible title for a very good starting point, IMHO) would it not be
simpler and involve less maintenance to include a link or
cross-reference in the 'formula' help page to the relevant part of the
Introduction? If nothing else, that might get folk to look at the
Introduction if they've bypassed it ....

Steve E

>>> Martin Maechler <[hidden email]> 03/06/2008 07:48:46
>>>
>>>>> "MP" == Mike Prager <[hidden email]>
    MP> Mike Prager <[hidden email]> wrote:
    >> I was at a loss to understand the use of "/" until I looked in
    >> "An Introduction [!] to R," where I found the explanation.
    >>
    >> My request is that more complete material on model formulae be
    >> lifted from "Introduction to R" (or elsewhere) and put into the
    >> main online help files.


*******************************************************************
This email and any attachments are confidential. Any use...{{dropped:8}}

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: Request: Documentation of formulae

Duncan Murdoch
S Ellison wrote:
> Rather than transport quantities of the Introduction to R (a perfectly
> sensible title for a very good starting point, IMHO) would it not be
> simpler and involve less maintenance to include a link or
> cross-reference in the 'formula' help page to the relevant part of the
> Introduction? If nothing else, that might get folk to look at the
> Introduction if they've bypassed it ....
>  

Yes, that would be much simpler.  I am hoping that help.search() will
soon be able to look through the indices and tables of contents of the
manuals, so that will be another way to discover the documentation.

Changing the title of the manual would be an unreasonable solution: it
affects authors of dozens of books, not just R Core, who all have to
track down every reference to the old title and write some ugly
disjunction instead.

Duncan Murdoch

> Steve E
>
>  
>>>> Martin Maechler <[hidden email]> 03/06/2008 07:48:46
>>>>
>>>>        
>>>>>> "MP" == Mike Prager <[hidden email]>
>>>>>>            
>     MP> Mike Prager <[hidden email]> wrote:
>     >> I was at a loss to understand the use of "/" until I looked in
>     >> "An Introduction [!] to R," where I found the explanation.
>     >>
>     >> My request is that more complete material on model formulae be
>     >> lifted from "Introduction to R" (or elsewhere) and put into the
>     >> main online help files.
>
>
> *******************************************************************
> This email and any attachments are confidential. Any use...{{dropped:8}}
>
> ______________________________________________
> [hidden email] mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
>

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: Request: Documentation of formulae

Mike Prager
In reply to this post by Martin Maechler
Martin Maechler <[hidden email]> wrote:

> Hi Mike, you make very worthy suggestions; but I assume the word
> "request" is really putting off almost all of us "R corers".
> You *have* heard that R is a volunteer project, that much of its
> development has happened in unpaid time of core team mates.
> Why are you not using "Suggestion" instead?

Dear Martin,

Thank you for alerting me that my comments could so easily be
taken differently from my intent.  The comments were indeed put
forth as suggestions.

Thanks also for the characterization as a competent R user.  I
may be that, or nearly so, but time and other resources don't
allow me to contribute changes now. Perhaps in future I will be
in a better position to do so.

With appreciation for R and R-Core,

Mike

--
Mike Prager, NOAA, Beaufort, NC
* Opinions expressed are personal and not represented otherwise.
* Any use of tradenames does not constitute a NOAA endorsement.

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel