Skip to main content

Export a fitted deep compartment model as a plain population PK model

Description

Writes a fitted DCM - a model with one or more [covariate_nn] blocks - out as an ordinary .ferx model: each network becomes its forward pass, spelled as plain equations at the top of [individual_parameters] at the fitted weights, and the block itself is removed. The exported model predicts exactly what the fitted network does, bit for bit, has no [covariate_nn] block, and loads in a ferx build without the nn cargo feature.

Usage

ferx_model_from_dcm(
  model,
  fit = NULL,
  output_model = NULL,
  weights = c("literal", "fixed_theta"),
  network_only = FALSE,
  theta = NULL
)

Arguments

  • model: Path to the DCM .ferx model file, or a [ferx_model](ferx_model.qmd) object.
  • fit: A [ferx_fit](ferx_fit.qmd) result of model: supplies the fitted weights and every other estimate. The fit must have been made with this model - the export compares fit$model_text with model and refuses a fit whose networks or equations differ (comments, layout, [parameters] values and the [data] path may differ). Give fit or theta, not both.
  • output_model: Path the exported .ferx file is written to. When NULL (default), <dir>/<stem>_expanded.ferx next to model. For a [ferx_example](ferx_example.qmd)() model that directory is inside the installed package, so pass a writable path such as file.path(tempdir(), "dcm_expanded.ferx"). An existing file is overwritten; the model file itself is refused.
  • weights: How the exported model carries the network weights: "literal" (default) inlines each weight as a numeric constant, so the exported network is frozen; "fixed_theta" declares each one as theta W_<NN>_<l>_<i>_<j>(value, lower, upper) FIX in [parameters], so the weights stay named and can be perturbed by hand. Either way the weights are not estimated: do not refit them.
  • network_only: Logical. FALSE (default) writes every other theta, omega, sigma and kappa at the fit’s estimate, so the export is the fitted model. TRUE keeps the values model declares and rewrites only the networks; needed for a model whose estimates cannot all be written back (a [mixture] per-class override, for one), which the default refuses.
  • theta: Instead of fit: a named numeric vector holding at least the network weights (W_<NN>_* / B_<NN>_*), for instance a saved fit$theta. Only the networks are rewritten and nothing is checked against a fit, as with network_only = TRUE.

Details

The transform is ferx-core’s nn::export (ferx-core #1331, also ferx export-dcm on the command line). It never evaluates a network, so it runs in every build, including one without nn. The exported equations are wrapped so that they are not mu-referenced; the model is meant for prediction and simulation at the fitted values, not for re-estimation.

Seealso

[ferx_model_to_frem](ferx_model_to_frem.qmd), the other model-to-model transform.

Value

A [ferx_model](ferx_model.qmd) pointing at the exported model file, so it composes with [ferx_predict](ferx_predict.qmd), [ferx_simulate](ferx_simulate.qmd)and the other model helpers. It carries model’s dataset. The exported file’s own [data] block is copied verbatim, so a relative path in it resolves from the exported file’s directory.

Examples

ex <- ferx_example("warfarin_dcm")
fit <- ferx_fit(ex$model, ex$data)
plain <- ferx_model_from_dcm(ex$model, fit,
                             output_model = file.path(tempdir(), "dcm.ferx"))
ferx_predict(plain$model, ex$data)