I'm putting together an R package. I would like to show example code in the vignette, where example data files (included in the package) are used to generate an (example) output file.
I read about using example data in Hadley Wickham's post (http://r-pkgs.had.co.nz/data.html), and believe I should keep my example data as raw data, as it must be parsed to generate the output.
So, I created a directory in my package structure
/Users/userName/myPackage/inst/extdata/
with subdirectories InputFiles and OutputFiles.
And I put the example file (exampleData.csv) inside of the InputFiles subdirectory (/Users/userName/myPackage/inst/extdata/InputFiles).
My vignette is located in:
/Users/userName/myPackage/vignettes/myPackage.Rnw
It contains the following syntax:
<<eval=FALSE>>=
fileString = "/Users/userName/myPackage/inst/extdata/InputFiles/exampleData.csv"
doFunction1(fileString)
doFunction2(fileString)
doFunction3(fileString, output ="Users/userName/myPackage/inst/extdata/OutputFiles")
@
I am having two problems with developing this vignette and its example datasets:
1) I am unsure if my use of the extdata file is appropriate. This seemed to be the best directory name and location to place my example files, according to the aforementioned Hadley Wickham reference.
2) I am unsure how to make the pathways relative, instead of absolute, as I have them currently. This example code does not run automatically, as you can see. Instead, I have it under an R chunk of eval=FALSE so that it is simply listed there for the users to test themselves. After running the example code, the users can also check that the output file was indeed created in (/Users/userName/myPackage/inst/extdata/OutputFiles). What is the best way for me to allow the user to not have to use an absolute path when following the example? Is it possible to just follow a relative path from within the package directory myPackage?
My data files consist of .csv, .htm, and .text files. In the past, when constructing a package, I have saved a data frame as .rda file, and then the user could simply use:
data(example.rda)
to read that file. They would not have to write the entire pathway. Is there a similar function that can be used to read .csv, .html, and .text files, and then output them to an example output location - without having to use the full pathway? Would it be possible to have help functions that also read in the input files and write to the output files? Would this cause a conflict in CRAN if various example help functions in the /man folder physically save the example output file to the example output folder?
The standard way to refer to a file in a package is:
# gives root package directory
system.file(package="myPackage")
# specific file
system.file("extdata/InputFiles/exampleData.csv", package="myPackage")
# best is to use cross-platform way to write a file path:
system.file("extdata", "InputFiles", "exampleData.csv", package="myPackage")
When developing with devtools, the inst subdirectory is ignored, so you never need to worry about absolute paths. This should work in a vignette. Note that a vignette, I think, only ever uses the installed version of a package, not the one you may have loaded in your development environment (specifically, devtools::load_all() does not change the code which is used to build the vignette, you must install() it first).
Finally, using data() is a bit old fashioned. Hadley and others recommend using lazy data, so the data appears in the namespace automatically. Try the following in your DESCRIPTION.
LazyData: true
LazyDataCompression: xz