Prepare a FREM (Full Random Effects Model) dataset and model

Description

Transforms a base model and dataset into a FREM model that treats covariates as additional dependent variables. The extended omega matrix captures covariate-parameter relationships implicitly, enabling covariate screening without stepwise search.

Usage

ferx_model_to_frem(
  model,
  data = NULL,
  covariates = NULL,
  output_dir = NULL,
  output_model = NULL,
  output_data = NULL,
  fit = NULL
)

Arguments

  • model: Path to a .ferx model file, or a [ferx_model](ferx_model.qmd) object. The model must declare its covariates in a [covariates] block, each tagged continuous or categorical.
  • data: Path to a NONMEM-format CSV file containing the covariate columns. Optional when model is a ferx_model that already carries a data path, or when the model file declares a [data] block (path = ...); passing data here overrides either.
  • covariates: Optional character vector used as a subset filter over the covariates declared in the model’s [covariates] block. When NULL (the default), all declared covariates are included. When supplied, only the named covariates are included - useful when you do not want every declared covariate in the FREM model. Each name must be declared in the block; an undeclared name is an error. This argument cannot introduce covariates the model has not declared, nor change their continuous/categorical kind.
  • output_dir: Directory for the output model and data files, created if it does not exist. Defaults to the directory containing model. For a [ferx_example](ferx_example.qmd)() model that directory is inside the installed package, so pass a writable directory such as file.path(tempdir(), "frem"). Read only for a file whose path is not given explicitly, so a call that supplies both output_model and output_data neither reads nor creates it.
  • output_model: Optional explicit path for the output .ferx model file, used instead of output_dir. When NULL (default), the file is written to <output_dir>/<stem>_frem.ferx, where <stem> is the model file name without its extension.
  • output_data: Optional explicit path for the output CSV data file, used instead of output_dir. When NULL (default), the file is written to <output_dir>/<stem>_frem_data.csv (the same <stem> as above, taken from the model file, not the data file). Both output paths are made absolute, so the returned [ferx_model](ferx_model.qmd) does not depend on the working directory the call was made from.
  • fit: Optional [ferx_fit](ferx_fit.qmd) result from fitting model (the base model, before FREM conversion). When supplied, its theta and omega estimates seed the generated FREM model’s PK theta inits and PK-PK omega block, so a subsequent fit of the FREM model warm-starts from converged parameters instead of model’s declared inits. Matching is by name (theta/eta names in fit); a name not found in model keeps its declared init. NULL (default) leaves every init at the value declared in model.

Details

The covariates folded into the FREM model - and whether each is continuous or categorical - come from the model’s [covariates] block, which is the single source of truth (and is required). The function:

  1. Reads the base model and dataset.
  2. Adds pseudo-observation rows for each covariate (one per subject), with DV set to the covariate value and a FREMTYPE column distinguishing covariate rows from PK observations.
  3. Generates a new .ferx model file with an extended omega block that covers both the original random effects and covariate random effects.
  4. Returns a ferx_model referencing the generated files.

After calling ferx_model_to_frem(), fit the returned model directly: [ferx_fit](ferx_fit.qmd)(frem).

Value

A [ferx_model](ferx_model.qmd) object pointing at the generated FREM model and dataset, so it composes directly with [ferx_fit](ferx_fit.qmd) and the other model helpers. The fixed covariate thetas, covariate omega initial values, and FREMTYPE mapping are written into the generated model and data files (and the fit’s omega is labelled by eta name), so no separate metadata object is returned.