Allometric scaling

Description

Adds allometric body-size scaling to a model: (WT/70)^0.75 on every clearance the pk template line binds (cl, q, q2, q3) and (WT/70)^1.0 on every volume (v, v1, v2, v3), written as [covariate_model] relations. This is Pharmpy’s allometry tool, and it is a convention rather than new machinery - the same thing you would write by hand as power(center = 70, fix = 0.75).

Usage

ferx_allometry(
  model = NULL,
  data = NULL,
  config = NULL,
  covariate = NULL,
  reference = NULL,
  parameters = NULL,
  exponents = NULL,
  estimate = FALSE,
  lower = NULL,
  upper = NULL,
  fit = TRUE,
  threads = NULL,
  retries = NULL,
  directory = NULL
)

# S3 method for ferx_allometry
print(x, digits = 4, ...)

Arguments

model: Path to a .ferx model, or a ferx_model object. Omit when config is given.
data: Path to the dataset. Defaults to the model’s [data] block. Names the dataset the search runs on, so like model it cannot be given beside config - the file’s own data key says which dataset that file searches.
config: Path to a .ferxsearch file carrying an ALLOMETRY(WT, 70) statement and an optional [allometry] section. Mutually exclusive with the arguments that state the scaling.
covariate: The size covariate (engine default "WT").
reference: The reference value it is divided by (engine default 70).
parameters: Parameters to scale. NULL takes every clearance and volume the template line binds.
exponents: One exponent per parameters entry. NULL uses the convention: 0.75 for a clearance, 1.0 for a volume.
estimate: Estimate the exponents from those values instead of fixing them, bounded by lower and upper.
lower, upper: Bounds of an estimated exponent (engine defaults 0 and 2).
fit: Fit the base and scaled models, or only build the scaled one.
threads: Total worker threads. NULL lets the runner choose.
retries: Perturbed restarts per fit on top of the exact one. NULL keeps the engine default.
directory: Where the two fits are journalled. NULL keeps them in memory.
x: A ferx_allometry object.
digits: Significant digits for the printed tables.
...: Ignored.

Details

With fit = FALSE this is a model transform: you get the scaled model text back and nothing is fitted, so allometry can be one step of a hand-built workflow. With fit = TRUE (the default) the base and the scaled model are fitted side by side and both outcomes are returned, which is what makes the scaling’s cost visible. A parameter that already carries a relation on the size covariate is left alone, as Pharmpy does, with a note saying so.

[ferx_covsearch](ferx_covsearch.qmd), [ferx_search_config](ferx_search_config.qmd)Other search: [ferx_amd](ferx_amd.qmd), [ferx_amd_plan](ferx_amd_plan.qmd), [ferx_covsearch](ferx_covsearch.qmd), [ferx_globalsearch](ferx_globalsearch.qmd), [ferx_iivsearch](ferx_iivsearch.qmd), [ferx_iovsearch](ferx_iovsearch.qmd), [ferx_modelsearch](ferx_modelsearch.qmd), [ferx_ruvsearch](ferx_ruvsearch.qmd), [ferx_search_config](ferx_search_config.qmd), [ferx_search_coverage](ferx_search_coverage.qmd), [ferx_search_results](ferx_search_results.qmd), [ferx_search_space](ferx_search_space.qmd)

Concept

Value

An object of class ferx_allometry:

scalings: One row per scaled parameter: parameter, exponent, fixed and the theta an estimated exponent declares.
model, model_path: The scaled model as text, and as a file.
covariate, reference: The scaling the relations were built on.
comparison: With fit = TRUE: the two fits side by side - model ("base" / "scaled"), ofv, converged, passed and failures.
fit, base_fit: With fit = TRUE: the scaled and base fits as ferx_fit objects.
dofv: OFV(base) - OFV(scaled), when both fits exist.
notes, cancelled: Parameters left alone and why, and whether the run was stopped early.

Examples

ex <- ferx_example("warfarin")

# The transform on its own: the scaled model, nothing fitted
scaled <- ferx_allometry(ex$model, ex$data, fit = FALSE)
cat(scaled$model)

# The tool: both fits, side by side
res <- ferx_allometry(ex$model, ex$data, covariate = "WT", reference = 70)
res
res$comparison