Core package for interactive visualization in the psyplot package

This package defines the Plotter and Formatoption classes, the core of the visualization in the psyplot package. Each Plotter combines a set of formatoption keys where each formatoption key is represented by a Formatoption subclass.

Data:

BEFOREPLOTTING	Priority value of formatoptions that are updated before the plot it made.
END	Priority value of formatoptions that are updated at the end.
START	Priority value of formatoptions that are updated before the data is loaded.
groups	dict.

Classes:

DictFormatoption(key[, plotter, ...])	Base formatoption class defining an alternative set_value that works for dictionaries.
Formatoption(key[, plotter, index_in_list, ...])	Abstract formatoption
FormatoptionMeta(clsname, bases, dct)	Meta class for formatoptions
Plotter([data, ax, auto_update, project, ...])	Interactive plotting object for one or more data arrays
PostProcDependencies()	The dependencies of this formatoption
PostProcessing(key[, plotter, ...])	Apply your own postprocessing script
PostTiming(key[, plotter, index_in_list, ...])	Determine when to run the post formatoption

Functions:

format_time(x)	Formats date values
is_data_dependent(fmto, data)	Check whether a formatoption is data dependent

psyplot.plotter.BEFOREPLOTTING = 20

Priority value of formatoptions that are updated before the plot it made.

class psyplot.plotter.DictFormatoption(key, plotter=None, index_in_list=None, additional_children=[], additional_dependencies=[], **kwargs)

Bases: Formatoption

Base formatoption class defining an alternative set_value that works for dictionaries.

Parameters:

• key (str) – formatoption key in the plotter

• plotter (psyplot.plotter.Plotter) – Plotter instance that holds this formatoption. If None, it is assumed that this instance serves as a descriptor.

• index_in_list (int or None) – The index that shall be used if the data is a psyplot.InteractiveList

• additional_children (list or str) – Additional children to use (see the children attribute)

• additional_dependencies (list or str) – Additional dependencies to use (see the dependencies attribute)

• **kwargs – Further keywords may be used to specify different names for children, dependencies and connection formatoptions that match the setup of the plotter. Hence, keywords may be anything of the children, dependencies and connections attributes, with values being the name of the new formatoption in this plotter.

Methods:

set_value(value[, validate, todefault])

Set (and validate) the value in the plotter

set_value(value, validate=True, todefault=False)

Set (and validate) the value in the plotter

Parameters:

• value – Value to set

• validate (bool) – if True, validate the value before it is set

• todefault (bool) – True if the value is updated to the default value

Notes

• If the current value in the plotter is None, then it will be set with the given value, otherwise the current value in the plotter is updated

• If the value is an empty dictionary, the value in the plotter is cleared

psyplot.plotter.END = 10

Priority value of formatoptions that are updated at the end.

class psyplot.plotter.Formatoption(key, plotter=None, index_in_list=None, additional_children=[], additional_dependencies=[], **kwargs)

Bases: object

Abstract formatoption

This class serves as an abstract version of an formatoption descriptor that can be used by Plotter instances.

Parameters:

• key (str) – formatoption key in the plotter

• plotter (psyplot.plotter.Plotter) – Plotter instance that holds this formatoption. If None, it is assumed that this instance serves as a descriptor.

• index_in_list (int or None) – The index that shall be used if the data is a psyplot.InteractiveList

• additional_children (list or str) – Additional children to use (see the children attribute)

• additional_dependencies (list or str) – Additional dependencies to use (see the dependencies attribute)

• **kwargs – Further keywords may be used to specify different names for children, dependencies and connection formatoptions that match the setup of the plotter. Hence, keywords may be anything of the children, dependencies and connections attributes, with values being the name of the new formatoption in this plotter.

Interface to the data:

any_decoder	Return the first possible decoder
ax	The axes this Formatoption plots on
data	The data that is plotted
data_dependent	bool or a callable.
decoder	The CFDecoder instance that decodes the raw_data
index_in_list	int or None.
iter_data	Returns an iterator over the plot data arrays
iter_raw_data	Returns an iterator over the original data arrays
project	Project of the plotter of this instance
raw_data	The original data of the plotter of this formatoption
set_data(data[, i])	Replace the data to plot
set_decoder(decoder[, i])	Replace the data to plot

Interface for the plotter:

changed	bool indicating whether the value changed compared to the default or not.
check_and_set(value[, todefault, validate])	Checks the value and sets the value if it changed
diff(value)	Checks whether the given value differs from what is currently set
finish_update()	Finish the update, initialization and sharing process
initialize_plot(value, *args, **kwargs)	Method that is called when the plot is made the first time
key	str.
lock	A threading.Rlock instance to lock while updating
plot_fmt	bool.
plotter	Plotter.
priority	int.
remove()	Method to remove the effects of this formatoption
requires_clearing	bool.
requires_replot	Boolean that is True if an update of the formatoption requires a replot
set_value(value[, validate, todefault])	Set (and validate) the value in the plotter.
share(fmto[, initializing])	Share the settings of this formatoption with other data objects
update(value)	Method that is call to update the formatoption on the axes
update_after_plot	bool.

Interface to other formatoptions:

children	list of str.
connections	list of str.
dependencies	list of str.
parents	list of str.
shared	set of the Formatoption instance that are shared with this instance.
shared_by	None if the formatoption is not controlled by another formatoption of another plotter, otherwise the corresponding Formatoption instance

Methods:

convert_coordinate(coord, *variables)	Convert a coordinate to units necessary for the plot.
get_decoder([i])
get_fmt_widget(parent, project)	Get a widget to update the formatoption in the GUI

Formatoption intrinsic:

default	Default value of this formatoption
validate	Validation method of the formatoption
value	Value of the formatoption in the corresponding plotter or the shared value
value2pickle	The value that can be used when pickling the information of the project
value2share	The value that is passed to shared formatoptions (by default, the value attribute)

Information attributes:

default_key	The key of this formatoption in the psyplot.rcParams
group	str.
groupname	Long name of the group this formatoption belongs too.
name	str.

Miscellaneous:

init_kwargs	dict key word arguments that are passed to the initialization of a new instance when accessed from the descriptor
logger	Logger of the plotter

property any_decoder

Return the first possible decoder

property ax

The axes this Formatoption plots on

property changed

bool indicating whether the value changed compared to the default or not.

check_and_set(value, todefault=False, validate=True)

Checks the value and sets the value if it changed

This method checks the value and sets it only if the diff() method result of the given value is True

Parameters:

• value – A possible value to set

• todefault (bool) – True if the value is updated to the default value

Returns:

A boolean to indicate whether it has been set or not

Return type:

bool

children = []

list of str. List of formatoptions that have to be updated before this one is updated. Those formatoptions are only updated if they exist in the update parameters.

connections = []

list of str. Connections to other formatoptions that are (different from dependencies and children) not important for the update process

convert_coordinate(coord, *variables)

Convert a coordinate to units necessary for the plot.

This method takes a single coordinate variable (e.g. the bounds of a coordinate, or the coordinate itself) and transforms the units that the plotter requires.

One might also provide additional variables that are supposed to be on the same unit, in case the given coord does not specify a units attribute. coord might be a CF-conform bounds variable, and one of the variables might be the corresponding coordinate.

Parameters:

• coord (xr.Variable) – The variable to transform

• *variables – The variables that are on the same unit as coord

Returns:

The transformed coord

Return type:

xr.Variable

Notes

By default, this method uses the convert_coordinate() method of the plotter.

property data

The data that is plotted

data_dependent = False

bool or a callable. This attribute indicates whether this Formatoption depends on the data and should be updated if the data changes. If it is a callable, it must accept one argument: the new data. (Note: This is automatically set to True for plot formatoptions)

property decoder

The CFDecoder instance that decodes the raw_data

property default

Default value of this formatoption

property default_key

The key of this formatoption in the psyplot.rcParams

dependencies = []

list of str. List of formatoptions that force an update of this formatoption if they are updated.

diff(value)

Checks whether the given value differs from what is currently set

Parameters:

value – A possible value to set (make sure that it has been validate via the validate attribute before)

Returns:

True if the value differs from what is currently set

Return type:

bool

finish_update()

Finish the update, initialization and sharing process

This function is called at the end of the Plotter.start_update(), Plotter.initialize_plot() or the Plotter.share() methods.

get_decoder(i=None)

get_fmt_widget(parent, project)

Get a widget to update the formatoption in the GUI

This method should return a QWidget that is loaded by the psyplot-gui when the formatoption is selected in the psyplot_gui.main.Mainwindow.fmt_widget. It should call the insert_text() method when the update text for the formatoption should be changed.

Parameters:

• parent (psyplot_gui.fmt_widget.FormatoptionWidget) – The parent widget that contains the returned QWidget

• project (psyplot.project.Project) – The current subproject (see psyplot.project.gcp())

Returns:

The widget to control the formatoption

Return type:

PyQt5.QtWidgets.QWidget

group = 'misc'

str. Key of the group name in groups of this formatoption keyword

property groupname

Long name of the group this formatoption belongs too.

index_in_list = 0

int or None. Index that is used in case the plotting data is a psyplot.InteractiveList

property init_kwargs

dict key word arguments that are passed to the initialization of a new instance when accessed from the descriptor

initialize_plot(value, *args, **kwargs)

Method that is called when the plot is made the first time

Parameters:

value – The value to use for the initialization

property iter_data

Returns an iterator over the plot data arrays

property iter_raw_data

Returns an iterator over the original data arrays

key = None

str. Formatoption key of this class in the Plotter class

property lock

A threading.Rlock instance to lock while updating

This lock is used when multiple plotter instances are updated at the same time while sharing formatoptions.

property logger

Logger of the plotter

name = None

str. A bit more verbose name than the formatoption key to be included in the gui. If None, the key is used in the gui

parents = []

list of str. List of formatoptions that, if included in the update, prevent the update of this formatoption.

plot_fmt = False

bool. Has to be True if the formatoption has a make_plot method to make the plot.

property plotter

Plotter. Plotter instance this formatoption belongs to

priority = 10

int. Priority value of the the formatoption determining when the formatoption is updated.

• 10: at the end (for labels, etc.)

• 20: before the plotting (e.g. for colormaps, etc.)

• 30: before loading the data (e.g. for lonlatbox)

property project

Project of the plotter of this instance

property raw_data

The original data of the plotter of this formatoption

remove()

Method to remove the effects of this formatoption

This method is called when the axes is cleared due to a formatoption with requires_clearing set to True. You don’t necessarily have to implement this formatoption if your plot results are removed by the usual matplotlib.axes.Axes.clear() method.

requires_clearing = False

bool. True if an update of this formatoption requires a clearing of the axes and reinitialization of the plot

requires_replot = False

Boolean that is True if an update of the formatoption requires a replot

set_data(data, i=None)

Replace the data to plot

This method may be used to replace the data that is visualized by the plotter. It changes it’s behaviour depending on whether an psyplot.data.InteractiveList is visualized or a single pysplot.data.InteractiveArray

Parameters:

• data (psyplot.data.InteractiveBase) – The data to insert

• i (int) – The position in the InteractiveList where to insert the data (if the plotter visualizes a list anyway)

Notes

This method uses the Formatoption.data attribute

set_decoder(decoder, i=None)

Replace the data to plot

This method may be used to replace the data that is visualized by the plotter. It changes it’s behaviour depending on whether an psyplot.data.InteractiveList is visualized or a single pysplot.data.InteractiveArray

Parameters:

• decoder (psyplot.data.CFDecoder) – The decoder to insert

• i (int) – The position in the InteractiveList where to insert the data (if the plotter visualizes a list anyway)

set_value(value, validate=True, todefault=False)

Set (and validate) the value in the plotter. This method is called by the plotter when it attempts to change the value of the formatoption.

Parameters:

• value – Value to set

• validate (bool) – if True, validate the value before it is set

• todefault (bool) – True if the value is updated to the default value

share(fmto, initializing=False, **kwargs)

Share the settings of this formatoption with other data objects

Parameters:

• fmto (Formatoption) – The Formatoption instance to share the attributes with

• **kwargs – Any other keyword argument that shall be passed to the update method of fmto

shared = {}

set of the Formatoption instance that are shared with this instance.

property shared_by

None if the formatoption is not controlled by another formatoption of another plotter, otherwise the corresponding Formatoption instance

abstract update(value)

Method that is call to update the formatoption on the axes

Parameters:

value – Value to update

update_after_plot = False

bool. True if this formatoption needs an update after the plot has changed

property validate

Validation method of the formatoption

property value

Value of the formatoption in the corresponding plotter or the shared value

property value2pickle

The value that can be used when pickling the information of the project

property value2share

The value that is passed to shared formatoptions (by default, the value attribute)

class psyplot.plotter.FormatoptionMeta(clsname, bases, dct)

Bases: ABCMeta

Meta class for formatoptions

This class serves as a meta class for formatoptions and allows a more efficient docstring generation by using the psyplot.docstring.docstrings when creating a new formatoption class

Assign an automatic documentation to the formatoption

class psyplot.plotter.Plotter(data=None, ax=None, auto_update=None, project=None, draw=False, make_plot=True, clear=False, enable_post=False, **kwargs)

Bases: dict

Interactive plotting object for one or more data arrays

This class is the base for the interactive plotting with the psyplot module. It capabilities are determined by it’s descriptor classes that are derived from the Formatoption class

Parameters:

• data (InteractiveArray or ArrayList, optional) – Data object that shall be visualized. If given and plot is True, the initialize_plot() method is called at the end. Otherwise you can call this method later by yourself

• ax (matplotlib.axes.Axes) – Matplotlib Axes to plot on. If None, a new one will be created as soon as the initialize_plot() method is called

• auto_update (bool) – Default: None. A boolean indicating whether this list shall automatically update the contained arrays when calling the update() method or not. See also the no_auto_update attribute. If None, the value from the 'lists.auto_update' key in the psyplot.rcParams dictionary is used.

• draw (bool or None) – Boolean to control whether the figure of this array shall be drawn at the end. If None, it defaults to the ‘auto_draw’` parameter in the psyplot.rcParams dictionary

• make_plot (bool) – If True, and data is not None, the plot is initialized. Otherwise only the framework between plotter and data is set up

• clear (bool) – If True, the axes is cleared first

• enable_post (bool) – If True, the post formatoption is enabled and post processing scripts are allowed

• **kwargs – Any formatoption key from the formatoptions attribute that shall be used

Attributes:

ax	Axes instance of the plot
base_variables	A mapping from the base_variable names to the variables
changed	dict containing the key value pairs that are not the default
data	The psyplot.InteractiveBase instance of this plotter
enable_post	bool that has to be True if the post processing script in the post formatoption should be enabled
figs2draw	All figures that have been manipulated through sharing and the own figure.
fmt_groups	A mapping from the formatoption group to the formatoptions
groups	A mapping from the group short name to the group description
include_links([value])	Temporarily include links in the key descriptions from show_keys(), show_docs() and show_summaries().
iter_base_variables	A mapping from the base_variable names to the variables
logger	logging.Logger of this plotter
no_auto_update	bool.
no_validation	Temporarily disable the validation
plot_data	The data that is used for plotting
plot_data_decoder	The decoder to use for the formatoptions.
post	Apply your own postprocessing script
post_timing	Determine when to run the post formatoption
project	psyplot.project.Project instance this plotter belongs to
rc	Default values for this plotter

Methods:

check_data(name, dims, is_unstructured)	A validation method for the data shape
check_key(key[, raise_error])	Checks whether the key is a valid formatoption
convert_coordinate(coord, *variables)	Convert a coordinate to units necessary for the plot.
draw()	Draw the figures and those that are shared and have been changed
get_enhanced_attrs(arr[, axes])
get_vfunc(key)	Return the validation function for a specified formatoption
has_changed(key[, include_last])	Determine whether a formatoption changed in the last update
initialize_plot([data, ax, make_plot, ...])	Initialize the plot for a data array
make_plot()	Method for making the plot
reinit([draw, clear])	Reinitializes the plot with the same data and on the same axes.
share(plotters[, keys, draw, auto_update])	Share the formatoptions of this plotter with others
show()	Shows all open figures
show_docs([keys, indent])	Classmethod to print the full documentations of the formatoptions
show_keys([keys, indent, grouped, func, ...])	Classmethod to return a nice looking table with the given formatoptions
show_summaries([keys, indent])	Classmethod to print the summaries of the formatoptions
start_update([draw, queues, update_shared])	Conduct the registered plot updates
unshare(plotters[, keys, auto_update, draw])	Close the sharing connection of this plotter with others
unshare_me([keys, auto_update, draw, ...])	Close the sharing connection of this plotter with others
update([fmt, replot, auto_update, draw, ...])	Update the formatoptions and the plot

property ax

Axes instance of the plot

property base_variables

A mapping from the base_variable names to the variables

property changed

dict containing the key value pairs that are not the default

classmethod check_data(name, dims, is_unstructured)

A validation method for the data shape

The default method does nothing and should be subclassed to validate the results. If the plotter accepts a InteractiveList, it should accept a list for name and dims

Parameters:

• name (str or list of str) – The variable name(s) of the data

• dims (list of str or list of lists of str) – The dimension name(s) of the data

• is_unstructured (bool or list of bool) – True if the corresponding array is unstructured

Returns:

• list of bool or None – True, if everything is okay, False in case of a serious error, None if it is intermediate. Each object in this list corresponds to one in the given name

• list of str – The message giving more information on the reason. Each object in this list corresponds to one in the given name

check_key(key, raise_error=True, *args, **kwargs)

Checks whether the key is a valid formatoption

Parameters:

• key (str) – Key to check

• raise_error (bool) – If not True, a list of similar keys is returned

• msg (str) – The additional message that shall be used if no close match to key is found

• *args – They are passed to the difflib.get_close_matches() function (i.e. n to increase the number of returned similar keys and cutoff to change the sensibility)

• **kwargs – They are passed to the difflib.get_close_matches() function (i.e. n to increase the number of returned similar keys and cutoff to change the sensibility)

Returns:

• str – The key if it is a valid string, else an empty string

• list – A list of similar formatoption strings (if found)

• str – An error message which includes

Raises:

KeyError – If the key is not a valid formatoption and raise_error is True

convert_coordinate(coord, *variables)

Convert a coordinate to units necessary for the plot.

This method takes a single coordinate variable (e.g. the bounds of a coordinate, or the coordinate itself) and transforms the units that the plotter requires.

One might also provide additional variables that are supposed to be on the same unit, in case the given coord does not specify a units attribute. coord might be a CF-conform bounds variable, and one of the variables might be the corresponding coordinate.

Parameters:

• coord (xr.Variable) – The variable to transform

• *variables – The variables that are on the same unit as coord

Returns:

The transformed coord

Return type:

xr.Variable

Notes

This method is supposed to be implemented by subclasses. The default implementation by the Plotter class does nothing.

property data

The psyplot.InteractiveBase instance of this plotter

draw()

Draw the figures and those that are shared and have been changed

enable_post = False

bool that has to be True if the post processing script in the post formatoption should be enabled

property figs2draw

All figures that have been manipulated through sharing and the own figure.

Notes

Using this property set will reset the figures too draw

property fmt_groups

A mapping from the formatoption group to the formatoptions

get_enhanced_attrs(arr, axes=['x', 'y', 't', 'z'])

get_vfunc(key)

Return the validation function for a specified formatoption

Parameters:

key (str) – Formatoption key in the rc dictionary

Returns:

Validation function for this formatoption

Return type:

function

property groups

A mapping from the group short name to the group description

has_changed(key, include_last=True)

Determine whether a formatoption changed in the last update

Parameters:

• key (str) – A formatoption key contained in this plotter

• include_last (bool) – if True and the formatoption has been included in the last update, the return value will not be None. Otherwise the return value will only be not None if it changed during the last update

Returns:

• None, if the value has not been changed during the last update or key is not a valid formatoption key

• a list of length two with the old value in the first place and the given value at the second

Return type:

None or list

include_links(value=None)

Temporarily include links in the key descriptions from show_keys(), show_docs() and show_summaries(). Note that this is a class attribute, so each change to the value of this attribute will affect all instances and subclasses

initialize_plot(data=None, ax=None, make_plot=True, clear=False, draw=False, remove=False, priority=None)

Initialize the plot for a data array

Parameters:

• data (InteractiveArray or ArrayList, optional) –

  Data object that shall be visualized.

  • If not None and plot is True, the given data is visualized.

  • If None and the data attribute is not None, the data in the data attribute is visualized

  • If both are None, nothing is done.

• ax (matplotlib.axes.Axes) – Matplotlib Axes to plot on. If None, a new one will be created as soon as the initialize_plot() method is called

• make_plot (bool) – If True, and data is not None, the plot is initialized. Otherwise only the framework between plotter and data is set up

• clear (bool) – If True, the axes is cleared first

• draw (bool or None) – Boolean to control whether the figure of this array shall be drawn at the end. If None, it defaults to the ‘auto_draw’` parameter in the psyplot.rcParams dictionary

• remove (bool) – If True, old effects by the formatoptions in this plotter are undone first

• priority (int) – If given, initialize only the formatoption with the given priority. This value must be out of START, BEFOREPLOTTING or END

property iter_base_variables

A mapping from the base_variable names to the variables

property logger

logging.Logger of this plotter

make_plot()

Method for making the plot

This method is called at the end of the BEFOREPLOTTING stage if and only if the plot_fmt attribute is set to True

property no_auto_update

bool. Boolean controlling whether the start_update() method is automatically called by the update() method

Examples

You can disable the automatic update via

>>> with data.no_auto_update:
...     data.update(time=1)
...     data.start_update()

To permanently disable the automatic update, simply set

>>> data.no_auto_update = True
>>> data.update(time=1)
>>> data.no_auto_update = False  # reenable automatical update

property no_validation

Temporarily disable the validation

Examples

Although it is not recommended to set a value with disabled validation, you can disable it via:

>>> with plotter.no_validation:
...     plotter["ticksize"] = "x"
...

To permanently disable the validation, simply set

>>> plotter.no_validation = True
>>> plotter["ticksize"] = "x"
>>> plotter.no_validation = False  # reenable validation

property plot_data

The data that is used for plotting

plot_data_decoder = None

The decoder to use for the formatoptions. If None, the decoder of the raw data is used

post

Apply your own postprocessing script

This formatoption let’s you apply your own post processing script. Just enter the script as a string and it will be executed. The formatoption will be made available via the self variable

Possible types

• None – Don’t do anything

• str – The post processing script as string

Note

This formatoption uses the built-in exec() function to compile the script. Since this poses a security risk when loading psyplot projects, it is by default disabled through the Plotter.enable_post attribute. If you are sure that you can trust the script in this formatoption, set this attribute of the corresponding Plotter to True

Examples

Assume, you want to manually add the mean of the data to the title of the matplotlib axes. You can simply do this via

from psyplot.plotter import Plotter
from xarray import DataArray

plotter = Plotter(DataArray([1, 2, 3]))
# enable the post formatoption
plotter.enable_post = True
plotter.update(post="self.ax.set_title(str(self.data.mean()))")
plotter.ax.get_title()
"2.0"

By default, the post formatoption is only ran, when it is explicitly updated. However, you can use the post_timing formatoption, to run it automatically. E.g. for running it after every update of the plotter, you can set

plotter.update(post_timing="always")

See also

post_timing

Determine the timing of this formatoption

post_timing

Determine when to run the post formatoption

This formatoption determines, whether the post formatoption should be run never, after replot or after every update.

Possible types

• ‘never’ – Never run post processing scripts

• ‘always’ – Always run post processing scripts

• ‘replot’ – Only run post processing scripts when the data changes or a replot is necessary

See also

post

The post processing formatoption

property project

psyplot.project.Project instance this plotter belongs to

property rc

Default values for this plotter

This SubDict stores the default values for this plotter. A modification of the dictionary does not affect other plotter instances unless you set the trace attribute to True

reinit(draw=None, clear=False)

Reinitializes the plot with the same data and on the same axes.

Parameters:

• draw (bool or None) – Boolean to control whether the figure of this array shall be drawn at the end. If None, it defaults to the ‘auto_draw’` parameter in the psyplot.rcParams dictionary

• clear (bool) – Whether to clear the axes or not

Warning

The axes may be cleared when calling this method (even if clear is set to False)!

share(plotters, keys=None, draw=None, auto_update=False)

Share the formatoptions of this plotter with others

This method shares the formatoptions of this Plotter instance with others to make sure that, if the formatoption of this changes, those of the others change as well

Parameters:

• plotters (list of Plotter instances or a Plotter) – The plotters to share the formatoptions with

• keys (string or iterable of strings) – The formatoptions to share, or group names of formatoptions to share all formatoptions of that group (see the fmt_groups property). If None, all formatoptions of this plotter are unshared.

• draw (bool or None) – Boolean to control whether the figure of this array shall be drawn at the end. If None, it defaults to the ‘auto_draw’` parameter in the psyplot.rcParams dictionary

• auto_update (bool) – Boolean determining whether or not the start_update() method is called at the end. This parameter has no effect if the no_auto_update attribute is set to True.

See also

unshare, unshare_me

show()

Shows all open figures

classmethod show_docs(keys=None, indent=0, *args, **kwargs)

Classmethod to print the full documentations of the formatoptions

Parameters:

• keys (list of str or None) – If None, the all formatoptions of the given class are used. Group names from the psyplot.plotter.groups mapping are replaced by the formatoptions

• indent (int) – The indentation of the table

• grouped (bool, optional) – If True, the formatoptions are grouped corresponding to the Formatoption.groupname attribute

• func (function or None) – The function the is used for returning (by default it is printed via the print() function or (when using the gui) in the help explorer). The given function must take a string as argument

• include_links (bool or None, optional) – Default False. If True, links (in restructured formats) are included in the description. If None, the behaviour is determined by the psyplot.plotter.Plotter.include_links attribute.

Returns:

The enhanced list of the formatoptions

Return type:

list of str

See also

show_keys, show_docs

classmethod show_keys(keys=None, indent=0, grouped=False, func=None, include_links=False, *args, **kwargs)

Classmethod to return a nice looking table with the given formatoptions

Parameters:

• keys (list of str or None) – If None, the all formatoptions of the given class are used. Group names from the psyplot.plotter.groups mapping are replaced by the formatoptions

• indent (int) – The indentation of the table

• grouped (bool, optional) – If True, the formatoptions are grouped corresponding to the Formatoption.groupname attribute

• func (function or None) – The function the is used for returning (by default it is printed via the print() function or (when using the gui) in the help explorer). The given function must take a string as argument

• include_links (bool or None, optional) – Default False. If True, links (in restructured formats) are included in the description. If None, the behaviour is determined by the psyplot.plotter.Plotter.include_links attribute.

Returns:

The enhanced list of the formatoptions

Return type:

list of str

Returns:

None if func is the print function, otherwise anything else

Return type:

results of func

See also

show_summaries, show_docs

classmethod show_summaries(keys=None, indent=0, *args, **kwargs)

Classmethod to print the summaries of the formatoptions

Parameters:

• keys (list of str or None) – If None, the all formatoptions of the given class are used. Group names from the psyplot.plotter.groups mapping are replaced by the formatoptions

• indent (int) – The indentation of the table

• grouped (bool, optional) – If True, the formatoptions are grouped corresponding to the Formatoption.groupname attribute

• func (function or None) – The function the is used for returning (by default it is printed via the print() function or (when using the gui) in the help explorer). The given function must take a string as argument

• include_links (bool or None, optional) – Default False. If True, links (in restructured formats) are included in the description. If None, the behaviour is determined by the psyplot.plotter.Plotter.include_links attribute.

Returns:

The enhanced list of the formatoptions

Return type:

list of str

See also

show_keys, show_docs

start_update(draw=None, queues=None, update_shared=True)

Conduct the registered plot updates

This method starts the updates from what has been registered by the update() method. You can call this method if you did not set the auto_update parameter to True when calling the update() method and when the no_auto_update attribute is True.

Parameters:

• draw (bool or None) – Boolean to control whether the figure of this array shall be drawn at the end. If None, it defaults to the ‘auto_draw’` parameter in the psyplot.rcParams dictionary

• queues (list of Queue.Queue instances) – The queues that are passed to the psyplot.plotter.Plotter.start_update() method to ensure a thread-safe update. It can be None if only one single plotter is updated at the same time. The number of jobs that are taken from the queue is determined by the _njobs() attribute. Note that there this parameter is automatically configured when updating from a Project.

Returns:

A boolean indicating whether a redrawing is necessary or not

Return type:

bool

See also

no_auto_update, update

unshare(plotters, keys=None, auto_update=False, draw=None)

Close the sharing connection of this plotter with others

This method undoes the sharing connections made by the share() method and releases the given plotters again, such that the formatoptions in this plotter may be updated again to values different from this one.

Parameters:

• plotters (list of Plotter instances or a Plotter) – The plotters to release

• keys (string or iterable of strings) – The formatoptions to unshare, or group names of formatoptions to unshare all formatoptions of that group (see the fmt_groups property). If None, all formatoptions of this plotter are unshared.

• draw (bool or None) – Boolean to control whether the figure of this array shall be drawn at the end. If None, it defaults to the ‘auto_draw’` parameter in the psyplot.rcParams dictionary

• auto_update (bool) – Boolean determining whether or not the start_update() method is called at the end. This parameter has no effect if the no_auto_update attribute is set to True.

See also

share, unshare_me

unshare_me(keys=None, auto_update=False, draw=None, update_other=True)

Close the sharing connection of this plotter with others

This method undoes the sharing connections made by the share() method and release this plotter again.

Parameters:

• keys (string or iterable of strings) – The formatoptions to unshare, or group names of formatoptions to unshare all formatoptions of that group (see the fmt_groups property). If None, all formatoptions of this plotter are unshared.

• draw (bool or None) – Boolean to control whether the figure of this array shall be drawn at the end. If None, it defaults to the ‘auto_draw’` parameter in the psyplot.rcParams dictionary

• auto_update (bool) – Boolean determining whether or not the start_update() method is called at the end. This parameter has no effect if the no_auto_update attribute is set to True.

See also

share, unshare

update(fmt={}, replot=False, auto_update=False, draw=None, force=False, todefault=False, **kwargs)

Update the formatoptions and the plot

If the data attribute of this plotter is None, the plotter is updated like a usual dictionary (see dict.update()). Otherwise the update is registered and the plot is updated if auto_update is True or if the start_update() method is called (see below).

Parameters:

• fmt (dict) – Keys can be any valid formatoptions with the corresponding values (see the formatoptions attribute)

• replot (bool) – Boolean that determines whether the data specific formatoptions shall be updated in any case or not.

• force (str, list of str or bool) – If formatoption key (i.e. string) or list of formatoption keys, thery are definitely updated whether they changed or not. If True, all the given formatoptions in this call of the are update() method are updated

• todefault (bool) – If True, all changed formatoptions (except the registered ones) are updated to their default value as stored in the rc attribute

• draw (bool or None) – Boolean to control whether the figure of this array shall be drawn at the end. If None, it defaults to the ‘auto_draw’` parameter in the psyplot.rcParams dictionary

• queues (list of Queue.Queue instances) – The queues that are passed to the psyplot.plotter.Plotter.start_update() method to ensure a thread-safe update. It can be None if only one single plotter is updated at the same time. The number of jobs that are taken from the queue is determined by the _njobs() attribute. Note that there this parameter is automatically configured when updating from a Project.

• auto_update (bool) – Boolean determining whether or not the start_update() method is called at the end. This parameter has no effect if the no_auto_update attribute is set to True.

• **kwargs – Any other formatoption that shall be updated (additionally to those in fmt)

Notes

If the no_auto_update attribute is True and the given auto_update parameter are is False, the update of the plots are registered and conducted at the next call of the start_update() method or the next call of this method (if the auto_update parameter is then True).

class psyplot.plotter.PostProcDependencies

Bases: object

The dependencies of this formatoption

class psyplot.plotter.PostProcessing(key, plotter=None, index_in_list=None, additional_children=[], additional_dependencies=[], **kwargs)

Bases: Formatoption

Apply your own postprocessing script

This formatoption let’s you apply your own post processing script. Just enter the script as a string and it will be executed. The formatoption will be made available via the self variable

Possible types

• None – Don’t do anything

• str – The post processing script as string

Note

This formatoption uses the built-in exec() function to compile the script. Since this poses a security risk when loading psyplot projects, it is by default disabled through the Plotter.enable_post attribute. If you are sure that you can trust the script in this formatoption, set this attribute of the corresponding Plotter to True

Examples

Assume, you want to manually add the mean of the data to the title of the matplotlib axes. You can simply do this via

from psyplot.plotter import Plotter
from xarray import DataArray

plotter = Plotter(DataArray([1, 2, 3]))
# enable the post formatoption
plotter.enable_post = True
plotter.update(post="self.ax.set_title(str(self.data.mean()))")
plotter.ax.get_title()
"2.0"

By default, the post formatoption is only ran, when it is explicitly updated. However, you can use the post_timing formatoption, to run it automatically. E.g. for running it after every update of the plotter, you can set

plotter.update(post_timing="always")

See also

post_timing

Determine the timing of this formatoption

Parameters:

• key (str) – formatoption key in the plotter

• plotter (psyplot.plotter.Plotter) – Plotter instance that holds this formatoption. If None, it is assumed that this instance serves as a descriptor.

• index_in_list (int or None) – The index that shall be used if the data is a psyplot.InteractiveList

• additional_children (list or str) – Additional children to use (see the children attribute)

• additional_dependencies (list or str) – Additional dependencies to use (see the dependencies attribute)

• **kwargs – Further keywords may be used to specify different names for children, dependencies and connection formatoptions that match the setup of the plotter. Hence, keywords may be anything of the children, dependencies and connections attributes, with values being the name of the new formatoption in this plotter.

Attributes:

children	list of str.
data_dependent	True if the corresponding post_timing formatoption is set to 'replot' to run the post processing script after every change of the data
default
dependencies	list of str.
group	str.
name	str.
post_timing	post_timing Formatoption instance in the plotter
priority	int.

Methods:

update(value)	Method that is call to update the formatoption on the axes
validate(value)	Validation method of the formatoption

children = ['post_timing']

list of str. List of formatoptions that have to be updated before this one is updated. Those formatoptions are only updated if they exist in the update parameters.

property data_dependent

True if the corresponding post_timing formatoption is set to 'replot' to run the post processing script after every change of the data

default = None

dependencies = []

list of str. List of formatoptions that force an update of this formatoption if they are updated.

group = 'post_processing'

str. Key of the group name in groups of this formatoption keyword

name = 'Custom post processing script'

str. A bit more verbose name than the formatoption key to be included in the gui. If None, the key is used in the gui

property post_timing

post_timing Formatoption instance in the plotter

priority = -inf

int. Priority value of the the formatoption determining when the formatoption is updated.

• 10: at the end (for labels, etc.)

• 20: before the plotting (e.g. for colormaps, etc.)

• 30: before loading the data (e.g. for lonlatbox)

update(value)

Method that is call to update the formatoption on the axes

Parameters:

value – Value to update

static validate(value)

Validation method of the formatoption

class psyplot.plotter.PostTiming(key, plotter=None, index_in_list=None, additional_children=[], additional_dependencies=[], **kwargs)

Bases: Formatoption

Determine when to run the post formatoption

This formatoption determines, whether the post formatoption should be run never, after replot or after every update.

Possible types

• ‘never’ – Never run post processing scripts

• ‘always’ – Always run post processing scripts

• ‘replot’ – Only run post processing scripts when the data changes or a replot is necessary

See also

post

The post processing formatoption

Parameters:

• key (str) – formatoption key in the plotter

• plotter (psyplot.plotter.Plotter) – Plotter instance that holds this formatoption. If None, it is assumed that this instance serves as a descriptor.

• index_in_list (int or None) – The index that shall be used if the data is a psyplot.InteractiveList

• additional_children (list or str) – Additional children to use (see the children attribute)

• additional_dependencies (list or str) – Additional dependencies to use (see the dependencies attribute)

• **kwargs – Further keywords may be used to specify different names for children, dependencies and connection formatoptions that match the setup of the plotter. Hence, keywords may be anything of the children, dependencies and connections attributes, with values being the name of the new formatoption in this plotter.

Attributes:

default
group	str.
name	str.
priority	int.

Methods:

get_fmt_widget(parent, project)	Get a widget to update the formatoption in the GUI
update(value)	Method that is call to update the formatoption on the axes
validate(value)	Validation method of the formatoption

default = 'never'

get_fmt_widget(parent, project)

Get a widget to update the formatoption in the GUI

This method should return a QWidget that is loaded by the psyplot-gui when the formatoption is selected in the psyplot_gui.main.Mainwindow.fmt_widget. It should call the insert_text() method when the update text for the formatoption should be changed.

Parameters:

• parent (psyplot_gui.fmt_widget.FormatoptionWidget) – The parent widget that contains the returned QWidget

• project (psyplot.project.Project) – The current subproject (see psyplot.project.gcp())

Returns:

The widget to control the formatoption

Return type:

PyQt5.QtWidgets.QWidget

group = 'post_processing'

str. Key of the group name in groups of this formatoption keyword

name = 'Timing of the post processing'

str. A bit more verbose name than the formatoption key to be included in the gui. If None, the key is used in the gui

priority = -inf

int. Priority value of the the formatoption determining when the formatoption is updated.

• 10: at the end (for labels, etc.)

• 20: before the plotting (e.g. for colormaps, etc.)

• 30: before loading the data (e.g. for lonlatbox)

update(value)

Method that is call to update the formatoption on the axes

Parameters:

value – Value to update

static validate(value)

Validation method of the formatoption

psyplot.plotter.START = 30

Priority value of formatoptions that are updated before the data is loaded.

psyplot.plotter.default_print_func()

the default function to use when printing formatoption infos (the default is use print or in the gui, use the help explorer)

psyplot.plotter.format_time(x)

Formats date values

This function formats datetime.datetime and datetime.timedelta objects (and the corresponding numpy objects) using the xarray.core.formatting.format_timestamp() and the xarray.core.formatting.format_timedelta() functions.

Parameters:

x (object) – The value to format. If not a time object, the value is returned

Returns:

Either the formatted time object or the initial x

Return type:

str or x

psyplot.plotter.groups = {'axes': 'Axes formatoptions', 'colors': 'Color coding formatoptions', 'data': 'Data manipulation formatoptions', 'labels': 'Label formatoptions', 'masking': 'Masking formatoptions', 'misc': 'Miscallaneous formatoptions', 'plotting': 'Plot formatoptions', 'post_processing': 'Post processing formatoptions', 'regression': 'Fitting formatoptions', 'ticks': 'Axis tick formatoptions', 'vector': 'Vector plot formatoptions'}

dict. Mapping from group to group names

psyplot.plotter.is_data_dependent(fmto, data)

Check whether a formatoption is data dependent

Parameters:

• fmto (Formatoption) – The Formatoption instance to check

• data (xarray.DataArray) – The data array to use if the data_dependent attribute is a callable

Returns:

True, if the formatoption depends on the data

Return type:

bool