spinetoolbox.plotting

Functions for plotting on PlotWidget.

Currently plotting from the table views found in the SpineDBEditor are supported.

The main entrance points to plotting are: - plot_selection() which plots selected cells on a table view returning a PlotWidget object - plot_pivot_column() which is a specialized method for plotting entire columns of a pivot table - add_time_series_plot() which adds a time series plot to an existing PlotWidget - add_map_plot() which adds a map plot to an existing PlotWidget

author

1. Soininen(VTT)

date

9.7.2019

Module Contents

Classes

PlottingHints	A base class for plotting hints.
ParameterTablePlottingHints	Support for plotting data in Parameter table views.
PivotTablePlottingHints	Support for plotting data in Tabular view.

Functions

plot_pivot_column(proxy_model, column, hints, plot_widget=None)	Returns a plot widget with a plot of an entire column in PivotTableModel.
plot_selection(model, indexes, hints, plot_widget=None)	Returns a plot widget with plots of the selected indexes.
add_array_plot(plot_widget, value, label=None)	Adds an array plot to a plot widget.
add_map_plot(plot_widget, map_value, label=None)	Adds a map plot to a plot widget.
add_time_series_plot(plot_widget, value, label=None)	Adds a time series step plot to a plot widget.
_add_plot_to_widget(values, labels, plot_widget)	Adds a new plot to plot_widget.
_raise_if_not_all_indexed_values(values)	Raises an exception if not all values are TimeSeries or Maps.
_filter_name_columns(selections)	Returns a dict with all but the entry with the greatest key removed.
_organize_selection_to_columns(indexes)	Organizes a list of model indexes into a dictionary of {column: (rows)} entries.
_collect_single_column_values(model, column, rows, hints)	Collects selected parameter values from a single column.
_collect_x_column_values(model, column, rows, hints)	Collects selected parameter values from an x column.
_collect_index_column_values(model, column, rows, hints)	Collects selected values from an index column.
_collect_column_values(model, column, rows, hints)	Collects selected parameter values from a single column for plotting.
_expand_maps(maps, labels)	Gathers the leaf elements from maps and expands labels accordingly.
_label_nested_maps(map_, label)	Collects leaf values from given Maps and labels them.
_filter_and_check(xs, ys)	Filters Nones and empty values from x and y and checks that data types match.
_raise_if_indexed_values_not_plottable(values)	Raises an exception if the indexed values in values contain elements that cannot be plotted.
_raise_if_value_types_clash(values, plot_widget)	Raises a PlottingError if values type is incompatible with plot_widget.
_x_values_from_rows(model, rows, hints)	Returns x value array constructed from model rows.

exception spinetoolbox.plotting.PlottingError(message)

Bases: Exception

An exception signalling failure in plotting.

Parameters

message (str) – an error message

property message(self)

str: the error message.

spinetoolbox.plotting.plot_pivot_column(proxy_model, column, hints, plot_widget=None)

Returns a plot widget with a plot of an entire column in PivotTableModel.

Parameters

• proxy_model (PivotTableSortFilterProxy) – a pivot table filter

• column (int) – a column index to the model

• hints (PlottingHints) – a helper needed for e.g. plot labels

• plot_widget (PlotWidget) – an existing plot widget to draw into or None to create a new widget

Returns

a plot widget

Return type

PlotWidget

spinetoolbox.plotting.plot_selection(model, indexes, hints, plot_widget=None)

Returns a plot widget with plots of the selected indexes.

Parameters

• model (QAbstractTableModel) – a model

• indexes (Iterable) – a list of QModelIndex objects for plotting

• hints (PlottingHints) – a helper needed for e.g. plot labels

• plot_widget (PlotWidget) – an existing plot widget to draw into or None to create a new widget

Returns

a PlotWidget object

spinetoolbox.plotting.add_array_plot(plot_widget, value, label=None)

Adds an array plot to a plot widget.

Parameters

• plot_widget (PlotWidget) – a plot widget to modify

• value (Array) – the array to plot

• label (str) – a label for the array

spinetoolbox.plotting.add_map_plot(plot_widget, map_value, label=None)

Adds a map plot to a plot widget.

Parameters

• plot_widget (PlotWidget) – a plot widget to modify

• map_value (Map) – the map to plot

• label (str) – a label for the map

spinetoolbox.plotting.add_time_series_plot(plot_widget, value, label=None)

Adds a time series step plot to a plot widget.

Parameters

• plot_widget (PlotWidget) – a plot widget to modify

• value (TimeSeries) – the time series to plot

• label (str) – a label for the time series

class spinetoolbox.plotting.PlottingHints

A base class for plotting hints.

The functionality in this class allows the plotting functions to work without explicit knowledge of the underlying table model or widget.

abstract cell_label(self, model, index)

Returns a label for the cell given by index in a table.

abstract column_label(self, model, column)

Returns a label for a column.

abstract filter_columns(self, selections, model)

Filters columns and returns the filtered selections.

abstract is_index_in_data(self, model, index)

Returns true if the cell given by index is actually plottable data.

static normalize_row(row, model)

Returns a ‘human understandable’ row number

abstract special_x_values(self, model, column, rows)

Returns X values if available, otherwise returns None.

abstract x_label(self, model)

Returns a label for the x axis.

class spinetoolbox.plotting.ParameterTablePlottingHints

Bases: PlottingHints

Support for plotting data in Parameter table views.

cell_label(self, model, index)

Returns a label build from the columns on the left from the data column.

column_label(self, model, column)

Returns the column header.

filter_columns(self, selections, model)

Returns the ‘value’ or ‘default_value’ column only.

is_index_in_data(self, model, index)

Always returns True.

special_x_values(self, model, column, rows)

Always returns None.

x_label(self, model)

Returns an empty string for the x axis label.

class spinetoolbox.plotting.PivotTablePlottingHints

Bases: PlottingHints

Support for plotting data in Tabular view.

cell_label(self, model, index)

Returns a label for the table cell given by index.

column_label(self, model, column)

Returns a label for a table column.

filter_columns(self, selections, model)

Filters the X column from selections.

is_index_in_data(self, model, index)

Returns True if index is in the data portion of the table.

static normalize_row(row, model)

See base class.

special_x_values(self, model, column, rows)

Returns the values from the X column if one is designated otherwise returns None.

x_label(self, model)

Returns the label of the X column, if available.

static _map_column_to_source(proxy_model, proxy_column)

Maps a proxy model column to source model.

static _map_column_from_source(proxy_model, source_column)

Maps a source model column to proxy model.

spinetoolbox.plotting._add_plot_to_widget(values, labels, plot_widget)

Adds a new plot to plot_widget.

spinetoolbox.plotting._raise_if_not_all_indexed_values(values)

Raises an exception if not all values are TimeSeries or Maps.

spinetoolbox.plotting._filter_name_columns(selections)

Returns a dict with all but the entry with the greatest key removed.

spinetoolbox.plotting._organize_selection_to_columns(indexes)

Organizes a list of model indexes into a dictionary of {column: (rows)} entries.

spinetoolbox.plotting._collect_single_column_values(model, column, rows, hints)

Collects selected parameter values from a single column.

The return value of this function depends on what type of data the given column contains. In case of plain numbers, a list of scalars and a single label string are returned. In case of indexed parameters (time series, maps), a list of parameter_value objects is returned, accompanied by a list of labels, each label corresponding to one of the indexed parameters.

Parameters

• model (QAbstractTableModel) – a table model

• column (int) – a column index to the model

• rows (Sequence) – row indexes to plot

• hints (PlottingHints) – a plot support object

Returns

values and label(s)

Return type

tuple

spinetoolbox.plotting._collect_x_column_values(model, column, rows, hints)

Collects selected parameter values from an x column.

Parameters

• model (QAbstractTableModel) – a table model

• column (int) – a column index to the model

• rows (Sequence) – row indexes to plot

• hints (PlottingHints) – a plot support object

Returns

a tuple of values and label(s)

spinetoolbox.plotting._collect_index_column_values(model, column, rows, hints)

Collects selected values from an index column.

Parameters

• model (QAbstractTableModel) – a table model

• column (int) – a column index to the model

• rows (Sequence) – row indexes to plot

• hints (PlottingHints) – a plot support object

Returns

column’s values

Return type

list

spinetoolbox.plotting._collect_column_values(model, column, rows, hints)

Collects selected parameter values from a single column for plotting.

The return value of this function depends on what type of data the given column contains. In case of plain numbers, a single tuple of two lists of x and y values and a single label string are returned. In case of time series, a list of TimeSeries objects is returned, accompanied by a list of labels, each label corresponding to one of the time series.

Parameters

• model (QAbstractTableModel) – a table model

• column (int) – a column index to the model

• rows (Sequence) – row indexes to plot

• hints (PlottingHints) – a support object

Returns

a tuple of values and label(s)

Return type

tuple

spinetoolbox.plotting._expand_maps(maps, labels)

Gathers the leaf elements from maps and expands labels accordingly.

Parameters

• maps (list of Map) – maps to expand

• labels (list of str) – map labels

Returns

expanded maps and labels

Return type

tuple

spinetoolbox.plotting._label_nested_maps(map_, label)

Collects leaf values from given Maps and labels them.

Parameters

• map (Map) – a map

• label (str) – map’s label

Returns

list of values and list of corresponding labels

Return type

tuple

spinetoolbox.plotting._filter_and_check(xs, ys)

Filters Nones and empty values from x and y and checks that data types match.

spinetoolbox.plotting._raise_if_indexed_values_not_plottable(values)

Raises an exception if the indexed values in values contain elements that cannot be plotted.

spinetoolbox.plotting._raise_if_value_types_clash(values, plot_widget)

Raises a PlottingError if values type is incompatible with plot_widget.

spinetoolbox.plotting._x_values_from_rows(model, rows, hints)

Returns x value array constructed from model rows.