R help - Feb 2001 - self documenting workspaces, and the proper role of the dot

again I ask for some suggestions : I don't mind being told to RTFM as long 
as I get a few hints as to where to look <g>

suppose I want to document the set of functions and vectors that I have in 
a workspace, and I would like to make that workspace 'self documenting'
..
so I could open up that particular workspace in a few months and know what 
xdiff contained ..etc. Essentially I want a listing of objects and their 
'descriptions'.

I could write a function to list each object and its 'description'
easily
enough, but names() does not quite fit the bill. For a 'scalar' I can
use
names(), but for a vector names() wants every element named - I guess I 
could just use the name of the first element but this is a bit kludgy. For 
a function I don't see any way of using names(), but I guess I could 
be disciplined about this and have every function that is specific to the 
workspace return some descriptive string.

One possibility that occurred to me is to have some 'documentation' 
objects

eg fred.doc<-"this is function fred and it does whatever" 

and write a function to list these (or the names of scalars) ..I suppose 
that is OK , if a little inelegant.

So this is less of a technical question than a housekeeping/procedural one 
.. if someone has a nice solution or if there are some features of R that 
I have overlooked that could be of assistance, I would be very interested.


thanks

somewhat separate topic : the dot

I'd also appreciate it if someone could clarify for me the proper role of 
the dot. It appears there are no semantic/syntactic restrictions on its 
use, as in
> .fred<-1
> .fred
[1] 1
> .fred.fred<-1
> .fred.fred
[1] 1
> .fred.fred.fred.fred.fred<-1
> .fred.fred.fred.fred.fred
[1] 1
> ...fred<-1
> ...fred
[1] 1
> ...fred.............................fred<-1
> ...fred.............................fred
[1] 1
> fred...fred.............................fred<-1
> fred...fred.............................fred
[1] 1

or even ....<-1:10

but I suspect there are some conventions at work, with which I am not
au fait. For instance I have noted that in ls()  .prefixed objects can be 
ignored, by option. 

So is an initial dot intended to denote 'internal' (or
'working') in
function names?

What about  p.value ? is there some reason for this, as opposed to pvalue 
?

In the oo languages with which I am most familar, dot is used to denote
hierarchy eg text.font.style  .. is there a similar intention at work 
here?



John Aitchison
-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-
r-help mailing list -- Read http://www.ci.tuwien.ac.at/~hornik/R/R-FAQ.html
Send "info", "help", or "[un]subscribe"
(in the "body", not the subject !)  To: r-help-request at
stat.math.ethz.ch
_._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._

The way I solve the problem of documentation is to write a
"program" (or "script") for everything, and include comments
in
it (as outlined at the beginning of "Notes on the use of R for
psychology experiments..." in the "Contributed" section of CRAN).
The script has as many comments as I care to write (never
enough).  Then I run the script with "source()".  I do have to
copy, or "copy and paste", new ideas that I think up along the
way.  But the ratio of good ideas to bad ones is quite low, so I
would certainly not want to save everything I do, automatically.

This is roughtly the style used in the examples included with R.

Others in this list have recommended ESS for similar purposes
(Emacs Speaks Statistics), but I haven't tried it (for fear of
confusion, since I use Emacs for everything else).

As for dots, I don't know.  But it does seem that they are just
another character, in contrast to _, which is not.  They do not
have the meaning that they have in Perl or JavaScript.


Jonathan Baron, Professor of Psychology, University of Pennsylvania
Home page: http://www.sas.upenn.edu/~jbaron
-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-
r-help mailing list -- Read http://www.ci.tuwien.ac.at/~hornik/R/R-FAQ.html
Send "info", "help", or "[un]subscribe"
(in the "body", not the subject !)  To: r-help-request at
stat.math.ethz.ch
_._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._

On Mon, 19 Feb 2001, John Aitchison wrote:
>
> again I ask for some suggestions : I don't mind being told to RTFM as
long
> as I get a few hints as to where to look <g>
>
> suppose I want to document the set of functions and vectors that I have in
> a workspace, and I would like to make that workspace 'self
documenting' ..
> so I could open up that particular workspace in a few months and know what
> xdiff contained ..etc. Essentially I want a listing of objects and their
> 'descriptions'.
>
> I could write a function to list each object and its 'description'
easily
> enough, but names() does not quite fit the bill. For a 'scalar' I
can use
> names(), but for a vector names() wants every element named - I guess I
> could just use the name of the first element but this is a bit kludgy. For
> a function I don't see any way of using names(), but I guess I could
> be disciplined about this and have every function that is specific to the
> workspace return some descriptive string.
>
> One possibility that occurred to me is to have some 'documentation'
> objects
>
> eg fred.doc<-"this is function fred and it does whatever"
>
> and write a function to list these (or the names of scalars) ..I suppose
> that is OK , if a little inelegant.
>
> So this is less of a technical question than a housekeeping/procedural one
> .. if someone has a nice solution or if there are some features of R that
> I have overlooked that could be of assistance, I would be very interested.

YOu could attach a "doc" attribute to everything. This has the
disadvantage that for objects with no special "print" method the
attribute
would always be printed with the object.

attr(a,"doc")<-"A is for apple"

and you could write a function that listed objects and documentation using
something like
sapply(ls(),function(x) attr(x,"doc")


>
>
> thanks
>
> somewhat separate topic : the dot
>
> I'd also appreciate it if someone could clarify for me the proper role
of
> the dot. It appears there are no semantic/syntactic restrictions on its
> use, as in
>
> > .fred<-1
> > .fred
> [1] 1
> > .fred.fred<-1
> > .fred.fred
> [1] 1
> > .fred.fred.fred.fred.fred<-1
> > .fred.fred.fred.fred.fred
> [1] 1
> > ...fred<-1
> > ...fred
> [1] 1
> > ...fred.............................fred<-1
> > ...fred.............................fred
> [1] 1
> > fred...fred.............................fred<-1
> > fred...fred.............................fred
> [1] 1
>
> or even ....<-1:10
>
> but I suspect there are some conventions at work, with which I am not
> au fait. For instance I have noted that in ls()  .prefixed objects can be
> ignored, by option.
>
> So is an initial dot intended to denote 'internal' (or
'working') in
> function names?
>
> What about  p.value ? is there some reason for this, as opposed to pvalue
> ?
>
> In the oo languages with which I am most familar, dot is used to denote
> hierarchy eg text.font.style  .. is there a similar intention at work
> here?

The dot is used in four different ways. It's almost always clear from
context which is intended.

1) Method separator
	print.default
	print.lm
	print.formula

are "print" methods for "default", "lm" and
"formula"

2) Separating words: since the underscore can't be part of a variable name
we can separate words either by InternalCapitals
	NextMethod
	commandArgs
or by.dots
	data.frame
	lm.influence
	split.plot
	filled.contour
	p.value

3) As in Unix, we use a leading dot to hide global variables and functions
that people would be better off not knowing about.
	.packages
	.Options
	.Generic

4) The ellipsis ... is a special token used to represent extra function
arguments. These can be positionally matched by ..1, ..2

One of the complications in UseMethod/NextMethod is that dots can mean
more than one thing.  We need to know that as.data.frame.matrix is an
"as.data.frame" method for "matrix" arguments, but
print.summary.lm.null
is a "print" method for "summary.lm.null" objects. If
someone wrote a
function "as.data" with a method for objects of class
"frame.matrix" we
would be in trouble, but it's no worse than what would happen if an
SAS ex-user wanted to write a function for the General Linear Model and
call it glm().


	-thomas

Thomas Lumley			Asst. Professor, Biostatistics
tlumley at u.washington.edu	University of Washington, Seattle

-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-
r-help mailing list -- Read http://www.ci.tuwien.ac.at/~hornik/R/R-FAQ.html
Send "info", "help", or "[un]subscribe"
(in the "body", not the subject !)  To: r-help-request at
stat.math.ethz.ch
_._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._

Hi

The suggestions below were to use attr()  and comment() ..
it seems from my tests that neither of these survive edit or fix , 
likewise attributes(). This is true of functions, but not of vectors.

---------------------------------
eg this works fine
> x<-1:10
> comment(x) <- 'this is a comment'
> attr(x,'creation')<-date()
> fix(x)
> x
[1]  1  9 10
attr(,"creation")
[1] "Mon Feb 19 23:55:55 2001"
> attributes(x)
$comment
[1] "this is a comment"
$creation
[1] "Mon Feb 19 23:55:55 2001"
----------------------------------------'
but this does not
 f<-function(x){attributes(x)}
> comment(f) <- 'function comment'
> attr(f,'creation')<-date()
> attributes(f)
$source
[1] "function(x){attributes(x)}"
$comment
[1] "function comment"
$creation
[1] "Tue Feb 20 00:00:15 2001"
> fix(f)
> attributes(f)
$source
[1] "function(x){print(attributes(x))" "}"
-------------------------------------------------------------

Is this a feature, a bug, an oversight? ??


It is easily 'fixed' apparently with

myfix<-function(f){s<-attributes(f);fix(f);attributes(f)<-s}

I cannot call myfix 'fix' here (ie override fix) because of infinite 
recursion .. what I am missing notation wise? (ie to call the 'ancestor'
of fix)

fix<-function(f){s<-attributes(f);base:fix(f);attributes(f)<-s} ? or 
somesuch

thanks again



On 19 Feb 2001, at 18:23, Peter Dalgaard BSA wrote:
> Thomas Lumley <tlumley at u.washington.edu> writes:
> 
> > YOu could attach a "doc" attribute to everything. This has
the
> > disadvantage that for objects with no special "print" method
the
> > attribute would always be printed with the object.
> > 
> > attr(a,"doc")<-"A is for apple"
> > 
> > and you could write a function that listed objects and documentation
> > using something like sapply(ls(),function(x) attr(x,"doc")
> 
> Actually, once upon a time in the far East, Ross wrote comment(x) and
> comment(x)<- to do just that. We're not very good at keeping them,
> though - for instance, they don't survive a fix() of the object.
> 
John Aitchison
-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-
r-help mailing list -- Read http://www.ci.tuwien.ac.at/~hornik/R/R-FAQ.html
Send "info", "help", or "[un]subscribe"
(in the "body", not the subject !)  To: r-help-request at
stat.math.ethz.ch
_._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._

All,

Thanks to everyone who responded with comments and suggestions about my
introductory text on using R with epidemiological data. I have tried to
incorporate all of the suggestions that were made and have uploaded the
new version to:

        http://www.myatt.demon.co.uk/index.htm

This text is released under the GNU Free Documentation License. Feel
free to use this as you will. Feel free to mail me with any comments or
suggestions that you may have.

Best wishes,

Mark


--
Mark Myatt


-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-
r-help mailing list -- Read http://www.ci.tuwien.ac.at/~hornik/R/R-FAQ.html
Send "info", "help", or "[un]subscribe"
(in the "body", not the subject !)  To: r-help-request at
stat.math.ethz.ch
_._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._