load R object by name

load_object(
  object,
  save_date = NULL,
  objects_path = jamsession_paths()$objects,
  envir = globalenv(),
  verbose = TRUE,
  ...
)

Arguments

object	`character` string indicating the name of the R object to load, or `data.frame` output from `grep_objects()` which contains colnames `("object", "object_path", "object_file")`.
save_date	optional character string with a specific date to use when loading an object. This string is matched with the `"save_date"` returned by `list_objects()`. When `save_date` is `NULL`, the most recent object is loaded, which is the default behavior.
objects_path	character vector of one or more file paths to search for saved R objects. When `objects_path=NULL`, it uses the output from `jamsession_paths()$objects`.
envir	optional R environment inside which to load the R object. Note that if an R object already exists in this environment, it will overwritten without warning. This behavior is intended by `load_object()`.
verbose	logical whether to print verbose output
...	additional arguments are ignored.

Value

invisible name of the R object loaded. It also loads the R object into the environment specified, by default the active global environment .GlobalEnv.

Details

This function loads the most recently saved R object by name, from a given file path. This mechanism is intended to help share useful R objects across R sessions, especially where it may be helpful to discover R objects by name, and where R objects may continue to be useful over time.

Typically this function is called with the name of one or more saved objects, and loads the most recent version of each. However, the argument save_date can be supplied as a vector, which is recycled for each saved object, as a method to load a specific version of an object. This behavior is not intended for routine use, but is available in rare cases that you may want to inspect previous versions of an object.

Note that envir can be used to load the object into a separate environment, if needed.

Examples

my_df <- data.frame(A=LETTERS[1:5], a=letters[1:5]);
print(my_df);
#>   A a
#> 1 A a
#> 2 B b
#> 3 C c
#> 4 D d
#> 5 E e

save_object("my_df");
#> Error in save_object("my_df"): Object could not be saved.

grep_objects("my_df");
#>                              object save_date days_old file_size
#> my_df_12jun2020               my_df 12jun2020      259 160 bytes
#> my_df-my_df2_12jun2020 my_df-my_df2 12jun2020      259 212 bytes
#>                                             object_path
#> my_df_12jun2020        /Users/wardjm/Projects/R-objects
#> my_df-my_df2_12jun2020 /Users/wardjm/Projects/R-objects
#>                                         object_file
#> my_df_12jun2020               my_df_12jun2020.RData
#> my_df-my_df2_12jun2020 my_df-my_df2_12jun2020.RData

rm(my_df);

load_object("my_df");
#> Warning: no non-missing arguments to min; returning Inf
#> Warning: no non-missing arguments to max; returning -Inf
#> Warning: no non-missing arguments to min; returning Inf
#> Warning: no non-missing arguments to max; returning -Inf
#> ##  (11:51:44) 26Feb2021:  load_object(): Loaded object: 'my_df' 
print(my_df);
#>   A a
#> 1 A a
#> 2 B b
#> 3 C c
#> 4 D d
#> 5 E e

load_object(grep_objects("my_df"))
#> ##  (11:51:44) 26Feb2021:  load_object(): Loaded object: 'my_df' 
#> ##  (11:51:44) 26Feb2021:  load_object(): Loaded objects: my_df,my_df2 
print(my_df);
#>   A a
#> 1 A a
#> 2 B b
#> 3 C c
#> 4 D d
#> 5 E e

######################################
# Load into a separate environment
rm(my_df);
#> Warning: object 'my_df' not found
sep_env <- new.env();
load_object("my_df", envir=sep_env);
#> ##  (11:51:44) 26Feb2021:  load_object(): Loaded object: 'my_df' 

# this object is not in the current workspace
find("my_df");
#> [1] ".GlobalEnv"

# you can use get() to see this object
print(get("my_df", envir=sep_env));
#>   A a
#> 1 A a
#> 2 B b
#> 3 C c
#> 4 D d
#> 5 E e

# or you can attach the environment to use objects inside
find("my_df");
#> [1] ".GlobalEnv"
attach(sep_env);
#> The following object is masked _by_ .GlobalEnv:
#> 
#>     my_df
find("my_df");
#> [1] ".GlobalEnv" "sep_env"   

# detach when no longer using this environment
detach("sep_env");
find("my_df");
#> [1] ".GlobalEnv"

######################################
# example showing two objects stored together
my_df2 <- data.frame(B=LETTERS[11:15], b=letters[11:15]);
load_object("my_df");
#> ##  (11:51:44) 26Feb2021:  load_object(): Loaded object: 'my_df' 
save_object(c("my_df", "my_df2"));
#> ##  (11:51:44) 26Feb2021:  save_objects(): Objects saved:~/Projects/R-objects/my_df-my_df2_26feb2021.RData 

grep_objects("my_df2");
#>                              object save_date days_old file_size
#> my_df-my_df2_26feb2021 my_df-my_df2 26feb2021        0 212 bytes
#>                                             object_path
#> my_df-my_df2_26feb2021 /Users/wardjm/Projects/R-objects
#>                                         object_file
#> my_df-my_df2_26feb2021 my_df-my_df2_26feb2021.RData
loaded <- load_object(grep_objects("my_df2"));
#> ##  (11:51:44) 26Feb2021:  load_object(): Loaded objects: my_df,my_df2 

# note that it loads two objects
print(loaded);
#> [1] "my_df"  "my_df2"

load R object by name

Arguments

Value

Details

See also

Examples