Read a search run’s table

Description

Reads a table a search run writes into its directory - the runner’s candidates.csv by default, a structural search’s models.csvwith type = "models", or a stepwise search’s steps.csv with type = "steps" - and returns it typed. The column list comes from the engine for every table, never a copy maintained here, so the R data frame and the file on disk are the same table.

Usage

ferx_search_results(
  directory,
  partial = NULL,
  type = c("candidates", "models", "steps")
)

Arguments

directory: Path to the run directory, or directly to the candidates.csv / candidates.partial.csv / models.csv / steps.csv file itself.
partial: Which table to read: NULL (the default) prefers the complete table and falls back to the partial one, TRUE demands the partial table, FALSE demands the complete one. When directory names a file directly, a value that disagrees with the file named is an error rather than an ignored argument.
type: Which table to read: "candidates" (the default) for the runner’s own candidate table, written by every tool, "models" for the model table [ferx_modelsearch](ferx_modelsearch.qmd), [ferx_iivsearch](ferx_iivsearch.qmd), [ferx_iovsearch](ferx_iovsearch.qmd) and [ferx_globalsearch](ferx_globalsearch.qmd) write, or "steps" for the step table [ferx_covsearch](ferx_covsearch.qmd) and [ferx_ruvsearch](ferx_ruvsearch.qmd) write. A run has more than one: the candidate table is one row per fit the runner was asked for, the model or step table one row per model the search itself decided on. Several tools write a file called models.csv, and both stepwise tools one called steps.csv; which schema a file carries is read off its own header, and reported as the tool attribute.

Details

The candidate table is one row per candidate the run was given and in the order it was given them, including the ones that failed. A candidate the strictness gate excluded carries why in failures rather than being absent, because a candidate missing from a report cannot be told apart from one that was never generated. A cancelled run writes candidates.partial.csv instead, leaving any complete table beside it untouched; this function reads the complete table when there is one and falls back to the partial table otherwise. The column list comes from the engine (never a copy maintained here), so a column the engine adds shows up as a column here. The engine writes an empty cell for “there is no value” - a candidate that never fitted has no OFV, a row that succeeded has nothing to say about whether a resume would retry it. Those cells come back as NA, not NaN and not "".

[ferx_search_config](ferx_search_config.qmd), [check_strictness](check_strictness.qmd)Other search: [ferx_allometry](ferx_allometry.qmd), [ferx_amd](ferx_amd.qmd), [ferx_amd_plan](ferx_amd_plan.qmd), [ferx_covsearch](ferx_covsearch.qmd), [ferx_globalsearch](ferx_globalsearch.qmd), [ferx_iivsearch](ferx_iivsearch.qmd), [ferx_iovsearch](ferx_iovsearch.qmd), [ferx_modelsearch](ferx_modelsearch.qmd), [ferx_ruvsearch](ferx_ruvsearch.qmd), [ferx_search_config](ferx_search_config.qmd), [ferx_search_coverage](ferx_search_coverage.qmd), [ferx_search_space](ferx_search_space.qmd)

Concept

Value

For type = "steps", a data frame with the engine’s 17 step columns for whichever stepwise tool wrote the file - covsearch’s (step, phase, candidate, parameter, covariate, form, …) or ruvsearch’s (iteration, candidate, feature, screened, …) - typed the same way, and carrying a tool attribute naming the one it matched. For type = "models", a data frame with the engine’s model-table columns for whichever tool wrote the file - modelsearch’s 21 (id, parent, layer, path, the four structural columns, criterion, rank, …), iivsearch’s 18 (id, parent, step, description, etas, blocks, …), iovsearch’s 19 (…, kappas, kappa_blocks, …) or globalsearch’s 24 (…, genome, covariates, fitness, non_influential, duplicate_of, …) - typed the same way and carrying the same tool attribute. Otherwise a data frame with the engine’s 15 candidate columns: id, parent, hash, features, criterion (numeric), ofv (numeric), converged (logical), passed(logical), failures, skipped, seconds (numeric), error, retryable (logical), duplicate_of and reused (logical). Carries attributes path (the file read) and partial (whether it is a cancelled run’s table).

Examples

res <- ferx_search_results("search-run-1")
res[res$passed, c("id", "features", "criterion")]
# Candidates the gate excluded, and why
res[!res$passed, c("id", "failures")]