Covariate Models

Covariate models in chi can be used to construct complex population structures that depend on characteristics of individuals or subpopulations, i.e. covariates of the inter-individual variability. Simple population models from Population Models are used to describe the variability within a subpopulation, while covariate models are used to describe the cross-subpopulation variability.

Classes

• LinearCovariateModel

Detailed API

class chi.LinearCovariateModel(n_cov=1, cov_names=None)

A linear covariate model.

A linear covariate model transforms the parameters of the population model \(\vartheta\) linearly in the covariates

\[\vartheta (\theta, \chi ) = \vartheta _{0} + \sum _c \beta _c \, \chi _c,\]

where \(\chi = \{ \chi _c\}\) are the covariates, \(\vartheta _0\) are the original parameters of the population model, and \(\theta = (\vartheta _0, \beta)\) are the new population model parameters.

By default, only the first population parameter is transformed. The parameters can be selected with set_population_parameters().

Extends CovariateModel.

Parameters:

• n_cov (int, optional) – Number of covariates.

• cov_names (List[str], optional) – Names of the covariates.

compute_population_parameters(parameters, pop_parameters, covariates)

Returns the transformed population model parameters.

Parameters:

• parameters (np.ndarray of shape (n_parameters,) or (n_selected, n_cov)) – Model parameters.

• pop_parameters (np.ndarray of shape (n_pop_params_per_dim, n_dim)) – Population model parameters.

• covariates (np.ndarray of shape (n_ids, n_cov)) – Covariates of individuals.

Return type:

np.ndarray of shape (n_ids, n_pop_params_per_dim, n_dim)

compute_sensitivities(parameters, pop_parameters, covariates, dlogp_dvartheta)

Returns the sensitivities of the likelihood with respect to the model parameters and the population model parameters.

Parameters:

• parameters (np.ndarray of shape (n_parameters,) or (n_selected, n_cov)) – Model parameters.

• pop_parameters (np.ndarray of shape (n_pop_params_per_dim, n_dim)) – Population model parameters.

• covariates (np.ndarray of shape (n_ids, n_cov)) – Covariates of individuals.

• dlogp_dvartheta (np.ndarray of shape (n_ids, n_param_per_dim, n_dim)) – Unflattened sensitivities of the population model to the transformed parameters.

Return type:

Tuple[np.ndarray of shape (n_pop_params,), np.ndarray of shape (n_parameters,)]

get_covariate_names()

Returns the names of the covariates.

get_parameter_names(exclude_cov_names=False)

Returns the names of the model parameters.

Parameters:

exclude_cov_names (bool, optional) – A boolean flag that indicates whether the covariate name is appended to the parameter name.

get_set_population_parameters()

Returns the indices of the population parameters that are transformed.

Indices are returned as a tuple of arrays, where the first array are parameters indices and the second array are the dimension indicies.

Return type:

Tuple[np.ndarray of shape (n_selected,), np.ndarray of shape (n_selected,)]

n_covariates()

Returns the number of covariates c.

n_parameters()

Returns the number of model parameters p.

set_covariate_names(names=None)

Sets the names of the covariates.

Parameters:

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

set_parameter_names(names=None, mask_names=False)

Sets the names of the model parameters.

Parameters:

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

set_population_parameters(indices)

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

Note that this influences the number of model parameters.

Warning

Whether or not the indices are out of bounds cannot be checked at this point. It is assumed that for any future call which requires pop_parameters, the selected indices are compatible with the input.

Parameters:

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

Base classes

• CovariateModel

Detailed API

class chi.CovariateModel(n_cov=1, cov_names=None)

A base class for covariate models.

Covariate models model parameters of population models as functions of covariates

\[\vartheta = \vartheta(\theta, \chi),\]

where \(\vartheta\) are the parameters of a chi.PopulationModel, \(\chi\) are the covariates and \(\theta\) are the new parameters that govern the inter-individual variability of the population.

This allows you to distinguish subpopulations in the population

\[p(\psi | \theta) = \int \mathrm{d}\chi \, p(\psi | \vartheta(\theta, \chi) )\, p(\chi),\]

where \(p(\chi)\) is the distribution of the covariates in the population (for discrete covariates the integrals becomes a sum). Each subpopulation is characterised by a unique set of covariates.

By default, only the first population parameter is transformed. The parameters to transform can be selected with set_population_parameters().

Parameters:

• n_cov (int, optional) – Number of covariates.

• cov_names (List[str], optional) – Names of the covariates.

compute_population_parameters(parameters)

Returns the transformed population model parameters.

Parameters:

• parameters (np.ndarray of shape (n_parameters,) or (n_selected, n_cov)) – Model parameters.

• pop_parameters (np.ndarray of shape (n_pop_params_per_dim, n_dim)) – Population model parameters.

• covariates (np.ndarray of shape (n_ids, n_cov)) – Covariates of individuals.

Return type:

np.ndarray of shape (n_ids, n_pop_params_per_dim, n_dim)

compute_sensitivities(parameters, pop_parameters, covariates, dlogp_dvartheta)

Returns the sensitivities of the likelihood with respect to the model parameters and the population model parameters.

Parameters:

• parameters (np.ndarray of shape (n_parameters,) or (n_selected, n_cov)) – Model parameters.

• pop_parameters (np.ndarray of shape (n_pop_params_per_dim, n_dim)) – Population model parameters.

• covariates (np.ndarray of shape (n_ids, n_cov)) – Covariates of individuals.

• dlogp_dvartheta (np.ndarray of shape (n_ids, n_param_per_dim, n_dim)) – Unflattened sensitivities of the population model to the transformed parameters.

Return type:

Tuple[np.ndarray of shape (n_pop_params,), np.ndarray of shape (n_parameters,)]

get_covariate_names()

Returns the names of the covariates.

get_parameter_names(exclude_cov_names=False)

Returns the names of the model parameters.

Parameters:

exclude_cov_names (bool, optional) – A boolean flag that indicates whether the covariate name is appended to the parameter name.

get_set_population_parameters()

Returns the indices of the population parameters that are transformed.

Indices are returned as a tuple of arrays, where the first array are parameters indices and the second array are the dimension indicies.

Return type:

Tuple[np.ndarray of shape (n_selected,), np.ndarray of shape (n_selected,)]

n_covariates()

Returns the number of covariates c.

n_parameters()

Returns the number of model parameters p.

set_covariate_names(names=None)

Sets the names of the covariates.

Parameters:

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

set_parameter_names(names=None, mask_names=False)

Sets the names of the model parameters.

Parameters:

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

set_population_parameters(indices)

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

Note that this influences the number of model parameters.

Warning

Whether or not the indices are out of bounds cannot be checked at this point. It is assumed that for any future call which requires pop_parameters, the selected indices are compatible with the input.

Parameters:

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