mizer (version 3.2.0)

saveParams: Save and restore mizer objects

Description

saveParams() saves a MizerParams object to a file. This can then be restored with readParams(). saveSim() and readSim() provide the same lifecycle for MizerSim objects.

Usage

saveParams(params, file)
readParams(file, install_extensions = FALSE)
saveSim(sim, file)
readSim(file, install_extensions = FALSE)

Value

saveParams() and saveSim() return NULL invisibly. readParams() returns a MizerParams object. readSim() returns a MizerSim object.

Arguments

params

A MizerParams object

file

The name of the file or a connection where the object is saved to or read from.

install_extensions

Logical. Should readParams() or readSim() attempt to install missing extension packages before registering the saved extension chain?

sim

A MizerSim object

What <code>saveParams()</code> and <code>saveSim()</code> do beyond <code><a href="/link/saveRDS()?package=mizer&version=3.2.0" data-mini-rdoc="mizer::saveRDS()">saveRDS()</a></code>

• They validate the object before writing it, so a corrupted or inconsistent object is caught at save time rather than when you next try to use it.

• They strip any extension class and save the object as a plain base mizer object (recording which extension packages it needs in a slot). This means the file can be read back even in an R session where the extension packages that defined those S4 classes are not loaded, and it protects the file against future changes to those extension classes.

• They check that the required extension packages are installed and stop with an informative error if they are not, so you do not save a file that you would be unable to read back.

• They warn if the model relies on custom functions (custom rate, dynamics, selectivity or predation-kernel functions that are not provided by mizer or a registered extension package). Such functions are not stored in the file, so to share the model you also need to share an R script or R Markdown file defining them.

Before saving a model you may want to set its metadata with setMetadata().

What <code>readParams()</code> and <code>readSim()</code> do beyond <code><a href="/link/readRDS()?package=mizer&version=3.2.0" data-mini-rdoc="mizer::readRDS()">readRDS()</a></code>

• They upgrade an object saved by an older version of mizer to the current structure (see upgradeParams()), so that models saved years ago still load correctly.

• They re-register the extension packages that the model needs and, optionally, install any that are missing (see install_extensions), before restoring the object's extension class.

• They coerce the object back to its extension class and revalidate it, reversing the class-stripping done at save time so you get back an object of the same class you saved.

Details

While these functions ultimately use saveRDS() and readRDS(), they do extra work to make the saved file more robust and more portable, so you should always prefer them over calling saveRDS()/readRDS() directly on a mizer object.

See Also

"Using mizer extension packages": vignette("using-extension-packages", package = "mizer")

Examples

# Save params to a temporary file and read them back
tmp <- tempfile(fileext = ".rds")
saveParams(NS_params, file = tmp)
params <- readParams(tmp)
identical(params, NS_params)

# Save and read back a simulation
tmp2 <- tempfile(fileext = ".rds")
saveSim(NS_sim, file = tmp2)
sim <- readSim(tmp2)
identical(sim, NS_sim)