Read a finished recovery grid from its cell files

What recovery_grid() returns, rebuilt from the files it left in dir, without fitting anything and without reading a fit. The per-cell sidecars hold everything that was scored, so a study can run on one machine and be assembled on another.

Usage

collect_grid(
  dir,
  scale = NULL,
  levels = NULL,
  correlations = NULL,
  prior_sd = NULL
)

Arguments

dir: The directory a recovery_grid() run wrote, holding grid.rds and the cell files. Written by bmmtools 0.2.0 or later; an earlier run left no grid.rds and cannot be collected.
scale: The scale to score on, as in recover(). NULL, the default, uses the scale the grid was run on. Giving it re-scores the stored rows, so a grid run on the link scale can be read again on the natural one without refitting.
levels, correlations: What to score, as in recovery_grid(). NULL uses what the grid requested. Either may be narrowed to a subset of what the cells hold; asking for something they do not hold is an error, because a level is extracted from a fit and the fits are not read here.
prior_sd: NULL, the default, uses the prior SDs the grid was scored with (<dir>/prior-sd.rds, written when recovery_grid() had a prior_sd), so the contraction is the grid's. Otherwise a source as recover() takes it — a table, a fit with sample_prior = "only", or a prior_check() — which replaces it.

Value

A bmmtools_recovery with the attributes recovery_grid() gives it, run_info included: one row per call that reached its cells in dir, so a grid run in slices by several processes says which process ran which cells. A directory written before bmmtools kept these records has no run_info. cells$elapsed is NA: no cell was run, so none took any time. cells$fit_seconds is the time each fit took when it was run, which is what a runtime table wants and what survives the trip between machines.

Details

This is a reader, not a resume. It checks neither the cache key nor the version of bmmtools that wrote the files, because on the machine that collects the results neither can match: the key covers the installed bmm, brms and Stan toolchain. A resume is what it has always been — rerunning the identical recovery_grid() call in the same directory — and it is the resume, not this function, that guarantees the files describe the call.

Cell files written before bmmtools stored the central 50 % interval are read with ci_low_50, ci_high_50 and covered_50 set to NA, so their coverage_50 is NA, and a message says how many there were. Rerunning the grid with the fits still in dir re-extracts them without refitting. Cell files written before it stored the posterior mean and SD are read with post_mean_link and post_sd_link set to NA, and a second message counts them.

Examples