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.

Functions

check_ex_exp_columns(exp_data, ...[, sim])	Check the columns in measurement file, if non-mandotory columns does not exist, create default columns
check_ex_visu_columns(vis_spec, exp_data, ...)	Check the columns in Visu_Spec file, if non-mandotory columns does not exist, create default columns
check_vis_spec_consistency(exp_data[, ...])	Helper function for plotting data and simulations, which checks the visualization setting, if no visualization specification file is provided.
create_dataset_id_list(simcond_id_list, ...)	Create dataset id list and corresponding plot legends.
create_dataset_id_list_new(df, group_by, id_list)	Create dataset ID list from a list of simulation condition IDs or observable IDs.
create_figure(uni_plot_ids, plots_to_file)	Helper function for plotting data and simulations, open figure and axes
create_or_update_vis_spec(exp_data, ...[, ...])	Helper function for plotting data and simulations, which updates vis_spec file if necessary or creates a default visualization table and updates/creates DATASET_ID column of exp_data.
expand_vis_spec_settings(vis_spec, columns_dict)	Expand visualization specification.
generate_dataset_id_col(exp_data)	Generate DATASET_ID column from condition_ids and observable_ids.
get_data_to_plot(plot_spec, m_data, ...[, ...])	Group the data, which should be plotted and return it as dataframe.
get_default_vis_specs(exp_data, exp_conditions)	Helper function for plotting data and simulations, which creates a default visualization table and updates/creates DATASET_ID column of exp_data
get_vis_spec_dependent_columns_dict(...[, ...])	Helper function for creating values for columns PLOT_ID, DATASET_ID, LEGEND_ENTRY, Y_VALUES for visualization specification file.
handle_dataset_plot(plot_spec, ax, exp_data, ...)	Handle dataset plot
import_from_files(data_file_path, ...[, ...])	Helper function for plotting data and simulations, which imports data from PEtab files.
matches_plot_spec(df, col_id, x_value, plot_spec)	Constructs an index for subsetting of the dataframe according to what is specified in plot_spec.

petab.visualize.helper_functions.check_ex_exp_columns(exp_data: pandas.core.frame.DataFrame, dataset_id_list: List[List[str]], sim_cond_id_list: List[List[str]], sim_cond_num_list: List[List[int]], observable_id_list: List[List[str]], observable_num_list: List[List[int]], exp_conditions: pandas.core.frame.DataFrame, sim: Optional[bool] = False) → Tuple[pandas.core.frame.DataFrame, List[List[str]], Dict]

Check the columns in measurement file, if non-mandotory columns does not exist, create default columns

Returns

A tuple of experimental DataFrame, list of datasetIds and dictionary of plot legends, corresponding to the datasetIds

petab.visualize.helper_functions.check_ex_visu_columns(vis_spec: pandas.core.frame.DataFrame, exp_data: pandas.core.frame.DataFrame, exp_conditions: pandas.core.frame.DataFrame) → pandas.core.frame.DataFrame

Check the columns in Visu_Spec file, if non-mandotory columns does not exist, create default columns

Returns

Updated visualization specification DataFrame

petab.visualize.helper_functions.check_vis_spec_consistency(exp_data: pandas.core.frame.DataFrame, dataset_id_list: Optional[List[List[str]]] = None, sim_cond_id_list: Optional[List[List[str]]] = None, sim_cond_num_list: Optional[List[List[int]]] = None, observable_id_list: Optional[List[List[str]]] = None, observable_num_list: Optional[List[List[int]]] = None) → str

Helper function for plotting data and simulations, which checks the visualization setting, if no visualization specification file is provided.

For documentation, see main function plot_data_and_simulation()

Returns

Specifies the grouping of data to plot.

petab.visualize.helper_functions.create_dataset_id_list(simcond_id_list: List[List[str]], simcond_num_list: List[List[int]], observable_id_list: List[List[str]], observable_num_list: List[List[int]], exp_data: pandas.core.frame.DataFrame, exp_conditions: pandas.core.frame.DataFrame, group_by: str) → Tuple[pandas.core.frame.DataFrame, List[List[str]], Dict, Dict]

Create dataset id list and corresponding plot legends. Additionally, update/create DATASET_ID column of exp_data

Parameters

group_by – defines grouping of data to plot

Returns

A tuple of experimental DataFrame, list of datasetIds and dictionary of plot legends, corresponding to the datasetIds

For additional documentation, see main function plot_data_and_simulation()

petab.visualize.helper_functions.create_dataset_id_list_new(df: pandas.core.frame.DataFrame, group_by: str, id_list: List[List[str]]) → List[List[str]]

Create dataset ID list from a list of simulation condition IDs or observable IDs.

Parameters

• df – Measurements or simulations DataFrame.

• group_by – Defines grouping of data to plot.

• id_list – Grouping list. Each sublist corresponds to a subplot in a figure, and contains the IDs of observables or simulation conditions for the subplot.

Returns

A list of datasetIds

petab.visualize.helper_functions.create_figure(uni_plot_ids: numpy.ndarray, plots_to_file: bool) → Tuple[matplotlib.figure.Figure, Union[Dict[str, matplotlib.axes._subplots.AxesSubplot], np.ndarray[plt.Subplot]]]

Helper function for plotting data and simulations, open figure and axes

Parameters

• uni_plot_ids – Array with unique plot indices

• plots_to_file – Indicator if plots are saved to file

Returns

• fig (Figure object of the created plot.)

• ax (Axis object of the created plot.)

petab.visualize.helper_functions.create_or_update_vis_spec(exp_data: pandas.core.frame.DataFrame, exp_conditions: pandas.core.frame.DataFrame, vis_spec: Optional[pandas.core.frame.DataFrame] = None, dataset_id_list: Optional[List[List[str]]] = None, sim_cond_id_list: Optional[List[List[str]]] = None, sim_cond_num_list: Optional[List[List[int]]] = None, observable_id_list: Optional[List[List[str]]] = None, observable_num_list: Optional[List[List[int]]] = None, plotted_noise: Optional[str] = 'MeanAndSD')

Helper function for plotting data and simulations, which updates vis_spec file if necessary or creates a default visualization table and updates/creates DATASET_ID column of exp_data. As a result, a visualization specification file exists with columns PLOT_ID, DATASET_ID, Y_VALUES and LEGEND_ENTRY

Returns

A tuple of visualization specification DataFrame and experimental DataFrame.

petab.visualize.helper_functions.expand_vis_spec_settings(vis_spec: pandas.core.frame.DataFrame, columns_dict)

Expand visualization specification. only makes sense if DATASET_ID is not in vis_spec.columns?

Parameters

• vis_spec (A visualization specification DataFrame.) –

• columns_dict –

Return type

Expanded visualization specification DataFrame

petab.visualize.helper_functions.generate_dataset_id_col(exp_data: pandas.core.frame.DataFrame) → List[str]

Generate DATASET_ID column from condition_ids and observable_ids.

Parameters

exp_data – A measurement (simulation) DataFrame in the PEtab format.

Returns

• A list with generated datasetIds for each entry in the measurement

• (simulation) DataFrame

petab.visualize.helper_functions.get_data_to_plot(plot_spec: pandas.core.series.Series, m_data: pandas.core.frame.DataFrame, simulation_data: pandas.core.frame.DataFrame, condition_ids: numpy.ndarray, col_id: str, simulation_field: str = 'simulation') → pandas.core.frame.DataFrame

Group the data, which should be plotted and return it as dataframe.

Parameters

• plot_spec – information about contains defined data format (visualization file)

• m_data – contains defined data format (measurement file)

• simulation_data – contains defined data format (simulation file)

• condition_ids – contains all unique condition IDs which should be plotted in one figure (can be found in measurementData file, column simulationConditionId)

• col_id – the name of the column in visualization file, whose entries should be unique (depends on condition in column xValues)

• simulation_field – Column name in simulation_data that contains the actual simulation result.

Returns

Contains the data which should be plotted (Mean and Std)

petab.visualize.helper_functions.get_default_vis_specs(exp_data: pandas.core.frame.DataFrame, exp_conditions: pandas.core.frame.DataFrame, dataset_id_list: Optional[List[List[str]]] = None, sim_cond_id_list: Optional[List[List[str]]] = None, sim_cond_num_list: Optional[List[List[int]]] = None, observable_id_list: Optional[List[List[str]]] = None, observable_num_list: Optional[List[List[int]]] = None, plotted_noise: Optional[str] = 'MeanAndSD') → Tuple[pandas.core.frame.DataFrame, pandas.core.frame.DataFrame]

Helper function for plotting data and simulations, which creates a default visualization table and updates/creates DATASET_ID column of exp_data

Returns

A tuple of visualization specification DataFrame and experimental DataFrame.

For documentation, see main function plot_data_and_simulation()

petab.visualize.helper_functions.get_vis_spec_dependent_columns_dict(exp_data: pandas.core.frame.DataFrame, exp_conditions: pandas.core.frame.DataFrame, dataset_id_list: Optional[List[List[str]]] = None, sim_cond_id_list: Optional[List[List[str]]] = None, sim_cond_num_list: Optional[List[List[int]]] = None, observable_id_list: Optional[List[List[str]]] = None, observable_num_list: Optional[List[List[int]]] = None) → Tuple[pandas.core.frame.DataFrame, Dict]

Helper function for creating values for columns PLOT_ID, DATASET_ID, LEGEND_ENTRY, Y_VALUES for visualization specification file. DATASET_ID column of exp_data is updated accordingly.

Returns

A tuple of experimental DataFrame and a dictionary with values for columns PLOT_ID, DATASET_ID, LEGEND_ENTRY, Y_VALUES for visualization specification file.

petab.visualize.helper_functions.handle_dataset_plot(plot_spec: pandas.core.series.Series, ax: matplotlib.axes._axes.Axes, exp_data: pandas.core.frame.DataFrame, exp_conditions: pandas.core.frame.DataFrame, sim_data: pandas.core.frame.DataFrame)

Handle dataset plot

petab.visualize.helper_functions.import_from_files(data_file_path: str, condition_file_path: str, simulation_file_path: str, dataset_id_list: List[List[str]], sim_cond_id_list: List[List[str]], sim_cond_num_list: List[List[int]], observable_id_list: List[List[str]], observable_num_list: List[List[int]], plotted_noise: str, visualization_file_path: Optional[str] = None) → Tuple[pandas.core.frame.DataFrame, pandas.core.frame.DataFrame, pandas.core.frame.DataFrame, pandas.core.frame.DataFrame]

Helper function for plotting data and simulations, which imports data from PEtab files. If visualization_file_path is not provided, the visualization specification DataFrame will be generated automatically.

For documentation, see main function plot_data_and_simulation()

Returns

A tuple of experimental data, experimental conditions, visualization specification and simulation data DataFrames.

petab.visualize.helper_functions.matches_plot_spec(df: pandas.core.frame.DataFrame, col_id: str, x_value: Union[float, str], plot_spec: pandas.core.series.Series) → pandas.core.series.Series

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

Parameters

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

• col_id – name of the column that will be used for indexing in x variable

• x_value – subsetted x value

• plot_spec – visualization spec from the visualization file

Returns

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