Not all aspects of R objects are captured by current hashing tools in R
(e.g. digest::digest, knitr caching, archivist::cache).
This is mostly because many objects have "transient"
(e.g., functions have environments), or "disk-backed" features.
Since the goal of using reproducibility is to have tools that are not session specific,
this function attempts to strip all session specific information so that the digest
works between sessions and operating systems.
It is tested under many conditions and object types, there are bound to be others that don't
work correctly.
.robustDigest(
object,
.objects = NULL,
length = getOption("reproducible.length", Inf),
algo = "xxhash64",
quick = getOption("reproducible.quick", FALSE),
classOptions = list(),
...
)
# S4 method for ANY
.robustDigest(object, .objects, length, algo, quick, classOptions)
# S4 method for function
.robustDigest(object, .objects, length, algo, quick, classOptions)
# S4 method for expression
.robustDigest(object, .objects, length, algo, quick, classOptions)
# S4 method for language
.robustDigest(object, .objects, length, algo, quick, classOptions)
# S4 method for character
.robustDigest(object, .objects, length, algo, quick, classOptions)
# S4 method for Path
.robustDigest(object, .objects, length, algo, quick, classOptions)
# S4 method for environment
.robustDigest(object, .objects, length, algo, quick, classOptions)
# S4 method for list
.robustDigest(object, .objects, length, algo, quick, classOptions)
# S4 method for data.frame
.robustDigest(object, .objects, length, algo, quick, classOptions)
# S4 method for numeric
.robustDigest(object, .objects, length, algo, quick, classOptions)
# S4 method for matrix
.robustDigest(object, .objects, length, algo, quick, classOptions)
# S4 method for integer
.robustDigest(object, .objects, length, algo, quick, classOptions)an object to digest.
Character vector of objects to be digested. This is only applicable if there is a list, environment (or similar) with named objects within it. Only this/these objects will be considered for caching, i.e., only use a subset of the list, environment or similar objects. In the case of nested list-type objects, this will only be applied outermost first.
Numeric. If the element passed to Cache is a Path class
object (from e.g., asPath(filename)) or it is a Raster with
file-backing, then this will be
passed to digest::digest, essentially limiting the number of bytes
to digest (for speed). This will only be used if quick = FALSE.
Default is getOption("reproducible.length"), which is set to Inf.
The algorithms to be used; currently available choices are
md5, which is also the default, sha1, crc32,
sha256, sha512, xxhash32, xxhash64,
murmur32, spookyhash, blake3, crc32c,
xxh3_64, and xxh3_128.
Logical or character. If TRUE,
no disk-based information will be assessed, i.e., only
memory content. See Details section about quick in Cache().
Optional list. This will pass into .robustDigest for
specific classes. Should be options that the .robustDigest knows what
to do with.
Arguments passed to FUN, if FUN is not an expression.
Optional character vector indicating which objects are to
be considered while making digestible. This argument is not used
in the default cases; the only known method that uses this
in the default cases; the only known method that uses this
argument is the simList class from SpaDES.core.
A hash i.e., digest of the object passed in.
Raster* objects have the potential for disk-backed storage, thus, require more work.
Also, because Raster* can have a built-in representation for having their data content
located on disk, this format will be maintained if the raster already is file-backed,
i.e., to create .tif or .grd backed rasters, use writeRaster first,
then Cache.
The .tif or .grd will be copied to the raster/ subdirectory of the
cachePath.
Their RAM representation (as an R object) will still be in the usual cacheOutputs/
(or formerly gallery/) directory.
For inMemory raster objects, they will remain as binary .RData files.
Functions (which are contained within environments) are
converted to a text representation via a call to format(FUN).
Objects contained within a list or environment are recursively hashed
using digest::digest(), while removing all references to
environments.
Character strings are first assessed with dir.exists and file.exists
to check for paths. If they are found to be paths, then the path is hashed with
only its filename via basename(filename). If it is actually a path, we suggest
using asPath(thePath)
a <- 2
tmpfile1 <- tempfile()
tmpfile2 <- tempfile()
tmpfile3 <- tempfile(fileext = ".grd")
tmpfile4 <- tempfile(fileext = ".grd")
save(a, file = tmpfile1)
save(a, file = tmpfile2)
# treats as character string, so 2 filenames are different
digest::digest(tmpfile1)
#> [1] "7c769d3dad9329b1dc9cb130a15ce180"
digest::digest(tmpfile2)
#> [1] "af345b8460cc0f1d8c0dd67f70570220"
# tests to see whether character string is representing a file
.robustDigest(tmpfile1)
#> [1] "94c61fb1b6303aeb"
.robustDigest(tmpfile2) # same
#> [1] "94c61fb1b6303aeb"
# if you tell it that it is a path, then you can decide if you want it to be
# treated as a character string or as a file path
.robustDigest(asPath(tmpfile1), quick = TRUE)
#> [1] "1288738e8f768259"
.robustDigest(asPath(tmpfile2), quick = TRUE) # different because using file info
#> [1] "8449c17baac9e655"
.robustDigest(asPath(tmpfile1), quick = FALSE)
#> [[1]]
#> [1] "94c61fb1b6303aeb"
#>
.robustDigest(asPath(tmpfile2), quick = FALSE) # same because using file content
#> [[1]]
#> [1] "94c61fb1b6303aeb"
#>
# SpatRasters are have pointers
if (requireNamespace("terra", quietly = TRUE)) {
r <- terra::rast(system.file("ex/elev.tif", package = "terra"))
r3 <- terra::deepcopy(r)
r1 <- terra::writeRaster(r, filename = tmpfile3)
digest::digest(r)
digest::digest(r3) # different but should be same
.robustDigest(r1)
.robustDigest(r3) # same... data & metadata are the same
# note, this is not true for comparing memory and file-backed rasters
.robustDigest(r)
.robustDigest(r1) # different
}
#> [1] "e7d6d282426b2ee7"