pharmpy package

Subpackages

Submodules

Module contents

Pharmpy

Pharmpy is a python package for pharmacometrics modelling.

Definitions

pharmpy.Model(obj, **kwargs)[source]

Factory for creating a pharmpy.model object from an object representing the model (i.e. path).

Parameters

obj – Currently a path-like object pointing to the model file.

Returns

  • Generic Model if path is None, otherwise appropriate implementation – is invoked (e.g. NONMEM7 Model).

class pharmpy.ModelStatements(statements=None)[source]

Bases: collections.abc.MutableSequence

A list of sympy statements describing the model

add_before_odes(statement)[source]

Add a statement just before the ODE system or at the end of the model

before_ode()[source]
copy()[source]
dependencies(symbol)[source]

Find all dependencies of a symbol

extract_params_from_symb(symbol_name, pset)[source]
find_assignment(variable, is_symbol=True, last=True)[source]

Returns full last statement or all assignments that contains the symbol or variable of interest of an assignment

property free_symbols

Get a set of all free symbols

full_expression_after_odes(expression)[source]

Expand an expression into its full definition

After ODE system

full_expression_from_odes(expression)[source]

Expand an expression into its full definition

Before ODE system

insert(ind, value)[source]

S.insert(index, value) – insert value before index

property ode_system

Returns the ODE system of the model or None if the model doesn’t have an ODE system

reassign(symbol, expression)[source]

Reassign symbol to expression

remove_symbol_definitions(symbols, statement)[source]

Remove symbols and dependencies not used elsewhere. statement is the statement from which the symbol was removed

subs(substitutions)[source]

Substitute symbols in all statements.

substitutions - dictionary with old-new pair (can be type str or

sympy symbol)

class pharmpy.Parameter(name, init, lower=None, upper=None, fix=False, unit=1)[source]

Bases: object

A single parameter

Example

>>> from pharmpy import Parameter
>>> param = Parameter("TVCL", 0.005, lower=0)
>>> param.fix = True
Parameters

  • name (str) – Name of the parameter

  • init (number) – Initial estimate or simply the value of parameter.

  • fix (bool) – A boolean to indicate whether the parameter is fixed or not. Note that fixing a parameter will keep its bounds even if a fixed parameter is actually constrained to one single value. This is so that unfixing will take back the previous bounds.

  • lower (number) – The lower bound of the parameter. Default no bound. Must be less than the init.

  • upper (number) – The upper bound of the parameter. Default no bound. Must be greater than the init.

  • unit (str or unit expression) – Unit of parameter. Default to unitless

copy()[source]

Create a copy of this Parameter

property init

Initial parameter estimate or value

is_close_to_bound(value=None, zero_limit=0.01, significant_digits=2)[source]

Check if parameter value is close to any bound

Parameters

  • value (number) – value to check against parameter bounds. Defaults to checking against the parameter init

  • zero_limit (number) – maximum distance to 0 bounds

  • significant_digits (int) – maximum distance to non-zero bounds in number of significant digits

Examples

>>> from pharmpy import Parameter
>>> par = Parameter("x", 1, lower=0, upper=10)
>>> par.is_close_to_bound()
False

>>> par.is_close_to_bound(0.005)
True

>>> par.is_close_to_bound(0.005, zero_limit=0.0001)
False

>>> par.is_close_to_bound(9.99)
True

>>> par.is_close_to_bound(9.99, significant_digits=3)
False
property lower

Lower bound of the parameter

property parameter_space

The parameter space set

A fixed parameter will be constrained to one single value and non-fixed parameters will be constrained to an interval possibly open in one or both ends.

Examples

>>> import sympy
>>> from pharmpy import Parameter
>>> par = Parameter("x", 1, lower=0, upper=10)
>>> sympy.pprint(par.parameter_space)
[0, 10]

>>> par.fix = True
>>> sympy.pprint(par.parameter_space)
{1}
property symbol

Symbol representing the parameter

unconstrain()[source]

Remove all constraints from this parameter

Example

>>> from pharmpy import Parameter
>>> par = Parameter("x", 1, lower=0, upper=2)
>>> par.unconstrain()
>>> par
Parameter("x", 1, lower=-oo, upper=oo, fix=False)
property upper

Upper bound of the parameter

class pharmpy.Parameters(params=None)[source]

Bases: collections.abc.MutableSequence

A collection of parameters

Class representing a group of parameters. Usually all parameters in a model. This class give a ways of displaying, summarizing and manipulating more than one parameter at a time.

Specific parameters can be found using indexing on the parameter name

Example

>>> from pharmpy import Parameters, Parameter
>>> par1 = Parameter("x", 0)
>>> par2 = Parameter("y", 1)
>>> pset = Parameters([par1, par2])
>>> pset["x"]
Parameter("x", 0, lower=-oo, upper=oo, fix=False)

>>> "x" in pset
True

>>> pset.append(Parameter("z", 0.1))
>>> len(pset)
3

>>> del pset["x"]
>>> len(pset)
2
copy()[source]

Create a deep copy of this Parameters

property fix

Fixedness of parameters as dict

property inits

Initial estimates of parameters as dict

insert(ind, value)[source]

S.insert(index, value) – insert value before index

is_close_to_bound(values=None, zero_limit=0.01, significant_digits=2)[source]

Logical Series of whether values are close to the respective bounds

Parameters

values (pd.Series) – Series of values with index a subset of parameter names. Default is to use all parameter inits

Returns

pd.Series – Logical Series with same index as values

Example

>>> from pharmpy import Parameters, Parameter
>>> par1 = Parameter("CL", 1, lower=0, upper=10)
>>> par2 = Parameter("V", 10, lower=0, upper=100)
>>> pset = Parameters([par1, par2])
>>> pset.is_close_to_bound()
CL    False
V     False
dtype: bool
property lower

Lower bounds of all parameters as a dictionary

property names

List of all parameter names

property nonfixed_inits

Dict of initial estimates for all non-fixed parameters

remove_fixed()[source]

Remove all fixed parameters

simplify(expr)[source]

Simplify expression given constraints of parameters

property symbols

List of all parameter symbols

to_dataframe()[source]

Create a dataframe with a summary of all Parameters

Returns

DataFrame – A dataframe with one row per parameter. The columns are value, lower, upper and fix Row Index is the names

Example

>>> from pharmpy import Parameters, Parameter
>>> par1 = Parameter("CL", 1, lower=0, upper=10)
>>> par2 = Parameter("V", 10, lower=0, upper=100)
>>> pset = Parameters([par1, par2])
>>> pset.to_dataframe()
    value  lower  upper    fix
CL      1      0     10  False
V      10      0    100  False
property upper

Upper bounds of all parameters as a dictionary

class pharmpy.RandomVariable(name, level, sympy_rv=None)[source]

Bases: object

A single random variable

Parameters

  • name (str) – Name of the random variable

  • level (str) – Name of the variability level. The default levels are IIV, IOV and RUV

  • sympy_rv (sympy.RandomSymbol) – RandomSymbol to use for this random variable. See also the normal and joint_normal classmethods.

Examples

>>> import sympy
>>> import sympy.stats
>>> from pharmpy import RandomVariable
>>> name = "ETA(1)"
>>> sd = sympy.sqrt(sympy.Symbol('OMEGA(1,1)'))
>>> rv = RandomVariable(name, "IIV", sympy.stats.Normal(name, 0, sd))
>>> rv
ETA(1) ~ 𝒩 (0, OMEGA(1,1))

See also

normal, joint_normal

copy(deep=True)[source]

Make copy of RandomVariable

Parameters

deep (bool) – Deep copy if True (default) else shallow

property free_symbols

Free symbols including random variable itself

property joint_names

Names of all (including this) jointly varying rvs in a list

classmethod joint_normal(names, level, mu, sigma)[source]

Create joint normally distributed random variables

Parameters

  • names (list) – Names of the random variables

  • level (str) – Variability level

  • mu (matrix or list) – Vector of the means of the random variables

  • sigma (matrix or list of lists) – Covariance matrix of the random variables

Example

>>> from pharmpy import RandomVariable, Parameter
>>> omega_cl = Parameter("OMEGA_CL", 0.1)
>>> omega_v = Parameter("OMEGA_V", 0.1)
>>> corr_cl_v = Parameter("OMEGA_CL_V", 0.01)
>>> rv1, rv2 = RandomVariable.joint_normal(["IIV_CL", "IIV_V"], 'IIV', [0, 0],
...     [[omega_cl.symbol, corr_cl_v.symbol], [corr_cl_v.symbol, omega_v.symbol]])
>>> rv1
⎡IIV_CL⎤     ⎧⎡0⎤  ⎡ OMEGA_CL   OMEGA_CL_V⎤⎫
⎢      ⎥ ~ 𝒩 ⎪⎢ ⎥, ⎢                      ⎥⎪
⎣IIV_V ⎦     ⎩⎣0⎦  ⎣OMEGA_CL_V   OMEGA_V  ⎦⎭
property name

Name of the random variable

classmethod normal(name, level, mean, variance)[source]

Create a normally distributed random variable

Parameters

  • name (str) – Name of the random variable

  • level (str) – Name of the variability level

  • mean (expression or number) – Mean of the random variable

  • variance (expression or number) – Variance of the random variable

Example

>>> from pharmpy import RandomVariable, Parameter
>>> omega = Parameter('OMEGA_CL', 0.1)
>>> rv = RandomVariable.normal("IIV_CL", "IIV", 0, omega.symbol)
>>> rv
IIV_CL ~ 𝒩 (0, OMEGA_CL)
property parameter_names

List of names of all parameters used in definition

subs(d)[source]

Substitute expressions

Parameters

d (dict) – Dictionary of from: to pairs for substitution

Examples

>>> import sympy
>>> from pharmpy import RandomVariable, Parameter
>>> omega = Parameter("OMEGA_CL", 0.1)
>>> rv = RandomVariable.normal("IIV_CL", "IIV", 0, omega.symbol)
>>> rv.subs({omega.symbol: sympy.Symbol("OMEGA_NEW")})
>>> rv
IIV_CL ~ 𝒩 (0, OMEGA_NEW)
property sympy_rv

Corresponding sympy random variable

class pharmpy.RandomVariables(rvs=None)[source]

Bases: collections.abc.MutableSequence

A collection of random variables

This class provides a container for random variables that preserves their order and acts list-like while also allowing for indexing on names.

Each RandomVariables object has two VariabilityHierarchies that describes the allowed variability levels for the contined random variables. One hierarchy for residual error variability (epsilons) and one for parameter variability (etas). By default the eta hierarchy has the two levels IIV and IOV and the epsilon hierarchy has one single level.

Parameters

rvs (list) – A list of RandomVariable to add. Default is to create an empty RandomVariabels.

Examples

>>> from pharmpy import RandomVariables, RandomVariable, Parameter
>>> omega = Parameter("OMEGA_CL", 0.1)
>>> rv = RandomVariable.normal("IIV_CL", "iiv", 0, omega.symbol)
>>> rvs = RandomVariables([rv])
copy(deep=True)[source]

Make copy of RandomVariables

Parameters

deep (bool) – Deep copy if True (default) else shallow

property covariance_matrix

Covariance matrix of all random variables

distributions()[source]

List with one entry per distribution instead of per random variable.

Returned is a list of tuples of a list of random variables that are jointly distributed and the distribution.

Example

>>> from pharmpy import RandomVariables, RandomVariable, Parameter
>>> omega_cl = Parameter("OMEGA_CL", 0.1)
>>> omega_v = Parameter("OMEGA_V", 0.1)
>>> omega_ka = Parameter("OMEGA_KA", 0.1)
>>> corr_cl_v = Parameter("OMEGA_CL_V", 0.01)
>>> rv1, rv2 = RandomVariable.joint_normal(["IIV_CL", "IIV_V"], 'IIV', [0, 0],
...     [[omega_cl.symbol, corr_cl_v.symbol], [corr_cl_v.symbol, omega_v.symbol]])
>>> rv3 = RandomVariable.normal("IIV_KA", 'IIV', 0, omega_ka.symbol)
>>> rvs = RandomVariables([rv1, rv2, rv3])
>>> dists = rvs.distributions()
property epsilons

Get only the epsilons

property etas

Get only the etas

property free_symbols

Set of free symbols for all random variables

get_covariance(rv1, rv2)[source]

Get covariance between two random variables

get_variance(rv)[source]

Get variance for a random variable

property iiv

Get only the iiv etas, i.e. etas with variability level 0

insert(ind, value)[source]

S.insert(index, value) – insert value before index

property iov

Get only the iov etas, i.e. etas with variability level 1

join(inds, fill=0, name_template=None, param_names=None)[source]

Join random variables together into one joint distribution

Set new covariances (and previous 0 covs) to ‘fill’

Parameters

  • inds – Indices of variables to join

  • fill (value) – Value to use for new covariances. Default is 0

  • name_template (str) – A string template to use for new covariance symbols. Using this option will override fill.

  • param_names (list) – List of parameter names to be used together with name_template.

Returns

  • A dictionary from newly created covariance parameter names to

  • tuple of parameter names. Empty dictionary if no parameter

  • symbols were created

Examples

>>> from pharmpy import RandomVariables, RandomVariable, Parameter
>>> omega_cl = Parameter("OMEGA_CL", 0.1)
>>> omega_v = Parameter("OMEGA_V", 0.1)
>>> rv1 = RandomVariable.normal("IIV_CL", 'IIV', 0, omega_cl.symbol)
>>> rv2 = RandomVariable.normal("IIV_V", 'IIV', 0, omega_v.symbol)
>>> rvs = RandomVariables([rv1, rv2])
>>> rvs.join(['IIV_CL', 'IIV_V'])
{}
>>> rvs
⎡IIV_CL⎤     ⎧⎡0⎤  ⎡OMEGA_CL     0   ⎤⎫
⎢      ⎥ ~ 𝒩 ⎪⎢ ⎥, ⎢                 ⎥⎪
⎣IIV_V ⎦     ⎩⎣0⎦  ⎣   0      OMEGA_V⎦⎭

See also

unjoin

property names

List of the names of all random variables

nearest_valid_parameters(parameter_values)[source]

Force parameter values into being valid

As small changes as possible

returns a dict with the valid parameter values

property parameter_names

List of parameter names for all random variables

parameters_sdcorr(values)[source]

Convert parameter values to sd/corr form

All parameter values will be converted to sd/corr assuming they are given in var/cov form. Only parameters for normal distributions will be affected.

Parameters

values (dict) – Dict of parameter names to values

sample(expr, parameters=None, samples=1, seed=None)[source]

Sample from the distribution of expr

parameters in the distriutions will first be replaced

subs(d)[source]

Substitute expressions

Parameters

d (dict) – Dictionary of from: to pairs for substitution

Examples

>>> import sympy
>>> from pharmpy import RandomVariables, Parameter
>>> omega = Parameter("OMEGA_CL", 0.1)
>>> rv = RandomVariable.normal("IIV_CL", "IIV", 0, omega.symbol)
>>> rvs = RandomVariables([rv])
>>> rvs.subs({omega.symbol: sympy.Symbol("OMEGA_NEW")})
>>> rvs
IIV_CL ~ 𝒩 (0, OMEGA_NEW)
unjoin(inds)[source]

Remove all covariances the random variables have with other random variables

Parameters

inds – One or multiple indices to unjoin

Examples

>>> from pharmpy import RandomVariables, RandomVariable, Parameter
>>> omega_cl = Parameter("OMEGA_CL", 0.1)
>>> omega_v = Parameter("OMEGA_V", 0.1)
>>> corr_cl_v = Parameter("OMEGA_CL_V", 0.01)
>>> rv1, rv2 = RandomVariable.joint_normal(["IIV_CL", "IIV_V"], 'IIV', [0, 0],
...     [[omega_cl.symbol, corr_cl_v.symbol], [corr_cl_v.symbol, omega_v.symbol]])
>>> rvs = RandomVariables([rv1, rv2])
>>> rvs.unjoin('IIV_CL')
>>> rvs
IIV_CL ~ 𝒩 (0, OMEGA_CL)
IIV_V ~ 𝒩 (0, OMEGA_V)

See also

join

validate_parameters(parameter_values)[source]

Validate a dict or Series of parameter values

Currently checks that all covariance matrices are posdef use_cache for using symengine cached matrices

property variance_parameters

List of all parameters representing variance for all random variables

class pharmpy.VariabilityHierarchy[source]

Bases: object

Description of a variability hierarchy

add_higher_level(name, group)[source]

Add a higher variability level to hierarchy

Parameters

  • name (str) – Name of new variability level

  • group (str) – Name of data column to group this level. None for no grouping (default)

Examples

>>> from pharmpy import VariabilityHierarchy
>>> hierarchy = VariabilityHierarchy()
>>> hierarchy.add_variability_level("IIV", 0, "ID")
>>> hierarchy.add_higher_level("IOV", "OCC")

See also

add_variability_level, add_lower_level

add_lower_level(name, group)[source]

Add a lower variability level to hierarchy

Parameters

  • name (str) – Name of new variability level

  • group (str) – Name of data column to group this level. None for no grouping (default)

Examples

>>> hierarchy = VariabilityHierarchy()
>>> hierarchy.add_variability_level("IIV", 0, "ID")
>>> hierarchy.add_lower_level("ICV", "COUNTRY")

See also

add_variability_level, add_higher_level

add_variability_level(name, level, group)[source]

Add variability level to hierarchy

Parameters

  • name (str) – A unique identifying name

  • level (int) – Numeric level. 0 is the base level. Lower levels consists of groups of higher levels. If for example 0 is IIV then IOV could be 1 and COUNTRY could be -1

  • group (str) – Name of data column to group this level. None for no grouping (default)

Examples

>>> from pharmpy import VariabilityHierarchy
>>> hierarchy = VariabilityHierarchy()
>>> hierarchy.add_variability_level("IIV", 0, "ID")
>>> hierarchy.add_variability_level("IOV", 1, "OCC")
get_name(i)[source]

Retrieve name of variability level

Parameters

i - int – Numeric variability level

Examples

>>> from pharmpy import VariabilityHierarchy
>>> hierarchy = VariabilityHierarchy()
>>> hierarchy.add_variability_level("IIV", 0, "ID")
>>> hierarchy.add_variability_level("IOV", 1, "OCC")
>>> hierarchy.get_name(1)
'IOV'
>>> hierarchy.get_name(0)
'IIV'
property levels

All numerical levels

property names

Names of all variability levels

remove_variability_level(ind)[source]

Remove a variability level

Parameters

ind (str or int) – name or number of variability level

Examples

>>> from pharmpy import VariabilityHierarchy
>>> hierarchy = VariabilityHierarchy()
>>> hierarchy.add_variability_level("IIV", 0, "ID")
>>> hierarchy.add_lower_level("ICV", "COUNTRY")
>>> hierarchy.remove_variability_level(-1)

See also

set_variability_level

set_variability_level(level, name, group)[source]

Change the name and group of variability level

Parameters

  • level (int) – Numeric level to change

  • name (str) – Name of new variability level

  • group (str) – Name of data column to group this level. None for no grouping (default)

Examples

>>> from pharmpy import VariabilityHierarchy
>>> hierarchy = VariabilityHierarchy()
>>> hierarchy.add_variability_level("IIV", 0, "ID")
>>> hierarchy.add_lower_level("ICV", "COUNTRY")
>>> hierarchy.set_variability_level(-1, "ICV", "CENTER")

See also

remove_variability_level

pharmpy.symbol(name)[source]
pharmpy pharmpy.data package