RandomVariables#

class pharmpy.model.RandomVariables(dists, eta_levels, epsilon_levels)[source]#

Bases: Sequence, Immutable

A collection of distributions 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 RandomVariables.

Examples

>>> from pharmpy.model import RandomVariables, NormalDistribution, Parameter
>>> omega = Parameter("OMEGA_CL", 0.1)
>>> dist = NormalDistribution.create("IIV_CL", "iiv", 0, omega.symbol)
>>> rvs = RandomVariables.create([dist])

Attributes Summary

`covariance_matrix`	Covariance matrix of all random variables
`epsilon_levels`	VariabilityHierarchy for all epsilons
`epsilons`	Get only the epsilons
`eta_levels`	VariabilityHierarchy for all etas
`etas`	Get only the etas
`free_symbols`	Set of free symbols for all random variables
`iiv`	Get only the iiv etas, i.e. etas with variability level 0.
`iov`	Get only the iov etas, i.e. etas with variability level 1.
`names`	List of the names of all random variables
`nrvs`
`parameter_names`	List of parameter names for all random variables
`symbols`	List with symbols for all random variables
`variance_parameters`	List of all parameters representing variance for all random variables

Methods Summary

`create`([dists, eta_levels, epsilon_levels])
`from_dict`(d)
`get_covariance`(rv1, rv2)	Get covariance between two random variables
`get_rvs_with_same_dist`(rv)	Gets random variables with the same distribution as input random variable
`join`(inds[, fill, name_template, param_names])	Join random variables together into one joint distribution
`nearest_valid_parameters`(parameter_values)	Force parameter values into being valid
`parameters_sdcorr`(values)	Convert parameter values to sd/corr form
`replace`(**kwargs)
`replace_with_sympy_rvs`(expr)	Replaces Pharmpy RVs in a Sympy expression with Sympy RVs
`sample`(expr[, parameters, samples, rng])	Sample from the distribution of expr
`subs`(d)	Substitute expressions
`to_dict`()
`unjoin`(inds)	Remove all covariances the random variables have with other random variables
`validate_parameters`(parameter_values)	Validate a dict or Series of parameter values

Attributes Documentation

covariance_matrix#: Covariance matrix of all random variables

epsilon_levels#: VariabilityHierarchy for all epsilons

epsilons#: Get only the epsilons

eta_levels#: VariabilityHierarchy for all etas

etas#: Get only the etas

free_symbols#: Set of free symbols for all random variables

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

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

names#: List of the names of all random variables

nrvs#

parameter_names#: List of parameter names for all random variables

symbols#: List with symbols for all random variables

variance_parameters#: List of all parameters representing variance for all random variables

Methods Documentation

classmethod create(dists=None, eta_levels=None, epsilon_levels=None)[source]#

classmethod from_dict(d)[source]#

get_covariance(rv1, rv2)[source]#: Get covariance between two random variables

get_rvs_with_same_dist(rv)[source]#

Gets random variables with the same distribution as input random variable

The resulting RandomVariables objects includes the input random variable.

Parameters:: rv (str) – Name of random variable
Returns:: RandomVariables – RandomVariables object with all distributions as input random variable (including input)

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’. All joined random variables will form a new joint normal distribution and if they were part of previous joint normal distributions they will be taken out from these and the remaining variables will be stay.

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 tuple of a the new RandomVariables and a dictionary from newly created covariance parameter names to
tuple of parameter names. Empty dictionary if no parameter symbols were created

Examples

>>> from pharmpy.model import RandomVariables, NormalDistribution, Parameter
>>> omega_cl = Parameter("OMEGA_CL", 0.1)
>>> omega_v = Parameter("OMEGA_V", 0.1)
>>> dist1 = NormalDistribution.create("IIV_CL", "IIV", 0, omega_cl.symbol)
>>> dist2 = NormalDistribution.create("IIV_V", "IIV", 0, omega_v.symbol)
>>> rvs = RandomVariables.create([dist1, dist2])
>>> rvs, _ = rvs.join(['IIV_CL', 'IIV_V'])
>>> rvs
⎡IIV_CL⎤    ⎧⎡0⎤  ⎡OMEGA_CL     0   ⎤⎫
⎢      ⎥ ~ N⎪⎢ ⎥, ⎢                 ⎥⎪
⎣IIV_V ⎦    ⎩⎣0⎦  ⎣   0      OMEGA_V⎦⎭

See also

unjoin

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

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.

Parameters:: values (dict) – Dict of parameter names to values

replace(**kwargs)[source]#

replace_with_sympy_rvs(expr)[source]#

Replaces Pharmpy RVs in a Sympy expression with Sympy RVs

Takes a Sympy expression and replaces all RVs with Sympy RVs, resulting expression can be used in different Sympy functions (e.g. sympy.stats.std())

Parameters:: expr (sympy.Expr) – Expression which will get RVs replaced
Returns:: sympy.Expr – Expression with replaced RVs

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

Sample from the distribution of expr

parameters in the distributions will first be replaced

subs(d)[source]#

Substitute expressions

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

Examples

>>> from pharmpy.basic import Expr
>>> from pharmpy.model import RandomVariables, Parameter
>>> omega = Parameter("OMEGA_CL", 0.1)
>>> dist = NormalDistribution.create("IIV_CL", "IIV", 0, omega.symbol)
>>> rvs = RandomVariables.create([dist])
>>> rvs.subs({omega.symbol: Expr.symbol("OMEGA_NEW")})
IIV_CL ~ N(0, OMEGA_NEW)

to_dict()[source]#

unjoin(inds)[source]#

Remove all covariances the random variables have with other random variables

Parameters:: inds – One or multiple names or symbols to unjoin

Examples

>>> from pharmpy.model import RandomVariables, JointNormalDistribution, Parameter
>>> omega_cl = Parameter("OMEGA_CL", 0.1)
>>> omega_v = Parameter("OMEGA_V", 0.1)
>>> corr_cl_v = Parameter("OMEGA_CL_V", 0.01)
>>> dist1 = JointNormalDistribution.create(["IIV_CL", "IIV_V"], 'IIV', [0, 0],
...     [[omega_cl.symbol, corr_cl_v.symbol], [corr_cl_v.symbol, omega_v.symbol]])
>>> rvs = RandomVariables.create([dist1])
>>> rvs.unjoin('IIV_CL')
IIV_CL ~ N(0, OMEGA_CL)
IIV_V ~ N(0, OMEGA_V)