4

Motivation

My colleagues and I routinely create ad hoc scripts in R, to perform ETL on proprietary data and generate automated reports for clients. I am attempting to standardize our approach, for the sake of consistency, modularity, and reusability.

In particular, I want to consolidate our most commonly used functions in a central directory, and to access them as if they were functions from a proprietary R package. However, I am quite raw as an R developer, and my teammates are even less experienced in R development. As such, the development of a formal package is unfeasible for the moment.

Approach

Fortunately, the box package, by Stack Overflow's very own Konrad Rudolph, provides (among other modularity) an accessible approach to approximate the behavior of an R package. Unlike the rigorous development process outlined by the RStudio team, box requires only that one create a regular .R file, in a meaningful location, with roxygen2 documentation (#') and explicit @exports:

Writing modules

The module bio/seq, which we have used in the previous section, is implemented in the file bio/seq.r. The file seq.r is, by and large, a normal R source file, which happens to live in a directory named bio.

In fact, there are only three things worth mentioning:

  1. Documentation. Functions in the module file can be documented using ‘roxygen2’ syntax. It works the same as for packages. The ‘box’ package parses the
    documentation and makes it available via box::help. Displaying module help requires that ‘roxygen2’ is installed.

  2. Export declarations. Similar to packages, modules explicitly need to declare which names they export; they do this using the annotation comment #' @export in front of the name. Again, this works similarly to ‘roxygen2’ (but does not require having that package installed).

At the moment, I am tinkering around with a particular module, as "imported" into a script. While the "import" itself works seamlessly, I cannot seem to access the documentation for my functions.

Code

I am experimenting with box on a Lenovo ThinkPad running Windows 10 Enterprise. I have created a script, aptly titled Script.R, whose location serves as my working directory. My module exists in the relative subdirectory ./Resources/Modules as the humble file time.R, reproduced here:

###########################
## Relative Date Windows ##
###########################

#' @title Past Day of Week
#' @description Determine the date of the given weekday that fell a given number
#'   of weeks before the given date.
#' @param from \code{Date} object. The point of reference, from which we go
#'   backwards. Defaults to current \code{Sys.Date()}.
#' @param back \code{integer}. The number of weeks to go backward from the point
#'   of reference; negative values go forward. Defaults to \code{1}, for last
#'   week. Weeks begin on \code{"Monday"}.
#' @param weekday \code{character}. The weekday within the week targeted by
#'   \code{back}; one of \code{c("Monday", "Tuesday", "Wednesday", "Thursday",
#'   "Friday", "Saturday", "Sunday")}.
#' @export
#' @return The date of the \code{weekday} falling in the week \code{back} weeks
#'   prior to the week in which \code{from} falls. Defaults to \code{"Monday"}.
past_weekday <- function(from = Sys.Date(),
                         back = 1,
                         weekday = c("Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday")
                         ) {
  cycle <- c("Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday")
  
  from <- as.Date(from)
  back <- as.integer(back)
  
  weekday_index <- (which(cycle == weekday[1]) - 1) %% 7
  
  from_index <- (which(cycle == "Sunday") + as.POSIXlt(from)$wday - 1) %% 7
  
  weekdate <- as.Date(from) - lubridate::days(from_index) - lubridate::weeks(as.numeric(back)) + lubridate::days(weekday_index)
  
  return(as.Date(weekdate))
}

Observe the roxygen2 documentation, as indicated by the special #' comments and @ tags. The documentation for past_weekday() is of far greater interest to me than the function itself.

Last and certainly least, here is reproduced Script.R itself:

# Set the working directory to the location of this very script.
setwd(this.path::this.dir())

# Access the functions in 'time.R' by relative location.
box::use(Resources/Modules/time)

# Run the function with its default values.
time$past_weekday()

# View the help page for the function.
box::help(time$past_weekday)

In theory, that final line will display the documentation for past_weekday(), via box::help():

enter image description here

The box vignette gives a simple example to that effect:

We can also display the interactive help for individual names using the box::help function, e.g.:

 box::help(seq$revcomp)

Problem

The first three lines of Script.R give me exactly what I desire. That is, they load time into R as an environment, from which I can access past_weekday() via time$past_weekday(). This module$function() syntax is analogous to the qualification of functions from formal packages: package::function(). Indeed, past_weekday() itself works just as expected:

time$past_weekday()
# [1] "2021-07-19"

However, when I attempt to interactively access the documentation

box::help(time$past_weekday)

the console displays the following warnings

Warning messages:
1: In utils::packageDescription(package, fields = "Version") :
  no package 'PKG' was found
2: In file.create(to[okay]) :
  cannot create file 'C:\Users\greg\AppData\Local\Temp\RtmpYBTTyG/.R/doc/html/module:Resources/Modules/time.html', reason 'Invalid argument'

and the interactive help window is empty but for this error message:

enter image description here

For my team, this could prove a serious issue. Since we often rely on useful functions written by each other, it is crucial that any user on our team be able to easily access clear documentation by the author of the function...just as the user is accustomed to doing with formal R packages. Without this ability, the user must either bug the author for clarification, or blunder ahead without a clear understanding of the function's purpose and limitations.

Suspicions

When I read the warning

In file.create(to[okay]) :
cannot create file 'C:\Users\greg\AppData\Local\Temp\RtmpYBTTyG/.R/doc/html/module:Resources/Modules/time.html', reason 'Invalid argument'

I was drawn to the filepath

C:\Users\greg\AppData\Local\Temp\RtmpYBTTyG/.R/doc/html/module:Resources/Modules/time.html

as the cause for an Invalid argument to file.create(). To my knowledge, a directory name .../module:Resources/... containing a colon : is illegal on Windows and elsewhere.

Indeed, when I supply another illegal filepath ./illegal:directory:name/missing.txt to file.create()

file.create('./illegal:directory:name/missing.txt')
# [1] FALSE

I get the same warning:

Warning message:
In file.create("./illegal:directory:name/missing.txt") :
  cannot create file './illegal:directory:name/missing.txt', reason 'Invalid argument'

The culprit appears to be this line in help.R:

display_help(doc, paste0('module:', mod_name), help_type)
#                               ^
#                             Here

However, this seems far too simple a diagnosis. Frankly, I would be quite surprised to find such a portability issue within a package designed by a seasoned developer. I find it overwhelmingly more likely that I am simply out of my depth.

What am I missing?


Update 1

I tried it on my MacBook Air, running Mojave, and it actually worked! While I still got the first (rather odd) warning message on the console

Warning message:
In utils::packageDescription(package, fields = "Version") :
  no package 'PKG' was found

the interactive help window does display the intended documentation:

enter image description here

Naturally, this does not exactly solve my problem—the scripts will be executed on a VM running Windows, just like my Lenovo and every other computer used at my company. However, it does support the hypothesis that this issue is specific to box on Windows.


Update 2

Konrad has kindly confirmed that this is indeed a bug, and he's working on a fix. Many thanks to Konrad for his clarification and responsiveness!

5
  • 1
    Colons are perfectly legal on Unix filesystems. Windows is unique in not allowing them. But that doesn't really matter: R packages are easy to write. Use one of those (supported by thousands of experienced R users) if this package doesn't work for you. Jul 30, 2021 at 0:34
  • @user2554330 Thanks for the advice! Unfortunately, we are restricted exclusively to Windows, as the automations are triggered on a Windows VM. More importantly, when you say "R packages are easy to write", I should note I am too inexperienced to write a formal package efficiently, and (to my knowledge) my teammates have no experience whatsoever in developing packages. And we do indeed need to create a custom "package", containing our own helper functions that we use on a routine basis. As it stands, I am unfamiliar with any alternatives to box, for making "informal packages". Know of any?
    – Greg
    Jul 30, 2021 at 2:35
  • 1
    No, I know of no alternatives to box, nor any need for one. As I said, packages are easy to write. Personally I'd start with the old fashioned package.skeleton() function, but it's probably even easier to use the more recent usethis::create_package() function. Try it! Jul 30, 2021 at 12:27
  • 1
    Put simply, that’s a bug. Thanks for reporting it, I’ll be working on a fix shortly! Jul 30, 2021 at 16:33
  • Thank you @KonradRudolph, I really appreciate it! I wanted to disambiguate things by creating an r-box tag, but I lack the requisite rep/privileges, so thanks for that too!
    – Greg
    Jul 30, 2021 at 16:36

1 Answer 1

3

As noted, that’s a bug, now fixed.

But since we’re here, a word on usage:

# Set the working directory to the location of this very script.
setwd(this.path::this.dir())

This is generally not recommended. To quote Jenny Bryan:

If the first line of your R script is

setwd("C:\Users\jenny\path\that\only\I\have")

I will come into your office and SET YOUR COMPUTER ON FIRE 🔥.

‘box’ also doesn’t need this; instead, the idea is to configure a global module search path (equivalent to R’s package library, see .libPaths()), e.g. via the box.path option (this would usually go into the user’s .Rprofile configuration — not in the script itself!):

options(box.path = 'C:\User\Konrad\some\path')

Afterwards, modules that are installed in this search path will be found by box::use.

As noted, this should be a global setting. To use project-specific modules, you wouldn’t set a global search path; instead, you’d use relative imports:

box::use(./Resources/Modules/time)

This should work regardless of the working directory; it uses the calling script’s location instead. Consequently, this.path::this.dir() or similar hacks are never necessary with ‘box’. And to find data files, ‘box’ provides the box::file function which also works regardless of the current working directory.

See also FAQ: how to organise globally installed modules?

6
  • Hi Konrad, and thanks for taking the time to cover this in a formal answer! To address your points: (1) Unlike the hardcoded path "C:\Users\jenny\path\that\only\I\have", the call this.path::this.dir() is fully self-contained and portable for interactive use in RStudio, for source()ing, and for executables; indeed, my R projects using this approach have run swimmingly in other environments. While I've always striven to implement these principles, it's good to see them codified by Jenny Bryan!
    – Greg
    Jul 30, 2021 at 18:39
  • (2) I hope to make both of the following accessible from a script via box: (a) a global module of universally useful functions; and (b) local modules specific to each project. When digging into box yesterday, I was quite pleased to read of the box.path option, as it would easily allow my team to orient our separate scripts toward a central location. As for the relative imports, however, I should note that I previously tried box::use(./Resources/Modules/time), without using setwd(this.path::this.dir()), but it failed for me within RStudio. Below is the error message:
    – Greg
    Jul 30, 2021 at 18:43
  • Error in mapply(FUN = f, ..., SIMPLIFY = FALSE) : Unable to load module “./Resources/Modules/time”; not found in “C:/Users/greg/OneDrive - My Company/Documents” (inside “find_in_path(spec, mod_search_path(caller))”)
    – Greg
    Jul 30, 2021 at 18:43
  • @Greg Thanks for the error message. To clarify, is the code box::use(./Resources/Modules/time) inside an R source file which is open in RStudio, and which you’ve executed by sourcing the file or by pressing Ctrl+Return? And is that file stored in the Documents folder? Because if so, that should work. I’ll investigate. Jul 31, 2021 at 14:07
  • Thanks for looking into this! To answer your questions: the code is indeed inside an R source file Script.R; this file is open in RStudio; and I have executed it via source() (and Ctrl+Return too). However, that file is not stored in the Documents folder. Rather, it is stored in the Template (01) directory nested under my Desktop; Template (01) also contains the subdirectory Resources, which contains the subdirectory Modules, which contains time.R. The full location of the folder is: C:Users\greg\OneDrive - My Company\Desktop\Projects\Automations\Templates\Template (01)
    – Greg
    Jul 31, 2021 at 19:02

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.