RandomVariables#

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

Bases: 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])

Attributes Summary

`covariance_matrix`	Covariance matrix of all random variables
`epsilons`	Get only the epsilons
`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
`parameter_names`	List of parameter names for all random variables
`variance_parameters`	List of all parameters representing variance for all random variables

Methods Summary

`copy`()	Make copy of RandomVariables
`distributions`()	List with one entry per distribution instead of per random variable.
`get_covariance`(rv1, rv2)	Get covariance between two random variables
`get_variance`(rv)	Get variance for a random variable
`insert`(ind, value)	S.insert(index, value) -- insert value before index
`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
`sample`(expr[, parameters, samples, rng])	Sample from the distribution of expr
`subs`(d)	Substitute expressions
`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

epsilons#: Get only the epsilons

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

parameter_names#: List of parameter names for all random variables

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

Methods Documentation

copy()[source]#: Make copy of RandomVariables

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()

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

get_variance(rv)[source]#: Get variance for a random variable

insert(ind, value)[source]#: S.insert(index, value) – insert value before index

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   ⎤⎫
⎢      ⎥ ~ 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. Only parameters for normal distributions will be affected.

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

sample(expr, parameters=None, samples=1, rng=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 ~ N(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 ~ N(0, OMEGA_CL)
IIV_V ~ N(0, OMEGA_V)