"""Project module of the psyplot Package.

This module contains the :class:`Project` class that serves as the main

part of the psyplot API. One instance of the :class:`Project` class serves as

coordinator of multiple plots and can be distributed into subprojects that

keep reference to the main project without holding all array instances

Furthermore this module contains an easy pyplot-like API to the current

subproject."""

# 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 os

import os.path as osp

import pickle

import sys

from collections import defaultdict

from copy import deepcopy as _deepcopy

from functools import partial, wraps

from importlib import import_module

from itertools import chain, count, cycle, islice, repeat

import matplotlib as mpl

import matplotlib.figure as mfig

import numpy as np

import pandas as pd

import six

import xarray

import yaml

from matplotlib.axes import SubplotBase

import psyplot

import psyplot.utils as utils

from psyplot import get_versions, rcParams

from psyplot.config.rcsetup import get_configdir, psyplot_fname

from psyplot.data import (

ArrayList,

CFDecoder,

InteractiveList,

Signal,

_MissingModule,

open_dataset,

open_mfdataset,

safe_list,

)

from psyplot.docstring import dedent, docstrings, safe_modulo

from psyplot.plotter import Plotter, unique_everseen

from psyplot.utils import get_default_value as _get_default_value

from psyplot.warning import critical, warn

try:

from cdo import CDO_PY_VERSION as cdo_version

from cdo import Cdo as _CdoBase

with_cdo = True

cdo_version = tuple(map(int, cdo_version.split(".")[:2]))

except ImportError as e:

Cdo = _MissingModule(e)

with_cdo = False

cdo_version = None

try: # try import show_colormaps for convenience

from psy_simple.colors import get_cmap, show_colormaps # noqa: F401

except ImportError:

pass

if rcParams["project.import_seaborn"] is not False:

try:

import seaborn as _sns

except ImportError as e:

if rcParams["project.import_seaborn"]:

raise

_sns = _MissingModule(e)

_open_projects = [] # list of open projects

_current_project = None # current main project

_current_subproject = None # current subproject

# the informations on the psyplot and plugin versions

_versions = get_versions(requirements=False)

_concat_dim_default = _get_default_value(xarray.open_mfdataset, "concat_dim")

def _update_versions():

"""Update :attr:`_versions` with the registered plotter methods"""

for pm_name in plot._plot_methods:

pm = getattr(plot, pm_name)

plugin = pm._plugin

if (

plugin is not None

and plugin not in _versions

and pm.module in sys.modules

):

_versions.update(get_versions(key=lambda s: s == plugin))

@docstrings.get_sections(base="multiple_subplots")

@docstrings.dedent

def multiple_subplots(

rows=1,

cols=1,

maxplots=None,

n=1,

delete=True,

for_maps=False,

*args,

**kwargs,

):

"""

Function to create subplots.

This function creates so many subplots on so many figures until the

specified number `n` is reached.

Parameters

----------

rows: int

The number of subplots per rows

cols: int

The number of subplots per column

maxplots: int

The number of subplots per figure (if None, it will be row*cols)

n: int

number of subplots to create

delete: bool

If True, the additional subplots per figure are deleted

for_maps: bool

If True this is a simple shortcut for setting

``subplot_kw=dict(projection=cartopy.crs.PlateCarree())`` and is

useful if you want to use the :attr:`~ProjectPlotter.mapplot`,

:attr:`~ProjectPlotter.mapvector` or

:attr:`~ProjectPlotter.mapcombined` plotting methods

``*args`` and ``**kwargs``

anything that is passed to the :func:`matplotlib.pyplot.subplots`

function

Returns

-------

list

list of maplotlib.axes.SubplotBase instances"""

import matplotlib.pyplot as plt

axes = np.array([])

maxplots = maxplots or rows * cols

kwargs.setdefault("figsize", [min(8.0 * cols, 16), min(6.5 * rows, 12)])

if for_maps:

import cartopy.crs as ccrs

subplot_kw = kwargs.setdefault("subplot_kw", {})

subplot_kw["projection"] = ccrs.PlateCarree()

for i in range(0, n, maxplots):

fig, ax = plt.subplots(rows, cols, *args, **kwargs)

try:

axes = np.append(axes, ax.ravel()[:maxplots])

if delete:

for iax in range(maxplots, rows * cols):

fig.delaxes(ax.ravel()[iax])

except AttributeError: # got a single subplot

axes = np.append(axes, [ax])

if i + maxplots > n and delete:

for ax2 in axes[n:]:

fig.delaxes(ax2)

axes = axes[:n]

return axes

def _is_slice(val):

return isinstance(val, slice)

def _only_main(func):

"""Call the given `func` only from the main project"""

@wraps(func)

def wrapper(self, *args, **kwargs):

if not self.is_main:

return getattr(self.main, func.__name__)(*args, **kwargs)

return func(self, *args, **kwargs)

return wrapper

def _first_main(func):

"""Call the given `func` with the same arguments but after the function

of the main project"""

@wraps(func)

def wrapper(self, *args, **kwargs):

if not self.is_main:

getattr(self.main, func.__name__)(*args, **kwargs)

return func(self, *args, **kwargs)

return wrapper

class Project(ArrayList):

"""A manager of multiple interactive data projects"""

_main = None

_registered_plotters = {} #: registered plotter identifiers

#: signal to be emiitted when the current main and/or subproject changes

oncpchange = Signal(name="oncpchange", cls_signal=True)

# block the signals of this class

block_signals = utils._TempBool()

@property

def main(self):

""":class:`Project`. The main project of this subproject"""

return self._main if self._main is not None else self

@main.setter

def main(self, value):

self._main = value

@property

@dedent

def plot(self):

"""

Plotting instance of this :class:`Project`. See the

:class:`ProjectPlotter` class for method documentations"""

return self._plot

@property

def _fmtos(self):

"""An iterator over formatoption objects

Contains only the formatoption whose keys are in all plotters in this

list"""

plotters = self.plotters

if len(plotters) == 0:

return {}

p0 = plotters[0]

if len(plotters) == 1:

return p0._fmtos

return (

getattr(p0, key)

for key in set(p0).intersection(*map(set, plotters[1:]))

)

@property

def is_csp(self):

"""Boolean that is True if the project is the current subproject"""

return self is _current_subproject

@property

def is_cmp(self):

"""Boolean that is True if the project is the current main project"""

return self is _current_project

@property

def figs(self):

"""A mapping from figures to data objects with the plotter in this

figure"""

ret = utils.Defaultdict(lambda: self[1:0])

for arr in self:

if arr.psy.plotter is not None:

ret[arr.psy.plotter.ax.get_figure()].append(arr)

return dict(ret)

@property

def axes(self):

"""A mapping from axes to data objects with the plotter in this axes"""

ret = utils.Defaultdict(lambda: self[1:0])

for arr in self:

if arr.psy.plotter is not None:

ret[arr.psy.plotter.ax].append(arr)

return dict(ret)

@property

def is_main(self):

""":class:`bool`. True if this :class:`Project` is a main project"""

return self._main is None

@property

def logger(self):

""":class:`logging.Logger` of this instance"""

if not self.is_main:

return self.main.logger

try:

return self._logger

except AttributeError:

name = "%s.%s.%s" % (

self.__module__,

self.__class__.__name__,

self.num,

)

self._logger = logging.getLogger(name)

self.logger.debug("Initializing...")

return self._logger

@logger.setter

def logger(self, value):

self._logger = value

def with_plotter(self):

ret = super(Project, self).with_plotter

ret.main = self.main

return ret

with_plotter = property(with_plotter, doc=ArrayList.with_plotter.__doc__)

@property

def arr_names(self):

"""Names of the arrays (!not of the variables!) in this list

This attribute can be set with an iterable of unique names to change

the array names of the data objects in this list."""

return list(arr.psy.arr_name for arr in self)

@arr_names.setter

def arr_names(self, value):

value = list(islice(value, len(self)))

if not len(set(value)) == len(self):

raise ValueError(

"Got %i unique array names for %i data objects!"

% (len(set(value)), len(self))

)

elif not self.is_main and set(value) & (

set(self.main.arr_names) - set(self.arr_names)

):

raise ValueError(

"Cannot rename arrays because there are duplicates with the "

"main project: %s"

% (

set(value)

& (set(self.main.arr_names) - set(self.arr_names)),

)

)

for arr, n in zip(self, value):

arr.psy.arr_name = n

if self.main is gcp(True):

for arr in self:

arr.psy.onupdate.emit()

@property

def plotters(self):

"""A list of all the plotters in this instance"""

return [arr.psy.plotter for arr in self.with_plotter]

@property

def datasets(self):

"""A mapping from dataset numbers to datasets in this list"""

return {

key: val["ds"]

for key, val in six.iteritems(

self._get_ds_descriptions(

self.array_info(ds_description=["ds"])

)

)

}

@property

def dsnames_map(self):

"""A dictionary from the dataset numbers in this list to their

filenames"""

return {

key: val["fname"]

for key, val in six.iteritems(

self._get_ds_descriptions(

self.array_info(ds_description=["num", "fname"]),

ds_description={"fname"},

)

)

}

@property

def dsnames(self):

"""The set of dataset names in this instance"""

return {t[0] for t in self._get_dsnames(self.array_info()) if t[0]}

@docstrings.get_sections(base="Project")

@docstrings.dedent

def __init__(self, *args, **kwargs):

"""

Parameters

----------

%(ArrayList.parameters)s

main: Project

The main project this subproject belongs to (or None if this

project is the main project)

num: int

The number of the project

"""

self.main = kwargs.pop("main", None)

self._plot = ProjectPlotter(self)

self.num = kwargs.pop("num", 1)

self._ds_counter = count()

with self.block_signals:

super(Project, self).__init__(*args, **kwargs)

@classmethod

@docstrings.get_sections(base="Project._register_plotter")

@dedent

def _register_plotter(

cls, identifier, module, plotter_name, plotter_cls=None

):

"""

Register a plotter in the :class:`Project` class to easy access it

Parameters

----------

identifier: str

Name of the attribute that is used to filter for the instances

belonging to this plotter

module: str

The module from where to import the `plotter_name`

plotter_name: str

The name of the plotter class in `module`

plotter_cls: type

The imported class of `plotter_name`. If None, it will be imported

when it is needed

"""

if plotter_cls is not None: # plotter has already been imported

def get_x(self):

return self(plotter_cls)

else:

def get_x(self):

return self(getattr(import_module(module), plotter_name))

setattr(

cls,

identifier,

property(

get_x,

doc=(

"List of data arrays that are plotted by :class:`%s.%s`"

" plotters"

)

% (module, plotter_name),

),

)

cls._registered_plotters[identifier] = (module, plotter_name)

def disable(self):

"""Disables the plotters in this list"""

for arr in self:

if arr.psy.plotter:

arr.psy.plotter.disabled = True

def enable(self):

for arr in self:

if arr.psy.plotter:

arr.psy.plotter.disabled = False

def __call__(self, *args, **kwargs):

ret = super(Project, self).__call__(*args, **kwargs)

ret.main = self.main

return ret

def __enter__(self):

return self

def __exit__(self, exc_type, exc_val, exc_tb):

self.close(True, True, True)

@staticmethod

@docstrings.get_sections(

base="Project._load_preset", sections=["Parameters", "Notes"]

)

def _load_preset(preset: str):

"""Load a preset from disk

Parameters

----------

preset: str or dict

The filename or identifier of a preset. If the given `preset` is

the path to an existing yaml file, it will be loaded. Otherwise we

look up the `preset` in the psyplot configuration directory (see

:func:`~psyplot.config.rcsetup.get_configdir`).

If a dictionary is provided, we assume that this is the preset

Returns

-------

dict

The loaded preset

Notes

-----

An identifier is the filename without extension. If you want to list

the available presets, run ``psyplot -lp`` from the command-line"""

if isinstance(preset, dict):

config = preset

else:

path = Project._resolve_preset_path(preset)

if path in rcParams["presets.trusted"]:

loader = yaml.Loader

else:

loader = yaml.SafeLoader

with open(path) as f:

try:

config = yaml.load(f, loader)

except yaml.constructor.ConstructorError as e:

e.note = (e.note or "") + (

" You might want to add it to the trusted presets "

'via\n\npsy.rcParams["presets.trusted"].append("{}")\n\n'

"and run this method again. To permanently store "

"this preset, edit the file at\n\n{} "

).format(path, psyplot_fname())

raise

return config

@staticmethod

def _resolve_preset_path(preset, if_exists=True):

if osp.exists(preset):

return preset

else:

confdir = get_configdir()

presets_dir = osp.join(confdir, "presets")

if osp.exists(osp.join(presets_dir, preset)):

return osp.join(presets_dir, preset)

elif osp.exists(osp.join(presets_dir, preset + ".yml")):

return osp.join(presets_dir, preset + ".yml")

else:

if if_exists:

raise ValueError(

f"Could not find a preset with name {preset}"

)

else:

if not preset.endswith(".yml"):

return osp.join(presets_dir, preset + ".yml")

return preset

@docstrings.dedent

def load_preset(self, preset: str, **kwargs):

"""Load a preset from disk and apply it to the open project.

This method loads a preset and updates the corresponding plots

Parameters

----------

%(Project._load_preset.parameters)s

``**kwargs``

Any other parameter that shall be passed to the

:meth:`~psyplot.data.ArrayList.update` method

Notes

-----

%(Project._load_preset.notes)s

"""

config = self._load_preset(preset)

plotmethods = self.plot._plot_methods

pm_config, defaults = utils.sort_kwargs(config, plotmethods)

with self.no_auto_update:

for pm in plotmethods:

method = getattr(self.plot, pm)

if method.is_imported:

sp = getattr(self, pm)

if sp:

valid = list(method.plotter_cls._get_formatoptions())

fmts = {

key: val

for key, val in defaults.items()

if key in valid

}

fmts.update(pm_config.get(pm, {}))

sp.update(fmt=fmts, **kwargs)

self.start_update()

@staticmethod

def extract_fmts_from_preset(preset: str, plotmethod: str):

"""Extract the formatoptions for a plotmethod from a given preset

This method takes the preset and extracts the formatoptions valid for

the given plotmethod

Parameters

----------

%(Project._load_preset.parameters)s

plotmethod: str

The plotmethod to use"""

preset = Project._load_preset(preset)

try:

plotmethod._method

except AttributeError:

method = getattr(plot, plotmethod)

else:

method = plotmethod

plotmethod = method._method

plotmethods = plot._plot_methods

pm_config, defaults = utils.sort_kwargs(preset, plotmethods)

valid = list(method.plotter_cls._get_formatoptions())

fmts = {key: val for key, val in defaults.items() if key in valid}

fmts.update(pm_config.get(plotmethod, {}))

return fmts

def save_preset(self, fname=None, include_defaults=False, update=False):

"""Save the formatoptions of this project as a preset

This method takes the formatoptions in the plotters of this project and

saves it as a preset file"""

def include(fmto, plotters):

key = fmto.key

for plotter in plotters:

if fmto.diff(plotter[key]):

return False

return True if include_defaults else fmto.changed

if update:

with open(fname) as f:

preset = yaml.load(f, yaml.Loader)

else:

preset = {}

plotters = self.plotters

for fmto in self._fmtos:

if include(fmto, plotters):

preset[fmto.key] = fmto.value

for pm in self.plot._plot_methods:

method = getattr(self.plot, pm)

if method.is_imported:

sp = getattr(self, pm)

plotters = sp.plotters

for fmto in sp._fmtos:

if fmto.key not in preset and include(fmto, plotters):

preset.setdefault(pm, {})

preset[pm][fmto.key] = fmto.value

if fname is not None:

fname = self._resolve_preset_path(fname, False)

os.makedirs(osp.dirname(fname), exist_ok=True)

with open(fname, "w") as f:

yaml.dump(preset, f)

else:

return preset

@_first_main

def extend(self, *args, **kwargs):

len0 = len(self)

ret = super(Project, self).extend(*args, **kwargs)

if self._main is None:

for arr in self:

if arr.psy.plotter is not None:

arr.psy.plotter._project = self

if len(self) > len0 and (self.is_csp or self.is_cmp):

self.oncpchange.emit(self)

return ret

extend.__doc__ = ArrayList.extend.__doc__

@_first_main

def append(self, *args, **kwargs):

len0 = len(self)

ret = super(Project, self).append(*args, **kwargs)

if self._main is None:

for arr in self:

if arr.psy.plotter is not None:

arr.psy.plotter._project = self

if len(self) > len0 and (self.is_csp or self.is_cmp):

self.oncpchange.emit(self)

return ret

append.__doc__ = ArrayList.append.__doc__

__call__.__doc__ = ArrayList.__call__.__doc__

@docstrings.get_sections(base="Project.close")

@dedent

def close(self, figs=True, data=False, ds=False, remove_only=False):

"""

Close this project instance

Parameters

----------

figs: bool

Close the figures

data: bool

delete the arrays from the (main) project

ds: bool

If True, close the dataset as well

remove_only: bool

If True and `figs` is True, the figures are not closed but the

plotters are removed"""

import matplotlib.pyplot as plt

close_ds = ds

for arr in self[:]:

if figs and arr.psy.plotter is not None:

if remove_only:

for fmto in arr.psy.plotter._fmtos:

try:

fmto.remove()

except Exception:

pass

else:

plt.close(arr.psy.plotter.ax.get_figure().number)

arr.psy.plotter = None

if data:

self.remove(arr)

if not self.is_main:

try:

self.main.remove(arr)

except ValueError: # arr not in list

pass

if close_ds:

if isinstance(arr, InteractiveList):

for ds in [

val["ds"]

for val in six.itervalues(

arr._get_ds_descriptions(

arr.array_info(

ds_description=["ds"],

standardize_dims=False,

)

)

)

]:

ds.close()

else:

arr.psy.base.close()

if self.is_main and self is gcp(True) and data:

scp(None)

elif self.is_main and self.is_cmp:

self.oncpchange.emit(self)

elif self.main.is_cmp:

self.oncpchange.emit(self.main)

docstrings.keep_params("multiple_subplots.parameters", "delete")

docstrings.delete_params("ArrayList.from_dataset.parameters", "base")

docstrings.delete_kwargs(

"ArrayList.from_dataset.other_parameters", kwargs="kwargs"

)

docstrings.keep_params("xarray.open_mfdataset.parameters", "concat_dim")

docstrings.keep_params("Project._load_preset.parameters", "preset")

@_only_main

@docstrings.get_sections(

base="Project._add_data",

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

)

@docstrings.dedent

def _add_data(

self,

plotter_cls,

filename_or_obj,

fmt={},

make_plot=True,

draw=False,

mf_mode=False,

ax=None,

engine=None,

delete=True,

share=False,

clear=False,

enable_post=None,

concat_dim=_concat_dim_default,

load=False,

*args,

**kwargs,

):

"""

Extract data from a dataset and visualize it with the given plotter

Parameters

----------

plotter_cls: type

The subclass of :class:`psyplot.plotter.Plotter` to use for

visualization

filename_or_obj: filename, :class:`xarray.Dataset` or data store

The object (or file name) to open. If not a dataset, the

:func:`psyplot.data.open_dataset` will be used to open a dataset

fmt: dict

Formatoptions that shall be when initializing the plot (you can

however also specify them as extra keyword arguments)

make_plot: bool

If True, the data is plotted at the end. Otherwise you have to

call the :meth:`psyplot.plotter.Plotter.initialize_plot` method or

the :meth:`psyplot.plotter.Plotter.reinit` method by yourself

%(InteractiveBase.start_update.parameters.draw)s

mf_mode: bool

If True, the :func:`psyplot.open_mfdataset` method is used.

Otherwise we use the :func:`psyplot.open_dataset` method which can

open only one single dataset

ax: None, tuple (x, y[, z]) or (list of) matplotlib.axes.Axes

Specifies the subplots on which to plot the new data objects.

- If None, a new figure will be created for each created plotter

- If tuple (x, y[, z]), `x` specifies the number of rows, `y` the

number of columns and the optional third parameter `z` the

maximal number of subplots per figure.

- If :class:`matplotlib.axes.Axes` (or list of those, e.g. created

by the :func:`matplotlib.pyplot.subplots` function), the data

will be plotted on these subplots

%(open_dataset.parameters.engine)s

%(multiple_subplots.parameters.delete)s

share: bool, fmt key or list of fmt keys

Determines whether the first created plotter shares it's

formatoptions with the others. If True, all formatoptions are

shared. Strings or list of strings specify the keys to share.

clear: bool

If True, axes are cleared before making the plot. This is only

necessary if the `ax` keyword consists of subplots with projection

that differs from the one that is needed

enable_post: bool

If True, the :attr:`~psyplot.plotter.Plotter.post` formatoption is

enabled and post processing scripts are allowed. If ``None``, this

parameter is set to True if there is a value given for the `post`

formatoption in `fmt` or `kwargs`

%(xarray.open_mfdataset.parameters.concat_dim)s

This parameter only does have an effect if `mf_mode` is True.

load: bool

If True, load the complete dataset into memory before plotting.

This might be useful if the data of other variables in the dataset

has to be accessed multiple times, e.g. for unstructured grids.

%(ArrayList.from_dataset.parameters.no_base)s

Other Parameters

----------------

%(ArrayList.from_dataset.other_parameters.no_args_kwargs)s

``**kwargs``

Any other dimension or formatoption that shall be passed to `dims`

or `fmt` respectively.

Returns

-------

Project

The subproject that contains the new (visualized) data array"""

if not isinstance(filename_or_obj, xarray.Dataset):

if mf_mode:

filename_or_obj = open_mfdataset(

filename_or_obj, engine=engine, concat_dim=concat_dim

)

else:

filename_or_obj = open_dataset(filename_or_obj, engine=engine)

if load:

old = filename_or_obj

filename_or_obj = filename_or_obj.load()

old.close()

fmt = dict(fmt)

possible_fmts = list(plotter_cls._get_formatoptions())

additional_fmt, kwargs = utils.sort_kwargs(kwargs, possible_fmts)

fmt.update(additional_fmt)

if enable_post is None:

enable_post = bool(fmt.get("post"))

# create the subproject

sub_project = self.from_dataset(filename_or_obj, **kwargs)

sub_project.main = self

sub_project.no_auto_update = not (

not sub_project.no_auto_update or not self.no_auto_update

)

# create the subplots

proj = plotter_cls._get_sample_projection()

if isinstance(ax, tuple):

axes = iter(

multiple_subplots(

*ax, n=len(sub_project), subplot_kw={"projection": proj}

)

)

elif ax is None or isinstance(

ax, (mpl.axes.SubplotBase, mpl.axes.Axes)

):

axes = repeat(ax)

else:

axes = iter(ax)

clear = clear or (isinstance(ax, tuple) and proj is not None)

for arr in sub_project:

plotter_cls(

arr,

make_plot=(not bool(share) and make_plot),

draw=False,

ax=next(axes),

clear=clear,

project=self,

enable_post=enable_post,

**fmt,

)

if share:

if share is True:

share = possible_fmts

elif isinstance(share, six.string_types):

share = [share]

else:

share = list(share)

sub_project[0].psy.plotter.share(

[arr.psy.plotter for arr in sub_project[1:]],

keys=share,

draw=False,

)

if make_plot:

for arr in sub_project:

arr.psy.plotter.reinit(draw=False, clear=clear)

if draw is None:

draw = rcParams["auto_draw"]

if draw:

sub_project.draw()

if rcParams["auto_show"]:

self.show()

self.extend(sub_project, new_name=True)

if self is gcp(True):

scp(sub_project)

return sub_project

def __getitem__(self, key):

"""Overwrites lists __getitem__ by returning subproject if `key` is a

slice"""

if isinstance(key, slice): # return a new project

ret = self.__class__(super(Project, self).__getitem__(key))

ret.main = self.main

else: # return the item

ret = super(Project, self).__getitem__(key)

return ret

if six.PY2: # for compatibility to python 2.7

def __getslice__(self, *args):

return self[slice(*args)]

def __add__(self, other):

# overwritte to return a subproject

ret = self.__class__(super(Project, self).__add__(other))

ret.main = self.main

return ret

@staticmethod

def show():

"""Shows all open figures"""

import matplotlib.pyplot as plt

plt.show(block=False)

docstrings.keep_params("join_dicts.parameters", "delimiter")

docstrings.keep_params("join_dicts.parameters", "keep_all")

@docstrings.get_sections(base="Project.joined_attrs")

@docstrings.with_indent(8)

def joined_attrs(

self, delimiter=", ", enhanced=True, plot_data=False, keep_all=True

):

"""Join the attributes of the arrays in this project

Parameters

----------

%(join_dicts.parameters.delimiter)s

enhanced: bool

If True, the :meth:`psyplot.plotter.Plotter.get_enhanced_attrs`

method is used, otherwise the :attr:`xarray.DataArray.attrs`

attribute is used.

plot_data: bool

It True, use the :attr:`psyplot.plotter.Plotter.plot_data`

attribute of the plotters rather than the raw data in this project

%(join_dicts.parameters.keep_all)s

Returns

-------

dict

A mapping from the attribute to the joined attributes which are

either strings or (if there is only one attribute value), the

data type of the corresponding value"""

if enhanced:

all_attrs = [

plotter.get_enhanced_attrs(

getattr(plotter, "plot_data" if plot_data else "data")

)

for plotter in self.plotters

]

else:

if plot_data:

all_attrs = [

plotter.plot_data.attrs for plotter in self.plotters

]

else:

all_attrs = [arr.attrs for arr in self]

return utils.join_dicts(

all_attrs, delimiter=delimiter, keep_all=keep_all

)

@docstrings.get_sections(base="Project.format_string")

@docstrings.with_indent(8)

def format_string(

self, s, use_time=False, format_args=None, *args, **kwargs

):

"""Format a string with the attributes in this project

Parameters

----------

s: str

The string that is subject to be formatted

use_time: bool

If True, formatting strings for the

:meth:`datetime.datetime.strftime` are expected to be found in

`output` (e.g. ``'%%m'``, ``'%%Y'``, etc.). If so, other formatting

strings must be escaped by double ``'%%'`` (e.g. ``'%%%i'``