pypesto.visualize

Visualize

pypesto comes with various visualization routines. To use these, import pypesto.visualize.

class pypesto.visualize.ReferencePoint[source]

Bases: dict

Reference point for plotting.

Should contain a parameter value and an objective function value, may also contain a color and a legend.

Can be used like a dict.

x

Reference parameters.

fval

Function value, fun(x), for reference parameters.

Type:

float

color

Color which should be used for reference point.

Type:

RGBA, optional

auto_color

flag indicating whether color for this reference point should be assigned automatically or whether it was assigned by user

Type:

boolean

legend

legend text for reference point

Type:

str

__init__(reference=None, x=None, fval=None, color=None, legend=None)[source]
Parameters:
pypesto.visualize.assign_clustered_colors(vals, balance_alpha=True, highlight_global=True)[source]

Cluster and assign colors.

Parameters:

  • vals (ndarray) – List to be clustered and assigned colors.

  • balance_alpha (bool) – Flag indicating whether alpha for large clusters should be reduced to avoid overplotting

  • highlight_global (bool) – flag indicating whether global optimum should be highlighted

Returns:

colors (list of RGBA) – One for each element in ‘vals’.

pypesto.visualize.assign_clusters(vals)[source]

Find clustering.

Parameters:

vals (numeric list or array) – List to be clustered.

Returns:

  • clust (numeric list) – Indicating the corresponding cluster of each element from ‘vals’.

  • clustsize (numeric list) – Size of clusters, length equals number of clusters.

pypesto.visualize.assign_colors(vals, colors=None, balance_alpha=True, highlight_global=True)[source]

Assign colors or format user specified colors.

Parameters:
Return type:

ndarray

Returns:

colors (list of colors recognized by matplotlib) – One for each element in ‘vals’.

pypesto.visualize.create_references(references=None, x=None, fval=None, color=None, legend=None)[source]

Create a list of reference point objects from user inputs.

Parameters:

  • references (ReferencePoint or dict or list, optional) – Will be converted into a list of RefPoints

  • x (ndarray, optional) – Parameter vector which should be used for reference point

  • fval (float, optional) – Objective function value which should be used for reference point

  • color (RGBA, optional) – Color which should be used for reference point.

  • legend (str) – legend text for reference point

Return type:

list[ReferencePoint]

Returns:

colors (list of RGBA) – One for each element in ‘vals’.

pypesto.visualize.delete_nan_inf(fvals, x=None, xdim=1, magnitude_bound=inf)[source]

Delete nan and inf values in fvals.

If parameters ‘x’ are passed, also the corresponding entries are deleted.

Parameters:

  • x (Sequence[ndarray | list[float]] | None) – array of parameters

  • fvals (ndarray) – array of fval

  • xdim (int | None) – dimension of x, in case x dimension cannot be inferred

  • magnitude_bound (float | None) – any values with a magnitude (absolute value) larger than the magnitude_bound are also deleted

Return type:

tuple[ndarray, ndarray]

Returns:

  • x – array of parameters without nan or inf

  • fvals – array of fval without nan or inf

pypesto.visualize.ensemble_crosstab_scatter_lowlevel(dataset, component_labels=None, axes=None, size=None, **kwargs)[source]

Plot cross-classification table of scatter plots for different coordinates.

Lowlevel routine for multiple UMAP and PCA plots, but can also be used to visualize, e.g., parameter traces across optimizer runs.

Parameters:

  • dataset (ndarray) – array of data points to be shown as scatter plot

  • component_labels (Sequence[str]) – labels for the x-axes and the y-axes

  • axes (ndarray | None)

  • size (tuple[float, float] | None)

Return type:

ndarray

Returns:

axes – 2-D NumPy array containing one matplotlib Axes per panel.

pypesto.visualize.ensemble_identifiability(ensemble, ax=None, size=(12, 6))[source]

Visualize identifiablity of parameter ensemble.

Plot an overview about how many parameters hit the parameter bounds based on an ensemble of parameters. confidence intervals/credible ranges are computed via the ensemble mean plus/minus 1 standard deviation. This highlevel routine expects an ensemble object as input.

Parameters:

  • ensemble (Ensemble) – ensemble of parameter vectors (from pypesto.ensemble)

  • ax (Axes | None) – Axes object to use.

  • size (tuple[float, float] | None) – Figure size (width, height) in inches. Is only applied when no ax object is specified

Return type:

Axes

Returns:

ax (matplotlib.axes.Axes) – The plot axes.

pypesto.visualize.ensemble_scatter_lowlevel(dataset, ax=None, size=(12, 6), x_label='component 1', y_label='component 2', color_by=None, color_map='viridis', background_color='white', marker_type='.', scatter_size=0.5, invert_scatter_order=False)[source]

Create a scatter plot.

Parameters:

  • dataset – array of data points in reduced dimension

  • ax (Axes | None) – Axes object to use.

  • size (tuple[float, float] | None) – Figure size (width, height) in inches. Is only applied when no ax object is specified

  • x_label (str) – The x-axis label

  • y_label (str) – The y-axis label

  • color_by (Sequence[float]) – A sequence/list of floats, which specify the color in the colormap

  • color_map (str) – A colormap name known to pyplot

  • background_color (str | tuple[float, float, float] | tuple[float, float, float, float]) – Background color of the axes object (defaults to black)

  • marker_type (str) – Type of plotted markers

  • scatter_size (float) – Size of plotted markers

  • invert_scatter_order (bool) – Specifies the order of plotting the scatter points, can be important in case of overplotting

Return type:

Axes

Returns:

ax (matplotlib.axes.Axes) – The plot axes.

pypesto.visualize.optimization_run_properties_one_plot(results, properties_to_plot=None, size=(18.5, 10.5), start_indices=None, colors=None, legends=None, plot_type='line', ax=None)[source]

Plot stats for allproperties specified in properties_to_plot on one plot.

Parameters:

  • results (Result) – Optimization result obtained by ‘optimize.py’ or list of those

  • ax (Axes | None) – Axes object to use.

  • properties_to_plot (list[str] | None) – Optimization run properties that should be plotted

  • size (tuple[float, float]) – Figure size (width, height) in inches. Is only applied when no ax object is specified

  • start_indices (int | Iterable[int] | None) – List of integers specifying the multistarts to be plotted or int specifying up to which start index should be plotted

  • colors (str | tuple[float, float, float] | tuple[float, float, float, float] | list[str | tuple[float, float, float] | tuple[float, float, float, float]] | ndarray | None) – List of colors recognized by matplotlib colors (one color per property in properties_to_plot), or single color. If not set and one result, clustering is done and colors are assigned automatically

  • legends (str | list[str] | None) – Labels, one label per optimization property

  • plot_type (str) – Specifies plot type. Possible values: ‘line’ and ‘hist’

Return type:

Axes

Returns:

ax – The plot axes.

Examples

optimization_run_properties_one_plot(
    result1,
    properties_to_plot=['time'],
    colors=[.5, .9, .9, .3]
)

optimization_run_properties_one_plot(
    result1,
    properties_to_plot=['time', 'n_grad'],
    colors=[[.5, .9, .9, .3], [.2, .1, .9, .5]]
)
pypesto.visualize.optimization_run_properties_per_multistart(results, properties_to_plot=None, size=(18.5, 10.5), start_indices=None, colors=None, legends=None, plot_type='line', axes=None)[source]

One plot per optimization property in properties_to_plot.

Parameters:

  • results (Result | Sequence[Result]) – Optimization result obtained by ‘optimize.py’ or list of those

  • properties_to_plot (list[str] | None) – Optimization run properties that should be plotted

  • size (tuple[float, float]) – Figure size (width, height) in inches. Is only applied when no ax object is specified

  • start_indices (int | Iterable[int] | None) – List of integers specifying the multistarts to be plotted or int specifying up to which start index should be plotted

  • colors (str | tuple[float, float, float] | tuple[float, float, float, float] | list[str | tuple[float, float, float] | tuple[float, float, float, float]] | ndarray | None) – List of colors recognized by matplotlib (one color per result in results), or single color. If not set and one result, clustering is done and colors are assigned automatically

  • legends (str | list[str] | None) – Labels for line plots, one label per result object

  • plot_type (str) – Specifies plot type. Possible values: ‘line’ and ‘hist’

  • axes (ndarray | None)

Return type:

ndarray

Returns:

axes – 2-D NumPy array containing one matplotlib Axes per panel.

Examples

optimization_run_properties_per_multistart(
    result1,
    properties_to_plot=['time'],
    colors=[.5, .9, .9, .3]
)

optimization_run_properties_per_multistart(
    [result1, result2],
    properties_to_plot=['time'],
    colors=[[.5, .9, .9, .3], [.2, .1, .9, .5]]
)

optimization_run_properties_per_multistart(
    result1,
    properties_to_plot=['time', 'n_grad'],
    colors=[.5, .9, .9, .3]
)

optimization_run_properties_per_multistart(
    [result1, result2], properties_to_plot=['time', 'n_fval'],
    colors=[[.5, .9, .9, .3], [.2, .1, .9, .5]]
)
pypesto.visualize.optimization_run_property_per_multistart(results, opt_run_property, axes=None, size=(18.5, 10.5), start_indices=None, colors=None, legends=None, plot_type='line')[source]

Plot stats for an optimization run property specified by opt_run_property.

It is possible to plot a histogram or a line plot. In a line plot, on the x-axis are the numbers of the multistarts, where the multistarts are ordered with respect to a function value. On the y-axis of the line plot the value of the corresponding parameter for each multistart is displayed.

Parameters:

  • opt_run_property (str) – optimization run property to plot. One of the ‘time’, ‘n_fval’, ‘n_grad’, ‘n_hess’, ‘n_res’, ‘n_sres’

  • results (Result | Sequence[Result]) – Optimization result obtained by ‘optimize.py’ or list of those

  • axes (Axes | ndarray | None) – Axes object to use

  • size (tuple[float, float]) – Figure size (width, height) in inches. Is only applied when no ax object is specified

  • start_indices (int | Iterable[int] | None) – List of integers specifying the multistarts to be plotted or int specifying up to which start index should be plotted

  • colors (str | tuple[float, float, float] | tuple[float, float, float, float] | list[str | tuple[float, float, float] | tuple[float, float, float, float]] | ndarray | None) – List of colors recognized by matplotlib (one color per result in results), or single color. If not set and one result, clustering is done and colors are assigned automatically

  • legends (str | list[str] | None) – Labels for line plots, one label per result object

  • plot_type (str) – Specifies plot type. Possible values: ‘line’, ‘hist’, ‘both’

Return type:

ndarray

Returns:

axes – 2-D NumPy array containing one matplotlib Axes per panel.

pypesto.visualize.optimization_scatter(result, parameter_indices='free_only', start_indices=None, diag_kind='kde', suptitle=None, size=None, show_bounds=False, axes=None)[source]

Plot a scatter matrix of all parameter pairs for the given starts.

Parameters:

  • result (Result) – Optimization result obtained by ‘optimize.py’.

  • parameter_indices (str | Sequence[int]) – List of integers specifying the parameters to be considered.

  • start_indices (int | Iterable[int] | None) – List of integers specifying the multistarts to be plotted or int specifying up to which start index should be plotted.

  • diag_kind (str) – Marginal distribution shown on the diagonal: ’kde’ (default) or ’hist’.

  • suptitle (str | None) – Title of the figure.

  • size (tuple[float, float] | None) – Figure size (width, height) in inches. Defaults to (2.5 * n + 0.5, 2.5 * n + 0.5).

  • show_bounds (bool) – Whether to draw dashed lines at the parameter bounds.

  • axes (ndarray | None) – Optional axes grid to draw into. Must have shape (n_params, n_params).

Return type:

ndarray

Returns:

axes – 2-D NumPy array of shape (n_params, n_params) containing one matplotlib Axes per panel.

pypesto.visualize.optimizer_convergence(result, ax=None, xscale='symlog', yscale='log', size=(18.5, 10.5))[source]

Visualize to help spotting convergence issues.

Scatter plot of function values and gradient values at the end of optimization. Optimizer exit-message is encoded by color. Can help identifying convergence issues in optimization and guide tolerance refinement etc.

Parameters:

  • result (Result) – Optimization result obtained by ‘optimize.py’

  • ax (Axes | None) – Axes object to use.

  • size (tuple[float, float]) – Figure size (width, height) in inches. Is only applied when no ax object is specified

  • xscale (str) – Scale for x-axis

  • yscale (str) – Scale for y-axis

Return type:

Axes

Returns:

ax (matplotlib.Axes) – The plot axes.

pypesto.visualize.optimizer_history(results, ax=None, size=(18.5, 10.5), trace_x='steps', trace_y='fval', scale_y='log10', offset_y=None, colors=None, y_limits=None, start_indices=None, reference=None, legends=None)[source]

Plot history of optimizer.

Can plot either the history of the cost function or of the gradient norm, over either the optimizer steps or the computation time.

Parameters:

  • results (Result | list[Result]) – Optimization result obtained by ‘optimize.py’ or list of those

  • ax (Axes | None) – Axes object to use.

  • size (tuple[float, float]) – Figure size (width, height) in inches. Is only applied when no ax object is specified

  • trace_x (str) – What should be plotted on the x-axis? Possibilities: TRACE_X Default: TRACE_X_STEPS

  • trace_y (str) – What should be plotted on the y-axis? Possibilities: TRACE_Y_FVAL, TRACE_Y_GRADNORM Default: TRACE_Y_FVAl

  • scale_y (str) – May be logarithmic or linear (‘log10’ or ‘lin’)

  • offset_y (float | None) – Offset for the y-axis-values, as these are plotted on a log10-scale Will be computed automatically if necessary

  • colors (str | tuple[float, float, float] | tuple[float, float, float, float] | list[str | tuple[float, float, float] | tuple[float, float, float, float]] | ndarray | None) – Color recognized by matplotlib or list of colors for plotting. If not set, clustering is done and colors are assigned automatically

  • y_limits (float | list[float] | ndarray | None) – maximum value to be plotted on the y-axis, or y-limits

  • start_indices (int | list[int] | None) – list of integers specifying the multistart to be plotted or int specifying up to which start index should be plotted

  • reference (ReferencePoint | dict | list[ReferencePoint] | list[dict] | None) – List of reference points for optimization results, containing at least a function value fval

  • legends (str | list[str] | None) – Labels for line plots, one label per result object

Return type:

Axes

Returns:

ax – The plot axes.

pypesto.visualize.optimizer_history_lowlevel(vals, scale_y='log10', colors=None, ax=None, size=(18.5, 10.5), x_label='Optimizer steps', y_label='Objective value', legend_text=None)[source]

Plot optimizer history using list of numpy arrays.

Parameters:
Return type:

Axes

Returns:

ax – The plot axes.

pypesto.visualize.parameter_hist(result, parameter_name, bins='auto', ax=None, size=(18.5, 10.5), color=None, start_indices=None)[source]

Plot parameter values as a histogram.

Parameters:

  • result (Result) – Optimization result obtained by ‘optimize.py’

  • parameter_name (str) – The name of the parameter that should be plotted

  • bins (int | str) – Specifies bins of the histogram

  • ax (Axes | None) – Axes object to use

  • size (tuple[float, float] | None) – Figure size (width, height) in inches. Is only applied when no ax object is specified

  • color (str | tuple[float, float, float] | tuple[float, float, float, float] | None) – Color recognized by matplotlib.

  • start_indices (int | list[int] | None) – List of integers specifying the multistarts to be plotted or int specifying up to which start index should be plotted

Return type:

Axes

Returns:

ax – The plot axes.

pypesto.visualize.parameters(results, ax=None, parameter_indices='free_only', lb=None, ub=None, size=None, reference=None, colors=None, legends=None, balance_alpha=True, start_indices=None, scale_to_interval=None, plot_inner_parameters=True, log10_scale_hier_sigma=True)[source]

Plot parameter values.

Parameters:

  • results (Result | Sequence[Result]) – Optimization result obtained by ‘optimize.py’ or list of those

  • ax (Axes | None) – Axes object to use.

  • parameter_indices (str | Sequence[int]) – Specifies which parameters should be plotted. Allowed string values are ‘all’ (both fixed and free parameters will be plotted) and ‘free_only’ (only free parameters will be plotted)

  • lb (ndarray | list[float] | None) – If not None, override result.problem.lb, problem.problem.ub. Dimension either result.problem.dim or result.problem.dim_full.

  • ub (ndarray | list[float] | None) – If not None, override result.problem.lb, problem.problem.ub. Dimension either result.problem.dim or result.problem.dim_full.

  • size (tuple[float, float] | None) – Figure size (width, height) in inches. Is only applied when no ax object is specified

  • reference (list[ReferencePoint] | None) – List of reference points for optimization results, containing at least a function value fval

  • colors (str | tuple[float, float, float] | tuple[float, float, float, float] | list[str | tuple[float, float, float] | tuple[float, float, float, float]] | ndarray | None) – list of colors recognized by matplotlib, or single color If not set, clustering is done and colors are assigned automatically

  • legends (str | list[str] | None) – Labels for line plots, one label per result object

  • balance_alpha (bool) – Flag indicating whether alpha for large clusters should be reduced to avoid overplotting (default: True)

  • start_indices (int | Iterable[int] | None) – list of integers specifying the multistarts to be plotted or int specifying up to which start index should be plotted

  • scale_to_interval (tuple[float, float] | None) – Tuple of bounds to which to scale all parameter values and bounds, or None to use bounds as determined by lb, ub.

  • plot_inner_parameters (bool) – Flag indicating whether to plot inner parameters (default: True).

  • log10_scale_hier_sigma (bool) – Flag indicating whether to scale inner parameters of type InnerParameterType.SIGMA to log10 (default: True).

Return type:

Axes

Returns:

ax – The plot axes.

pypesto.visualize.parameters_correlation_matrix(result, parameter_indices='free_only', start_indices=None, method='pearson', cluster=True, cmap='bwr', return_table=False, heatmap_kwargs=None, size=None)[source]

Plot correlation of optimized parameters.

Parameters:

  • result (Result) – Optimization result obtained by ‘optimize.py’

  • parameter_indices (str | Sequence[int]) – List of integers specifying the parameters to be considered.

  • start_indices (int | Iterable[int] | None) – List of integers specifying the multistarts to be plotted or int specifying up to which start index should be plotted

  • method (str | Callable) – The method to compute correlation. Allowed values are pearson, kendall, spearman or a callable.

  • cluster (bool) – Whether to cluster the correlation matrix.

  • cmap (Colormap | str) – Colormap to use for the heatmap. Defaults to ‘bwr’.

  • return_table (bool) – Whether to return the parameter table additionally for further inspection.

  • heatmap_kwargs (dict | None) – Additional keyword arguments to seaborn.heatmap().

  • size (tuple[float, float] | None) – Figure size (width, height) in inches.

Return type:

Axes

Returns:

ax – The plot axis.

pypesto.visualize.parameters_lowlevel(xs, fvals, lb=None, ub=None, x_labels=None, x_axis_label='Parameter value', ax=None, size=None, colors=None, linestyle='-', legend_text=None, balance_alpha=True)[source]

Plot parameters plot using list of parameters.

Parameters:

  • xs (ndarray) – Including optimized parameters for each start that did not result in an infinite fval. Shape: (n_starts_successful, dim).

  • fvals (ndarray) – Function values. Needed to assign cluster colors.

  • lb (ndarray | list[float] | None) – The lower and upper bounds.

  • ub (ndarray | list[float] | None) – The lower and upper bounds.

  • x_labels (Iterable[str] | None) – Labels to be used for the parameters.

  • ax (Axes | None) – Axes object to use.

  • size (tuple[float, float] | None) – see parameters

  • colors (Sequence[ndarray | str | tuple[float, float, float] | tuple[float, float, float, float]] | None) – A single color recognized by matplotlib or a list of colors, one for each element in ‘fvals’.

  • linestyle (str) – linestyle argument for parameter plot

  • legend_text (str | None) – Label for line plots

  • balance_alpha (bool) – Flag indicating whether alpha for large clusters should be reduced to avoid overplotting (default: True)

  • x_axis_label (str)

Return type:

Axes

Returns:

ax – The plot axes.

pypesto.visualize.plot_categories_from_inner_result(inner_problem, inner_solver, results, simulation, timepoints, observable_ids=None, condition_ids=None, petab_condition_ordering=None, measurement_df_observable_ordering=None, axes=None, **kwargs)[source]

Plot the inner solutions.

Parameters:

  • inner_problem (OrdinalProblem) – The inner problem.

  • inner_solver (OrdinalInnerSolver) – The inner solver.

  • results (list[dict]) – The results from the inner solver.

  • simulation (list[ndarray]) – The model simulation.

  • timepoints (list[ndarray]) – The timepoints of the simulation.

  • kwargs – Additional arguments to pass to the figure.

  • axes (Axes | None) – The optional axes to plot on.

  • observable_ids (list[str])

  • condition_ids (list[str])

  • petab_condition_ordering (list[str])

  • measurement_df_observable_ordering (list[str])

Returns:

  • fig – The figure.

  • axes – The axes.

pypesto.visualize.plot_categories_from_pypesto_result(pypesto_result, start_index=0, axes=None, **kwargs)[source]

Plot the inner solutions from a pypesto result.

Parameters:

  • pypesto_result (Result) – The pypesto result.

  • start_index – The index of the pypesto_result.optimize_result.list to plot.

  • axes (Axes | None) – The optional axes to plot on.

  • kwargs – Additional arguments to pass to the figure.

Returns:

  • fig – The figure.

  • axes – The axes.

pypesto.visualize.plot_linear_observable_mappings_from_pypesto_result(pypesto_result, pypesto_problem, start_index=0, axes=None, rel_and_semiquant_obs_indices=None, **kwargs)[source]

Plot the linear observable mappings from a pyPESTO result.

Parameters:

  • pypesto_result (Result) – The pyPESTO result object from optimization.

  • pypesto_problem (HierarchicalProblem) – The pyPESTO problem. It should contain the objective object that was used for estimation.

  • start_index – The observable mapping from this start’s optimized vector will be plotted.

  • axes (ndarray | None) – Optional 2-D NumPy array of Axes to draw into. Required when rel_and_semiquant_obs_indices is set.

  • rel_and_semiquant_obs_indices (list[int] | None) – Sorted indices of the relative and semi-quantitative observables in the AMICI model. Each observable is plotted on the subplot at the corresponding position in axes.flat.

  • **kwargs – Additional arguments to pass to the matplotlib.pyplot.subplots function.

Return type:

ndarray

Returns:

axes – A 2-D NumPy array of matplotlib Axes.

pypesto.visualize.plot_splines_from_inner_result(inner_problem, inner_solver, results, sim, observable_ids=None, axes=None, rel_and_semiquant_obs_indices=None, **kwargs)[source]

Plot the estimated spline approximations from inner results.

Parameters:

  • inner_problem – The inner problem.

  • inner_solver – The inner solver.

  • results – The results from the inner solver.

  • sim – The simulated model output.

  • observable_ids – The ids of the observables.

  • axes – Optional 2-D NumPy array of Axes to draw into. Required when rel_and_semiquant_obs_indices is set.

  • rel_and_semiquant_obs_indices – Sorted indices of the relative and semi-quantitative observables in the AMICI model. Each observable is plotted on the subplot at the corresponding position in axes.flat.

  • kwargs – Additional arguments to pass to the plotting function.

Returns:

axes – A 2-D NumPy array of matplotlib Axes.

Return type:

ndarray

pypesto.visualize.plot_splines_from_pypesto_result(pypesto_result, start_index=0, axes=None, rel_and_semiquant_obs_indices=None, **kwargs)[source]

Plot the estimated spline approximations from a pypesto result.

Parameters:

  • pypesto_result (Result) – The pypesto result.

  • start_index – The observable mapping from this start’s optimized vector will be plotted.

  • axes (Axes | ndarray | None) – Optional axes grid to draw into.

  • rel_and_semiquant_obs_indices (list[int] | None) – The indices of the relative and semi-quantitative observables in the amici model. Important if both relative and semi-quantitative observables will be plotted on the same axes.

  • kwargs – Additional arguments to pass to the plotting function.

Return type:

ndarray | None

Returns:

axes – A 2-D NumPy array of matplotlib Axes, or None if the required simulation fails.

pypesto.visualize.process_offset_y(offset_y, scale_y, min_val)[source]

Compute offset for y-axis, depend on user settings.

Parameters:

  • offset_y (float | None) – value for offsetting the later plotted values, in order to ensure positivity if a semilog-plot is used

  • scale_y (str) – Can be ‘lin’ or ‘log10’, specifying whether values should be plotted on linear or on log10-scale

  • min_val (float) – Smallest value to be plotted

Return type:

float

Returns:

offset_y (float) – value for offsetting the later plotted values, in order to ensure positivity if a semilog-plot is used

pypesto.visualize.process_result_list(results, colors=None, legends=None)[source]

Assign colors and legends to a list of results, check user provided lists.

Parameters:
Return type:

tuple[list[Result], list[str | tuple[float, float, float] | tuple[float, float, float, float]], list[str]]

Returns:

  • results – list of pypesto.Result objects

  • colors – One for each element in ‘results’.

  • legends – labels for line plots

pypesto.visualize.process_y_limits(ax, y_limits)[source]

Apply user specified limits of y-axis.

Parameters:
Return type:

Axes

Returns:

ax – Axes object to use.

pypesto.visualize.profile_cis(result, confidence_level=0.95, df=1, profile_indices=None, profile_list=0, color='C0', show_bounds=False, ax=None)[source]

Plot approximate confidence intervals based on profiles.

Parameters:

  • result (Result) – The result object after profiling.

  • confidence_level (float) – The confidence level in (0,1), which is translated to an approximate threshold assuming a chi2 distribution, using pypesto.profile.chi2_quantile_to_ratio.

  • df (int) – Degrees of freedom of the chi2 distribution.

  • profile_indices (Sequence[int]) – List of integer values specifying which profiles should be plotted. Defaults to the indices for which profiles were generated in profile list profile_list.

  • profile_list (int) – Index of the profile list to be used.

  • color (str | tuple) – Main plot color.

  • show_bounds (bool) – Whether to show, and extend the plot to, the lower and upper bounds.

  • ax (Axes | None) – Axes object to use. Default: Create a new one.

Return type:

Axes

pypesto.visualize.profile_lowlevel(fvals, ax=None, size=(18.5, 6.5), color=None, legend_text=None, show_bounds=False, lb=None, ub=None)[source]

Lowlevel routine for plotting one profile, working with a numpy array only.

Parameters:
Return type:

Axes

Returns:

The plot axes.

pypesto.visualize.profile_lowlevel_2d(result, profile_index, second_par_index, ax, profile_list_id=0, ratio_min=0.0, cmap='viridis', plot_objective_values=False, x_labels=None, vmin=None, vmax=None)[source]

Lowlevel routine for plotting a two-parameter profile visualization.

Visualizes the profile of one parameter (x-axis) while showing the values of a second parameter (y-axis), with colors indicating the objective ratio or function value. Axis limits are always set to the parameter bounds, with dashed lines marking the lower and upper bounds. Axis labels include the parameter scale (e.g. log10(k1)) unless overridden via x_labels.

Parameters:

  • result (Result) – A single pypesto.Result after profiling.

  • profile_index (int) – Integer index specifying which profile to plot (x-axis parameter).

  • second_par_index (int) – Integer index specifying which parameter to show on y-axis.

  • ax (Axes) – Axes object to use for plotting.

  • profile_list_id (int) – Index of the profile list to visualize.

  • ratio_min (float) – Minimum ratio below which to cut off.

  • cmap (str) – Colormap to use for the objective ratio/value colors.

  • plot_objective_values (bool) – Whether to plot the objective function values instead of the likelihood ratio values.

  • x_labels (Sequence[str]) – Labels for the parameters (indexed by full parameter index). If None, labels are auto-generated from parameter names and scales.

  • vmin (float) – Minimum value for the color scale. If None, auto-scaled to the data.

  • vmax (float) – Maximum value for the color scale. If None, auto-scaled to the data.

Return type:

Axes

Returns:

The plot axes.

pypesto.visualize.profile_nested_cis(result, confidence_levels=(0.95, 0.9), df=1, profile_indices=None, profile_list=0, colors=None, ax=None, orientation='v')[source]

Plot approximate nested confidence intervals based on profiles.

Parameters:

  • result (Result) – The result object with profiling results.

  • confidence_levels (Sequence[float]) – The confidence levels in (0,1), which are translated to an approximate threshold assuming a chi2 distribution, using pypesto.profile.chi2_quantile_to_ratio.

  • df (int) – Degrees of freedom of the chi2 distribution.

  • profile_indices (Sequence[int]) – List of integer values specifying which profiles should be plotted. Defaults to the indices for which profiles were generated in profile list profile_list.

  • profile_list (int) – Index of the profile list to be used.

  • colors (Sequence) – A color for each confidence interval.

  • ax (Axes | None) – Axes object to use. Default: Create a new one.

  • orientation (Literal['v', 'h']) – Orientation of the plot, either vertical or horizontal.

Return type:

Axes

pypesto.visualize.profiles(results, ax=None, profile_indices=None, size=(18.5, 6.5), reference=None, colors=None, legends=None, x_labels=None, profile_list_ids=0, ratio_min=0.0, confidence_level=None, show_bounds=False, plot_objective_values=False, quality_colors=False)[source]

Plot classical 1D profile plot.

Using the posterior, e.g. Gaussian like profile.

Parameters:

  • results (Result | Sequence[Result]) – List of or single pypesto.Result after profiling.

  • ax (Axes | None) – List of axes objects to use.

  • profile_indices (Sequence[int]) – List of integer values specifying which profiles should be plotted.

  • size (tuple[float, float]) – Figure size (width, height) in inches. Is only applied when no ax object is specified.

  • reference (ReferencePoint | Sequence[ReferencePoint]) – List of reference points for optimization results, containing at least a function value fval.

  • colors (str | tuple[float, float, float] | tuple[float, float, float, float] | list[str | tuple[float, float, float] | tuple[float, float, float, float]] | ndarray | None) – List of colors, or single color. If multiple colors are passed, their number needs to correspond to either the number of results or the number of profile_list_ids. Cannot be provided if quality_colors is set to True.

  • legends (Sequence[str]) – Labels for line plots, one label per result object.

  • x_labels (Sequence[str]) – Labels for parameter value axes (e.g. parameter names).

  • profile_list_ids (int | Sequence[int]) – Index or list of indices of the profile lists to visualize.

  • ratio_min (float) – Minimum likelihood-ratio value below which to cut off profile points. Mutually exclusive with confidence_level.

  • confidence_level (float | None) – Confidence level in (0, 1) (e.g. 0.95). Converted to ratio_min via pypesto.profile.chi2_quantile_to_ratio(). Convenience alternative to specifying ratio_min directly.

  • show_bounds (bool) – Whether to show, and extend the plot to, the lower and upper bounds.

  • plot_objective_values (bool) – Whether to plot the objective function values instead of the likelihood ratio values.

  • quality_colors (bool) – If set to True, the profiles are colored according to types of steps the profiler took. This gives additional information about the profile quality. Red indicates a step for which min_step_size was reduced, blue indicates a step for which max_step_size was increased, and green indicates a step for which the profiler had to resample the parameter vector due to optimization failure of the previous two. Black indicates a step for which none of the above was necessary. This option is only available if there is only one result and one profile_list_id (one profile per plot).

Return type:

Axes

Returns:

ax – The plot axes.

pypesto.visualize.profiles_lowlevel(fvals, ax=None, size=(18.5, 6.5), color=None, legend_text=None, x_labels=None, show_bounds=False, lb_full=None, ub_full=None, plot_objective_values=False)[source]

Lowlevel routine for profile plotting.

Working with a list of arrays only, opening different axes objects in case.

Parameters:

  • fvals (float | Sequence[float]) – Values to plot.

  • ax (Sequence[Axes] | None) – List of axes object to use.

  • size (tuple[float, float]) – Figure size (width, height) in inches. Is only applied when no ax object is specified.

  • color (str | tuple[float, float, float] | tuple[float, float, float, float] | list[ndarray] | None) – Color for profiles in plot. In case of quality_colors=True, this is a list of np.ndarray[RGBA] for each profile – one color per profile point for each profile.

  • legend_text (str) – Label for line plots.

  • show_bounds (bool) – Whether to show, and extend the plot to, the lower and upper bounds.

  • lb_full (Sequence[float]) – Lower bound.

  • ub_full (Sequence[float]) – Upper bound.

  • plot_objective_values (bool) – Whether to plot the objective function values instead of the likelihood ratio values.

Return type:

list[Axes]

Returns:

The plot axes.

pypesto.visualize.projection_scatter_pca(pca_coordinates, components=(0, 1), **kwargs)[source]

Plot a scatter plot for PCA coordinates.

Creates either one or multiple scatter plots, depending on the number of coordinates passed to it.

Parameters:

  • pca_coordinates (ndarray) – array of pca coordinates (returned as first output by the routine get_pca_representation) to be shown as scatter plot

  • components (Sequence[int]) – Components to be plotted (corresponds to columns of pca_coordinates)

Return type:

Axes | ndarray

Returns:

axs – Either a single matplotlib Axes (2 components) or a 2-D NumPy array of Axes (more than 2 components).

pypesto.visualize.projection_scatter_umap(umap_coordinates, components=(0, 1), **kwargs)[source]

Plot a scatter plots for UMAP coordinates.

Creates either one or multiple scatter plots, depending on the number of coordinates passed to it.

Parameters:

  • umap_coordinates (ndarray) – array of umap coordinates (returned as first output by the routine get_umap_representation) to be shown as scatter plot

  • components (Sequence[int]) – Components to be plotted (corresponds to columns of umap_coordinates)

Return type:

Axes | ndarray

Returns:

axs – Either a single matplotlib Axes (2 components) or a 2-D NumPy array of Axes (more than 2 components).

pypesto.visualize.projection_scatter_umap_original(umap_object, color_by=None, components=(0, 1), ax=None, **kwargs)[source]

See projection_scatter_umap for more documentation.

Wrapper around umap.plot.points. Similar to projection_scatter_umap, but uses the original plotting routine from umap.plot.

Parameters:

  • umap_object (None) – umap object (returned as second output by get_umap_representation) to be shown as scatter plot

  • color_by (Sequence[float]) – A sequence/list of floats, which specify the color in the colormap

  • components (Sequence[int]) – Components to be plotted (corresponds to columns of umap_coordinates)

  • ax (Axes | None) – Axes object to use.

Return type:

Axes

Returns:

ax (matplotlib.axes.Axes) – The plot axes.

pypesto.visualize.sampling_1d_marginals(result, i_chain=0, parameter_indices=None, stepsize=1, plot_type='both', bw_method='scott', suptitle=None, size=None, axes=None, par_indices=<object object>)[source]

Plot marginals.

Parameters:

  • result (Result) – The pyPESTO result object with filled sample result.

  • i_chain (int) – Which chain to plot. Default: First chain.

  • parameter_indices (Sequence[int]) – List of integer values specifying which parameters to plot. Default: All parameters are shown.

  • stepsize (int) – Only one in stepsize values is plotted.

  • plot_type (str) – Specify whether to plot a histogram (‘hist’), a kernel density estimate (‘kde’), or both (‘both’).

  • bw_method (str) – Kernel bandwidth method.

  • suptitle (str | None) – Figure super title.

  • size (tuple[float, float] | None) – Figure size in inches.

  • axes (ndarray | None) – Axes grid to use. Must match the computed subplot layout.

  • par_indices (Sequence[int]) – Deprecated. Use parameter_indices instead.

Return type:

ndarray

Returns:

axes – 2-D NumPy array containing one matplotlib Axes per panel.

pypesto.visualize.sampling_fval_traces(result, i_chain=0, full_trace=False, stepsize=1, title=None, size=None, ax=None)[source]

Plot log-posterior (=function value) over iterations.

Parameters:

  • result (Result) – The pyPESTO result object with filled sample result.

  • i_chain (int) – Which chain to plot. Default: First chain.

  • full_trace (bool) – Plot the full trace including warm up. Default: False.

  • stepsize (int) – Only one in stepsize values is plotted.

  • title (str | None) – Axes title.

  • size (tuple[float, float] | None) – Figure size in inches.

  • ax (Axes | None) – Axes object to use.

Return type:

Axes

Returns:

ax – The plot axes.

pypesto.visualize.sampling_parameter_cis(result, confidence_levels=None, step=0.05, show_median=True, title=None, size=None, ax=None, alpha=None)[source]

Plot MCMC-based parameter credibility intervals.

Parameters:

  • result (Result) – The pyPESTO result object with filled sample result.

  • confidence_levels (Sequence[float]) – Credibility levels as fractions in (0, 1), e.g. [0.95] for a 95% credibility interval. Defaults to [0.95].

  • alpha (Sequence[int]) – Deprecated. Use confidence_levels instead. Previously accepted integer percentages (e.g. [95]); values are divided by 100 automatically during the transition.

  • step (float) – Height of boxes for projectile plot, defaults to 0.05.

  • show_median (bool) – Plot the median of the MCMC chain. Default: True.

  • title (str | None) – Axes title.

  • size (tuple[float, float] | None) – Figure size in inches.

  • ax (Axes | None) – Axes object to use.

Return type:

Axes

Returns:

ax – The plot axes.

pypesto.visualize.sampling_parameter_traces(result, i_chain=0, parameter_indices=None, full_trace=False, stepsize=1, use_problem_bounds=True, suptitle=None, size=None, axes=None, ax=<object object>, par_indices=<object object>)[source]

Plot parameter values over iterations.

Parameters:

  • result (Result) – The pyPESTO result object with filled sample result.

  • i_chain (int) – Which chain to plot. Default: First chain.

  • parameter_indices (Sequence[int]) – List of integer values specifying which parameters to plot. Default: All parameters are shown.

  • full_trace (bool) – Plot the full trace including warm up. Default: False.

  • stepsize (int) – Only one in stepsize values is plotted.

  • use_problem_bounds (bool) – Defines if the y-limits shall be the lower and upper bounds of parameter estimation problem.

  • suptitle (str | None) – Figure suptitle.

  • size (tuple[float, float] | None) – Figure size in inches.

  • axes (ndarray | None) – Axes grid to use. Must match the computed subplot layout.

  • ax (ndarray | None) – Deprecated. Use axes instead.

  • par_indices (Sequence[int]) – Deprecated. Use parameter_indices instead.

Return type:

ndarray

Returns:

axes – 2-D NumPy array containing one matplotlib Axes per panel.

pypesto.visualize.sampling_prediction_trajectories(ensemble_prediction, levels, title=None, size=None, axes=None, labels=None, axis_label_padding=50, groupby='condition', condition_gap=0.01, condition_ids=None, output_ids=None, weighting=False, reverse_opacities=False, average='median', add_sd=False, measurement_df=None)[source]

Visualize prediction trajectory of an EnsemblePrediction.

Plot MCMC-based prediction credibility intervals for the model states or outputs. One or various credibility levels can be depicted. Plots are grouped by condition.

Parameters:

  • ensemble_prediction (EnsemblePrediction) – The ensemble prediction.

  • levels (float | Sequence[float]) – Credibility levels, e.g. [95] for a 95% credibility interval. See the _get_level_percentiles() method for a description of how these levels are handled, and current limitations.

  • title (str | None) – Axes title.

  • size (tuple[float, float] | None) – Figure size in inches.

  • axes (Axes | ndarray | None) – Axes object to use.

  • labels (dict[str, str] | None) – Keys should be ensemble output IDs, values should be the desired label for that output. Defaults to output IDs.

  • axis_label_padding (int) – Pixels between axis labels and plots.

  • groupby (str) – Group plots by pypesto.C.OUTPUT or pypesto.C.CONDITION.

  • condition_gap (float) – Gap between conditions when groupby == pypesto.C.CONDITION.

  • condition_ids (Sequence[str]) – If provided, only data for the provided condition IDs will be plotted.

  • output_ids (Sequence[str]) – If provided, only data for the provided output IDs will be plotted.

  • weighting (bool) – Whether weights should be used for trajectory.

  • reverse_opacities (bool) – Whether to reverse the opacities that are assigned to different levels.

  • average (str) – The ID of the statistic that will be plotted as the average (e.g., MEDIAN or MEAN).

  • add_sd (bool) – Whether to add the standard deviation of the predictions to the plot.

  • measurement_df (DataFrame | None) – Plot measurement data. NB: This should take the form of a PEtab measurements table, and the observableId column should correspond to the output IDs in the ensemble prediction.

Return type:

ndarray

Returns:

axes – 2-D NumPy array containing one matplotlib Axes per panel.

pypesto.visualize.sampling_scatter(result, i_chain=0, stepsize=1, suptitle=None, diag_kind='kde', size=None, show_bounds=True, axes=None)[source]

Parameter scatter plot.

Parameters:

  • result (Result) – The pyPESTO result object with filled sample result.

  • i_chain (int) – Which chain to plot. Default: First chain.

  • stepsize (int) – Only one in stepsize values is plotted.

  • suptitle (str | None) – Figure super title.

  • diag_kind (str) – Visualization mode for marginal densities {‘auto’, ‘hist’, ‘kde’, None}

  • size (tuple[float, float] | None) – Figure size in inches.

  • show_bounds (bool) – Whether to show, and extend the plot to, the lower and upper bounds.

  • axes (ndarray | None)

Return type:

ndarray

Returns:

axes – 2-D NumPy array containing one matplotlib Axes per panel.

pypesto.visualize.visualize_2d_profile(result, profile_indices=None, size=None, profile_list_id=0, ratio_min=0.0, cmap='viridis', plot_objective_values=False, x_labels=None, profile_color=None, reference=None, label_fontsize=14)[source]

Create an n×n grid of profile plots.

Diagonal plots show 1D profiles (likelihood ratio vs. parameter value). Off-diagonal plots show the path of one parameter while another is profiled, with color indicating the likelihood ratio or objective value. Legend panels summarizing profile points and bound lines are drawn on the top-left diagonal and the first off-diagonal subplot.

Parameters:

  • result (Result) – A single pypesto.Result after profiling.

  • profile_indices (Sequence[int]) – List of integer indices specifying which parameters to include. If None, all parameters with computed profiles are included.

  • size (tuple[float, float]) – Figure size (width, height) in inches. If None, automatically sized based on number of parameters (3.5 inches per parameter).

  • profile_list_id (int) – Index of the profile list to visualize.

  • ratio_min (float) – Minimum ratio below which to cut off.

  • cmap (str) – Colormap to use for the 2D off-diagonal scatter plots.

  • plot_objective_values (bool) – Whether to plot the objective function values instead of the likelihood ratio values.

  • x_labels (Sequence[str]) – Labels for the parameters (indexed by full parameter index). If None, labels are auto-generated from parameter names and scales.

  • profile_color (str | tuple[float, float, float] | tuple[float, float, float, float] | ndarray | None) – Color for the diagonal 1D profile lines. Passed directly to profile_lowlevel(). If None, the default color is used.

  • reference (ReferencePoint | Sequence[ReferencePoint]) – List of reference points for optimization results, shown on diagonal 1D plots.

  • label_fontsize (int) – Font size for axis labels and the colorbar label. Tick labels are drawn two points smaller.

Return type:

tuple[Figure, ndarray]

Returns:

  • fig – The figure object.

  • axes – Array of axes objects (n×n grid).

pypesto.visualize.visualize_estimated_observable_mapping(pypesto_result, pypesto_problem, start_index=0, axes=None, **kwargs)[source]

Visualize the estimated observable mapping for relative and semi-quantitative observables.

Visualizes the estimated linear mapping for relative observables and the non-linear spline approximation for semi-quantitative observables.

Parameters:

  • pypesto_result (Result) – The pyPESTO result object from optimization.

  • pypesto_problem (HierarchicalProblem) – The pyPESTO problem. It should contain the objective object that was used for estimation.

  • start_index (int) – The observable mapping from this start’s optimized vector will be plotted.

  • axes (Axes | ndarray | None) – Optional axes grid to draw into.

  • kwargs – Additional arguments to passed to matplotlib.pyplot.subplots (e.g. figsize= …).

Return type:

ndarray | None

Returns:

axes – A 2-D NumPy array of matplotlib Axes, or None if the required simulation fails.

pypesto.visualize.waterfall(results, ax=None, size=(18.5, 10.5), y_limits=None, scale_y='log10', offset_y=None, start_indices=None, n_starts_to_zoom=0, reference=None, colors=None, legends=None, order_by_id=False)[source]

Plot waterfall plot.

Parameters:

  • results (Result | Sequence[Result]) – Optimization result obtained by ‘optimize.py’ or list of those

  • ax (Axes | None) – Axes object to use.

  • size (tuple[float, float] | None) – Figure size (width, height) in inches. Is only applied when no ax object is specified

  • y_limits (tuple[float] | None) – Maximum value to be plotted on the y-axis, or y-limits

  • scale_y (str | None) – May be logarithmic or linear (‘log10’ or ‘lin’)

  • offset_y (float | None) – Offset for the y-axis, if it is supposed to be in log10-scale

  • start_indices (Sequence[int] | int | None) – Integers specifying the multistart to be plotted or int specifying up to which start index should be plotted

  • n_starts_to_zoom (int) – Number of best multistarts that should be zoomed in. Should be smaller that the total number of multistarts

  • reference (Sequence[ReferencePoint] | None) – Reference points for optimization results, containing at least a function value fval

  • colors (str | tuple[float, float, float] | tuple[float, float, float, float] | list[str | tuple[float, float, float] | tuple[float, float, float, float]] | ndarray | None) – List of colors or single color for plotting. If not set, clustering is done and colors are assigned automatically

  • legends (Sequence[str] | str | None) – Labels for line plots, one label per result object

  • order_by_id (bool) – Function values corresponding to the same start ID will be located at the same x-axis position. Only applicable when a list of result objects are provided. Default behavior is to sort the function values of each result independently of other results.

Return type:

Axes

Returns:

ax (matplotlib.Axes) – The plot axes.

pypesto.visualize.waterfall_lowlevel(fvals, ax=None, size=(18.5, 10.5), scale_y='log10', offset_y=0.0, colors=None, legend_text=None)[source]

Plot waterfall plot using list of function values.

Parameters:

  • fvals – Including values need to be plotted. None values indicate that the corresponding start index should be skipped.

  • ax (Axes | None) – Axes object to use.

  • size (tuple[float, float] | None) – Figure size (width, height) in inches. Is only applied when no ax object is specified

  • scale_y (str) – May be logarithmic or linear (‘log10’ or ‘lin’)

  • offset_y (float) – offset for the y-axis, if it is supposed to be in log10-scale

  • colors (str | tuple[float, float, float] | tuple[float, float, float, float] | list[str | tuple[float, float, float] | tuple[float, float, float, float]] | ndarray | None) – Color recognized by matplotlib or list of colors for plotting. If not set, clustering is done and colors are assigned automatically

  • legend_text (str | None) – Label for line plots

Return type:

Axes

Returns:

ax (matplotlib.Axes) – The plot axes.