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.ferxmodel file, or a[ferx_model](ferx_model.qmd)object.fit: A[ferx_fit](ferx_fit.qmd)result ofmodel: supplies the fitted weights and every other estimate. The fit must have been made with this model - the export comparesfit$model_textwithmodeland refuses a fit whose networks or equations differ (comments, layout,[parameters]values and the[data]path may differ). Givefitortheta, not both.output_model: Path the exported.ferxfile is written to. WhenNULL(default),<dir>/<stem>_expanded.ferxnext tomodel. For a[ferx_example](ferx_example.qmd)()model that directory is inside the installed package, so pass a writable path such asfile.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 astheta W_<NN>_<l>_<i>_<j>(value, lower, upper) FIXin[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.TRUEkeeps the valuesmodeldeclares 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 offit: a named numeric vector holding at least the network weights (W_<NN>_*/B_<NN>_*), for instance a savedfit$theta. Only the networks are rewritten and nothing is checked against a fit, as withnetwork_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)