Is there a standard way to document data frames?

Question

Given a data frame, DF, it is simple to save DF as an R object using save() and share with co-workers. However, it is often necessary to attach a separate document explaining precise column definitions. Is there a (standard/common) way to include this information with the object?

If we built a package for DF we could create a help page explaining all these details, like the built-in datasets. Thus the data and explanation would always be available and we need only share a single package source file. However, building a package seems over-kill for this problem. (As a side benefit, we would gain version control on the data set as changes would increment the package version number).

The Hmisc package includes the label() function, which adds a new attribute to objects. Associated methods for subsetting/creating/etc data.frames are included to propagate the new attribute (since attributes are in general dropped by most functions).

Setting attributes is an obvious alternative to writing a package, and we can add arbitrarily named attributes.

A brief example:

DF <-
structure(list(Gender = structure(c(1L, 1L, 1L, 2L, 2L, 2L), .Label = c("Female",
"Male"), class = "factor"), Date = structure(c(15518, 15524,
15518, 15526, 15517, 15524), class = "Date"), Dose = c(15, 10,
11, 11, 12, 14), Reaction = c(7.97755180189919, 11.7033586194156,
9.959784869289, 6.0170950790238, 1.92480908119655, 7.70265419443507
)), .Names = c("Gender", "Date", "Dose", "Reaction"), row.names = c(NA,
-6L), class = "data.frame")

library(Hmisc)

label(DF$Reaction) <- "Time to react to eye-dot test, in seconds, recorded electronically"

# or we could set our own attributes

attr(DF$Date,"Description") <- "Date of experiment. Note, results are collected weekly from test centres"

# Since Hmisc adds class "labelled" to data.frame and impelments
# the appropriate methods, the formed is retained on subsetting 
# (not that this is feature is wanted)

DF.mini <- DF[ DF$Gender=="Male",]


# compare
str(DF)      # Not quite sure why str() prints the label attribute but not the Desciptions
str(DF.mini) # we retain the label attribute

attributes(DF$Date)
attributes(DF.mini$Date) # we lose the Description attribute

So my questions:

1. Do people include extra information with their objects (my example is a data frame, but applies to all R objects), keeping all the relevant information in one place?
2. If yes, how?
3. Curious, why does str() print the label attribute, I believe the Hmisc package has added another function/method somewhere, but couldn't see why - can someone explain that bit?

Answer 1

There is a base function: comment which can assign or retrieve text which is stored in an attribute.

(And I do not understand the question about why does str print the label. Shouldn't all (non-name, non-class, non-rowname) attributes be displayed by str?)