Prediction Plots

Prediction plots in chi are intended for the illustration of sampling results from a PredictiveModel. The predicted samples or approximate predictive distributions can then be compared to real measurements.

Functional classes

PDPredictivePlot
PKPredictivePlot
ResidualPlot

Detailed API

class chi.plots.PDPredictivePlot(updatemenu=True)[source]

A figure class that visualises the predictions of a predictive pharmacodynamic model.

Extends SingleFigure.

Parameters:: updatemenu – Boolean flag that enables or disables interactive buttons, such as a logarithmic scale switch for the y-axis.

add_data(data, observable=None, id_key='ID', time_key='Time', obs_key='Observable', value_key='Value')[source]

Adds pharmacodynamic time series data of (multiple) individuals to the figure.

Expects a pandas.DataFrame with an ID, a time, an observable and a value column, and adds a scatter plot of the measured time series to the figure. Each individual receives a unique colour.

Parameters:

data – A pandas.DataFrame with the time series PD data in form of an ID, time, and observable column.
observable – The predicted observable. This argument is used to determine the relevant rows in the dataframe. If None, the first observable in the observable column is selected.
id_key – Key label of the DataFrame which specifies the ID column. The ID refers to the identity of an individual. Defaults to 'ID'.
time_key – Key label of the DataFrame which specifies the time column. Defaults to 'Time'.
obs_key – Key label of the DataFrame which specifies the observable column. Defaults to 'Observable'.
value_key – Key label of the DataFrame which specifies the column of the measured values. Defaults to 'Value'.

add_prediction(data, observable=None, bulk_probs=[0.9], time_key='Time', obs_key='Observable', value_key='Value')[source]

Adds the prediction to the figure.

Expects a pandas.DataFrame with a time, an observable and a value column. The time column determines the times of the measurements and the value column the measured value. The observable column determines the observable.

A list of bulk probabilities bulk_probs can be specified, which are then added as area to the figure. The corresponding upper and lower percentiles are estimated from the ranks of the provided samples.

Warning

For low sample sizes the illustrated bulk probabilities may deviate significantly from the theoretical bulk probabilities. The upper and lower limit are determined from the rank of the samples for each time point.

Parameters:

data – A pandas.DataFrame with the time series PD simulation in form of a time and observable column.
observable – The predicted observable. This argument is used to determine the relevant rows in the dataframe. If None, the first observable in the observable column is selected.
bulk_probs – A list of bulk probabilities that are illustrated in the figure. If None the samples are illustrated as a scatter plot.
time_key – Key label of the pandas.DataFrame which specifies the time column. Defaults to 'Time'.
obs_key – Key label of the pandas.DataFrame which specifies the observable column. Defaults to 'Observable'.
value_key – Key label of the pandas.DataFrame which specifies the value column. Defaults to 'Value'.

set_axis_labels(xlabel, ylabel): Sets the x axis, and y axis label of the figure.

show(): Displays the figure.

class chi.plots.PKPredictivePlot(updatemenu=True)[source]

A figure class that visualises the predictions of a predictive pharmacokinetic model.

Extends SingleSubplotFigure.

Parameters:: updatemenu – Boolean flag that enables or disables interactive buttons, such as a logarithmic scale switch for the y-axis.

add_data(data, observable=None, id_key='ID', time_key='Time', obs_key='Observable', value_key='Value', dose_key='Dose', dose_duration_key='Duration')[source]

Adds pharmacokinetic time series data of (multiple) individuals to the figure.

Expects a pandas.DataFrame with an ID, a time, an observable and a value column, and adds a scatter plot of the measuremed time series to the figure. The dataframe is also expected to have information about the administered dose via a dose and a dose duration column. Each individual receives a unique colour.

Parameters:

data – A pandas.DataFrame with the time series PD data in form of an ID, time, and observable column.
observable – The measured observable. This argument is used to determine the relevant rows in the dataframe. If None, the first observable in the observable column is selected.
id_key – Key label of the DataFrame which specifies the ID column. The ID refers to the identity of an individual. Defaults to 'ID'.
time_key – Key label of the DataFrame which specifies the time column. Defaults to 'Time'.
obs_key – Key label of the DataFrame which specifies the observable column. Defaults to 'Observable'.
value_key – Key label of the DataFrame which specifies the column of the measured values. Defaults to 'Value'.
dose_key – Key label of the DataFrame which specifies the dose column. Defaults to 'Dose'.
dose_duration_key – Key label of the DataFrame which specifies the dose duration column. Defaults to 'Duration'.

add_prediction(data, observable=None, bulk_probs=[0.9], time_key='Time', obs_key='Observable', value_key='Value', dose_key='Dose', dose_duration_key='Duration')[source]

Adds the prediction for the observable pharmacokinetic observable values to the figure.

Expects a pandas.DataFrame with a time, an observable and a value column. The time column determines the time of the observable measurement and the sample column the corresponding observable measurement. The observable column determines the observable type. The dataframe is also expected to have information about the administered dose via a dose and a dose duration column.

A list of bulk probabilities bulk_probs can be specified, which are then added as area to the figure. The corresponding upper and lower percentiles are estimated from the ranks of the provided samples.

Warning

For low sample sizes the illustrated bulk probabilities may deviate significantly from the theoretical bulk probabilities. The upper and lower limit are determined from the rank of the samples for each time point.

Parameters:

data – A pandas.DataFrame with the time series PD simulation in form of a time and observable column.
observable – The predicted observable. This argument is used to determine the relevant rows in the dataframe. If None, the first observable in the observable column is selected.
bulk_probs – A list of bulk probabilities that are illustrated in the figure. If None the samples are illustrated as a scatter plot.
time_key – Key label of the pandas.DataFrame which specifies the time column. Defaults to 'Time'.
obs_key – Key label of the pandas.DataFrame which specifies the observable column. Defaults to 'Observable'.
value_key – Key label of the pandas.DataFrame which specifies the value column. Defaults to 'Value'.
dose_key – Key label of the DataFrame which specifies the dose column. Defaults to 'Dose'.
dose_duration_key – Key label of the DataFrame which specifies the dose duration column. Defaults to 'Duration'.

set_axis_labels(time_label, biom_label, dose_label)[source]: Sets the label of the time axis, the biomarker axis, and the dose axis.

show(): Displays the figure.

class chi.plots.ResidualPlot(measurements, id_key='ID', time_key='Time', obs_key='Observable', value_key='Value', updatemenu=True)[source]

A figure class that visualises the residual error between the predictions of a predictive model and measured observations.

Expects a pandas.DataFrame of measurements with an ID, a time, observable and a value column. This dataset is used as reference to compute the residuals.

Extends SingleFigure.

Parameters:

data – A pandas.DataFrame with the time series PD data in form of an ID, time, and biomarker column.
id_key – Key label of the DataFrame which specifies the ID column. The ID refers to the identity of an individual. Defaults to 'ID'.
time_key – Key label of the DataFrame which specifies the time column. Defaults to 'Time'.
obs_key – Key label of the DataFrame which specifies the observable column. Defaults to 'Observable'.
value_key – Key label of the DataFrame which specifies the column of the measured values. Defaults to 'Value'.
updatemenu – Boolean flag that enables or disables interactive buttons, such as a logarithmic scale switch for the y-axis.

add_data(data, observable=None, individual=None, show_residuals=True, show_relative=False, time_key='Time', obs_key='Observable', value_key='Value')[source]

Adds the residuals of the predicted values with respect to the measured values to the figure.

Expects a pandas.DataFrame with a time, an observable and a value column. The time column determines the times of the measurements and the value column the measured values. The observable column determines the measured observable.

The predictions are matched to the observations based on their ID and time label. If multiple predictions are provided for one measured time point, the mean prediction is computed as reference.

Parameters:

data – A pandas.DataFrame with the time series PD simulation in form of a time and observable column.
observable – The predicted bimoarker. This argument is used to determine the relevant rows in the dataframe. If None, the first observable type in the observable column is selected.
individual – The ID of the individual whose measurements are used as reference for the predictive residuals. Defaults to None which compares the predictions to all individuals.
show_residuals – A boolean flag which indicates whether the residuals are plotted on the y axis, or the measurements themselves. Defaults to True.
show_relative – A boolean flag which indicates whether the observations/residuals are normalised by the mean predictions. Defaults to False.
time_key – Key label of the pandas.DataFrame which specifies the time column. Defaults to 'Time'.
obs_key – Key label of the pandas.DataFrame which specifies the observable column. Defaults to 'Observable'.
value_key – Key label of the pandas.DataFrame which specifies the value column. Defaults to 'Value'.

set_axis_labels(xlabel, ylabel): Sets the x axis, and y axis label of the figure.

show(): Displays the figure.