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_independent_var_values(data_df: DataFrame, dataplot: DataPlot) → Tuple[ndarray, str, Series]

Get independent variable values.

Parameters:

• data_df – A pandas data frame to subset, can be from measurement file or simulation file.

• dataplot – Data plot visualization settings.

Returns:

• col_name_unique – A name of the column from Measurement (Simulation) table, which specifies independent variable values (depends on the xValues entry of visualization specification). Possible values:

  • TIME (independent variable values will be taken from the TIME column of Measurement (Simulation) table)

  • SIMULATION_CONDITION_ID (independent variable values will be taken from one of the columns of Condition table)

• uni_condition_id – Time points or contains all unique condition IDs which should be plotted together as one dataplot. Independent variable values will be collected for these conditions

• conditions_ – An independent variable values or None for the BarPlot case possible values: time points, None, vales of independent variable (Parameter or Species, specified in the xValues entry of visualization specification) for each condition_id in uni_condition_id

static _matches_plot_spec(df: DataFrame, plot_spec: DataPlot, dataset_id) → Series

Construct an index for subsetting of the dataframe according to what is specified in plot_spec.

Parameters:

• df – A pandas data frame to subset, can be from measurement file or simulation file.

• plot_spec – A visualization spec from the visualization file.

Returns:

• Boolean series that can be used for subsetting of the passed

• dataframe

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

static _error_column_for_plot_type_data(plot_type_data: str) → str | None

Translate PEtab plotTypeData value to column name of internal data representation

Parameters:

• plot_type_data (PEtab plotTypeData value (the way replicates) –

• handled) (should be) –

Return type:

Name of corresponding column

static _line_plot_at_t_inf(ax: Axes, plotTypeData: str, measurements_to_plot: DataSeries, simulations_to_plot: DataSeries, noise_col: str, label_base: str, split_axes_params: dict, color=None) → Tuple[Axes, Axes]

Plot data at t=inf.

Parameters:

• ax – Axis object for the data corresponding to the finite timepoints.

• plotTypeData – The way replicates should be handled.

• measurements_to_plot – Measurements to plot.

• simulations_to_plot – Simulations to plot.

• noise_col – The name of the error column for plot_type_data.

• label_base – Label base.

• split_axes_params – A dictionary of split axes parameters with - Axis object for the data corresponding to t=inf - Time value that represents t=inf - left and right limits for the axis where the data corresponding to the finite timepoints is plotted

• color – Line color.

Returns:

• Two axis objects (for the data corresponding to the finite timepoints)

• and for the data corresponding to t=inf

static _postprocess_splitaxes(ax: Axes, ax_inf: Axes, t_inf: float) → None

Postprocess the splitaxes: set axes limits, turn off unnecessary ticks and plot dashed lines highlighting the gap in the x axis.

Parameters:

• ax – Axis object for the data corresponding to the finite timepoints.

• ax_inf – Axis object for the data corresponding to t=inf.

• t_inf – Time value that represents t=inf

_preprocess_splitaxes(fig: Figure, ax: Axes, subplot: Subplot) → Dict

Prepare splitaxes if data at t=inf should be plotted: compute left and right limits for the axis where the data corresponding to the finite timepoints will be plotted, compute time point that will represent t=inf on the plot, create additional axes for plotting data at t=inf.

static _square_plot_equal_ranges(ax: Axes, lim: List | Tuple | None = None) → Axes

Square plot with equal range for scatter plots.

Return type:

Updated axis object.

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

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