Predictive Models

Predictive models in chi can be used to model data-generating processes and generate synthetic measurements.

Each predictive model consists of a MechanisticModel and an ErrorModel.

Classes

• PAMPredictiveModel

• PopulationPredictiveModel

• PosteriorPredictiveModel

• PredictiveModel

• PriorPredictiveModel

Detailed API

class chi.PAMPredictiveModel(predictive_models, weights)

A model that is defined by the probabilistic average of posterior predictive models.

Probabilistic averging of models is the weighted average of the predictive distributions of individual models

\[p(x | x^{\mathrm{obs}}) = \sum _m w_m\, p_m(x | x^{\mathrm{obs}}),\]

where the sum runs over the individual models and \(w_m\) is the weight of model \(m\).

Warning

Does currently not support CovariatePopulationModels.

Parameters:

• predictive_models (List[PosteriorPredictiveModel] of length n_models.) – A list of predictive models.

• weights (List np.ndarray of length n_models.) – The weights of candidate models. Weights are normalised automatically.

get_dosing_regimen(final_time=None)

Returns the dosing regimen of the compound in form of a pandas.DataFrame.

The dataframe has a time, a duration, and a dose column, which indicate the time point and duration of the dose administration in the time units of the mechanistic model, MechanisticModel.time_unit(). The dose column specifies the amount of the compound that is being administered in units of the drug amount variable of the mechanistic model.

If an indefinitely administered dosing regimen is set, i.e. a finite duration and undefined number of doses, see set_dosing_regimen(), only the first administration of the dose will appear in the dataframe. Alternatively, a final dose time final_time can be provided, up to which the dose events are registered.

If no dosing regimen has been set, None is returned.

Parameters:

final_time – Time up to which dose events are registered in the dataframe. If None, all dose events are registered, except for indefinite dosing regimens. Here, only the first dose event is registered.

get_n_outputs()

Returns the number of outputs.

get_output_names()

Returns the output names.

get_predictive_model()

Returns a list of the chi.PosteriorPredictiveModel instances.

get_weights()

Returns the weights of the individual predictive models.

sample(times, n_samples=None, individual=None, seed=None, include_regimen=False)

Samples “measurements” of the biomarkers from the posterior predictive model and returns them in form of a pandas.DataFrame.

For each of the n_samples a parameter set is drawn from the approximate posterior distribution. These paramaters are then used to sample from the predictive model.

Parameters:

• times (list, numpy.ndarray of shape (n,)) – Times for the virtual “measurements”.

• n_samples (int, optional) – The number of virtual “measurements” that are performed at each time point. If None the biomarkers are measured only once at each time point.

• individual (str, optional) – The ID of the modelled individual. If None, either the first ID or the population is simulated.

• seed (int) – A seed for the pseudo-random number generator.

• include_regimen (bool, optional) – A boolean flag which determines whether the information about the dosing regimen is included.

set_dosing_regimen(dose, start=0, duration=0.01, period=None, num=None)

Sets the dosing regimen with which the compound is administered.

By default the dose is administered as a bolus injection (duration on a time scale that is 100 fold smaller than the basic time unit). To model an infusion of the dose over a longer time period, the duration can be adjusted to the appropriate time scale.

By default the dose is administered once. To apply multiple doses provide a dose administration period.

Note

This method requires a MechanisticModel that supports dose administration.

Parameters:

• dose – The amount of the compound that is injected at each administration.

• start – Start time of the treatment.

• duration – Duration of dose administration. For a bolus injection, a dose duration of 1% of the time unit should suffice. By default the duration is set to 0.01 (bolus).

• period – Periodicity at which doses are administered. If None the dose is administered only once.

• num – Number of administered doses. If None and the periodicity of the administration is not None, doses are administered indefinitely.

class chi.PopulationPredictiveModel(predictive_model, population_model)

Implements a model of a data-generating process.

The model is defined by an instance of a PredictiveModel and an instance of a PopulationModel. The predictive model \(p(y | \psi, t)\) defines the data-generating process for an individual in the population with parameters \(\psi\). The population model \(p(\psi | \theta)\) defines how the parameters vary across individuals in the population.

As a result, the data-generating process is defined as

\[p(y | \theta, t) = \int \mathrm{d}\psi \, p(y | \psi, t)\, p(\psi |\theta).\]

Extends PredictiveModel.

Parameters:

• predictive_model – An instance of a PredictiveModel.

• population_model – An instance of a PopulationModel.

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 at None, sets the parameter free again.

Parameters:

name_value_dict – A dictionary with model parameter names as keys, and parameter values as values.

get_dosing_regimen(final_time=None)

Returns the dosing regimen of the compound in form of a pandas.DataFrame.

The dataframe has a time, a duration, and a dose column, which indicate the time point and duration of the dose administration in the time units of the mechanistic model, MechanisticModel.time_unit(). The dose column specifies the amount of the compound that is being administered in units of the drug amount variable of the mechanistic model.

If an indefinitely administered dosing regimen is set, i.e. a finite duration and undefined number of doses, see set_dosing_regimen(), only the first administration of the dose will appear in the dataframe. Alternatively, a final dose time final_time can be provided, up to which the dose events are registered.

If no dosing regimen has been set, None is returned.

Parameters:

final_time – Time up to which dose events are registered in the dataframe. If None, all dose events are registered, except for indefinite dosing regimens. Here, only the first dose event is registered.

get_n_outputs()

Returns the number of outputs.

get_output_names()

Returns the output names.

get_parameter_names()

Returns the parameter names of the predictive model.

get_submodels()

Returns the submodels of the predictive model in form of a dictionary.

n_parameters()

Returns the number of parameters of the predictive model.

sample(parameters, times, n_samples=None, seed=None, return_df=True, include_regimen=False, covariates=None)

Samples measurements of the observables from virtual patients.

Virtual patients are sampled from the population model and measured by sampling from the individual-level predictive model. Each virtual patient is measured at each of the provided time points.

The number of virtual patients that is being measured can be specified with n_samples.

If the data-generating process does not depend on covariates, the covariates input is ignored.

Parameters:

• parameters (np.ndarry of shape (n_parameters,)) – Population model parameters.

• times (np.ndarray of shape (n_times,)) – Measurement time points.

• n_samples (int, optional) – Number of virtual patients.

• seed (int or numpy.random.Generator, optional) – Seed for the pseudo-random number generator.

• return_df (bool, optional) – A boolean flag which determines whether the output is returned as a pandas.DataFrame or a numpy.ndarray.

• include_regimen (bool, optional) – A boolean flag which determines whether the dosing regimen information is included in the output. Only possible when return_df=True.

• covariates (List, np.ndarray of shape (n_cov,) or (n_samples, n_cov), optional) – Covariate values, specifying the sampled subpopulation.

Return type:

pandas.DataFrame or np.ndarray of shape (n_outputs, n_times, n_samples)

set_dosing_regimen(dose, start=0, duration=0.01, period=None, num=None)

Sets the dosing regimen with which the compound is administered.

By default the dose is administered as a bolus injection (duration on a time scale that is 100 fold smaller than the basic time unit). To model an infusion of the dose over a longer time period, the duration can be adjusted to the appropriate time scale.

By default the dose is administered once. To apply multiple doses provide a dose administration period.

Note

This method requires a MechanisticModel that supports compound administration.

Parameters:

• dose – The amount of the compound that is injected at each administration.

• start – Start time of the treatment.

• duration – Duration of dose administration. For a bolus injection, a dose duration of 1% of the time unit should suffice. By default the duration is set to 0.01 (bolus).

• period – Periodicity at which doses are administered. If None the dose is administered only once.

• num – Number of administered doses. If None and the periodicity of the administration is not None, doses are administered indefinitely.

class chi.PosteriorPredictiveModel(predictive_model, posterior_samples, param_map=None)

Implements the posterior predictive model of the modelled data-generating process and the associated parameter posterior distribution.

A PosteriorPredictiveModel is instantiated with a PredictiveModel and samples from the associated posterior distribution in form of a xarray.Dataset. The samples approximate the posterior distribution of the model parameters.

Formally, the posterior predictive model is defined as

\[p(y | \mathcal{D}, t) = \int \text{d}\psi \, p(y | \psi , t)\, p(\psi | \mathcal{D}),\]

where \(p(y | \psi, t)\) is the model of the data-generating process and \(p(\psi | \mathcal{D})\) is the posterior distribution of the model parmeters.

Parameters:

• predictive_model (PredictiveModel) – A predictive model which defines the distribution of observable biomarkers over time conditioned on parameter values.

• posterior_samples (xarray.Dataset) – Samples from the posterior distribution of the model parameters.

• param_map (dict, optional) – A dictionary which can be used to map predictive model parameter names to the parameter names in the xarray.Dataset. If None, it is assumed that the names are identical.

get_dosing_regimen(final_time=None)

Returns the dosing regimen of the compound in form of a pandas.DataFrame.

The dataframe has a time, a duration, and a dose column, which indicate the time point and duration of the dose administration in the time units of the mechanistic model, MechanisticModel.time_unit(). The dose column specifies the amount of the compound that is being administered in units of the drug amount variable of the mechanistic model.

If an indefinitely administered dosing regimen is set, i.e. a finite duration and undefined number of doses, see set_dosing_regimen(), only the first administration of the dose will appear in the dataframe. Alternatively, a final dose time final_time can be provided, up to which the dose events are registered.

If no dosing regimen has been set, None is returned.

Parameters:

final_time – Time up to which dose events are registered in the dataframe. If None, all dose events are registered, except for indefinite dosing regimens. Here, only the first dose event is registered.

get_n_outputs()

Returns the number of outputs.

get_output_names()

Returns the output names.

get_predictive_model()

Returns the predictive model.

sample(times, n_samples=None, individual=None, seed=None, include_regimen=False, covariates=None)

Samples virtual measurements from the posterior predictive model and returns them in form of a pandas.DataFrame.

For each of the n_samples a parameter set is drawn from the approximate posterior distribution. These paramaters are then used to sample from the predictive model.

Parameters:

• times (list, numpy.ndarray of shape (n,)) – Times for the virtual “measurements”.

• n_samples (int, optional) – The number of virtual “measurements” that are performed at each time point. If None the biomarkers are measured only once at each time point.

• individual (str, optional) – The ID of the modelled individual. If None, either the first ID or the population is simulated.

• seed (int or numpy.random.Generator, optional) – Seed for the pseudo-random number generator.

• include_regimen (bool, optional) – A boolean flag which determines whether the dosing regimen information is included in the output. Only possible when return_df=True.

• covariates (List, np.ndarray of shape (n_cov,) or (n_samples, n_cov), optional) – Covariate values, specifying the sampled subpopulation.

Return type:

pandas.DataFrame

set_dosing_regimen(dose, start=0, duration=0.01, period=None, num=None)

Sets the dosing regimen of the administered compound.

By default the dose is administered as a bolus injection (duration on a time scale that is 100 fold smaller than the time unit). To model an infusion of the dose over a longer time period, the duration can be adjusted to the appropriate time scale.

By default the dose is administered once. To apply multiple doses provide a dose administration period.

Note

This method requires a MechanisticModel that supports dose administration.

Parameters:

• dose – The amount of the compound that is injected at each administration.

• start – Start time of the treatment.

• duration – Duration of dose administration. For a bolus injection, a dose duration of 1% of the time unit should suffice. By default the duration is set to 0.01 (bolus).

• period – Periodicity at which doses are administered. If None the dose is administered only once.

• num – Number of administered doses. If None and the periodicity of the administration is not None, doses are administered indefinitely.

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

Implements a model of a data-generating process.

The model is defined by an instance of a MechanisticModel and an instance of an ErrorModel for each mechanistic model output

\[p(y | \psi , t),\]

where \(y\) are measurements of quantities of interest, \(\psi\) are the model parameters and \(t\) is the time.

Parameters:

• mechanistic_model – An instance of a MechanisticModel.

• error_models – A list of ErrorModel instances, one for each model output of the mechanistic model.

• outputs – A list of the model outputs, which maps the error models to the model outputs. If None the error models are assumed to be listed in the same order as the model 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 at None, sets the parameter free again.

Parameters:

name_value_dict – A dictionary with model parameter names as keys, and parameter value as values.

get_dosing_regimen(final_time=None)

Returns the dosing regimen of the compound in form of a pandas.DataFrame.

The dataframe has a time, a duration, and a dose column, which indicate the time point and duration of the dose administration in the time units of the mechanistic model, MechanisticModel.time_unit(). The dose column specifies the amount of the compound that is being administered in units of the drug amount variable of the mechanistic model.

If an indefinitely administered dosing regimen is set, i.e. a finite duration and undefined number of doses, see set_dosing_regimen(), only the first administration of the dose will appear in the dataframe. Alternatively, a final dose time final_time can be provided, up to which the dose events are registered.

If no dosing regimen has been set, None is returned.

Parameters:

final_time – Time up to which dose events are registered in the dataframe. If None, all dose events are registered, except for indefinite dosing regimens. Here, only the first dose event is registered.

get_n_outputs()

Returns the number of outputs.

get_output_names()

Returns the output names.

get_parameter_names()

Returns the parameter names of the predictive model.

get_submodels()

Returns the submodels of the predictive model in form of a dictionary.

n_parameters()

Returns the number of parameters of the predictive model.

sample(parameters, times, n_samples=None, seed=None, return_df=True, include_regimen=False, *args, **kwargs)

Samples “measurements” of the biomarkers from the predictive model and returns them in form of a pandas.DataFrame or a numpy.ndarray.

The mechanistic model is solved for the provided parameters and times, and samples around this solution are drawn from the error models for each time point.

The number of samples for each time point can be specified with n_samples.

Parameters:

• parameters – An array-like object with the parameter values of the predictive model.

• times – An array-like object with times at which the virtual “measurements” are performed.

• n_samples – The number of virtual “measurements” that are performed at each time point. If None the biomarkers are measured only once at each time point.

• seed – A seed for the pseudo-random number generator or a numpy.random.Generator.

• return_df – A boolean flag which determines whether the output is returned as a pandas.DataFrame or a numpy.ndarray. If False the samples are returned as a numpy array of shape (n_outputs, n_times, n_samples).

• include_regimen – A boolean flag which determines whether the dosing regimen information is included in the output. If the samples are returned as a numpy.ndarray, the dosing information is not included.

set_dosing_regimen(dose, start=0, duration=0.01, period=None, num=None)

Sets the dosing regimen with which the compound is administered.

By default the dose is administered as a bolus injection (duration on a time scale that is 100 fold smaller than the basic time unit). To model an infusion of the dose over a longer time period, the duration can be adjusted to the appropriate time scale.

By default the dose is administered once. To apply multiple doses provide a dose administration period.

Note

This method requires a MechanisticModel that supports compound administration.

Parameters:

• dose – The amount of the compound that is injected at each administration.

• start – Start time of the treatment.

• duration – Duration of dose administration. For a bolus injection, a dose duration of 1% of the time unit should suffice. By default the duration is set to 0.01 (bolus).

• period – Periodicity at which doses are administered. If None the dose is administered only once.

• num – Number of administered doses. If None and the periodicity of the administration is not None, doses are administered indefinitely.

class chi.PriorPredictiveModel(predictive_model, log_prior)

Implements a model that predicts the change of observable biomarkers over time based on the provided distribution of model parameters prior to the inference.

A prior predictive model may be used to check whether the assumptions about the parameter distribution log_prior lead to a predictive distirbution that encapsulates the expected measurement values of preclinical and clinical biomarkers.

A PriorPredictiveModel is instantiated with an instance of a PredictiveModel and a pints.LogPrior of the same parametric dimension as the predictive model. Future biomarker “measurements” can then be predicted by first sampling parameter values from the log-prior distribution, and then generating “virtual” measurements from the predictive model with those parameters.

Parameters:

• predictive_model – An instance of a PredictiveModel.

• log_prior – An instance of a pints.LogPrior of the same dimensionality as the number of predictive model parameters.

get_dosing_regimen(final_time=None)

Returns the dosing regimen of the compound in form of a pandas.DataFrame.

The dataframe has a time, a duration, and a dose column, which indicate the time point and duration of the dose administration in the time units of the mechanistic model, MechanisticModel.time_unit(). The dose column specifies the amount of the compound that is being administered in units of the drug amount variable of the mechanistic model.

If an indefinitely administered dosing regimen is set, i.e. a finite duration and undefined number of doses, see set_dosing_regimen(), only the first administration of the dose will appear in the dataframe. Alternatively, a final dose time final_time can be provided, up to which the dose events are registered.

If no dosing regimen has been set, None is returned.

Parameters:

final_time – Time up to which dose events are registered in the dataframe. If None, all dose events are registered, except for indefinite dosing regimens. Here, only the first dose event is registered.

get_n_outputs()

Returns the number of outputs.

get_output_names()

Returns the output names.

get_predictive_model()

Returns the predictive model.

sample(times, n_samples=None, seed=None, include_regimen=False, covariates=None)

Samples “measurements” of the biomarkers from the prior predictive model and returns them in form of a pandas.DataFrame.

For each of the n_samples a parameter set is drawn from the log-prior. These paramaters are then used to sample from the predictive model.

Parameters:

• times (list, numpy.ndarray of shape (n,)) – Times for the virtual “measurements”.

• n_samples (int, optional) – The number of virtual “measurements” that are performed at each time point. If None the biomarkers are measured only once at each time point.

• seed (int or numpy.random.Generator, optional) – Seed for the pseudo-random number generator.

• include_regimen (bool, optional) – A boolean flag which determines whether the dosing regimen information is included in the output. Only possible when return_df=True.

• covariates (List, np.ndarray of shape (n_cov,) or (n_samples, n_cov), optional) – Covariate values, specifying the sampled subpopulation.

Return type:

pandas.DataFrame

set_dosing_regimen(dose, start=0, duration=0.01, period=None, num=None)

Sets the dosing regimen of the administered compound.

By default the dose is administered as a bolus injection (duration on a time scale that is 100 fold smaller than the time unit). To model an infusion of the dose over a longer time period, the duration can be adjusted to the appropriate time scale.

By default the dose is administered once. To apply multiple doses provide a dose administration period.

Note

This method requires a MechanisticModel that supports dose administration.

Parameters:

• dose – The amount of the compound that is injected at each administration.

• start – Start time of the treatment.

• duration – Duration of dose administration. For a bolus injection, a dose duration of 1% of the time unit should suffice. By default the duration is set to 0.01 (bolus).

• period – Periodicity at which doses are administered. If None the dose is administered only once.

• num – Number of administered doses. If None and the periodicity of the administration is not None, doses are administered indefinitely.

Base classes

• AveragedPredictiveModel

Detailed API

class chi.AveragedPredictiveModel(predictive_model)

A base class for predictive models whose parameters are drawn from a distribution.

get_dosing_regimen(final_time=None)

Returns the dosing regimen of the compound in form of a pandas.DataFrame.

The dataframe has a time, a duration, and a dose column, which indicate the time point and duration of the dose administration in the time units of the mechanistic model, MechanisticModel.time_unit(). The dose column specifies the amount of the compound that is being administered in units of the drug amount variable of the mechanistic model.

If an indefinitely administered dosing regimen is set, i.e. a finite duration and undefined number of doses, see set_dosing_regimen(), only the first administration of the dose will appear in the dataframe. Alternatively, a final dose time final_time can be provided, up to which the dose events are registered.

If no dosing regimen has been set, None is returned.

Parameters:

final_time – Time up to which dose events are registered in the dataframe. If None, all dose events are registered, except for indefinite dosing regimens. Here, only the first dose event is registered.

get_n_outputs()

Returns the number of outputs.

get_output_names()

Returns the output names.

get_predictive_model()

Returns the predictive model.

sample(times, n_samples=None, seed=None, include_regimen=False)

Samples virtual measurements from the model of the data-generating process and returns them in form of a pandas.DataFrame.

set_dosing_regimen(dose, start=0, duration=0.01, period=None, num=None)

Sets the dosing regimen of the administered compound.

By default the dose is administered as a bolus injection (duration on a time scale that is 100 fold smaller than the time unit). To model an infusion of the dose over a longer time period, the duration can be adjusted to the appropriate time scale.

By default the dose is administered once. To apply multiple doses provide a dose administration period.

Note

This method requires a MechanisticModel that supports dose administration.

Parameters:

• dose – The amount of the compound that is injected at each administration.

• start – Start time of the treatment.

• duration – Duration of dose administration. For a bolus injection, a dose duration of 1% of the time unit should suffice. By default the duration is set to 0.01 (bolus).

• period – Periodicity at which doses are administered. If None the dose is administered only once.

• num – Number of administered doses. If None and the periodicity of the administration is not None, doses are administered indefinitely.