[R-pkg-devel] appropriate directory for data downloads in examples, demos and vignettes

FYI,

my R.cache package keeps cache files under a specific cache directory.
To meet the CRAN Policies
[http://cran.r-project.org/web/packages/policies.html] that:

"Packages should not write in the users? home filespace, nor anywhere
else on the file system apart from the R session?s temporary directory
(or during installation in the location pointed to by TMPDIR: and such
usage should be cleaned up). Installing into the system?s R
installation (e.g., scripts to its bin directory) is not allowed.

Limited exceptions may be allowed in interactive sessions if the
package obtains confirmation from the user."

The R.cache root directory is setup as follows:

1. It can be specified via environment variable R_CACHE_PATH.  If that
is not given, it defaults to ~/.Rcache/, i.e. effectively: rootpath <-
Sys.getenv("R_CACHE_PATH", default="~/.Rcache").

2. Next, if and only if this directory exists, then no "questions
asked" and this directory will be used as is.

3. If it does not exist and R runs in an interactive session, then the
user is prompted whether s/he wish to create the directory given by
the 'rootpath' rule above, e.g.

library(R.cache)

The R.cache package needs to create a directory that will hold cache
files. It is convenient to use one in the user's home directory,
because it remains also after restarting R. Do you wish to create the
'~/.Rcache/' directory? If not, a temporary directory
(C:\Users\hb\AppData\Local\Temp\Rtmp0udmsF/.Rcache) that is specific
to this R session will be used. [Y/n]:

If user accepts, then the directory is created and we're back to Step
2 above (which will be the case for all future R sessions).

4. If the user don't want to create this directory, or R runs in a
non-interactive session (e.g. R CMD check), then a temporary cache
directory is used, which is rootpath <- file.path(tempdir(),
".Rcache").  This directory is only guaranteed to exist for the
current session.

Comment on ~/.Rcache/: This default was chosen because it can be
created on all platforms and for all users.  I don't know of any other
path (except one under tempdir()) for which this is true.  The
downside is that it adds to the user's quota, will most likely be
backed up by default etc. However, it is very easy to use file links
to point it elsewhere, e.g. ln -s /vartmp/$USER/.Rcache ~/.Rcache/.


If your GIS data is supposed to live beyond a single R session, then
you could use a similar approach for your MazamaSpatialUtils package.
You could emulate the above completely, e.g. MAZAMA_SPATIAL_PATH and
~/.mazama_spatial/.  Alternatively, you could leverage the R.cache
package and simply put all your data in a subdirectory under the
R.cache root path, e.g. getCachePath(dirs="MazamaSpatialUtils").  For
most users this will become ~/.Rcache/MazamaSpatialUtils/.  With this,
all required interactions with the user is taken care of by R.cache
(as above) and it will also fallback to using a temporary directory
when run under 'R CMD check'.k


Either way, you definitely want to use tempdir() for a
session-specific temporary directory, e.g.

tempdir()

[1] "C:\\Users\\hb\\AppData\\Local\\Temp\\Rtmp0udmsF"

It works on all platforms and you don't have to create your on "hash"
subdirectory.


/Henrik
(author of R.cache)

On Mon, Jun 29, 2015 at 9:22 AM, Paul Gilbert <pgilbert902 at gmail.com>
wrote:

Regarding alternative places for scripts, you can add a directory (eg
inst/testLocalScripts) and then with a recently added R CMD feature you

can

do

 R CMD check --test-dir=inst/testLocalScripts your-package.tar.gz

This will not (automatically) be checked on CRAN. Beware that you also

need

to run R CMD check without this option to run your regular tests.

Paul



On 06/29/2015 11:25 AM, Jonathan Callahan wrote:

Hi,

The MazamaSpatialUtils
<http://cran.r-project.org/package=MazamaSpatialUtils> package has a
required "package state" variable which users set to specify where they
want to store large amounts of GIS data that is being downloaded and
converted by the package. The implementation of this follows Hadley's
advice here:

http://adv-r.had.co.nz/Environments.html#explicit-envs

The functionality is implemented with package environment and getter and
setter functions:

spatialEnv <- new.env(parent = emptyenv())
spatialEnv$dataDir <- NULL


getSpatialDataDir <- function() {
   if (is.null(spatialEnv$dataDir)) {
     stop('No data directory found. Please set a data directory with
setSpatialDataDir("YOUR_DATA_DIR").',call.=FALSE)
   } else {
     return(spatialEnv$dataDir)
   }
}


setSpatialDataDir <- function(dataDir) {
   old <- spatialEnv$dataDir
   dataDir <- path.expand(dataDir)
   tryCatch({
     if (!file.exists(dataDir)) dir.create(dataDir)
     spatialEnv$dataDir <- dataDir
   }, warning = function(warn) {
     warning("Invalid path name.")
   }, error   = function(err) {
     stop(paste0("Error in setSpatialDataDir(",dataDir,")."))
   })
   return(invisible(old))
}


My question is:

*What is an appropriate directory to specify for vignettes (or demos or
examples) that need to go through CRAN testing?*

The R code in vignettes need to specify a directory that is writable
during
the package build process but that will also be available to users.

Should we create a /tmp/<hash> directory? Would that be available on all
systems?

Alternatively,

*What is an alternative to vignettes and demos for tutorial scripts that
should not be tested upon submission to CRAN?*


Thanks for any suggestions.

Jon