[Rd] help files for load and related functions
I recently had a discussion with a user about loading and attaching in R. I was surprised that the help files don't provide a very clear picture. From my point of view 'load' and 'attach' are very similar operations, the difference being that 'attach' creates a new database on the search list while 'load' puts all the objects into the global environment. The help file for 'load' is inexplicit that this is what happens. The 'load' and 'attach' help files neither refer to the other in their See Also. Furthermore, the 'library' help file talks about loading packages. I would suggest that it should use attaching as that is the analogous operation. None of these three help files (nor that of 'save') has a Side Effects section. Personally I think that all help files should have a Side Effects section (to make it clear to new users what side effects are and that they are not a good thing for most functions to have). I can understand there could be another point of view on that. However, I definitely think that there should be a Side Effects section in the help files of functions whose whole point is a side effect. Patrick Burns [EMAIL PROTECTED] +44 (0)20 8525 0696 http://www.burns-stat.com (home of S Poetry and A Guide for the Unwilling S User) __ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] help files for load and related functions
On 12/17/2007 6:00 AM, Patrick Burns wrote: I recently had a discussion with a user about loading and attaching in R. I was surprised that the help files don't provide a very clear picture. From my point of view 'load' and 'attach' are very similar operations, the difference being that 'attach' creates a new database on the search list while 'load' puts all the objects into the global environment. The help file for 'load' is inexplicit that this is what happens. The 'load' and 'attach' help files neither refer to the other in their See Also. Furthermore, the 'library' help file talks about loading packages. I would suggest that it should use attaching as that is the analogous operation. None of these three help files (nor that of 'save') has a Side Effects section. Personally I think that all help files should have a Side Effects section (to make it clear to new users what side effects are and that they are not a good thing for most functions to have). I can understand there could be another point of view on that. However, I definitely think that there should be a Side Effects section in the help files of functions whose whole point is a side effect. I think you make good points. Care to submit patches? The source for those man pages are in https://svn.R-project.org/R/trunk/src/library/base/man/attach.Rd https://svn.R-project.org/R/trunk/src/library/base/man/library.Rd https://svn.R-project.org/R/trunk/src/library/base/man/load.Rd https://svn.R-project.org/R/trunk/src/library/base/man/save.Rd If you send them to me before Thursday or after Jan 2, I'll take a look. (If you send them to me during the Xmas break there's a good chance they'll get lost.) Duncan Murdoch __ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] help files for load and related functions
Dear Patrick, Firstly, and most importantly, I do not think that your post qualified for Rd! Please use the correct mail list for such things: R-help. I do not think anybody on Rd wants mailboxes clogged with irrelevant messages. Back to your question: it is not clear if you are confused, or your 'user' is confused, but all three help pages look pretty clear and straight forward to me. Moreover, I do not see any connection between attach and library, which you find logical: - load - the general use of this one is to load external data sets, e.g. load serialised R object(s) (as the example shows). Until you load, you cannot use the object as it has no relation to the R session and can be e.g. a file sitting somewhere on a network - attach - the general use of this one would be to access elements of a data set directly, without the data set name specifier and the accessor operator, such as $, thus as the help page states - it is used to add the data set to the search path (as the example shows). If you look at the example, you do not have to call attach to be able to use data, data could have existed there before and what you effectively get with attach is a more convenient way of dealing with the data - library - is used to load *and* attach an R package, which is not exactly the same as a serialised R object(s), but a full set of other functionality. Attaching packages is just a part of the loading process, which occurs basically when the package becomes visible to the user. Same as with load, you cannot use the package until you load it. There is not a hint of similarity between loading a package and attaching a data set as I see it. Regards, Oleg On Mon, 2007-12-17 at 11:00 +, Patrick Burns wrote: I recently had a discussion with a user about loading and attaching in R. I was surprised that the help files don't provide a very clear picture. From my point of view 'load' and 'attach' are very similar operations, the difference being that 'attach' creates a new database on the search list while 'load' puts all the objects into the global environment. The help file for 'load' is inexplicit that this is what happens. The 'load' and 'attach' help files neither refer to the other in their See Also. Furthermore, the 'library' help file talks about loading packages. I would suggest that it should use attaching as that is the analogous operation. None of these three help files (nor that of 'save') has a Side Effects section. Personally I think that all help files should have a Side Effects section (to make it clear to new users what side effects are and that they are not a good thing for most functions to have). I can understand there could be another point of view on that. However, I definitely think that there should be a Side Effects section in the help files of functions whose whole point is a side effect. Patrick Burns [EMAIL PROTECTED] +44 (0)20 8525 0696 http://www.burns-stat.com (home of S Poetry and A Guide for the Unwilling S User) __ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel -- Dr Oleg Sklyar * EBI-EMBL, Cambridge CB10 1SD, UK * +44-1223-494466 __ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] help files for load and related functions
On Mon, 2007-12-17 at 14:06 +, Oleg Sklyar wrote: Dear Patrick, Firstly, and most importantly, I do not think that your post qualified for Rd! Please use the correct mail list for such things: R-help. I do not think anybody on Rd wants mailboxes clogged with irrelevant messages. No. R Devel *is* the correct place for this discussion, as it pertains to the development of R. Patrick is reporting that he found the current help for load(), attach() etc lacking explicit statements about what R actually does when you call them, and how the functions differ in their side effects, especially from the point of view of a new user. The reason for your comment above is perhaps related to the one below my text; Patrick _isn't_ looking for help, just pointing out an infelicity in the current documentation as identified by the user, and, I suspect, welcoming comment on his suggestions for changes. G Back to your question: it is not clear if you are confused, or your 'user' is confused, but all three help pages look pretty clear and straight forward to me. Moreover, I do not see any connection between attach and library, which you find logical: - load - the general use of this one is to load external data sets, e.g. load serialised R object(s) (as the example shows). Until you load, you cannot use the object as it has no relation to the R session and can be e.g. a file sitting somewhere on a network - attach - the general use of this one would be to access elements of a data set directly, without the data set name specifier and the accessor operator, such as $, thus as the help page states - it is used to add the data set to the search path (as the example shows). If you look at the example, you do not have to call attach to be able to use data, data could have existed there before and what you effectively get with attach is a more convenient way of dealing with the data - library - is used to load *and* attach an R package, which is not exactly the same as a serialised R object(s), but a full set of other functionality. Attaching packages is just a part of the loading process, which occurs basically when the package becomes visible to the user. Same as with load, you cannot use the package until you load it. There is not a hint of similarity between loading a package and attaching a data set as I see it. Regards, Oleg On Mon, 2007-12-17 at 11:00 +, Patrick Burns wrote: I recently had a discussion with a user about loading and attaching in R. I was surprised that the help files don't provide a very clear picture. From my point of view 'load' and 'attach' are very similar operations, the difference being that 'attach' creates a new database on the search list while 'load' puts all the objects into the global environment. The help file for 'load' is inexplicit that this is what happens. The 'load' and 'attach' help files neither refer to the other in their See Also. Furthermore, the 'library' help file talks about loading packages. I would suggest that it should use attaching as that is the analogous operation. None of these three help files (nor that of 'save') has a Side Effects section. Personally I think that all help files should have a Side Effects section (to make it clear to new users what side effects are and that they are not a good thing for most functions to have). I can understand there could be another point of view on that. However, I definitely think that there should be a Side Effects section in the help files of functions whose whole point is a side effect. Patrick Burns [EMAIL PROTECTED] +44 (0)20 8525 0696 http://www.burns-stat.com (home of S Poetry and A Guide for the Unwilling S User) __ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel -- %~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~% Dr. Gavin Simpson [t] +44 (0)20 7679 0522 ECRC, UCL Geography, [f] +44 (0)20 7679 0565 Pearson Building, [e] gavin.simpsonATNOSPAMucl.ac.uk Gower Street, London [w] http://www.ucl.ac.uk/~ucfagls/ UK. WC1E 6BT. [w] http://www.freshwaters.org.uk %~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~% __ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] help files for load and related functions
Patches to the help files sound like a good idea. However, it isn't something I'm likely to get to immediately. I'm hoping that some other nice person will volunteer. Pat Duncan Murdoch wrote: On 12/17/2007 6:00 AM, Patrick Burns wrote: I recently had a discussion with a user about loading and attaching in R. I was surprised that the help files don't provide a very clear picture. From my point of view 'load' and 'attach' are very similar operations, the difference being that 'attach' creates a new database on the search list while 'load' puts all the objects into the global environment. The help file for 'load' is inexplicit that this is what happens. The 'load' and 'attach' help files neither refer to the other in their See Also. Furthermore, the 'library' help file talks about loading packages. I would suggest that it should use attaching as that is the analogous operation. None of these three help files (nor that of 'save') has a Side Effects section. Personally I think that all help files should have a Side Effects section (to make it clear to new users what side effects are and that they are not a good thing for most functions to have). I can understand there could be another point of view on that. However, I definitely think that there should be a Side Effects section in the help files of functions whose whole point is a side effect. I think you make good points. Care to submit patches? The source for those man pages are in https://svn.R-project.org/R/trunk/src/library/base/man/attach.Rd https://svn.R-project.org/R/trunk/src/library/base/man/library.Rd https://svn.R-project.org/R/trunk/src/library/base/man/load.Rd https://svn.R-project.org/R/trunk/src/library/base/man/save.Rd If you send them to me before Thursday or after Jan 2, I'll take a look. (If you send them to me during the Xmas break there's a good chance they'll get lost.) Duncan Murdoch __ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] help files for load and related functions
On 12/17/2007 9:06 AM, Oleg Sklyar wrote: Dear Patrick, Firstly, and most importantly, I do not think that your post qualified for Rd! Please use the correct mail list for such things: R-help. I do not think anybody on Rd wants mailboxes clogged with irrelevant messages. Since Patrick's message was about changes to the documentation, I think it is relevant to this list. Duncan Murdoch Back to your question: it is not clear if you are confused, or your 'user' is confused, but all three help pages look pretty clear and straight forward to me. Moreover, I do not see any connection between attach and library, which you find logical: - load - the general use of this one is to load external data sets, e.g. load serialised R object(s) (as the example shows). Until you load, you cannot use the object as it has no relation to the R session and can be e.g. a file sitting somewhere on a network - attach - the general use of this one would be to access elements of a data set directly, without the data set name specifier and the accessor operator, such as $, thus as the help page states - it is used to add the data set to the search path (as the example shows). If you look at the example, you do not have to call attach to be able to use data, data could have existed there before and what you effectively get with attach is a more convenient way of dealing with the data - library - is used to load *and* attach an R package, which is not exactly the same as a serialised R object(s), but a full set of other functionality. Attaching packages is just a part of the loading process, which occurs basically when the package becomes visible to the user. Same as with load, you cannot use the package until you load it. There is not a hint of similarity between loading a package and attaching a data set as I see it. Regards, Oleg On Mon, 2007-12-17 at 11:00 +, Patrick Burns wrote: I recently had a discussion with a user about loading and attaching in R. I was surprised that the help files don't provide a very clear picture. From my point of view 'load' and 'attach' are very similar operations, the difference being that 'attach' creates a new database on the search list while 'load' puts all the objects into the global environment. The help file for 'load' is inexplicit that this is what happens. The 'load' and 'attach' help files neither refer to the other in their See Also. Furthermore, the 'library' help file talks about loading packages. I would suggest that it should use attaching as that is the analogous operation. None of these three help files (nor that of 'save') has a Side Effects section. Personally I think that all help files should have a Side Effects section (to make it clear to new users what side effects are and that they are not a good thing for most functions to have). I can understand there could be another point of view on that. However, I definitely think that there should be a Side Effects section in the help files of functions whose whole point is a side effect. Patrick Burns [EMAIL PROTECTED] +44 (0)20 8525 0696 http://www.burns-stat.com (home of S Poetry and A Guide for the Unwilling S User) __ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel __ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
