Population Models

Population models in chi can be used to model the variation of mechanistic model parameters or error model parameters across individuals.

Classes

ComposedPopulationModel
CovariatePopulationModel
GaussianModel
HeterogeneousModel
LogNormalModel
PooledModel
TruncatedGaussianModel

Detailed API

class chi.ComposedPopulationModel(population_models)[source]

A multi-dimensional population model composed of mutliple population models.

A ComposedPopulationModel assumes that its constituent population models are independent. The probability density function of the composed population model is therefore given by the product of the probability density functions.

For constituent population models \(p(\psi _1 | \theta _1), \ldots , p(\psi _n | \theta _n)\), the probability density function of the composed population model is given by

\[p(\psi _1, \ldots , \psi _n | \theta _1, \ldots , \theta _n) = \prod _{k=1}^n p(\psi _k | \theta _k) .\]

Extends chi.PopulationModel.

Parameters:: population_models (List[chi.PopulationModel]) – A list of population models.

compute_individual_parameters(parameters, eta, covariates=None, return_eta=False)[source]

Returns the individual parameters.

If the model does not transform the bottom-level parameters, eta is returned.

If the population model does not use covariates, the covariate input is ignored.

If the population model uses covariates, the covariates of the constituent population models are expected to be concatinated in the order of the consitutent models. The order of the covariates can be checked with get_covariate_names().

Parameters:

parameters (np.ndarray of shape (n_parameters,)) – Model parameters.
eta (np.ndarray of shape (n_ids * n_dim) or (n_ids, n_dim)) – Inter-individual fluctuations.
covariates (np.ndarray of shape (n_ids, n_cov)) – Covariates of the individuals.
return_eta (boolean, optional) – A boolean flag indicating whether eta is returned regardless of whether the parametrisation is centered or not.

Return type:

np.ndarray of shape (n_ids, n_dim)

compute_log_likelihood(parameters, observations, covariates=None)[source]

Returns the log-likelihood of the population model parameters.

Parameters:

parameters (np.ndarray of shape (n_parameters,), (n_param_per_dim, n_dim) or (n_ids, n_param_per_dim, n_dim)) – Parameters of the population model.
observations (np.ndarray of shape (n_ids, n_dim)) – Individual model parameters.
covariates (np.ndarray of shape (n_ids, n_cov)) – Covariates of the individuals.

Return type:

float

compute_pointwise_ll(parameters, observations)[source]

Returns the pointwise log-likelihood of the model parameters for each observation.

Parameters:

parameters (np.ndarray of shape (p, n_dim)) – Parameters of the population model.
observations (np.ndarray of shape (n, n_dim)) – “Observations” of the individuals. Typically refers to the values of a mechanistic model parameter for each individual.

Returns:

Log-likelihoods for each individual parameter for population parameters.

Return type:

np.ndarray of length (n, n_dim)

compute_sensitivities(parameters, observations, dlogp_dpsi=None, reduce=False, covariates=None, *args, **kwargs)[source]

Returns the log-likelihood of the population model parameters and its sensitivity to the population parameters as well as the observations.

The log-likelihood and sensitivities are returned as a tuple (score, deta, dtheta).

Parameters:

parameters (np.ndarray of shape (n_parameters,), (n_param_per_dim, n_dim) or (n_ids, n_param_per_dim, n_dim)) – Parameters of the population model.
observations (np.ndarray of shape (n_ids, n_dim)) – Individual model parameters.
dlogp_dpsi (np.ndarray of shape (n_ids, n_dim), optional) – The sensitivities of the log-likelihood of the individual parameters with respect to the individual parameters.
reduce (bool, optional) – A boolean flag indicating whether the sensitivites are returned as an array of shape (n_hierarchical_parameters,). reduce is prioritised over flattened.
covariates (np.ndarray of shape (n_ids, n_cov)) – Covariates of individuals.

Return type:

Tuple[float, np.ndarray of shape (n_ids, n_dim), np.ndarray of shape (n_parameters,)]

get_covariate_names()[source]: Returns the names of the covariates. If name is not set, defaults are returned.

get_dim_names()[source]: Returns the names of the dimensions.

get_parameter_names(exclude_dim_names=False)[source]

Returns the names of the population model parameters. If name is not set, defaults are returned.

Parameters:: exclude_dim_names (bool, optional) – A boolean flag that indicates whether the dimension name is appended to the parameter name.

get_population_models()[source]: Returns the constituent population models.

get_special_dims()

Returns information on pooled and heterogeneously modelled dimensions.

Returns a tuple with 3 entries:

A list of lists, each entry containing 1. the start and end
dimension of the special dimensions; 2. the associated start and end index of the model parameters; 3. and a boolean indicating whether the dimension is pooled (True) or heterogeneous (False).
The number of pooled dimensions.
The number of heterogeneous dimensions.

n_covariates(): Returns the number of covariates.

n_dim(): Returns the dimensionality of the population model.

n_hierarchical_dim()

Returns the number of parameter dimensions whose samples are not deterministically defined by the population parameters.

I.e. the number of dimensions minus the number of pooled and heterogeneously modelled dimensions.

n_hierarchical_parameters(n_ids)[source]

Returns a tuple of the number of individual parameters and the number of population parameters that this model expects in context of a HierarchicalLogLikelihood, when n_ids individuals are modelled.

Parameters:: n_ids – Number of individuals.

n_ids()

Returns the number of modelled individuals.

If the behaviour of the population model does not change with the number of modelled individuals 0 is returned.

n_parameters()[source]: Returns the number of parameters of the population model.

sample(parameters, n_samples=None, seed=None, covariates=None, *args, **kwargs)[source]

Returns random samples from the population distribution.

The returned value is a NumPy array with shape (n_samples, n_dim).

If the model does not depend on covariates the covariate input is ignored.

If the population model uses covariates, the covariates of the constituent population models are expected to be concatinated in the order of the consitutent models. The order of the covariates can be checked with get_covariate_names().

Parameters:

parameters (List, np.ndarray of shape (n_parameters,)) – Values of the model parameters.
n_samples (int, optional) – Number of samples. If None, one sample is returned.
seed (int, np.random.Generator, optional) – A seed for the pseudo-random number generator.
covariates (List, np.ndarray of shape (n_cov,) or (n_samples, n_cov), optional) – Covariate values, specifying the sampled subpopulation.

Returns:

Samples from population model conditional on covariates.

Return type:

np.ndarray of shape (n_samples, n_dim)

set_covariate_names(names=None)

Sets the names of the covariates.

If the model has no covariates, input is ignored.

Parameters:: names (List[str]) – A list of parameter names. If None, covariate names are reset to defaults.

set_dim_names(names=None)[source]

Sets the names of the population model dimensions.

Parameters:: names – An array-like object with string-convertable entries of length n_dim(). If None, dimension names are reset to defaults.

set_n_ids(n_ids)[source]

Sets the number of modelled individuals.

The behaviour of most population models is the same for any number of individuals, in which case n_ids is ignored. However, for some models, e.g. HeterogeneousModel the behaviour changes with n_ids.

Parameters:: n_ids (int) – Number of individuals.

set_parameter_names(names=None)[source]

Sets the names of the population model parameters.

Parameters:: names (List[str]) – A list with string-convertable entries of length n_parameters(). If None, parameter names are reset to defaults.

class chi.CovariatePopulationModel(population_model, covariate_model, dim_names=None)[source]

A population model that models the parameters across individuals conditional on covariates of the inter-individual variability.

A covariate population model partitions a population into subpopulations which are characterised by covariates \(\chi\). The inter-individual variability within a subpopulation is modelled by a non-covariate population model

\[p(\psi | \theta, \chi) = p(\psi | \vartheta (\theta, \chi)),\]

where \(\vartheta\) are the population parameters of the subpopulation which depend on global population parameters \(\theta\) and the covariates \(\chi\).

The population_model input defines the non-covariate population model for the subpopulations \(p(\psi | \vartheta )\) and the covariate_model defines the relationship between the subpopulations and the covariates \(\vartheta (\theta, \chi)\).

Extends PopulationModel.

Parameters:

population_model (PopulationModel) – Defines the distribution of the subpopulations.
covariate_model (CovariateModel) – Defines the covariate model.
dim_names (List[str], optional) – Name of dimensions.

compute_individual_parameters(parameters, eta, covariates, return_eta=False)[source]

Returns the individual parameters.

If the model does not transform the bottom-level parameters, eta is returned.

Parameters:

parameters (np.ndarray of shape (n_parameters,)) – Model parameters.
eta (np.ndarray of shape (n_ids * n_dim) or (n_ids, n_dim)) – Inter-individual fluctuations.
covariates (np.ndarray of shape (n_ids, n_cov)) – Covariates of individuals.
return_eta (boolean, optional) – A boolean flag indicating whether eta is returned regardless of whether the parametrisation is centered or not.

Return type:

np.ndarray of shape (n_ids, n_dim)

compute_log_likelihood(parameters, observations, covariates)[source]

Returns the log-likelihood of the population model parameters.

Parameters:

parameters (np.ndarray of shape (n_parameters,)) – Parameters of the population model.
observations (np.ndarray of shape (n_ids, n_dim)) – Individual model parameters.
covariates (np.ndarray of shape (n_ids, n_cov)) – Covariates of individuals.

Return type:

float

compute_pointwise_ll(parameters, observations, *args, **kwargs)

Returns the pointwise log-likelihood of the model parameters for each observation.

Parameters:

parameters (np.ndarray of shape (p, n_dim)) – Parameters of the population model.
observations (np.ndarray of shape (n, n_dim)) – “Observations” of the individuals. Typically refers to the values of a mechanistic model parameter for each individual.

Returns:

Log-likelihoods for each individual parameter for population parameters.

Return type:

np.ndarray of length (n, n_dim)

compute_sensitivities(parameters, observations, covariates, dlogp_dpsi=None, reduce=False)[source]

Returns the log-likelihood of the population model parameters and its sensitivity to the population parameters as well as the observations.

The sensitivities of the bottom-level log-likelihoods with respect to the observations (bottom-level parameters) may be provided using dlogp_dpsi, in order to compute the sensitivities of the full hierarchical log-likelihood.

The log-likelihood and sensitivities are returned as a tuple (score, deta, dtheta).

Parameters:

parameters (np.ndarray of shape (n_parameters,)) – Parameters of the population model.
observations (np.ndarray of shape (n_ids, n_dim)) – Individual model parameters.
covariates (np.ndarray of shape (n_ids, n_cov)) – Covariates of individuals.
dlogp_dpsi (np.ndarray of shape (n_ids, n_dim), optional) – The sensitivities of the log-likelihood of the individual parameters with respect to the individual parameters.
reduce (bool, optional) – A boolean flag indicating whether the sensitivites are returned as an array of shape (n_hierarchical_parameters,). reduce is prioritised over flattened.

Return type:

Tuple[float, np.ndarray of shape (n_ids, n_dim), np.ndarray of shape (n_parameters,)]

get_covariate_names()[source]: Returns the names of the covariates. If name is not set, defaults are returned.

get_dim_names()[source]: Returns the names of the dimensions.

get_parameter_names(exclude_dim_names=False)[source]

Returns the names of the model parameters. If name is not set, defaults are returned.

Parameters:: exclude_dim_names (bool, optional) – A boolean flag that indicates whether the dimension name is appended to the parameter name.

get_special_dims()

Returns information on pooled and heterogeneously modelled dimensions.

Returns a tuple with 3 entries:

A list of lists, each entry containing 1. the start and end
dimension of the special dimensions; 2. the associated start and end index of the model parameters; 3. and a boolean indicating whether the dimension is pooled (True) or heterogeneous (False).
The number of pooled dimensions.
The number of heterogeneous dimensions.

n_covariates(): Returns the number of covariates.

n_dim(): Returns the dimensionality of the population model.

n_hierarchical_dim()

Returns the number of parameter dimensions whose samples are not deterministically defined by the population parameters.

I.e. the number of dimensions minus the number of pooled and heterogeneously modelled dimensions.

n_hierarchical_parameters(n_ids)[source]

Returns a tuple of the number of individual parameters and the number of population parameters that this model expects in context of a HierarchicalLogLikelihood, when n_ids individuals are modelled.

Parameters:: n_ids – Number of individuals.

n_ids()

Returns the number of modelled individuals.

If the behaviour of the population model does not change with the number of modelled individuals 0 is returned.

n_parameters()[source]: Returns the number of parameters of the population model.

sample(parameters, covariates, n_samples=None, seed=None)[source]

Returns random samples from the population distribution.

The returned value is a NumPy array with shape (n_samples, n_dim).

Parameters:

parameters (np.ndarray of shape (p,) or (p_per_dim, n_dim)) – Parameters of the population model.
n_samples (int, optional) – Number of samples. If None, one sample is returned.
seed (int, optional) – A seed for the pseudo-random number generator.
covariates (List, np.ndarray of shape (n_cov,) or (n_samples, n_cov)) – Covariate values, specifying the sampled subpopulation.

set_covariate_names(names=None)[source]

Sets the names of the covariates.

Parameters:: names (List) – A list of parameter names. If None, covariate names are reset to defaults.

set_dim_names(names=None)[source]

Sets the names of the population model dimensions.

Setting the dimension names overwrites the parameter names of the covariate model.

Parameters:: names (List[str], optional) – A list of dimension names. If None, dimension names are reset to defaults.

set_n_ids(n_ids)

Sets the number of modelled individuals.

The behaviour of most population models is the same for any number of individuals, in which case n_ids is ignored. However, for some models, e.g. HeterogeneousModel the behaviour changes with n_ids.

Parameters:: n_ids (int) – Number of individuals.

set_parameter_names(names=None)[source]

Sets the names of the population model parameters.

Parameters:: names (List[str]) – A list with string-convertable entries of length n_parameters(). If None, parameter names are reset to defaults.

set_population_parameters(indices)[source]

Sets the parameters of the population model that are transformed by the covariate model.

Note that this influences the number of model parameters.

Parameters:: indices (List[Tuple[int, int]]) – A list of parameter indices [param index, dim index].

class chi.GaussianModel(n_dim=1, dim_names=None, centered=True)[source]

A population model which models parameters across individuals with a Gaussian distribution.

A Gaussian population model assumes that a model parameter \(\psi\) varies across individuals such that \(\psi\) is normally distributed in the population

\[p(\psi |\mu, \sigma) = \frac{1}{\sqrt{2\pi} \sigma} \exp\left(-\frac{(\psi - \mu )^2} {2 \sigma ^2}\right).\]

Here, \(\mu\) and \(\sigma ^2\) are the mean and variance of the Gaussian distribution.

Any observed individual with parameter \(\psi _i\) is assumed to be a realisation of the random variable \(\psi\).

If centered = False the parametrisation is non-centered, i.e.

\[\psi = \mu + \sigma \eta ,\]

where \(\eta\) models the inter-individual variability and is standard normally distributed.

Extends PopulationModel.

Parameters:

n_dim (int, optional) – The dimensionality of the population model.
dim_names (List[str], optional) – Optional names of the population dimensions.
centered (bool, optional) – Boolean flag indicating whether parametrisation is centered or non-centered.

compute_individual_parameters(parameters, eta, return_eta=False, *args, **kwargs)[source]

Returns the individual parameters.

If centered = True, the model does not transform the parameters and eta is returned.

If centered = False, the individual parameters are defined as

\[\psi = \mu + \sigma \eta,\]

where \(\mu\) and \(\sigma\) are the model parameters and \(\eta\) are the inter-individual fluctuations.

Parameters:

parameters (np.ndarray of shape (n_parameters,), (n_param_per_dim, n_dim) or (n_ids, n_param_per_dim, n_dim)) – Model parameters.
eta (np.ndarray of shape (n_ids * n_dim) or (n_ids, n_dim)) – Inter-individual fluctuations.
return_eta (boolean, optional) – A boolean flag indicating whether eta is returned regardless of whether the parametrisation is centered or not.

Return type:

np.ndarray of shape (n_ids, n_dim)

compute_log_likelihood(parameters, observations, *args, **kwargs)[source]

Returns the log-likelihood of the population model parameters.

If centered = False, the log-likelihood of the standard normal is returned. The contribution of the population parameters to the log-likelihood can be computed with the log-likelihood of the individual parameters, see chi.ErrorModel.

Parameters:

parameters (np.ndarray of shape (n_parameters,), (n_param_per_dim, n_dim) or (n_ids, n_param_per_dim, n_dim)) – Parameters of the population model.
observations (np.ndarray of shape (n_ids, n_dim)) – Individual model parameters.

Return type:

float

compute_pointwise_ll(parameters, observations, *args, **kwargs)

Returns the pointwise log-likelihood of the model parameters for each observation.

Parameters:

parameters (np.ndarray of shape (p, n_dim)) – Parameters of the population model.
observations (np.ndarray of shape (n, n_dim)) – “Observations” of the individuals. Typically refers to the values of a mechanistic model parameter for each individual.

Returns:

Log-likelihoods for each individual parameter for population parameters.

Return type:

np.ndarray of length (n, n_dim)

compute_sensitivities(parameters, observations, dlogp_dpsi=None, reduce=False, flattened=True, *args, **kwargs)[source]

Returns the log-likelihood of the population model parameters and its sensitivities to the population parameters as well as the observations.

The sensitivities of the bottom-level log-likelihoods with respect to the observations (bottom-level parameters) may be provided using dlogp_dpsi, in order to compute the sensitivities of the full hierarchical log-likelihood.

The log-likelihood and sensitivities are returned as a tuple (score, deta, dtheta).

Parameters:

parameters (np.ndarray of shape (n_parameters,), (n_param_per_dim, n_dim) or (n_ids, n_param_per_dim, n_dim)) – Parameters of the population model.
observations (np.ndarray of shape (n_ids, n_dim)) – Individual model parameters.
dlogp_dpsi (np.ndarray of shape (n_ids, n_dim), optional) – The sensitivities of the log-likelihood of the individual parameters.
reduce (bool, optional) – A boolean flag indicating whether the sensitivites are returned as an array of shape (n_hierarchical_parameters,). reduce is prioritised over flattened.
flattened (bool, optional) – Boolean flag that indicates whether the sensitivities w.r.t. the population parameters are returned as 1-dim. array. If False sensitivities are returned in shape (n_ids, n_param_per_dim, n_dim).

Return type:

Tuple[float, np.ndarray of shape (n_ids, n_dim), np.ndarray of shape (n_parameters,)]

get_covariate_names(): Returns the names of the covariates. If name is not set, defaults are returned.

get_dim_names(): Returns the names of the dimensions.

get_parameter_names(exclude_dim_names=False)[source]

Returns the name of the the population model parameters. If name were not set, defaults are returned.

Parameters:: exclude_dim_names (bool, optional) – A boolean flag that indicates whether the dimension name is appended to the parameter name.

get_special_dims()

Returns information on pooled and heterogeneously modelled dimensions.

Returns a tuple with 3 entries:

A list of lists, each entry containing 1. the start and end
dimension of the special dimensions; 2. the associated start and end index of the model parameters; 3. and a boolean indicating whether the dimension is pooled (True) or heterogeneous (False).
The number of pooled dimensions.
The number of heterogeneous dimensions.

n_covariates(): Returns the number of covariates.

n_dim(): Returns the dimensionality of the population model.

n_hierarchical_dim()

Returns the number of parameter dimensions whose samples are not deterministically defined by the population parameters.

I.e. the number of dimensions minus the number of pooled and heterogeneously modelled dimensions.

n_hierarchical_parameters(n_ids)[source]

Returns a tuple of the number of individual parameters and the number of population parameters that this model expects in context of a HierarchicalLogLikelihood, when n_ids individuals are modelled.

Parameters:: n_ids (int) – Number of individuals.

n_ids()

Returns the number of modelled individuals.

If the behaviour of the population model does not change with the number of modelled individuals 0 is returned.

n_parameters()[source]: Returns the number of parameters of the population model.

sample(parameters, n_samples=None, seed=None, *args, **kwargs)[source]

Returns random samples from the population distribution.

The returned value is a NumPy array with shape (n_samples, n_dim).

If centered = False random samples from the standard normal distribution are returned.

Parameters:

parameters (np.ndarray of shape (p,) or (p_per_dim, n_dim)) – Parameters of the population model.
n_samples (int, optional) – Number of samples. If None, one sample is returned.
seed (int, optional) – A seed for the pseudo-random number generator.

set_covariate_names(names=None)

Sets the names of the covariates.

If the model has no covariates, input is ignored.

Parameters:: names (List[str]) – A list of parameter names. If None, covariate names are reset to defaults.

set_dim_names(names=None)

Sets the names of the population model dimensions.

Parameters:: names (List[str], optional) – A list of dimension names. If None, dimension names are reset to defaults.

set_n_ids(n_ids)

Sets the number of modelled individuals.

The behaviour of most population models is the same for any number of individuals, in which case n_ids is ignored. However, for some models, e.g. HeterogeneousModel the behaviour changes with n_ids.

Parameters:: n_ids (int) – Number of individuals.

set_parameter_names(names=None)[source]

Sets the names of the population model parameters.

The population parameter of a GaussianModel are the population mean and standard deviation of the parameter \(\psi\).

Parameters:: names (List[str]) – A list with string-convertable entries of length n_parameters(). If None, parameter names are reset to defaults.

class chi.HeterogeneousModel(n_dim=1, dim_names=None, n_ids=1)[source]

A population model which imposes no relationship on the model parameters across individuals.

A heterogeneous model assumes that the parameters across individuals are independent.

Extends PopulationModel.

Note

Heterogeneous population models are special: the number of parameters depends on the number of modelled individuals.

Parameters:

n_dim (int, optional) – The dimensionality of the population model.
dim_names (List[str], optional) – Optional names of the population dimensions.
n_ids (int, optional) – Number of modelled individuals.

compute_individual_parameters(parameters, eta, return_eta=False, *args, **kwargs)[source]

Returns the individual parameters.

If the model does not transform the bottom-level parameters, eta is returned.

Parameters:

parameters (np.ndarray of shape (n_parameters,), (n_param_per_dim, n_dim) or (n_ids, n_param_per_dim, n_dim)) – Model parameters.
eta (np.ndarray of shape (n_ids, n_dim)) – Inter-individual fluctuations.
return_eta (boolean, optional) – A boolean flag indicating whether eta is returned regardless of whether the parametrisation is centered or not.

Return type:

np.ndarray of shape (n_ids, n_dim)

compute_log_likelihood(parameters, observations, *args, **kwargs)[source]

Returns the log-likelihood of the population model parameters.

A heterogenous population model is equivalent to a multi-dimensional delta-distribution, where each bottom-level parameter is determined by a separate delta-distribution.

Parameters:

parameters (np.ndarray of shape (n_parameters,), (n_param_per_dim, n_dim) or (n_ids, n_param_per_dim, n_dim)) – Parameters of the population model.
observations (np.ndarray of shape (n_ids, n_dim)) – Individual model parameters.

Return type:

float

compute_pointwise_ll(parameters, observations, *args, **kwargs)

Returns the pointwise log-likelihood of the model parameters for each observation.

Parameters:

parameters (np.ndarray of shape (p, n_dim)) – Parameters of the population model.
observations (np.ndarray of shape (n, n_dim)) – “Observations” of the individuals. Typically refers to the values of a mechanistic model parameter for each individual.

Returns:

Log-likelihoods for each individual parameter for population parameters.

Return type:

np.ndarray of length (n, n_dim)

compute_sensitivities(parameters, observations, dlogp_dpsi=None, reduce=False, flattened=True, *args, **kwargs)[source]

Returns the log-likelihood of the population parameters and its sensitivities w.r.t. the parameters and the observations.

The log-likelihood and sensitivities are returned as a tuple (score, deta, dtheta).

Parameters:

parameters (np.ndarray of shape (n_parameters,), (n_param_per_dim, n_dim) or (n_ids, n_param_per_dim, n_dim)) – Parameters of the population model.
observations (np.ndarray of shape (n_ids, n_dim)) – Individual model parameters.
dlogp_dpsi (np.ndarray of shape (n_ids, n_dim), optional) – The sensitivities of the log-likelihood of the individual parameters.
reduce (bool, optional) – A boolean flag indicating whether the sensitivites are returned as an array of shape (n_hierarchical_parameters,). reduce is prioritised over flattened.
flattened (bool, optional) – Boolean flag that indicates whether the sensitivities w.r.t. the population parameters are returned as 1-dim. array. If False sensitivities are returned in shape (n_ids, n_param_per_dim, n_dim).

Return type:

Tuple[float, np.ndarray of shape (n_ids, n_dim), np.ndarray of shape (n_parameters,)]

get_covariate_names(): Returns the names of the covariates. If name is not set, defaults are returned.

get_dim_names(): Returns the names of the dimensions.

get_parameter_names(exclude_dim_names=False)[source]

Returns the name of the the population model parameters. If name were not set, defaults are returned.

Parameters:: exclude_dim_names (bool, optional) – A boolean flag that indicates whether the dimension name is appended to the parameter name.

get_special_dims()

Returns information on pooled and heterogeneously modelled dimensions.

Returns a tuple with 3 entries:

A list of lists, each entry containing 1. the start and end
dimension of the special dimensions; 2. the associated start and end index of the model parameters; 3. and a boolean indicating whether the dimension is pooled (True) or heterogeneous (False).
The number of pooled dimensions.
The number of heterogeneous dimensions.

n_covariates(): Returns the number of covariates.

n_dim(): Returns the dimensionality of the population model.

n_hierarchical_dim()

Returns the number of parameter dimensions whose samples are not deterministically defined by the population parameters.

I.e. the number of dimensions minus the number of pooled and heterogeneously modelled dimensions.

n_hierarchical_parameters(n_ids)[source]

Returns a tuple of the number of individual parameters and the number of population parameters that this model expects in context of a HierarchicalLogLikelihood, when n_ids individuals are modelled.

Parameters:: n_ids (int) – Number of individuals.

n_ids()[source]

Returns the number of modelled individuals.

If the behaviour of the population model does not change with the number of modelled individuals 0 is returned.

n_parameters()[source]: Returns the number of parameters of the population model.

sample(parameters, n_samples=None, seed=None, *args, **kwargs)[source]

Returns random samples from the population distribution.

The returned value is a NumPy array with shape (n_samples, n_dim).

For n_samples > 1 the samples are randomly drawn from the n_ids individuals.

Parameters:

parameters (np.ndarray of shape (p,) or (p_per_dim, n_dim)) – Parameters of the population model.
n_samples (int, optional) – Number of samples. If None, one sample is returned.
seed (int, optional) – A seed for the pseudo-random number generator.

set_covariate_names(names=None)

Sets the names of the covariates.

If the model has no covariates, input is ignored.

Parameters:: names (List[str]) – A list of parameter names. If None, covariate names are reset to defaults.

set_dim_names(names=None)

Sets the names of the population model dimensions.

Parameters:: names (List[str], optional) – A list of dimension names. If None, dimension names are reset to defaults.

set_n_ids(n_ids, no_shortcut=False)[source]

Sets the number of modelled individuals.

The behaviour of most population models is the same for any number of individuals, in which case n_ids is ignored. However, for some models, e.g. HeterogeneousModel the behaviour changes with n_ids.

Parameters:

n_ids (int) – Number of individuals.
no_shortcut (bool, optional) – Boolean flag that prevents exiting the method early when n_ids are unchanged.

set_parameter_names(names=None)[source]

Sets the names of the population model parameters.

Parameters:: names (List[str]) – A list with string-convertable entries of length n_parameters(). If None, parameter names are reset to defaults.

class chi.LogNormalModel(n_dim=1, dim_names=None, centered=True)[source]

A population model which models parameters across individuals with a lognormal distribution.

A lognormal population model assumes that a model parameter \(\psi\) varies across individuals such that \(\psi\) is log-normally distributed in the population

\[p(\psi |\mu _{\text{log}}, \sigma _{\text{log}}) = \frac{1}{\psi} \frac{1}{\sqrt{2\pi} \sigma _{\text{log}}} \exp\left(-\frac{(\log \psi - \mu _{\text{log}})^2} {2 \sigma ^2_{\text{log}}}\right).\]

Here, \(\mu _{\text{log}}\) and \(\sigma ^2_{\text{log}}\) are the mean and variance of \(\log \psi\) in the population, respectively.

Any observed individual with parameter \(\psi _i\) is assumed to be a realisation of the random variable \(\psi\).

If centered = False the parametrisation is non-centered, i.e.

\[\log \psi = \mu _{\text{log}} + \sigma _{\text{log}} \eta ,\]

where \(\eta\) models the inter-individual variability and is standard normally distributed.

Extends PopulationModel.

Parameters:

n_dim (int, optional) – The dimensionality of the population model.
dim_names (List[str], optional) – Optional names of the population dimensions.
centered (bool, optional) – Boolean flag indicating whether parametrisation is centered or non-centered.

compute_individual_parameters(parameters, eta, return_eta=False, *args, **kwargs)[source]

Returns the individual parameters.

If centered = True, the model does not transform the parameters and eta is returned.

If centered = False, the individual parameters are computed using

\[\psi = \mathrm{e}^{ \mu _{\mathrm{log}} + \sigma _{\mathrm{log}} \eta},\]

where \(\mu _{\mathrm{log}}\) and \(\sigma _{\mathrm{log}}\) are the model parameters and \(\eta\) are the inter-individual fluctuations.

Parameters:

parameters (np.ndarray of shape (n_parameters,), (n_param_per_dim, n_dim) or (n_ids, n_param_per_dim, n_dim)) – Model parameters.
eta (np.ndarray of shape (n_ids * n_dim) or (n_ids, n_dim)) – Inter-individual fluctuations.
return_eta (boolean, optional) – A boolean flag indicating whether eta is returned regardless of whether the parametrisation is centered or not.

Return type:

np.ndarray of shape (n_ids, n_dim)

compute_log_likelihood(parameters, observations, *args, **kwargs)[source]

Returns the log-likelihood of the population model parameters.

If centered = False, the log-likelihood of the standard normal is returned. The contribution of the population parameters to the log-likelihood can be computed with the log-likelihood of the individual parameters, see chi.ErrorModel.

Parameters:

parameters (np.ndarray of shape (n_parameters,), (n_param_per_dim, n_dim) or (n_ids, n_param_per_dim, n_dim)) – Parameters of the population model.
observations (np.ndarray of shape (n_ids, n_dim)) – Individual model parameters.

Return type:

float

compute_pointwise_ll(parameters, observations, *args, **kwargs)

Returns the pointwise log-likelihood of the model parameters for each observation.

Parameters:

parameters (np.ndarray of shape (p, n_dim)) – Parameters of the population model.
observations (np.ndarray of shape (n, n_dim)) – “Observations” of the individuals. Typically refers to the values of a mechanistic model parameter for each individual.

Returns:

Log-likelihoods for each individual parameter for population parameters.

Return type:

np.ndarray of length (n, n_dim)

compute_sensitivities(parameters, observations, dlogp_dpsi=None, reduce=False, flattened=True, *args, **kwargs)[source]

Returns the log-likelihood of the population model parameters and its sensitivity to the population parameters as well as the observations.

The sensitivities of the bottom-level log-likelihoods with respect to the observations (bottom-level parameters) may be provided using dlogp_dpsi, in order to compute the sensitivities of the full hierarchical log-likelihood.

The log-likelihood and sensitivities are returned as a tuple (score, deta, dtheta).

Parameters:

parameters (np.ndarray of shape (n_parameters,), (n_param_per_dim, n_dim) or (n_ids, n_param_per_dim, n_dim)) – Parameters of the population model.
observations (np.ndarray of shape (n_ids, n_dim)) – Individual model parameters.
dlogp_dpsi (np.ndarray of shape (n_ids, n_dim), optional) – The sensitivities of the log-likelihood of the individual parameters.
reduce (bool, optional) – A boolean flag indicating whether the sensitivites are returned as an array of shape (n_hierarchical_parameters,). reduce is prioritised over flattened.
flattened (bool, optional) – Boolean flag that indicates whether the sensitivities w.r.t. the population parameters are returned as 1-dim. array. If False sensitivities are returned in shape (n_ids, n_param_per_dim, n_dim).

Return type:

Tuple[float, np.ndarray of shape (n_ids, n_dim), np.ndarray of shape (n_parameters,)]

get_covariate_names(): Returns the names of the covariates. If name is not set, defaults are returned.

get_dim_names(): Returns the names of the dimensions.

get_mean_and_std(parameters)[source]

Returns the mean and the standard deviation of the population for given \(\mu _{\text{log}}\) and \(\sigma _{\text{log}}\).

The mean and variance of the parameter \(\psi\), \(\mu = \mathbb{E}\left[ \psi \right]\) and \(\sigma ^2 = \text{Var}\left[ \psi \right]\), are given by

\[\mu = \mathrm{e}^{\mu _{\text{log}} + \sigma ^2_{\text{log}} / 2} \quad \text{and} \quad \sigma ^2 = \mu ^2 \left( \mathrm{e}^{\sigma ^2_{\text{log}}} - 1\right) .\]

Parameters:: parameters (np.ndarray of shape (p,) or (p_per_dim, n_dim)) – Parameters of the population model.

get_parameter_names(exclude_dim_names=False)[source]

Returns the name of the the population model parameters. If name were not set, defaults are returned.

Parameters:: exclude_dim_names (bool, optional) – A boolean flag that indicates whether the dimension name is appended to the parameter name.

get_special_dims()

Returns information on pooled and heterogeneously modelled dimensions.

Returns a tuple with 3 entries:

A list of lists, each entry containing 1. the start and end
dimension of the special dimensions; 2. the associated start and end index of the model parameters; 3. and a boolean indicating whether the dimension is pooled (True) or heterogeneous (False).
The number of pooled dimensions.
The number of heterogeneous dimensions.

n_covariates(): Returns the number of covariates.

n_dim(): Returns the dimensionality of the population model.

n_hierarchical_dim()

Returns the number of parameter dimensions whose samples are not deterministically defined by the population parameters.

I.e. the number of dimensions minus the number of pooled and heterogeneously modelled dimensions.

n_hierarchical_parameters(n_ids)[source]

Returns a tuple of the number of individual parameters and the number of population parameters that this model expects in context of a HierarchicalLogLikelihood, when n_ids individuals are modelled.

Parameters:: n_ids – Number of individuals.

n_ids()

Returns the number of modelled individuals.

If the behaviour of the population model does not change with the number of modelled individuals 0 is returned.

n_parameters()[source]: Returns the number of parameters of the population model.

sample(parameters, n_samples=None, seed=None, *args, **kwargs)[source]

Returns random samples from the population distribution.

The returned value is a NumPy array with shape (n_samples, n_dim).

If centered = False random samples from the standard normal distribution are returned.

Parameters:

parameters (np.ndarray of shape (p,) or (p_per_dim, n_dim)) – Parameters of the population model.
n_samples (int, optional) – Number of samples. If None, one sample is returned.
seed (int, optional) – A seed for the pseudo-random number generator.

set_covariate_names(names=None)

Sets the names of the covariates.

If the model has no covariates, input is ignored.

Parameters:: names (List[str]) – A list of parameter names. If None, covariate names are reset to defaults.

set_dim_names(names=None)

Sets the names of the population model dimensions.

Parameters:: names (List[str], optional) – A list of dimension names. If None, dimension names are reset to defaults.

set_n_ids(n_ids)

Sets the number of modelled individuals.

The behaviour of most population models is the same for any number of individuals, in which case n_ids is ignored. However, for some models, e.g. HeterogeneousModel the behaviour changes with n_ids.

Parameters:: n_ids (int) – Number of individuals.

set_parameter_names(names=None)[source]

Sets the names of the population model parameters.

The population parameter of a LogNormalModel are the population mean and standard deviation of the parameter \(\psi\).

Parameters:: names (List[str]) – A list with string-convertable entries of length n_parameters(). If None, parameter names are reset to defaults.

class chi.PooledModel(n_dim=1, dim_names=None)[source]

A population model which pools the model parameters across individuals.

A pooled model assumes that the parameters across individuals do not vary. As a result, all individual parameters are set to the same value.

Extends PopulationModel.

Parameters:

n_dim (int, optional) – The dimensionality of the population model.
dim_names (List[str], optional) – Optional names of the population dimensions.

compute_individual_parameters(parameters, eta, return_eta=False, *args, **kwargs)[source]

Returns the individual parameters.

If the model does not transform the bottom-level parameters, eta is returned.

Parameters:

parameters (np.ndarray of shape (n_parameters,), (n_param_per_dim, n_dim) or (n_ids, n_param_per_dim, n_dim)) – Model parameters.
eta (np.ndarray of shape (n_ids, n_dim)) – Inter-individual fluctuations.
return_eta (boolean, optional) – A boolean flag indicating whether eta is returned regardless of whether the parametrisation is centered or not.

Return type:

np.ndarray of shape (n_ids, n_dim)

compute_log_likelihood(parameters, observations, *args, **kwargs)[source]

Returns the log-likelihood of the population model parameters.

Parameters:

parameters (np.ndarray of shape (n_parameters,), (n_param_per_dim, n_dim) or (n_ids, n_param_per_dim, n_dim)) – Parameters of the population model.
observations (np.ndarray of shape (n_ids, n_dim)) – Individual model parameters.

Return type:

float

compute_pointwise_ll(parameters, observations)[source]

Returns the pointwise log-likelihood of the model parameters for each observation.

A pooled population model is a delta-distribution centred at the population model parameter. As a result the log-likelihood score is 0, if all individual parameters are equal to the population parameter, and \(-\infty\) otherwise.

Parameters:

parameters (np.ndarray of shape (p,) or (p_per_dim, n_dim)) – Parameters of the population model.
observations (np.ndarray of shape (n, n_dim)) – “Observations” of the individuals. Typically refers to the values of a mechanistic model parameter for each individual, i.e. [\(\psi _1, \ldots , \psi _N\)].

Returns:

Log-likelihoods for each individual parameter for population parameters.

Return type:

np.ndarray of length (n, n_dim)

compute_sensitivities(parameters, observations, dlogp_dpsi=None, reduce=False, flattened=True, *args, **kwargs)[source]

Returns the log-likelihood of the population model parameters and its sensitivity to the population parameters as well as the observations.

The log-likelihood and sensitivities are returned as a tuple (score, deta, dtheta).

Parameters:

parameters (np.ndarray of shape (n_parameters,), (n_param_per_dim, n_dim) or (n_ids, n_param_per_dim, n_dim)) – Parameters of the population model.
observations (np.ndarray of shape (n_ids, n_dim)) – Individual model parameters.
dlogp_dpsi (np.ndarray of shape (n_ids, n_dim), optional) – The sensitivities of the log-likelihood of the individual parameters.
reduce (bool, optional) – A boolean flag indicating whether the sensitivites are returned as an array of shape (n_hierarchical_parameters,). reduce is prioritised over flattened.
flattened (bool, optional) – Boolean flag that indicates whether the sensitivities w.r.t. the population parameters are returned as 1-dim. array. If False sensitivities are returned in shape (n_ids, n_param_per_dim, n_dim).

Return type:

Tuple[float, np.ndarray of shape (n_ids, n_dim), np.ndarray of shape (n_parameters,)]

get_covariate_names(): Returns the names of the covariates. If name is not set, defaults are returned.

get_dim_names(): Returns the names of the dimensions.

get_parameter_names(exclude_dim_names=False)[source]

Returns the name of the the population model parameters. If name were not set, defaults are returned.

Parameters:: exclude_dim_names (bool, optional) – A boolean flag that indicates whether the dimension name is appended to the parameter name.

get_special_dims()

Returns information on pooled and heterogeneously modelled dimensions.

Returns a tuple with 3 entries:

A list of lists, each entry containing 1. the start and end
dimension of the special dimensions; 2. the associated start and end index of the model parameters; 3. and a boolean indicating whether the dimension is pooled (True) or heterogeneous (False).
The number of pooled dimensions.
The number of heterogeneous dimensions.

n_covariates(): Returns the number of covariates.

n_dim(): Returns the dimensionality of the population model.

n_hierarchical_dim()

Returns the number of parameter dimensions whose samples are not deterministically defined by the population parameters.

I.e. the number of dimensions minus the number of pooled and heterogeneously modelled dimensions.

n_hierarchical_parameters(n_ids)[source]

Returns a tuple of the number of individual parameters and the number of population parameters that this model expects in context of a HierarchicalLogLikelihood, when n_ids individuals are modelled.

Parameters:: n_ids (int) – Number of individuals.

n_ids()

Returns the number of modelled individuals.

If the behaviour of the population model does not change with the number of modelled individuals 0 is returned.

n_parameters()[source]: Returns the number of parameters of the population model.

sample(parameters, n_samples=None, *args, **kwargs)[source]

Returns random samples from the underlying population distribution.

For a PooledModel the input top-level parameters are copied n_samples times and are returned.

The returned value is a NumPy array with shape (n_samples, n_dim).

Parameters:

parameters (np.ndarray of shape (p,) or (p_per_dim, n_dim)) – Parameters of the population model.
n_samples (int, optional) – Number of samples. If None, one sample is returned.
seed (int, optional) – A seed for the pseudo-random number generator.

set_covariate_names(names=None)

Sets the names of the covariates.

If the model has no covariates, input is ignored.

Parameters:: names (List[str]) – A list of parameter names. If None, covariate names are reset to defaults.

set_dim_names(names=None)

Sets the names of the population model dimensions.

Parameters:: names (List[str], optional) – A list of dimension names. If None, dimension names are reset to defaults.

set_n_ids(n_ids)

Sets the number of modelled individuals.

The behaviour of most population models is the same for any number of individuals, in which case n_ids is ignored. However, for some models, e.g. HeterogeneousModel the behaviour changes with n_ids.

Parameters:: n_ids (int) – Number of individuals.

set_parameter_names(names=None)[source]

Sets the names of the population model parameters.

Parameters:: names (List[str]) – A list with string-convertable entries of length n_parameters(). If None, parameter names are reset to defaults.

class chi.TruncatedGaussianModel(n_dim=1, dim_names=None)[source]

A population model which models model parameters across individuals as Gaussian random variables which are truncated at zero.

A truncated Gaussian population model assumes that a model parameter \(\psi\) varies across individuals such that \(\psi\) is Gaussian distributed in the population for \(\psi\) greater 0

\[p(\psi |\mu, \sigma) = \frac{1}{1 - \Phi (-\mu / \sigma )} \frac{1}{\sqrt{2\pi} \sigma} \exp\left(-\frac{(\psi - \mu )^2} {2 \sigma ^2}\right)\quad \text{for} \quad \psi > 0\]

and \(p(\psi |\mu, \sigma) = 0\) for \(\psi \leq 0\). \(\Phi (\psi )\) denotes the cumulative distribution function of the Gaussian distribution.

Here, \(\mu\) and \(\sigma ^2\) are the mean and variance of the untruncated Gaussian distribution.

Any observed individual with parameter \(\psi _i\) is assumed to be a realisation of the random variable \(\psi\).

Extends PopulationModel.

Parameters:

n_dim (int, optional) – The dimensionality of the population model.
dim_names (List[str], optional) – Optional names of the population dimensions.

compute_individual_parameters(parameters, eta, return_eta=False, *args, **kwargs)

Returns the individual parameters.

If the model does not transform the bottom-level parameters, eta is returned.

Parameters:

parameters (np.ndarray of shape (n_parameters,), (n_param_per_dim, n_dim) or (n_ids, n_param_per_dim, n_dim)) – Model parameters.
eta (np.ndarray of shape (n_ids * n_dim) or (n_ids, n_dim)) – Inter-individual fluctuations.
return_eta (boolean, optional) – A boolean flag indicating whether eta is returned regardless of whether the parametrisation is centered or not.

Return type:

np.ndarray of shape (n_ids, n_dim)

compute_log_likelihood(parameters, observations, *args, **kwargs)[source]

Returns the log-likelihood of the population model parameters.

Parameters:

parameters (np.ndarray of shape (n_parameters,), (n_param_per_dim, n_dim) or (n_ids, n_param_per_dim, n_dim)) – Parameters of the population model.
observations (np.ndarray of shape (n_ids, n_dim)) – Individual model parameters.

Return type:

float

compute_pointwise_ll(parameters, observations, *args, **kwargs)

Returns the pointwise log-likelihood of the model parameters for each observation.

Parameters:

parameters (np.ndarray of shape (p, n_dim)) – Parameters of the population model.
observations (np.ndarray of shape (n, n_dim)) – “Observations” of the individuals. Typically refers to the values of a mechanistic model parameter for each individual.

Returns:

Log-likelihoods for each individual parameter for population parameters.

Return type:

np.ndarray of length (n, n_dim)

compute_sensitivities(parameters, observations, dlogp_dpsi=None, reduce=False, flattened=True, *args, **kwargs)[source]

Returns the log-likelihood of the population model parameters and its sensitivity to the population parameters as well as the observations.

The sensitivities of the bottom-level log-likelihoods with respect to the observations (bottom-level parameters) may be provided using dlogp_dpsi, in order to compute the sensitivities of the full hierarchical log-likelihood.

The log-likelihood and sensitivities are returned as a tuple (score, deta, dtheta).

Parameters:

parameters (np.ndarray of shape (n_parameters,), (n_param_per_dim, n_dim) or (n_ids, n_param_per_dim, n_dim)) – Parameters of the population model.
observations (np.ndarray of shape (n_ids, n_dim)) – Individual model parameters.
dlogp_dpsi (np.ndarray of shape (n_ids, n_dim), optional) – The sensitivities of the log-likelihood of the individual parameters with respect to the individual parameters.
reduce (bool, optional) – A boolean flag indicating whether the sensitivites are returned as an array of shape (n_hierarchical_parameters,). reduce is prioritised over flattened.
flattened (bool, optional) – Boolean flag that indicates whether the sensitivities w.r.t. the population parameters are returned as 1-dim. array. If False sensitivities are returned in shape (n_ids, n_param_per_dim, n_dim).

Return type:

Tuple[float, np.ndarray of shape (n_ids, n_dim), np.ndarray of shape (n_parameters,)]

get_covariate_names(): Returns the names of the covariates. If name is not set, defaults are returned.

get_dim_names(): Returns the names of the dimensions.

get_mean_and_std(parameters)[source]

Returns the mean and the standard deviation of the population for given \(\mu\) and \(\sigma\).

The mean and variance of the parameter \(\psi\) are given by

\[\mathbb{E}\left[ \psi \right] = \mu + \sigma F(\mu/\sigma) \quad \text{and} \quad \text{Var}\left[ \psi \right] = \sigma ^2 \left[ 1 - \frac{\mu}{\sigma}F(\mu/\sigma) - F(\mu/\sigma) ^2 \right],\]

where \(F(\mu/\sigma) = \phi(\mu/\sigma )/(1-\Phi(-\mu/\sigma))\) is a function given by the Gaussian probability density function \(\phi(\psi)\) and the Gaussian cumulative distribution function \(\Phi(\psi)\).

Parameters:: parameters (np.ndarray of shape (p,) or (p_per_dim, n_dim)) – Parameters of the population model.
Return type:: np.ndarray of shape (p_per_dim, n_dim)

get_parameter_names(exclude_dim_names=False)[source]

Returns the name of the the population model parameters. If name were not set, defaults are returned.

Parameters:: exclude_dim_names (bool, optional) – A boolean flag that indicates whether the dimension name is appended to the parameter name.

get_special_dims()

Returns information on pooled and heterogeneously modelled dimensions.

Returns a tuple with 3 entries:

A list of lists, each entry containing 1. the start and end
dimension of the special dimensions; 2. the associated start and end index of the model parameters; 3. and a boolean indicating whether the dimension is pooled (True) or heterogeneous (False).
The number of pooled dimensions.
The number of heterogeneous dimensions.

n_covariates(): Returns the number of covariates.

n_dim(): Returns the dimensionality of the population model.

n_hierarchical_dim()

Returns the number of parameter dimensions whose samples are not deterministically defined by the population parameters.

I.e. the number of dimensions minus the number of pooled and heterogeneously modelled dimensions.

n_hierarchical_parameters(n_ids)[source]

Returns a tuple of the number of individual parameters and the number of population parameters that this model expects in context of a HierarchicalLogLikelihood, when n_ids individuals are modelled.

Parameters:: n_ids (int) – Number of individuals.

n_ids()

Returns the number of modelled individuals.

If the behaviour of the population model does not change with the number of modelled individuals 0 is returned.

n_parameters()[source]: Returns the number of parameters of the population model.

sample(parameters, n_samples=None, seed=None, *args, **kwargs)[source]

Returns random samples from the population distribution.

The returned value is a NumPy array with shape (n_samples, n_dim).

If centered = False random samples from the standard normal distribution are returned.

Parameters:

parameters (np.ndarray of shape (p,) or (p_per_dim, n_dim)) – Parameters of the population model.
n_samples (int, optional) – Number of samples. If None, one sample is returned.
seed (int, optional) – A seed for the pseudo-random number generator.

set_covariate_names(names=None)

Sets the names of the covariates.

If the model has no covariates, input is ignored.

Parameters:: names (List[str]) – A list of parameter names. If None, covariate names are reset to defaults.

set_dim_names(names=None)

Sets the names of the population model dimensions.

Parameters:: names (List[str], optional) – A list of dimension names. If None, dimension names are reset to defaults.

set_n_ids(n_ids)

Sets the number of modelled individuals.

The behaviour of most population models is the same for any number of individuals, in which case n_ids is ignored. However, for some models, e.g. HeterogeneousModel the behaviour changes with n_ids.

Parameters:: n_ids (int) – Number of individuals.

set_parameter_names(names=None)[source]

Sets the names of the population model parameters.

Parameters:: names (List[str]) – A list of parameter names. If None, parameter names are reset to defaults.

Detailed API

class chi.PopulationModel(n_dim=1, dim_names=None)[source]

A base class for population models.

Population models can be multi-dimensional, but unless explicitly specfied in the model description, the dimensions of the model are modelled independently.

Parameters:

n_dim (int, optional) – The dimensionality of the population model.
dim_names (List[str], optional) – Optional names of the population dimensions.

compute_individual_parameters(parameters, eta, return_eta=False, *args, **kwargs)[source]

Returns the individual parameters.

If the model does not transform the bottom-level parameters, eta is returned.

Parameters:

parameters (np.ndarray of shape (n_parameters,), (n_param_per_dim, n_dim) or (n_ids, n_param_per_dim, n_dim)) – Model parameters.
eta (np.ndarray of shape (n_ids * n_dim) or (n_ids, n_dim)) – Inter-individual fluctuations.
return_eta (boolean, optional) – A boolean flag indicating whether eta is returned regardless of whether the parametrisation is centered or not.

Return type:

np.ndarray of shape (n_ids, n_dim)

compute_log_likelihood(parameters, observations, *args, **kwargs)[source]

Returns the log-likelihood of the population model parameters.

Parameters:

parameters (np.ndarray of shape (n_parameters,), (n_param_per_dim, n_dim) or (n_ids, n_param_per_dim, n_dim)) – Parameters of the population model.
observations (np.ndarray of shape (n_ids, n_dim)) – Individual model parameters.

Return type:

float

compute_pointwise_ll(parameters, observations, *args, **kwargs)[source]

Returns the pointwise log-likelihood of the model parameters for each observation.

Parameters:

parameters (np.ndarray of shape (p, n_dim)) – Parameters of the population model.
observations (np.ndarray of shape (n, n_dim)) – “Observations” of the individuals. Typically refers to the values of a mechanistic model parameter for each individual.

Returns:

Log-likelihoods for each individual parameter for population parameters.

Return type:

np.ndarray of length (n, n_dim)

compute_sensitivities(parameters, observations, dlogp_dpsi=None, reduce=False, *args, **kwargs)[source]

Returns the log-likelihood of the population model parameters and its sensitivity to the population parameters as well as the observations.

The sensitivities of the bottom-level log-likelihoods with respect to the observations (bottom-level parameters) may be provided using dlogp_dpsi, in order to compute the sensitivities of the full hierarchical log-likelihood.

The log-likelihood and sensitivities are returned as a tuple (score, deta, dtheta).

Parameters:

parameters (np.ndarray of shape (n_parameters,), (n_param_per_dim, n_dim) or (n_ids, n_param_per_dim, n_dim)) – Parameters of the population model.
observations (np.ndarray of shape (n_ids, n_dim)) – Individual model parameters.
dlogp_dpsi (np.ndarray of shape (n_ids, n_dim), optional) – The sensitivities of the log-likelihood of the individual parameters with respect to the individual parameters.
reduce (bool, optional) – A boolean flag indicating whether the sensitivites are returned as an array of shape (n_hierarchical_parameters,).

Return type:

Tuple[float, np.ndarray of shape (n_ids, n_dim), np.ndarray of shape (n_parameters,)]

get_covariate_names()[source]: Returns the names of the covariates. If name is not set, defaults are returned.

get_dim_names()[source]: Returns the names of the dimensions.

get_parameter_names(exclude_dim_names=False)[source]

Returns the names of the population model parameters. If name is not set, defaults are returned.

Parameters:: exclude_dim_names (bool, optional) – A boolean flag that indicates whether the dimension name is appended to the parameter name.

get_special_dims()[source]

Returns information on pooled and heterogeneously modelled dimensions.

Returns a tuple with 3 entries:

A list of lists, each entry containing 1. the start and end
dimension of the special dimensions; 2. the associated start and end index of the model parameters; 3. and a boolean indicating whether the dimension is pooled (True) or heterogeneous (False).
The number of pooled dimensions.
The number of heterogeneous dimensions.

n_covariates()[source]: Returns the number of covariates.

n_dim()[source]: Returns the dimensionality of the population model.

n_hierarchical_dim()[source]

Returns the number of parameter dimensions whose samples are not deterministically defined by the population parameters.

I.e. the number of dimensions minus the number of pooled and heterogeneously modelled dimensions.

n_hierarchical_parameters(n_ids)[source]

Returns a tuple of the number of individual parameters and the number of population parameters that this model expects in context of a HierarchicalLogLikelihood, when n_ids individuals are modelled.

Parameters:: n_ids (int) – Number of individuals.

n_ids()[source]

Returns the number of modelled individuals.

If the behaviour of the population model does not change with the number of modelled individuals 0 is returned.

n_parameters()[source]: Returns the number of parameters of the population model.

sample(parameters, n_samples=None, seed=None, *args, **kwargs)[source]

Returns random samples from the population distribution.

The returned value is a NumPy array with shape (n_samples, n_dim).

Parameters:

parameters (np.ndarray of shape (p,) or (p_per_dim, n_dim)) – Parameters of the population model.
n_samples (int, optional) – Number of samples. If None, one sample is returned.
seed (int, optional) – A seed for the pseudo-random number generator.

set_covariate_names(names=None)[source]

Sets the names of the covariates.

If the model has no covariates, input is ignored.

Parameters:: names (List[str]) – A list of parameter names. If None, covariate names are reset to defaults.

set_dim_names(names=None)[source]

Sets the names of the population model dimensions.

Parameters:: names (List[str], optional) – A list of dimension names. If None, dimension names are reset to defaults.

set_n_ids(n_ids)[source]

Sets the number of modelled individuals.

The behaviour of most population models is the same for any number of individuals, in which case n_ids is ignored. However, for some models, e.g. HeterogeneousModel the behaviour changes with n_ids.

Parameters:: n_ids (int) – Number of individuals.

set_parameter_names(names=None)[source]

Sets the names of the population model parameters.

Parameters:: names (List[str]) – A list of parameter names. If None, parameter names are reset to defaults.

class chi.ReducedPopulationModel(population_model)[source]

A class that can be used to permanently fix model parameters of a PopulationModel instance.

This may be useful to explore simplified versions of a model.

Extends chi.PopulationModel.

Parameters:: population_model (chi.PopulationModel) – A population model.

compute_individual_parameters(parameters, eta, *args, **kwargs)[source]

Returns the individual parameters.

If the model does not transform the bottom-level parameters, eta is returned.

Parameters:

parameters (np.ndarray of shape (n_parameters,), (n_param_per_dim, n_dim) or (n_ids, n_param_per_dim, n_dim)) – Model parameters.
eta (np.ndarray of shape (n_ids, n_dim)) – Inter-individual fluctuations.

Return type:

np.ndarray of shape (n_ids, n_dim)

compute_log_likelihood(parameters, observations, *args, **kwargs)[source]

Returns the log-likelihood of the population model parameters.

Parameters:

parameters (np.ndarray of shape (n_parameters,) or (n_param_per_dim, n_dim)) – Parameters of the population model.
observations (np.ndarray of shape (n_ids, n_dim)) – Individual model parameters.

Return type:

float

compute_sensitivities(parameters, observations, dlogp_dpsi=None, reduce=False, **kwargs)[source]

Returns the log-likelihood of the population model parameters and its sensitivity to the population parameters as well as the observations.

The sensitivities of the bottom-level log-likelihoods with respect to the observations (bottom-level parameters) may be provided using dlogp_dpsi, in order to compute the sensitivities of the full hierarchical log-likelihood.

The log-likelihood and sensitivities are returned as a tuple (score, deta, dtheta).

Parameters:

parameters (np.ndarray of shape (n_parameters,) or (n_param_per_dim, n_dim)) – Parameters of the population model.
observations (np.ndarray of shape (n_ids, n_dim)) – Individual model parameters.
dlogp_dpsi (np.ndarray of shape (n_ids, n_dim), optional) – The sensitivities of the log-likelihood of the individual parameters with respect to the individual parameters.
reduce (bool, optional) – A boolean flag indicating whether the sensitivites are returned as an array of shape (n_hierarchical_parameters,). reduce is prioritised over flattened.

Return type:

Tuple[float, np.ndarray of shape (n_ids, n_dim), np.ndarray of shape (n_parameters,)]

fix_parameters(name_value_dict)[source]

Fixes the value of model parameters, and effectively removes them as a parameter from the model. Fixing the value of a parameter at None, sets the parameter free again.

Parameters:: name_value_dict (Dict[str:float]) – A dictionary with model parameter names as keys, and parameter values as values.

get_covariate_names()[source]: Returns the names of the covariates. If name is not set, defaults are returned.

get_dim_names()[source]: Returns the names of the dimensions.

get_parameter_names(exclude_dim_names=False)[source]: Returns the name of the the population model parameters. If name were not set, defaults are returned.

get_population_model()[source]: Returns the original population model.

get_special_dims()[source]

Returns information on pooled and heterogeneously modelled dimensions.

Returns a tuple with 3 entries:

A list of lists, each entry containing 1. the start and end
dimension of the special dimensions; 2. the associated start and end index of the model parameters; 3. and a boolean indicating whether the dimension is pooled (True) or heterogeneous (False).
The number of pooled dimensions.
The number of heterogeneous dimensions.

n_fixed_parameters()[source]: Returns the number of fixed model parameters.

n_hierarchical_parameters(n_ids)[source]

Returns a tuple of the number of individual parameters and the number of population parameters that this model expects in context of a HierarchicalLogLikelihood, when n_ids individuals are modelled.

Parameters:: n_ids – Number of individuals.

n_parameters()[source]: Returns the number of parameters of the population model.

sample(parameters, n_samples=None, seed=None, *args, **kwargs)[source]

Returns random samples from the population distribution.

The returned value is a NumPy array with shape (n_samples, n_dim).

Parameters:

parameters (np.ndarray of shape (p,) or (p_per_dim, n_dim)) – Parameters of the population model.
n_samples (int, optional) – Number of samples. If None, one sample is returned.
seed (int, optional) – A seed for the pseudo-random number generator.

set_covariate_names(names=None)[source]

Sets the names of the covariates.

If the model has no covariates, input is ignored.

Parameters:: names (List) – A list of parameter names. If None, covariate names are reset to defaults.

set_dim_names(names=None)[source]

Sets the names of the population model dimensions.

Parameters:: names (List[str], optional) – A list of dimension names. If None, dimension names are reset to defaults.

set_n_ids(n_ids)[source]

Sets the number of modelled individuals.

The behaviour of most population models is the same for any number of individuals, in which case n_ids is ignored. However, for some models, e.g. HeterogeneousModel the behaviour changes with n_ids.

Parameters:: n_ids (int) – Number of individuals.

set_parameter_names(names=None)[source]

Sets the names of the population model parameters.

Parameters:: names – A dictionary that maps the current parameter names to new names. If None, parameter names are reset to defaults.