Using job::export() to control exports from RStudio Jobs • job

Use job::export() to control what is returned from a job. The documentation for job::export() includes code examples and may be useful to read first. In this article, we’ll discuss situations where it definitely makes sense to deviate from this default. Check out the related article on controlling imports to a job.

job::export() should be called as the last command in the job. If it isn’t called, job defaults to calling job::export("changed", file = NULL).

Ignore temporary objects

Use export(c(main, results)) to keep the export small and uncluttered. This is useful if you have many or large intermediate objects. For example, here we do some data preprocessing, but only return the final dataset and the model fit:

job::job({
  # Select some data
  rows = 1:5
  cols = c("mpg", "cyl", "hp")
  df = mtcars[rows, cols]
  
  # Fit and export
  fit = lm(mpg ~ ., df)
  job::export(c(df, fit))
})

When the main result is not an object

Sometimes, a text output is the most interesting, e.g., when your job contains something like print(summary(fit)). In these cases, just call job::export("none") on the last line of the code chunk to prevent the job from returning intermediate objects to the main session (or a file).

Export to file

If you just want to output to a file, I recommend using saveRDS() for single objects or export(..., file = "filename.RData") for multiple objects. You can use relative paths for the file name because the job runs in the same working directory as your RStudio session. Example:

job::job({
  d = "I am dee"
  saveRDS(d, "d_object.rds")  # Save single objects
  b = "I am bee"
  job::export("changed", file = "my_environment.RData")
})

When you use the job::export(..., file) argument, it implicitly calls job::export("none") after saving, i.e., returns nothing to the main session. To load the objects into your main session (or another job), simply:

# Load single object
d = readRDS("d_object.rds")
print(d)  # "I am ae"

# Load into global 
load("my_environment.RData")
print(b)  # "I am bee"

# Load into environment
job_result = new.env()
load("my_environment.RData", envir = job_result)
print(job_result$b)  # "I am bee"

You can also use save() and save.image(envir = sys.frame(sys.nframe())) inside the code chunk. The latter will include two functions called emitProgress() and sourceWithProgress() are set by RStudio.