Structural PK model search

Description

Runs a structural search - Pharmpy’s modelsearch - over a base model and a space of structural features: absorption, elimination, peripheral compartments, transit compartments and lag time. Every candidate is built by the engine’s own model editor, fitted, gated, and ranked on the criterion rank names (the mixed BIC unless the file says otherwise).

Usage

ferx_modelsearch(
  model = NULL,
  data = NULL,
  search_space = NULL,
  config = NULL,
  algorithm = NULL,
  iiv_strategy = NULL,
  rank = NULL,
  cutoff = NULL,
  threads = NULL,
  retries = NULL,
  directory = NULL,
  resume = FALSE,
  progress = interactive()
)

# S3 method for ferx_modelsearch
print(x, digits = 4, ...)

# S3 method for ferx_modelsearch
summary(object, digits = 4, ...)

Arguments

  • model: Path to a .ferx model, or a ferx_model object. Omit when config is given.
  • data: Path to the dataset. Defaults to the model’s [data] block. Names the dataset the search runs on, so like model it cannot be given beside config - the file’s own data key says which dataset that file searches.
  • search_space: MFL text naming the structural space, e.g. "ABSORPTION(FO); PERIPHERALS(0..1); LAGTIME([OFF,ON])".
  • config: Path to a .ferxsearch file. Mutually exclusive with the arguments that state the search.
  • algorithm: "reduced_stepwise" (the default), "exhaustive_stepwise" or "exhaustive". NULL keeps the engine default.
  • iiv_strategy: How a candidate’s new parameters are given a random effect: "absorption_delay" (the default - an eta on a new lag time or mean transit time only), "add_diagonal" (an eta on every new PK parameter) or "no_add". NULL keeps the engine default.
  • rank: [rank] type - the criterion candidates are ranked and gated on, e.g. "bic", "aic", "ofv". NULL keeps the tool default (the mixed BIC).
  • cutoff: [rank] cutoff: the improvement on the criterion a candidate must show over the base model to be selected. NULL selects the best model on the criterion alone.
  • threads: Total worker threads. NULL lets the runner choose.
  • retries: Perturbed restarts per candidate on top of the exact one. NULL keeps the engine default.
  • directory: Where the per-layer journals, models.csv, models/<id>.ferx and final.ferx are written. NULL keeps the run in memory, which also means it cannot be resumed.
  • resume: Reuse the fits already journalled in directory.
  • progress: Print the engine’s layer progress to the console.
  • x: A ferx_modelsearch object.
  • digits: Significant digits for the printed tables.
  • ...: Ignored.
  • object: A ferx_modelsearch object.

Details

The algorithm decides which candidates exist. "exhaustive" fits every combination of the space in one layer; "exhaustive_stepwise" adds one feature per layer to every model of the layer before it; "reduced_stepwise" - the default - extends only the best model of each feature-set group, which is what keeps a four-feature space to tens of fits rather than hundreds. As with [ferx_covsearch](ferx_covsearch.qmd), a candidate has to pass the strictness gate before it can be ranked, and the model table always carries the termination status and the gate verdict beside the criterion - a candidate that stalled at its initial estimates carries a criterion that says nothing about the structure it was testing.

Two entry forms

Pass either config - a .ferxsearch file, which is the reproducible artifact - or the inline arguments. The inline form is rendered into the same configuration and handed to the engine’s own loader, so the two cannot disagree; search_space is MFL text, quoted verbatim, which is also what makes a space portable to and from Pharmpy. The run arguments (threads, retries, resume, directory, progress) say how to run a search rather than what to search, and are available to both forms.

What the space may say

ABSORPTION, ELIMINATION, PERIPHERALS, TRANSITSand LAGTIME. A covariate or variability statement is another tool’s space and is refused by name before any fit starts, as is a feature the engine cannot build (ABSORPTION(SEQ-ZO-FO)). Check a space with [ferx_search_space](ferx_search_space.qmd) / [ferx_search_coverage](ferx_search_coverage.qmd) first: both answer without fitting anything.

Seealso

[ferx_search_space](ferx_search_space.qmd), [ferx_search_coverage](ferx_search_coverage.qmd), [ferx_covsearch](ferx_covsearch.qmd), [ferx_search_results](ferx_search_results.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_ruvsearch](ferx_ruvsearch.qmd), [ferx_search_config](ferx_search_config.qmd), [ferx_search_coverage](ferx_search_coverage.qmd), [ferx_search_results](ferx_search_results.qmd), [ferx_search_space](ferx_search_space.qmd)

Concept

search

Value

An object of class ferx_modelsearch:

  • models: The model table, one row per fitted model, in the engine’s own column order: id, parent, layer, path, absorption, peripherals, transits, lagtime, n_parameters, ofv, criterion, d_criterion, rank, converged, passed, failures, error, seconds, selected, continued, reused - followed by structure, the engine’s one-line rendering of the same four structural columns.
  • fit: The winning model’s fit as a ferx_fit, or NULL when a degraded resume could not recover it.
  • model_text: Every candidate’s model text, named by model id, so the model the table ranked second can be read or refitted without re-running the search. final_model_path is the final.ferx written beside the run.
  • input_model, base_model_id, base_structure: The model the search started from, and the root of the space it searched (they differ when the input lies off the space and had to be moved onto it).
  • base_ofv, base_criterion, final_ofv, final_criterion, final_model_id: The two objective function values, the two criterion values, and the id of the model that won.
  • criterion, algorithm, iiv_strategy, n_layers: What the search ranked on and how it searched.
  • candidates: The runner’s candidate table when the run wrote one - see [ferx_search_results](ferx_search_results.qmd).
  • notes, cancelled: What the search wants said once, and whether it was stopped early.

Examples

ex <- ferx_example("warfarin")

# Inline: no file to author for a one-off
res <- ferx_modelsearch(
  model        = ex$model,
  data         = ex$data,
  search_space = "ABSORPTION(FO); PERIPHERALS(0..1); LAGTIME([OFF,ON])",
  directory    = "modelsearch-run-1"
)
res
res$models[res$models$passed, c("id", "structure", "criterion", "rank")]
summary(res)

# Reproducible: the .ferxsearch file is the artifact
res2 <- ferx_modelsearch(config = ex$search, directory = "modelsearch-run-2")