pharmpy.random_variables module

class pharmpy.random_variables.RandomVariable(name, level, sympy_rv=None)

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)

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)

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)

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)

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.random_variables.RandomVariables(rvs=None)

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)

Make copy of RandomVariables

Parameters

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

property covariance_matrix

Covariance matrix of all random variables

distributions()

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)

Get covariance between two random variables

get_variance(rv)

Get variance for a random variable

property iiv

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

insert(ind, value)

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)

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)

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)

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)

Sample from the distribution of expr

parameters in the distriutions will first be replaced

subs(d)

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)

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)

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.random_variables.VariabilityHierarchy

Bases: object

Description of a variability hierarchy

add_higher_level(name, group)

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)

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)

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)

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)

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)

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

class pharmpy.random_variables.VariabilityLevel(name, level, group=None)

Bases: object

A variability level

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)

Inheritance Diagram

pharmpy.parameter_sampling module pharmpy.results module