Inter-occasion variability search

Description

Runs an inter-occasion variability search - Pharmpy’s iovsearch - over a base model: which parameters carry a kappa, and whether the etas those kappas sit beside are still worth keeping. Every candidate is built by the engine’s own model editor, fitted, gated, and ranked on the criterion rank names (the BIC(random) unless the file says otherwise).

Usage

ferx_iovsearch(
  model = NULL,
  data = NULL,
  search_space = NULL,
  config = NULL,
  column = NULL,
  distribution = NULL,
  groups = NULL,
  block_retries = NULL,
  rank = NULL,
  cutoff = NULL,
  threads = NULL,
  retries = NULL,
  directory = NULL,
  resume = FALSE,
  progress = interactive()
)

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

# S3 method for ferx_iovsearch
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 parameters to try a kappa on, e.g. "IOV?(*, exp)" - the statement takes parameters and an effect, and only the exponential form is searchable. NULL takes Pharmpy’s default: every parameter carrying a free eta.
  • config: Path to a .ferxsearch file. Mutually exclusive with the arguments that state the search.
  • column: The occasion column. NULL takes the base model’s iov_column; a value that disagrees with it is an error rather than a silent override.
  • distribution: How the added kappas are declared: "same-as-iiv" (the default - kappas blocked as their etas are), "disjoint" (one kappa line each), "joint" (one block_kappa over all of them) or "explicit" (the blocks groups names). NULL keeps the engine default.
  • groups: The kappa blocks for distribution = "explicit", as a list of character vectors of parameter names, e.g. list(c("CL", "V"), "KA").
  • block_retries: Extra starts per kappa beyond two in a candidate’s largest block_kappa, 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(random), 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_iovsearch object.
  • digits: Significant digits for the printed tables.
  • ...: Ignored.
  • object: A ferx_iovsearch object.

Two stages, not one table

An iovsearch is two searches in sequence. The full-IOV model - a kappa on every candidate parameter - is fitted first; step 1 then removes kappas from it, and step 2, taking step 1’s winner as its parent, removes the etas of the parameters that kept a kappa. Every row of $models carries the step it was fitted in, and $steps is the engine’s own per-step ranking.

What the base model needs

The occasions are read by the engine from the base model’s iov_column ([fit_options] iov_column = OCC). A base without one is refused by name: the dataset’s occasions were never read, so no candidate could be fitted. The base needs no kappa of its own - the search adds them - and the column must carry at least two occasion values.

Labels

The engine’s own description column is written in parameternames (IIV([CL]+[V]);IOV([CL])), which is Pharmpy’s spelling and what models.csv carries. The structure, eta_labels, kappa_labels and kappa_block_labels columns beside it are the same structure in the model’s declared random-effect names (IIV([ETA_CL]+[ETA_V]);IOV([KAPPA_CL])), read off each candidate’s own text. A random effect the model does not name falls back to OMEGA(i,i) / KAPPA<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.

Seealso

[ferx_iivsearch](ferx_iivsearch.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_iivsearch](ferx_iivsearch.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

search

Value

An object of class ferx_iovsearch:

  • models: The model table, one row per fitted model, in the engine’s own column order: id, parent, step, description, etas, kappas, kappa_blocks, n_parameters, ofv, criterion, d_criterion, rank, converged, passed, failures, error, starts, seconds, selected - followed by step_kind, eta_labels, kappa_labels, kappa_block_labels and structure (the same structure in the model’s declared random effect names).
  • steps: The engine’s per-step 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, input_ofv, input_criterion: The model the search started from, as fitted.
  • final_model_id, final_structure, final_description, final_etas, final_kappas, final_kappa_blocks, final_criterion: The winning model, the random effects it carries and the blocks over the kappas.
  • criterion, distribution, column, n_steps: What the search ranked on, how the kappas were declared and which column carried the occasions.
  • options: The search as the engine read it: distribution, column, groups, 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("warfarin_iov")

# Inline: no file to author for a one-off
res <- ferx_iovsearch(
  model     = ex$model,
  data      = ex$data,
  directory = "iovsearch-run-1"
)
res
res$models[, c("id", "step", "structure", "criterion", "rank")]
summary(res)

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