Re: [Rd] R CMD check WARNING \usage question

From: Bryan Hanson <hanson_at_depauw.edu>
Date: Fri, 06 Jan 2012 15:01:44 -0500

Jeff, this sounds like a standardized data format, not a function. You are basically telling the user how to put their own data into the correct format. You are not giving them any data (at least not with this file), and you are not giving them a function because there is no function here to do the same thing over and over with different data.

If this sounds right, I think the answer is you have to write your own custom Rd file that as far as I know is not really documented per se. However, I have done this exact thing, so I'm appending an example below (from package ChemoSpec). See if this makes sense. Bryan

\name{Spectra}
\Rdversion{1.1}
\title{

Spectra Objects
}
\alias{Spectra}

\description{
In \code{ChemoSpec}, spectral data sets are stored in an S3 class called \code{Spectra}, which contains a variety of information in addition to the spectra themselves. \code{Spectra} objects are created by \code{\link{getManyCsv}} or similar functions (no others currently exist). }

\section{Structure}{
The structure of a \code{Spectra} object is a list of 7 elements and an attribute as follows:

\tabular{lll}{

\emph{element} \tab \emph{type} \tab \emph{description}\cr
$freq \tab num \tab A common frequency (or wavelength) axis for all the spectra.\cr
$data \tab num \tab The intensities for the spectra.  A matrix of dimension \cr
\tab \tab no. samples x no. frequency points.\cr
$names \tab chr \tab The sample names for the spectra; length must be no. samples.\cr
$groups \tab Factor \tab The group classification of the samples; length must be no. samples.\cr
$colors \tab chr \tab The colors for each sample; length must be no. samples. \cr
\tab \tab Groups and colors correspond.\cr
$sym \tab integer \tab As for \code{colors}, but symbols for plotting (if b/w is desired).\cr
$alt.sym \tab chr \tab Lower-case letters as alternate symbols for plotting.\cr
$unit \tab chr \tab Two entries, the first giving the x axis unit, the second the y axis unit.\cr
$desc \tab chr \tab A character string describing the data set.  This appears on plots and therefore \cr
\tab \tab should probably be kept to 40 characters or less.\cr - attr \tab chr "Spectra" \tab The S3 class designation.\cr }
}
\seealso{
\code{\link{sumSpectra}} to summarize a \code{"Spectra"} object.
\code{\link{sumGroups}} to summarize group membership of a \code{"Spectra"} object.
\code{\link{chkSpectra}} to verify the integrity of a \code{"Spectra"} object.
\code{\link{colorSymbol}} for a discussion of color options.

}
\references{
\url{http://academic.depauw.edu/~hanson/ChemoSpec/ChemoSpec.html} }

\author{
Bryan A. Hanson, DePauw University. \email{hanson_at_depauw.edu} }

\keyword{ classes }

On Jan 6, 2012, at 2:48 PM, Jeff Hamann wrote:

> I know I should provide a better answer, but I think it's really for a function.
>
> For this package, we simply pass a list object about, but have to obfuscate it using a domain familiar nomenclature for the users.
>
> So, not a data set, but a function. I think.
>
> Here's the file in it's entirety:
>
>
> %% $Id $
>
> \name{sample.data}
> \alias{sample.data}
>
> \title{CONIFERS forest growth model sample data}
>
> \description{ A list object of type \code{sample.data} stores all of
> the basic information about a \code{\link{data.frame}} object
> representing a sample of plants.}
>
> \usage{
> x <- list( plots=data.frame(), plants=data.frame(), age=0, x0=0.0, n.years.projected=0 )
> class(x) <- "sample.data"
> }
>
> \details{
> To create the basic data type used in rconifers, you create a
> list object with the following elements (order is not
> important):
> \describe{
> \item{plots}{is a \link{data.frame} with the the same elements as \code{\link{plots.swo}}.}
> \item{plants}{is a \link{data.frame} with the the same elements as \code{\link{plants.swo}}.}
> \item{age}{is an integer value that represents the age of the plants,
> in years.}
> \item{x0}{is the $x_{0}$ coefficient for the Hann and Wang (1990) mortality model.}
> \item{n.years.projected}{is the number of years that $x$ has been
> projected forward in time.}
> }
> }
>
> \references{
>
> Ritchie, M.W. 2008. User's Guide and Help System for CONIFERS: A Simulator for Young Conifer Plantations Version
> 4.10. See \url{http://www.fs.fed.us/psw/programs/ecology_of_western_forests/projects/conifers/}
>
> }
>
> \author{Jeff D. Hamann \email{jeff.hamann_at_forestinformatics.com},\cr
> Martin W. Ritchie \email{mritchie_at_fs.fed.us} }
>
> \seealso{ \code{\link{plants.smc}},
> \code{\link{plots.smc}}
> \code{\link{plants.swo}},
> \code{\link{plots.swo}},
> \code{\link{sample.data}},
> \code{\link{set.species.map}},
> \code{\link{set.variant}},
> \code{\link{smc}},
> \code{\link{summary.sample.data}},
> \code{\link{swo}},
> \code{\link{thin}}
> }
>
> \examples{
> library( rconifers )
> ## Example for SWO variant
> ## set the variant to the SWO variant and set species map
> ##set.species.map( set.variant(0) )
> set.variant(0)
>
> ## grow the data that was originally swo in the smc variant
> # load and display CONIFERS example plots
> data( plots.swo )
> print( plots.swo )
>
> # load and display CONIFERS example plants
> data( plants.swo )
> print( plants.swo )
>
> # create the sample.data list object
> sample.swo.3 <- list( plots=plots.swo, plants=plants.swo, age=3, x0=0.0,n.years.projected=0)
> class(sample.swo.3) <- "sample.data"
>
>
> }
>
> \keyword{models}
>
> and the WARNING:
>
> * checking Rd \usage sections ... WARNING
> Assignments in \usage in documentation object 'sample.data':
> x <- list(plots, plants, age = 0, x0 = 0, n.years.projected = 0)
> class(x) <- "sample.data"
>
> Functions with \usage entries need to have the appropriate \alias
> entries, and all their arguments documented.
> The \usage entries must correspond to syntactically valid R code.
> See the chapter 'Writing R documentation files' in manual 'Writing R
> Extensions'.
> * checking Rd contents ... OK
>
>
>
> Respectfully,
> Jeff.
>
>
> Jeff Hamann, PhD
> PO Box 1421
> Corvallis, Oregon 97339-1421
> 541-754-2457
> jeff.hamann[at]forestinformatics[dot]com
> jeff.d.hamann[at]gmail[dot]com
> http://www.forestinformatics.com
> http://en.wikipedia.org/wiki/Forest_informatics
>
> To ensure that your email is processed, include a subject entry in your email.
>
>
>
>
> On Jan 6, 2012, at 11:38 AM, Bryan Hanson wrote:
>

>> Jeff, quick question: is this a data set or a function you are documenting?  What you say sounds like it's data, but the Rd file reads more like a function.  Or are you trying to document a data format/object which stores specific data sets?
>> 
>> Let us know, and I'll bet the answer will appear pretty quickly. Bryan
>> 
>> ***********
>> Bryan Hanson
>> Professor of Chemistry & Biochemistry
>> DePauw University
>> 
>> On Jan 6, 2012, at 2:11 PM, Jeff Hamann wrote:
>> 
>>> I'm trying to update a package and would like to crush a WARNING message for a clean build. 
>>> 
>>> I've been struggling with this question and haven't gotten any traction on the web either.
>>> 
>>> I've got a document file (Rd) that contains the following \usage statement:
>>> 
>>> \name{sample.data}
>>> \alias{sample.data}
>>> 
>>> \title{CONIFERS forest growth model sample data}
>>> 
>>> \description{ A list object of type \code{sample.data} stores all of
>>> the basic information about a \code{\link{data.frame}} object
>>> representing a sample of plants.}
>>> 
>>> \usage{
>>> x <- list( plots=data.frame(), plants=data.frame(), age=0, x0=0.0, n.years.projected=0 )
>>> class(x)  <- "sample.data"
>>> }
>>> 
>>> When I run R CMD check [pkg], I get the following WARNING:
>>> 
>>> * checking Rd \usage sections ... WARNING
>>> Assignments in \usage in documentation object 'sample.data':
>>> x <- list(plots, plants, age = 0, x0 = 0, n.years.projected = 0)
>>> class(x) <- "sample.data"
>>> 
>>> Functions with \usage entries need to have the appropriate \alias
>>> entries, and all their arguments documented.
>>> The \usage entries must correspond to syntactically valid R code.
>>> See the chapter 'Writing R documentation files' in manual 'Writing R
>>> Extensions'.
>>> * checking Rd contents ... OK
>>> 
>>> I'm not sure if there's a problem with the \alias section or the \usage section or both sections (I'm assuming this is the case).
>>> 
>>> I've read the Chapter 2 of R-ext.pdf plenty and just can't seem to see where I'm blowing it.
>>> 
>>> Respectfully,
>>> Jeff.
>>> 
>>> 
>>> Jeff Hamann, PhD
>>> PO Box 1421
>>> Corvallis, Oregon 97339-1421
>>> 541-754-2457
>>> jeff.hamann[at]forestinformatics[dot]com
>>> jeff.d.hamann[at]gmail[dot]com
>>> http://www.forestinformatics.com
>>> http://en.wikipedia.org/wiki/Forest_informatics
>>> 
>>> To ensure that your email is processed, include a subject entry in your email.
>>> 
>>> 
>>> 
>>> 
>>> 
>>> 	[[alternative HTML version deleted]]
>>> 
>>> ______________________________________________
>>> R-devel_at_r-project.org mailing list
>>> https://stat.ethz.ch/mailman/listinfo/r-devel
>> 
>> 

>

        [[alternative HTML version deleted]]



R-devel_at_r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel Received on Fri 06 Jan 2012 - 20:04:58 GMT

This quarter's messages: by month, or sorted: [ by date ] [ by thread ] [ by subject ] [ by author ]

All messages

Archive maintained by Robert King, hosted by the discipline of statistics at the University of Newcastle, Australia.
Archive generated by hypermail 2.2.0, at Fri 06 Jan 2012 - 20:30:07 GMT.

Mailing list information is available at https://stat.ethz.ch/mailman/listinfo/r-devel. Please read the posting guide before posting to the list.

list of date sections of archive