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 patrick at burns-stat.com +44 (0)20 8525 0696 http://www.burns-stat.com (home of S Poetry and "A Guide for the Unwilling S User")
help files for load and related functions
7 messages · Patrick Burns, Oleg Sklyar, Gavin Simpson +2 more
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
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 +0000, 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 patrick at burns-stat.com +44 (0)20 8525 0696 http://www.burns-stat.com (home of S Poetry and "A Guide for the Unwilling S User")
______________________________________________ R-devel at 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
On Mon, 2007-12-17 at 14:06 +0000, 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 +0000, 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 patrick at burns-stat.com +44 (0)20 8525 0696 http://www.burns-stat.com (home of S Poetry and "A Guide for the Unwilling S User")
______________________________________________ R-devel at 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 %~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%
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 +0000, 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 patrick at burns-stat.com +44 (0)20 8525 0696 http://www.burns-stat.com (home of S Poetry and "A Guide for the Unwilling S User")
______________________________________________ R-devel at r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
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
"DM" == Duncan Murdoch <murdoch at stats.uwo.ca>
on Mon, 17 Dec 2007 09:36:48 -0500 writes:
DM> 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.
{ Oleg, you may have to be told that Pat Burns has been
acquainted with the S language for a very long time, maybe
about as long as you know to read... }
DM> Since Patrick's message was about changes to the documentation, I think
DM> it is relevant to this list.
yes indeed!
And the technicality of the discussion further down
is another good reason.
DM> 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.
Hmm, I think there is, ..... and there's more :
The function load() is well known for loading R objects into the
global environment; well known, easy to understand. However, it
can load into any other environment; and environments are the
crucial entities here.
BUT when talking about loading in the context of R packages *and*
namespaces (!), there are other things:
One important point I think was not mentioned yet, and is probably *the*
reason of potential confusion of useRs and even programmeRs: here
library(<package>) does conceptually two things
1) it *loads* the (exported) objects from the installed package
(or with lazy-loading just loads "stubs") into a new environment.
2) it "attaches" the names of those objects to the search() path
where things happen a bit differently for namespaced and other
packages.
For namespaced packages the two steps are really nicely
separable on a user level: I hope you've known
loadNamespace(), unloadNamespace(), attachNamespace() and the
fact that e.g. cluster::pam() loads cluster's package namespace
but does not attach cluster to search().
{ If you want to delve and hence to look at the library()
function, please do so in the sources, e.g.,
https://svn.r-project.org/R/trunk/src/library/base/R/library.R
which has many comments that are all gone in the 'library' function object.
}
I'd say: Because the loading part is the more delicate one than the
attach one, help(library) talks more about loading the package
than attaching..
Regards, Martin
>> Regards,
>> Oleg
>>
>> On Mon, 2007-12-17 at 11:00 +0000, 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
>>> patrick at burns-stat.com
>>> +44 (0)20 8525 0696
>>> http://www.burns-stat.com
>>> (home of S Poetry and "A Guide for the Unwilling S User")
>>>
>>> ______________________________________________
>>> R-devel at r-project.org mailing list
>>> https://stat.ethz.ch/mailman/listinfo/r-devel
DM> ______________________________________________
DM> R-devel at r-project.org mailing list
DM> https://stat.ethz.ch/mailman/listinfo/r-devel