Load and validate a .ferxsearch search configuration

Description

Reads a .ferxsearch file with the engine’s own loader and returns everything it validated, so a search space is checked before the first candidate is fitted rather than while watching fits fail. The loader is strict: an unknown section, an unparseable [space] mfl, an empty space, a feature the engine cannot express (a coverage gap), an unrecognised [rank] type or an invalid [rank.penalties] charge are all errors here, each naming the offender.

Usage

ferx_search_config(path)

# S3 method for ferx_search_config
print(x, ...)

Arguments

path: Path to a .ferxsearch file.
x: A ferx_search_config object.
...: Ignored.

Details

The file format (ferx-core’s search tooling) is TOML:

base = "../models/two_cpt_oral_cov.ferx"
data = "../data/two_cpt_oral_cov.csv"

[space]
mfl = "COVARIATE?(@IIV, @CONTINUOUS, [pow, lin])"

[rank]
type = "bic"

[strictness]
require_converged = true

[run]
threads = 4
retries = 2

base, data and [run] cache_dir are resolved relative to the configuration file’s own directory, so the file travels with its model. A tool section ([covsearch], [modelsearch], [globalsearch], [iivsearch], [iovsearch], [ruvsearch], [structsearch], [allometry]) is kept for the tool that owns it and reported in $tools; any other section name is an error, so a misspelt [strictnes] cannot silently leave the gate at its defaults. The engine accepts a section for every tool it knows, which is more than this package binds - [structsearch] today. A file carrying one loads cleanly and then has that section ignored by whichever R tool it is handed to, which is a search other than the one asked for. Loading such a file warns, here and in every tool that takes config =, naming the section and - where one exists - where it can be run instead. The check is the complement of the sections this package has a tool for, so a section a later ferx-core adds is reported until a binding for it exists here. [rank.penalties] (the schedule a [rank] type = "penalized"charges) comes back in $rank$penalties as the effectiveschedule: the file’s keys overlaid on the engine’s pyDarwin defaults, with $rank$penalties_set naming the charges the file changed. A file that restates a default is not distinguishable from one that omits it, since the two describe the same run.

[ferx_search_space](ferx_search_space.qmd) to expand the space against a model, [ferx_search_coverage](ferx_search_coverage.qmd) for the coverage table as data, and [ferx_search_results](ferx_search_results.qmd) to read a run’s candidate table. 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_coverage](ferx_search_coverage.qmd), [ferx_search_results](ferx_search_results.qmd), [ferx_search_space](ferx_search_space.qmd)

Concept

Value

An S3 object of class ferx_search_config: a list with path, dir, base, data (NULL when the file defers to the model’s [data] block), mfl (the space source, verbatim), space (a data frame with one row per feature: feature, keyword, optional), rank(type, cutoff, penalties - a named numeric of the effective [rank.penalties] schedule - and penalties_set, the charges the file changed), strictness (the effectivegate, the file’s keys overlaid on the engine’s defaults), strictness_set (the keys the file stated explicitly), run(threads, retries, cache_dir, resume) and tools (the tool sections the file carries).

Examples

cfg <- ferx_search_config(ferx_example("two_cpt_oral_cov")$search)
cfg$space
cfg$rank$type