Stepwise covariate modeling (SCM) search

Runs forward inclusion and optional backward elimination of parameter–covariate relationships, selecting terms by likelihood-ratio tests against p_forward and p_backward.

Usage

sg_covsearch(
  gfo,
  gco,
  output_dir = NULL,
  covariates = NULL,
  parameters = NULL,
  test_pairs = NULL,
  p_forward = 0.05,
  p_backward = 0.01,
  fit_function = sg_fit,
  update_theta_init = FALSE,
  run_backward = TRUE,
  update_theta_init_backward = FALSE,
  path_to_fitter = NULL
)

Arguments

gfo

GFO or character. Baseline fit object, or path to a GFO .json/.RData, containing at least COTAB and CATAB.

gco

GCO or character. Control object (list), or path to a GCO .json/.RData, containing at least headers and theta.

output_dir

Character. Directory where fit projects and search history files are written. Default value is tempdir().

covariates

Character vector or NULL. Covariate names to consider. When NULL, all covariates from gco$headers are used. Default value is NULL.

parameters

Character vector or NULL. Parameter names to consider. When NULL, all parameters from gco$theta are used. Default value is NULL.

test_pairs

Data.frame or NULL. Candidate pairs with columns parameter, covariate, type, reference, and center. When NULL, all parameter–covariate combinations are generated. Default value is NULL.

p_forward

Numeric in (0,1). Significance level for forward inclusion. Default value is 0.05.

p_backward

Numeric in (0,1). Significance level for backward elimination. Default value is 0.01.

fit_function

Function. Fitting function that returns a fit-like object consumable by get_ofv. Default value is sg_fit.

update_theta_init

Logical. If TRUE, refreshes theta INIT values from accepted forward fits only (never from rejected candidates). Default value is FALSE.

run_backward

Logical. If TRUE, runs Stage 4 backward elimination after forward inclusion converges. Default value is TRUE.

update_theta_init_backward

Logical. If TRUE, refreshes theta INIT only after accepted backward removals. Default value is FALSE.

path_to_fitter

Character or NULL. Path to the fitter executable. When NULL, gco$path_to_fitter is used if present. Default value is NULL.

Value

A list with final_gco, final_covariates, forward/backward summaries, runtime settings, and execution metadata.

Examples

model_path <- tempfile(fileext = ".txt")
data_path <- tempfile(fileext = ".csv")
writeLines(c("[LONGITUDINAL]", "input = {CL, V}", "PK:"), model_path)
writeLines(c("ID,TIME,DV,WT", "1,0,0,70", "2,0,0,80"), data_path)

gco <- list(
  model = model_path,
  data = data_path,
  headers = list(
    list(name = "ID", use = "identifier", type = NULL),
    list(name = "TIME", use = "time", type = NULL),
    list(name = "DV", use = "observation", type = "continuous"),
    list(name = "WT", use = "covariate", type = "continuous")
  ),
  theta = data.frame(
    NAME = c("CL", "V"),
    TRANS = c("logNormal", "logNormal"),
    INIT = c(0.2, 20),
    EST = c(TRUE, TRUE),
    stringsAsFactors = FALSE
  ),
  ruv = list(dummy = TRUE),
  re = list(dummy = TRUE),
  occ = list(dummy = TRUE),
  covs = list(),
  project_name = "base_model"
)

gfo <- list(
  OFV = data.frame(LL = 100),
  SUMTAB = data.frame(PAR = character(0), VALUE = numeric(0), stringsAsFactors = FALSE),
  COTAB = data.frame(ID = 1:4, WT = c(70, 80, 90, 75), stringsAsFactors = FALSE),
  CATAB = data.frame(ID = 1:4, stringsAsFactors = FALSE)
)

mock_fit <- function(model, data, headers, theta, ruv, re, occ, covs, project_name,
                     task_opt = NULL, opt_name = "Monolix", fit = TRUE,
                     path_to_save_output = NULL, path_to_fitter = NULL) {
  ofv <- if (grepl("_001$", project_name)) 95 else 99
  list(
    GFO = list(
      OFV = data.frame(LL = ofv),
      SUMTAB = data.frame(PAR = character(0), VALUE = numeric(0), stringsAsFactors = FALSE),
      COTAB = data.frame(dummy = 1),
      CATAB = data.frame(dummy = 1)
    )
  )
}

result <- sg_covsearch(
  gfo = gfo,
  gco = gco,
  output_dir = tempfile("covsearch-example-"),
  covariates = "WT",
  parameters = "CL",
  run_backward = FALSE,
  fit_function = mock_fit
)

result$forward$selected[, c("parameter", "covariate")]
#>   parameter covariate
#> 1        CL        WT