add_covariate_effect#

pharmpy.modeling.add_covariate_effect(model, parameter, covariate, effect, operation='*', allow_nested=False)[source]#

Adds covariate effect to pharmpy.model.

The following effects have templates:

  • Linear function for continuous covariates (lin)

    • Function:

    \[\text{coveff} = 1 + \text{theta} * (\text{cov} - \text{median})\]

    • Init: 0.001

    • Upper:

      • If median of covariate equals minimum: 100,000

      • Otherwise: \(\frac{1}{\text{median} - \text{min}}\)

    • Lower:

      • If median of covariate equals maximum: -100,000

      • Otherwise: \(\frac{1}{\text{median} - \text{max}}\)

  • Linear function for categorical covariates (cat)
    • Function:

      • If covariate is the most common category:

      \[\text{coveff} = 1\]

      • For each additional category:

      \[\text{coveff} = 1 + \text{theta}\]

    • Init: 0.001

    • Upper: 5

    • Lower: -1

  • (alternative) Linear function for categorical covariates (cat2)
    • Function:

      • If covariate is the most common category:

      \[\text{coveff} = 1\]

      • For each additional category:

      \[\text{coveff} = \text{theta}\]

    • Init: 0.001

    • Upper: 6

    • Lower: 0

  • Piecewise linear function/”hockey-stick”, continuous covariates only (piece_lin)
    • Function:

      • If cov <= median:

      \[\text{coveff} = 1 + \text{theta1} * (\text{cov} - \text{median})\]

      • If cov > median:

      \[\text{coveff} = 1 + \text{theta2} * (\text{cov} - \text{median})\]

    • Init: 0.001

    • Upper:

      • For first state: \(\frac{1}{\text{median} - \text{min}}\)

      • Otherwise: 100,000

    • Lower:

      • For first state: -100,000

      • Otherwise: \(\frac{1}{\text{median} - \text{max}}\)

  • Exponential function, continuous covariates only (exp)

    • Function:

    \[\text{coveff} = \exp(\text{theta} * (\text{cov} - \text{median}))\]
    • Init:

      • If lower > 0.001 or upper < 0.001: \(\frac{\text{upper} - \text{lower}}{2}\)

      • If estimated init is 0: \(\frac{\text{upper}}{2}\)

      • Otherwise: 0.001

    • Upper:

      • If min - median = 0 or max - median = 0: 100

      • Otherwise:

      \[\min(\frac{\log(0.01)}{\text{min} - \text{median}}, \frac{\log(100)}{\text{max} - \text{median}})\]
    • Lower:

      • If min - median = 0 or max - median = 0: 0.01

      • Otherwise:

      \[\max(\frac{\log(0.01)}{\text{max} - \text{median}}, \frac{\log(100)}{\text{min} - \text{median}})\]
  • Power function, continuous covariates only (pow)

    • Function:

    \[\text{coveff} = (\frac{\text{cov}}{\text{median}})^\text{theta}\]

    • Init: 0.001

    • Upper: 100,000

    • Lower: -100

Parameters:

  • model (Model) – Pharmpy model to add covariate effect to.

  • parameter (str) – Name of parameter to add covariate effect to.

  • covariate (str) – Name of covariate.

  • effect (str) – Type of covariate effect. May be abbreviated covariate effect (see above) or custom.

  • operation (str, optional) – Whether the covariate effect should be added or multiplied (default).

  • allow_nested (bool, optional) – Whether to allow adding a covariate effect when one already exists for the input parameter-covariate pair.

Returns:

Model – Pharmpy model object

Examples

>>> from pharmpy.modeling import *
>>> model = load_example_model("pheno")
>>> model = add_covariate_effect(model, "CL", "APGR", "exp")
>>> model.statements.before_odes.full_expression("CL")
POP_CL*WGT*exp(ETA_CL + POP_CLAPGR*(APGR - 7.0))
On this page