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, **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

Returns:

axs – A dictionary of plot axes.

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] | None) – Figure size (width, height) in inches. Is only applied when no ax object is specified

Returns:

ax (matplotlib.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] | 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

Returns:

ax (matplotlib.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')[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

  • 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')[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’

Return type:

dict[str, Axes]

Returns:

  • ax

  • The plot axes.

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 | 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:

Axes

Returns:

axes – The plot axes.

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

Plot a scatter plot of all pairs of parameters 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) – Visualization mode for marginal densities {‘auto’, ‘hist’, ‘kde’, None}.

  • suptitle (str) – Title of the plot.

  • size (tuple[float, float]) – Size of the plot.

  • show_bounds (bool) – Whether to show the parameter bounds.

Returns:

ax – The plot axis.

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]) – 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) – 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 – Optimization result obtained by ‘optimize.py’

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

  • bins – Specifies bins of the histogram

  • ax – Axes object to use

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

  • color – Color recognized by matplotlib.

  • start_indices – List of integers specifying the multistarts to be plotted or int specifying up to which start index should be plotted

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)[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 are pearson, kendall, spearman or a callable function.

  • 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.

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 (Axes | None) – The axes to plot the linear observable mappings on.

  • 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 matplotlib.pyplot.subplots function.

Returns:

axes – The 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 – The axes to plot the estimated spline approximations on.

  • rel_and_semiquant_obs_indices – 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.

Returns:

axes – The matplotlib axes.

pypesto.visualize.plot_splines_from_pypesto_result(pypesto_result, start_index=0, **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.

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

Returns:

axes – The matplotlib axes.

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) – 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:

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

  • 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.

  • color (str | tuple[float, float, float] | tuple[float, float, float, float] | ndarray | None) – Color for profiles in plot. A single color or an array of RGBA for each profile point

  • legend_text (str) – Label for line plots.

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

  • lb (float) – Lower bound.

  • ub (float) – Upper bound.

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. 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) – Axes object to use. Default: Create a new one.

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

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, 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 – 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 ratio below which to cut off.

  • 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)

Returns:

axs – Either one axes object, or a dictionary of plot axes (depending on the number of coordinates passed)

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)

Returns:

axs – Either one axes object, or a dictionary of plot axes (depending on the number of coordinates passed)

pypesto.visualize.projection_scatter_umap_original(umap_object, color_by=None, components=(0, 1), **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)

Returns:

ax (matplotlib.Axes) – The plot axes.

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

Plot marginals.

Parameters:

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

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

  • par_indices (list of integer values) – 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 ({'hist'|'kde'|'both'}) – Specify whether to plot a histogram (‘hist’), a kernel density estimate (‘kde’), or both (‘both’).

  • bw_method ({'scott', 'silverman' | scalar | pair of scalars}) – Kernel bandwidth method.

  • suptitle (str) – Figure super title.

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

Returns:

ax – matplotlib-axes

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) – Axes title.

  • size (ndarray) – Figure size in inches.

  • ax (Axes) – Axes object to use.

Returns:

ax – The plot axes.

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

Plot MCMC-based parameter credibility intervals.

Parameters:

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

  • alpha (Sequence[int]) – List of lower tail probabilities, defaults to 95% interval.

  • 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) – Axes title.

  • size (ndarray) – Figure size in inches.

  • ax (Axes) – Axes object to use.

Return type:

Axes

Returns:

ax – The plot axes.

pypesto.visualize.sampling_parameter_traces(result, i_chain=0, par_indices=None, full_trace=False, stepsize=1, use_problem_bounds=True, suptitle=None, size=None, ax=None)[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.

  • par_indices (list of integer values) – 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) – Figure suptitle.

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

  • ax (Axes) – Axes object to use.

Returns:

ax – The plot axes.

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) – Axes title.

  • size (ndarray) – Figure size in inches.

  • axes (Axes) – Axes object to use.

  • labels (dict[str, str]) – 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) – 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:

Axes

Returns:

axes – The plot axes.

pypesto.visualize.sampling_scatter(result, i_chain=0, stepsize=1, suptitle=None, diag_kind='kde', size=None, show_bounds=True)[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) – Figure super title.

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

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

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

Returns:

ax – The plot axes.

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)[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.

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 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.

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 | None) – The axes to plot the estimated observable mapping on.

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

Returns:

axes – The matplotlib axes.

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 (matplotlib.Axes, optional) – 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 (float or ndarray, optional) – 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.

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] | 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

Returns:

ax (matplotlib.Axes) – The plot axes.