3

When developing packages, I often have R scripts stored in the inst directory that produce data objects then included in the package, i.e. stored as someObj.rda in the data directory.

These objects, in turn, have R scripts with roxygen2 headers for documentation (e.g. someObj.R). Ideally, I would like to include a line in the roxygen2 header that sources and formats the script as code, OUTSIDE of examples. Yes, I could copy the lines in, but in the DRY principle, it would be nice to have the documentation include the code automatically.

I have tried the following with no success:

rdScript <- function(x) { lns <- readLines(x) lns <- sprintf("#' \\code{%s}", lns) cat(lns, sep = "\n") } #' @name someObj #' @title Some R Bbject #' @description Some R Object #' @details #' Data created with the following script: #' @eval rdScript("inst/createCrimeData.R") #' NULL

And this:

rdScript <- function(x) { lns <- readLines(x) lns <- sprintf("\\code{%s}", lns) lns } #' @name someObj #' @title Some R Bbject #' @description Some R Object #' @details #' Data created with the following script: #' @eval rdScript("inst/createCrimeData.R") #' NULL

Edit in response to arguments against placing these scripts in the inst

While this was not the intention of this question, I would like to make the argument for inst being the ideal place for these scripts. This situation comes up for me personally when producing not general-use R packages, but R packages to accompany manuscripts and reproduce analyses. R packages provide an ideal format for disseminating fully-reproducible analyses. However, often analyses include large datasets that are not needed in entirety. By including a script in inst, users can choose (easily) to reproduce the data included in the package BUT are not required recreate the input data for the analysis. It does not make sense to obscure the scripts away.

Improve this question
5
  • What do you mean by "R scripts stored in the inst directory that produce data objects then included in the package". Stuff in /inst is not run, it is copied to the package root Commented May 8, 2020 at 0:27
  • Correct -- often I include data objects that were themselves created by some script that I do not intend users to run. For reproducibility purposes, I include the script in inst. It would be cool to also include that script in the documentation. Commented May 8, 2020 at 0:35
  • 1
    If you don't intend users to run your script, don't put it in /inst Commented May 8, 2020 at 0:43
  • I don’t intend the typical user to run the code. Commented May 8, 2020 at 0:57
  • "R packages provide an ideal format for disseminating fully-reproducible analyses." If it was an ideal format, you wouldn't have to ask this question Commented May 8, 2020 at 1:35

1 Answer 1

Reset to default
2

First, I would agree with Hong Ooi and say that in general you shouldn't put it in inst/; that is copied into the user's installation. I follow the advice in Hadley Wickham's R Packages and put them in a folder called data-raw/ (which you then add to .Rbuildignore). However, for the use case you further describe in the edits to your question, I can see why you would want to put the script in inst/ to distribute to your users.

But, on to the problem at hand. You can do this by instead using @evalRd and adding the \details{} part in rdScript(). I set up a dummy package foo with the file inst/bar.R with the following code in it:

a <- 5 b <- 8

Then I made R/baz.R with

rdScript <- function(filename, prepend = "") { lns <- readLines(filename) lns <- paste(sprintf("\\code{%s}", lns), collapse = "\n\n") return(paste("\\details{", prepend, "\n", lns, "}", sep = "\n")) } #' @name someObj #' @title Some R Object #' @description Some R Object #' #' @evalRd rdScript("inst/bar.R", "Data was created with the following script:") NULL

After document()ing, I get the following in man/someObj.Rd:

% Generated by roxygen2: do not edit by hand % Please edit documentation in R/baz.R \name{someObj} \alias{someObj} \title{Some R Object} \description{ Some R Object } \details{ Data was created with the following script: \code{a <- 5} \code{b <- 8} }

which renders in RStudio's help viewer as

enter image description here

Improve this answer
Sign up to request clarification or add additional context in comments.

5 Comments

The issue here is the new line. In the rendered help doc, i.e. running ?someObj the code does not have newlines rendered.
@dayne See edits; just need to add some more "\n"
I could have sworn I tried that exact modification with the \n\n and it didn't work -- this is what I get for asking questions at night. Nice answer! Also, see my edit regarding the use of inst.
@dayne In the context you describe in your edit, it makes sense. The question of whether to put in inst/ or not depends fully on if you want to distribute the script to your users. In this case, it sounds like the answer is "yes," so it makes total sense for you to do that. Glad it helped, cheers!
Let us continue this discussion in chat.

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.