sensitivity.uncertainty¶

The uncertainty analysis: bands of timecourses and distributions of values.

The uncertainty of a prediction is a scan over draws of the uncertain parameters, see sbmlsim.simulation.sampling (random, lhs, fit_parameters, profile_parameters, fit_repeats, population), run by Simulator.run, and its summary over the dimension of the draws, ScanResult.summary(dim, quantiles=[0.05, 0.5, 0.95]). The functions here draw it: plot_bands a timecourse as a median and a band per label of the other dimensions, plot_distribution a value per simulation as a histogram or a box per label. They return the figure and never show it; called once per scenario with one ax and a label each, they draw the scenarios into one plot with one legend.

plot_bands draws quantities, ScanResult.q: the axes have the units of the first quantities drawn into them and convert every other one, so a band shares an axis with the lines of ax.plot(res.q["time"], res.q["cp"]), and time_unit and unit choose the units, e.g. time_unit="hr". The axes are labelled with sbmlsim.plot.label_axes, the units in their short form, e.g. ng/ml; plot_distribution converts into unit and labels the same way.

plot_bands ¶

plot_bands(
    summary,
    key,
    *,
    lower="q0.05",
    center="q0.5",
    upper="q0.95",
    ax=None,
    alpha=0.3,
    label=None,
    time_unit=None,
    unit=None,
    name=None,
)

Draw a timecourse of a summary as a center line and a band per label.

Every line is labelled with the labels of the other dimensions, e.g. dose=1, or with the key for a summary without other dimensions. A label is the label of the line of a summary without other dimensions and the prefix of the labels of the lines otherwise, e.g. mid: dose=1, so the summaries of several scenarios drawn into one ax are told apart in its legend, which every call draws again with every line of the axes.

Parameters:

Name	Type	Description	Default
`summary`	`ScanResult`	a summary of a scan, `ScanResult.summary(..., quantiles=...)`.	required
`key`	`str`	the timecourse.	required
`lower`	`str`	the statistic of the lower bound of the band.	`'q0.05'`
`center`	`str`	the statistic of the line.	`'q0.5'`
`upper`	`str`	the statistic of the upper bound of the band.	`'q0.95'`
`ax`	`Axes \| None`	the axes to draw into, a new figure without.	`None`
`alpha`	`float`	the opacity of the band.	`0.3`
`label`	`str \| None`	the label of the lines, see above.	`None`
`time_unit`	`str \| None`	the unit of the time, e.g. `hr`, the one of the summary by default; an axis which has a unit keeps it.	`None`
`unit`	`str \| None`	the unit of the values, e.g. `ng/ml`, the one of the summary by default; an axis which has a unit keeps it.	`None`
`name`	`str \| None`	the name of the values on their axis, the key by default.	`None`

Returns:

Type	Description
`Figure`	The figure.

Raises:

Type	Description
`ValueError`	if the variable is no timecourse of a summary or a statistic is missing.

plot_distribution ¶

plot_distribution(
    result,
    key,
    *,
    dim,
    kind="hist",
    ax=None,
    bins=30,
    label=None,
    unit=None,
    name=None,
)

Draw a value per simulation over the draws as a histogram or a box per label.

The histograms and boxes are labelled as the lines of plot_bands: with the labels of the other dimensions, the key without them, and a label is the label of a result without other dimensions and the prefix of the labels otherwise. Histograms of several calls into one ax share one legend; the bins are the ones of a call.

Parameters:

Name	Type	Description	Default
`result`	`ScanResult`	the result of a scan over draws.	required
`key`	`str`	a value per simulation, e.g. the parameter of a PK observable.	required
`dim`	`str`	the dimension of the draws.	required
`kind`	`str`	`hist` or `box`.	`'hist'`
`ax`	`Axes \| None`	the axes to draw into, a new figure without.	`None`
`bins`	`int`	the number of bins of a histogram, shared by every label.	`30`
`label`	`str \| None`	the label of the distributions, see above.	`None`
`unit`	`str \| None`	the unit of the values, e.g. `ng/ml`, the one of the result by default.	`None`
`name`	`str \| None`	the name of the values on their axis, the key by default.	`None`

Returns:

Type	Description
`Figure`	The figure.

Raises:

Type	Description
`ValueError`	if the variable is a timecourse, the dimension is not one of it, or the kind is unknown.