""":class:`bool`. Boolean controlling whether the :meth:`start_update`

method is automatically called by the :meth:`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"""

if getattr(self, "_no_auto_update", None) is not None:

return self._no_auto_update

else:

self._no_auto_update = utils._TempBool()

"""

>>> _infer_interval_breaks(np.arange(5))

array([-0.5, 0.5, 1.5, 2.5, 3.5, 4.5])

Taken from xarray.plotting.plot module

"""

coord = np.asarray(coord)

deltas = 0.5 * (coord[1:] - coord[:-1])

first = coord[0] - deltas[0]

last = coord[-1] + deltas[-1]

"""Return the variable names of an array"""

if VARIABLELABEL in arr.dims:

return arr.coords[VARIABLELABEL].tolist()

else:

try:

return getattr(import_module(store_mod), store_cls).open(fname)

except AttributeError:

# xarray 0.16 fails with pandas 1.1.0 for datetime, see

# https://github.com/pydata/xarray/issues/4283

for key, val in dims.items():

if np.issubdtype(np.asarray(val).dtype, np.datetime64):

"""

Sets up the arr_names dictionary for the plot

Parameters

----------

arr_names: string, list of strings or dictionary

Set the unique array names of the resulting arrays and (optionally)

dimensions.

- if string: same as list of strings (see below). Strings may

include {0} which will be replaced by a counter.

- list of strings: those will be used for the array names. The final

number of dictionaries in the return depend in this case on the

`dims` and ``**furtherdims``

- dictionary:

Then nothing happens and an :class:`dict` version of

`arr_names` is returned.

sort: list of strings

This parameter defines how the dictionaries are ordered. It has no

effect if `arr_names` is a dictionary (use a

:class:`dict` for that). It can be a list of

dimension strings matching to the dimensions in `dims` for the

variable.

dims: dict

Keys must be variable names of dimensions (e.g. time, level, lat or

lon) or 'name' for the variable name you want to choose.

Values must be values of that dimension or iterables of the values

(e.g. lists). Note that strings will be put into a list.

For example dims = {'name': 't2m', 'time': 0} will result in one plot

for the first time step, whereas dims = {'name': 't2m', 'time': [0, 1]}

will result in two plots, one for the first (time == 0) and one for the

second (time == 1) time step.

``**kwargs``

The same as `dims` (those will update what is specified in `dims`)

Returns

-------

dict

A mapping from the keys in `arr_names` and to dictionaries. Each

dictionary corresponds defines the coordinates of one data array to

load"""

try:

return dict(arr_names)

except (ValueError, TypeError):

# ValueError for cydict, TypeError for dic

pass

if arr_names is None:

arr_names = repeat("arr{0}")

elif isstring(arr_names):

arr_names = repeat(arr_names)

dims = dict(dims)

for key, val in six.iteritems(kwargs):

dims.setdefault(key, val)

sorted_dims = dict()

if sort:

for key in sort:

sorted_dims[key] = dims.pop(key)

for key, val in six.iteritems(dims):

sorted_dims[key] = val

else:

# make sure, it is first sorted for the variable names

if "name" in dims:

sorted_dims["name"] = None

for key, val in sorted(dims.items()):

sorted_dims[key] = val

for key, val in six.iteritems(kwargs):

sorted_dims.setdefault(key, val)

for key, val in six.iteritems(sorted_dims):

sorted_dims[key] = iter(safe_list(val))

return dict(

[

(arr_name.format(i), dict(zip(sorted_dims.keys(), dim_tuple)))

for i, (arr_name, dim_tuple) in enumerate(

zip(arr_names, product(*map(list, sorted_dims.values())))

)

]

"""Test whether `arr` is an integer array that can be replaced by a slice

Parameters

----------

arr: numpy.array

Numpy integer array

Returns

-------

slice or None

If `arr` could be converted to an array, this is returned, otherwise

`None` is returned

See Also

--------

get_index_from_coord"""

if isinstance(arr, slice):

return arr

if len(arr) == 1:

return slice(arr[0], arr[0] + 1)

step = np.unique(arr[1:] - arr[:-1])

if len(step) == 1:

"""Function to return the coordinate as integer, integer array or slice

If `coord` is zero-dimensional, the corresponding integer in `base_index`

will be supplied. Otherwise it is first tried to return a slice, if that

does not work an integer array with the corresponding indices is returned.

Parameters

----------

coord: xarray.Coordinate or xarray.Variable

Coordinate to convert

base_index: pandas.Index

The base index from which the `coord` was extracted

Returns

-------

int, array of ints or slice

The indexer that can be used to access the `coord` in the

`base_index`

"""

try:

values = coord.values

except AttributeError:

values = coord

if values.ndim == 0:

return base_index.get_loc(values[()])

if len(values) == len(base_index) and (values == base_index).all():

return slice(None)

values = np.array(list(map(lambda i: base_index.get_loc(i), values)))

"%Y": "[0-9]{4}",

"%m": "[0-9]{1,2}",

"%d": "[0-9]{1,2}",

"%H": "[0-9]{1,2}",

"%M": "[0-9]{1,2}",

"%S": "[0-9]{1,2}",

"""

Get the time information from file names

Parameters

----------

t_format: str

The string that can be used to get the time information in the files.

Any numeric datetime format string (e.g. %Y, %m, %H) can be used, but

not non-numeric strings like %b, etc. See [1]_ for the datetime format

strings

files: list of str

The that contain the time informations

Returns

-------

pandas.Index

The time coordinate

list of str

The file names as they are sorten in the returned index

References

----------

.. [1] https://docs.python.org/2/library/datetime.html"""

def median(arr):

return arr.min() + (arr.max() - arr.min()) / 2

import re

from pandas import Index

t_pattern = t_format

for fmt, patt in t_patterns.items():

t_pattern = t_pattern.replace(fmt, patt)

t_pattern = re.compile(t_pattern)

time = list(range(len(files)))

for i, f in enumerate(files):

time[i] = median(

np.array(

list(

map(

lambda s: np.datetime64(

dt.datetime.strptime(s, t_format)

),

t_pattern.findall(f),

)

)

)

)

ind = np.argsort(time) # sort according to time

files = np.array(files)[ind]

time = np.array(time)[ind]

"""

Store the given dataset as a netCDF file

This functions works essentially the same as the usual

:meth:`xarray.Dataset.to_netcdf` method but can also encode absolute time

units

Parameters

----------

ds: xarray.Dataset

The dataset to store

%(xarray.Dataset.to_netcdf.parameters)s

"""

to_update = {}

for v, obj in six.iteritems(ds.variables):

units = obj.attrs.get("units", obj.encoding.get("units", None))

if units == "day as %Y%m%d.%f" and np.issubdtype(

obj.dtype, np.datetime64

):

to_update[v] = xr.Variable(

obj.dims,

AbsoluteTimeEncoder(obj),

attrs=obj.attrs.copy(),

encoding=obj.encoding,

)

to_update[v].attrs["units"] = units

if to_update:

ds = ds.copy()

ds.update(to_update)

"""Try to get the file name from the ScipyDataStore store"""

try:

return store.ds.filename

except AttributeError:

"""Try to get the file name from the NioDataStore store"""

try:

f = store.ds.file

except AttributeError:

return None

try:

return f.path

except AttributeError:

"""Signal to connect functions to a specific event

This class behaves almost similar to PyQt's

:class:`PyQt4.QtCore.pyqtBoundSignal`

"""

instance = None

owner = None

def __init__(self, name=None, cls_signal=False):

self.name = name

self.cls_signal = cls_signal

self._connections = []

def connect(self, func):

if func not in self._connections:

self._connections.append(func)

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

if not getattr(self.owner, "block_signals", False) and not getattr(

self.instance, "block_signals", False

):

logger.debug("Emitting signal %s", self.name)

for func in self._connections[:]:

logger.debug("Calling %s", func)

func(*args, **kwargs)

def disconnect(self, func=None):

"""Disconnect a function call to the signal. If None, all connections

are disconnected"""

if func is None:

self._connections = []

else:

self._connections.remove(func)

def __get__(self, instance, owner):

self.owner = owner

if instance is None or self.cls_signal:

return self

ret = getattr(instance, self.name, None)

if ret is None:

setattr(instance, self.name, Signal(self.name))

ret = getattr(instance, self.name, None)

ret.instance = instance

"""

Return the filename of the corresponding to a dataset

This method returns the path to the `ds` or saves the dataset

if there exists no filename

Parameters

----------

ds: xarray.Dataset

The dataset you want the path information for

dump: bool

If True and the dataset has not been dumped so far, it is dumped to a

temporary file or the one generated by `paths` is used

paths: iterable or True

An iterator over filenames to use if a dataset has no filename.

If paths is ``True``, an iterator over temporary files will be

created without raising a warning

Other Parameters

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

``**kwargs``

Any other keyword for the :func:`to_netcdf` function

%(xarray.Dataset.to_netcdf.parameters)s

Returns

-------

str or None

None, if the dataset has not yet been dumped to the harddisk and

`dump` is False, otherwise the complete the path to the input

file

str

The module of the :class:`xarray.backends.common.AbstractDataStore`

instance that is used to hold the data

str

The class name of the

:class:`xarray.backends.common.AbstractDataStore` instance that is

used to open the data

"""

from tempfile import NamedTemporaryFile

# if already specified, return that filename

if ds.psy._filename is not None:

return tuple([ds.psy._filename] + list(ds.psy.data_store))

def dump_nc():

# make sure that the data store is not closed by providing a

# write argument

if xr_version < (0, 11):

kwargs.setdefault("writer", xarray_api.ArrayWriter())

store = to_netcdf(ds, fname, **kwargs)

else:

# `writer` parameter was removed by

# https://github.com/pydata/xarray/pull/2261

kwargs.setdefault("multifile", True)

store = to_netcdf(ds, fname, **kwargs)[1]

store_mod = store.__module__

store_cls = store.__class__.__name__

ds._file_obj = store

return store_mod, store_cls

def tmp_it():

while True:

yield NamedTemporaryFile(suffix=".nc").name

fname = None

if paths is True or (dump and paths is None):

paths = tmp_it()

elif paths is not None:

if isstring(paths):

paths = iter([paths])

else:

paths = iter(paths)

store_mod, store_cls = ds.psy.data_store

if "source" in ds.encoding:

fname = ds.encoding["source"]

store_mod = None

store_cls = None

# check if paths is provided and if yes, save the file

if fname is None and paths is not None:

fname = next(paths, None)

if dump and fname is not None:

store_mod, store_cls = dump_nc()

ds.psy.filename = fname

ds.psy.data_store = (store_mod, store_cls)

"""

Class that interpretes the coordinates and attributes accordings to

cf-conventions"""

_registry = []

@property

def logger(self):

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

try:

return self._logger

except AttributeError:

name = "%s.%s" % (self.__module__, self.__class__.__name__)

self._logger = logging.getLogger(name)

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

return self._logger

@logger.setter

def logger(self, value):

self._logger = value

def __init__(self, ds=None, x=None, y=None, z=None, t=None):

self.ds = ds

self.x = rcParams["decoder.x"].copy() if x is None else set(x)

self.y = rcParams["decoder.y"].copy() if y is None else set(y)

self.z = rcParams["decoder.z"].copy() if z is None else set(z)

self.t = rcParams["decoder.t"].copy() if t is None else set(t)

@staticmethod

def register_decoder(decoder_class, pos=0):

"""Register a new decoder

This function registeres a decoder class to use

Parameters

----------

decoder_class: type

The class inherited from the :class:`CFDecoder`

pos: int

The position where to register the decoder (by default: the first

position"""

CFDecoder._registry.insert(pos, decoder_class)

@classmethod

@docstrings.get_sections(

base="CFDecoder.can_decode", sections=["Parameters", "Returns"]

)

def can_decode(cls, ds, var):

"""

Class method to determine whether the object can be decoded by this

decoder class.

Parameters

----------

ds: xarray.Dataset

The dataset that contains the given `var`

var: xarray.Variable or xarray.DataArray

The array to decode

Returns

-------

bool

True if the decoder can decode the given array `var`. Otherwise

False

Notes

-----

The default implementation returns True for any argument. Subclass this

method to be specific on what type of data your decoder can decode

"""

return True

@classmethod

@docstrings.dedent

def get_decoder(cls, ds, var, *args, **kwargs):

"""

Class method to get the right decoder class that can decode the

given dataset and variable

Parameters

----------

%(CFDecoder.can_decode.parameters)s

Returns

-------

CFDecoder

The decoder for the given dataset that can decode the variable

`var`"""

for decoder_cls in cls._registry:

if decoder_cls.can_decode(ds, var):

return decoder_cls(ds, *args, **kwargs)

return CFDecoder(ds, *args, **kwargs)

@staticmethod

@docstrings.get_sections(

base="CFDecoder.decode_coords", sections=["Parameters", "Returns"]

)

def decode_coords(ds, gridfile=None):

"""

Sets the coordinates and bounds in a dataset

This static method sets those coordinates and bounds that are marked

marked in the netCDF attributes as coordinates in :attr:`ds` (without

deleting them from the variable attributes because this information is

necessary for visualizing the data correctly)

Parameters

----------

ds: xarray.Dataset

The dataset to decode

gridfile: str

The path to a separate grid file or a xarray.Dataset instance which

may store the coordinates used in `ds`

Returns

-------

xarray.Dataset

`ds` with additional coordinates"""

def add_attrs(obj):

if "coordinates" in obj.attrs:

extra_coords.update(obj.attrs["coordinates"].split())

obj.encoding["coordinates"] = obj.attrs.pop("coordinates")

if "grid_mapping" in obj.attrs:

extra_coords.add(obj.attrs["grid_mapping"])

if "bounds" in obj.attrs:

extra_coords.add(obj.attrs["bounds"])

if gridfile is not None and not isinstance(gridfile, xr.Dataset):

gridfile = open_dataset(gridfile)

extra_coords = set(ds.coords)

for k, v in six.iteritems(ds.variables):

add_attrs(v)

add_attrs(ds)

if gridfile is not None:

ds.update(

{

k: v

for k, v in six.iteritems(gridfile.variables)

if k in extra_coords

}

)

if xr_version < (0, 11):

ds.set_coords(

extra_coords.intersection(ds.variables), inplace=True

)

else:

ds._coord_names.update(extra_coords.intersection(ds.variables))

return ds

@docstrings.get_sections(

base="CFDecoder.is_unstructured", sections=["Parameters", "Returns"]

)

@docstrings.get_sections(

base="CFDecoder.get_cell_node_coord",

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

)

@dedent

def get_cell_node_coord(self, var, coords=None, axis="x", nans=None):

"""

Checks whether the bounds in the variable attribute are triangular

Parameters

----------

var: xarray.Variable or xarray.DataArray

The variable to check

coords: dict

Coordinates to use. If None, the coordinates of the dataset in the

:attr:`ds` attribute are used.

axis: {'x', 'y'}

The spatial axis to check

nans: {None, 'skip', 'only'}

Determines whether values with nan shall be left (None), skipped

(``'skip'``) or shall be the only one returned (``'only'``)

Returns

-------

xarray.DataArray or None

the bounds corrdinate (if existent)"""

if coords is None:

coords = self.ds.coords

axis = axis.lower()

get_coord = self.get_x if axis == "x" else self.get_y

coord = get_coord(var, coords=coords)

if coord is not None:

bounds = self._get_coord_cell_node_coord(

coord, coords, nans, var=var

)

if bounds is None:

bounds = self.get_plotbounds(coord)

if bounds.ndim == 1:

dim0 = coord.dims[-1]

bounds = xr.DataArray(

np.dstack([bounds[:-1], bounds[1:]])[0],

dims=(dim0, "_bnds"),

attrs=coord.attrs.copy(),

name=coord.name + "_bnds",

)

elif bounds.ndim == 2:

warn("2D bounds are not yet sufficiently tested!")

bounds = xr.DataArray(

np.dstack(

[

bounds[1:, 1:].ravel(),

bounds[1:, :-1].ravel(),

bounds[:-1, :-1].ravel(),

bounds[:-1, 1:].ravel(),

]

)[0],

dims=("".join(var.dims[-2:]), "_bnds"),

attrs=coord.attrs.copy(),

name=coord.name + "_bnds",

)

else:

raise NotImplementedError(

"More than 2D-bounds are not supported"

)

if bounds is not None and bounds.shape[-1] == 2:

# normal CF-Conventions for rectangular grids

arr = bounds.values

if axis == "y":

stacked = np.c_[

arr[..., :1], arr[..., :1], arr[..., 1:], arr[..., 1:]

]

if bounds.ndim == 2:

stacked = np.repeat(

stacked.reshape((-1, 4)),

len(self.get_x(var, coords)),

axis=0,

)

else:

stacked = stacked.reshape((-1, 4))

else:

stacked = np.c_[arr, arr[..., ::-1]]

if bounds.ndim == 2:

stacked = np.tile(

stacked, (len(self.get_y(var, coords)), 1)

)

else:

stacked = stacked.reshape((-1, 4))

bounds = xr.DataArray(

stacked,

dims=("cell", bounds.dims[1]),

name=bounds.name,

attrs=bounds.attrs,

)

return bounds

return None

docstrings.delete_params(

"CFDecoder.get_cell_node_coord.parameters", "var", "axis"

)

@docstrings.dedent

def _get_coord_cell_node_coord(

self, coord, coords=None, nans=None, var=None

):

"""

Get the boundaries of an unstructed coordinate

Parameters

----------

coord: xr.Variable

The coordinate whose bounds should be returned

%(CFDecoder.get_cell_node_coord.parameters.no_var|axis)s

Returns

-------

%(CFDecoder.get_cell_node_coord.returns)s

"""

bounds = coord.attrs.get("bounds")

if bounds is not None:

bounds = self.ds.coords.get(bounds)

if bounds is not None:

if coords is not None:

bounds = bounds.sel(

**{

key: coords[key]

for key in set(coords).intersection(bounds.dims)

}

)

if nans is not None and var is None:

raise ValueError("Need the variable to deal with NaN!")

elif nans is None:

pass

elif nans == "skip":

dims = [dim for dim in set(var.dims) - set(bounds.dims)]

mask = var.notnull().all(list(dims)) if dims else var.notnull()

try:

bounds = bounds[mask.values]

except IndexError: # 3D bounds

bounds = bounds.where(mask)

elif nans == "only":

dims = [dim for dim in set(var.dims) - set(bounds.dims)]

mask = var.isnull().all(list(dims)) if dims else var.isnull()

bounds = bounds[mask.values]

else:

raise ValueError(

"`nans` must be either None, 'skip', or 'only'! "

"Not {0}!".format(str(nans))

)

return bounds

@docstrings.get_sections(

base="CFDecoder._check_unstructured_bounds",

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

)

@docstrings.dedent

def _check_unstructured_bounds(

self, var, coords=None, axis="x", nans=None

):

"""

Checks whether the bounds in the variable attribute are triangular

Parameters

----------

%(CFDecoder.get_cell_node_coord.parameters)s

Returns

-------

bool or None

True, if unstructered, None if it could not be determined

xarray.Coordinate or None

the bounds corrdinate (if existent)"""

# !!! WILL BE REMOVED IN THE NEAR FUTURE! !!!

bounds = self.get_cell_node_coord(var, coords, axis=axis, nans=nans)

if bounds is not None:

return bounds.shape[-1] == 3, bounds

else:

return None, None

@docstrings.dedent

def is_unstructured(self, var):

"""

Test if a variable is on an unstructered grid

Parameters

----------

%(CFDecoder.is_unstructured.parameters)s

Returns

-------

%(CFDecoder.is_unstructured.returns)s

Notes

-----

Currently this is the same as :meth:`is_unstructured` method, but may

change in the future to support hexagonal grids"""

if str(var.attrs.get("grid_type")) == "unstructured":

return True

xcoord = self.get_x(var)

if xcoord is not None:

bounds = self._get_coord_cell_node_coord(xcoord)

if (

bounds is not None

and bounds.ndim == 2

and bounds.shape[-1] > 2

):

return True

@docstrings.dedent

def is_circumpolar(self, var):

"""

Test if a variable is on a circumpolar grid

Parameters

----------

%(CFDecoder.is_unstructured.parameters)s

Returns

-------

%(CFDecoder.is_unstructured.returns)s"""

xcoord = self.get_x(var)

return xcoord is not None and xcoord.ndim == 2

def get_variable_by_axis(self, var, axis, coords=None):

"""Return the coordinate matching the specified axis

This method uses to ``'axis'`` attribute in coordinates to return the

corresponding coordinate of the given variable

Possible types

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

var: xarray.Variable

The variable to get the dimension for

axis: {'x', 'y', 'z', 't'}

The axis string that identifies the dimension

coords: dict

Coordinates to use. If None, the coordinates of the dataset in the

:attr:`ds` attribute are used.

Returns

-------

xarray.Coordinate or None

The coordinate for `var` that matches the given `axis` or None if

no coordinate with the right `axis` could be found.

Notes

-----

This is a rather low-level function that only interpretes the

CFConvention. It is used by the :meth:`get_x`,

:meth:`get_y`, :meth:`get_z` and :meth:`get_t` methods

Warning

-------

If None of the coordinates have an ``'axis'`` attribute, we use the

``'coordinate'`` attribute of `var` (if existent).

Since however the CF Conventions do not determine the order on how

the coordinates shall be saved, we try to use a pattern matching

for latitude (``'lat'``) and longitude (``lon'``). If this patterns

do not match, we interpret the coordinates such that x: -1, y: -2,

z: -3. This is all not very safe for awkward dimension names,

but works for most cases. If you want to be a hundred percent sure,

use the :attr:`x`, :attr:`y`, :attr:`z` and :attr:`t` attribute.

See Also

--------

get_x, get_y, get_z, get_t"""

def get_coord(cname, raise_error=True):

try:

return coords[cname]

except KeyError:

if cname not in self.ds.coords:

if raise_error:

raise

return None

ret = self.ds.coords[cname]

try:

idims = var.psy.idims

except AttributeError: # got xarray.Variable

idims = {}

return ret.isel(

**{d: sl for d, sl in idims.items() if d in ret.dims}

)

axis = axis.lower()

if axis not in list("xyzt"):

raise ValueError(

"Axis must be one of X, Y, Z, T, not {0}".format(axis)

)

# we first check for the dimensions and then for the coordinates

# attribute

coords = coords or self.ds.coords