The overall goal of jamsession:
- Store R sessions
- Store R objects
- Refresh custom R functions
The core philosophy is to use
Centralize file paths for the purpose of re-use across different R sessions, or different R projects.
We have found it more practical to store re-usable data in central locations, rather than inside “silos” within each project subfolder. However, it can be configured to store into whichever file path makes sense for your project work.
Store and reload R sessions.
Sessions are stored for re-use, alongside a text list of objects stored in the RData file. Otherwise the only way to retrieve the set of objects contained in an RData file is to load the file.
Sessions can be loaded into an environment to protect existing R objects in globalenv().
Sessions can be loaded into globalenv(), making it easy to pick up from where the previous work saved that session.
grep_jamsessions() makes it easy to find past sessions.
The core driving use case is to “pick up that project from last year” and make a few custom figures. You could re-run all the steps, and surely this should always be possible. In some cases, it is too cumbersome to re-run everything, and it is beneficial to re-use the exact data as used in the previous work. To be fair, you could accomplish the same by loading Rmarkdown cache, see
jamba::reload_rmarkdown_cache().
Store and reload R objects across sessions.
Individual R objects may be quite useful to re-use in other R sessions. Using save() is straightforward, but produces another RData file with unknown contents.
save_object() uses a specific folder, making it convenient to find and re-use R objects by name. Again, objects can be loaded into an environment or into globalenv() to use in your active R session.
The driving use case is to help re-use R data objects which may be cumbersome to create initially, and where that data once created can be very useful in subsequent projects. For example, preparing genome gene-exon data. Or parsing MSigDB gene set pathway data into
data.frameorlistformats.
Load custom R functions as a virtual package.
It is quite common to create a file with custom R functions to use during a project analysis. Refreshing the function code during development can be tricky - either by copy-paste or by source("filename.R") or sys.source("filename.R").
refresh_functions() does similar work of sys.source() except that it creates a virtual R package by calling the amazing ‘pkgload’ R package. This step means your .R file can contain roxygen2 function help docs, and they will appear as help text for each function.
Whenever you update the R file, run refresh_functions() and it will cleanly apply the new code, even removing functions which get deleted from the source file.
As a nice by-product, you can even use refresh_functions() to create a new, proper R package from just the .R file, or multiple .R files.
The driving use case is to enable re-using custom R functions, in a more civilized way than by loading an .R file. In fact, R functions are often useful across multiple projects, and so they should be convenient to re-use for that purpose.
How to install
Install with ‘remotes’:
# install.packages("remotes")
remotes::install_github("jmw86069/jamsession")or use ‘pak’:
# install.packages("pak")
pak::pkg_install("jmw86069/jamsession")Other Details
The default file paths are stored in options() and can be reviewed and edited using jamsession_paths().
For our work, we typically define custom paths in .Rprofile for our convenience, but could be configured per project as relevant.
When saving jamsessions and objects, the output file is stored with the current date in the filename. It is a crude mechanism of “versioning”, and it is not intended to be a replacement for a proper versioning system such as Git. However, this crude “daily” versioning does afford some ability to review past versions of data and R session.
It also has the nice benefit of giving a rough idea of when the data were last saved.