Skip to contents

Read a run saved by precise_dist()

Source: R/precise_read.R
precise_read.Rd

Reads the RDS envelope written by the file= argument of precise_dist() and returns the run tibble with the ledger attached.

Usage

precise_read(file, metrics = NULL)

Arguments

file

Path to a file written by the file= argument of precise_dist().

metrics

NULL for every completed measure, or a character vector of display keys to keep, in the order you give them. Asking for a key that was requested but did not complete is an error naming its ledger status. Asking for a key that was never requested is an error listing what is available. The attached ledger always describes the whole run, whether or not you subset.

Value

A tibble with the columns distance, metric, matrix, type, and time_taken_seconds, with the run ledger attached as the "precise_dist_run" attribute. See precise_run_report(). A complete envelope reproduces the original result exactly, so it also carries the history column when the original call used coerce = "distance".

Details

An envelope in state complete returns the exact object the original call returned. An envelope in state partial, meaning the run was interrupted, crashed, or is still in flight, is reconstructed from the completed native matrices and a message reports how far the run got.

Envelope versions are handled as follows. A bare list or a version 2 envelope predates the enforced matrix-validity contract and is refused with a recomputation error, leaving readRDS() available for manual recovery. A version 3 envelope uses the former capitalized column names and is normalized to the current lowercase names in memory. The file on disk is never modified.

See also

precise_dist() to write the file, and precise_run_report() to read the ledger.

Author

Brian Muchmore

Examples

data(data_cell_cycle, package = "PreciseDist")

cells <- c(1:4, 60:63, 118:121)
cell_cycle <- as.matrix(data_cell_cycle[cells, 2:41])
rownames(cell_cycle) <- paste0(data_cell_cycle$Cell_cycle[cells], "_", cells)

cache <- tempfile(fileext = ".rds")
saved <- precise_dist(
  cell_cycle,
  dists = c("euclidean", "manhattan"),
  file = cache,
  verbose = FALSE
)

restored <- precise_read(cache)
identical(saved, restored)
#> [1] TRUE