petab.visualize.plotting

PEtab visualization data selection and visualization settings classes

Classes

DataPlot(plot_settings)

Visualization specification of a plot of one data series, e.g. for an individual line on a subplot.

DataProvider(exp_conditions[, ...])

Handles data selection.

DataSeries(conditions_[, data_to_plot])

Data for one individual line

Figure([subplots, size, title])

Visualization specification of a figure.

Subplot(plot_id, plot_settings[, dataplots])

Visualization specification of a subplot.

VisSpecParser(conditions_data[, exp_data, ...])

Parser of visualization specification provided by user either in the form of Visualization table or as a list of lists with datasets ids or observable ids or condition ids.
class petab.visualize.plotting.DataPlot(plot_settings: dict)[source]

Bases: object

Visualization specification of a plot of one data series, e.g. for an individual line on a subplot.

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

Bases: object

Handles data selection.

_get_independent_var_values(data_df: DataFrame, dataplot: DataPlot) → Tuple[ndarray, str, Series][source]

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

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

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

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.plotting.DataSeries(conditions_: ndarray | Series | None, data_to_plot: DataFrame | None = None)[source]

Bases: object

Data for one individual line

add_offsets(x_offset=0, y_offset=0) → None[source]

Data offsets.

Parameters:

  • x_offset – Offset for the independent variable.

  • y_offset – Offsets for the observable.

add_x_offset(offset) → None[source]

Offset for the independent variable.

Parameters:

offset – Offset value.

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

Bases: object

Visualization specification of a figure.

Contains information regarding how data should be visualized.

add_subplot(subplot: Subplot) → None[source]

Add subplot.

Parameters:

subplot – Subplot visualization settings.

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

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

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.plotting.Subplot(plot_id: str, plot_settings: dict, dataplots: List[DataPlot] | None = None)[source]

Bases: object

Visualization specification of a subplot.

add_dataplot(dataplot: DataPlot) → None[source]

Add data plot.

Parameters:

dataplot – Data plot visualization settings.

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

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.plotting.VisSpecParser(conditions_data: str | Path | DataFrame, exp_data: str | Path | DataFrame | None = None, sim_data: str | Path | DataFrame | None = None)[source]

Bases: object

Parser of visualization specification provided by user either in the form of Visualization table or as a list of lists with datasets ids or observable ids or condition ids. Figure instance is created containing information regarding how data should be visualized. In addition to the Figure instance, a DataProvider instance is created that will be responsible for the data selection and manipulation.

_add_dataset_id_col() → None[source]

Add dataset_id column to the measurement table and simulations table (possibly overwrite).

_create_legend(dataset_id: str) → str[source]

Create a legend for the dataset ids.

Parameters:

dataset_id – Dataset id.

Return type:

A legend.

_expand_vis_spec_settings(vis_spec: DataFrame)[source]

Expand visualization specification for the case when DATASET_ID is not in vis_spec.columns.

Parameters:

vis_spec – Visualization specification DataFrame in the PEtab format or a path to a visualization file.

Return type:

A visualization specification DataFrame.

_get_vis_spec_dependent_columns_dict(group_by: str, id_list: List[List[str]] | None = None) → Dict[source]

Helper method for creating values for columns PLOT_ID, DATASET_ID, LEGEND_ENTRY, Y_VALUES for visualization specification file.

Parameters:

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

  • id_list – Grouping list. Each sublist corresponds to a subplot and contains the Ids of datasets or observables or simulation conditions for this subplot.

Return type:

A dictionary with values for columns PLOT_ID, DATASET_ID, LEGEND_ENTRY, Y_VALUES for visualization specification.

_vis_spec_rows_for_obs(obs_id: str, settings: dict) → DataFrame[source]

Create vis_spec for one observable.

For each dataset_id corresponding to the observable with the specified id create a vis_spec entry with provided settings.

Parameters:

  • obs_id – Observable ID.

  • settings – Additional visualization settings. For each key that is a valid visualization specification column name, the setting will be added to the resulting visualization specification.

Return type:

A visualization specification DataFrame.

static create_subplot(plot_id: str, subplot_vis_spec: DataFrame) → Subplot[source]

Create subplot.

Parameters:

  • plot_id – Plot id.

  • subplot_vis_spec – A visualization specification DataFrame that contains specification for the subplot and corresponding dataplots.

Return type:

Subplot

parse_from_id_list(ids_per_plot: List[List[str]] | None = None, group_by: str = 'observable', plotted_noise: str | None = 'MeanAndSD') → Tuple[Figure, DataProvider][source]

Get visualization settings from a list of ids and a grouping parameter.

Parameters:

  • ids_per_plot –

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

    dataset_ids_per_plot = [['dataset_1', 'dataset_2'],
                        ['dataset_1', 'dataset_4',
                         'dataset_5']]

    or

    cond_id_list = [['model1_data1'],
                ['model1_data2', 'model1_data3'],
                ['model1_data4', 'model1_data5'],
                ['model1_data6']].

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

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

Return type:

A figure template with visualization settings and a data provider

parse_from_vis_spec(vis_spec: str | Path | DataFrame | None) → Tuple[Figure, DataProvider][source]

Get visualization settings from a visualization specification.

Parameters:

vis_spec – Visualization specification DataFrame in the PEtab format or a path to a visualization file.

Return type:

A figure template with visualization settings and a data provider