Introduction to jamsession

The jamsession package and functions are motived primarily to make your (my) analysis workflows as efficient as possible. They start with the simple idea of storing certain information in a central location, partly because it makes it easier to find months or years later. This workflow also works well if more often than not, you have multiple R sessions open and active, since these functions add the project name to the R prompt.

The R session and object files are versioned with the date, which has been an appropriate level of granularity, as well as being useful information when returning to work on past projects.

That said, this package mainly focuses on three aspects of R analysis work:

R sessions

This package stores and loads R sessions via .RData files from one stored location. These methods are useful are when analyzing data on different projects, where one may be asked to review data or results from projects years after the initial analysis. The methods here also store the R command history, which can be helpful when picking up where one left off.

Saving or loading an R session also sets the R prompt to the project name, which is particularly helpful when multiple R sessions are open an active at once.

R objects

This package also stored individual R objects in their own central location, in order to make it efficient to save and load objects in any R session, regardless the project or current working directory.

R functions

This package allows a clean mechanism of using a helper R script with functions to load and reload for active analysis use. Doing so minimizes copy-paste into active consoles, including via Rstudio, but also keeps function code in their own environment instead of the global environment. When stored in the global environment, the function code is saved along with the R session, which may not be desirable especially when using a large set of helper functions.

Motivations

Some motivations for this package:

make it efficient to find past R sessions and R objects by name, without the need to traverse down a nested file directory structure
make stored sessions and objects versioned by date, rather than using only the project or object name, and not needing to increment a version number every time a file is saved
provide a quick way to save and load R objects across different R sessions, to share useful objects in a structured, repeatable way
provide a clean method to load R functions from a separate file, to avoid having to copy-paste functions inside an R script, and to avoid R functions becoming part of the environment

Basic R session workflow

When starting a new project in a new R console, it is helpful to initiate the environment with the project name, by saving a new session. By default, the R prompt will change to display the session.

Note that we add the argument sessions_path=tempdir() only for this vignette, in typical use this argument is not used, because R sessions are stored in one location.

library(jamsession);
some_object <- data.frame(A=LETTERS[1:10]);
save_jamsession("jamsessionVignette",
   sessions_path=tempdir());
#> ##------ Mon Nov 17 17:56:31 2025 ------##
#> ##  (17:56:31) 17Nov2025:   save_jamsession(): Saved jamsession 'jamsessionVignette' to sessions_path 'C:\Users\JAMES~1.WAR\AppData\Local\Temp\RtmpSSHQA4' 
#> ##  (17:56:31) 17Nov2025:   save_jamsession(): session_file:C:\Users\JAMES~1.WAR\AppData\Local\Temp\RtmpSSHQA4/inProgress_jamsessionVignette_17nov2025.RData

You may then do some work and wish to save your session:

x <- rnorm(90);
y <- matrix(ncol=9, data=x);
## Usually only run like this:
# save_jamsession();

## For this vignette we add sessions_path
save_jamsession("jamsessionVignette",
   sessions_path=tempdir());
#> ##------ Mon Nov 17 17:56:31 2025 ------##
#> ##  (17:56:31) 17Nov2025:   save_jamsession(): Saved jamsession 'jamsessionVignette' to sessions_path 'C:\Users\JAMES~1.WAR\AppData\Local\Temp\RtmpSSHQA4' 
#> ##  (17:56:32) 17Nov2025:   save_jamsession(): session_file:C:\Users\JAMES~1.WAR\AppData\Local\Temp\RtmpSSHQA4/inProgress_jamsessionVignette_17nov2025.RData

You can later start R and pick up where you left off, which is simulated here by removing these objects, then loading the session:

rm(y);
load_jamsession("jamsessionVignette",
   sessions_path=tempdir());
#> ##  (17:56:32) 17Nov2025:   load_jamsession(): Loading session: C:/Users/JAMES~1.WAR/AppData/Local/Temp/RtmpSSHQA4/inProgress_jamsessionVignette_17nov2025.RData 
#> ##  (17:56:32) 17Nov2025:   load_jamsession(): Loaded session:jamsessionVignette into environment 'R_GlobalEnv' 
#> ##  (17:56:32) 17Nov2025:   load_jamsession(): jamba::setPrompt()
print(head(y));
#>              [,1]       [,2]       [,3]       [,4]        [,5]        [,6]
#> [1,] -1.400043517 -0.5536994  0.4681544  0.9353632  0.07003485  0.86208648
#> [2,]  0.255317055  0.6289820  0.3629513  0.1764886 -0.63912332 -0.24323674
#> [3,] -2.437263611  2.0650249 -1.3045435  0.2436855 -0.04996490 -0.20608719
#> [4,] -0.005571287 -1.6309894  0.7377763  1.6235489 -0.25148344  0.01917759
#> [5,]  0.621552721  0.5124269  1.8885049  0.1120381  0.44479712  0.02956075
#> [6,]  1.148411606 -1.8630115 -0.0974451 -0.1339970  2.75541758  0.54982754
#>            [,7]       [,8]       [,9]
#> [1,]  1.0743459 -1.4707363  1.9243433
#> [2,] -0.6650882  0.2841503  1.2983928
#> [3,]  1.1139524  1.3373204  0.7487913
#> [4,] -0.2458964  0.2366963  0.5562243
#> [5,] -1.1775633  1.3182934 -0.5482573
#> [6,] -0.9758506  0.5239098  1.1105349

Saving R objects

If you want to save an object, it is best to name it something specific before saving it. The call the saveObject() function with the name of the object:

Note that we add the argument objects_path=tempdir() only for this vignette, in typical use this argument is not used, because R objects are stored in one location.

jamsessionVignetteY <- t;
save_object("jamsessionVignetteY",
   objects_path=tempdir());
#> ##  (17:56:32) 17Nov2025:   save_objects(): Object saved:C:\Users\JAMES~1.WAR\AppData\Local\Temp\RtmpSSHQA4/jamsessionVignetteY_17nov2025.RData

You can then load this object from any R console using load_object(), simulated here by removing the object, then loading it from the saved object file:

rm(jamsessionVignetteY);
load_object("jamsessionVignetteY",
   objects_path=tempdir());
#> ##  (17:56:32) 17Nov2025:   load_object(): Loaded object: 'jamsessionVignetteY'
print(head(jamsessionVignetteY));
#>                 
#> 1 function (x)  
#> 2 UseMethod("t")

Loading R functions

R is a functional programming language, which makes it especially useful and powerful to write and re-use custom functions. Most R analysts have built up a long list of useful helper functions, either for re-use across all their projects, or written specifically per project. Either way, these functions need to be loaded into the R workspace, and very likely will need to be refreshed as the functions are updated over time.

We demonstrate having a utility script by creating a temporary script, then using refresh_functions().

## Create a simple R script function fun()
r_script <- "
#' Simple print function
#' 
#' This function simply runs print()
#'
#' @param x any R object that can be printed.
#' @param ... additional arguments are passed to print().
#'
#' @export
printfun <- function(x, ...) {print(x, ...)};
";

## Save to a file in tempdir
fn_file <- file.path(tempdir(),
   "jamvignette_functions.R");
## Save the R script to a file
cat(r_script, file=fn_file);

Now the file has been saved under the name “jamsession”. We can load this file with refresh_functions().

For this vignette, we include argument functions_path=tempdir(), but this argument is usually not necessary, when functions are saved to a common path. Run jamvignette_paths() to see or set the expected paths.

## Load the R script
refresh_functions("jamvignette",
   functions_path=tempdir());
#> ✔ Creating C:/Users/JAMES~1.WAR/AppData/Local/Temp/RtmpSSHQA4/jamvignette/.
#> ✔ Setting active project to
#>   "C:/Users/james.ward/AppData/Local/Temp/RtmpSSHQA4/jamvignette".
#> ✔ Creating R/.
#> ✔ Writing DESCRIPTION.
#> ✔ Writing NAMESPACE.
#> ✔ Setting active project to "<no active project>".
#> ##  (17:56:33) 17Nov2025:   refresh_functions(): Loaded temporary package as 'jamvignette'

## search() shows the environments including jamvignette
print(search());
#>  [1] ".GlobalEnv"          "devtools_shims"      "package:jamvignette"
#>  [4] "package:jamsession"  "package:stats"       "package:graphics"   
#>  [7] "package:grDevices"   "package:utils"       "package:datasets"   
#> [10] "package:methods"     "Autoloads"           "tools:callr"        
#> [13] "package:base"

## find() to show where printfun is located
find("printfun")
#> [1] "package:jamvignette"

Lastly, we can run the printfun() function to show it works.

printfun(LETTERS[1:10]);
#>  [1] "A" "B" "C" "D" "E" "F" "G" "H" "I" "J"

Introduction to jamsession

James M. Ward

2025-11-17