Stepwise covariate modelling (SCM)

Description

Runs a stepwise covariate search - PsN’s scm, Pharmpy’s covsearch - over a model and a candidate set of covariate effects. Each forward step fits every remaining effect on its own, keeps the largest OFV drop that is significant by the likelihood-ratio test, and repeats; the backward phase then removes the cheapest effect whose removal is not significant.

Usage

ferx_covsearch(
  model = NULL,
  data = NULL,
  search_space = NULL,
  config = NULL,
  algorithm = NULL,
  p_forward = NULL,
  p_backward = NULL,
  max_steps = NULL,
  adaptive_scope_reduction = NULL,
  rank = NULL,
  cutoff = NULL,
  threads = NULL,
  retries = NULL,
  directory = NULL,
  resume = FALSE,
  progress = interactive()
)

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

# S3 method for ferx_covsearch
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 candidate effects, e.g. "COVARIATE?(@IIV, @CONTINUOUS, [pow,lin])". A COVARIATE(...) statement without ? forces that effect into the base model before the search starts.
  • config: Path to a .ferxsearch file. Mutually exclusive with the arguments that state the search.
  • algorithm: "scm-forward-then-backward" or "scm-forward". NULL keeps the engine default.
  • p_forward, p_backward: Significance levels of the forward and backward tests (engine defaults 0.01 and 0.001).
  • max_steps: Cap on the number of steps; NULL for unlimited.
  • adaptive_scope_reduction: Stash effects that fail badly and retest them once at the end (SCM+). NULL keeps the engine default.
  • rank: [rank] type for the strictness / ranking criterion, e.g. "bic". NULL keeps the tool default (covsearch selects on the likelihood-ratio test).
  • cutoff: [rank] cutoff. NULL keeps the 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, steps.csv 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_covsearch object.
  • digits: Significant digits for the printed tables.
  • ...: Ignored.
  • object: A ferx_covsearch object.

Details

Every candidate is fitted with perturbed restarts (retries) and has to pass the strictness gate before it can win, because a candidate that stalled at its initial estimates carries an OFV that says nothing about the model. The step table therefore always shows the termination status and the gate verdict beside the OFV, and a candidate the gate excluded is a row with its reason rather than an absence.

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.

Seealso

[ferx_search_config](ferx_search_config.qmd), [ferx_search_space](ferx_search_space.qmd), [ferx_search_results](ferx_search_results.qmd), [ferx_allometry](ferx_allometry.qmd)Other search: [ferx_allometry](ferx_allometry.qmd), [ferx_amd](ferx_amd.qmd), [ferx_amd_plan](ferx_amd_plan.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_results](ferx_search_results.qmd), [ferx_search_space](ferx_search_space.qmd)

Concept

search

Value

An object of class ferx_covsearch:

  • steps: The step table, one row per candidate of every step, in the engine’s own column order: step, phase, candidate, parameter, covariate, form, parent_ofv, ofv, dofv, df, p_value, alpha, significant, selected, converged, passed, failures.
  • included: The final relation set: parameter, covariate, form and origin (the base model, a forced statement, or the forward step that added it).
  • fit: The final model’s fit as a ferx_fit, or NULL when a degraded resume could not recover it.
  • base_model, final_model: The model text the search started and ended on; final_model_path is the final.ferx written beside the run.
  • base_ofv, final_ofv, final_step: The two objective function values and the step that produced the winner (0 is the base model).
  • 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("two_cpt_oral_cov")

# Inline: no file to author for a one-off
res <- ferx_covsearch(
  model        = ex$model,
  data         = ex$data,
  search_space = "COVARIATE?(@IIV, @CONTINUOUS, [pow,lin])",
  p_forward    = 0.01,
  p_backward   = 0.001,
  directory    = "covsearch-run-1"
)
res
res$steps[res$steps$selected, ]
summary(res)

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