Save an Artifact into a Repository

saveToLocalRepo function saves desired artifacts to the local Repository in a given directory. To learn more about artifacts visit archivist-package.

saveToLocalRepo(artifact, repoDir = aoptions("repoDir"),
  archiveData = TRUE, archiveTags = TRUE, archiveMiniature = TRUE,
  archiveSessionInfo = TRUE, force = TRUE, value = FALSE, ...,
  userTags = c(), use_flocks = aoptions("use_flocks"),
  silent = aoptions("silent"), ascii = FALSE,
  artifactName = deparse(substitute(artifact)))

saveToRepo(artifact, repoDir = aoptions("repoDir"), archiveData = TRUE,
  archiveTags = TRUE, archiveMiniature = TRUE,
  archiveSessionInfo = TRUE, force = TRUE, value = FALSE, ...,
  userTags = c(), use_flocks = aoptions("use_flocks"),
  silent = aoptions("silent"), ascii = FALSE,
  artifactName = deparse(substitute(artifact)))

asave(artifact, repoDir = aoptions("repoDir"), archiveData = TRUE,
  archiveTags = TRUE, archiveMiniature = TRUE,
  archiveSessionInfo = TRUE, force = TRUE, value = FALSE, ...,
  userTags = c(), use_flocks = aoptions("use_flocks"),
  silent = aoptions("silent"), ascii = FALSE,
  artifactName = deparse(substitute(artifact)))

Arguments

artifact	An arbitrary R artifact to be saved. For supported artifacts see details.
repoDir	A character denoting an existing directory in which an artifact will be saved.
archiveData	A logical value denoting whether to archive the data from the `artifact`.
archiveTags	A logical value denoting whether to archive Tags from the `artifact`.
archiveMiniature	A logical value denoting whether to archive a miniature of the `artifact`.
archiveSessionInfo	A logical value denoting whether to archive the session info that describes the context in this given artifact was created.
force	A logical value denoting whether to archive `artifact` if it was already archived in a Repository.
value	A logical value. Should the result be (default `value = FALSE`) the `md5hash` of a stored artifact or should the result be an input artifact (`value = TRUE`), so that valueing code can be used. See examples.
...	Graphical parameters denoting width and height of a miniature. See details. Further arguments passed to head. See Details section about `firtsRows` parameter
userTags	A character vector with Tags. These Tags will be added to the repository along with the artifact.
use_flocks	A logical value. If `TRUE` then `flock` package is used to lock access to a database. By default it's `FALSE`.
silent	If TRUE produces no warnings.
ascii	A logical value. An `ascii` argument is passed to save function.
artifactName	The name of the artifact with which it should be archived. If `NULL` then object's MD5 hash will be used instead.

Value

As a result of calling this function a character string is returned, which determines the md5hash of the artifact. If archiveData is TRUE, the result will also have an attribute, named data, which determines md5hash of the data needed to compute the artifact.

Details

saveToLocalRepo function saves desired artifacts to the local Repository in a given directory. Artifacts are saved in the local Repository, which is a SQLite database named backpack. After every saveToLocalRepo call the database is refreshed, so the artifact is available immediately in the database for other collaborators. Each artifact is archived in a md5hash.rda file. This file will be saved in a folder (under repoDir directory) named gallery. For each artifact, md5hash is a unique string of length 32 that is produced by digest function, which uses a cryptographical MD5 hash algorithm.

By default, a miniature of an artifact and (if possible) a data set needed to compute this artifact are extracted. They are also going to be saved in a file named by their md5hash in the gallery folder that exists in the directory specified in the repoDir argument. Moreover, a specific Tag-relation is going to be added to the backpack dataset in case there is a need to load the artifact with it's related data set - see loadFromLocalRepo or loadFromRemoteRepo. Default settings may be changed by using the archiveData, archiveTag or archiveMiniature arguments with the FALSE value.

Tags are artifact's attributes, different for various artifact's classes. For more detailed information check Tags

Archived artifact can be searched in the backpack dataset by using the searchInLocalRepo or searchInRemoteRepo functions. Artifacts can be searched by their Tags, names, classes or archiving date.

firstRows parameter.

If the artifact is of class data.frame or user set archiveData = TRUE for artifact that stores data within it, it is possible to specify how many rows of that data (or that data.frame) should be archived in a miniature. This can be done by adding the argument firstRows with the n corresponding to the number of rows (as in head). Note that, the data can be extracted only from the artifacts that are supported by the archivist package; see Tags.

Graphical parameters.

If the artifact is of class lattice or ggplot, and archiveMiniature = TRUE, then it is possible to set the miniature's width and height parameters. By default they are set to width = 800, height = 600.

Supported artifact's classes are listed here Tags.

Note

In the following way one can specify his own Tags for artifacts by setting artifact's attribute before call of the saveToLocalRepo function: attr(x, "tags" ) = c( "name1", "name2" ), where x is an artifact and name1, name2 are Tags specified by a user. It can be also done in a new, simpler way by using userTags parameter like this:

saveToLocalRepo(model, repoDir, userTags = c("my_model", "do not delete")).

Specifing additional Tags by attributes can be beneficial when one uses addHooksToPrint.

Important: if one wants to archive data from artifacts which is one of: survfit, glmnet, qda, lda, trellis, htest class, and this dataset is transformed within the artifact's formula then saveToLocalRepo will not archive this dataset. saveToLocalRepo only archives datasets that already exist in any of R environments.

Example: The data set will not be archived here.

z <- lda(Sp ~ ., Iris, prior = c(1,1,1)/3, subset = train[,-8])
saveToLocalRepo( z, repoDir )

Example: The data set will be archived here.

train2 <- train[,-8]
z <- lda(Sp ~ ., Iris, prior = c(1,1,1)/3, subset = train2)
saveToLocalRepo( z, repoDir )

Contact

Bug reports and feature requests can be sent to https://github.com/pbiecek/archivist/issues

References

Biecek P and Kosinski M (2017). "archivist: An R Package for Managing, Recording and Restoring Data Analysis Results." _Journal of Statistical Software_, *82*(11), pp. 1-28. doi: 10.18637/jss.v082.i11 (URL: http://doi.org/10.18637/jss.v082.i11). URL https://github.com/pbiecek/archivist

Examples

# NOT RUN {
exampleRepoDir <- tempfile(tmpdir = ".")
createLocalRepo(repoDir = exampleRepoDir)
data(swiss)
saveToLocalRepo(swiss, repoDir=exampleRepoDir, archiveSessionInfo = TRUE)
showLocalRepo(method = "md5hashes", repoDir = exampleRepoDir)
showLocalRepo(method = "tags", repoDir = exampleRepoDir)

loadFromLocalRepo(md5hash = '2a6e492cb6982f230e48cf46023e2e4f',
  repoDir = system.file("graphGallery", package = "archivist"), value = TRUE) -> model

saveToLocalRepo(model, repoDir=exampleRepoDir,
             userTags = c("do not delete", "my favourite model"))
aoptions('repoDir', system.file("graphGallery", package = "archivist"))
showLocalRepo(method = "tags")
data(iris)
asave(iris, silent = FALSE) # iris was used in pl
aoptions('repoDir', NULL, unset = TRUE)
deleteLocalRepo(exampleRepoDir, TRUE)
rm(exampleRepoDir)
# }