I've been reading through R's Affy manual, and it refers to other vignettes. Does the difference between these two terms simply relate to quantity of content, or is there more to it?
Reference Manuals
The reference manual of a package is a single document beginning with the package description and containing all of the content from the .Rd help files for the packages. Generally, this means it has the help files for (exported) functions in the package, any documented data sets, and package-level documentation (if included). It is automatically generated from the .Rd sources.
Every package has a manual. Even a package with no exported functions and documentation would still have a manual (when built) consisting of the text from the Description file.
Vignettes
Vignettes are free-form documents. Generally, package authors use them to demonstrate the use of their package. They are optional, some packages have several (as I write this dplyr has 8 vignettes) and many packages have none.
As mentioned in the comments the R Extensions Manual is the definitive source for all things package-related. Here is Josh's link to the Vignettes Section, and 2.15 Processing documentation files describes how reference manuals are built.
Related
I have been working on an R package. A package deals with large data (more than 200-300mb is the data file that is used in vignette example, however, when compressed, the whole package is about 20-30mb). If I would use smaller data, an example in vignette would not make any sense.
Since I plan to upload this to a CRAN, what should I do? I read that you need to "justify the size of your package" and "If it’s still too large, consider moving data into its own package." (this is from R packages by Hadley Wickham). What does this mean?
When running check as cran, I get a note about package size (0 errors and 0 warnings). It doesn't seem like the package is that big and it is impossible to include less data because test example in vignette would not make any sense. Is this a valid reason for having package size larger than 5mb or will it be turned down from cran?
I thought about putting this data on my private server and loading it over the internet (for example read.tabe(file="https://link_to_file....")) in vignette Rmd. However, I found out that all the data for creating a vignette has to be in vignettes folder.
Then I thought about excluding the vignette, pkgdown site and the data (and .r file describing this data in R folder) from the build and submitting the package as it is to cran (with no vignette and data). Furthermore, I would put the vignette, pkgdown site and the data on another github repository available for everybody, providing the link in README file.
Does this make sense to you? By proceeding this way I would have a package which, if tested, would give 0 errors, warnings and notes but without complete documentation (however, I would provide it over github repo).
What do you think? Does submitting a package without vignette increases chances of being turned down (even though you have 0 errors/warnings/notes in a check)? Or should I include the vignette but then have a > 5mb package (which returns 1 note in check)? Is there a way to submit a package with a vignette but without the data but still provide the data separately?
I have no idea how to proceed. Any suggestions are welcome, thank you...
Title should be pretty clear I hope. I'm writing a package called forecasting, with imports for dplyr among other packages. With the imports written in to the DESCRIPTION file, I am able to force these other packages to be installed along with forecasting - is there an equivalent way to do this for the loading of the package? In other words, is there a way that when I load my package with library(forecasting), it automatically also loads dplyr and the other packages?
Thanks
Yes.
Re-read "Writing R Extensions". The Depends: forces both the initial installation as well as the loading of the depended-upon packages.
But these days you want Imports: along with importFrom() in the NAMESPACE file which is more fine-grained.
But first things first: get it working with Depends.
Edit:
Opps you're correct, the documentation I referenced is not a primary source. Perhaps this is better:
From the R documentation:
The ‘Depends’ field gives a comma-separated list of package names which this package depends on. Those packages will be attached before the current package when library or require is called.
and
The ‘Imports’ field lists packages whose namespaces are imported from (as specified in the NAMESPACE file) but which do not need to be attached. Namespaces accessed by the ‘::’ and ‘:::’ operators must be listed here, or in ‘Suggests’ or ‘Enhances’
Original:
From the R packages documentation:
Adding a package dependency here [the DESCRIPTION file] ensures that it’ll be installed. However, it does not mean that it will be attached along with your package (i.e., library(x)). The best practice is to explicitly refer to external functions using the syntax package::function(). This makes it very easy to identify which functions live outside of your package. This is especially useful when you read your code in the future.
I'm planning to condense some of my code into a package, and was looking at the source of a few published packages on CRAN as a guide. I notice many packages include the file R\zzz.R, so I presume there must be some convention surrounding this.
However, I cannot find any mention of zzz.R in the official Writing R Extensions guide. What is this file for, and do I need to include one in my package? Why is it named the way it is - why not zzzz.R?
It's a file where one usually puts actions on load of the package. It is tradition/convention that it's called zzz.R and could be called anything.R
You only need to include this if you want you package to do something out of the ordinary when it loads. Keep looking at what people put in there and you'll begin to get a sense of what they're used for.
This zzz.R file was also mentioned by Hadley Wickham in his book "R packages", at the bottom of "When you do need side-effects" section.
https://r-pkgs.org/Code.html#when-you-do-need-side-effects
If you use .onLoad(), consider using .onUnload() to clean up any side effects. By convention, .onLoad() and friends are usually saved in a file called R/zzz.R. (Note that .First.lib() and .Last.lib() are old versions of .onLoad() and .onUnload() and should no longer be used.)
I'm writing a vignette for one of my packages.
In this vignette, I would like to demonstrate how this package can interact with other packages that are not being imported by the NAMESPACE or by the Imports section of the DESCRIPTION file.
So, I'm putting a require call to use these external packages in my vignette, but of course I got the following NOTE when I try to R CMD check the package:
* checking for unstated dependencies in vignettes ... NOTE
‘library’ or ‘require’ call not declared from: ‘RColorBrewer’
Is there any way around this, or should I either import these external packages or "fake" the vignette using eval=FALSE?
Put it in Suggests: of your DESCRIPTION file.
From p. 6 of the R extensions manual:
The ‘Suggests’ field uses the same syntax as ‘Depends’ and lists
packages that are not necessarily needed. This includes packages used
only in examples, tests or vignettes (see Section 1.4 [Writing package
vignettes], page 26), and packages loaded in the body of functions.
E.g., suppose an example from package foo uses a dataset from package
bar. Then it is not necessary to have bar use foo unless one wants to
execute all the examples/tests/vignettes: it is useful to have bar,
but not necessary. Version requirements can be specified, and will be
used by R CMD check.
In addition if the vignette properly depends on that package, there should be a
% \VignetteDepends{...}
statement in the vignette itself: Sweave, Part II: Package Vignettes, R News 3/2 (Oct. 2003), 21 - 24.
However, your case possibly is a bit different:
I use if (require ("pkgxy")) without % \\VignetteDepends{pkgxy} (Suggests: pkgxy in the DESCRIPTION is needed anyways) for some things I want to show but where I don't want to force the user to have all the suggested pacakges installed. I put a box at the beginning of the vignette where I report which of those packages are available and if a package is not available when the vignette is built, an "pkgxy is needed to do this" text is put into the vignette.
The "introduction" vignette of package hyperSpec is an example (to find out how it actually works, you need not only the .Rnw but also some more definitions).
Can I include some PDF in the pkg/doc folder so that the vignette function works, but no corresponding Rnw, Rtex, etc exists?
I am thinking of slides or documents containing markdown text weaved with R chunks, which have a different build process and hence different file extensions.
The writing R extensions guide suggests that it should be possible to include documents which can not be build at installation time, but the vignette function seems to look for files with special extensions (Rnw, Rtex, etc) and also for a file called vignette.rds.
Any hints are appreciated.
I asked about this several years ago, and while Fritz Leisch is amenable to the idea, he hasn't had the time to implement it.
(Cross-posted from a response I just left on R-help:)
As a workaround, you could include your own xvignette function in your package: see below.
It won't show you indices, but it will pick up any appropriately named file that you include in the inst/doc directory of your
package ...
xvignette <- function(vname,pkg,ext="pdf") {
vname <- paste(vname,ext,sep=".")
fn <- system.file("doc",vname,package=pkg)
if (nchar(fn)==0) stop("file not found")
utils:::print.vignette(list(pdf=fn))
invisible(fn)
}
You'll have to somehow alert your package users to the fact that this alternative documentation exists -- perhaps in the help file for the package itself.
You might fill in the default value of pkg above with your package name to make it easier on the user: I thought about using some variant of getPackageName(environment(xvignette)) to do it automatically, but that seems too complicated ...
Brian Ripley also mentioned in his response to the question that:
At present vignette() means Sweave documents, as only they have
metadata like titles. This is planned to be changed soon.
... but I don't know what "soon" means (it will be about 6 months until 2.14.0 comes out, I think)
edit: http://article.gmane.org/gmane.comp.lang.r.devel/28449 details another workaround (creating a dummy vignette that incorporates the existing PDF file)
edit 2: And
here's what Yihui Xie has to say about including knitr-based vignettes in packages (essentially another "dummy vignette" strategy)
vignette about non-Sweave vignettes from the R.rsp package
This is supported natively as of R 3.0.0, see http://yihui.name/knitr/demo/vignette/.
Instructions to use knitr as vignette engine boil down to:
add %\VignetteEngine{knitr::knitr} to the Rnw source document (note you still need %\VignetteIndexEntry{} as before)
specify VignetteBuilder: knitr in the package DESCRIPTION file
add Suggests: knitr in DESCRIPTION if knitr is needed only for vignettes
See also the official R documentation on that topic.