R help - Apr 2003 - good source for explaining input and output parameters of R functions

Hello,
   thank you all for answering my previous Qs.. I have a new Q:
   I am wondering is there good source for explaning input and output
parameters of R function?
  In that aspect, I found the help documents in R is not that helpful:)
I am struggling with trying to understand what some of the returned value
means..
for example, for surf.ls() function, the help in R only describes 3
fields(the wierd thing is that those explained 3 fields are identical to
the input) of returned value, and leave a bunch of others(e.g., like
"f"
and "wz"which looks pretty interesting, but i had no clue what they
are
about..) unexplained.

Is there any good source if I want to understand the input and output of ,
or how to use a particular R function?

Many thanks,
yan

It's almost entirely up to the author of the function how much (or little)
to document in the help page.  Packages on CRAN go through some checks, one
of which is that all parameters of functions are documented in the help
page.  However, the return value is another matter.  It's supposed to be
documented in the "Value" section of the help page, but some people
don't
bother documenting everything being returned, sometimes because some of them
weren't meant to be used by user directly.

When all else fails, read the R code itself.

HTH,
Andy
> -----Original Message-----
> From: Yan Yu [mailto:yanyu at cs.ucla.edu]
> Sent: Wednesday, April 16, 2003 7:39 PM
> To: r-help at stat.math.ethz.ch
> Subject: [R] good source for explaining input and output 
> parameters of R
> functions
> 
> 
> Hello,
>    thank you all for answering my previous Qs.. I have a new Q:
>    I am wondering is there good source for explaning input and output
> parameters of R function?
>   In that aspect, I found the help documents in R is not that 
> helpful:)
> I am struggling with trying to understand what some of the 
> returned value
> means..
> for example, for surf.ls() function, the help in R only describes 3
> fields(the wierd thing is that those explained 3 fields are 
> identical to
> the input) of returned value, and leave a bunch of 
> others(e.g., like "f"
> and "wz"which looks pretty interesting, but i had no clue 
> what they are
> about..) unexplained.
> 
> Is there any good source if I want to understand the input 
> and output of ,
> or how to use a particular R function?
> 
> Many thanks,
> yan
> 
> ______________________________________________
> R-help at stat.math.ethz.ch mailing list
> https://www.stat.math.ethz.ch/mailman/listinfo/r-help
>

If certain elements returned by a function are not documented, they are
unlikely to be of much use to the user.  In particular, the help page for
surf.ls() says:

Value:

     list with components

    beta: the coefficients 

       x: 

       y: 

       z: and others for internal use only. 
          

So there are other elements returned but they are only used for internal
computations or whatever.  The user will likely not need them or even be
able to use them intelligently.

If you really want to know what all of the returned values are, the best
place to look is the source code.

-roger
_______________________________
UCLA Department of Statistics
http://www.stat.ucla.edu/~rpeng

On Wed, 16 Apr 2003, Yan Yu wrote:
> Hello,
>    thank you all for answering my previous Qs.. I have a new Q:
>    I am wondering is there good source for explaning input and output
> parameters of R function?
>   In that aspect, I found the help documents in R is not that helpful:)
> I am struggling with trying to understand what some of the returned value
> means..
> for example, for surf.ls() function, the help in R only describes 3
> fields(the wierd thing is that those explained 3 fields are identical to
> the input) of returned value, and leave a bunch of others(e.g., like
"f"
> and "wz"which looks pretty interesting, but i had no clue what
they are
> about..) unexplained.
> 
> Is there any good source if I want to understand the input and output of ,
> or how to use a particular R function?
> 
> Many thanks,
> yan
> 
> ______________________________________________
> R-help at stat.math.ethz.ch mailing list
> https://www.stat.math.ethz.ch/mailman/listinfo/r-help
>

I forgot to mention this: It may be unsafe to use undocumented
 part of returned value.  One possible reason that some parts 
are not documented is that they are subject to change without 
notice, and not considered part of the API.

Andy
> From: Liaw, Andy [mailto:andy_liaw at merck.com]
> 
> It's almost entirely up to the author of the function how 
> much (or little)
> to document in the help page.  Packages on CRAN go through 
> some checks, one
> of which is that all parameters of functions are documented 
> in the help
> page.  However, the return value is another matter.  It's 
> supposed to be
> documented in the "Value" section of the help page, but some 
> people don't
> bother documenting everything being returned, sometimes 
> because some of them
> weren't meant to be used by user directly.
> 
> When all else fails, read the R code itself.
> 
> HTH,
> Andy
> 
> > -----Original Message-----
> > From: Yan Yu [mailto:yanyu at cs.ucla.edu]
> > Sent: Wednesday, April 16, 2003 7:39 PM
> > To: r-help at stat.math.ethz.ch
> > Subject: [R] good source for explaining input and output 
> > parameters of R
> > functions
> > 
> > 
> > Hello,
> >    thank you all for answering my previous Qs.. I have a new Q:
> >    I am wondering is there good source for explaning input 
> and output
> > parameters of R function?
> >   In that aspect, I found the help documents in R is not that 
> > helpful:)
> > I am struggling with trying to understand what some of the 
> > returned value
> > means..
> > for example, for surf.ls() function, the help in R only describes 3
> > fields(the wierd thing is that those explained 3 fields are 
> > identical to
> > the input) of returned value, and leave a bunch of 
> > others(e.g., like "f"
> > and "wz"which looks pretty interesting, but i had no clue 
> > what they are
> > about..) unexplained.
> > 
> > Is there any good source if I want to understand the input 
> > and output of ,
> > or how to use a particular R function?
> > 
> > Many thanks,
> > yan
> > 
> > ______________________________________________
> > R-help at stat.math.ethz.ch mailing list
> > https://www.stat.math.ethz.ch/mailman/listinfo/r-help
> >
> 
> ______________________________________________
> R-help at stat.math.ethz.ch mailing list
> https://www.stat.math.ethz.ch/mailman/listinfo/r-help
> 
> 
> --------------------------------------------------------------
> ----------------
> Notice:  This e-mail message, together with any attachments, 
> contains information of Merck & Co., Inc. (Whitehouse 
> Station, New Jersey, USA) that may be confidential, 
> proprietary copyrighted and/or legally privileged, and is 
> intended solely for the use of the individual or entity named 
> in this message.  If you are not the intended recipient, and 
> have received this message in error, please immediately 
> return this by e-mail and then delete it.
> 
> =============================================================>
===============>

1) surf.ls is not part of R: it is in package spatial.

2) Its help page does explain *4* fields in the value, and says

       `and others for internal use only.'

That means what it says: they are not for use by you, and hence not
documented.

I think you have unrealistic expectations: my uncredited software was
written to support a book (see its DESCRIPTION file), and the *book* does
explain how it works. All you need to do is to buy the book ... or read the
sources, as R is Open Source and that package is GPL-ed.


On Wed, 16 Apr 2003, Yan Yu wrote:
> Hello,
>    thank you all for answering my previous Qs.. I have a new Q:
>    I am wondering is there good source for explaning input and output
> parameters of R function?
>   In that aspect, I found the help documents in R is not that helpful:)
> I am struggling with trying to understand what some of the returned value
> means..
> for example, for surf.ls() function, the help in R only describes 3
> fields(the wierd thing is that those explained 3 fields are identical to
> the input) of returned value, and leave a bunch of others(e.g., like
"f"
> and "wz"which looks pretty interesting, but i had no clue what
they are
> about..) unexplained.
>
> Is there any good source if I want to understand the input and output of ,
> or how to use a particular R function?
>
> Many thanks,
> yan
>
> ______________________________________________
> R-help at stat.math.ethz.ch mailing list
> https://www.stat.math.ethz.ch/mailman/listinfo/r-help
>
-- 
Brian D. Ripley,                  ripley at stats.ox.ac.uk
Professor of Applied Statistics,  http://www.stats.ox.ac.uk/~ripley/
University of Oxford,             Tel:  +44 1865 272861 (self)
1 South Parks Road,                     +44 1865 272860 (secr)
Oxford OX1 3TG, UK                Fax:  +44 1865 272595