pharmpy.modeling package

Submodules

• pharmpy.modeling.data module
• pharmpy.modeling.evaluation module
• pharmpy.modeling.help_functions module
• pharmpy.modeling.results module
• pharmpy.modeling.run module

Module contents

pharmpy.modeling.add_covariate_effect(model, parameter, covariate, effect, operation='*')

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 most common category:

    \[\text{coveff} = 1\]

    • For each additional category:

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

  • Init: \(0.001\)

  • Upper: \(100,000\)

  • Lower: \(-100,000\)

• 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).

pharmpy.modeling.add_estimation_step(model, method, interaction=True, options=None, idx=None)

Add estimation step

Adds estimation step for a model in a given index. Methods currently supported are:

FO, FOCE, ITS, LAPLACE, IMPMAP, IMP, SAEM

Parameters

• model (Model) – Pharmpy model

• method (str) – estimation method to change to

• interaction (bool) – whether to use interaction or not, default is true

• options (dict) – any additional options. Note that this removes old options

• idx (int) – index of estimation step, default is None (adds step last)

Returns

model (Model)

pharmpy.modeling.add_iiv(model, list_of_parameters, expression, operation='*', eta_names=None)

Adds IIVs to pharmpy.model. Effects that currently have templates are:

• Additive (add)

• Proportional (prop)

• Exponential (exp)

• Logit (logit)

For all except exponential the operation input is not needed. Otherwise user specified input is supported. Initial estimates for new etas are 0.09.

Parameters

• model (Model) – Pharmpy model to add new IIVs to.

• list_of_parameters (str, list) – Name/names of parameter to add new IIVs to.

• expression (str, list) – Effect/effects on eta. Either abbreviated (see above) or custom.

• operation (str, list, optional) – Whether the new IIV should be added or multiplied (default).

• eta_names (str, list, optional) – Custom name/names of new eta

pharmpy.modeling.add_individual_parameter(model, name)

Add an individual or pk parameter to a model

pharmpy.modeling.add_iov(model, occ, list_of_parameters=None, eta_names=None)

Adds IOVs to pharmpy.model. Initial estimate of new IOVs are 10% of the IIV eta it is based on.

Parameters

• model (Model) – Pharmpy model to add new IOVs to.

• occ (str) – Name of occasion column.

• list_of_parameters (str, list) – List of names of parameters and random variables. Accepts random variable names, parameter names, or a mix of both.

• eta_names (str, list) – Custom names of new etas. Must be equal to the number of input etas times the number of categories for occasion.

pharmpy.modeling.add_peripheral_compartment(model)

Add a peripheral distribution compartment to model

The rate of flow from the central to the peripheral compartment will be parameterized as QPn / VC where VC is the volume of the central compartment. The rate of flow from the peripheral to the central compartment will be parameterized as QPn / VPn where VPn is the volumne of the added peripheral compartment.

Initial estimates:

n
1	\(\mathsf{CL} = \mathsf{CL'}\), \(\mathsf{VC} = \mathsf{VC'}\), \(\mathsf{QP1} = \mathsf{CL'}\) and \(\mathsf{VP1} = \mathsf{VC'} \cdot 0.05\)
2	\(\mathsf{QP1} = \mathsf{QP1' / 2}\), \(\mathsf{VP1} = \mathsf{VP1'}\), \(\mathsf{QP2} = \mathsf{QP1' / 2}\) and \(\mathsf{VP2} = \mathsf{VP1'}\)

pharmpy.modeling.calculate_individual_parameter_statistics(model, exprs, seed=None)

Calculate statistics for individual parameters

Calculate the mean (expected value of the distribution), variance (variance of the distribution) and standard error for individual parameters described by arbitrary expressions. Any dataset column or variable used in the model can be used in the expression. The exception being that variables that depends on the solution of the ODE system cannot be used. If covariates are used in the expression the statistics of the parameter is calculated at the median value of each covariate as well as at the 5:th and 95:th percentiles.

Parameters

• model (Model) – A previously estimated model

• exprs (str, sympy expression or iterable of str or sympy expressions) – Expressions or equations for parameters of interest. If equations are used the names of the left hand sides will be used as the names of the parameters.

• seed (int or numpy rng)

Returns

pd.DataFrame – A DataFrame of statistics indexed on parameter and covariate value.

pharmpy.modeling.calculate_individual_shrinkage(model)

Calculate the individual eta-shrinkage

Definition: ieta_shr = (var(eta) / omega)

pharmpy.modeling.calculate_pk_parameters_statistics(model, seed=None)

Calculate statistics for common pharmacokinetic parameters

Calculate the mean (expected value of the distribution), variance (variance of the distribution) and standard error for some individual pre-defined pharmacokinetic parameters.

Parameters

• model (Model) – A previously estimated model

• seed (int or numpy rng)

Returns

pd.DataFrame – A DataFrame of statistics indexed on parameter and covariate value.

See also

calculate_individual_parameter_statistics

Calculation of statistics for arbitrary parameters

pharmpy.modeling.convert_model(model, to_format)

Convert model to other format

Parameters

• model (Model) – Model to convert

• to_format (str) – Name of format to convert into. Currently supported ‘nlmixr’

• Results

• ——-

• Model – New model object with new underlying model format.

pharmpy.modeling.copy_model(model)

Copies model to a new model object

pharmpy.modeling.create_joint_distribution(model, rvs=None)

Combines some or all etas into a joint distribution.

The etas must be IIVs and cannot be fixed. Initial estimates for covariance between the etas is dependent on whether the model has results from a previous results. In that case, the correlation will be calculated from individual estimates, otherwise correlation will be set to 10%.

Parameters

• model (Model) – Pharmpy model

• rvs (list) – Sequence of etas or names of etas to combine. If None, all etas that are IIVs and non-fixed will be used (full block). None is default.

pharmpy.modeling.create_results(path, **kwargs)

pharmpy.modeling.evaluate_expression(model, expression)

Evaluate expression using model

Calculate the value of expression for each data record. The expression can contain dataset columns, variables in model and population parameters. If the model has parameter estimates these will be used. Initial estimates will be used for non-estimated parameters.

Parameters

expression (str or sympy expression) – Expression to evaluate

Returns

pd.Series – A series of one evaluated value for each data record

pharmpy.modeling.explicit_odes(model)

Convert model from compartmental system to explicit ODE system or do nothing if it already has an explicit ODE system

pharmpy.modeling.fit(models)

pharmpy.modeling.fix_parameters(model, parameter_names)

Fix parameters

Fix all listed parameters

Parameters

• model (Model) – Pharmpy model

• parameter_names (list or str) – one parameter name or a list of parameter names

Returns

model (Model)

pharmpy.modeling.fix_parameters_to(model, parameter_names, values)

Fix parameters to

Fix all listed parameters to specified value/values

Parameters

• model (Model) – Pharmpy model

• parameter_names (list or str) – one parameter name or a list of parameter names

• values (list or int) – one value or a list of values (must be equal to number of parameter_names)

Returns

model (Model)

pharmpy.modeling.get_number_of_individuals(model)

Retrieve the number of individuals in the model dataset

pharmpy.modeling.get_number_of_observations(model)

Retrieve the total number of observations in the model dataset

pharmpy.modeling.get_number_of_observations_per_individual(model)

Number of observations for each individual

pharmpy.modeling.has_additive_error_model(model)

Check if a model has an additive error model

Parameters

model (Model) – The model to check

pharmpy.modeling.has_combined_error_model(model)

Check if a model has a combined additive and proportinal error model

Parameters

model (Model) – The model to check

pharmpy.modeling.has_proportional_error_model(model)

Check if a model has a proportional error model

Parameters

model (Model) – The model to check

pharmpy.modeling.has_zero_order_absorption(model)

Check if ode system describes a zero order absorption

currently defined as having Infusion dose with rate not in dataset

pharmpy.modeling.read_model(path)

Read model from file

pharmpy.modeling.read_model_from_string(code)

Read model directly from the model code in a string

pharmpy.modeling.read_results(path)

pharmpy.modeling.remove_error_model(model)

Remove error model.

Parameters

model (Model) – Remove error model for this model

pharmpy.modeling.remove_estimation_step(model, idx)

Remove estimation step

Parameters

• model (Model) – Pharmpy model

• idx (int) – index of estimation step to remove

Returns

model (Model)

pharmpy.modeling.remove_iiv(model, to_remove=None)

Removes all IIV omegas given a list with eta names and/or parameter names.

Parameters

• model (Model) – Pharmpy model to create block effect on.

• to_remove (str, list) – Name/names of etas and/or name/names of individual parameters to remove. If None, all etas that are IIVs will be removed. None is default.

pharmpy.modeling.remove_iov(model)

Removes all IOV omegas.

Parameters

model (Model) – Pharmpy model to remove IOV from.

pharmpy.modeling.remove_lag_time(model)

Remove lag time from the dose compartment of model.

pharmpy.modeling.remove_peripheral_compartment(model)

Remove a peripheral distribution compartment from model

Initial estimates:

n
2	\(\mathsf{CL} = \mathsf{CL'}\), \(\mathsf{QP1} = \mathsf{CL'}\) and \(\mathsf{VP1} = \mathsf{VC'} \cdot 0.05\)
3	\(\mathsf{QP1} = (\mathsf{QP1'} + \mathsf{QP2'}) / 2\), \(\mathsf{VP1} = \mathsf{VP1'} + \mathsf{VP2'}\)

pharmpy.modeling.set_additive_error_model(model, data_trans=None)

Set an additive error model. Initial estimate for new sigma is \((min(DV)/2)²\).

The error function being applied depends on the data transformation.

Data transformation	Additive error
\(y\)	\(f + \epsilon_1\)
\(log(y)\)	\(\log(f) + \frac{\epsilon_1}{f}\)

Parameters

• model (Model) – Set error model for this model

• data_trans (str or expression) – A data transformation expression or None (default) to use the transformation specified by the model.

pharmpy.modeling.set_bolus_absorption(model)

Set or change to bolus absorption rate.

Parameters

model (Model) – Model to set or change absorption rate

pharmpy.modeling.set_combined_error_model(model, data_trans=None)

Set a combined error model. Initial estimates for new sigmas are \((min(DV)/2)²\) for proportional and 0.09 for additive.

The error function being applied depends on the data transformation.

Data transformation	Combined error
\(y\)	\(f + f \epsilon_1 + \epsilon_2\)
\(log(y)\)	\(\log(f) + \epsilon_1 + \frac{\epsilon_2}{f}\)

Parameters

• model (Model) – Set error model for this model

• data_trans (str or expression) – A data transformation expression or None (default) to use the transformation specified by the model.

pharmpy.modeling.set_dtbs_error_model(model)

Dynamic transform both sides

pharmpy.modeling.set_estimation_step(model, method, interaction=True, options={}, est_idx=0)

Set estimation step

Sets estimation step for a model. Methods currently supported are:

FO, FOCE, ITS, LAPLACE, IMPMAP, IMP, SAEM

Parameters

• model (Model) – Pharmpy model

• method (str) – estimation method to change to

• interaction (bool) – whether to use interaction or not, default is true

• options (dict) – any additional options. Note that this removes old options

• est_idx (int) – index of estimation step, default is 0 (first estimation step)

Returns

model (Model)

pharmpy.modeling.set_first_order_absorption(model)

Set or change to first order absorption rate. Initial estimate for absorption rate is set the previous rate if available, otherwise it is set to the time of first observation/2 is used.

Parameters

model (Model) – Model to set or change to use first order absorption rate

pharmpy.modeling.set_first_order_elimination(model)

pharmpy.modeling.set_iiv_on_ruv(model, list_of_eps=None, same_eta=True, eta_names=None)

Multiplies epsilons with exponential (new) etas. Initial estimates for new etas are 0.09.

Parameters

• model (Model) – Pharmpy model to apply IIV on epsilons.

• list_of_eps (str, list) – Name/names of epsilons to multiply with exponential etas. If None, all epsilons will be chosen. None is default.

• same_eta (bool) – Boolean of whether all RUVs from input should use the same new ETA or if one ETA should be created for each RUV. True is default.

• eta_names (str, list) – Custom names of new etas. Must be equal to the number epsilons or 1 if same eta.

pharmpy.modeling.set_initial_estimates(model, inits)

Set initial estimates

Parameters

• model (Model) – Pharmpy model

• inits (dict) – A dictionary of parameter init for parameters to change

Returns

model (Model)

pharmpy.modeling.set_lag_time(model)

Add lag time to the dose compartment of model. Initial estimate for lag time is set the previous lag time if available, otherwise it is set to the time of first observation/2 is used.

pharmpy.modeling.set_michaelis_menten_elimination(model)

Sets elimination to Michaelis-Menten. Initial estimate for CLMM is set to CL and KM is set to \(2*max(DV)\).

pharmpy.modeling.set_mixed_mm_fo_elimination(model)

Sets elimination to mixed Michaelis-Menten and first order. Initial estimate for CLMM is set to CL/2 and KM is set to \(2*max(DV)\).

pharmpy.modeling.set_name(model, new_name)

Sets name of model object

pharmpy.modeling.set_ode_solver(model, solver)

pharmpy.modeling.set_peripheral_compartments(model, n)

pharmpy.modeling.set_power_on_ruv(model, list_of_eps=None)

Applies a power effect to provided epsilons. Initial estimates for new thetas are 1 if the error model is proportional, otherwise they are 0.1.

Parameters

• model (Model) – Pharmpy model to create block effect on.

• list_of_eps (str, list) – Name/names of epsilons to apply power effect. If None, all epsilons will be used. None is default.

pharmpy.modeling.set_proportional_error_model(model, data_trans=None)

Set a proportional error model. Initial estimate for new sigma is 0.09.

The error function being applied depends on the data transformation.

Data transformation	Proportional error
\(y\)	\(f + f \epsilon_1\)
\(log(y)\)	\(\log(f) + \epsilon_1\)

Parameters

• model (Model) – Set error model for this model

• data_trans (str or expression) – A data transformation expression or None (default) to use the transformation specified by the model.

pharmpy.modeling.set_seq_zo_fo_absorption(model)

Set or change to sequential zero order first order absorption rate. Initial estimate for absorption rate is set the previous rate if available, otherwise it is set to the time of first observation/2 is used.

Parameters

model (Model) – Model to set or change absorption rate

pharmpy.modeling.set_transit_compartments(model, n)

Set the number of transit compartments of model. Initial estimate for absorption rate is set the previous rate if available, otherwise it is set to the time of first observation/2 is used.

pharmpy.modeling.set_weighted_error_model(model)

Encode error model with one epsilon and W as weight

pharmpy.modeling.set_zero_order_absorption(model)

Set or change to zero order absorption rate. Initial estimate for absorption rate is set the previous rate if available, otherwise it is set to the time of first observation/2 is used.

Parameters

model (Model) – Model to set or change to first order absorption rate

pharmpy.modeling.set_zero_order_elimination(model)

Sets elimination to zero order. Initial estimate for KM is set to 1% of smallest observation.

pharmpy.modeling.split_joint_distribution(model, rvs=None)

Splits etas following a joint distribution into separate distributions.

Parameters

• model (Model) – Pharmpy model

• rvs (str, list) – Name/names of etas to separate. If None, all etas that are IIVs and non-fixed will become single. None is default.

pharmpy.modeling.summarize_models(models)

pharmpy.modeling.transform_etas_boxcox(model, list_of_etas=None)

Applies a boxcox transformation to specified etas from a pharmpy.model. Initial estimate for lambda is 0.1 with bounds (-3, 3).

Parameters

• model (Model) – Pharmpy model to apply boxcox transformation to.

• list_of_etas (str, list) – Name/names of etas to transform. If None, all etas will be transformed (default).

pharmpy.modeling.transform_etas_john_draper(model, list_of_etas=None)

Applies a John Draper transformation 1 to specified etas from a pharmpy.model. Initial estimate for lambda is 0.1 with bounds (-3, 3).

1

John, J., Draper, N. (1980). An Alternative Family of Transformations. Journal of the Royal Statistical Society. Series C (Applied Statistics), 29(2), 190-197. doi:10.2307/2986305

Parameters

• model (Model) – Pharmpy model to apply John Draper transformation to.

• list_of_etas (str, list) – Name/names of etas to transform. If None, all etas will be transformed (default).

pharmpy.modeling.transform_etas_tdist(model, list_of_etas=None)

Applies a t-distribution transformation to specified etas from a pharmpy.model. Initial estimate for degrees of freedom is 80 with bounds (3, 100).

Parameters

• model (Model) – Pharmpy model to apply t distribution transformation to.

• list_of_etas (str, list) – Name/names of etas to transform. If None, all etas will be transformed (default).

pharmpy.modeling.unfix_parameters(model, parameter_names)

Unfix parameters

Unfix all listed parameters

Parameters

• model (Model) – Pharmpy model

• parameter_names (list or str) – one parameter name or a list of parameter names

Returns

model (Model)

pharmpy.modeling.unfix_parameters_to(model, parameter_names, values)

Unix parameters to

Unfix all listed parameters to specified value/values

Parameters

• model (Model) – Pharmpy model

• parameter_names (list or str) – one parameter name or a list of parameter names

• values (list or int) – one value or a list of values (must be equal to number of parameter_names)

Returns

model (Model)

pharmpy.modeling.update_inits(model, force_individual_estimates=False)

Updates initial estimates from previous output. Can be forced if no initial individual estimates have been read.

Parameters

• model (Model) – Pharmpy model to create block effect on.

• force_individual_estimates (bool) – Whether update of initial individual estimates should be forced.

pharmpy.modeling.update_source(model)

Update source

Let the code of the underlying source language be updated to reflect changes in the model object.

pharmpy.modeling.use_thetas_for_error_stdev(model)

Use thetas to estimate standard deviation of error

pharmpy.modeling.write_model(model, path='', force=True)

Write model to file

pharmpy.execute.dispatcher module pharmpy.modeling.data module