"""Core package for interactive visualization in the psyplot package

This package defines the :class:`Plotter` and :class:`Formatoption` classes,

the core of the visualization in the :mod:`psyplot` package. Each

:class:`Plotter` combines a set of formatoption keys where each formatoption

key is represented by a :class:`Formatoption` subclass."""

# SPDX-FileCopyrightText: 2016-2024 University of Lausanne

# SPDX-FileCopyrightText: 2020-2021 Helmholtz-Zentrum Geesthacht

# SPDX-FileCopyrightText: 2021-2024 Helmholtz-Zentrum hereon GmbH

#

# SPDX-License-Identifier: LGPL-3.0-only

import logging

import weakref

from abc import ABCMeta, abstractmethod

from collections import defaultdict

from datetime import datetime, timedelta

from itertools import chain, groupby, repeat, starmap, tee

from textwrap import TextWrapper

from threading import RLock

import six

from numpy import datetime64, inf, ndarray, timedelta64

from xarray.core.formatting import format_timedelta, format_timestamp

from psyplot import rcParams

from psyplot.config.rcsetup import SubDict

from psyplot.data import CFDecoder, InteractiveList, _no_auto_update_getter

from psyplot.docstring import dedent, docstrings

from psyplot.utils import (

Defaultdict,

_temp_bool_prop,

_TempBool,

check_key,

unique_everseen,

)

from psyplot.warning import PsyPlotRuntimeWarning, warn

#: the default function to use when printing formatoption infos (the default is

#: use print or in the gui, use the help explorer)

default_print_func = six.print_

#: :class:`dict`. Mapping from group to group names

groups = {

"data": "Data manipulation formatoptions",

"axes": "Axes formatoptions",

"labels": "Label formatoptions",

"plotting": "Plot formatoptions",

"post_processing": "Post processing formatoptions",

"colors": "Color coding formatoptions",

"misc": "Miscallaneous formatoptions",

"ticks": "Axis tick formatoptions",

"vector": "Vector plot formatoptions",

"masking": "Masking formatoptions",

"regression": "Fitting formatoptions",

}

def _identity(*args):

"""identity function to make no validation

Returns

-------

object

just return the last argument in ``*args``"""

return args[-1]

def format_time(x):

"""Formats date values

This function formats :class:`datetime.datetime` and

:class:`datetime.timedelta` objects (and the corresponding numpy objects)

using the :func:`xarray.core.formatting.format_timestamp` and the

:func:`xarray.core.formatting.format_timedelta` functions.

Parameters

----------

x: object

The value to format. If not a time object, the value is returned

Returns

-------

str or `x`

Either the formatted time object or the initial `x`"""

if isinstance(x, (datetime64, datetime)):

return format_timestamp(x)

elif isinstance(x, (timedelta64, timedelta)):

return format_timedelta(x)

elif isinstance(x, ndarray):

return list(x) if x.ndim else x[()]

return x

def is_data_dependent(fmto, data):

"""Check whether a formatoption is data dependent

Parameters

----------

fmto: Formatoption

The :class:`Formatoption` instance to check

data: xarray.DataArray

The data array to use if the :attr:`~Formatoption.data_dependent`

attribute is a callable

Returns

-------

bool

True, if the formatoption depends on the data"""

if callable(fmto.data_dependent):

return fmto.data_dependent(data)

return fmto.data_dependent

def _child_property(childname):

def get_x(self):

return getattr(self.plotter, self._child_mapping[childname])

return property(

get_x, doc=childname + " Formatoption instance in the plotter"

)

class FormatoptionMeta(ABCMeta):

"""Meta class for formatoptions

This class serves as a meta class for formatoptions and allows a more

efficient docstring generation by using the

:attr:`psyplot.docstring.docstrings` when creating a new formatoption

class"""

def __new__(cls, clsname, bases, dct):

"""Assign an automatic documentation to the formatoption"""

doc = dct.get("__doc__")

if doc is not None:

dct["__doc__"] = docstrings.dedent(doc)

new_cls = super(FormatoptionMeta, cls).__new__(

cls, clsname, bases, dct

)

for childname in chain(

new_cls.children,

new_cls.dependencies,

new_cls.connections,

new_cls.parents,

):

setattr(new_cls, childname, _child_property(childname))

if new_cls.plot_fmt:

new_cls.data_dependent = True

return new_cls

# priority values

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

START = 30

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

BEFOREPLOTTING = 20

#: Priority value of formatoptions that are updated at the end.

END = 10

@six.add_metaclass(FormatoptionMeta)

class Formatoption(object):

"""Abstract formatoption

This class serves as an abstract version of an formatoption descriptor

that can be used by :class:`~psyplot.plotter.Plotter` instances."""

priority = END

""":class:`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)"""

#: :class:`str`. Formatoption key of this class in the

#: :class:`~psyplot.plotter.Plotter` class

key = None

_plotter = None

@property

def plotter(self):

""":class:`~psyplot.plotter.Plotter`. Plotter instance this

formatoption belongs to"""

if self._plotter is None:

return

return self._plotter()

@plotter.setter

def plotter(self, value):

if value is not None:

self._plotter = weakref.ref(value)

else:

self._plotter = value

#: `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.

children = []

#: `list of str`. List of formatoptions that force an update of this

#: formatoption if they are updated.

dependencies = []

#: `list of str`. Connections to other formatoptions that are (different

#: from :attr:`dependencies` and :attr:`children`) not important for the

#: update process

connections = []

#: `list of str`. List of formatoptions that, if included in the update,

#: prevent the update of this formatoption.

parents = []

#: :class:`bool`. Has to be True if the formatoption has a ``make_plot``

#: method to make the plot.

plot_fmt = False

#: :class:`bool`. True if an update of this formatoption requires a

#: clearing of the axes and reinitialization of the plot

requires_clearing = False

#: :class:`str`. Key of the group name in :data:`groups` of this

#: formatoption keyword

group = "misc"

#: :class:`bool` or a callable. This attribute indicates whether this

#: :class:`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)

data_dependent = False

#: :class:`bool`. True if this formatoption needs an update after the plot

#: has changed

update_after_plot = False

#: :class:`set` of the :class:`Formatoption` instance that are shared

#: with this instance.

shared = set()

#: int or None. Index that is used in case the plotting data is a

#: :class:`psyplot.InteractiveList`

index_in_list = 0

#: :class:`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

name = None

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

requires_replot = False

@property

def init_kwargs(self):

""":class:`dict` key word arguments that are passed to the

initialization of a new instance when accessed from the descriptor"""

return self._child_mapping

@property

def project(self):

"""Project of the plotter of this instance"""

return self.plotter.project

@property

def ax(self):

"""The axes this Formatoption plots on"""

return self.plotter.ax

@property

def lock(self):

"""A :class:`threading.Rlock` instance to lock while updating

This lock is used when multiple :class:`plotter` instances are

updated at the same time while sharing formatoptions."""

try:

return self._lock

except AttributeError:

self._lock = RLock()

return self._lock

@property

def logger(self):

"""Logger of the plotter"""

return self.plotter.logger.getChild(self.key)

@property

def groupname(self):

"""Long name of the group this formatoption belongs too."""

try:

return groups[self.group]

except KeyError:

warn(

"Unknown formatoption group " + str(self.group),

PsyPlotRuntimeWarning,

)

return self.group

@property

def raw_data(self):

"""The original data of the plotter of this formatoption"""

if self.index_in_list is not None and isinstance(

self.plotter.data, InteractiveList

):

return self.plotter.data[self.index_in_list]

else:

return self.plotter.data

@property

def decoder(self):

"""The :class:`~psyplot.data.CFDecoder` instance that decodes the

:attr:`raw_data`"""

# If the decoder is modified by one of the formatoptions, use this one

if self.plotter.plot_data_decoder is not None:

if self.index_in_list is not None and isinstance(

self.plotter.plot_data, InteractiveList

):

ret = self.plotter.plot_data_decoder[self.index_in_list]

if ret is not None:

return ret

else:

return self.plotter.plot_data_decoder

data = self.raw_data

check = isinstance(data, InteractiveList)

while check:

data = data[0]

check = isinstance(data, InteractiveList)

return data.psy.decoder

@decoder.setter

def decoder(self, value):

self.set_decoder(value, self.index_in_list)

@property

def any_decoder(self):

"""Return the first possible decoder"""

ret = self.decoder

while not isinstance(ret, CFDecoder):

ret = ret[0]

return ret

@property

def data(self):

"""The data that is plotted"""

if self.index_in_list is not None and isinstance(

self.plotter.plot_data, InteractiveList

):

return self.plotter.plot_data[self.index_in_list]

else:

return self.plotter.plot_data

@data.setter

def data(self, value):

self.set_data(value, self.index_in_list)

@property

def iter_data(self):

"""Returns an iterator over the plot data arrays"""

data = self.data

if isinstance(data, InteractiveList):

return iter(data)

return iter([data])

@property

def iter_raw_data(self):

"""Returns an iterator over the original data arrays"""

data = self.raw_data

if isinstance(data, InteractiveList):

return iter(data)

return iter([data])

@property

def validate(self):

"""Validation method of the formatoption"""

try:

return self._validate

except AttributeError:

try:

self._validate = self.plotter.get_vfunc(self.key)

except KeyError:

warn(

"Could not find a validation function for %s "

"formatoption keyword! No validation will be made!"

% (self.key),

PsyPlotRuntimeWarning,

logger=self.logger,

)

self._validate = _identity

return self._validate

@validate.setter

def validate(self, value):

self._validate = value

@property

def default(self):

"""Default value of this formatoption"""

return self.plotter.rc[self.key]

@property

def default_key(self):

"""The key of this formatoption in the :attr:`psyplot.rcParams`"""

return self.plotter.rc._get_val_and_base(self.key)[0]

@property

def shared_by(self):

"""None if the formatoption is not controlled by another formatoption

of another plotter, otherwise the corresponding :class:`Formatoption`

instance"""

return self.plotter._shared.get(self.key)

@property

def value(self):

"""Value of the formatoption in the corresponding :attr:`plotter` or

the shared value"""

shared_by = self.shared_by

if shared_by:

return shared_by.value2share

return self.plotter[self.key]

@property

@dedent

def changed(self):

"""

:class:`bool` indicating whether the value changed compared to the

default or not."""

return self.diff(self.default)

@property

@dedent

def value2share(self):

"""

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

:attr:`value` attribute)"""

return self.value

@property

@dedent

def value2pickle(self):

"""

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

"""

return self.value

@docstrings.get_sections(base="Formatoption")

@dedent

def __init__(

self,

key,

plotter=None,

index_in_list=None,

additional_children=[],

additional_dependencies=[],

**kwargs,

):

"""

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

:class:`psyplot.InteractiveList`

additional_children: list or str

Additional children to use (see the :attr:`children` attribute)

additional_dependencies: list or str

Additional dependencies to use (see the :attr:`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

:attr:`children`, :attr:`dependencies` and :attr:`connections`

attributes, with values being the name of the new formatoption in

this plotter."""

self.key = key

self.plotter = plotter

self.index_in_list = index_in_list

self.shared = set()

self.additional_children = additional_children

self.additional_dependencies = additional_dependencies

self.children = self.children + additional_children

self.dependencies = self.dependencies + additional_dependencies

self._child_mapping = dict(

zip(

*tee(

chain(

self.children,

self.dependencies,

self.connections,

self.parents,

),

2,

)

)

)

# check kwargs

for key in (key for key in kwargs if key not in self._child_mapping):

raise TypeError(

"%s.__init__() got an unexpected keyword argument %r"

% (self.__class__.__name__, key)

)

# set up child mapping

self._child_mapping.update(kwargs)

# reset the dependency lists to match the current plotter setup

for attr in ["children", "dependencies", "connections", "parents"]:

setattr(

self,

attr,

[self._child_mapping[key] for key in getattr(self, attr)],

)

def __set__(self, instance, value):

if isinstance(value, Formatoption):

setattr(instance, "_" + self.key, value)

else:

fmto = getattr(instance, self.key)

fmto.set_value(value)

def __get__(self, instance, owner):

if instance is None:

return self

try:

return getattr(instance, "_" + self.key)

except AttributeError:

fmto = self.__class__(

self.key,

instance,

self.index_in_list,

additional_children=self.additional_children,

additional_dependencies=self.additional_dependencies,

**self.init_kwargs,

)

setattr(instance, "_" + self.key, fmto)

return fmto

def __delete__(self, instance, owner):

fmto = getattr(instance, "_" + self.key)

with instance.no_validation:

instance[self.key] = fmto.default

@docstrings.get_sections(base="Formatoption.set_value")

@dedent

def set_value(self, 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"""

# do nothing if the key is shared

if self.key in self.plotter._shared:

return

with self.plotter.no_validation:

self.plotter[self.key] = (

value if not validate else self.validate(value)

)

def set_data(self, 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

:class:`psyplot.data.InteractiveList` is visualized or a single

:class:`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 :attr:`Formatoption.data` attribute

"""

if self.index_in_list is not None:

i = self.index_in_list

if i is not None and isinstance(

self.plotter.plot_data, InteractiveList

):

self.plotter.plot_data[i] = data

else:

self.plotter.plot_data = data

def set_decoder(self, 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

:class:`psyplot.data.InteractiveList` is visualized or a single

:class:`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)

"""

# we do not modify the raw data but instead set it on the plotter

# TODO: This is not safe for encapsulated InteractiveList instances!

if i is not None and isinstance(

self.plotter.plot_data, InteractiveList

):

n = len(self.plotter.plot_data)

decoders = self.plotter.plot_data_decoder or [None] * n

decoders[i] = decoder

self.plotter.plot_data_decoder = decoders

else:

if isinstance(

self.plotter.plot_data, InteractiveList

) and isinstance(decoder, CFDecoder):

decoder = [decoder] * len(self.plotter.plot_data)

self.plotter.plot_data_decoder = decoder

def get_decoder(self, i=None):

# we do not modify the raw data but instead set it on the plotter

# TODO: This is not safe for encapsulated InteractiveList instances!

if i is not None and isinstance(

self.plotter.plot_data, InteractiveList

):

n = len(self.plotter.plot_data)

decoders = self.plotter.plot_data_decoder or [None] * n

return decoders[i] or self.plotter.plot_data[i].psy.decoder

else:

return self.decoder

def check_and_set(self, 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 :meth:`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

-------

bool

A boolean to indicate whether it has been set or not"""

if validate:

value = self.validate(value)

if self.diff(value):

self.set_value(value, validate=False, todefault=todefault)

return True

return False

def diff(self, 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 :attr:`validate` attribute before)

Returns

-------

bool

True if the value differs from what is currently set"""

return value != self.value

def initialize_plot(self, value, *args, **kwargs):

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

Parameters

----------

value

The value to use for the initialization"""

self.update(value, *args, **kwargs)

@abstractmethod

def update(self, value):

"""Method that is call to update the formatoption on the axes

Parameters

----------

value

Value to update"""

pass

def get_fmt_widget(self, 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

:attr:`psyplot_gui.main.Mainwindow.fmt_widget`. It should call the

:meth:`~psyplot_gui.fmt_widget.FormatoptionWidget.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 :func:`psyplot.project.gcp`)

Returns

-------

PyQt5.QtWidgets.QWidget

The widget to control the formatoption"""

return None

def share(self, fmto, initializing=False, **kwargs):

"""Share the settings of this formatoption with other data objects

Parameters

----------

fmto: Formatoption

The :class:`Formatoption` instance to share the attributes with

``**kwargs``

Any other keyword argument that shall be passed to the update

method of `fmto`"""

# lock all the childrens and the formatoption itself

self.lock.acquire()

fmto._lock_children()

fmto.lock.acquire()

# update the other plotter

if initializing:

fmto.initialize_plot(self.value2share, **kwargs)

else:

fmto.update(self.value2share, **kwargs)

self.shared.add(fmto)

# release the locks

fmto.lock.release()

fmto._release_children()

self.lock.release()

def _lock_children(self):

"""acquire the locks of the children"""

plotter = self.plotter

for key in self.children + self.dependencies:

try:

getattr(plotter, key).lock.acquire()

except AttributeError:

pass

def _release_children(self):

"""release the locks of the children"""

plotter = self.plotter

for key in self.children + self.dependencies:

try:

getattr(plotter, key).lock.release()

except AttributeError:

pass

def finish_update(self):

"""Finish the update, initialization and sharing process

This function is called at the end of the :meth:`Plotter.start_update`,

:meth:`Plotter.initialize_plot` or the :meth:`Plotter.share` methods.

"""

pass

@dedent

def remove(self):

"""

Method to remove the effects of this formatoption

This method is called when the axes is cleared due to a

formatoption with :attr:`requires_clearing` set to True. You don't

necessarily have to implement this formatoption if your plot results

are removed by the usual :meth:`matplotlib.axes.Axes.clear` method."""

pass

@docstrings.get_extended_summary(base="Formatoption.convert_coordinate")

@docstrings.get_sections(

base="Formatoption.convert_coordinate",

sections=["Parameters", "Returns"],

)

def convert_coordinate(self, 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

-------

xr.Variable

The transformed `coord`

Notes

-----

By default, this method uses the :meth:`~Plotter.convert_coordinate`

method of the :attr:`plotter`.

"""

return self.plotter.convert_coordinate(coord, *variables)

class DictFormatoption(Formatoption):

"""

Base formatoption class defining an alternative set_value that works for

dictionaries."""

@docstrings.dedent

def set_value(self, value, validate=True, todefault=False):

"""

Set (and validate) the value in the plotter

Parameters

----------

%(Formatoption.set_value.parameters)s

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"""

value = value if not validate else self.validate(value)

# if the key in the plotter is not already set (i.e. it is initialized

# with None, we set it)

if self.plotter[self.key] is None:

with self.plotter.no_validation:

self.plotter[self.key] = value.copy()

# in case of an empty dict, clear the value

elif not value:

self.plotter[self.key].clear()

# otherwhise we update the dictionary

else:

if todefault:

self.plotter[self.key].clear()

self.plotter[self.key].update(value)

class PostTiming(Formatoption):

"""

Determine when to run the :attr:`post` formatoption

This formatoption determines, whether the :attr:`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"""

default = "never"

priority = -inf

group = "post_processing"

name = "Timing of the post processing"

@staticmethod

def validate(value):

value = six.text_type(value)

possible_values = ["never", "always", "replot"]

if value not in possible_values:

raise ValueError(

"String must be one of %s, not %r" % (possible_values, value)

)

return value

def update(self, value):

pass

def get_fmt_widget(self, parent, project):

from psyplot_gui.compat.qtcompat import QComboBox

combo = QComboBox(parent)

combo.addItems(["never", "always", "replot"])

combo.setCurrentText(

next((plotter[self.key] for plotter in project.plotters), "never")

)

combo.currentTextChanged.connect(parent.set_obj)

return combo

class PostProcDependencies(object):

"""The dependencies of this formatoption"""

def __get__(self, instance, owner):

if (

instance is None

or instance.plotter is None

or not instance.plotter._initialized

):

return []

elif instance.post_timing.value == "always":

return list(set(instance.plotter) - {instance.key})

else:

return []

def __set__(self, instance, value):

pass

class PostProcessing(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 :func:`exec` function to compile the

script. Since this poses a security risk when loading psyplot projects,

it is by default disabled through the :attr:`Plotter.enable_post`

attribute. If you are sure that you can trust the script in this

formatoption, set this attribute of the corresponding :class:`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

.. code-block:: python

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 :attr:`post_timing` formatoption, to

run it automatically. E.g. for running it after every update of the

plotter, you can set

.. code-block:: python

plotter.update(post_timing="always")

See Also

--------

post_timing: Determine the timing of this formatoption"""

children = ["post_timing"]

default = None

priority = -inf

group = "post_processing"

name = "Custom post processing script"

@staticmethod

def validate(value):