Problems

To simplify the process of builiding a log-posterior, which models either individuals separately or as a population, the ProblemModellingController has been implemented.

Classes

• ProblemModellingController

Detailed API

class chi.ProblemModellingController(mechanistic_model, error_models, outputs=None)

A problem modelling controller which simplifies the model building process of a pharmacokinetic and pharmacodynamic problem.

The class is instantiated with an instance of a MechanisticModel and one instance of an ErrorModel for each mechanistic model output.

Parameters:

• mechanistic_model (MechanisticModel) – A mechanistic model for the problem.

• error_models (list[ErrorModel]) – A list of error models. One error model has to be provided for each mechanistic model output.

• outputs (list[str], optional) – A list of mechanistic model output names, which can be used to map the error models to mechanistic model outputs. If None, the error models are assumed to be ordered in the same order as MechanisticModel.outputs().

fix_parameters(name_value_dict)

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

Note

1. Fixing model parameters resets the log-prior to None.

2. Once a population model is set, only population model parameters can be fixed.

3. Setting data resets all population parameters as the number of parameters may change with the number of modelled individuals.

Parameters:

name_value_dict (dict) – A dictionary with model parameters as keys, and the value to be fixed at as values.

get_covariate_names()

Returns the names of the covariates.

get_dosing_regimens()

Returns a dictionary of dosing regimens in form of myokit.Protocol instances.

The dosing regimens are extracted from the dataset if a dose key is provided. If no dose key is provided None is returned.

get_log_posterior(individual=None)

Returns the LogPosterior defined by the measurements of the modelled observables, the administered dosing regimen, the mechanistic model, the error model, the log-prior, and optionally the population model, covariates and the fixed model parameters.

If measurements of multiple individuals exist in the dataset, the indiviudals ID can be passed to return the log-posterior associated to that individual. If no ID is selected and no population model has been set, a list of log-posteriors is returned corresponding to each of the individuals.

This method raises an error if the data or the log-prior have not been set. See set_data() and set_log_prior().

Parameters:

individual (str, optional) – The ID of an individual. If None the log-posteriors for all individuals is returned. Input is ignored if a population model is set.

get_log_prior()

Returns the LogPrior for the model parameters. If no log-prior is set, None is returned.

get_n_parameters(exclude_pop_model=False)

Returns the number of the model parameters, i.e. the combined number of parameters from the mechanistic model and the error model when no population model has been set, or the number of population model parameters when a population model has been set.

Any parameters that have been fixed to a constant value will not be included in the number of model parameters.

Parameters:

exclude_pop_model (bool, optional) – A boolean flag to indicate whether the population model should be ignored (if set).

get_parameter_names(exclude_pop_model=False)

Returns the names of the model parameters, i.e. the combined names of the mechanistic model parameters and the error model parameters when no population model has been set, or the names of population model parameters when a population model has been set.

Any parameters that have been fixed to a constant value will not be included.

Parameters:

exclude_pop_model (bool, optional) – A boolean flag to indicate whether the population model should be ignored (if set).

get_predictive_model()

Returns a PredictiveModel defined by the mechanistic model, the error model, and optionally the population model and the fixed model parameters.

set_data(data, output_observable_dict=None, covariate_dict=None, id_key='ID', time_key='Time', obs_key='Observable', value_key='Value', dose_key='Dose', dose_duration_key='Duration')

Sets the data of the modelling problem.

The data contains information about the measurement time points, the measured values of the observables, the observable name, IDs to identify the corresponding individuals, and optionally information on the administered dose amount and duration.

The data is expected to be in form of a pandas.DataFrame with the columns ID | Time | Observable | Value | Dose | Duration.

If no information exists, the corresponding column keys can be set to None.

Note

Time-dependent covariates are currently not supported. Thus, the Time column of observables that are used as covariates is ignored.

Parameters:

• data (pandas.DataFrame) – A dataframe with an ID, time, observable, value and optionally a dose and duration column.

• output_observable_dict (dict, optional) – A dictionary with mechanistic model output names as keys and dataframe observable names as values. If None the model outputs and observables are assumed to have the same names.

• covariate_dict (dict, optional) – A dictionary with population model covariate names as keys and dataframe observables as values. If None the model covariates and observables are assumed to have the same names.

• id_key (str, optional) – The key of the ID column in the pandas.DataFrame. Default is 'ID'.

• time_key (str, optional) – The key of the time column in the pandas.DataFrame. Default is 'Time'.

• obs_key (str, optional) – The key of the observable column in the pandas.DataFrame. Default is 'Observable'.

• value_key (str, optional) – The key of the value column in the pandas.DataFrame. Default is 'Value'.

• dose_key (str, optional) – The key of the dose column in the pandas.DataFrame. Default is 'Dose'.

• dose_duration_key (str, optional) – The key of the duration column in the pandas.DataFrame. Default is 'Duration'.

set_log_prior(log_prior)

Sets the prior distribution of the model parameters.

The log-prior dimensions are assumed to be ordered according to get_parameter_names().

Note

This method requires that the data has been set, since the number of parameters of an hierarchical model may vary with the number of individuals in the dataset (see e.g. HeterogeneousModel).

Parameters:

log_prior – A pints.LogPrior of the length get_n_parameters().

set_population_model(population_model)

Sets the population model.

A population model specifies how model parameters vary across individuals. The dimension of the population model has to match the number of model parameters.

Note

Setting a population model resets the log-prior to None, because it changes the top-level parameters of the model.

Parameters:

population_model (PopulationModel) – A PopulationModel whose dimension is the same as the number of bottom-level parameters.