reproducible (version 2.0.10)

.sortDotsUnderscoreFirst: Exported generics and methods

Description

There are a number of generics that are exported for other packages to use. These are listed below. They are not intended for use by normal users; rather, they are made available for package developers to build specific methods.

Usage

.sortDotsUnderscoreFirst(obj)
.orderDotsUnderscoreFirst(obj)
.tagsByClass(object)
# S4 method for ANY
.tagsByClass(object)
.cacheMessage(
  object,
  functionName,
  fromMemoise = getOption("reproducible.useMemoise", TRUE),
  verbose = getOption("reproducible.verbose", 1)
)
# S4 method for ANY
.cacheMessage(
  object,
  functionName,
  fromMemoise = getOption("reproducible.useMemoise", TRUE),
  verbose = getOption("reproducible.verbose", 1)
)
.addTagsToOutput(object, outputObjects, FUN, preDigestByClass)
# S4 method for ANY
.addTagsToOutput(object, outputObjects, FUN, preDigestByClass)
.preDigestByClass(object)
# S4 method for ANY
.preDigestByClass(object)
.checkCacheRepo(
  object,
  create = FALSE,
  verbose = getOption("reproducible.verbose", 1)
)
# S4 method for ANY
.checkCacheRepo(
  object,
  create = FALSE,
  verbose = getOption("reproducible.verbose", 1)
)
.prepareOutput(object, cachePath, ...)
# S4 method for ANY
.prepareOutput(object, cachePath, ...)
.addChangedAttr(object, preDigest, origArguments, ...)
# S4 method for ANY
.addChangedAttr(object, preDigest, origArguments, ...)
updateFilenameSlots(obj, curFilenames, newFilenames, isStack = NULL)
# S3 method for default
updateFilenameSlots(obj, curFilenames, newFilenames, isStack = NULL, ...)
# S3 method for list
updateFilenameSlots(obj, ...)
# S3 method for environment
updateFilenameSlots(obj, ...)
makeMemoisable(x)
# S3 method for default
makeMemoisable(x)
# S3 method for data.table
makeMemoisable(x)
unmakeMemoisable(x)
# S3 method for default
unmakeMemoisable(x)

Value

.sortDotsUnderscoreFirst: the same object as obj, but sorted with dots and underscores first, lower case before upper case.

.tagsByClass default method returns NULL.

.cacheMessage: nothing; called for its messaging side effect, which, by default, just edits the name of the function into a generic "loaded cached result" message.

.addTagsToOutput: The inputted object but with tags attached.

.preDigestByClass: A list with elements that have a difficult time being digested correctly, e.g., an S4 object with some elements removed and handled for digesting purposes. The default method for preDigestByClass and simply returns NULL.

.checkCacheRepo: A character string with a path to a cache repository.

.prepareOutput: The object, modified

.addChangedAttr: the object, with an attribute ".Cache" and sub-element, "changed", added set to either TRUE or FALSE

updateFilenameSlots: The original object, but with its internal file pointer updated to the newFilenames

The same object, but with any modifications, especially dealing with saving of environments, which memoising doesn't handle correctly in some cases.

Arguments

obj

An object. This function only has useful methods for Raster*, with all other classes being simply a pass-through

object

Any R object returned from a function

functionName

A character string indicating the function name

fromMemoise

Logical. If TRUE, the message will be about recovery from memoised copy

verbose

Numeric, -1 silent (where possible), 0 being very quiet, 1 showing more messaging, 2 being more messaging, etc. Default is 1. Above 3 will output much more information about the internals of Caching, which may help diagnose Caching challenges. Can set globally with an option, e.g., options('reproducible.verbose' = 0) to reduce to minimal

outputObjects

Optional character vector indicating which objects to return. This is only relevant for list, environment (or similar) objects

FUN

A function

preDigestByClass

A list, usually from .preDigestByClass

create

Logical. If TRUE, then it will create the path for cache.

cachePath

A repository used for storing cached objects. This is optional if Cache is used inside a SpaDES module.

...

Anything passed to methods.

preDigest

The full, element by element hash of the input arguments to that same function, e.g., from .robustDigest

origArguments

These are the actual arguments (i.e., the values, not the names) that were the source for preDigest

curFilenames

An optional character vector of filenames currently existing and that are pointed to in the obj. If omitted, will take from the obj using Filenames(obj)

newFilenames

An optional character vector of filenames to use instead of the curFilenames. This can also be a single directory, in which case the renaming will be given: file.path(newFilenames, basename(Filenames(obj, allowMultiple = FALSE)))

x

An object to make memoisable. See individual methods in other packages.

Author

Eliot McIntire

Details

.sortDotsUnderscoreFirst: This exists so Windows, Linux, and Mac machines can have the same order after a sort. It will put dots and underscores first (with the sort key based on their second character, see examples. It also sorts lower case before upper case.

The methods should do as described below.

.tagsByClass should return a character vector, with a single colon (":") dividing two parts: the tag type and tag value, for the specific class.

.cacheMessage should make a call to message that gives information about the loaded cached object being returned.

.addTagsToOutput should add one or more attributes to an object, named either "tags", "call" or "function". It may be wise to do a "deep" copy within this method, but it may not be necessary.

.addChangedAttr should return the same object, with this a very specific attribute added: it must be named ".Cache", and have a sub-list element named "changed", which must be a logical, TRUE or FALSE, to describe whether the object has changed or not since last attempt to cache it. This is mostly useful when there are only one or a few sub-elements of e.g., a large list, that are changed. Cache will be able to only recover the changed parts, to reduce time required to complete a call to Cache.

updateFilenameSlots: this exists because when copying file-backed rasters, the usual mechanism of writeRaster can be very slow. This function allows for a user to optionally create a hard link to the old file, give it a new name, then update the filename slot(s) in the Raster* class object. This can be 100s of times faster for large rasters.

makeMemoiseable and unmakeMemoisable methods are run during Cache. The methods should address any parts that will not successfully work for memoising, most notably, data.table or other pass-by-reference objects likely need to be deep copied, so that the memoised version doesn't get changed after being stashed in the RAM cache (i.e., memoised)

makeMemoiseable and unmakeMemoisable are, by default, just a pass through for most class. reproducible only has a method for data.table class objects.

Examples

items <- c(A = "a", Z = "z", `.D` = ".d", `_C` = "_C")
.sortDotsUnderscoreFirst(items)

# dots & underscore (using 2nd character), then all lower then all upper
items <- c(B = "Upper", b = "lower", A = "a", `.D` = ".d", `_C` = "_C")
.sortDotsUnderscoreFirst(items)

# with a vector
.sortDotsUnderscoreFirst(c(".C", "_B", "A")) # _B is first

.tagsByClass(character())

a <- 1
.cacheMessage(a, "mean")

a <- 1
.preDigestByClass(a) # returns NULL in the simple case here.

a <- normalizePath(file.path(tempdir(), "test"), mustWork = FALSE)
.checkCacheRepo(a, create = TRUE)

a <- 1
.prepareOutput(a) # does nothing

b <- "NULL"
.prepareOutput(b) # converts to NULL

if (requireNamespace("terra", quietly = TRUE)) {
  r <- terra::rast(terra::ext(0, 10, 0, 10), vals = 1:100)

  # write to disk manually -- will be in tempdir()
  r <- terra::writeRaster(r, file = tempfile(fileext = ".tif"))

  # copy it to the cache repository
  r <- .prepareOutput(r, tempdir())
}
a <- 1
.addChangedAttr(a) # does nothing because default method is just a pass through