I'm creating a new package and documenting lookup tables stored in the data/ folder using an R script as per the instructions here http://r-pkgs.had.co.nz/data.html. I have two .rda tables, one for looking up the product based on a product code and another looking up the category based on the category code. (e.g. data/productlookup.rda)
Here's an except of my documented data which is stored in the R/ folder of the package.
#' ProductDecodes: Extract info from Product Codes
#'
#' This package contains functions for the extraction of information
#' from Product codes.
#'
#' #docType package
#' #name productDecoding
NULL
#' Product lookup
#'
#' #source internal
"productlookup"
#' Category lookup
#'
#' #source internal
"categorylookup"
However, when I come to roxygenise the package I get an error stating the .rda tables cannot be found.
Error in get(name, envir = env) : object 'productlookup' not found
The error doesn't occur when the tables are loaded into the global environment first. What I want to know is whether it is possible to roxygenise the package without having to load the .rda into the global environment first? I don't understand why roxygenise needs the lookup tables to be in the global environment in order to find them. Any help/explanation of why this error is occurring would be appreciated.
This is what I usually do and I've just tested successfully with roxygen2 5.0.1:
#' Product lookup
#'
#' #format A data.frame with 200 rows and 2 variables:
#' \itemize{
#' \item prod: product name
#' \item val: product value in US$
#' }
#'
#' #source internal
#' #name productlookup
NULL
Of course, the resulting help page needs more information.
Related
The help() function allows us to see an index with a list of all functions within a package:
help(package=stats)
If the package is very large, the help page will be automatically broken down alphabetically, with links to each section by initial letter (as in the case of stats). Smaller packages will have all the functions together in alphabetical order.
Is this index page customizable?
I'm using roxygen2, and would love to be able to group functions by their #family.
See section 10.6 of R Packages :
You can use roxygen to provide a help page for your package as a whole.
you need to document NULL, and then manually label it with #docType package and #name . This is also an excellent place to use the #section tag to divide up page into useful categories.
Just create an mypackage.R file with the above Roxygen tags applied to NULL:
#' Mypackage: A package I created
#'
#' MyPackage has different families of functions described below
#'
#' #section Some functions:
#' * [mysum()]
#' * [myprod()]
#'
#' #section Other functions:
#' * [other()]
#' * [foo()]
#'
#' #docType package
#' #name mypackage
NULL
The brackets [] allow to create links to the functions of the package.
I have created a package containing a dataset called mydata.
I want to use my dataset in my functions but I dont know how to call it.
when i use data("mydata") to call my dataset and avoid warning messages I have another message during the building process
See section ‘Good practice’ in ‘?data’.
#imporFrom mypackage mydata doesn't work either. What's the best way to call a dataset in the package itself?
Use package_name::mydata, example in car package car::Angell.
Dataset is in a data folder with for example mydata.rda inside.
To add help, create a data.R file in R folder.
Personnaly I put inside :
# 1. mydata ----
#' Here is a long title
#'
#' Description of the dataset : length, columns
#'
#' #format one object of class XXX
#'
#' #source where it comes from
#' #name mydata
NULL
I am building my own package for the first time and it is finally building with no problems. The problem is that I am exporting only one function with Roxygen2 (6.0.1) as it is the only one to be used but when I build and load my package, all the function present in it are exported. (When I look with package:: )
I've been searching for similar occurrences but didn't find any
Here is the Roxygen comments just before the function:
#' Do a plot
#'
#' #param region a GRange object with chr, start, end
#' #param genome a character vector "hg19","hg38" or "mm10"
#' #param BAM a path to the BAM related csv input file
#' #param BED a path to the BED related csv input file
#' #param avgTrack a logical indicating if the average track should be present or not
#' #param geneTrack a logical indicating if the gene track should be present or not
#' #param max a vector of number containing the maximum of each BAM track
#'
#' #export
myfunction <- function(){}
And here is the NAMESPACE that is generated by Roxygen2:
# Generated by roxygen2: do not edit by hand
export(myfunction)
importFrom(GenomicRanges,findOverlaps)
importFrom(IRanges,elementNROWS)
importFrom(IRanges,splitAsList)
importFrom(S4Vectors,List)
importFrom(S4Vectors,queryHits)
importFrom(S4Vectors,subjectHits)
importFrom(S4Vectors,subjectLength)
importFrom(biomaRt,getBM)
importFrom(grDevices,hcl)
importFrom(graphics,axis)
importFrom(graphics,legend)
importFrom(graphics,lines)
importFrom(graphics,par)
importFrom(graphics,plot)
importFrom(graphics,plot.new)
importFrom(graphics,rect)
importFrom(graphics,segments)
importFrom(graphics,text)
importFrom(rbamtools,bamCount)
importFrom(rbamtools,bamReader)
importFrom(rbamtools,getRefCoords)
importFrom(utils,read.table)
when I do mypackage:: I should have only one function showing (mypackage::myfunction) by I get all the functions that are in my code instead.
So for some reasons when I modify my NAMESPACE from export(myfunction) to export("myfunction") I get the expected result.
It can also be achieved by using #' #export "myfunction"with the Roxygen2 syntax.
I've developed a R package but for some reason the dataset that goes with the package is not being loaded properly when the package is Roxygenised and installed. I have a .R script in the R folder of the package that looks like this
#' Score Card
#' #docType data
#' #name scoreCard
#' #aliases scoreCard
#' #format An object of class \code{data.frame} with 119 rows and 3 columns.
#' \describe{
#' \item{Category}{The Category for which an observation is made}
#' \item{Observation}{The possible responses given for each category}
#' \item{Score}{The score allocated against a response for each category}
#' }
#' #source Internal
#' #usage scoreCard
#' #keywords datasets
NULL
This creates an .Rmd file for the dataset when Roxygenise is called but when I try to call the data set using packageName::scoreCard it states 'scoreCard' is not an exported object from 'namespace:packageName'. Can anyone spot what I might have done wrong in the above script or any other ideas of what might be going wrong, I'm at a bit of a loss? (The data set is stored in the data folder of the package as per normal.) Afraid I can't share the data or package sorry.
Right I didn't realise I needed LazyData: true in my description file. Should have read this more carefully: http://r-pkgs.had.co.nz/data.html
I'm writing an R package and largely following Hadley's book on the topic. I'm running into a problem with documenting methods for simple generics like print, plot, head, and tail. When I use the #describeIn tag to control where the method documentation goes, I get the nice feature of them showing up in the help file for the main analysis function that returns an object of the given class. The problem is that these generics also show up in the package's index. If I add #keywords internal to the generics, then they are removed from the package's index, but so is the main analysis function (they are in the same .R file). If I document the generics in a separate .R file, then I can gain control over what is and is not in the package's index, but I have two issues: the main analysis function doesn't come first in the Usage section of the help file; and if add the #keywords internal for the generics, this removes the analysis function from the package index too, even though they are documented (in this instance) in separate files. The crux of the problem seems to be that #keywords internal applies to all functions in the given .R file, and maybe even any function referenced in #describeIn, while #describeIn is designed for documenting multiple functions in a given .R file.
For now, I have the analysis function and generics in the same .R file to control where the method documention goes and its ordering in the Usage section, but am not using #keywords internal and leaving the index cluttered.
Here's a rough sketch of an exported analysis function:
#' #inheritParams foo
#' #export
seats <- function(judgeit.object, ...) {
[...omitted...]
class(out.object) <- "judgeit.seats"
return(out.object)
}
And a generic:
#' #describeIn seats Print a \code{\link{seats}} output
#' #keywords internal
#' #export
print.judgeit.seats <- function(x,...) print(x$output,...)
I want the help file for ?seats to look like this:
seats(judgeit.object, ...)
## S3 method for class 'judgeit.seats'
print(x, ...)
## S3 method for class 'judgeit.seats'
head(x, ...)
## S3 method for class 'judgeit.seats'
tail(x, ...)
I do not want print.judgeit.seats, head.judgeit.seats, etc. to appear in the package index, because it quickly becomes very cluttered.
Unfortunately, I am not aware of any easy fix for what you are asking.
Tags and their effect
#export will make your function visible in the global environment. CRAN requires that you document any such functions that is not hidden (i.e. that starts with .).
If you use #describeIn or #rdname, an automatic alias is created. Any alias creates an entry in the index, but points to the same .Rd file. For example, adding
#' #name myfunction
#' #aliases foo foobar`
would create foo and foobar entries in the index, but refer to the myfunction.Rd documentation file. If you try to delete manually the \alias{} in the .Rd file, CRAN will complain.
#describeIn will list the functions in the order they appear in the .R files (if they are documented in multiple files, they are listed according to the alphabetical order of the .R file, then the order of appearance). Reordering your functions can give you what you want.
#keywords internal (along with #export, a title and a description) will have Roxygen create a .Rd file that can be accessed by the user using ?, but will not be visible in the index (if you have only the tags, Roxygen will not create a .Rd file and you will get a warning because your function is not documented).
If you have a #keywords internal in any of the functions calling #describeIn, that function will be masked from the index. This does not apply to all functions in a .R file, only those which are aliases.
#usage requires you to have an alias for each method documented. You can try using instead #section Usage:, but note sections are listed in alphabetical order and the spacing will be larger.
Workaround
If you document a NULL function, you can add the #param you want. and include a multiple lines #Section: Usage field to include (manually) the S3 methods with your comments. Give it a name such as #name Seats (it cannot be the name of the function, otherwise you have ?seats pointing to two different files).
Then, document your function seats with a different #name tag and a different title, and use #internal' to hide it from the user. Use \code{\link{seats}}` to refer to that documentation.
#' Seats
#' Description of the function
#' #param judgeit.object object
#' #param x object from seats
#' #param ... additional arguments
#' #name seats
#' #section Usage:
#' \preformatted{seats(judgeit.object, ...)
#' ## S3 method for class 'judgeit.seats'
#' print(x, ...)
#' ## S3 method for class 'judgeit.seats'
#' head(x, ...)
#' ## S3 method for class 'judgeit.seats'
#' tail(x, ...)}
NULL
#' Seats function
#' #name internal-function
#' #inheritParams seats
#' #export
#' #keywords internal
#' #seealso \code{\link{seats}}
seats <- function(judgeit.object, ...) {
[...omitted...]
class(out.object) <- "judgeit.seats"
return(out.object)
}
#' Print a \code{\link{seats}} output
#'
#' #inheritParams seats
#' #describeIn internal-function
#' #export
print.judgeit.seats <- function(x,...) print(x$output,...)
This way, the user calling ?seats will be pointed to the overall documentation.