Variability-structure search

Description

Runs a variability-structure search - Pharmpy’s iivsearch - over a base model: which parameters carry an eta, and which of those etas are correlated. Every candidate is built by the engine’s own model editor, fitted, gated, and ranked on the criterion rank names (the BIC(iiv) unless the file says otherwise).

Usage

ferx_iivsearch(
  model = NULL,
  data = NULL,
  search_space = NULL,
  config = NULL,
  algorithm = NULL,
  correlation_algorithm = NULL,
  as_fullblock = NULL,
  block_retries = NULL,
  rank = NULL,
  cutoff = NULL,
  threads = NULL,
  retries = NULL,
  directory = NULL,
  resume = FALSE,
  progress = interactive()
)

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

# S3 method for ferx_iivsearch
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 variability space, e.g. "IIV?(@PK, exp); COVARIANCE?(IIV, *)".
config: Path to a .ferxsearch file. Mutually exclusive with the arguments that state the search.
algorithm: "top_down_exhaustive" (the default), "bottom_up_stepwise", "simultaneous_stepwise" or "skip" (no eta-count stage; the block stage alone). NULL keeps the engine default.
correlation_algorithm: "top_down_exhaustive" or "skip". NULL keeps the engine’s derivation: the block stage runs after any algorithm but "simultaneous_stepwise".
as_fullblock: Pharmpy’s as_fullblock: a bottom-up candidate blocks every eta it carries rather than adding the new one diagonally. NULL keeps the engine default (FALSE).
block_retries: Extra starts per eta beyond two in a candidate’s largest block, on top of the run’s starts. NULL keeps the engine default (2).
rank: [rank] type - the criterion candidates are ranked and gated on. NULL keeps the tool default, the BIC(iiv), which is what "bic" means for this tool.
cutoff: [rank] cutoff: the improvement on the criterion a candidate must show over its step’s parent to replace it. NULL takes any improvement, which is Pharmpy’s default.
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-step 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 step progress to the console.
x: A ferx_iivsearch object.
digits: Significant digits for the printed tables.
...: Ignored.
object: A ferx_iivsearch object.

Two stages, not one table

An iivsearch is two searches in sequence. The first decides the number of etas (step_kind = "no_of_etas"); the second, taking the winner of the first as its parent, decides the block structureover them (step_kind = "block_structure"); a last comparison puts the winner beside the input model ("compare_to_input"). Every row of $models carries the stage it was fitted in, and $steps is the engine’s own per-stage ranking, so a search that added an eta and then blocked two of them reads as the two decisions it was. algorithm = "simultaneous_stepwise" is the exception: it decides the block structure as it adds each eta, so it has no second stage and refuses correlation_algorithm. A candidate whose largest block has more than two etas is fitted from more starting points than a diagonal one (block_retries per eta beyond two, on top of retries + 1), because a block covariance is the part of an omega most likely to land in a local optimum. The starts each candidate actually got are on its row.

Labels

The engine’s own description column is written in parameternames ([CL,V]+[KA]), which is Pharmpy’s spelling and what models.csv carries. The structure, eta_labels and block_labels columns beside it are the same structure in the model’s declared random-effect names ([ETA_CL,ETA_V]+[ETA_KA]), read off each candidate’s own text - so a model that calls its eta something other than ETA_<P> is labelled as it is written. An eta the model does not name falls back to OMEGA(i,i), per the output label convention.

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. 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

IIV and COVARIANCE statements only. Both take two arguments: IIV?(@PK, exp) makes every PK parameter’s eta exploratory, IIV(CL, exp) keeps CL’s whatever the search decides, COVARIANCE?(IIV, [CL, V]) offers the two as a block and COVARIANCE(IIV, [CL, V]) forces it. Only the exponential form is searchable, since it is the one the eta edits can reverse. A structural or covariate statement is another tool’s space and is refused by name before any fit starts.

[ferx_iovsearch](ferx_iovsearch.qmd), [ferx_modelsearch](ferx_modelsearch.qmd), [ferx_search_space](ferx_search_space.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_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_results](ferx_search_results.qmd), [ferx_search_space](ferx_search_space.qmd)

Concept

Value

An object of class ferx_iivsearch:

models: The model table, one row per fitted model, in the engine’s own column order: id, parent, step, description, etas, blocks, n_parameters, ofv, criterion, d_criterion, rank, converged, passed, failures, error, starts, seconds, selected - followed by step_kind (the stage the row belongs to), eta_labels, block_labels and structure (the same structure in the model’s declared eta names).
steps: The engine’s per-stage ranking, one row per model ranked in a step: step, kind, parent, id, criterion, d_criterion (positive is better), rank, best.
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 a structure the search rejected can be read or refitted without re-running it. final_model_path is the final.ferx written beside the run.
input_model, input_structure, input_description: The model the search started from, and its structure in declared eta names and in the engine’s parameter names.
base_model_id, base_ofv, base_criterion: The root of the search: "input", or "base" when one had to be derived.
final_model_id, final_structure, final_description, final_etas, final_blocks, final_ofv, final_criterion: The winning model, its structure, the etas it carries and the blocks over them.
criterion, algorithm, correlation_algorithm, block_stage, n_steps: What the search ranked on and how it searched.
options: The search as the engine read it: algorithm, correlation_algorithm, as_fullblock, block_retries, starts and cutoff.
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("one_cpt_iv")

# Inline: no file to author for a one-off
res <- ferx_iivsearch(
  model        = ex$model,
  data         = ex$data,
  search_space = "IIV?(@PK, exp); COVARIANCE?(IIV, *)",
  directory    = "iivsearch-run-1"
)
res
res$models[, c("id", "step_kind", "structure", "criterion", "rank")]
res$steps
summary(res)

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