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_to_frem(
  model,
  data = NULL,
  covariates = NULL,
  output_dir = NULL,
  output_model = NULL,
  output_data = 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.
  • 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. Defaults to the directory containing model.
  • output_model: Optional explicit path for the output .ferx model file. When NULL (default), the file is written to <output_dir>/<stem>_frem.ferx.
  • output_data: Optional explicit path for the output CSV data file. When NULL (default), the file is written to <output_dir>/<stem>_frem_data.csv.

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