petab.visualize

Visualize

PEtab comes with visualization functionality. Those need to be imported via import petab.visualize.

class petab.visualize.DataProvider(exp_conditions: DataFrame, measurements_data: DataFrame | None = None, simulations_data: DataFrame | None = None)

Bases: object

Handles data selection.

get_data_series(data_df: DataFrame, data_col: Literal['measurement', 'simulation'], dataplot: DataPlot, provided_noise: bool) → DataSeries

Get data to plot from measurement or simulation DataFrame.

Parameters:

• data_df (measurement or simulation DataFrame)

• data_col (data column, i.e. 'measurement' or 'simulation')

• dataplot (visualization specification)

• provided_noise – True if numeric values for the noise level are provided in the data table

Return type:

Data to plot

get_data_to_plot(dataplot: DataPlot, provided_noise: bool) → Tuple[DataSeries, DataSeries]

Get data to plot.

Parameters:

• dataplot (visualization specification)

• provided_noise – True if numeric values for the noise level are provided in the measurement table

Returns:

• measurements_to_plot,

• simulations_to_plot

class petab.visualize.Figure(subplots: List[Subplot] | None = None, size: Tuple = [20, 15], title: Tuple | None = None)

Bases: object

Visualization specification of a figure.

Contains information regarding how data should be visualized.

add_subplot(subplot: Subplot) → None

Add subplot.

Parameters:

subplot – Subplot visualization settings.

save_to_tsv(output_file_path: str = 'visuSpec.tsv') → None

Save full Visualization specification table.

Note that datasetId column in the resulting table might have been generated even though datasetId column in Measurement table is missing or is different. Please, correct it manually.

Parameters:

output_file_path – File path to which the generated visualization specification is saved.

set_axes_limits(xlim: Tuple[Real | None, Real | None] | None = None, ylim: Tuple[Real | None, Real | None] | None = None) → None

Set axes limits for all subplots. If xlim or ylim or any of the tuple items is None, corresponding limit is left unchanged.

Parameters:

• xlim – X axis limits.

• ylim – Y axis limits.

class petab.visualize.MPLPlotter(figure: Figure, data_provider: DataProvider)

Bases: Plotter

Matplotlib wrapper

generate_barplot(ax: Axes, dataplot: DataPlot, plotTypeData: str) → None

Generate barplot.

Parameters:

• ax – Axis object.

• dataplot – Visualization settings for the plot.

• plotTypeData – Specifies how replicates should be handled.

generate_figure(subplot_dir: str | None = None, format_: str = 'png') → Dict[str, Axes] | None

Generate the full figure based on the markup in the figure attribute.

Parameters:

• subplot_dir – A path to the folder where single subplots should be saved. PlotIDs will be taken as file names.

• format – File format for the generated figure. (See matplotlib.pyplot.savefig() for supported options).

Returns:

• ax – Axis object of the created plot.

• None – In case subplots are saved to file.

generate_lineplot(ax: Axes, dataplot: DataPlot, plotTypeData: str, splitaxes_params: dict) → Tuple[Axes, Axes]

Generate line plot.

It is possible to plot only data or only simulation or both.

Parameters:

• ax – Axis object.

• dataplot – Visualization settings for the plot.

• plotTypeData – Specifies how replicates should be handled.

• splitaxes_params

generate_scatterplot(ax: Axes, dataplot: DataPlot, plotTypeData: str) → None

Generate scatterplot.

Parameters:

• ax – Axis object.

• dataplot – Visualization settings for the plot.

• plotTypeData – Specifies how replicates should be handled.

generate_subplot(fig: Figure, ax: Axes, subplot: Subplot) → None

Generate subplot based on markup provided by subplot.

Parameters:

• fig – Figure object.

• ax – Axis object.

• subplot – Subplot visualization settings.

petab.visualize.plot_goodness_of_fit(petab_problem: Problem, simulations_df: str | Path | DataFrame, size: Tuple = (10, 7), ax: Axes | None = None) → Axes

Plot goodness of fit.

Parameters:

• petab_problem – A PEtab problem.

• simulations_df – A simulation DataFrame in the PEtab format or path to the simulation output data file.

• size – Figure size.

• ax – Axis object.

Returns:

ax

Return type:

Axis object of the created plot.

petab.visualize.plot_problem(petab_problem: Problem, simulations_df: str | DataFrame | None = None, grouping_list: List[List[str]] | None = None, group_by: str = 'observable', plotted_noise: str = 'MeanAndSD', subplot_dir: str | None = None, plotter_type: str = 'mpl') → Dict[str, Axes] | None

Visualization using petab problem. If Visualization table is part of the petab_problem, it will be used for visualization. Otherwise, grouping_list will be used. If neither Visualization table nor grouping_list are available, measurements (simulations) will be grouped by observable, i.e. all measurements for each observable will be visualized on one plot.

Parameters:

• petab_problem – A PEtab problem.

• simulations_df – A simulation DataFrame in the PEtab format or path to the simulation output data file.

• grouping_list – A list of lists. Each sublist corresponds to a plot, each subplot contains the Ids of datasets or observables or simulation conditions for this plot.

• group_by – Possible values: ‘dataset’, ‘observable’, ‘simulation’.

• plotted_noise – A string indicating how noise should be visualized: [‘MeanAndSD’ (default), ‘MeanAndSEM’, ‘replicate’, ‘provided’].

• subplot_dir – A string which is taken as path to the folder where single subplots should be saved. PlotIDs will be taken as file names.

• plotter_type – Specifies which library should be used for plot generation. Currently, only matplotlib is supported.

Returns:

• ax (Axis object of the created plot.)

• None (In case subplots are saved to a file.)

petab.visualize.plot_residuals_vs_simulation(petab_problem: Problem, simulations_df: str | Path | DataFrame, size: Tuple | None = (10, 7), axes: Tuple[Axes, Axes] | None = None) → Axes

Plot residuals versus simulation values for measurements with normal noise assumption.

Parameters:

• petab_problem – A PEtab problem.

• simulations_df – A simulation DataFrame in the PEtab format or path to the simulation output data file.

• size – Figure size.

• axes – Axis object.

Returns:

ax

Return type:

Axis object of the created plot.

petab.visualize.plot_with_vis_spec(vis_spec_df: str | DataFrame, conditions_df: str | DataFrame, measurements_df: str | DataFrame | None = None, simulations_df: str | DataFrame | None = None, subplot_dir: str | None = None, plotter_type: str = 'mpl', format_: str = 'png') → Dict[str, Axes] | None

Plot measurements and/or simulations. Specification of the visualization routines is provided in visualization table.

Parameters:

• vis_spec_df – A visualization table.

• conditions_df – A condition DataFrame in the PEtab format or path to the condition file.

• measurements_df – A measurement DataFrame in the PEtab format or path to the data file.

• simulations_df – A simulation DataFrame in the PEtab format or path to the simulation output data file.

• subplot_dir – A path to the folder where single subplots should be saved. PlotIDs will be taken as file names.

• plotter_type – Specifies which library should be used for plot generation. Currently, only matplotlib is supported.

• format – File format for the generated figure. (See matplotlib.pyplot.savefig() for supported options).

Returns:

• ax (Axis object of the created plot.)

• None (In case subplots are saved to a file.)

petab.visualize.plot_without_vis_spec(conditions_df: str | DataFrame, grouping_list: List[List[str]] | None = None, group_by: str = 'observable', measurements_df: str | DataFrame | None = None, simulations_df: str | DataFrame | None = None, plotted_noise: str = 'MeanAndSD', subplot_dir: str | None = None, plotter_type: str = 'mpl', format_: str = 'png') → Dict[str, Axes] | None

Plot measurements and/or simulations. What exactly should be plotted is specified in a grouping_list. If grouping list is not provided, measurements (simulations) will be grouped by observable, i.e. all measurements for each observable will be visualized on one plot.

Parameters:

• grouping_list – A list of lists. Each sublist corresponds to a plot, each subplot contains the Ids of datasets or observables or simulation conditions for this plot.

• group_by – Grouping type. Possible values: ‘dataset’, ‘observable’, ‘simulation’.

• conditions_df – A condition DataFrame in the PEtab format or path to the condition file.

• measurements_df – A measurement DataFrame in the PEtab format or path to the data file.

• simulations_df – A simulation DataFrame in the PEtab format or path to the simulation output data file.

• plotted_noise – A string indicating how noise should be visualized: [‘MeanAndSD’ (default), ‘MeanAndSEM’, ‘replicate’, ‘provided’].

• subplot_dir – A path to the folder where single subplots should be saved. PlotIDs will be taken as file names.

• plotter_type – Specifies which library should be used for plot generation. Currently, only matplotlib is supported.

• format – File format for the generated figure. (See matplotlib.pyplot.savefig() for supported options).

Returns:

• ax (Axis object of the created plot.)

• None (In case subplots are saved to a file.)

Modules

petab.visualize.cli	Command-line interface for visualization.
petab.visualize.data_overview	Functions for creating an overview report of a PEtab problem
petab.visualize.helper_functions	This file should contain the functions, which PEtab internally needs for plotting, but which are not meant to be used by non-developers and should hence not be directly visible/usable when using import petab.visualize.
petab.visualize.lint	Validation of PEtab visualization files
petab.visualize.plot_data_and_simulation	Functions for plotting PEtab measurement files and simulation results in the same format.
petab.visualize.plot_residuals	Functions for plotting residuals.
petab.visualize.plotter	PEtab visualization plotter classes
petab.visualize.plotting	PEtab visualization data selection and visualization settings classes