From fbb4deb4a6c3c64c7e53e7b7e0d17f985dfbb864 Mon Sep 17 00:00:00 2001 From: Ray Bell Date: Fri, 16 Jul 2021 15:24:40 -0400 Subject: [PATCH 01/11] add storage_options arg to to_zarr --- xarray/backends/api.py | 13 +++++++++++-- xarray/core/dataset.py | 11 ++++++++--- 2 files changed, 19 insertions(+), 5 deletions(-) diff --git a/xarray/backends/api.py b/xarray/backends/api.py index 9b4fa8fce5a..8316d556994 100644 --- a/xarray/backends/api.py +++ b/xarray/backends/api.py @@ -18,6 +18,7 @@ ) import numpy as np +from fsspec import get_mapper from .. import backends, coding, conventions from ..core import indexing @@ -1310,6 +1311,7 @@ def to_zarr( dataset: Dataset, store: Union[MutableMapping, str, Path] = None, chunk_store=None, + storage_options: Dict[str, str] = None, mode: str = None, synchronizer=None, group: str = None, @@ -1330,6 +1332,13 @@ def to_zarr( store = _normalize_path(store) chunk_store = _normalize_path(chunk_store) + if storage_options is None: + mapper = store + chunk_mapper = chunk_store + else: + mapper = get_mapper(store, **storage_options) + chunk_mapper = get_mapper(chunk_store, **storage_options) + if encoding is None: encoding = {} @@ -1372,13 +1381,13 @@ def to_zarr( already_consolidated = False consolidate_on_close = consolidated or consolidated is None zstore = backends.ZarrStore.open_group( - store=store, + store=mapper, mode=mode, synchronizer=synchronizer, group=group, consolidated=already_consolidated, consolidate_on_close=consolidate_on_close, - chunk_store=chunk_store, + chunk_store=chunk_mapper, append_dim=append_dim, write_region=region, safe_chunks=safe_chunks, diff --git a/xarray/core/dataset.py b/xarray/core/dataset.py index 13da8cfad03..3413d4f5dad 100644 --- a/xarray/core/dataset.py +++ b/xarray/core/dataset.py @@ -1902,6 +1902,7 @@ def to_zarr( self, store: Union[MutableMapping, str, Path] = None, chunk_store: Union[MutableMapping, str, Path] = None, + storage_options: Dict[str, str] = None, mode: str = None, synchronizer=None, group: str = None, @@ -1930,10 +1931,13 @@ def to_zarr( Parameters ---------- store : MutableMapping, str or Path, optional - Store or path to directory in file system. + Store or path to directory in local or remote file system. chunk_store : MutableMapping, str or Path, optional - Store or path to directory in file system only for Zarr array chunks. - Requires zarr-python v2.4.0 or later. + Store or path to directory in local or remote file system only for Zarr + array chunks. Requires zarr-python v2.4.0 or later. + storage_options : dict, optional + Any additional parameters for the storage backend (ignored for local + paths). mode : {"w", "w-", "a", "r+", None}, optional Persistence mode: "w" means create (overwrite if exists); "w-" means create (fail if exists); @@ -2020,6 +2024,7 @@ def to_zarr( self, store=store, chunk_store=chunk_store, + storage_options=storage_options, mode=mode, synchronizer=synchronizer, group=group, From 3c0805fe361ad2b4756cabb76301805b40657110 Mon Sep 17 00:00:00 2001 From: Ray Bell Date: Fri, 16 Jul 2021 15:33:19 -0400 Subject: [PATCH 02/11] add try import --- xarray/backends/api.py | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/xarray/backends/api.py b/xarray/backends/api.py index 8316d556994..be0c03d0b21 100644 --- a/xarray/backends/api.py +++ b/xarray/backends/api.py @@ -18,7 +18,6 @@ ) import numpy as np -from fsspec import get_mapper from .. import backends, coding, conventions from ..core import indexing @@ -39,6 +38,10 @@ from dask.delayed import Delayed except ImportError: Delayed = None + try: + from fsspec import get_mapper + except ImportError: + get_mapper = None DATAARRAY_NAME = "__xarray_dataarray_name__" @@ -1337,7 +1340,7 @@ def to_zarr( chunk_mapper = chunk_store else: mapper = get_mapper(store, **storage_options) - chunk_mapper = get_mapper(chunk_store, **storage_options) + chunk_mapper = get_mapper(store, **storage_options) if encoding is None: encoding = {} From 29e58af8a435d7f945670561d6e7a43836007c27 Mon Sep 17 00:00:00 2001 From: Ray Bell Date: Fri, 16 Jul 2021 15:56:30 -0400 Subject: [PATCH 03/11] add what's new --- doc/whats-new.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/whats-new.rst b/doc/whats-new.rst index 0053824c87b..c4951380b7f 100644 --- a/doc/whats-new.rst +++ b/doc/whats-new.rst @@ -21,6 +21,8 @@ v0.18.3 (unreleased) New Features ~~~~~~~~~~~~ +- Added `storage_options` arg to :py:meth:`~xarray.Dataset.to_zarr` (:pull:`5615`). + By `Ray Bell `_. - Allow passing a dictionary as coords to a :py:class:`DataArray` (:issue:`5527`, reverts :pull:`1539`, which had deprecated this due to python's inconsistent ordering in earlier versions). By `Sander van Rijn `_. From 9f5e501234151275a9223627619c7ca6596dc701 Mon Sep 17 00:00:00 2001 From: Ray Bell Date: Wed, 28 Jul 2021 13:02:04 -0400 Subject: [PATCH 04/11] merge main whats-new --- doc/whats-new.rst | 11082 ++++++++++++++++++++++---------------------- 1 file changed, 5560 insertions(+), 5522 deletions(-) diff --git a/doc/whats-new.rst b/doc/whats-new.rst index c4951380b7f..57df47023f3 100644 --- a/doc/whats-new.rst +++ b/doc/whats-new.rst @@ -1,5535 +1,5573 @@ .. currentmodule:: xarray -What's New -========== - -.. ipython:: python - :suppress: - - import numpy as np - import pandas as pd - import xarray as xray - import xarray - import xarray as xr - - np.random.seed(123456) - -.. _whats-new.0.18.3: - -v0.18.3 (unreleased) ---------------------- - -New Features -~~~~~~~~~~~~ -- Added `storage_options` arg to :py:meth:`~xarray.Dataset.to_zarr` (:pull:`5615`). - By `Ray Bell `_. -- Allow passing a dictionary as coords to a :py:class:`DataArray` (:issue:`5527`, - reverts :pull:`1539`, which had deprecated this due to python's inconsistent ordering in earlier versions). - By `Sander van Rijn `_. -- Added :py:meth:`Dataset.coarsen.construct`, :py:meth:`DataArray.coarsen.construct` (:issue:`5454`, :pull:`5475`). - By `Deepak Cherian `_. -- Xarray now uses consolidated metadata by default when writing and reading Zarr - stores (:issue:`5251`). - By `Stephan Hoyer `_. -- New top-level function :py:func:`unify_chunks`. - By `Mattia Almansi `_. -- Allow assigning values to a subset of a dataset using positional or label-based - indexing (:issue:`3015`, :pull:`5362`). - By `Matthias Göbel `_. -- Attempting to reduce a weighted object over missing dimensions now raises an error (:pull:`5362`). - By `Mattia Almansi `_. -- Add ``.sum`` to :py:meth:`~xarray.DataArray.rolling_exp` and - :py:meth:`~xarray.Dataset.rolling_exp` for exponentially weighted rolling - sums. These require numbagg 0.2.1; - (:pull:`5178`). - By `Maximilian Roos `_. -- :py:func:`xarray.cov` and :py:func:`xarray.corr` now lazily check for missing - values if inputs are dask arrays (:issue:`4804`, :pull:`5284`). - By `Andrew Williams `_. -- Attempting to ``concat`` list of elements that are not all ``Dataset`` or all ``DataArray`` now raises an error (:issue:`5051`, :pull:`5425`). - By `Thomas Hirtz `_. -- allow passing a function to ``combine_attrs`` (:pull:`4896`). - By `Justus Magin `_. -- Allow plotting categorical data (:pull:`5464`). - By `Jimmy Westling `_. -- Allow removal of the coordinate attribute ``coordinates`` on variables by setting ``.attrs['coordinates']= None`` - (:issue:`5510`). - By `Elle Smith `_. - -Breaking changes -~~~~~~~~~~~~~~~~ - -- The default ``mode`` for :py:meth:`Dataset.to_zarr` when ``region`` is set - has changed to the new ``mode="r+"``, which only allows for overriding - pre-existing array values. This is a safer default than the prior ``mode="a"``, - and allows for higher performance writes (:pull:`5252`). - By `Stephan Hoyer `_. -- The main parameter to :py:func:`combine_by_coords` is renamed to `data_objects` instead - of `datasets` so anyone calling this method using a named parameter will need to update - the name accordingly (:issue:`3248`, :pull:`4696`). - By `Augustus Ijams `_. - -Deprecations -~~~~~~~~~~~~ - - -Bug fixes -~~~~~~~~~ -- Fix a minor incompatibility between partial datetime string indexing with a - :py:class:`CFTimeIndex` and upcoming pandas version 1.3.0 (:issue:`5356`, - :pull:`5359`). - By `Spencer Clark `_. -- Fix 1-level multi-index incorrectly converted to single index (:issue:`5384`, - :pull:`5385`). - By `Benoit Bovy `_. -- Don't cast a duck array in a coordinate to :py:class:`numpy.ndarray` in - :py:meth:`DataArray.differentiate` (:pull:`5408`) - By `Justus Magin `_. -- Fix the ``repr`` of :py:class:`Variable` objects with ``display_expand_data=True`` - (:pull:`5406`) - By `Justus Magin `_. -- Plotting a pcolormesh with ``xscale="log"`` and/or ``yscale="log"`` works as - expected after improving the way the interval breaks are generated (:issue:`5333`). - By `Santiago Soler `_ -- :py:func:`combine_by_coords` can now handle combining a list of unnamed - ``DataArray`` as input (:issue:`3248`, :pull:`4696`). - By `Augustus Ijams `_. - - -Documentation -~~~~~~~~~~~~~ - - -Internal Changes -~~~~~~~~~~~~~~~~ -- Run CI on the first & last python versions supported only; currently 3.7 & 3.9. - (:pull:`5433`) - By `Maximilian Roos `_. -- Publish test results & timings on each PR. - (:pull:`5537`) - By `Maximilian Roos `_. - -- Explicit indexes refactor: add a ``xarray.Index.query()`` method in which - one may eventually provide a custom implementation of label-based data - selection (not ready yet for public use). Also refactor the internal, - pandas-specific implementation into ``PandasIndex.query()`` and - ``PandasMultiIndex.query()`` (:pull:`5322`). - By `Benoit Bovy `_. - -.. _whats-new.0.18.2: - -v0.18.2 (19 May 2021) ---------------------- - -This release reverts a regression in xarray's unstacking of dask-backed arrays. - -.. _whats-new.0.18.1: - -v0.18.1 (18 May 2021) ---------------------- - -This release is intended as a small patch release to be compatible with the new -2021.5.0 ``dask.distributed`` release. It also includes a new -``drop_duplicates`` method, some documentation improvements, the beginnings of -our internal Index refactoring, and some bug fixes. - -Thank you to all 16 contributors! - -Anderson Banihirwe, Andrew, Benoit Bovy, Brewster Malevich, Giacomo Caria, -Illviljan, James Bourbeau, Keewis, Maximilian Roos, Ravin Kumar, Stephan Hoyer, -Thomas Nicholas, Tom Nicholas, Zachary Moon. - -New Features -~~~~~~~~~~~~ -- Implement :py:meth:`DataArray.drop_duplicates` - to remove duplicate dimension values (:pull:`5239`). - By `Andrew Huang `_. -- Allow passing ``combine_attrs`` strategy names to the ``keep_attrs`` parameter of - :py:func:`apply_ufunc` (:pull:`5041`) - By `Justus Magin `_. -- :py:meth:`Dataset.interp` now allows interpolation with non-numerical datatypes, - such as booleans, instead of dropping them. (:issue:`4761` :pull:`5008`). - By `Jimmy Westling `_. -- Raise more informative error when decoding time variables with invalid reference dates. - (:issue:`5199`, :pull:`5288`). By `Giacomo Caria `_. - -Breaking changes -~~~~~~~~~~~~~~~~ - - -Deprecations -~~~~~~~~~~~~ - - -Bug fixes -~~~~~~~~~ -- Opening netCDF files from a path that doesn't end in ``.nc`` without supplying - an explicit ``engine`` works again (:issue:`5295`), fixing a bug introduced in - 0.18.0. - By `Stephan Hoyer `_ - -Documentation -~~~~~~~~~~~~~ -- Clean up and enhance docstrings for the :py:class:`DataArray.plot` and ``Dataset.plot.*`` - families of methods (:pull:`5285`). - By `Zach Moon `_. - -- Explanation of deprecation cycles and how to implement them added to contributors - guide. (:pull:`5289`) - By `Tom Nicholas `_. - - -Internal Changes -~~~~~~~~~~~~~~~~ - -- Explicit indexes refactor: add an ``xarray.Index`` base class and - ``Dataset.xindexes`` / ``DataArray.xindexes`` properties. Also rename - ``PandasIndexAdapter`` to ``PandasIndex``, which now inherits from - ``xarray.Index`` (:pull:`5102`). - By `Benoit Bovy `_. -- Replace ``SortedKeysDict`` with python's ``dict``, given dicts are now ordered. - By `Maximilian Roos `_. -- Updated the release guide for developers. Now accounts for actions that are automated via github - actions. (:pull:`5274`). - By `Tom Nicholas `_. - -.. _whats-new.0.18.0: - -v0.18.0 (6 May 2021) --------------------- - -This release brings a few important performance improvements, a wide range of -usability upgrades, lots of bug fixes, and some new features. These include -a plugin API to add backend engines, a new theme for the documentation, -curve fitting methods, and several new plotting functions. - -Many thanks to the 38 contributors to this release: Aaron Spring, Alessandro Amici, -Alex Marandon, Alistair Miles, Ana Paula Krelling, Anderson Banihirwe, Aureliana Barghini, -Baudouin Raoult, Benoit Bovy, Blair Bonnett, David Trémouilles, Deepak Cherian, -Gabriel Medeiros Abrahão, Giacomo Caria, Hauke Schulz, Illviljan, Mathias Hauser, Matthias Bussonnier, -Mattia Almansi, Maximilian Roos, Ray Bell, Richard Kleijn, Ryan Abernathey, Sam Levang, Spencer Clark, -Spencer Jones, Tammas Loughran, Tobias Kölling, Todd, Tom Nicholas, Tom White, Victor Negîrneac, -Xianxiang Li, Zeb Nicholls, crusaderky, dschwoerer, johnomotani, keewis - - -New Features -~~~~~~~~~~~~ - -- apply ``combine_attrs`` on data variables and coordinate variables when concatenating - and merging datasets and dataarrays (:pull:`4902`). - By `Justus Magin `_. -- Add :py:meth:`Dataset.to_pandas` (:pull:`5247`) - By `Giacomo Caria `_. -- Add :py:meth:`DataArray.plot.surface` which wraps matplotlib's `plot_surface` to make - surface plots (:issue:`2235` :issue:`5084` :pull:`5101`). - By `John Omotani `_. -- Allow passing multiple arrays to :py:meth:`Dataset.__setitem__` (:pull:`5216`). - By `Giacomo Caria `_. -- Add 'cumulative' option to :py:meth:`Dataset.integrate` and - :py:meth:`DataArray.integrate` so that result is a cumulative integral, like - :py:func:`scipy.integrate.cumulative_trapezoidal` (:pull:`5153`). - By `John Omotani `_. -- Add ``safe_chunks`` option to :py:meth:`Dataset.to_zarr` which allows overriding - checks made to ensure Dask and Zarr chunk compatibility (:issue:`5056`). - By `Ryan Abernathey `_ -- Add :py:meth:`Dataset.query` and :py:meth:`DataArray.query` which enable indexing - of datasets and data arrays by evaluating query expressions against the values of the - data variables (:pull:`4984`). - By `Alistair Miles `_. -- Allow passing ``combine_attrs`` to :py:meth:`Dataset.merge` (:pull:`4895`). - By `Justus Magin `_. -- Support for `dask.graph_manipulation - `_ (requires dask >=2021.3) - By `Guido Imperiale `_ -- Add :py:meth:`Dataset.plot.streamplot` for streamplot plots with :py:class:`Dataset` - variables (:pull:`5003`). - By `John Omotani `_. -- Many of the arguments for the :py:attr:`DataArray.str` methods now support - providing an array-like input. In this case, the array provided to the - arguments is broadcast against the original array and applied elementwise. -- :py:attr:`DataArray.str` now supports ``+``, ``*``, and ``%`` operators. These - behave the same as they do for :py:class:`str`, except that they follow - array broadcasting rules. -- A large number of new :py:attr:`DataArray.str` methods were implemented, - :py:meth:`DataArray.str.casefold`, :py:meth:`DataArray.str.cat`, - :py:meth:`DataArray.str.extract`, :py:meth:`DataArray.str.extractall`, - :py:meth:`DataArray.str.findall`, :py:meth:`DataArray.str.format`, - :py:meth:`DataArray.str.get_dummies`, :py:meth:`DataArray.str.islower`, - :py:meth:`DataArray.str.join`, :py:meth:`DataArray.str.normalize`, - :py:meth:`DataArray.str.partition`, :py:meth:`DataArray.str.rpartition`, - :py:meth:`DataArray.str.rsplit`, and :py:meth:`DataArray.str.split`. - A number of these methods allow for splitting or joining the strings in an - array. (:issue:`4622`) - By `Todd Jennings `_ -- Thanks to the new pluggable backend infrastructure external packages may now - use the ``xarray.backends`` entry point to register additional engines to be used in - :py:func:`open_dataset`, see the documentation in :ref:`add_a_backend` - (:issue:`4309`, :issue:`4803`, :pull:`4989`, :pull:`4810` and many others). - The backend refactor has been sponsored with the "Essential Open Source Software for Science" - grant from the `Chan Zuckerberg Initiative `_ and - developed by `B-Open `_. - By `Aureliana Barghini `_ and `Alessandro Amici `_. -- :py:attr:`~core.accessor_dt.DatetimeAccessor.date` added (:issue:`4983`, :pull:`4994`). - By `Hauke Schulz `_. -- Implement ``__getitem__`` for both :py:class:`~core.groupby.DatasetGroupBy` and - :py:class:`~core.groupby.DataArrayGroupBy`, inspired by pandas' - :py:meth:`~pandas.core.groupby.GroupBy.get_group`. - By `Deepak Cherian `_. -- Switch the tutorial functions to use `pooch `_ - (which is now a optional dependency) and add :py:func:`tutorial.open_rasterio` as a - way to open example rasterio files (:issue:`3986`, :pull:`4102`, :pull:`5074`). - By `Justus Magin `_. -- Add typing information to unary and binary arithmetic operators operating on - :py:class:`Dataset`, :py:class:`DataArray`, :py:class:`Variable`, - :py:class:`~core.groupby.DatasetGroupBy` or - :py:class:`~core.groupby.DataArrayGroupBy` (:pull:`4904`). - By `Richard Kleijn `_. -- Add a ``combine_attrs`` parameter to :py:func:`open_mfdataset` (:pull:`4971`). - By `Justus Magin `_. -- Enable passing arrays with a subset of dimensions to - :py:meth:`DataArray.clip` & :py:meth:`Dataset.clip`; these methods now use - :py:func:`xarray.apply_ufunc`; (:pull:`5184`). - By `Maximilian Roos `_. -- Disable the `cfgrib` backend if the `eccodes` library is not installed (:pull:`5083`). - By `Baudouin Raoult `_. -- Added :py:meth:`DataArray.curvefit` and :py:meth:`Dataset.curvefit` for general curve fitting applications. (:issue:`4300`, :pull:`4849`) - By `Sam Levang `_. -- Add options to control expand/collapse of sections in display of Dataset and - DataArray. The function :py:func:`set_options` now takes keyword aguments - ``display_expand_attrs``, ``display_expand_coords``, ``display_expand_data``, - ``display_expand_data_vars``, all of which can be one of ``True`` to always - expand, ``False`` to always collapse, or ``default`` to expand unless over a - pre-defined limit (:pull:`5126`). - By `Tom White `_. -- Significant speedups in :py:meth:`Dataset.interp` and :py:meth:`DataArray.interp`. - (:issue:`4739`, :pull:`4740`). - By `Deepak Cherian `_. -- Prevent passing `concat_dim` to :py:func:`xarray.open_mfdataset` when - `combine='by_coords'` is specified, which should never have been possible (as - :py:func:`xarray.combine_by_coords` has no `concat_dim` argument to pass to). - Also removes unneeded internal reordering of datasets in - :py:func:`xarray.open_mfdataset` when `combine='by_coords'` is specified. - Fixes (:issue:`5230`). - By `Tom Nicholas `_. -- Implement ``__setitem__`` for ``xarray.core.indexing.DaskIndexingAdapter`` if - dask version supports item assignment. (:issue:`5171`, :pull:`5174`) - By `Tammas Loughran `_. - -Breaking changes -~~~~~~~~~~~~~~~~ -- The minimum versions of some dependencies were changed: - - ============ ====== ==== - Package Old New - ============ ====== ==== - boto3 1.12 1.13 - cftime 1.0 1.1 - dask 2.11 2.15 - distributed 2.11 2.15 - matplotlib 3.1 3.2 - numba 0.48 0.49 - ============ ====== ==== - -- :py:func:`open_dataset` and :py:func:`open_dataarray` now accept only the first argument - as positional, all others need to be passed are keyword arguments. This is part of the - refactor to support external backends (:issue:`4309`, :pull:`4989`). - By `Alessandro Amici `_. -- Functions that are identities for 0d data return the unchanged data - if axis is empty. This ensures that Datasets where some variables do - not have the averaged dimensions are not accidentially changed - (:issue:`4885`, :pull:`5207`). - By `David Schwörer `_. -- :py:attr:`DataArray.coarsen` and :py:attr:`Dataset.coarsen` no longer support passing ``keep_attrs`` - via its constructor. Pass ``keep_attrs`` via the applied function, i.e. use - ``ds.coarsen(...).mean(keep_attrs=False)`` instead of ``ds.coarsen(..., keep_attrs=False).mean()``. - Further, coarsen now keeps attributes per default (:pull:`5227`). - By `Mathias Hauser `_. -- switch the default of the :py:func:`merge` ``combine_attrs`` parameter to - ``"override"``. This will keep the current behavior for merging the ``attrs`` of - variables but stop dropping the ``attrs`` of the main objects (:pull:`4902`). - By `Justus Magin `_. - -Deprecations -~~~~~~~~~~~~ - -- Warn when passing `concat_dim` to :py:func:`xarray.open_mfdataset` when - `combine='by_coords'` is specified, which should never have been possible (as - :py:func:`xarray.combine_by_coords` has no `concat_dim` argument to pass to). - Also removes unneeded internal reordering of datasets in - :py:func:`xarray.open_mfdataset` when `combine='by_coords'` is specified. - Fixes (:issue:`5230`), via (:pull:`5231`, :pull:`5255`). - By `Tom Nicholas `_. -- The `lock` keyword argument to :py:func:`open_dataset` and :py:func:`open_dataarray` is now - a backend specific option. It will give a warning if passed to a backend that doesn't support it - instead of being silently ignored. From the next version it will raise an error. - This is part of the refactor to support external backends (:issue:`5073`). - By `Tom Nicholas `_ and `Alessandro Amici `_. - - -Bug fixes -~~~~~~~~~ -- Properly support :py:meth:`DataArray.ffill`, :py:meth:`DataArray.bfill`, :py:meth:`Dataset.ffill`, :py:meth:`Dataset.bfill` along chunked dimensions. - (:issue:`2699`). - By `Deepak Cherian `_. -- Fix 2d plot failure for certain combinations of dimensions when `x` is 1d and `y` is - 2d (:issue:`5097`, :pull:`5099`). - By `John Omotani `_. -- Ensure standard calendar times encoded with large values (i.e. greater than - approximately 292 years), can be decoded correctly without silently overflowing - (:pull:`5050`). This was a regression in xarray 0.17.0. - By `Zeb Nicholls `_. -- Added support for `numpy.bool_` attributes in roundtrips using `h5netcdf` engine with `invalid_netcdf=True` [which casts `bool`s to `numpy.bool_`] (:issue:`4981`, :pull:`4986`). - By `Victor Negîrneac `_. -- Don't allow passing ``axis`` to :py:meth:`Dataset.reduce` methods (:issue:`3510`, :pull:`4940`). - By `Justus Magin `_. -- Decode values as signed if attribute `_Unsigned = "false"` (:issue:`4954`) - By `Tobias Kölling `_. -- Keep coords attributes when interpolating when the indexer is not a Variable. (:issue:`4239`, :issue:`4839` :pull:`5031`) - By `Jimmy Westling `_. -- Ensure standard calendar dates encoded with a calendar attribute with some or - all uppercase letters can be decoded or encoded to or from - ``np.datetime64[ns]`` dates with or without ``cftime`` installed - (:issue:`5093`, :pull:`5180`). - By `Spencer Clark `_. -- Warn on passing ``keep_attrs`` to ``resample`` and ``rolling_exp`` as they are ignored, pass ``keep_attrs`` - to the applied function instead (:pull:`5265`). - By `Mathias Hauser `_. - -Documentation -~~~~~~~~~~~~~ -- New section on :ref:`add_a_backend` in the "Internals" chapter aimed to backend developers - (:issue:`4803`, :pull:`4810`). - By `Aureliana Barghini `_. -- Add :py:meth:`Dataset.polyfit` and :py:meth:`DataArray.polyfit` under "See also" in - the docstrings of :py:meth:`Dataset.polyfit` and :py:meth:`DataArray.polyfit` - (:issue:`5016`, :pull:`5020`). - By `Aaron Spring `_. -- New sphinx theme & rearrangement of the docs (:pull:`4835`). - By `Anderson Banihirwe `_. - -Internal Changes -~~~~~~~~~~~~~~~~ -- Enable displaying mypy error codes and ignore only specific error codes using - ``# type: ignore[error-code]`` (:pull:`5096`). - By `Mathias Hauser `_. -- Replace uses of ``raises_regex`` with the more standard - ``pytest.raises(Exception, match="foo")``; - (:pull:`5188`), (:pull:`5191`). - By `Maximilian Roos `_. - -.. _whats-new.0.17.0: - -v0.17.0 (24 Feb 2021) ---------------------- - -This release brings a few important performance improvements, a wide range of -usability upgrades, lots of bug fixes, and some new features. These include -better ``cftime`` support, a new quiver plot, better ``unstack`` performance, -more efficient memory use in rolling operations, and some python packaging -improvements. We also have a few documentation improvements (and more planned!). - -Many thanks to the 36 contributors to this release: Alessandro Amici, Anderson -Banihirwe, Aureliana Barghini, Ayrton Bourn, Benjamin Bean, Blair Bonnett, Chun -Ho Chow, DWesl, Daniel Mesejo-León, Deepak Cherian, Eric Keenan, Illviljan, Jens -Hedegaard Nielsen, Jody Klymak, Julien Seguinot, Julius Busecke, Kai Mühlbauer, -Leif Denby, Martin Durant, Mathias Hauser, Maximilian Roos, Michael Mann, Ray -Bell, RichardScottOZ, Spencer Clark, Tim Gates, Tom Nicholas, Yunus Sevinchan, -alexamici, aurghs, crusaderky, dcherian, ghislainp, keewis, rhkleijn - -Breaking changes -~~~~~~~~~~~~~~~~ -- xarray no longer supports python 3.6 - - The minimum version policy was changed to also apply to projects with irregular - releases. As a result, the minimum versions of some dependencies have changed: - - ============ ====== ==== - Package Old New - ============ ====== ==== - Python 3.6 3.7 - setuptools 38.4 40.4 - numpy 1.15 1.17 - pandas 0.25 1.0 - dask 2.9 2.11 - distributed 2.9 2.11 - bottleneck 1.2 1.3 - h5netcdf 0.7 0.8 - iris 2.2 2.4 - netcdf4 1.4 1.5 - pseudonetcdf 3.0 3.1 - rasterio 1.0 1.1 - scipy 1.3 1.4 - seaborn 0.9 0.10 - zarr 2.3 2.4 - ============ ====== ==== - - (:issue:`4688`, :pull:`4720`, :pull:`4907`, :pull:`4942`) -- As a result of :pull:`4684` the default units encoding for - datetime-like values (``np.datetime64[ns]`` or ``cftime.datetime``) will now - always be set such that ``int64`` values can be used. In the past, no units - finer than "seconds" were chosen, which would sometimes mean that ``float64`` - values were required, which would lead to inaccurate I/O round-trips. -- Variables referred to in attributes like ``bounds`` and ``grid_mapping`` - can be set as coordinate variables. These attributes are moved to - :py:attr:`DataArray.encoding` from :py:attr:`DataArray.attrs`. This behaviour - is controlled by the ``decode_coords`` kwarg to :py:func:`open_dataset` and - :py:func:`open_mfdataset`. The full list of decoded attributes is in - :ref:`weather-climate` (:pull:`2844`, :issue:`3689`) -- As a result of :pull:`4911` the output from calling :py:meth:`DataArray.sum` - or :py:meth:`DataArray.prod` on an integer array with ``skipna=True`` and a - non-None value for ``min_count`` will now be a float array rather than an - integer array. - -Deprecations -~~~~~~~~~~~~ - -- ``dim`` argument to :py:meth:`DataArray.integrate` is being deprecated in - favour of a ``coord`` argument, for consistency with :py:meth:`Dataset.integrate`. - For now using ``dim`` issues a ``FutureWarning``. It will be removed in - version 0.19.0 (:pull:`3993`). - By `Tom Nicholas `_. -- Deprecated ``autoclose`` kwargs from :py:func:`open_dataset` are removed (:pull:`4725`). - By `Aureliana Barghini `_. -- the return value of :py:meth:`Dataset.update` is being deprecated to make it work more - like :py:meth:`dict.update`. It will be removed in version 0.19.0 (:pull:`4932`). - By `Justus Magin `_. - -New Features -~~~~~~~~~~~~ -- :py:meth:`~xarray.cftime_range` and :py:meth:`DataArray.resample` now support - millisecond (``"L"`` or ``"ms"``) and microsecond (``"U"`` or ``"us"``) frequencies - for ``cftime.datetime`` coordinates (:issue:`4097`, :pull:`4758`). - By `Spencer Clark `_. -- Significantly higher ``unstack`` performance on numpy-backed arrays which - contain missing values; 8x faster than previous versions in our benchmark, and - now 2x faster than pandas (:pull:`4746`). - By `Maximilian Roos `_. -- Add :py:meth:`Dataset.plot.quiver` for quiver plots with :py:class:`Dataset` variables. - By `Deepak Cherian `_. -- Add ``"drop_conflicts"`` to the strategies supported by the ``combine_attrs`` kwarg - (:issue:`4749`, :pull:`4827`). - By `Justus Magin `_. -- Allow installing from git archives (:pull:`4897`). - By `Justus Magin `_. -- :py:class:`~core.rolling.DataArrayCoarsen` and :py:class:`~core.rolling.DatasetCoarsen` - now implement a ``reduce`` method, enabling coarsening operations with custom - reduction functions (:issue:`3741`, :pull:`4939`). - By `Spencer Clark `_. -- Most rolling operations use significantly less memory. (:issue:`4325`). - By `Deepak Cherian `_. -- Add :py:meth:`Dataset.drop_isel` and :py:meth:`DataArray.drop_isel` - (:issue:`4658`, :pull:`4819`). - By `Daniel Mesejo `_. -- Xarray now leverages updates as of cftime version 1.4.1, which enable exact I/O - roundtripping of ``cftime.datetime`` objects (:pull:`4758`). - By `Spencer Clark `_. -- :py:func:`open_dataset` and :py:func:`open_mfdataset` now accept ``fsspec`` URLs - (including globs for the latter) for ``engine="zarr"``, and so allow reading from - many remote and other file systems (:pull:`4461`) - By `Martin Durant `_ -- :py:meth:`DataArray.swap_dims` & :py:meth:`Dataset.swap_dims` now accept dims - in the form of kwargs as well as a dict, like most similar methods. - By `Maximilian Roos `_. - -Bug fixes -~~~~~~~~~ -- Use specific type checks in ``xarray.core.variable.as_compatible_data`` instead of - blanket access to ``values`` attribute (:issue:`2097`) - By `Yunus Sevinchan `_. -- :py:meth:`DataArray.resample` and :py:meth:`Dataset.resample` do not trigger - computations anymore if :py:meth:`Dataset.weighted` or - :py:meth:`DataArray.weighted` are applied (:issue:`4625`, :pull:`4668`). By - `Julius Busecke `_. -- :py:func:`merge` with ``combine_attrs='override'`` makes a copy of the attrs - (:issue:`4627`). -- By default, when possible, xarray will now always use values of - type ``int64`` when encoding and decoding ``numpy.datetime64[ns]`` datetimes. This - ensures that maximum precision and accuracy are maintained in the round-tripping - process (:issue:`4045`, :pull:`4684`). It also enables encoding and decoding standard - calendar dates with time units of nanoseconds (:pull:`4400`). - By `Spencer Clark `_ and `Mark Harfouche - `_. -- :py:meth:`DataArray.astype`, :py:meth:`Dataset.astype` and :py:meth:`Variable.astype` support - the ``order`` and ``subok`` parameters again. This fixes a regression introduced in version 0.16.1 - (:issue:`4644`, :pull:`4683`). - By `Richard Kleijn `_ . -- Remove dictionary unpacking when using ``.loc`` to avoid collision with ``.sel`` parameters (:pull:`4695`). - By `Anderson Banihirwe `_. -- Fix the legend created by :py:meth:`Dataset.plot.scatter` (:issue:`4641`, :pull:`4723`). - By `Justus Magin `_. -- Fix a crash in orthogonal indexing on geographic coordinates with ``engine='cfgrib'`` - (:issue:`4733` :pull:`4737`). - By `Alessandro Amici `_. -- Coordinates with dtype ``str`` or ``bytes`` now retain their dtype on many operations, - e.g. ``reindex``, ``align``, ``concat``, ``assign``, previously they were cast to an object dtype - (:issue:`2658` and :issue:`4543`). - By `Mathias Hauser `_. -- Limit number of data rows when printing large datasets. (:issue:`4736`, :pull:`4750`). - By `Jimmy Westling `_. -- Add ``missing_dims`` parameter to transpose (:issue:`4647`, :pull:`4767`). - By `Daniel Mesejo `_. -- Resolve intervals before appending other metadata to labels when plotting (:issue:`4322`, :pull:`4794`). - By `Justus Magin `_. -- Fix regression when decoding a variable with a ``scale_factor`` and ``add_offset`` given - as a list of length one (:issue:`4631`). - By `Mathias Hauser `_. -- Expand user directory paths (e.g. ``~/``) in :py:func:`open_mfdataset` and - :py:meth:`Dataset.to_zarr` (:issue:`4783`, :pull:`4795`). - By `Julien Seguinot `_. -- Raise DeprecationWarning when trying to typecast a tuple containing a :py:class:`DataArray`. - User now prompted to first call `.data` on it (:issue:`4483`). - By `Chun Ho Chow `_. -- Ensure that :py:meth:`Dataset.interp` raises ``ValueError`` when interpolating - outside coordinate range and ``bounds_error=True`` (:issue:`4854`, - :pull:`4855`). - By `Leif Denby `_. -- Fix time encoding bug associated with using cftime versions greater than - 1.4.0 with xarray (:issue:`4870`, :pull:`4871`). - By `Spencer Clark `_. -- Stop :py:meth:`DataArray.sum` and :py:meth:`DataArray.prod` computing lazy - arrays when called with a ``min_count`` parameter (:issue:`4898`, :pull:`4911`). - By `Blair Bonnett `_. -- Fix bug preventing the ``min_count`` parameter to :py:meth:`DataArray.sum` and - :py:meth:`DataArray.prod` working correctly when calculating over all axes of - a float64 array (:issue:`4898`, :pull:`4911`). - By `Blair Bonnett `_. -- Fix decoding of vlen strings using h5py versions greater than 3.0.0 with h5netcdf backend (:issue:`4570`, :pull:`4893`). - By `Kai Mühlbauer `_. -- Allow converting :py:class:`Dataset` or :py:class:`DataArray` objects with a ``MultiIndex`` - and at least one other dimension to a ``pandas`` object (:issue:`3008`, :pull:`4442`). - By `ghislainp `_. - -Documentation -~~~~~~~~~~~~~ -- Add information about requirements for accessor classes (:issue:`2788`, :pull:`4657`). - By `Justus Magin `_. -- Start a list of external I/O integrating with ``xarray`` (:issue:`683`, :pull:`4566`). - By `Justus Magin `_. -- Add concat examples and improve combining documentation (:issue:`4620`, :pull:`4645`). - By `Ray Bell `_ and - `Justus Magin `_. -- explicitly mention that :py:meth:`Dataset.update` updates inplace (:issue:`2951`, :pull:`4932`). - By `Justus Magin `_. -- Added docs on vectorized indexing (:pull:`4711`). - By `Eric Keenan `_. - -Internal Changes -~~~~~~~~~~~~~~~~ -- Speed up of the continuous integration tests on azure. - - - Switched to mamba and use matplotlib-base for a faster installation of all dependencies (:pull:`4672`). - - Use ``pytest.mark.skip`` instead of ``pytest.mark.xfail`` for some tests that can currently not - succeed (:pull:`4685`). - - Run the tests in parallel using pytest-xdist (:pull:`4694`). - - By `Justus Magin `_ and `Mathias Hauser `_. -- Use ``pyproject.toml`` instead of the ``setup_requires`` option for - ``setuptools`` (:pull:`4897`). - By `Justus Magin `_. -- Replace all usages of ``assert x.identical(y)`` with ``assert_identical(x, y)`` - for clearer error messages (:pull:`4752`). - By `Maximilian Roos `_. -- Speed up attribute style access (e.g. ``ds.somevar`` instead of ``ds["somevar"]``) and - tab completion in IPython (:issue:`4741`, :pull:`4742`). - By `Richard Kleijn `_. -- Added the ``set_close`` method to ``Dataset`` and ``DataArray`` for backends - to specify how to voluntary release all resources. (:pull:`#4809`) - By `Alessandro Amici `_. -- Update type hints to work with numpy v1.20 (:pull:`4878`). - By `Mathias Hauser `_. -- Ensure warnings cannot be turned into exceptions in :py:func:`testing.assert_equal` and - the other ``assert_*`` functions (:pull:`4864`). - By `Mathias Hauser `_. -- Performance improvement when constructing DataArrays. Significantly speeds up - repr for Datasets with large number of variables. - By `Deepak Cherian `_. - -.. _whats-new.0.16.2: - -v0.16.2 (30 Nov 2020) ---------------------- - -This release brings the ability to write to limited regions of ``zarr`` files, -open zarr files with :py:func:`open_dataset` and :py:func:`open_mfdataset`, -increased support for propagating ``attrs`` using the ``keep_attrs`` flag, as -well as numerous bugfixes and documentation improvements. - -Many thanks to the 31 contributors who contributed to this release: Aaron -Spring, Akio Taniguchi, Aleksandar Jelenak, alexamici, Alexandre Poux, Anderson -Banihirwe, Andrew Pauling, Ashwin Vishnu, aurghs, Brian Ward, Caleb, crusaderky, -Dan Nowacki, darikg, David Brochart, David Huard, Deepak Cherian, Dion Häfner, -Gerardo Rivera, Gerrit Holl, Illviljan, inakleinbottle, Jacob Tomlinson, James -A. Bednar, jenssss, Joe Hamman, johnomotani, Joris Van den Bossche, Julia Kent, -Julius Busecke, Kai Mühlbauer, keewis, Keisuke Fujii, Kyle Cranmer, Luke -Volpatti, Mathias Hauser, Maximilian Roos, Michaël Defferrard, Michal -Baumgartner, Nick R. Papior, Pascal Bourgault, Peter Hausamann, PGijsbers, Ray -Bell, Romain Martinez, rpgoldman, Russell Manser, Sahid Velji, Samnan Rahee, -Sander, Spencer Clark, Stephan Hoyer, Thomas Zilio, Tobias Kölling, Tom -Augspurger, Wei Ji, Yash Saboo, Zeb Nicholls, - -Deprecations -~~~~~~~~~~~~ - -- :py:attr:`~core.accessor_dt.DatetimeAccessor.weekofyear` and :py:attr:`~core.accessor_dt.DatetimeAccessor.week` - have been deprecated. Use ``DataArray.dt.isocalendar().week`` - instead (:pull:`4534`). By `Mathias Hauser `_. - `Maximilian Roos `_, and `Spencer Clark `_. -- :py:attr:`DataArray.rolling` and :py:attr:`Dataset.rolling` no longer support passing ``keep_attrs`` - via its constructor. Pass ``keep_attrs`` via the applied function, i.e. use - ``ds.rolling(...).mean(keep_attrs=False)`` instead of ``ds.rolling(..., keep_attrs=False).mean()`` - Rolling operations now keep their attributes per default (:pull:`4510`). - By `Mathias Hauser `_. - -New Features -~~~~~~~~~~~~ - -- :py:func:`open_dataset` and :py:func:`open_mfdataset` - now works with ``engine="zarr"`` (:issue:`3668`, :pull:`4003`, :pull:`4187`). - By `Miguel Jimenez `_ and `Wei Ji Leong `_. -- Unary & binary operations follow the ``keep_attrs`` flag (:issue:`3490`, :issue:`4065`, :issue:`3433`, :issue:`3595`, :pull:`4195`). - By `Deepak Cherian `_. -- Added :py:meth:`~core.accessor_dt.DatetimeAccessor.isocalendar()` that returns a Dataset - with year, week, and weekday calculated according to the ISO 8601 calendar. Requires - pandas version 1.1.0 or greater (:pull:`4534`). By `Mathias Hauser `_, - `Maximilian Roos `_, and `Spencer Clark `_. -- :py:meth:`Dataset.to_zarr` now supports a ``region`` keyword for writing to - limited regions of existing Zarr stores (:pull:`4035`). - See :ref:`io.zarr.appending` for full details. - By `Stephan Hoyer `_. -- Added typehints in :py:func:`align` to reflect that the same type received in ``objects`` arg will be returned (:pull:`4522`). - By `Michal Baumgartner `_. -- :py:meth:`Dataset.weighted` and :py:meth:`DataArray.weighted` are now executing value checks lazily if weights are provided as dask arrays (:issue:`4541`, :pull:`4559`). - By `Julius Busecke `_. -- Added the ``keep_attrs`` keyword to ``rolling_exp.mean()``; it now keeps attributes - per default. By `Mathias Hauser `_ (:pull:`4592`). -- Added ``freq`` as property to :py:class:`CFTimeIndex` and into the - ``CFTimeIndex.repr``. (:issue:`2416`, :pull:`4597`) - By `Aaron Spring `_. - -Bug fixes -~~~~~~~~~ - -- Fix bug where reference times without padded years (e.g. ``since 1-1-1``) would lose their units when - being passed by ``encode_cf_datetime`` (:issue:`4422`, :pull:`4506`). Such units are ambiguous - about which digit represents the years (is it YMD or DMY?). Now, if such formatting is encountered, - it is assumed that the first digit is the years, they are padded appropriately (to e.g. ``since 0001-1-1``) - and a warning that this assumption is being made is issued. Previously, without ``cftime``, such times - would be silently parsed incorrectly (at least based on the CF conventions) e.g. "since 1-1-1" would - be parsed (via ``pandas`` and ``dateutil``) to ``since 2001-1-1``. - By `Zeb Nicholls `_. -- Fix :py:meth:`DataArray.plot.step`. By `Deepak Cherian `_. -- Fix bug where reading a scalar value from a NetCDF file opened with the ``h5netcdf`` backend would raise a ``ValueError`` when ``decode_cf=True`` (:issue:`4471`, :pull:`4485`). - By `Gerrit Holl `_. -- Fix bug where datetime64 times are silently changed to incorrect values if they are outside the valid date range for ns precision when provided in some other units (:issue:`4427`, :pull:`4454`). - By `Andrew Pauling `_ -- Fix silently overwriting the ``engine`` key when passing :py:func:`open_dataset` a file object - to an incompatible netCDF (:issue:`4457`). Now incompatible combinations of files and engines raise - an exception instead. By `Alessandro Amici `_. -- The ``min_count`` argument to :py:meth:`DataArray.sum()` and :py:meth:`DataArray.prod()` - is now ignored when not applicable, i.e. when ``skipna=False`` or when ``skipna=None`` - and the dtype does not have a missing value (:issue:`4352`). - By `Mathias Hauser `_. -- :py:func:`combine_by_coords` now raises an informative error when passing coordinates - with differing calendars (:issue:`4495`). By `Mathias Hauser `_. -- :py:attr:`DataArray.rolling` and :py:attr:`Dataset.rolling` now also keep the attributes and names of of (wrapped) - ``DataArray`` objects, previously only the global attributes were retained (:issue:`4497`, :pull:`4510`). - By `Mathias Hauser `_. -- Improve performance where reading small slices from huge dimensions was slower than necessary (:pull:`4560`). By `Dion Häfner `_. -- Fix bug where ``dask_gufunc_kwargs`` was silently changed in :py:func:`apply_ufunc` (:pull:`4576`). By `Kai Mühlbauer `_. - -Documentation -~~~~~~~~~~~~~ -- document the API not supported with duck arrays (:pull:`4530`). - By `Justus Magin `_. -- Mention the possibility to pass functions to :py:meth:`Dataset.where` or - :py:meth:`DataArray.where` in the parameter documentation (:issue:`4223`, :pull:`4613`). - By `Justus Magin `_. -- Update the docstring of :py:class:`DataArray` and :py:class:`Dataset`. - (:pull:`4532`); - By `Jimmy Westling `_. -- Raise a more informative error when :py:meth:`DataArray.to_dataframe` is - is called on a scalar, (:issue:`4228`); - By `Pieter Gijsbers `_. -- Fix grammar and typos in the :doc:`contributing` guide (:pull:`4545`). - By `Sahid Velji `_. -- Fix grammar and typos in the :doc:`user-guide/io` guide (:pull:`4553`). - By `Sahid Velji `_. -- Update link to NumPy docstring standard in the :doc:`contributing` guide (:pull:`4558`). - By `Sahid Velji `_. -- Add docstrings to ``isnull`` and ``notnull``, and fix the displayed signature - (:issue:`2760`, :pull:`4618`). - By `Justus Magin `_. - -Internal Changes -~~~~~~~~~~~~~~~~ - -- Optional dependencies can be installed along with xarray by specifying - extras as ``pip install "xarray[extra]"`` where ``extra`` can be one of ``io``, - ``accel``, ``parallel``, ``viz`` and ``complete``. See docs for updated - :ref:`installation instructions `. - (:issue:`2888`, :pull:`4480`). - By `Ashwin Vishnu `_, `Justus Magin - `_ and `Mathias Hauser - `_. -- Removed stray spaces that stem from black removing new lines (:pull:`4504`). - By `Mathias Hauser `_. -- Ensure tests are not skipped in the ``py38-all-but-dask`` test environment - (:issue:`4509`). By `Mathias Hauser `_. -- Ignore select numpy warnings around missing values, where xarray handles - the values appropriately, (:pull:`4536`); - By `Maximilian Roos `_. -- Replace the internal use of ``pd.Index.__or__`` and ``pd.Index.__and__`` with ``pd.Index.union`` - and ``pd.Index.intersection`` as they will stop working as set operations in the future - (:issue:`4565`). By `Mathias Hauser `_. -- Add GitHub action for running nightly tests against upstream dependencies (:pull:`4583`). - By `Anderson Banihirwe `_. -- Ensure all figures are closed properly in plot tests (:pull:`4600`). - By `Yash Saboo `_, `Nirupam K N - `_ and `Mathias Hauser - `_. - -.. _whats-new.0.16.1: - -v0.16.1 (2020-09-20) ---------------------- - -This patch release fixes an incompatibility with a recent pandas change, which -was causing an issue indexing with a ``datetime64``. It also includes -improvements to ``rolling``, ``to_dataframe``, ``cov`` & ``corr`` methods and -bug fixes. Our documentation has a number of improvements, including fixing all -doctests and confirming their accuracy on every commit. - -Many thanks to the 36 contributors who contributed to this release: - -Aaron Spring, Akio Taniguchi, Aleksandar Jelenak, Alexandre Poux, -Caleb, Dan Nowacki, Deepak Cherian, Gerardo Rivera, Jacob Tomlinson, James A. -Bednar, Joe Hamman, Julia Kent, Kai Mühlbauer, Keisuke Fujii, Mathias Hauser, -Maximilian Roos, Nick R. Papior, Pascal Bourgault, Peter Hausamann, Romain -Martinez, Russell Manser, Samnan Rahee, Sander, Spencer Clark, Stephan Hoyer, -Thomas Zilio, Tobias Kölling, Tom Augspurger, alexamici, crusaderky, darikg, -inakleinbottle, jenssss, johnomotani, keewis, and rpgoldman. - -Breaking changes -~~~~~~~~~~~~~~~~ - -- :py:meth:`DataArray.astype` and :py:meth:`Dataset.astype` now preserve attributes. Keep the - old behavior by passing `keep_attrs=False` (:issue:`2049`, :pull:`4314`). - By `Dan Nowacki `_ and `Gabriel Joel Mitchell `_. - -New Features -~~~~~~~~~~~~ - -- :py:meth:`~xarray.DataArray.rolling` and :py:meth:`~xarray.Dataset.rolling` - now accept more than 1 dimension. (:pull:`4219`) - By `Keisuke Fujii `_. -- :py:meth:`~xarray.DataArray.to_dataframe` and :py:meth:`~xarray.Dataset.to_dataframe` - now accept a ``dim_order`` parameter allowing to specify the resulting dataframe's - dimensions order (:issue:`4331`, :pull:`4333`). - By `Thomas Zilio `_. -- Support multiple outputs in :py:func:`xarray.apply_ufunc` when using - ``dask='parallelized'``. (:issue:`1815`, :pull:`4060`). - By `Kai Mühlbauer `_. -- ``min_count`` can be supplied to reductions such as ``.sum`` when specifying - multiple dimension to reduce over; (:pull:`4356`). - By `Maximilian Roos `_. -- :py:func:`xarray.cov` and :py:func:`xarray.corr` now handle missing values; (:pull:`4351`). - By `Maximilian Roos `_. -- Add support for parsing datetime strings formatted following the default - string representation of cftime objects, i.e. YYYY-MM-DD hh:mm:ss, in - partial datetime string indexing, as well as :py:meth:`~xarray.cftime_range` - (:issue:`4337`). By `Spencer Clark `_. -- Build ``CFTimeIndex.__repr__`` explicitly as :py:class:`pandas.Index`. Add ``calendar`` as a new - property for :py:class:`CFTimeIndex` and show ``calendar`` and ``length`` in - ``CFTimeIndex.__repr__`` (:issue:`2416`, :pull:`4092`) - By `Aaron Spring `_. -- Use a wrapped array's ``_repr_inline_`` method to construct the collapsed ``repr`` - of :py:class:`DataArray` and :py:class:`Dataset` objects and - document the new method in :doc:`internals/index`. (:pull:`4248`). - By `Justus Magin `_. -- Allow per-variable fill values in most functions. (:pull:`4237`). - By `Justus Magin `_. -- Expose ``use_cftime`` option in :py:func:`~xarray.open_zarr` (:issue:`2886`, :pull:`3229`) - By `Samnan Rahee `_ and `Anderson Banihirwe `_. - -Bug fixes -~~~~~~~~~ - -- Fix indexing with datetime64 scalars with pandas 1.1 (:issue:`4283`). - By `Stephan Hoyer `_ and - `Justus Magin `_. -- Variables which are chunked using dask only along some dimensions can be chunked while storing with zarr along previously - unchunked dimensions (:pull:`4312`) By `Tobias Kölling `_. -- Fixed a bug in backend caused by basic installation of Dask (:issue:`4164`, :pull:`4318`) - `Sam Morley `_. -- Fixed a few bugs with :py:meth:`Dataset.polyfit` when encountering deficient matrix ranks (:issue:`4190`, :pull:`4193`). By `Pascal Bourgault `_. -- Fixed inconsistencies between docstring and functionality for :py:meth:`DataArray.str.get` - and :py:meth:`DataArray.str.wrap` (:issue:`4334`). By `Mathias Hauser `_. -- Fixed overflow issue causing incorrect results in computing means of :py:class:`cftime.datetime` - arrays (:issue:`4341`). By `Spencer Clark `_. -- Fixed :py:meth:`Dataset.coarsen`, :py:meth:`DataArray.coarsen` dropping attributes on original object (:issue:`4120`, :pull:`4360`). By `Julia Kent `_. -- fix the signature of the plot methods. (:pull:`4359`) By `Justus Magin `_. -- Fix :py:func:`xarray.apply_ufunc` with ``vectorize=True`` and ``exclude_dims`` (:issue:`3890`). - By `Mathias Hauser `_. -- Fix `KeyError` when doing linear interpolation to an nd `DataArray` - that contains NaNs (:pull:`4233`). - By `Jens Svensmark `_ -- Fix incorrect legend labels for :py:meth:`Dataset.plot.scatter` (:issue:`4126`). - By `Peter Hausamann `_. -- Fix ``dask.optimize`` on ``DataArray`` producing an invalid Dask task graph (:issue:`3698`) - By `Tom Augspurger `_ -- Fix ``pip install .`` when no ``.git`` directory exists; namely when the xarray source - directory has been rsync'ed by PyCharm Professional for a remote deployment over SSH. - By `Guido Imperiale `_ -- Preserve dimension and coordinate order during :py:func:`xarray.concat` (:issue:`2811`, :issue:`4072`, :pull:`4419`). - By `Kai Mühlbauer `_. -- Avoid relying on :py:class:`set` objects for the ordering of the coordinates (:pull:`4409`) - By `Justus Magin `_. - -Documentation -~~~~~~~~~~~~~ - -- Update the docstring of :py:meth:`DataArray.copy` to remove incorrect mention of 'dataset' (:issue:`3606`) - By `Sander van Rijn `_. -- Removed skipna argument from :py:meth:`DataArray.count`, :py:meth:`DataArray.any`, :py:meth:`DataArray.all`. (:issue:`755`) - By `Sander van Rijn `_ -- Update the contributing guide to use merges instead of rebasing and state - that we squash-merge. (:pull:`4355`). By `Justus Magin `_. -- Make sure the examples from the docstrings actually work (:pull:`4408`). - By `Justus Magin `_. -- Updated Vectorized Indexing to a clearer example. - By `Maximilian Roos `_ - -Internal Changes -~~~~~~~~~~~~~~~~ - -- Fixed all doctests and enabled their running in CI. - By `Justus Magin `_. -- Relaxed the :ref:`mindeps_policy` to support: - - - all versions of setuptools released in the last 42 months (but no older than 38.4) - - all versions of dask and dask.distributed released in the last 12 months (but no - older than 2.9) - - all versions of other packages released in the last 12 months - - All are up from 6 months (:issue:`4295`) - `Guido Imperiale `_. -- Use :py:func:`dask.array.apply_gufunc ` instead of - :py:func:`dask.array.blockwise` in :py:func:`xarray.apply_ufunc` when using - ``dask='parallelized'``. (:pull:`4060`, :pull:`4391`, :pull:`4392`) - By `Kai Mühlbauer `_. -- Align ``mypy`` versions to ``0.782`` across ``requirements`` and - ``.pre-commit-config.yml`` files. (:pull:`4390`) - By `Maximilian Roos `_ -- Only load resource files when running inside a Jupyter Notebook - (:issue:`4294`) By `Guido Imperiale `_ -- Silenced most ``numpy`` warnings such as ``Mean of empty slice``. (:pull:`4369`) - By `Maximilian Roos `_ -- Enable type checking for :py:func:`concat` (:issue:`4238`) - By `Mathias Hauser `_. -- Updated plot functions for matplotlib version 3.3 and silenced warnings in the - plot tests (:pull:`4365`). By `Mathias Hauser `_. -- Versions in ``pre-commit.yaml`` are now pinned, to reduce the chances of - conflicting versions. (:pull:`4388`) - By `Maximilian Roos `_ - - - -.. _whats-new.0.16.0: - -v0.16.0 (2020-07-11) ---------------------- - -This release adds `xarray.cov` & `xarray.corr` for covariance & correlation -respectively; the `idxmax` & `idxmin` methods, the `polyfit` method & -`xarray.polyval` for fitting polynomials, as well as a number of documentation -improvements, other features, and bug fixes. Many thanks to all 44 contributors -who contributed to this release: - -Akio Taniguchi, Andrew Williams, Aurélien Ponte, Benoit Bovy, Dave Cole, David -Brochart, Deepak Cherian, Elliott Sales de Andrade, Etienne Combrisson, Hossein -Madadi, Huite, Joe Hamman, Kai Mühlbauer, Keisuke Fujii, Maik Riechert, Marek -Jacob, Mathias Hauser, Matthieu Ancellin, Maximilian Roos, Noah D Brenowitz, -Oriol Abril, Pascal Bourgault, Phillip Butcher, Prajjwal Nijhara, Ray Bell, Ryan -Abernathey, Ryan May, Spencer Clark, Spencer Hill, Srijan Saurav, Stephan Hoyer, -Taher Chegini, Todd, Tom Nicholas, Yohai Bar Sinai, Yunus Sevinchan, -arabidopsis, aurghs, clausmichele, dmey, johnomotani, keewis, raphael dussin, -risebell - -Breaking changes -~~~~~~~~~~~~~~~~ - -- Minimum supported versions for the following packages have changed: ``dask >=2.9``, - ``distributed>=2.9``. - By `Deepak Cherian `_ -- ``groupby`` operations will restore coord dimension order. Pass ``restore_coord_dims=False`` - to revert to previous behavior. -- :meth:`DataArray.transpose` will now transpose coordinates by default. - Pass ``transpose_coords=False`` to revert to previous behaviour. - By `Maximilian Roos `_ -- Alternate draw styles for :py:meth:`plot.step` must be passed using the - ``drawstyle`` (or ``ds``) keyword argument, instead of the ``linestyle`` (or - ``ls``) keyword argument, in line with the `upstream change in Matplotlib - `_. - (:pull:`3274`) - By `Elliott Sales de Andrade `_ -- The old ``auto_combine`` function has now been removed in - favour of the :py:func:`combine_by_coords` and - :py:func:`combine_nested` functions. This also means that - the default behaviour of :py:func:`open_mfdataset` has changed to use - ``combine='by_coords'`` as the default argument value. (:issue:`2616`, :pull:`3926`) - By `Tom Nicholas `_. -- The ``DataArray`` and ``Variable`` HTML reprs now expand the data section by - default (:issue:`4176`) - By `Stephan Hoyer `_. - -New Features -~~~~~~~~~~~~ -- :py:meth:`DataArray.argmin` and :py:meth:`DataArray.argmax` now support - sequences of 'dim' arguments, and if a sequence is passed return a dict - (which can be passed to :py:meth:`DataArray.isel` to get the value of the minimum) of - the indices for each dimension of the minimum or maximum of a DataArray. - (:pull:`3936`) - By `John Omotani `_, thanks to `Keisuke Fujii - `_ for work in :pull:`1469`. -- Added :py:func:`xarray.cov` and :py:func:`xarray.corr` (:issue:`3784`, :pull:`3550`, :pull:`4089`). - By `Andrew Williams `_ and `Robin Beer `_. -- Implement :py:meth:`DataArray.idxmax`, :py:meth:`DataArray.idxmin`, - :py:meth:`Dataset.idxmax`, :py:meth:`Dataset.idxmin`. (:issue:`60`, :pull:`3871`) - By `Todd Jennings `_ -- Added :py:meth:`DataArray.polyfit` and :py:func:`xarray.polyval` for fitting - polynomials. (:issue:`3349`, :pull:`3733`, :pull:`4099`) - By `Pascal Bourgault `_. -- Added :py:meth:`xarray.infer_freq` for extending frequency inferring to CFTime indexes and data (:pull:`4033`). - By `Pascal Bourgault `_. -- ``chunks='auto'`` is now supported in the ``chunks`` argument of - :py:meth:`Dataset.chunk`. (:issue:`4055`) - By `Andrew Williams `_ -- Control over attributes of result in :py:func:`merge`, :py:func:`concat`, - :py:func:`combine_by_coords` and :py:func:`combine_nested` using - combine_attrs keyword argument. (:issue:`3865`, :pull:`3877`) - By `John Omotani `_ -- `missing_dims` argument to :py:meth:`Dataset.isel`, - :py:meth:`DataArray.isel` and :py:meth:`Variable.isel` to allow replacing - the exception when a dimension passed to ``isel`` is not present with a - warning, or just ignore the dimension. (:issue:`3866`, :pull:`3923`) - By `John Omotani `_ -- Support dask handling for :py:meth:`DataArray.idxmax`, :py:meth:`DataArray.idxmin`, - :py:meth:`Dataset.idxmax`, :py:meth:`Dataset.idxmin`. (:pull:`3922`, :pull:`4135`) - By `Kai Mühlbauer `_ and `Pascal Bourgault `_. -- More support for unit aware arrays with pint (:pull:`3643`, :pull:`3975`, :pull:`4163`) - By `Justus Magin `_. -- Support overriding existing variables in ``to_zarr()`` with ``mode='a'`` even - without ``append_dim``, as long as dimension sizes do not change. - By `Stephan Hoyer `_. -- Allow plotting of boolean arrays. (:pull:`3766`) - By `Marek Jacob `_ -- Enable using MultiIndex levels as coordinates in 1D and 2D plots (:issue:`3927`). - By `Mathias Hauser `_. -- A ``days_in_month`` accessor for :py:class:`xarray.CFTimeIndex`, analogous to - the ``days_in_month`` accessor for a :py:class:`pandas.DatetimeIndex`, which - returns the days in the month each datetime in the index. Now days in month - weights for both standard and non-standard calendars can be obtained using - the :py:class:`~core.accessor_dt.DatetimeAccessor` (:pull:`3935`). This - feature requires cftime version 1.1.0 or greater. By - `Spencer Clark `_. -- For the netCDF3 backend, added dtype coercions for unsigned integer types. - (:issue:`4014`, :pull:`4018`) - By `Yunus Sevinchan `_ -- :py:meth:`map_blocks` now accepts a ``template`` kwarg. This allows use cases - where the result of a computation could not be inferred automatically. - By `Deepak Cherian `_ -- :py:meth:`map_blocks` can now handle dask-backed xarray objects in ``args``. (:pull:`3818`) - By `Deepak Cherian `_ -- Add keyword ``decode_timedelta`` to :py:func:`xarray.open_dataset`, - (:py:func:`xarray.open_dataarray`, :py:func:`xarray.open_dataarray`, - :py:func:`xarray.decode_cf`) that allows to disable/enable the decoding of timedeltas - independently of time decoding (:issue:`1621`) - `Aureliana Barghini `_ - -Enhancements -~~~~~~~~~~~~ -- Performance improvement of :py:meth:`DataArray.interp` and :py:func:`Dataset.interp` - We performs independant interpolation sequentially rather than interpolating in - one large multidimensional space. (:issue:`2223`) - By `Keisuke Fujii `_. -- :py:meth:`DataArray.interp` now support interpolations over chunked dimensions (:pull:`4155`). By `Alexandre Poux `_. -- Major performance improvement for :py:meth:`Dataset.from_dataframe` when the - dataframe has a MultiIndex (:pull:`4184`). - By `Stephan Hoyer `_. - - :py:meth:`DataArray.reset_index` and :py:meth:`Dataset.reset_index` now keep - coordinate attributes (:pull:`4103`). By `Oriol Abril `_. -- Axes kwargs such as ``facecolor`` can now be passed to :py:meth:`DataArray.plot` in ``subplot_kws``. - This works for both single axes plots and FacetGrid plots. - By `Raphael Dussin `_. -- Array items with long string reprs are now limited to a - reasonable width (:pull:`3900`) - By `Maximilian Roos `_ -- Large arrays whose numpy reprs would have greater than 40 lines are now - limited to a reasonable length. - (:pull:`3905`) - By `Maximilian Roos `_ - -Bug fixes -~~~~~~~~~ -- Fix errors combining attrs in :py:func:`open_mfdataset` (:issue:`4009`, :pull:`4173`) - By `John Omotani `_ -- If groupby receives a ``DataArray`` with name=None, assign a default name (:issue:`158`) - By `Phil Butcher `_. -- Support dark mode in VS code (:issue:`4024`) - By `Keisuke Fujii `_. -- Fix bug when converting multiindexed Pandas objects to sparse xarray objects. (:issue:`4019`) - By `Deepak Cherian `_. -- ``ValueError`` is raised when ``fill_value`` is not a scalar in :py:meth:`full_like`. (:issue:`3977`) - By `Huite Bootsma `_. -- Fix wrong order in converting a ``pd.Series`` with a MultiIndex to ``DataArray``. - (:issue:`3951`, :issue:`4186`) - By `Keisuke Fujii `_ and `Stephan Hoyer `_. -- Fix renaming of coords when one or more stacked coords is not in - sorted order during stack+groupby+apply operations. (:issue:`3287`, - :pull:`3906`) By `Spencer Hill `_ -- Fix a regression where deleting a coordinate from a copied :py:class:`DataArray` - can affect the original :py:class:`DataArray`. (:issue:`3899`, :pull:`3871`) - By `Todd Jennings `_ -- Fix :py:class:`~xarray.plot.FacetGrid` plots with a single contour. (:issue:`3569`, :pull:`3915`). - By `Deepak Cherian `_ -- Use divergent colormap if ``levels`` spans 0. (:issue:`3524`) - By `Deepak Cherian `_ -- Fix :py:class:`~xarray.plot.FacetGrid` when ``vmin == vmax``. (:issue:`3734`) - By `Deepak Cherian `_ -- Fix plotting when ``levels`` is a scalar and ``norm`` is provided. (:issue:`3735`) - By `Deepak Cherian `_ -- Fix bug where plotting line plots with 2D coordinates depended on dimension - order. (:issue:`3933`) - By `Tom Nicholas `_. -- Fix ``RasterioDeprecationWarning`` when using a ``vrt`` in ``open_rasterio``. (:issue:`3964`) - By `Taher Chegini `_. -- Fix ``AttributeError`` on displaying a :py:class:`Variable` - in a notebook context. (:issue:`3972`, :pull:`3973`) - By `Ian Castleden `_. -- Fix bug causing :py:meth:`DataArray.interpolate_na` to always drop attributes, - and added `keep_attrs` argument. (:issue:`3968`) - By `Tom Nicholas `_. -- Fix bug in time parsing failing to fall back to cftime. This was causing time - variables with a time unit of `'msecs'` to fail to parse. (:pull:`3998`) - By `Ryan May `_. -- Fix weighted mean when passing boolean weights (:issue:`4074`). - By `Mathias Hauser `_. -- Fix html repr in untrusted notebooks: fallback to plain text repr. (:pull:`4053`) - By `Benoit Bovy `_. -- Fix :py:meth:`DataArray.to_unstacked_dataset` for single-dimension variables. (:issue:`4049`) - By `Deepak Cherian `_ -- Fix :py:func:`open_rasterio` for ``WarpedVRT`` with specified ``src_crs``. (:pull:`4104`) - By `Dave Cole `_. - -Documentation -~~~~~~~~~~~~~ -- update the docstring of :py:meth:`DataArray.assign_coords` : clarify how to - add a new coordinate to an existing dimension and illustrative example - (:issue:`3952`, :pull:`3958`) By - `Etienne Combrisson `_. -- update the docstring of :py:meth:`Dataset.diff` and - :py:meth:`DataArray.diff` so it does document the ``dim`` - parameter as required. (:issue:`1040`, :pull:`3909`) - By `Justus Magin `_. -- Updated :doc:`Calculating Seasonal Averages from Timeseries of Monthly Means - ` example notebook to take advantage of the new - ``days_in_month`` accessor for :py:class:`xarray.CFTimeIndex` - (:pull:`3935`). By `Spencer Clark `_. -- Updated the list of current core developers. (:issue:`3892`) - By `Tom Nicholas `_. -- Add example for multi-dimensional extrapolation and note different behavior - of ``kwargs`` in :py:meth:`Dataset.interp` and :py:meth:`DataArray.interp` - for 1-d and n-d interpolation (:pull:`3956`). - By `Matthias Riße `_. -- Apply ``black`` to all the code in the documentation (:pull:`4012`) - By `Justus Magin `_. -- Narrative documentation now describes :py:meth:`map_blocks`: :ref:`dask.automatic-parallelization`. - By `Deepak Cherian `_. -- Document ``.plot``, ``.dt``, ``.str`` accessors the way they are called. (:issue:`3625`, :pull:`3988`) - By `Justus Magin `_. -- Add documentation for the parameters and return values of :py:meth:`DataArray.sel`. - By `Justus Magin `_. - -Internal Changes -~~~~~~~~~~~~~~~~ -- Raise more informative error messages for chunk size conflicts when writing to zarr files. - By `Deepak Cherian `_. -- Run the ``isort`` pre-commit hook only on python source files - and update the ``flake8`` version. (:issue:`3750`, :pull:`3711`) - By `Justus Magin `_. -- Add `blackdoc `_ to the list of - checkers for development. (:pull:`4177`) - By `Justus Magin `_. -- Add a CI job that runs the tests with every optional dependency - except ``dask``. (:issue:`3794`, :pull:`3919`) - By `Justus Magin `_. -- Use ``async`` / ``await`` for the asynchronous distributed - tests. (:issue:`3987`, :pull:`3989`) - By `Justus Magin `_. -- Various internal code clean-ups (:pull:`4026`, :pull:`4038`). - By `Prajjwal Nijhara `_. - -.. _whats-new.0.15.1: - -v0.15.1 (23 Mar 2020) ---------------------- - -This release brings many new features such as :py:meth:`Dataset.weighted` methods for weighted array -reductions, a new jupyter repr by default, and the start of units integration with pint. There's also -the usual batch of usability improvements, documentation additions, and bug fixes. - -Breaking changes -~~~~~~~~~~~~~~~~ - -- Raise an error when assigning to the ``.values`` or ``.data`` attribute of - dimension coordinates i.e. ``IndexVariable`` objects. This has been broken since - v0.12.0. Please use :py:meth:`DataArray.assign_coords` or :py:meth:`Dataset.assign_coords` - instead. (:issue:`3470`, :pull:`3862`) - By `Deepak Cherian `_ - -New Features -~~~~~~~~~~~~ - -- Weighted array reductions are now supported via the new :py:meth:`DataArray.weighted` - and :py:meth:`Dataset.weighted` methods. See :ref:`comput.weighted`. (:issue:`422`, :pull:`2922`). - By `Mathias Hauser `_. -- The new jupyter notebook repr (``Dataset._repr_html_`` and - ``DataArray._repr_html_``) (introduced in 0.14.1) is now on by default. To - disable, use ``xarray.set_options(display_style="text")``. - By `Julia Signell `_. -- Added support for :py:class:`pandas.DatetimeIndex`-style rounding of - ``cftime.datetime`` objects directly via a :py:class:`CFTimeIndex` or via the - :py:class:`~core.accessor_dt.DatetimeAccessor`. - By `Spencer Clark `_ -- Support new h5netcdf backend keyword `phony_dims` (available from h5netcdf - v0.8.0 for :py:class:`~xarray.backends.H5NetCDFStore`. - By `Kai Mühlbauer `_. -- Add partial support for unit aware arrays with pint. (:pull:`3706`, :pull:`3611`) - By `Justus Magin `_. -- :py:meth:`Dataset.groupby` and :py:meth:`DataArray.groupby` now raise a - `TypeError` on multiple string arguments. Receiving multiple string arguments - often means a user is attempting to pass multiple dimensions as separate - arguments and should instead pass a single list of dimensions. - (:pull:`3802`) - By `Maximilian Roos `_ -- :py:func:`map_blocks` can now apply functions that add new unindexed dimensions. - By `Deepak Cherian `_ -- An ellipsis (``...``) is now supported in the ``dims`` argument of - :py:meth:`Dataset.stack` and :py:meth:`DataArray.stack`, meaning all - unlisted dimensions, similar to its meaning in :py:meth:`DataArray.transpose`. - (:pull:`3826`) - By `Maximilian Roos `_ -- :py:meth:`Dataset.where` and :py:meth:`DataArray.where` accept a lambda as a - first argument, which is then called on the input; replicating pandas' behavior. - By `Maximilian Roos `_. -- ``skipna`` is available in :py:meth:`Dataset.quantile`, :py:meth:`DataArray.quantile`, - :py:meth:`core.groupby.DatasetGroupBy.quantile`, :py:meth:`core.groupby.DataArrayGroupBy.quantile` - (:issue:`3843`, :pull:`3844`) - By `Aaron Spring `_. -- Add a diff summary for `testing.assert_allclose`. (:issue:`3617`, :pull:`3847`) - By `Justus Magin `_. - -Bug fixes -~~~~~~~~~ - -- Fix :py:meth:`Dataset.interp` when indexing array shares coordinates with the - indexed variable (:issue:`3252`). - By `David Huard `_. -- Fix recombination of groups in :py:meth:`Dataset.groupby` and - :py:meth:`DataArray.groupby` when performing an operation that changes the - size of the groups along the grouped dimension. By `Eric Jansen - `_. -- Fix use of multi-index with categorical values (:issue:`3674`). - By `Matthieu Ancellin `_. -- Fix alignment with ``join="override"`` when some dimensions are unindexed. (:issue:`3681`). - By `Deepak Cherian `_. -- Fix :py:meth:`Dataset.swap_dims` and :py:meth:`DataArray.swap_dims` producing - index with name reflecting the previous dimension name instead of the new one - (:issue:`3748`, :pull:`3752`). By `Joseph K Aicher - `_. -- Use ``dask_array_type`` instead of ``dask_array.Array`` for type - checking. (:issue:`3779`, :pull:`3787`) - By `Justus Magin `_. -- :py:func:`concat` can now handle coordinate variables only present in one of - the objects to be concatenated when ``coords="different"``. - By `Deepak Cherian `_. -- xarray now respects the over, under and bad colors if set on a provided colormap. - (:issue:`3590`, :pull:`3601`) - By `johnomotani `_. -- ``coarsen`` and ``rolling`` now respect ``xr.set_options(keep_attrs=True)`` - to preserve attributes. :py:meth:`Dataset.coarsen` accepts a keyword - argument ``keep_attrs`` to change this setting. (:issue:`3376`, - :pull:`3801`) By `Andrew Thomas `_. -- Delete associated indexes when deleting coordinate variables. (:issue:`3746`). - By `Deepak Cherian `_. -- Fix :py:meth:`Dataset.to_zarr` when using ``append_dim`` and ``group`` - simultaneously. (:issue:`3170`). By `Matthias Meyer `_. -- Fix html repr on :py:class:`Dataset` with non-string keys (:pull:`3807`). - By `Maximilian Roos `_. - -Documentation -~~~~~~~~~~~~~ - -- Fix documentation of :py:class:`DataArray` removing the deprecated mention - that when omitted, `dims` are inferred from a `coords`-dict. (:pull:`3821`) - By `Sander van Rijn `_. -- Improve the :py:func:`where` docstring. - By `Maximilian Roos `_ -- Update the installation instructions: only explicitly list recommended dependencies - (:issue:`3756`). - By `Mathias Hauser `_. - -Internal Changes -~~~~~~~~~~~~~~~~ - -- Remove the internal ``import_seaborn`` function which handled the deprecation of - the ``seaborn.apionly`` entry point (:issue:`3747`). - By `Mathias Hauser `_. -- Don't test pint integration in combination with datetime objects. (:issue:`3778`, :pull:`3788`) - By `Justus Magin `_. -- Change test_open_mfdataset_list_attr to only run with dask installed - (:issue:`3777`, :pull:`3780`). - By `Bruno Pagani `_. -- Preserve the ability to index with ``method="nearest"`` with a - :py:class:`CFTimeIndex` with pandas versions greater than 1.0.1 - (:issue:`3751`). By `Spencer Clark `_. -- Greater flexibility and improved test coverage of subtracting various types - of objects from a :py:class:`CFTimeIndex`. By `Spencer Clark - `_. -- Update Azure CI MacOS image, given pending removal. - By `Maximilian Roos `_ -- Remove xfails for scipy 1.0.1 for tests that append to netCDF files (:pull:`3805`). - By `Mathias Hauser `_. -- Remove conversion to ``pandas.Panel``, given its removal in pandas - in favor of xarray's objects. - By `Maximilian Roos `_ - -.. _whats-new.0.15.0: - - -v0.15.0 (30 Jan 2020) ---------------------- - -This release brings many improvements to xarray's documentation: our examples are now binderized notebooks (`click here `_) -and we have new example notebooks from our SciPy 2019 sprint (many thanks to our contributors!). - -This release also features many API improvements such as a new -:py:class:`~core.accessor_dt.TimedeltaAccessor` and support for :py:class:`CFTimeIndex` in -:py:meth:`~DataArray.interpolate_na`); as well as many bug fixes. - -Breaking changes -~~~~~~~~~~~~~~~~ -- Bumped minimum tested versions for dependencies: - - - numpy 1.15 - - pandas 0.25 - - dask 2.2 - - distributed 2.2 - - scipy 1.3 - -- Remove ``compat`` and ``encoding`` kwargs from ``DataArray``, which - have been deprecated since 0.12. (:pull:`3650`). - Instead, specify the ``encoding`` kwarg when writing to disk or set - the :py:attr:`DataArray.encoding` attribute directly. - By `Maximilian Roos `_. -- :py:func:`xarray.dot`, :py:meth:`DataArray.dot`, and the ``@`` operator now - use ``align="inner"`` (except when ``xarray.set_options(arithmetic_join="exact")``; - :issue:`3694`) by `Mathias Hauser `_. - -New Features -~~~~~~~~~~~~ -- Implement :py:meth:`DataArray.pad` and :py:meth:`Dataset.pad`. (:issue:`2605`, :pull:`3596`). - By `Mark Boer `_. -- :py:meth:`DataArray.sel` and :py:meth:`Dataset.sel` now support :py:class:`pandas.CategoricalIndex`. (:issue:`3669`) - By `Keisuke Fujii `_. -- Support using an existing, opened h5netcdf ``File`` with - :py:class:`~xarray.backends.H5NetCDFStore`. This permits creating an - :py:class:`~xarray.Dataset` from a h5netcdf ``File`` that has been opened - using other means (:issue:`3618`). - By `Kai Mühlbauer `_. -- Implement ``median`` and ``nanmedian`` for dask arrays. This works by rechunking - to a single chunk along all reduction axes. (:issue:`2999`). - By `Deepak Cherian `_. -- :py:func:`~xarray.concat` now preserves attributes from the first Variable. - (:issue:`2575`, :issue:`2060`, :issue:`1614`) - By `Deepak Cherian `_. -- :py:meth:`Dataset.quantile`, :py:meth:`DataArray.quantile` and ``GroupBy.quantile`` - now work with dask Variables. - By `Deepak Cherian `_. -- Added the ``count`` reduction method to both :py:class:`~core.rolling.DatasetCoarsen` - and :py:class:`~core.rolling.DataArrayCoarsen` objects. (:pull:`3500`) - By `Deepak Cherian `_ -- Add ``meta`` kwarg to :py:func:`~xarray.apply_ufunc`; - this is passed on to :py:func:`dask.array.blockwise`. (:pull:`3660`) - By `Deepak Cherian `_. -- Add ``attrs_file`` option in :py:func:`~xarray.open_mfdataset` to choose the - source file for global attributes in a multi-file dataset (:issue:`2382`, - :pull:`3498`). By `Julien Seguinot `_. -- :py:meth:`Dataset.swap_dims` and :py:meth:`DataArray.swap_dims` - now allow swapping to dimension names that don't exist yet. (:pull:`3636`) - By `Justus Magin `_. -- Extend :py:class:`~core.accessor_dt.DatetimeAccessor` properties - and support ``.dt`` accessor for timedeltas - via :py:class:`~core.accessor_dt.TimedeltaAccessor` (:pull:`3612`) - By `Anderson Banihirwe `_. -- Improvements to interpolating along time axes (:issue:`3641`, :pull:`3631`). - By `David Huard `_. - - - Support :py:class:`CFTimeIndex` in :py:meth:`DataArray.interpolate_na` - - define 1970-01-01 as the default offset for the interpolation index for both - :py:class:`pandas.DatetimeIndex` and :py:class:`CFTimeIndex`, - - use microseconds in the conversion from timedelta objects to floats to avoid - overflow errors. - -Bug fixes -~~~~~~~~~ -- Applying a user-defined function that adds new dimensions using :py:func:`apply_ufunc` - and ``vectorize=True`` now works with ``dask > 2.0``. (:issue:`3574`, :pull:`3660`). - By `Deepak Cherian `_. -- Fix :py:meth:`~xarray.combine_by_coords` to allow for combining incomplete - hypercubes of Datasets (:issue:`3648`). By `Ian Bolliger - `_. -- Fix :py:func:`~xarray.combine_by_coords` when combining cftime coordinates - which span long time intervals (:issue:`3535`). By `Spencer Clark - `_. -- Fix plotting with transposed 2D non-dimensional coordinates. (:issue:`3138`, :pull:`3441`) - By `Deepak Cherian `_. -- :py:meth:`plot.FacetGrid.set_titles` can now replace existing row titles of a - :py:class:`~xarray.plot.FacetGrid` plot. In addition :py:class:`~xarray.plot.FacetGrid` gained - two new attributes: :py:attr:`~xarray.plot.FacetGrid.col_labels` and - :py:attr:`~xarray.plot.FacetGrid.row_labels` contain :py:class:`matplotlib.text.Text` handles for both column and - row labels. These can be used to manually change the labels. - By `Deepak Cherian `_. -- Fix issue with Dask-backed datasets raising a ``KeyError`` on some computations involving :py:func:`map_blocks` (:pull:`3598`). - By `Tom Augspurger `_. -- Ensure :py:meth:`Dataset.quantile`, :py:meth:`DataArray.quantile` issue the correct error - when ``q`` is out of bounds (:issue:`3634`) by `Mathias Hauser `_. -- Fix regression in xarray 0.14.1 that prevented encoding times with certain - ``dtype``, ``_FillValue``, and ``missing_value`` encodings (:issue:`3624`). - By `Spencer Clark `_ -- Raise an error when trying to use :py:meth:`Dataset.rename_dims` to - rename to an existing name (:issue:`3438`, :pull:`3645`) - By `Justus Magin `_. -- :py:meth:`Dataset.rename`, :py:meth:`DataArray.rename` now check for conflicts with - MultiIndex level names. -- :py:meth:`Dataset.merge` no longer fails when passed a :py:class:`DataArray` instead of a :py:class:`Dataset`. - By `Tom Nicholas `_. -- Fix a regression in :py:meth:`Dataset.drop`: allow passing any - iterable when dropping variables (:issue:`3552`, :pull:`3693`) - By `Justus Magin `_. -- Fixed errors emitted by ``mypy --strict`` in modules that import xarray. - (:issue:`3695`) by `Guido Imperiale `_. -- Allow plotting of binned coordinates on the y axis in :py:meth:`plot.line` - and :py:meth:`plot.step` plots (:issue:`3571`, - :pull:`3685`) by `Julien Seguinot `_. -- setuptools is now marked as a dependency of xarray - (:pull:`3628`) by `Richard Höchenberger `_. - -Documentation -~~~~~~~~~~~~~ -- Switch doc examples to use `nbsphinx `_ and replace - ``sphinx_gallery`` scripts with Jupyter notebooks. (:pull:`3105`, :pull:`3106`, :pull:`3121`) - By `Ryan Abernathey `_. -- Added :doc:`example notebook ` demonstrating use of xarray with - Regional Ocean Modeling System (ROMS) ocean hydrodynamic model output. (:pull:`3116`) - By `Robert Hetland `_. -- Added :doc:`example notebook ` demonstrating the visualization of - ERA5 GRIB data. (:pull:`3199`) - By `Zach Bruick `_ and - `Stephan Siemen `_. -- Added examples for :py:meth:`DataArray.quantile`, :py:meth:`Dataset.quantile` and - ``GroupBy.quantile``. (:pull:`3576`) - By `Justus Magin `_. -- Add new :doc:`example notebook ` example notebook demonstrating - vectorization of a 1D function using :py:func:`apply_ufunc` , dask and numba. - By `Deepak Cherian `_. -- Added example for :py:func:`~xarray.map_blocks`. (:pull:`3667`) - By `Riley X. Brady `_. - -Internal Changes -~~~~~~~~~~~~~~~~ -- Make sure dask names change when rechunking by different chunk sizes. Conversely, make sure they - stay the same when rechunking by the same chunk size. (:issue:`3350`) - By `Deepak Cherian `_. -- 2x to 5x speed boost (on small arrays) for :py:meth:`Dataset.isel`, - :py:meth:`DataArray.isel`, and :py:meth:`DataArray.__getitem__` when indexing by int, - slice, list of int, scalar ndarray, or 1-dimensional ndarray. - (:pull:`3533`) by `Guido Imperiale `_. -- Removed internal method ``Dataset._from_vars_and_coord_names``, - which was dominated by ``Dataset._construct_direct``. (:pull:`3565`) - By `Maximilian Roos `_. -- Replaced versioneer with setuptools-scm. Moved contents of setup.py to setup.cfg. - Removed pytest-runner from setup.py, as per deprecation notice on the pytest-runner - project. (:pull:`3714`) by `Guido Imperiale `_. -- Use of isort is now enforced by CI. - (:pull:`3721`) by `Guido Imperiale `_ - - -.. _whats-new.0.14.1: - -v0.14.1 (19 Nov 2019) ---------------------- - -Breaking changes -~~~~~~~~~~~~~~~~ - -- Broken compatibility with ``cftime < 1.0.3`` . By `Deepak Cherian `_. - - .. warning:: - - cftime version 1.0.4 is broken - (`cftime/126 `_); - please use version 1.0.4.2 instead. - -- All leftover support for dates from non-standard calendars through ``netcdftime``, the - module included in versions of netCDF4 prior to 1.4 that eventually became the - `cftime `_ package, has been removed in favor of relying solely on - the standalone ``cftime`` package (:pull:`3450`). - By `Spencer Clark `_. - -New Features -~~~~~~~~~~~~ -- Added the ``sparse`` option to :py:meth:`~xarray.DataArray.unstack`, - :py:meth:`~xarray.Dataset.unstack`, :py:meth:`~xarray.DataArray.reindex`, - :py:meth:`~xarray.Dataset.reindex` (:issue:`3518`). - By `Keisuke Fujii `_. -- Added the ``fill_value`` option to :py:meth:`DataArray.unstack` and - :py:meth:`Dataset.unstack` (:issue:`3518`, :pull:`3541`). - By `Keisuke Fujii `_. -- Added the ``max_gap`` kwarg to :py:meth:`~xarray.DataArray.interpolate_na` and - :py:meth:`~xarray.Dataset.interpolate_na`. This controls the maximum size of the data - gap that will be filled by interpolation. By `Deepak Cherian `_. -- Added :py:meth:`Dataset.drop_sel` & :py:meth:`DataArray.drop_sel` for dropping labels. - :py:meth:`Dataset.drop_vars` & :py:meth:`DataArray.drop_vars` have been added for - dropping variables (including coordinates). The existing :py:meth:`Dataset.drop` & - :py:meth:`DataArray.drop` methods remain as a backward compatible - option for dropping either labels or variables, but using the more specific methods is encouraged. - (:pull:`3475`) - By `Maximilian Roos `_ -- Added :py:meth:`Dataset.map` & ``GroupBy.map`` & ``Resample.map`` for - mapping / applying a function over each item in the collection, reflecting the widely used - and least surprising name for this operation. - The existing ``apply`` methods remain for backward compatibility, though using the ``map`` - methods is encouraged. - (:pull:`3459`) - By `Maximilian Roos `_ -- :py:meth:`Dataset.transpose` and :py:meth:`DataArray.transpose` now support an ellipsis (``...``) - to represent all 'other' dimensions. For example, to move one dimension to the front, - use ``.transpose('x', ...)``. (:pull:`3421`) - By `Maximilian Roos `_ -- Changed ``xr.ALL_DIMS`` to equal python's ``Ellipsis`` (``...``), and changed internal usages to use - ``...`` directly. As before, you can use this to instruct a ``groupby`` operation - to reduce over all dimensions. While we have no plans to remove ``xr.ALL_DIMS``, we suggest - using ``...``. (:pull:`3418`) - By `Maximilian Roos `_ -- :py:func:`xarray.dot`, and :py:meth:`DataArray.dot` now support the - ``dims=...`` option to sum over the union of dimensions of all input arrays - (:issue:`3423`) by `Mathias Hauser `_. -- Added new ``Dataset._repr_html_`` and ``DataArray._repr_html_`` to improve - representation of objects in Jupyter. By default this feature is turned off - for now. Enable it with ``xarray.set_options(display_style="html")``. - (:pull:`3425`) by `Benoit Bovy `_ and - `Julia Signell `_. -- Implement `dask deterministic hashing - `_ - for xarray objects. Note that xarray objects with a dask.array backend already used - deterministic hashing in previous releases; this change implements it when whole - xarray objects are embedded in a dask graph, e.g. when :py:meth:`DataArray.map_blocks` is - invoked. (:issue:`3378`, :pull:`3446`, :pull:`3515`) - By `Deepak Cherian `_ and - `Guido Imperiale `_. -- Add the documented-but-missing :py:meth:`~core.groupby.DatasetGroupBy.quantile`. -- xarray now respects the ``DataArray.encoding["coordinates"]`` attribute when writing to disk. - See :ref:`io.coordinates` for more. (:issue:`3351`, :pull:`3487`) - By `Deepak Cherian `_. -- Add the documented-but-missing :py:meth:`~core.groupby.DatasetGroupBy.quantile`. - (:issue:`3525`, :pull:`3527`). By `Justus Magin `_. - -Bug fixes -~~~~~~~~~ -- Ensure an index of type ``CFTimeIndex`` is not converted to a ``DatetimeIndex`` when - calling :py:meth:`Dataset.rename`, :py:meth:`Dataset.rename_dims` and :py:meth:`Dataset.rename_vars`. - By `Mathias Hauser `_. (:issue:`3522`). -- Fix a bug in :py:meth:`DataArray.set_index` in case that an existing dimension becomes a level - variable of MultiIndex. (:pull:`3520`). By `Keisuke Fujii `_. -- Harmonize ``_FillValue``, ``missing_value`` during encoding and decoding steps. (:pull:`3502`) - By `Anderson Banihirwe `_. -- Fix regression introduced in v0.14.0 that would cause a crash if dask is installed - but cloudpickle isn't (:issue:`3401`) by `Rhys Doyle `_ -- Fix grouping over variables with NaNs. (:issue:`2383`, :pull:`3406`). - By `Deepak Cherian `_. -- Make alignment and concatenation significantly more efficient by using dask names to compare dask - objects prior to comparing values after computation. This change makes it more convenient to carry - around large non-dimensional coordinate variables backed by dask arrays. Existing workarounds involving - ``reset_coords(drop=True)`` should now be unnecessary in most cases. - (:issue:`3068`, :issue:`3311`, :issue:`3454`, :pull:`3453`). - By `Deepak Cherian `_. -- Add support for cftime>=1.0.4. By `Anderson Banihirwe `_. -- Rolling reduction operations no longer compute dask arrays by default. (:issue:`3161`). - In addition, the ``allow_lazy`` kwarg to ``reduce`` is deprecated. - By `Deepak Cherian `_. -- Fix ``GroupBy.reduce`` when reducing over multiple dimensions. - (:issue:`3402`). By `Deepak Cherian `_ -- Allow appending datetime and bool data variables to zarr stores. - (:issue:`3480`). By `Akihiro Matsukawa `_. -- Add support for numpy >=1.18 (); bugfix mean() on datetime64 arrays on dask backend - (:issue:`3409`, :pull:`3537`). By `Guido Imperiale `_. -- Add support for pandas >=0.26 (:issue:`3440`). - By `Deepak Cherian `_. -- Add support for pseudonetcdf >=3.1 (:pull:`3485`). - By `Barron Henderson `_. - -Documentation -~~~~~~~~~~~~~ -- Fix leap year condition in `monthly means example `_. - By `Mickaël Lalande `_. -- Fix the documentation of :py:meth:`DataArray.resample` and - :py:meth:`Dataset.resample`, explicitly stating that a - datetime-like dimension is required. (:pull:`3400`) - By `Justus Magin `_. -- Update the :ref:`terminology` page to address multidimensional coordinates. (:pull:`3410`) - By `Jon Thielen `_. -- Fix the documentation of :py:meth:`Dataset.integrate` and - :py:meth:`DataArray.integrate` and add an example to - :py:meth:`Dataset.integrate`. (:pull:`3469`) - By `Justus Magin `_. - -Internal Changes -~~~~~~~~~~~~~~~~ - -- Added integration tests against `pint `_. - (:pull:`3238`, :pull:`3447`, :pull:`3493`, :pull:`3508`) - by `Justus Magin `_. - - .. note:: - - At the moment of writing, these tests *as well as the ability to use pint in general* - require `a highly experimental version of pint - `_ (install with - ``pip install git+https://github.com/andrewgsavage/pint.git@refs/pull/6/head)``. - Even with it, interaction with non-numpy array libraries, e.g. dask or sparse, is broken. - -- Use Python 3.6 idioms throughout the codebase. (:pull:`3419`) - By `Maximilian Roos `_ - -- Run basic CI tests on Python 3.8. (:pull:`3477`) - By `Maximilian Roos `_ - -- Enable type checking on default sentinel values (:pull:`3472`) - By `Maximilian Roos `_ - -- Add ``Variable._replace`` for simpler replacing of a subset of attributes (:pull:`3472`) - By `Maximilian Roos `_ - -.. _whats-new.0.14.0: - -v0.14.0 (14 Oct 2019) ---------------------- - -Breaking changes -~~~~~~~~~~~~~~~~ -- This release introduces a rolling policy for minimum dependency versions: - :ref:`mindeps_policy`. - - Several minimum versions have been increased: - - ============ ================== ==== - Package Old New - ============ ================== ==== - Python 3.5.3 3.6 - numpy 1.12 1.14 - pandas 0.19.2 0.24 - dask 0.16 (tested: 2.4) 1.2 - bottleneck 1.1 (tested: 1.2) 1.2 - matplotlib 1.5 (tested: 3.1) 3.1 - ============ ================== ==== - - Obsolete patch versions (x.y.Z) are not tested anymore. - The oldest supported versions of all optional dependencies are now covered by - automated tests (before, only the very latest versions were tested). - - (:issue:`3222`, :issue:`3293`, :issue:`3340`, :issue:`3346`, :issue:`3358`). - By `Guido Imperiale `_. - -- Dropped the ``drop=False`` optional parameter from :py:meth:`Variable.isel`. - It was unused and doesn't make sense for a Variable. (:pull:`3375`). - By `Guido Imperiale `_. - -- Remove internal usage of :py:class:`collections.OrderedDict`. After dropping support for - Python <=3.5, most uses of ``OrderedDict`` in Xarray were no longer necessary. We - have removed the internal use of the ``OrderedDict`` in favor of Python's builtin - ``dict`` object which is now ordered itself. This change will be most obvious when - interacting with the ``attrs`` property on Dataset and DataArray objects. - (:issue:`3380`, :pull:`3389`). By `Joe Hamman `_. - -New functions/methods -~~~~~~~~~~~~~~~~~~~~~ - -- Added :py:func:`~xarray.map_blocks`, modeled after :py:func:`dask.array.map_blocks`. - Also added :py:meth:`Dataset.unify_chunks`, :py:meth:`DataArray.unify_chunks` and - :py:meth:`testing.assert_chunks_equal`. (:pull:`3276`). - By `Deepak Cherian `_ and - `Guido Imperiale `_. - -Enhancements -~~~~~~~~~~~~ - -- ``core.groupby.GroupBy`` enhancements. By `Deepak Cherian `_. - - - Added a repr (:pull:`3344`). Example:: - - >>> da.groupby("time.season") - DataArrayGroupBy, grouped over 'season' - 4 groups with labels 'DJF', 'JJA', 'MAM', 'SON' - - - Added a ``GroupBy.dims`` property that mirrors the dimensions - of each group (:issue:`3344`). - -- Speed up :py:meth:`Dataset.isel` up to 33% and :py:meth:`DataArray.isel` up to 25% for small - arrays (:issue:`2799`, :pull:`3375`). By - `Guido Imperiale `_. - -Bug fixes -~~~~~~~~~ -- Reintroduce support for :mod:`weakref` (broken in v0.13.0). Support has been - reinstated for :py:class:`~xarray.DataArray` and :py:class:`~xarray.Dataset` objects only. - Internal xarray objects remain unaddressable by weakref in order to save memory - (:issue:`3317`). By `Guido Imperiale `_. -- Line plots with the ``x`` or ``y`` argument set to a 1D non-dimensional coord - now plot the correct data for 2D DataArrays - (:issue:`3334`). By `Tom Nicholas `_. -- Make :py:func:`~xarray.concat` more robust when merging variables present in some datasets but - not others (:issue:`508`). By `Deepak Cherian `_. -- The default behaviour of reducing across all dimensions for - :py:class:`~xarray.core.groupby.DataArrayGroupBy` objects has now been properly removed - as was done for :py:class:`~xarray.core.groupby.DatasetGroupBy` in 0.13.0 (:issue:`3337`). - Use ``xarray.ALL_DIMS`` if you need to replicate previous behaviour. - Also raise nicer error message when no groups are created (:issue:`1764`). - By `Deepak Cherian `_. -- Fix error in concatenating unlabeled dimensions (:pull:`3362`). - By `Deepak Cherian `_. -- Warn if the ``dim`` kwarg is passed to rolling operations. This is redundant since a dimension is - specified when the :py:class:`~core.rolling.DatasetRolling` or :py:class:`~core.rolling.DataArrayRolling` object is created. - (:pull:`3362`). By `Deepak Cherian `_. - -Documentation -~~~~~~~~~~~~~ - -- Created a glossary of important xarray terms (:issue:`2410`, :pull:`3352`). - By `Gregory Gundersen `_. -- Created a "How do I..." section (:ref:`howdoi`) for solutions to common questions. (:pull:`3357`). - By `Deepak Cherian `_. -- Add examples for :py:meth:`Dataset.swap_dims` and :py:meth:`DataArray.swap_dims` - (pull:`3331`, pull:`3331`). By `Justus Magin `_. -- Add examples for :py:meth:`align`, :py:meth:`merge`, :py:meth:`combine_by_coords`, - :py:meth:`full_like`, :py:meth:`zeros_like`, :py:meth:`ones_like`, :py:meth:`Dataset.pipe`, - :py:meth:`Dataset.assign`, :py:meth:`Dataset.reindex`, :py:meth:`Dataset.fillna` (:pull:`3328`). - By `Anderson Banihirwe `_. -- Fixed documentation to clean up an unwanted file created in ``ipython`` example - (:pull:`3353`). By `Gregory Gundersen `_. - -.. _whats-new.0.13.0: - -v0.13.0 (17 Sep 2019) ---------------------- - -This release includes many exciting changes: wrapping of -`NEP18 `_ compliant -numpy-like arrays; new :py:meth:`~Dataset.plot.scatter` plotting method that can scatter -two ``DataArrays`` in a ``Dataset`` against each other; support for converting pandas -DataFrames to xarray objects that wrap ``pydata/sparse``; and more! - -Breaking changes -~~~~~~~~~~~~~~~~ - -- This release increases the minimum required Python version from 3.5.0 to 3.5.3 - (:issue:`3089`). By `Guido Imperiale `_. -- The ``isel_points`` and ``sel_points`` methods are removed, having been deprecated - since v0.10.0. These are redundant with the ``isel`` / ``sel`` methods. - See :ref:`vectorized_indexing` for the details - By `Maximilian Roos `_ -- The ``inplace`` kwarg for public methods now raises an error, having been deprecated - since v0.11.0. - By `Maximilian Roos `_ -- :py:func:`~xarray.concat` now requires the ``dim`` argument. Its ``indexers``, ``mode`` - and ``concat_over`` kwargs have now been removed. - By `Deepak Cherian `_ -- Passing a list of colors in ``cmap`` will now raise an error, having been deprecated since - v0.6.1. -- Most xarray objects now define ``__slots__``. This reduces overall RAM usage by ~22% - (not counting the underlying numpy buffers); on CPython 3.7/x64, a trivial DataArray - has gone down from 1.9kB to 1.5kB. - - Caveats: - - - Pickle streams produced by older versions of xarray can't be loaded using this - release, and vice versa. - - Any user code that was accessing the ``__dict__`` attribute of - xarray objects will break. The best practice to attach custom metadata to xarray - objects is to use the ``attrs`` dictionary. - - Any user code that defines custom subclasses of xarray classes must now explicitly - define ``__slots__`` itself. Subclasses that don't add any attributes must state so - by defining ``__slots__ = ()`` right after the class header. - Omitting ``__slots__`` will now cause a ``FutureWarning`` to be logged, and will raise an - error in a later release. - - (:issue:`3250`) by `Guido Imperiale `_. -- The default dimension for :py:meth:`Dataset.groupby`, :py:meth:`Dataset.resample`, - :py:meth:`DataArray.groupby` and :py:meth:`DataArray.resample` reductions is now the - grouping or resampling dimension. -- :py:meth:`DataArray.to_dataset` requires ``name`` to be passed as a kwarg (previously ambiguous - positional arguments were deprecated) -- Reindexing with variables of a different dimension now raise an error (previously deprecated) -- ``xarray.broadcast_array`` is removed (previously deprecated in favor of - :py:func:`~xarray.broadcast`) -- ``Variable.expand_dims`` is removed (previously deprecated in favor of - :py:meth:`Variable.set_dims`) - -New functions/methods -~~~~~~~~~~~~~~~~~~~~~ - -- xarray can now wrap around any - `NEP18 `_ compliant - numpy-like library (important: read notes about ``NUMPY_EXPERIMENTAL_ARRAY_FUNCTION`` in - the above link). Added explicit test coverage for - `sparse `_. (:issue:`3117`, :issue:`3202`). - This requires `sparse>=0.8.0`. By `Nezar Abdennur `_ - and `Guido Imperiale `_. - -- :py:meth:`~Dataset.from_dataframe` and :py:meth:`~DataArray.from_series` now - support ``sparse=True`` for converting pandas objects into xarray objects - wrapping sparse arrays. This is particularly useful with sparsely populated - hierarchical indexes. (:issue:`3206`) - By `Stephan Hoyer `_. - -- The xarray package is now discoverable by mypy (although typing hints coverage is not - complete yet). mypy type checking is now enforced by CI. Libraries that depend on - xarray and use mypy can now remove from their setup.cfg the lines:: - - [mypy-xarray] - ignore_missing_imports = True - - (:issue:`2877`, :issue:`3088`, :issue:`3090`, :issue:`3112`, :issue:`3117`, - :issue:`3207`) - By `Guido Imperiale `_ - and `Maximilian Roos `_. - -- Added :py:meth:`DataArray.broadcast_like` and :py:meth:`Dataset.broadcast_like`. - By `Deepak Cherian `_ and `David Mertz - `_. - -- Dataset plotting API for visualizing dependencies between two DataArrays! - Currently only :py:meth:`Dataset.plot.scatter` is implemented. - By `Yohai Bar Sinai `_ and `Deepak Cherian `_ - -- Added :py:meth:`DataArray.head`, :py:meth:`DataArray.tail` and :py:meth:`DataArray.thin`; - as well as :py:meth:`Dataset.head`, :py:meth:`Dataset.tail` and :py:meth:`Dataset.thin` methods. - (:issue:`319`) By `Gerardo Rivera `_. - -Enhancements -~~~~~~~~~~~~ - -- Multiple enhancements to :py:func:`~xarray.concat` and :py:func:`~xarray.open_mfdataset`. - By `Deepak Cherian `_ - - - Added ``compat='override'``. When merging, this option picks the variable from the first dataset - and skips all comparisons. - - - Added ``join='override'``. When aligning, this only checks that index sizes are equal among objects - and skips checking indexes for equality. - - - :py:func:`~xarray.concat` and :py:func:`~xarray.open_mfdataset` now support the ``join`` kwarg. - It is passed down to :py:func:`~xarray.align`. - - - :py:func:`~xarray.concat` now calls :py:func:`~xarray.merge` on variables that are not concatenated - (i.e. variables without ``concat_dim`` when ``data_vars`` or ``coords`` are ``"minimal"``). - :py:func:`~xarray.concat` passes its new ``compat`` kwarg down to :py:func:`~xarray.merge`. - (:issue:`2064`) - - Users can avoid a common bottleneck when using :py:func:`~xarray.open_mfdataset` on a large number of - files with variables that are known to be aligned and some of which need not be concatenated. - Slow equality comparisons can now be avoided, for e.g.:: - - data = xr.open_mfdataset(files, concat_dim='time', data_vars='minimal', - coords='minimal', compat='override', join='override') - -- In :py:meth:`~xarray.Dataset.to_zarr`, passing ``mode`` is not mandatory if - ``append_dim`` is set, as it will automatically be set to ``'a'`` internally. - By `David Brochart `_. - -- Added the ability to initialize an empty or full DataArray - with a single value. (:issue:`277`) - By `Gerardo Rivera `_. - -- :py:func:`~xarray.Dataset.to_netcdf()` now supports the ``invalid_netcdf`` kwarg when used - with ``engine="h5netcdf"``. It is passed to ``h5netcdf.File``. - By `Ulrich Herter `_. - -- ``xarray.Dataset.drop`` now supports keyword arguments; dropping index - labels by using both ``dim`` and ``labels`` or using a - :py:class:`~core.coordinates.DataArrayCoordinates` object are deprecated (:issue:`2910`). - By `Gregory Gundersen `_. - -- Added examples of :py:meth:`Dataset.set_index` and - :py:meth:`DataArray.set_index`, as well are more specific error messages - when the user passes invalid arguments (:issue:`3176`). - By `Gregory Gundersen `_. - -- :py:meth:`Dataset.filter_by_attrs` now filters the coordinates as well as the variables. - By `Spencer Jones `_. - -Bug fixes -~~~~~~~~~ - -- Improve "missing dimensions" error message for :py:func:`~xarray.apply_ufunc` - (:issue:`2078`). - By `Rick Russotto `_. -- :py:meth:`~xarray.DataArray.assign_coords` now supports dictionary arguments - (:issue:`3231`). - By `Gregory Gundersen `_. -- Fix regression introduced in v0.12.2 where ``copy(deep=True)`` would convert - unicode indices to dtype=object (:issue:`3094`). - By `Guido Imperiale `_. -- Improved error handling and documentation for `.expand_dims()` - read-only view. -- Fix tests for big-endian systems (:issue:`3125`). - By `Graham Inggs `_. -- XFAIL several tests which are expected to fail on ARM systems - due to a ``datetime`` issue in NumPy (:issue:`2334`). - By `Graham Inggs `_. -- Fix KeyError that arises when using .sel method with float values - different from coords float type (:issue:`3137`). - By `Hasan Ahmad `_. -- Fixed bug in ``combine_by_coords()`` causing a `ValueError` if the input had - an unused dimension with coordinates which were not monotonic (:issue:`3150`). - By `Tom Nicholas `_. -- Fixed crash when applying ``distributed.Client.compute()`` to a DataArray - (:issue:`3171`). By `Guido Imperiale `_. -- Better error message when using groupby on an empty DataArray (:issue:`3037`). - By `Hasan Ahmad `_. -- Fix error that arises when using open_mfdataset on a series of netcdf files - having differing values for a variable attribute of type list. (:issue:`3034`) - By `Hasan Ahmad `_. -- Prevent :py:meth:`~xarray.DataArray.argmax` and :py:meth:`~xarray.DataArray.argmin` from calling - dask compute (:issue:`3237`). By `Ulrich Herter `_. -- Plots in 2 dimensions (pcolormesh, contour) now allow to specify levels as numpy - array (:issue:`3284`). By `Mathias Hauser `_. -- Fixed bug in :meth:`DataArray.quantile` failing to keep attributes when - `keep_attrs` was True (:issue:`3304`). By `David Huard `_. - -Documentation -~~~~~~~~~~~~~ - -- Created a `PR checklist `_ - as a quick reference for tasks before creating a new PR - or pushing new commits. - By `Gregory Gundersen `_. - -- Fixed documentation to clean up unwanted files created in ``ipython`` examples - (:issue:`3227`). - By `Gregory Gundersen `_. - -.. _whats-new.0.12.3: - -v0.12.3 (10 July 2019) ----------------------- - -New functions/methods -~~~~~~~~~~~~~~~~~~~~~ - -- New methods :py:meth:`Dataset.to_stacked_array` and - :py:meth:`DataArray.to_unstacked_dataset` for reshaping Datasets of variables - with different dimensions - (:issue:`1317`). - This is useful for feeding data from xarray into machine learning models, - as described in :ref:`reshape.stacking_different`. - By `Noah Brenowitz `_. - -Enhancements -~~~~~~~~~~~~ - -- Support for renaming ``Dataset`` variables and dimensions independently - with :py:meth:`~Dataset.rename_vars` and :py:meth:`~Dataset.rename_dims` - (:issue:`3026`). - By `Julia Kent `_. - -- Add ``scales``, ``offsets``, ``units`` and ``descriptions`` - attributes to :py:class:`~xarray.DataArray` returned by - :py:func:`~xarray.open_rasterio`. (:issue:`3013`) - By `Erle Carrara `_. - -Bug fixes -~~~~~~~~~ - -- Resolved deprecation warnings from newer versions of matplotlib and dask. -- Compatibility fixes for the upcoming pandas 0.25 and NumPy 1.17 releases. - By `Stephan Hoyer `_. -- Fix summaries for multiindex coordinates (:issue:`3079`). - By `Jonas Hörsch `_. -- Fix HDF5 error that could arise when reading multiple groups from a file at - once (:issue:`2954`). - By `Stephan Hoyer `_. - -.. _whats-new.0.12.2: - -v0.12.2 (29 June 2019) ----------------------- - -New functions/methods -~~~~~~~~~~~~~~~~~~~~~ - -- Two new functions, :py:func:`~xarray.combine_nested` and - :py:func:`~xarray.combine_by_coords`, allow for combining datasets along any - number of dimensions, instead of the one-dimensional list of datasets - supported by :py:func:`~xarray.concat`. - - The new ``combine_nested`` will accept the datasets as a nested - list-of-lists, and combine by applying a series of concat and merge - operations. The new ``combine_by_coords`` instead uses the dimension - coordinates of datasets to order them. - - :py:func:`~xarray.open_mfdataset` can use either ``combine_nested`` or - ``combine_by_coords`` to combine datasets along multiple dimensions, by - specifying the argument ``combine='nested'`` or ``combine='by_coords'``. - - The older function ``auto_combine`` has been deprecated, - because its functionality has been subsumed by the new functions. - To avoid FutureWarnings switch to using ``combine_nested`` or - ``combine_by_coords``, (or set the ``combine`` argument in - ``open_mfdataset``). (:issue:`2159`) - By `Tom Nicholas `_. - -- :py:meth:`~xarray.DataArray.rolling_exp` and - :py:meth:`~xarray.Dataset.rolling_exp` added, similar to pandas' - ``pd.DataFrame.ewm`` method. Calling ``.mean`` on the resulting object - will return an exponentially weighted moving average. - By `Maximilian Roos `_. - -- New :py:func:`DataArray.str ` for string - related manipulations, based on ``pandas.Series.str``. - By `0x0L `_. - -- Added ``strftime`` method to ``.dt`` accessor, making it simpler to hand a - datetime ``DataArray`` to other code expecting formatted dates and times. - (:issue:`2090`). :py:meth:`~xarray.CFTimeIndex.strftime` is also now - available on :py:class:`CFTimeIndex`. - By `Alan Brammer `_ and - `Ryan May `_. - -- ``GroupBy.quantile`` is now a method of ``GroupBy`` - objects (:issue:`3018`). - By `David Huard `_. - -- Argument and return types are added to most methods on ``DataArray`` and - ``Dataset``, allowing static type checking both within xarray and external - libraries. Type checking with `mypy `_ is enabled in - CI (though not required yet). - By `Guido Imperiale `_ - and `Maximilian Roos `_. - -Enhancements to existing functionality -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- Add ``keepdims`` argument for reduce operations (:issue:`2170`) - By `Scott Wales `_. -- Enable ``@`` operator for DataArray. This is equivalent to :py:meth:`DataArray.dot` - By `Maximilian Roos `_. -- Add ``fill_value`` argument for reindex, align, and merge operations - to enable custom fill values. (:issue:`2876`) - By `Zach Griffith `_. -- :py:meth:`DataArray.transpose` now accepts a keyword argument - ``transpose_coords`` which enables transposition of coordinates in the - same way as :py:meth:`Dataset.transpose`. :py:meth:`DataArray.groupby` - :py:meth:`DataArray.groupby_bins`, and :py:meth:`DataArray.resample` now - accept a keyword argument ``restore_coord_dims`` which keeps the order - of the dimensions of multi-dimensional coordinates intact (:issue:`1856`). - By `Peter Hausamann `_. -- Clean up Python 2 compatibility in code (:issue:`2950`) - By `Guido Imperiale `_. -- Better warning message when supplying invalid objects to ``xr.merge`` - (:issue:`2948`). By `Mathias Hauser `_. -- Add ``errors`` keyword argument to ``Dataset.drop`` and :py:meth:`Dataset.drop_dims` - that allows ignoring errors if a passed label or dimension is not in the dataset - (:issue:`2994`). - By `Andrew Ross `_. - -IO related enhancements -~~~~~~~~~~~~~~~~~~~~~~~ - -- Implement :py:func:`~xarray.load_dataset` and - :py:func:`~xarray.load_dataarray` as alternatives to - :py:func:`~xarray.open_dataset` and :py:func:`~xarray.open_dataarray` to - open, load into memory, and close files, returning the Dataset or DataArray. - These functions are helpful for avoiding file-lock errors when trying to - write to files opened using ``open_dataset()`` or ``open_dataarray()``. - (:issue:`2887`) - By `Dan Nowacki `_. -- It is now possible to extend existing :ref:`io.zarr` datasets, by using - ``mode='a'`` and the new ``append_dim`` argument in - :py:meth:`~xarray.Dataset.to_zarr`. - By `Jendrik Jördening `_, - `David Brochart `_, - `Ryan Abernathey `_ and - `Shikhar Goenka `_. -- ``xr.open_zarr`` now accepts manually specified chunks with the ``chunks=`` - parameter. ``auto_chunk=True`` is equivalent to ``chunks='auto'`` for - backwards compatibility. The ``overwrite_encoded_chunks`` parameter is - added to remove the original zarr chunk encoding. - By `Lily Wang `_. -- netCDF chunksizes are now only dropped when original_shape is different, - not when it isn't found. (:issue:`2207`) - By `Karel van de Plassche `_. -- Character arrays' character dimension name decoding and encoding handled by - ``var.encoding['char_dim_name']`` (:issue:`2895`) - By `James McCreight `_. -- open_rasterio() now supports rasterio.vrt.WarpedVRT with custom transform, - width and height (:issue:`2864`). - By `Julien Michel `_. - -Bug fixes -~~~~~~~~~ - -- Rolling operations on xarray objects containing dask arrays could silently - compute the incorrect result or use large amounts of memory (:issue:`2940`). - By `Stephan Hoyer `_. -- Don't set encoding attributes on bounds variables when writing to netCDF. - (:issue:`2921`) - By `Deepak Cherian `_. -- NetCDF4 output: variables with unlimited dimensions must be chunked (not - contiguous) on output. (:issue:`1849`) - By `James McCreight `_. -- indexing with an empty list creates an object with zero-length axis (:issue:`2882`) - By `Mayeul d'Avezac `_. -- Return correct count for scalar datetime64 arrays (:issue:`2770`) - By `Dan Nowacki `_. -- Fixed max, min exception when applied to a multiIndex (:issue:`2923`) - By `Ian Castleden `_ -- A deep copy deep-copies the coords (:issue:`1463`) - By `Martin Pletcher `_. -- Increased support for `missing_value` (:issue:`2871`) - By `Deepak Cherian `_. -- Removed usages of `pytest.config`, which is deprecated (:issue:`2988`) - By `Maximilian Roos `_. -- Fixed performance issues with cftime installed (:issue:`3000`) - By `0x0L `_. -- Replace incorrect usages of `message` in pytest assertions - with `match` (:issue:`3011`) - By `Maximilian Roos `_. -- Add explicit pytest markers, now required by pytest - (:issue:`3032`). - By `Maximilian Roos `_. -- Test suite fixes for newer versions of pytest (:issue:`3011`, :issue:`3032`). - By `Maximilian Roos `_ - and `Stephan Hoyer `_. - -.. _whats-new.0.12.1: - -v0.12.1 (4 April 2019) ----------------------- - -Enhancements -~~~~~~~~~~~~ - -- Allow ``expand_dims`` method to support inserting/broadcasting dimensions - with size > 1. (:issue:`2710`) - By `Martin Pletcher `_. - -Bug fixes -~~~~~~~~~ - -- Dataset.copy(deep=True) now creates a deep copy of the attrs (:issue:`2835`). - By `Andras Gefferth `_. -- Fix incorrect ``indexes`` resulting from various ``Dataset`` operations - (e.g., ``swap_dims``, ``isel``, ``reindex``, ``[]``) (:issue:`2842`, - :issue:`2856`). - By `Stephan Hoyer `_. - -.. _whats-new.0.12.0: - -v0.12.0 (15 March 2019) ------------------------ - -Highlights include: - -- Removed support for Python 2. This is the first version of xarray that is - Python 3 only! -- New :py:meth:`~xarray.DataArray.coarsen` and - :py:meth:`~xarray.DataArray.integrate` methods. See :ref:`comput.coarsen` - and :ref:`compute.using_coordinates` for details. -- Many improvements to cftime support. See below for details. - -Deprecations -~~~~~~~~~~~~ - -- The ``compat`` argument to ``Dataset`` and the ``encoding`` argument to - ``DataArray`` are deprecated and will be removed in a future release. - (:issue:`1188`) - By `Maximilian Roos `_. - -cftime related enhancements -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- Resampling of standard and non-standard calendars indexed by - :py:class:`~xarray.CFTimeIndex` is now possible. (:issue:`2191`). - By `Jwen Fai Low `_ and - `Spencer Clark `_. - -- Taking the mean of arrays of :py:class:`cftime.datetime` objects, and - by extension, use of :py:meth:`~xarray.DataArray.coarsen` with - :py:class:`cftime.datetime` coordinates is now possible. By `Spencer Clark - `_. - -- Internal plotting now supports ``cftime.datetime`` objects as time series. - (:issue:`2164`) - By `Julius Busecke `_ and - `Spencer Clark `_. - -- :py:meth:`~xarray.cftime_range` now supports QuarterBegin and QuarterEnd offsets (:issue:`2663`). - By `Jwen Fai Low `_ - -- :py:meth:`~xarray.open_dataset` now accepts a ``use_cftime`` argument, which - can be used to require that ``cftime.datetime`` objects are always used, or - never used when decoding dates encoded with a standard calendar. This can be - used to ensure consistent date types are returned when using - :py:meth:`~xarray.open_mfdataset` (:issue:`1263`) and/or to silence - serialization warnings raised if dates from a standard calendar are found to - be outside the :py:class:`pandas.Timestamp`-valid range (:issue:`2754`). By - `Spencer Clark `_. - -- :py:meth:`pandas.Series.dropna` is now supported for a - :py:class:`pandas.Series` indexed by a :py:class:`~xarray.CFTimeIndex` - (:issue:`2688`). By `Spencer Clark `_. - -Other enhancements -~~~~~~~~~~~~~~~~~~ - -- Added ability to open netcdf4/hdf5 file-like objects with ``open_dataset``. - Requires (h5netcdf>0.7 and h5py>2.9.0). (:issue:`2781`) - By `Scott Henderson `_ -- Add ``data=False`` option to ``to_dict()`` methods. (:issue:`2656`) - By `Ryan Abernathey `_ -- :py:meth:`DataArray.coarsen` and - :py:meth:`Dataset.coarsen` are newly added. - See :ref:`comput.coarsen` for details. - (:issue:`2525`) - By `Keisuke Fujii `_. -- Upsampling an array via interpolation with resample is now dask-compatible, - as long as the array is not chunked along the resampling dimension. - By `Spencer Clark `_. -- :py:func:`xarray.testing.assert_equal` and - :py:func:`xarray.testing.assert_identical` now provide a more detailed - report showing what exactly differs between the two objects (dimensions / - coordinates / variables / attributes) (:issue:`1507`). - By `Benoit Bovy `_. -- Add ``tolerance`` option to ``resample()`` methods ``bfill``, ``pad``, - ``nearest``. (:issue:`2695`) - By `Hauke Schulz `_. -- :py:meth:`DataArray.integrate` and - :py:meth:`Dataset.integrate` are newly added. - See :ref:`compute.using_coordinates` for the detail. - (:issue:`1332`) - By `Keisuke Fujii `_. -- Added :py:meth:`~xarray.Dataset.drop_dims` (:issue:`1949`). - By `Kevin Squire `_. - -Bug fixes -~~~~~~~~~ - -- Silenced warnings that appear when using pandas 0.24. - By `Stephan Hoyer `_ -- Interpolating via resample now internally specifies ``bounds_error=False`` - as an argument to ``scipy.interpolate.interp1d``, allowing for interpolation - from higher frequencies to lower frequencies. Datapoints outside the bounds - of the original time coordinate are now filled with NaN (:issue:`2197`). By - `Spencer Clark `_. -- Line plots with the ``x`` argument set to a non-dimensional coord now plot - the correct data for 1D DataArrays. - (:issue:`2725`). By `Tom Nicholas `_. -- Subtracting a scalar ``cftime.datetime`` object from a - :py:class:`CFTimeIndex` now results in a :py:class:`pandas.TimedeltaIndex` - instead of raising a ``TypeError`` (:issue:`2671`). By `Spencer Clark - `_. -- backend_kwargs are no longer ignored when using open_dataset with pynio engine - (:issue:'2380') - By `Jonathan Joyce `_. -- Fix ``open_rasterio`` creating a WKT CRS instead of PROJ.4 with - ``rasterio`` 1.0.14+ (:issue:`2715`). - By `David Hoese `_. -- Masking data arrays with :py:meth:`xarray.DataArray.where` now returns an - array with the name of the original masked array (:issue:`2748` and :issue:`2457`). - By `Yohai Bar-Sinai `_. -- Fixed error when trying to reduce a DataArray using a function which does not - require an axis argument. (:issue:`2768`) - By `Tom Nicholas `_. -- Concatenating a sequence of :py:class:`~xarray.DataArray` with varying names - sets the name of the output array to ``None``, instead of the name of the - first input array. If the names are the same it sets the name to that, - instead to the name of the first DataArray in the list as it did before. - (:issue:`2775`). By `Tom Nicholas `_. - -- Per the `CF conventions section on calendars - `_, - specifying ``'standard'`` as the calendar type in - :py:meth:`~xarray.cftime_range` now correctly refers to the ``'gregorian'`` - calendar instead of the ``'proleptic_gregorian'`` calendar (:issue:`2761`). - -.. _whats-new.0.11.3: - -v0.11.3 (26 January 2019) -------------------------- - -Bug fixes -~~~~~~~~~ - -- Saving files with times encoded with reference dates with timezones - (e.g. '2000-01-01T00:00:00-05:00') no longer raises an error - (:issue:`2649`). By `Spencer Clark `_. -- Fixed performance regression with ``open_mfdataset`` (:issue:`2662`). - By `Tom Nicholas `_. -- Fixed supplying an explicit dimension in the ``concat_dim`` argument to - to ``open_mfdataset`` (:issue:`2647`). - By `Ben Root `_. - -.. _whats-new.0.11.2: - -v0.11.2 (2 January 2019) ------------------------- - -Removes inadvertently introduced setup dependency on pytest-runner -(:issue:`2641`). Otherwise, this release is exactly equivalent to 0.11.1. - -.. warning:: - - This is the last xarray release that will support Python 2.7. Future releases - will be Python 3 only, but older versions of xarray will always be available - for Python 2.7 users. For the more details, see: - - - `Xarray Github issue discussing dropping Python 2 `__ - - `Python 3 Statement `__ - - `Tips on porting to Python 3 `__ - -.. _whats-new.0.11.1: - -v0.11.1 (29 December 2018) --------------------------- - -This minor release includes a number of enhancements and bug fixes, and two -(slightly) breaking changes. - -Breaking changes -~~~~~~~~~~~~~~~~ - -- Minimum rasterio version increased from 0.36 to 1.0 (for ``open_rasterio``) -- Time bounds variables are now also decoded according to CF conventions - (:issue:`2565`). The previous behavior was to decode them only if they - had specific time attributes, now these attributes are copied - automatically from the corresponding time coordinate. This might - break downstream code that was relying on these variables to be - brake downstream code that was relying on these variables to be - not decoded. - By `Fabien Maussion `_. - -Enhancements -~~~~~~~~~~~~ - -- Ability to read and write consolidated metadata in zarr stores (:issue:`2558`). - By `Ryan Abernathey `_. -- :py:class:`CFTimeIndex` uses slicing for string indexing when possible (like - :py:class:`pandas.DatetimeIndex`), which avoids unnecessary copies. - By `Stephan Hoyer `_ -- Enable passing ``rasterio.io.DatasetReader`` or ``rasterio.vrt.WarpedVRT`` to - ``open_rasterio`` instead of file path string. Allows for in-memory - reprojection, see (:issue:`2588`). - By `Scott Henderson `_. -- Like :py:class:`pandas.DatetimeIndex`, :py:class:`CFTimeIndex` now supports - "dayofyear" and "dayofweek" accessors (:issue:`2597`). Note this requires a - version of cftime greater than 1.0.2. By `Spencer Clark - `_. -- The option ``'warn_for_unclosed_files'`` (False by default) has been added to - allow users to enable a warning when files opened by xarray are deallocated - but were not explicitly closed. This is mostly useful for debugging; we - recommend enabling it in your test suites if you use xarray for IO. - By `Stephan Hoyer `_ -- Support Dask ``HighLevelGraphs`` by `Matthew Rocklin `_. -- :py:meth:`DataArray.resample` and :py:meth:`Dataset.resample` now supports the - ``loffset`` kwarg just like Pandas. - By `Deepak Cherian `_ -- Datasets are now guaranteed to have a ``'source'`` encoding, so the source - file name is always stored (:issue:`2550`). - By `Tom Nicholas `_. -- The ``apply`` methods for ``DatasetGroupBy``, ``DataArrayGroupBy``, - ``DatasetResample`` and ``DataArrayResample`` now support passing positional - arguments to the applied function as a tuple to the ``args`` argument. - By `Matti Eskelinen `_. -- 0d slices of ndarrays are now obtained directly through indexing, rather than - extracting and wrapping a scalar, avoiding unnecessary copying. By `Daniel - Wennberg `_. -- Added support for ``fill_value`` with - :py:meth:`~xarray.DataArray.shift` and :py:meth:`~xarray.Dataset.shift` - By `Maximilian Roos `_ - -Bug fixes -~~~~~~~~~ - -- Ensure files are automatically closed, if possible, when no longer referenced - by a Python variable (:issue:`2560`). - By `Stephan Hoyer `_ -- Fixed possible race conditions when reading/writing to disk in parallel - (:issue:`2595`). - By `Stephan Hoyer `_ -- Fix h5netcdf saving scalars with filters or chunks (:issue:`2563`). - By `Martin Raspaud `_. -- Fix parsing of ``_Unsigned`` attribute set by OPENDAP servers. (:issue:`2583`). - By `Deepak Cherian `_ -- Fix failure in time encoding when exporting to netCDF with versions of pandas - less than 0.21.1 (:issue:`2623`). By `Spencer Clark - `_. -- Fix MultiIndex selection to update label and level (:issue:`2619`). - By `Keisuke Fujii `_. - -.. _whats-new.0.11.0: - -v0.11.0 (7 November 2018) -------------------------- - -Breaking changes -~~~~~~~~~~~~~~~~ - -- Finished deprecations (changed behavior with this release): - - - ``Dataset.T`` has been removed as a shortcut for :py:meth:`Dataset.transpose`. - Call :py:meth:`Dataset.transpose` directly instead. - - Iterating over a ``Dataset`` now includes only data variables, not coordinates. - Similarily, calling ``len`` and ``bool`` on a ``Dataset`` now - includes only data variables. - - ``DataArray.__contains__`` (used by Python's ``in`` operator) now checks - array data, not coordinates. - - The old resample syntax from before xarray 0.10, e.g., - ``data.resample('1D', dim='time', how='mean')``, is no longer supported will - raise an error in most cases. You need to use the new resample syntax - instead, e.g., ``data.resample(time='1D').mean()`` or - ``data.resample({'time': '1D'}).mean()``. - - -- New deprecations (behavior will be changed in xarray 0.12): - - - Reduction of :py:meth:`DataArray.groupby` and :py:meth:`DataArray.resample` - without dimension argument will change in the next release. - Now we warn a FutureWarning. - By `Keisuke Fujii `_. - - The ``inplace`` kwarg of a number of `DataArray` and `Dataset` methods is being - deprecated and will be removed in the next release. - By `Deepak Cherian `_. - - -- Refactored storage backends: - - - Xarray's storage backends now automatically open and close files when - necessary, rather than requiring opening a file with ``autoclose=True``. A - global least-recently-used cache is used to store open files; the default - limit of 128 open files should suffice in most cases, but can be adjusted if - necessary with - ``xarray.set_options(file_cache_maxsize=...)``. The ``autoclose`` argument - to ``open_dataset`` and related functions has been deprecated and is now a - no-op. - - This change, along with an internal refactor of xarray's storage backends, - should significantly improve performance when reading and writing - netCDF files with Dask, especially when working with many files or using - Dask Distributed. By `Stephan Hoyer `_ - - -- Support for non-standard calendars used in climate science: - - - Xarray will now always use :py:class:`cftime.datetime` objects, rather - than by default trying to coerce them into ``np.datetime64[ns]`` objects. - A :py:class:`~xarray.CFTimeIndex` will be used for indexing along time - coordinates in these cases. - - A new method :py:meth:`~xarray.CFTimeIndex.to_datetimeindex` has been added - to aid in converting from a :py:class:`~xarray.CFTimeIndex` to a - :py:class:`pandas.DatetimeIndex` for the remaining use-cases where - using a :py:class:`~xarray.CFTimeIndex` is still a limitation (e.g. for - resample or plotting). - - Setting the ``enable_cftimeindex`` option is now a no-op and emits a - ``FutureWarning``. - -Enhancements -~~~~~~~~~~~~ - -- :py:meth:`xarray.DataArray.plot.line` can now accept multidimensional - coordinate variables as input. `hue` must be a dimension name in this case. - (:issue:`2407`) - By `Deepak Cherian `_. -- Added support for Python 3.7. (:issue:`2271`). - By `Joe Hamman `_. -- Added support for plotting data with `pandas.Interval` coordinates, such as those - created by :py:meth:`~xarray.DataArray.groupby_bins` - By `Maximilian Maahn `_. -- Added :py:meth:`~xarray.CFTimeIndex.shift` for shifting the values of a - CFTimeIndex by a specified frequency. (:issue:`2244`). - By `Spencer Clark `_. -- Added support for using ``cftime.datetime`` coordinates with - :py:meth:`~xarray.DataArray.differentiate`, - :py:meth:`~xarray.Dataset.differentiate`, - :py:meth:`~xarray.DataArray.interp`, and - :py:meth:`~xarray.Dataset.interp`. - By `Spencer Clark `_ -- There is now a global option to either always keep or always discard - dataset and dataarray attrs upon operations. The option is set with - ``xarray.set_options(keep_attrs=True)``, and the default is to use the old - behaviour. - By `Tom Nicholas `_. -- Added a new backend for the GRIB file format based on ECMWF *cfgrib* - python driver and *ecCodes* C-library. (:issue:`2475`) - By `Alessandro Amici `_, - sponsored by `ECMWF `_. -- Resample now supports a dictionary mapping from dimension to frequency as - its first argument, e.g., ``data.resample({'time': '1D'}).mean()``. This is - consistent with other xarray functions that accept either dictionaries or - keyword arguments. By `Stephan Hoyer `_. - -- The preferred way to access tutorial data is now to load it lazily with - :py:meth:`xarray.tutorial.open_dataset`. - :py:meth:`xarray.tutorial.load_dataset` calls `Dataset.load()` prior - to returning (and is now deprecated). This was changed in order to facilitate - using tutorial datasets with dask. - By `Joe Hamman `_. -- ``DataArray`` can now use ``xr.set_option(keep_attrs=True)`` and retain attributes in binary operations, - such as (``+, -, * ,/``). Default behaviour is unchanged (*Attributes will be dismissed*). By `Michael Blaschek `_ - -Bug fixes -~~~~~~~~~ - -- ``FacetGrid`` now properly uses the ``cbar_kwargs`` keyword argument. - (:issue:`1504`, :issue:`1717`) - By `Deepak Cherian `_. -- Addition and subtraction operators used with a CFTimeIndex now preserve the - index's type. (:issue:`2244`). - By `Spencer Clark `_. -- We now properly handle arrays of ``datetime.datetime`` and ``datetime.timedelta`` - provided as coordinates. (:issue:`2512`) - By `Deepak Cherian `_. -- ``xarray.DataArray.roll`` correctly handles multidimensional arrays. - (:issue:`2445`) - By `Keisuke Fujii `_. -- ``xarray.plot()`` now properly accepts a ``norm`` argument and does not override - the norm's ``vmin`` and ``vmax``. (:issue:`2381`) - By `Deepak Cherian `_. -- ``xarray.DataArray.std()`` now correctly accepts ``ddof`` keyword argument. - (:issue:`2240`) - By `Keisuke Fujii `_. -- Restore matplotlib's default of plotting dashed negative contours when - a single color is passed to ``DataArray.contour()`` e.g. ``colors='k'``. - By `Deepak Cherian `_. - - -- Fix a bug that caused some indexing operations on arrays opened with - ``open_rasterio`` to error (:issue:`2454`). - By `Stephan Hoyer `_. - -- Subtracting one CFTimeIndex from another now returns a - ``pandas.TimedeltaIndex``, analogous to the behavior for DatetimeIndexes - (:issue:`2484`). By `Spencer Clark `_. -- Adding a TimedeltaIndex to, or subtracting a TimedeltaIndex from a - CFTimeIndex is now allowed (:issue:`2484`). - By `Spencer Clark `_. -- Avoid use of Dask's deprecated ``get=`` parameter in tests - by `Matthew Rocklin `_. -- An ``OverflowError`` is now accurately raised and caught during the - encoding process if a reference date is used that is so distant that - the dates must be encoded using cftime rather than NumPy (:issue:`2272`). - By `Spencer Clark `_. - -- Chunked datasets can now roundtrip to Zarr storage continually - with `to_zarr` and ``open_zarr`` (:issue:`2300`). - By `Lily Wang `_. - -.. _whats-new.0.10.9: - -v0.10.9 (21 September 2018) ---------------------------- - -This minor release contains a number of backwards compatible enhancements. - -Announcements of note: - -- Xarray is now a NumFOCUS fiscally sponsored project! Read - `the anouncement `_ - for more details. -- We have a new :doc:`roadmap` that outlines our future development plans. - -- ``Dataset.apply`` now properly documents the way `func` is called. - By `Matti Eskelinen `_. - -Enhancements -~~~~~~~~~~~~ - -- :py:meth:`~xarray.DataArray.differentiate` and - :py:meth:`~xarray.Dataset.differentiate` are newly added. - (:issue:`1332`) - By `Keisuke Fujii `_. - -- Default colormap for sequential and divergent data can now be set via - :py:func:`~xarray.set_options()` - (:issue:`2394`) - By `Julius Busecke `_. - -- min_count option is newly supported in :py:meth:`~xarray.DataArray.sum`, - :py:meth:`~xarray.DataArray.prod` and :py:meth:`~xarray.Dataset.sum`, and - :py:meth:`~xarray.Dataset.prod`. - (:issue:`2230`) - By `Keisuke Fujii `_. - -- :py:func:`~plot.plot()` now accepts the kwargs - ``xscale, yscale, xlim, ylim, xticks, yticks`` just like Pandas. Also ``xincrease=False, yincrease=False`` now use matplotlib's axis inverting methods instead of setting limits. - By `Deepak Cherian `_. (:issue:`2224`) - -- DataArray coordinates and Dataset coordinates and data variables are - now displayed as `a b ... y z` rather than `a b c d ...`. - (:issue:`1186`) - By `Seth P `_. -- A new CFTimeIndex-enabled :py:func:`cftime_range` function for use in - generating dates from standard or non-standard calendars. By `Spencer Clark - `_. - -- When interpolating over a ``datetime64`` axis, you can now provide a datetime string instead of a ``datetime64`` object. E.g. ``da.interp(time='1991-02-01')`` - (:issue:`2284`) - By `Deepak Cherian `_. - -- A clear error message is now displayed if a ``set`` or ``dict`` is passed in place of an array - (:issue:`2331`) - By `Maximilian Roos `_. - -- Applying ``unstack`` to a large DataArray or Dataset is now much faster if the MultiIndex has not been modified after stacking the indices. - (:issue:`1560`) - By `Maximilian Maahn `_. - -- You can now control whether or not to offset the coordinates when using - the ``roll`` method and the current behavior, coordinates rolled by default, - raises a deprecation warning unless explicitly setting the keyword argument. - (:issue:`1875`) - By `Andrew Huang `_. - -- You can now call ``unstack`` without arguments to unstack every MultiIndex in a DataArray or Dataset. - By `Julia Signell `_. - -- Added the ability to pass a data kwarg to ``copy`` to create a new object with the - same metadata as the original object but using new values. - By `Julia Signell `_. - -Bug fixes -~~~~~~~~~ - -- ``xarray.plot.imshow()`` correctly uses the ``origin`` argument. - (:issue:`2379`) - By `Deepak Cherian `_. - -- Fixed ``DataArray.to_iris()`` failure while creating ``DimCoord`` by - falling back to creating ``AuxCoord``. Fixed dependency on ``var_name`` - attribute being set. - (:issue:`2201`) - By `Thomas Voigt `_. -- Fixed a bug in ``zarr`` backend which prevented use with datasets with - invalid chunk size encoding after reading from an existing store - (:issue:`2278`). - By `Joe Hamman `_. - -- Tests can be run in parallel with pytest-xdist - By `Tony Tung `_. - -- Follow up the renamings in dask; from dask.ghost to dask.overlap - By `Keisuke Fujii `_. - -- Now raises a ValueError when there is a conflict between dimension names and - level names of MultiIndex. (:issue:`2299`) - By `Keisuke Fujii `_. - -- Follow up the renamings in dask; from dask.ghost to dask.overlap - By `Keisuke Fujii `_. - -- Now :py:func:`~xarray.apply_ufunc` raises a ValueError when the size of - ``input_core_dims`` is inconsistent with the number of arguments. - (:issue:`2341`) - By `Keisuke Fujii `_. - -- Fixed ``Dataset.filter_by_attrs()`` behavior not matching ``netCDF4.Dataset.get_variables_by_attributes()``. - When more than one ``key=value`` is passed into ``Dataset.filter_by_attrs()`` it will now return a Dataset with variables which pass - all the filters. - (:issue:`2315`) - By `Andrew Barna `_. - -.. _whats-new.0.10.8: - -v0.10.8 (18 July 2018) ----------------------- - -Breaking changes -~~~~~~~~~~~~~~~~ - -- Xarray no longer supports python 3.4. Additionally, the minimum supported - versions of the following dependencies has been updated and/or clarified: - - - Pandas: 0.18 -> 0.19 - - NumPy: 1.11 -> 1.12 - - Dask: 0.9 -> 0.16 - - Matplotlib: unspecified -> 1.5 - - (:issue:`2204`). By `Joe Hamman `_. - -Enhancements -~~~~~~~~~~~~ - -- :py:meth:`~xarray.DataArray.interp_like` and - :py:meth:`~xarray.Dataset.interp_like` methods are newly added. - (:issue:`2218`) - By `Keisuke Fujii `_. - -- Added support for curvilinear and unstructured generic grids - to :py:meth:`~xarray.DataArray.to_cdms2` and - :py:meth:`~xarray.DataArray.from_cdms2` (:issue:`2262`). - By `Stephane Raynaud `_. - -Bug fixes -~~~~~~~~~ - -- Fixed a bug in ``zarr`` backend which prevented use with datasets with - incomplete chunks in multiple dimensions (:issue:`2225`). - By `Joe Hamman `_. - -- Fixed a bug in :py:meth:`~Dataset.to_netcdf` which prevented writing - datasets when the arrays had different chunk sizes (:issue:`2254`). - By `Mike Neish `_. - -- Fixed masking during the conversion to cdms2 objects by - :py:meth:`~xarray.DataArray.to_cdms2` (:issue:`2262`). - By `Stephane Raynaud `_. - -- Fixed a bug in 2D plots which incorrectly raised an error when 2D coordinates - weren't monotonic (:issue:`2250`). - By `Fabien Maussion `_. - -- Fixed warning raised in :py:meth:`~Dataset.to_netcdf` due to deprecation of - `effective_get` in dask (:issue:`2238`). - By `Joe Hamman `_. - -.. _whats-new.0.10.7: - -v0.10.7 (7 June 2018) ---------------------- - -Enhancements -~~~~~~~~~~~~ - -- Plot labels now make use of metadata that follow CF conventions - (:issue:`2135`). - By `Deepak Cherian `_ and `Ryan Abernathey `_. - -- Line plots now support facetting with ``row`` and ``col`` arguments - (:issue:`2107`). - By `Yohai Bar Sinai `_. - -- :py:meth:`~xarray.DataArray.interp` and :py:meth:`~xarray.Dataset.interp` - methods are newly added. - See :ref:`interp` for the detail. - (:issue:`2079`) - By `Keisuke Fujii `_. - -Bug fixes -~~~~~~~~~ - -- Fixed a bug in ``rasterio`` backend which prevented use with ``distributed``. - The ``rasterio`` backend now returns pickleable objects (:issue:`2021`). - By `Joe Hamman `_. - -.. _whats-new.0.10.6: - -v0.10.6 (31 May 2018) ---------------------- - -The minor release includes a number of bug-fixes and backwards compatible -enhancements. - -Enhancements -~~~~~~~~~~~~ - -- New PseudoNetCDF backend for many Atmospheric data formats including - GEOS-Chem, CAMx, NOAA arlpacked bit and many others. See - :ref:`io.PseudoNetCDF` for more details. - By `Barron Henderson `_. - -- The :py:class:`Dataset` constructor now aligns :py:class:`DataArray` - arguments in ``data_vars`` to indexes set explicitly in ``coords``, - where previously an error would be raised. - (:issue:`674`) - By `Maximilian Roos `_. - -- :py:meth:`~DataArray.sel`, :py:meth:`~DataArray.isel` & :py:meth:`~DataArray.reindex`, - (and their :py:class:`Dataset` counterparts) now support supplying a ``dict`` - as a first argument, as an alternative to the existing approach - of supplying `kwargs`. This allows for more robust behavior - of dimension names which conflict with other keyword names, or are - not strings. - By `Maximilian Roos `_. - -- :py:meth:`~DataArray.rename` now supports supplying ``**kwargs``, as an - alternative to the existing approach of supplying a ``dict`` as the - first argument. - By `Maximilian Roos `_. - -- :py:meth:`~DataArray.cumsum` and :py:meth:`~DataArray.cumprod` now support - aggregation over multiple dimensions at the same time. This is the default - behavior when dimensions are not specified (previously this raised an error). - By `Stephan Hoyer `_ - -- :py:meth:`DataArray.dot` and :py:func:`dot` are partly supported with older - dask<0.17.4. (related to :issue:`2203`) - By `Keisuke Fujii `_. - -- Xarray now uses `Versioneer `__ - to manage its version strings. (:issue:`1300`). - By `Joe Hamman `_. - -Bug fixes -~~~~~~~~~ - -- Fixed a regression in 0.10.4, where explicitly specifying ``dtype='S1'`` or - ``dtype=str`` in ``encoding`` with ``to_netcdf()`` raised an error - (:issue:`2149`). - `Stephan Hoyer `_ - -- :py:func:`apply_ufunc` now directly validates output variables - (:issue:`1931`). - By `Stephan Hoyer `_. - -- Fixed a bug where ``to_netcdf(..., unlimited_dims='bar')`` yielded NetCDF - files with spurious 0-length dimensions (i.e. ``b``, ``a``, and ``r``) - (:issue:`2134`). - By `Joe Hamman `_. - -- Removed spurious warnings with ``Dataset.update(Dataset)`` (:issue:`2161`) - and ``array.equals(array)`` when ``array`` contains ``NaT`` (:issue:`2162`). - By `Stephan Hoyer `_. - -- Aggregations with :py:meth:`Dataset.reduce` (including ``mean``, ``sum``, - etc) no longer drop unrelated coordinates (:issue:`1470`). Also fixed a - bug where non-scalar data-variables that did not include the aggregation - dimension were improperly skipped. - By `Stephan Hoyer `_ - -- Fix :meth:`~DataArray.stack` with non-unique coordinates on pandas 0.23 - (:issue:`2160`). - By `Stephan Hoyer `_ - -- Selecting data indexed by a length-1 ``CFTimeIndex`` with a slice of strings - now behaves as it does when using a length-1 ``DatetimeIndex`` (i.e. it no - longer falsely returns an empty array when the slice includes the value in - the index) (:issue:`2165`). - By `Spencer Clark `_. - -- Fix ``DataArray.groupby().reduce()`` mutating coordinates on the input array - when grouping over dimension coordinates with duplicated entries - (:issue:`2153`). - By `Stephan Hoyer `_ - -- Fix ``Dataset.to_netcdf()`` cannot create group with ``engine="h5netcdf"`` - (:issue:`2177`). - By `Stephan Hoyer `_ - -.. _whats-new.0.10.4: - -v0.10.4 (16 May 2018) ----------------------- - -The minor release includes a number of bug-fixes and backwards compatible -enhancements. A highlight is ``CFTimeIndex``, which offers support for -non-standard calendars used in climate modeling. - -Documentation -~~~~~~~~~~~~~ - -- New FAQ entry, :ref:`ecosystem`. - By `Deepak Cherian `_. -- :ref:`assigning_values` now includes examples on how to select and assign - values to a :py:class:`~xarray.DataArray` with ``.loc``. - By `Chiara Lepore `_. - -Enhancements -~~~~~~~~~~~~ - -- Add an option for using a ``CFTimeIndex`` for indexing times with - non-standard calendars and/or outside the Timestamp-valid range; this index - enables a subset of the functionality of a standard - ``pandas.DatetimeIndex``. - See :ref:`CFTimeIndex` for full details. - (:issue:`789`, :issue:`1084`, :issue:`1252`) - By `Spencer Clark `_ with help from - `Stephan Hoyer `_. -- Allow for serialization of ``cftime.datetime`` objects (:issue:`789`, - :issue:`1084`, :issue:`2008`, :issue:`1252`) using the standalone ``cftime`` - library. - By `Spencer Clark `_. -- Support writing lists of strings as netCDF attributes (:issue:`2044`). - By `Dan Nowacki `_. -- :py:meth:`~xarray.Dataset.to_netcdf` with ``engine='h5netcdf'`` now accepts h5py - encoding settings ``compression`` and ``compression_opts``, along with the - NetCDF4-Python style settings ``gzip=True`` and ``complevel``. - This allows using any compression plugin installed in hdf5, e.g. LZF - (:issue:`1536`). By `Guido Imperiale `_. -- :py:meth:`~xarray.dot` on dask-backed data will now call :func:`dask.array.einsum`. - This greatly boosts speed and allows chunking on the core dims. - The function now requires dask >= 0.17.3 to work on dask-backed data - (:issue:`2074`). By `Guido Imperiale `_. -- ``plot.line()`` learned new kwargs: ``xincrease``, ``yincrease`` that change - the direction of the respective axes. - By `Deepak Cherian `_. - -- Added the ``parallel`` option to :py:func:`open_mfdataset`. This option uses - ``dask.delayed`` to parallelize the open and preprocessing steps within - ``open_mfdataset``. This is expected to provide performance improvements when - opening many files, particularly when used in conjunction with dask's - multiprocessing or distributed schedulers (:issue:`1981`). - By `Joe Hamman `_. - -- New ``compute`` option in :py:meth:`~xarray.Dataset.to_netcdf`, - :py:meth:`~xarray.Dataset.to_zarr`, and :py:func:`~xarray.save_mfdataset` to - allow for the lazy computation of netCDF and zarr stores. This feature is - currently only supported by the netCDF4 and zarr backends. (:issue:`1784`). - By `Joe Hamman `_. - - -Bug fixes -~~~~~~~~~ - -- ``ValueError`` is raised when coordinates with the wrong size are assigned to - a :py:class:`DataArray`. (:issue:`2112`) - By `Keisuke Fujii `_. -- Fixed a bug in :py:meth:`~xarray.DataArray.rolling` with bottleneck. Also, - fixed a bug in rolling an integer dask array. (:issue:`2113`) - By `Keisuke Fujii `_. -- Fixed a bug where `keep_attrs=True` flag was neglected if - :py:func:`apply_ufunc` was used with :py:class:`Variable`. (:issue:`2114`) - By `Keisuke Fujii `_. -- When assigning a :py:class:`DataArray` to :py:class:`Dataset`, any conflicted - non-dimensional coordinates of the DataArray are now dropped. - (:issue:`2068`) - By `Keisuke Fujii `_. -- Better error handling in ``open_mfdataset`` (:issue:`2077`). - By `Stephan Hoyer `_. -- ``plot.line()`` does not call ``autofmt_xdate()`` anymore. Instead it changes - the rotation and horizontal alignment of labels without removing the x-axes of - any other subplots in the figure (if any). - By `Deepak Cherian `_. -- Colorbar limits are now determined by excluding ±Infs too. - By `Deepak Cherian `_. - By `Joe Hamman `_. -- Fixed ``to_iris`` to maintain lazy dask array after conversion (:issue:`2046`). - By `Alex Hilson `_ and `Stephan Hoyer `_. - -.. _whats-new.0.10.3: - -v0.10.3 (13 April 2018) ------------------------- - -The minor release includes a number of bug-fixes and backwards compatible enhancements. - -Enhancements -~~~~~~~~~~~~ - -- :py:meth:`~xarray.DataArray.isin` and :py:meth:`~xarray.Dataset.isin` methods, - which test each value in the array for whether it is contained in the - supplied list, returning a bool array. See :ref:`selecting values with isin` - for full details. Similar to the ``np.isin`` function. - By `Maximilian Roos `_. -- Some speed improvement to construct :py:class:`~xarray.core.rolling.DataArrayRolling` - object (:issue:`1993`) - By `Keisuke Fujii `_. -- Handle variables with different values for ``missing_value`` and - ``_FillValue`` by masking values for both attributes; previously this - resulted in a ``ValueError``. (:issue:`2016`) - By `Ryan May `_. - -Bug fixes -~~~~~~~~~ - -- Fixed ``decode_cf`` function to operate lazily on dask arrays - (:issue:`1372`). By `Ryan Abernathey `_. -- Fixed labeled indexing with slice bounds given by xarray objects with - datetime64 or timedelta64 dtypes (:issue:`1240`). - By `Stephan Hoyer `_. -- Attempting to convert an xarray.Dataset into a numpy array now raises an - informative error message. - By `Stephan Hoyer `_. -- Fixed a bug in decode_cf_datetime where ``int32`` arrays weren't parsed - correctly (:issue:`2002`). - By `Fabien Maussion `_. -- When calling `xr.auto_combine()` or `xr.open_mfdataset()` with a `concat_dim`, - the resulting dataset will have that one-element dimension (it was - silently dropped, previously) (:issue:`1988`). - By `Ben Root `_. - -.. _whats-new.0.10.2: - -v0.10.2 (13 March 2018) ------------------------ - -The minor release includes a number of bug-fixes and enhancements, along with -one possibly **backwards incompatible change**. - -Backwards incompatible changes -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- The addition of ``__array_ufunc__`` for xarray objects (see below) means that - NumPy `ufunc methods`_ (e.g., ``np.add.reduce``) that previously worked on - ``xarray.DataArray`` objects by converting them into NumPy arrays will now - raise ``NotImplementedError`` instead. In all cases, the work-around is - simple: convert your objects explicitly into NumPy arrays before calling the - ufunc (e.g., with ``.values``). - -.. _ufunc methods: https://docs.scipy.org/doc/numpy/reference/ufuncs.html#methods - -Enhancements -~~~~~~~~~~~~ - -- Added :py:func:`~xarray.dot`, equivalent to :py:func:`numpy.einsum`. - Also, :py:func:`~xarray.DataArray.dot` now supports ``dims`` option, - which specifies the dimensions to sum over. - (:issue:`1951`) - By `Keisuke Fujii `_. - -- Support for writing xarray datasets to netCDF files (netcdf4 backend only) - when using the `dask.distributed `_ - scheduler (:issue:`1464`). - By `Joe Hamman `_. - -- Support lazy vectorized-indexing. After this change, flexible indexing such - as orthogonal/vectorized indexing, becomes possible for all the backend - arrays. Also, lazy ``transpose`` is now also supported. (:issue:`1897`) - By `Keisuke Fujii `_. - -- Implemented NumPy's ``__array_ufunc__`` protocol for all xarray objects - (:issue:`1617`). This enables using NumPy ufuncs directly on - ``xarray.Dataset`` objects with recent versions of NumPy (v1.13 and newer): - - .. ipython:: python - - ds = xr.Dataset({"a": 1}) - np.sin(ds) - - This obliviates the need for the ``xarray.ufuncs`` module, which will be - deprecated in the future when xarray drops support for older versions of - NumPy. By `Stephan Hoyer `_. - -- Improve :py:func:`~xarray.DataArray.rolling` logic. - :py:func:`~xarray.core.rolling.DataArrayRolling` object now supports - :py:func:`~xarray.core.rolling.DataArrayRolling.construct` method that returns a view - of the DataArray / Dataset object with the rolling-window dimension added - to the last axis. This enables more flexible operation, such as strided - rolling, windowed rolling, ND-rolling, short-time FFT and convolution. - (:issue:`1831`, :issue:`1142`, :issue:`819`) - By `Keisuke Fujii `_. -- :py:func:`~plot.line()` learned to make plots with data on x-axis if so specified. (:issue:`575`) - By `Deepak Cherian `_. - -Bug fixes -~~~~~~~~~ - -- Raise an informative error message when using ``apply_ufunc`` with numpy - v1.11 (:issue:`1956`). - By `Stephan Hoyer `_. -- Fix the precision drop after indexing datetime64 arrays (:issue:`1932`). - By `Keisuke Fujii `_. -- Silenced irrelevant warnings issued by ``open_rasterio`` (:issue:`1964`). - By `Stephan Hoyer `_. -- Fix kwarg `colors` clashing with auto-inferred `cmap` (:issue:`1461`) - By `Deepak Cherian `_. -- Fix :py:func:`~xarray.plot.imshow` error when passed an RGB array with - size one in a spatial dimension. - By `Zac Hatfield-Dodds `_. - -.. _whats-new.0.10.1: - -v0.10.1 (25 February 2018) --------------------------- - -The minor release includes a number of bug-fixes and backwards compatible enhancements. - -Documentation -~~~~~~~~~~~~~ - -- Added a new guide on :ref:`contributing` (:issue:`640`) - By `Joe Hamman `_. -- Added apply_ufunc example to :ref:`/examples/weather-data.ipynb#Toy-weather-data` (:issue:`1844`). - By `Liam Brannigan `_. -- New entry `Why don’t aggregations return Python scalars?` in the - :doc:`getting-started-guide/faq` (:issue:`1726`). - By `0x0L `_. - -Enhancements -~~~~~~~~~~~~ -**New functions and methods**: - -- Added :py:meth:`DataArray.to_iris` and - :py:meth:`DataArray.from_iris` for - converting data arrays to and from Iris_ Cubes with the same data and coordinates - (:issue:`621` and :issue:`37`). - By `Neil Parley `_ and `Duncan Watson-Parris `_. -- Experimental support for using `Zarr`_ as storage layer for xarray - (:issue:`1223`). - By `Ryan Abernathey `_ and - `Joe Hamman `_. -- New :py:meth:`~xarray.DataArray.rank` on arrays and datasets. Requires - bottleneck (:issue:`1731`). - By `0x0L `_. -- ``.dt`` accessor can now ceil, floor and round timestamps to specified frequency. - By `Deepak Cherian `_. - -**Plotting enhancements**: - -- :func:`xarray.plot.imshow` now handles RGB and RGBA images. - Saturation can be adjusted with ``vmin`` and ``vmax``, or with ``robust=True``. - By `Zac Hatfield-Dodds `_. -- :py:func:`~plot.contourf()` learned to contour 2D variables that have both a - 1D coordinate (e.g. time) and a 2D coordinate (e.g. depth as a function of - time) (:issue:`1737`). - By `Deepak Cherian `_. -- :py:func:`~plot.plot()` rotates x-axis ticks if x-axis is time. - By `Deepak Cherian `_. -- :py:func:`~plot.line()` can draw multiple lines if provided with a - 2D variable. - By `Deepak Cherian `_. - -**Other enhancements**: - -- Reduce methods such as :py:func:`DataArray.sum()` now handles object-type array. - - .. ipython:: python - - da = xr.DataArray(np.array([True, False, np.nan], dtype=object), dims="x") - da.sum() - - (:issue:`1866`) - By `Keisuke Fujii `_. -- Reduce methods such as :py:func:`DataArray.sum()` now accepts ``dtype`` - arguments. (:issue:`1838`) - By `Keisuke Fujii `_. -- Added nodatavals attribute to DataArray when using :py:func:`~xarray.open_rasterio`. (:issue:`1736`). - By `Alan Snow `_. -- Use ``pandas.Grouper`` class in xarray resample methods rather than the - deprecated ``pandas.TimeGrouper`` class (:issue:`1766`). - By `Joe Hamman `_. -- Experimental support for parsing ENVI metadata to coordinates and attributes - in :py:func:`xarray.open_rasterio`. - By `Matti Eskelinen `_. -- Reduce memory usage when decoding a variable with a scale_factor, by - converting 8-bit and 16-bit integers to float32 instead of float64 - (:pull:`1840`), and keeping float16 and float32 as float32 (:issue:`1842`). - Correspondingly, encoded variables may also be saved with a smaller dtype. - By `Zac Hatfield-Dodds `_. -- Speed of reindexing/alignment with dask array is orders of magnitude faster - when inserting missing values (:issue:`1847`). - By `Stephan Hoyer `_. -- Fix ``axis`` keyword ignored when applying ``np.squeeze`` to ``DataArray`` (:issue:`1487`). - By `Florian Pinault `_. -- ``netcdf4-python`` has moved the its time handling in the ``netcdftime`` module to - a standalone package (`netcdftime`_). As such, xarray now considers `netcdftime`_ - an optional dependency. One benefit of this change is that it allows for - encoding/decoding of datetimes with non-standard calendars without the - ``netcdf4-python`` dependency (:issue:`1084`). - By `Joe Hamman `_. - -.. _Zarr: http://zarr.readthedocs.io/ - -.. _Iris: http://scitools.org.uk/iris - -.. _netcdftime: https://unidata.github.io/netcdftime - -**New functions/methods** - -- New :py:meth:`~xarray.DataArray.rank` on arrays and datasets. Requires - bottleneck (:issue:`1731`). - By `0x0L `_. - -Bug fixes -~~~~~~~~~ -- Rolling aggregation with ``center=True`` option now gives the same result - with pandas including the last element (:issue:`1046`). - By `Keisuke Fujii `_. - -- Support indexing with a 0d-np.ndarray (:issue:`1921`). - By `Keisuke Fujii `_. -- Added warning in api.py of a netCDF4 bug that occurs when - the filepath has 88 characters (:issue:`1745`). - By `Liam Brannigan `_. -- Fixed encoding of multi-dimensional coordinates in - :py:meth:`~Dataset.to_netcdf` (:issue:`1763`). - By `Mike Neish `_. -- Fixed chunking with non-file-based rasterio datasets (:issue:`1816`) and - refactored rasterio test suite. - By `Ryan Abernathey `_ -- Bug fix in open_dataset(engine='pydap') (:issue:`1775`) - By `Keisuke Fujii `_. -- Bug fix in vectorized assignment (:issue:`1743`, :issue:`1744`). - Now item assignment to :py:meth:`~DataArray.__setitem__` checks -- Bug fix in vectorized assignment (:issue:`1743`, :issue:`1744`). - Now item assignment to :py:meth:`DataArray.__setitem__` checks - coordinates of target, destination and keys. If there are any conflict among - these coordinates, ``IndexError`` will be raised. - By `Keisuke Fujii `_. -- Properly point ``DataArray.__dask_scheduler__`` to - ``dask.threaded.get``. By `Matthew Rocklin `_. -- Bug fixes in :py:meth:`DataArray.plot.imshow`: all-NaN arrays and arrays - with size one in some dimension can now be plotted, which is good for - exploring satellite imagery (:issue:`1780`). - By `Zac Hatfield-Dodds `_. -- Fixed ``UnboundLocalError`` when opening netCDF file (:issue:`1781`). - By `Stephan Hoyer `_. -- The ``variables``, ``attrs``, and ``dimensions`` properties have been - deprecated as part of a bug fix addressing an issue where backends were - unintentionally loading the datastores data and attributes repeatedly during - writes (:issue:`1798`). - By `Joe Hamman `_. -- Compatibility fixes to plotting module for Numpy 1.14 and Pandas 0.22 - (:issue:`1813`). - By `Joe Hamman `_. -- Bug fix in encoding coordinates with ``{'_FillValue': None}`` in netCDF - metadata (:issue:`1865`). - By `Chris Roth `_. -- Fix indexing with lists for arrays loaded from netCDF files with - ``engine='h5netcdf`` (:issue:`1864`). - By `Stephan Hoyer `_. -- Corrected a bug with incorrect coordinates for non-georeferenced geotiff - files (:issue:`1686`). Internally, we now use the rasterio coordinate - transform tool instead of doing the computations ourselves. A - ``parse_coordinates`` kwarg has beed added to :py:func:`~open_rasterio` - (set to ``True`` per default). - By `Fabien Maussion `_. -- The colors of discrete colormaps are now the same regardless if `seaborn` - is installed or not (:issue:`1896`). - By `Fabien Maussion `_. -- Fixed dtype promotion rules in :py:func:`where` and :py:func:`concat` to - match pandas (:issue:`1847`). A combination of strings/numbers or - unicode/bytes now promote to object dtype, instead of strings or unicode. - By `Stephan Hoyer `_. -- Fixed bug where :py:meth:`~xarray.DataArray.isnull` was loading data - stored as dask arrays (:issue:`1937`). - By `Joe Hamman `_. - -.. _whats-new.0.10.0: - -v0.10.0 (20 November 2017) --------------------------- - -This is a major release that includes bug fixes, new features and a few -backwards incompatible changes. Highlights include: - -- Indexing now supports broadcasting over dimensions, similar to NumPy's - vectorized indexing (but better!). -- :py:meth:`~DataArray.resample` has a new groupby-like API like pandas. -- :py:func:`~xarray.apply_ufunc` facilitates wrapping and parallelizing - functions written for NumPy arrays. -- Performance improvements, particularly for dask and :py:func:`open_mfdataset`. - -Breaking changes -~~~~~~~~~~~~~~~~ - -- xarray now supports a form of vectorized indexing with broadcasting, where - the result of indexing depends on dimensions of indexers, - e.g., ``array.sel(x=ind)`` with ``ind.dims == ('y',)``. Alignment between - coordinates on indexed and indexing objects is also now enforced. - Due to these changes, existing uses of xarray objects to index other xarray - objects will break in some cases. - - The new indexing API is much more powerful, supporting outer, diagonal and - vectorized indexing in a single interface. - The ``isel_points`` and ``sel_points`` methods are deprecated, since they are - now redundant with the ``isel`` / ``sel`` methods. - See :ref:`vectorized_indexing` for the details (:issue:`1444`, - :issue:`1436`). - By `Keisuke Fujii `_ and - `Stephan Hoyer `_. - -- A new resampling interface to match pandas' groupby-like API was added to - :py:meth:`Dataset.resample` and :py:meth:`DataArray.resample` - (:issue:`1272`). :ref:`Timeseries resampling ` is - fully supported for data with arbitrary dimensions as is both downsampling - and upsampling (including linear, quadratic, cubic, and spline interpolation). - - Old syntax: - - .. ipython:: - :verbatim: - - In [1]: ds.resample("24H", dim="time", how="max") - Out[1]: - - [...] - - New syntax: - - .. ipython:: - :verbatim: - - In [1]: ds.resample(time="24H").max() - Out[1]: - - [...] - - Note that both versions are currently supported, but using the old syntax will - produce a warning encouraging users to adopt the new syntax. - By `Daniel Rothenberg `_. - -- Calling ``repr()`` or printing xarray objects at the command line or in a - Jupyter Notebook will not longer automatically compute dask variables or - load data on arrays lazily loaded from disk (:issue:`1522`). - By `Guido Imperiale `_. - -- Supplying ``coords`` as a dictionary to the ``DataArray`` constructor without - also supplying an explicit ``dims`` argument is no longer supported. This - behavior was deprecated in version 0.9 but will now raise an error - (:issue:`727`). - -- Several existing features have been deprecated and will change to new - behavior in xarray v0.11. If you use any of them with xarray v0.10, you - should see a ``FutureWarning`` that describes how to update your code: - - - ``Dataset.T`` has been deprecated an alias for ``Dataset.transpose()`` - (:issue:`1232`). In the next major version of xarray, it will provide short- - cut lookup for variables or attributes with name ``'T'``. - - ``DataArray.__contains__`` (e.g., ``key in data_array``) currently checks - for membership in ``DataArray.coords``. In the next major version of - xarray, it will check membership in the array data found in - ``DataArray.values`` instead (:issue:`1267`). - - Direct iteration over and counting a ``Dataset`` (e.g., ``[k for k in ds]``, - ``ds.keys()``, ``ds.values()``, ``len(ds)`` and ``if ds``) currently - includes all variables, both data and coordinates. For improved usability - and consistency with pandas, in the next major version of xarray these will - change to only include data variables (:issue:`884`). Use ``ds.variables``, - ``ds.data_vars`` or ``ds.coords`` as alternatives. - -- Changes to minimum versions of dependencies: - - - Old numpy < 1.11 and pandas < 0.18 are no longer supported (:issue:`1512`). - By `Keisuke Fujii `_. - - The minimum supported version bottleneck has increased to 1.1 - (:issue:`1279`). - By `Joe Hamman `_. - -Enhancements -~~~~~~~~~~~~ - -**New functions/methods** - -- New helper function :py:func:`~xarray.apply_ufunc` for wrapping functions - written to work on NumPy arrays to support labels on xarray objects - (:issue:`770`). ``apply_ufunc`` also support automatic parallelization for - many functions with dask. See :ref:`comput.wrapping-custom` and - :ref:`dask.automatic-parallelization` for details. - By `Stephan Hoyer `_. - -- Added new method :py:meth:`Dataset.to_dask_dataframe`, convert a dataset into - a dask dataframe. - This allows lazy loading of data from a dataset containing dask arrays (:issue:`1462`). - By `James Munroe `_. - -- New function :py:func:`~xarray.where` for conditionally switching between - values in xarray objects, like :py:func:`numpy.where`: - - .. ipython:: - :verbatim: - - In [1]: import xarray as xr - - In [2]: arr = xr.DataArray([[1, 2, 3], [4, 5, 6]], dims=("x", "y")) - - In [3]: xr.where(arr % 2, "even", "odd") - Out[3]: - - array([['even', 'odd', 'even'], - ['odd', 'even', 'odd']], - dtype='`_. - -- Added :py:func:`~xarray.show_versions` function to aid in debugging - (:issue:`1485`). - By `Joe Hamman `_. - -**Performance improvements** - -- :py:func:`~xarray.concat` was computing variables that aren't in memory - (e.g. dask-based) multiple times; :py:func:`~xarray.open_mfdataset` - was loading them multiple times from disk. Now, both functions will instead - load them at most once and, if they do, store them in memory in the - concatenated array/dataset (:issue:`1521`). - By `Guido Imperiale `_. - -- Speed-up (x 100) of ``xarray.conventions.decode_cf_datetime``. - By `Christian Chwala `_. - -**IO related improvements** - -- Unicode strings (``str`` on Python 3) are now round-tripped successfully even - when written as character arrays (e.g., as netCDF3 files or when using - ``engine='scipy'``) (:issue:`1638`). This is controlled by the ``_Encoding`` - attribute convention, which is also understood directly by the netCDF4-Python - interface. See :ref:`io.string-encoding` for full details. - By `Stephan Hoyer `_. - -- Support for ``data_vars`` and ``coords`` keywords from - :py:func:`~xarray.concat` added to :py:func:`~xarray.open_mfdataset` - (:issue:`438`). Using these keyword arguments can significantly reduce - memory usage and increase speed. - By `Oleksandr Huziy `_. - -- Support for :py:class:`pathlib.Path` objects added to - :py:func:`~xarray.open_dataset`, :py:func:`~xarray.open_mfdataset`, - ``xarray.to_netcdf``, and :py:func:`~xarray.save_mfdataset` - (:issue:`799`): - - .. ipython:: - :verbatim: - - In [2]: from pathlib import Path # In Python 2, use pathlib2! - - In [3]: data_dir = Path("data/") - - In [4]: one_file = data_dir / "dta_for_month_01.nc" - - In [5]: xr.open_dataset(one_file) - Out[5]: - - [...] - - By `Willi Rath `_. - -- You can now explicitly disable any default ``_FillValue`` (``NaN`` for - floating point values) by passing the enconding ``{'_FillValue': None}`` - (:issue:`1598`). - By `Stephan Hoyer `_. - -- More attributes available in :py:attr:`~xarray.Dataset.attrs` dictionary when - raster files are opened with :py:func:`~xarray.open_rasterio`. - By `Greg Brener `_. - -- Support for NetCDF files using an ``_Unsigned`` attribute to indicate that a - a signed integer data type should be interpreted as unsigned bytes - (:issue:`1444`). - By `Eric Bruning `_. - -- Support using an existing, opened netCDF4 ``Dataset`` with - :py:class:`~xarray.backends.NetCDF4DataStore`. This permits creating an - :py:class:`~xarray.Dataset` from a netCDF4 ``Dataset`` that has been opened using - other means (:issue:`1459`). - By `Ryan May `_. - -- Changed :py:class:`~xarray.backends.PydapDataStore` to take a Pydap dataset. - This permits opening Opendap datasets that require authentication, by - instantiating a Pydap dataset with a session object. Also added - :py:meth:`xarray.backends.PydapDataStore.open` which takes a url and session - object (:issue:`1068`). - By `Philip Graae `_. - -- Support reading and writing unlimited dimensions with h5netcdf (:issue:`1636`). - By `Joe Hamman `_. - -**Other improvements** - -- Added ``_ipython_key_completions_`` to xarray objects, to enable - autocompletion for dictionary-like access in IPython, e.g., - ``ds['tem`` + tab -> ``ds['temperature']`` (:issue:`1628`). - By `Keisuke Fujii `_. - -- Support passing keyword arguments to ``load``, ``compute``, and ``persist`` - methods. Any keyword arguments supplied to these methods are passed on to - the corresponding dask function (:issue:`1523`). - By `Joe Hamman `_. - -- Encoding attributes are now preserved when xarray objects are concatenated. - The encoding is copied from the first object (:issue:`1297`). - By `Joe Hamman `_ and - `Gerrit Holl `_. - -- Support applying rolling window operations using bottleneck's moving window - functions on data stored as dask arrays (:issue:`1279`). - By `Joe Hamman `_. - -- Experimental support for the Dask collection interface (:issue:`1674`). - By `Matthew Rocklin `_. - -Bug fixes -~~~~~~~~~ - -- Suppress ``RuntimeWarning`` issued by ``numpy`` for "invalid value comparisons" - (e.g. ``NaN``). Xarray now behaves similarly to Pandas in its treatment of - binary and unary operations on objects with NaNs (:issue:`1657`). - By `Joe Hamman `_. - -- Unsigned int support for reduce methods with ``skipna=True`` - (:issue:`1562`). - By `Keisuke Fujii `_. - -- Fixes to ensure xarray works properly with pandas 0.21: - - - Fix :py:meth:`~xarray.DataArray.isnull` method (:issue:`1549`). - - :py:meth:`~xarray.DataArray.to_series` and - :py:meth:`~xarray.Dataset.to_dataframe` should not return a ``pandas.MultiIndex`` - for 1D data (:issue:`1548`). - - Fix plotting with datetime64 axis labels (:issue:`1661`). - - By `Stephan Hoyer `_. - -- :py:func:`~xarray.open_rasterio` method now shifts the rasterio - coordinates so that they are centered in each pixel (:issue:`1468`). - By `Greg Brener `_. - -- :py:meth:`~xarray.Dataset.rename` method now doesn't throw errors - if some ``Variable`` is renamed to the same name as another ``Variable`` - as long as that other ``Variable`` is also renamed (:issue:`1477`). This - method now does throw when two ``Variables`` would end up with the same name - after the rename (since one of them would get overwritten in this case). - By `Prakhar Goel `_. - -- Fix :py:func:`xarray.testing.assert_allclose` to actually use ``atol`` and - ``rtol`` arguments when called on ``DataArray`` objects (:issue:`1488`). - By `Stephan Hoyer `_. - -- xarray ``quantile`` methods now properly raise a ``TypeError`` when applied to - objects with data stored as ``dask`` arrays (:issue:`1529`). - By `Joe Hamman `_. - -- Fix positional indexing to allow the use of unsigned integers (:issue:`1405`). - By `Joe Hamman `_ and - `Gerrit Holl `_. - -- Creating a :py:class:`Dataset` now raises ``MergeError`` if a coordinate - shares a name with a dimension but is comprised of arbitrary dimensions - (:issue:`1120`). - By `Joe Hamman `_. - -- :py:func:`~xarray.open_rasterio` method now skips rasterio's ``crs`` - attribute if its value is ``None`` (:issue:`1520`). - By `Leevi Annala `_. - -- Fix :py:func:`xarray.DataArray.to_netcdf` to return bytes when no path is - provided (:issue:`1410`). - By `Joe Hamman `_. - -- Fix :py:func:`xarray.save_mfdataset` to properly raise an informative error - when objects other than ``Dataset`` are provided (:issue:`1555`). - By `Joe Hamman `_. - -- :py:func:`xarray.Dataset.copy` would not preserve the encoding property - (:issue:`1586`). - By `Guido Imperiale `_. - -- :py:func:`xarray.concat` would eagerly load dask variables into memory if - the first argument was a numpy variable (:issue:`1588`). - By `Guido Imperiale `_. - -- Fix bug in :py:meth:`~xarray.Dataset.to_netcdf` when writing in append mode - (:issue:`1215`). - By `Joe Hamman `_. - -- Fix ``netCDF4`` backend to properly roundtrip the ``shuffle`` encoding option - (:issue:`1606`). - By `Joe Hamman `_. - -- Fix bug when using ``pytest`` class decorators to skiping certain unittests. - The previous behavior unintentionally causing additional tests to be skipped - (:issue:`1531`). By `Joe Hamman `_. - -- Fix pynio backend for upcoming release of pynio with Python 3 support - (:issue:`1611`). By `Ben Hillman `_. - -- Fix ``seaborn`` import warning for Seaborn versions 0.8 and newer when the - ``apionly`` module was deprecated. - (:issue:`1633`). By `Joe Hamman `_. - -- Fix COMPAT: MultiIndex checking is fragile - (:issue:`1833`). By `Florian Pinault `_. - -- Fix ``rasterio`` backend for Rasterio versions 1.0alpha10 and newer. - (:issue:`1641`). By `Chris Holden `_. - -Bug fixes after rc1 -~~~~~~~~~~~~~~~~~~~ - -- Suppress warning in IPython autocompletion, related to the deprecation - of ``.T`` attributes (:issue:`1675`). - By `Keisuke Fujii `_. - -- Fix a bug in lazily-indexing netCDF array. (:issue:`1688`) - By `Keisuke Fujii `_. - -- (Internal bug) MemoryCachedArray now supports the orthogonal indexing. - Also made some internal cleanups around array wrappers (:issue:`1429`). - By `Keisuke Fujii `_. - -- (Internal bug) MemoryCachedArray now always wraps ``np.ndarray`` by - ``NumpyIndexingAdapter``. (:issue:`1694`) - By `Keisuke Fujii `_. - -- Fix importing xarray when running Python with ``-OO`` (:issue:`1706`). - By `Stephan Hoyer `_. - -- Saving a netCDF file with a coordinates with a spaces in its names now raises - an appropriate warning (:issue:`1689`). - By `Stephan Hoyer `_. - -- Fix two bugs that were preventing dask arrays from being specified as - coordinates in the DataArray constructor (:issue:`1684`). - By `Joe Hamman `_. - -- Fixed ``apply_ufunc`` with ``dask='parallelized'`` for scalar arguments - (:issue:`1697`). - By `Stephan Hoyer `_. - -- Fix "Chunksize cannot exceed dimension size" error when writing netCDF4 files - loaded from disk (:issue:`1225`). - By `Stephan Hoyer `_. - -- Validate the shape of coordinates with names matching dimensions in the - DataArray constructor (:issue:`1709`). - By `Stephan Hoyer `_. - -- Raise ``NotImplementedError`` when attempting to save a MultiIndex to a - netCDF file (:issue:`1547`). - By `Stephan Hoyer `_. - -- Remove netCDF dependency from rasterio backend tests. - By `Matti Eskelinen `_ - -Bug fixes after rc2 -~~~~~~~~~~~~~~~~~~~ - -- Fixed unexpected behavior in ``Dataset.set_index()`` and - ``DataArray.set_index()`` introduced by Pandas 0.21.0. Setting a new - index with a single variable resulted in 1-level - ``pandas.MultiIndex`` instead of a simple ``pandas.Index`` - (:issue:`1722`). By `Benoit Bovy `_. - -- Fixed unexpected memory loading of backend arrays after ``print``. - (:issue:`1720`). By `Keisuke Fujii `_. - -.. _whats-new.0.9.6: - -v0.9.6 (8 June 2017) --------------------- - -This release includes a number of backwards compatible enhancements and bug -fixes. - -Enhancements -~~~~~~~~~~~~ - -- New :py:meth:`~xarray.Dataset.sortby` method to ``Dataset`` and ``DataArray`` - that enable sorting along dimensions (:issue:`967`). - See :ref:`the docs ` for examples. - By `Chun-Wei Yuan `_ and - `Kyle Heuton `_. - -- Add ``.dt`` accessor to DataArrays for computing datetime-like properties - for the values they contain, similar to ``pandas.Series`` (:issue:`358`). - By `Daniel Rothenberg `_. - -- Renamed internal dask arrays created by ``open_dataset`` to match new dask - conventions (:issue:`1343`). - By `Ryan Abernathey `_. - -- :py:meth:`~xarray.as_variable` is now part of the public API (:issue:`1303`). - By `Benoit Bovy `_. - -- :py:func:`~xarray.align` now supports ``join='exact'``, which raises - an error instead of aligning when indexes to be aligned are not equal. - By `Stephan Hoyer `_. - -- New function :py:func:`~xarray.open_rasterio` for opening raster files with - the `rasterio `_ library. - See :ref:`the docs ` for details. - By `Joe Hamman `_, - `Nic Wayand `_ and - `Fabien Maussion `_ - -Bug fixes -~~~~~~~~~ - -- Fix error from repeated indexing of datasets loaded from disk (:issue:`1374`). - By `Stephan Hoyer `_. - -- Fix a bug where ``.isel_points`` wrongly assigns unselected coordinate to - ``data_vars``. - By `Keisuke Fujii `_. - -- Tutorial datasets are now checked against a reference MD5 sum to confirm - successful download (:issue:`1392`). By `Matthew Gidden - `_. - -- ``DataArray.chunk()`` now accepts dask specific kwargs like - ``Dataset.chunk()`` does. By `Fabien Maussion `_. - -- Support for ``engine='pydap'`` with recent releases of Pydap (3.2.2+), - including on Python 3 (:issue:`1174`). - -Documentation -~~~~~~~~~~~~~ - -- A new `gallery `_ - allows to add interactive examples to the documentation. - By `Fabien Maussion `_. - -Testing -~~~~~~~ - -- Fix test suite failure caused by changes to ``pandas.cut`` function - (:issue:`1386`). - By `Ryan Abernathey `_. - -- Enhanced tests suite by use of ``@network`` decorator, which is - controlled via ``--run-network-tests`` command line argument - to ``py.test`` (:issue:`1393`). - By `Matthew Gidden `_. - -.. _whats-new.0.9.5: - -v0.9.5 (17 April, 2017) ------------------------ - -Remove an inadvertently introduced print statement. - -.. _whats-new.0.9.3: - -v0.9.3 (16 April, 2017) ------------------------ - -This minor release includes bug-fixes and backwards compatible enhancements. - -Enhancements -~~~~~~~~~~~~ - -- New :py:meth:`~xarray.DataArray.persist` method to Datasets and DataArrays to - enable persisting data in distributed memory when using Dask (:issue:`1344`). - By `Matthew Rocklin `_. - -- New :py:meth:`~xarray.DataArray.expand_dims` method for ``DataArray`` and - ``Dataset`` (:issue:`1326`). - By `Keisuke Fujii `_. - -Bug fixes -~~~~~~~~~ - -- Fix ``.where()`` with ``drop=True`` when arguments do not have indexes - (:issue:`1350`). This bug, introduced in v0.9, resulted in xarray producing - incorrect results in some cases. - By `Stephan Hoyer `_. - -- Fixed writing to file-like objects with :py:meth:`~xarray.Dataset.to_netcdf` - (:issue:`1320`). - `Stephan Hoyer `_. - -- Fixed explicitly setting ``engine='scipy'`` with ``to_netcdf`` when not - providing a path (:issue:`1321`). - `Stephan Hoyer `_. - -- Fixed open_dataarray does not pass properly its parameters to open_dataset - (:issue:`1359`). - `Stephan Hoyer `_. - -- Ensure test suite works when runs from an installed version of xarray - (:issue:`1336`). Use ``@pytest.mark.slow`` instead of a custom flag to mark - slow tests. - By `Stephan Hoyer `_ - -.. _whats-new.0.9.2: - -v0.9.2 (2 April 2017) ---------------------- - -The minor release includes bug-fixes and backwards compatible enhancements. - -Enhancements -~~~~~~~~~~~~ - -- ``rolling`` on Dataset is now supported (:issue:`859`). - -- ``.rolling()`` on Dataset is now supported (:issue:`859`). - By `Keisuke Fujii `_. - -- When bottleneck version 1.1 or later is installed, use bottleneck for rolling - ``var``, ``argmin``, ``argmax``, and ``rank`` computations. Also, rolling - median now accepts a ``min_periods`` argument (:issue:`1276`). - By `Joe Hamman `_. - -- When ``.plot()`` is called on a 2D DataArray and only one dimension is - specified with ``x=`` or ``y=``, the other dimension is now guessed - (:issue:`1291`). - By `Vincent Noel `_. - -- Added new method :py:meth:`~Dataset.assign_attrs` to ``DataArray`` and - ``Dataset``, a chained-method compatible implementation of the - ``dict.update`` method on attrs (:issue:`1281`). - By `Henry S. Harrison `_. - -- Added new ``autoclose=True`` argument to - :py:func:`~xarray.open_mfdataset` to explicitly close opened files when not in - use to prevent occurrence of an OS Error related to too many open files - (:issue:`1198`). - Note, the default is ``autoclose=False``, which is consistent with - previous xarray behavior. - By `Phillip J. Wolfram `_. - -- The ``repr()`` of ``Dataset`` and ``DataArray`` attributes uses a similar - format to coordinates and variables, with vertically aligned entries - truncated to fit on a single line (:issue:`1319`). Hopefully this will stop - people writing ``data.attrs = {}`` and discarding metadata in notebooks for - the sake of cleaner output. The full metadata is still available as - ``data.attrs``. - By `Zac Hatfield-Dodds `_. - -- Enhanced tests suite by use of ``@slow`` and ``@flaky`` decorators, which are - controlled via ``--run-flaky`` and ``--skip-slow`` command line arguments - to ``py.test`` (:issue:`1336`). - By `Stephan Hoyer `_ and - `Phillip J. Wolfram `_. - -- New aggregation on rolling objects :py:meth:`~core.rolling.DataArrayRolling.count` - which providing a rolling count of valid values (:issue:`1138`). - -Bug fixes -~~~~~~~~~ -- Rolling operations now keep preserve original dimension order (:issue:`1125`). - By `Keisuke Fujii `_. - -- Fixed ``sel`` with ``method='nearest'`` on Python 2.7 and 64-bit Windows - (:issue:`1140`). - `Stephan Hoyer `_. - -- Fixed ``where`` with ``drop='True'`` for empty masks (:issue:`1341`). - By `Stephan Hoyer `_ and - `Phillip J. Wolfram `_. - -.. _whats-new.0.9.1: - -v0.9.1 (30 January 2017) ------------------------- - -Renamed the "Unindexed dimensions" section in the ``Dataset`` and -``DataArray`` repr (added in v0.9.0) to "Dimensions without coordinates" -(:issue:`1199`). - -.. _whats-new.0.9.0: - -v0.9.0 (25 January 2017) ------------------------- - -This major release includes five months worth of enhancements and bug fixes from -24 contributors, including some significant changes that are not fully backwards -compatible. Highlights include: - -- Coordinates are now *optional* in the xarray data model, even for dimensions. -- Changes to caching, lazy loading and pickling to improve xarray's experience - for parallel computing. -- Improvements for accessing and manipulating ``pandas.MultiIndex`` levels. -- Many new methods and functions, including - :py:meth:`~DataArray.quantile`, - :py:meth:`~DataArray.cumsum`, - :py:meth:`~DataArray.cumprod` - :py:attr:`~DataArray.combine_first` - :py:meth:`~DataArray.set_index`, - :py:meth:`~DataArray.reset_index`, - :py:meth:`~DataArray.reorder_levels`, - :py:func:`~xarray.full_like`, - :py:func:`~xarray.zeros_like`, - :py:func:`~xarray.ones_like` - :py:func:`~xarray.open_dataarray`, - :py:meth:`~DataArray.compute`, - :py:meth:`Dataset.info`, - :py:func:`testing.assert_equal`, - :py:func:`testing.assert_identical`, and - :py:func:`testing.assert_allclose`. - -Breaking changes -~~~~~~~~~~~~~~~~ - -- Index coordinates for each dimensions are now optional, and no longer created - by default :issue:`1017`. You can identify such dimensions without coordinates - by their appearance in list of "Dimensions without coordinates" in the - ``Dataset`` or ``DataArray`` repr: - - .. ipython:: - :verbatim: - - In [1]: xr.Dataset({"foo": (("x", "y"), [[1, 2]])}) - Out[1]: - - Dimensions: (x: 1, y: 2) - Dimensions without coordinates: x, y - Data variables: - foo (x, y) int64 1 2 - - This has a number of implications: - - - :py:func:`~align` and :py:meth:`~Dataset.reindex` can now error, if - dimensions labels are missing and dimensions have different sizes. - - Because pandas does not support missing indexes, methods such as - ``to_dataframe``/``from_dataframe`` and ``stack``/``unstack`` no longer - roundtrip faithfully on all inputs. Use :py:meth:`~Dataset.reset_index` to - remove undesired indexes. - - ``Dataset.__delitem__`` and :py:meth:`~Dataset.drop` no longer delete/drop - variables that have dimensions matching a deleted/dropped variable. - - ``DataArray.coords.__delitem__`` is now allowed on variables matching - dimension names. - - ``.sel`` and ``.loc`` now handle indexing along a dimension without - coordinate labels by doing integer based indexing. See - :ref:`indexing.missing_coordinates` for an example. - - :py:attr:`~Dataset.indexes` is no longer guaranteed to include all - dimensions names as keys. The new method :py:meth:`~Dataset.get_index` has - been added to get an index for a dimension guaranteed, falling back to - produce a default ``RangeIndex`` if necessary. - -- The default behavior of ``merge`` is now ``compat='no_conflicts'``, so some - merges will now succeed in cases that previously raised - ``xarray.MergeError``. Set ``compat='broadcast_equals'`` to restore the - previous default. See :ref:`combining.no_conflicts` for more details. - -- Reading :py:attr:`~DataArray.values` no longer always caches values in a NumPy - array :issue:`1128`. Caching of ``.values`` on variables read from netCDF - files on disk is still the default when :py:func:`open_dataset` is called with - ``cache=True``. - By `Guido Imperiale `_ and - `Stephan Hoyer `_. -- Pickling a ``Dataset`` or ``DataArray`` linked to a file on disk no longer - caches its values into memory before pickling (:issue:`1128`). Instead, pickle - stores file paths and restores objects by reopening file references. This - enables preliminary, experimental use of xarray for opening files with - `dask.distributed `_. - By `Stephan Hoyer `_. -- Coordinates used to index a dimension are now loaded eagerly into - :py:class:`pandas.Index` objects, instead of loading the values lazily. - By `Guido Imperiale `_. -- Automatic levels for 2d plots are now guaranteed to land on ``vmin`` and - ``vmax`` when these kwargs are explicitly provided (:issue:`1191`). The - automated level selection logic also slightly changed. - By `Fabien Maussion `_. - -- ``DataArray.rename()`` behavior changed to strictly change the ``DataArray.name`` - if called with string argument, or strictly change coordinate names if called with - dict-like argument. - By `Markus Gonser `_. - -- By default ``to_netcdf()`` add a ``_FillValue = NaN`` attributes to float types. - By `Frederic Laliberte `_. - -- ``repr`` on ``DataArray`` objects uses an shortened display for NumPy array - data that is less likely to overflow onto multiple pages (:issue:`1207`). - By `Stephan Hoyer `_. - -- xarray no longer supports python 3.3, versions of dask prior to v0.9.0, - or versions of bottleneck prior to v1.0. - -Deprecations -~~~~~~~~~~~~ - -- Renamed the ``Coordinate`` class from xarray's low level API to - :py:class:`~xarray.IndexVariable`. ``Variable.to_variable`` and - ``Variable.to_coord`` have been renamed to - :py:meth:`~xarray.Variable.to_base_variable` and - :py:meth:`~xarray.Variable.to_index_variable`. -- Deprecated supplying ``coords`` as a dictionary to the ``DataArray`` - constructor without also supplying an explicit ``dims`` argument. The old - behavior encouraged relying on the iteration order of dictionaries, which is - a bad practice (:issue:`727`). -- Removed a number of methods deprecated since v0.7.0 or earlier: - ``load_data``, ``vars``, ``drop_vars``, ``dump``, ``dumps`` and the - ``variables`` keyword argument to ``Dataset``. -- Removed the dummy module that enabled ``import xray``. - -Enhancements -~~~~~~~~~~~~ - -- Added new method :py:meth:`~DataArray.combine_first` to ``DataArray`` and - ``Dataset``, based on the pandas method of the same name (see :ref:`combine`). - By `Chun-Wei Yuan `_. - -- Added the ability to change default automatic alignment (arithmetic_join="inner") - for binary operations via :py:func:`~xarray.set_options()` - (see :ref:`math automatic alignment`). - By `Chun-Wei Yuan `_. - -- Add checking of ``attr`` names and values when saving to netCDF, raising useful - error messages if they are invalid. (:issue:`911`). - By `Robin Wilson `_. -- Added ability to save ``DataArray`` objects directly to netCDF files using - :py:meth:`~xarray.DataArray.to_netcdf`, and to load directly from netCDF files - using :py:func:`~xarray.open_dataarray` (:issue:`915`). These remove the need - to convert a ``DataArray`` to a ``Dataset`` before saving as a netCDF file, - and deals with names to ensure a perfect 'roundtrip' capability. - By `Robin Wilson `_. -- Multi-index levels are now accessible as "virtual" coordinate variables, - e.g., ``ds['time']`` can pull out the ``'time'`` level of a multi-index - (see :ref:`coordinates`). ``sel`` also accepts providing multi-index levels - as keyword arguments, e.g., ``ds.sel(time='2000-01')`` - (see :ref:`multi-level indexing`). - By `Benoit Bovy `_. -- Added ``set_index``, ``reset_index`` and ``reorder_levels`` methods to - easily create and manipulate (multi-)indexes (see :ref:`reshape.set_index`). - By `Benoit Bovy `_. -- Added the ``compat`` option ``'no_conflicts'`` to ``merge``, allowing the - combination of xarray objects with disjoint (:issue:`742`) or - overlapping (:issue:`835`) coordinates as long as all present data agrees. - By `Johnnie Gray `_. See - :ref:`combining.no_conflicts` for more details. -- It is now possible to set ``concat_dim=None`` explicitly in - :py:func:`~xarray.open_mfdataset` to disable inferring a dimension along - which to concatenate. - By `Stephan Hoyer `_. -- Added methods :py:meth:`DataArray.compute`, :py:meth:`Dataset.compute`, and - :py:meth:`Variable.compute` as a non-mutating alternative to - :py:meth:`~DataArray.load`. - By `Guido Imperiale `_. -- Adds DataArray and Dataset methods :py:meth:`~xarray.DataArray.cumsum` and - :py:meth:`~xarray.DataArray.cumprod`. By `Phillip J. Wolfram - `_. - -- New properties :py:attr:`Dataset.sizes` and :py:attr:`DataArray.sizes` for - providing consistent access to dimension length on both ``Dataset`` and - ``DataArray`` (:issue:`921`). - By `Stephan Hoyer `_. -- New keyword argument ``drop=True`` for :py:meth:`~DataArray.sel`, - :py:meth:`~DataArray.isel` and :py:meth:`~DataArray.squeeze` for dropping - scalar coordinates that arise from indexing. - ``DataArray`` (:issue:`242`). - By `Stephan Hoyer `_. - -- New top-level functions :py:func:`~xarray.full_like`, - :py:func:`~xarray.zeros_like`, and :py:func:`~xarray.ones_like` - By `Guido Imperiale `_. -- Overriding a preexisting attribute with - :py:func:`~xarray.register_dataset_accessor` or - :py:func:`~xarray.register_dataarray_accessor` now issues a warning instead of - raising an error (:issue:`1082`). - By `Stephan Hoyer `_. -- Options for axes sharing between subplots are exposed to - :py:class:`~xarray.plot.FacetGrid` and :py:func:`~xarray.plot.plot`, so axes - sharing can be disabled for polar plots. - By `Bas Hoonhout `_. -- New utility functions :py:func:`~xarray.testing.assert_equal`, - :py:func:`~xarray.testing.assert_identical`, and - :py:func:`~xarray.testing.assert_allclose` for asserting relationships - between xarray objects, designed for use in a pytest test suite. -- ``figsize``, ``size`` and ``aspect`` plot arguments are now supported for all - plots (:issue:`897`). See :ref:`plotting.figsize` for more details. - By `Stephan Hoyer `_ and - `Fabien Maussion `_. -- New :py:meth:`~Dataset.info` method to summarize ``Dataset`` variables - and attributes. The method prints to a buffer (e.g. ``stdout``) with output - similar to what the command line utility ``ncdump -h`` produces (:issue:`1150`). - By `Joe Hamman `_. -- Added the ability write unlimited netCDF dimensions with the ``scipy`` and - ``netcdf4`` backends via the new ``xray.Dataset.encoding`` attribute - or via the ``unlimited_dims`` argument to ``xray.Dataset.to_netcdf``. - By `Joe Hamman `_. -- New :py:meth:`~DataArray.quantile` method to calculate quantiles from - DataArray objects (:issue:`1187`). - By `Joe Hamman `_. - - -Bug fixes -~~~~~~~~~ -- ``groupby_bins`` now restores empty bins by default (:issue:`1019`). - By `Ryan Abernathey `_. - -- Fix issues for dates outside the valid range of pandas timestamps - (:issue:`975`). By `Mathias Hauser `_. - -- Unstacking produced flipped array after stacking decreasing coordinate values - (:issue:`980`). - By `Stephan Hoyer `_. - -- Setting ``dtype`` via the ``encoding`` parameter of ``to_netcdf`` failed if - the encoded dtype was the same as the dtype of the original array - (:issue:`873`). - By `Stephan Hoyer `_. - -- Fix issues with variables where both attributes ``_FillValue`` and - ``missing_value`` are set to ``NaN`` (:issue:`997`). - By `Marco Zühlke `_. - -- ``.where()`` and ``.fillna()`` now preserve attributes (:issue:`1009`). - By `Fabien Maussion `_. - -- Applying :py:func:`broadcast()` to an xarray object based on the dask backend - won't accidentally convert the array from dask to numpy anymore (:issue:`978`). - By `Guido Imperiale `_. - -- ``Dataset.concat()`` now preserves variables order (:issue:`1027`). - By `Fabien Maussion `_. - -- Fixed an issue with pcolormesh (:issue:`781`). A new - ``infer_intervals`` keyword gives control on whether the cell intervals - should be computed or not. - By `Fabien Maussion `_. - -- Grouping over an dimension with non-unique values with ``groupby`` gives - correct groups. - By `Stephan Hoyer `_. - -- Fixed accessing coordinate variables with non-string names from ``.coords``. - By `Stephan Hoyer `_. - -- :py:meth:`~xarray.DataArray.rename` now simultaneously renames the array and - any coordinate with the same name, when supplied via a :py:class:`dict` - (:issue:`1116`). - By `Yves Delley `_. - -- Fixed sub-optimal performance in certain operations with object arrays (:issue:`1121`). - By `Yves Delley `_. - -- Fix ``.groupby(group)`` when ``group`` has datetime dtype (:issue:`1132`). - By `Jonas Sølvsteen `_. - -- Fixed a bug with facetgrid (the ``norm`` keyword was ignored, :issue:`1159`). - By `Fabien Maussion `_. - -- Resolved a concurrency bug that could cause Python to crash when - simultaneously reading and writing netCDF4 files with dask (:issue:`1172`). - By `Stephan Hoyer `_. - -- Fix to make ``.copy()`` actually copy dask arrays, which will be relevant for - future releases of dask in which dask arrays will be mutable (:issue:`1180`). - By `Stephan Hoyer `_. - -- Fix opening NetCDF files with multi-dimensional time variables - (:issue:`1229`). - By `Stephan Hoyer `_. - -Performance improvements -~~~~~~~~~~~~~~~~~~~~~~~~ - -- ``xarray.Dataset.isel_points`` and ``xarray.Dataset.sel_points`` now - use vectorised indexing in numpy and dask (:issue:`1161`), which can - result in several orders of magnitude speedup. - By `Jonathan Chambers `_. - -.. _whats-new.0.8.2: - -v0.8.2 (18 August 2016) ------------------------ - -This release includes a number of bug fixes and minor enhancements. - -Breaking changes -~~~~~~~~~~~~~~~~ - -- :py:func:`~xarray.broadcast` and :py:func:`~xarray.concat` now auto-align - inputs, using ``join=outer``. Previously, these functions raised - ``ValueError`` for non-aligned inputs. - By `Guido Imperiale `_. - -Enhancements -~~~~~~~~~~~~ - -- New documentation on :ref:`panel transition`. By - `Maximilian Roos `_. -- New ``Dataset`` and ``DataArray`` methods :py:meth:`~xarray.Dataset.to_dict` - and :py:meth:`~xarray.Dataset.from_dict` to allow easy conversion between - dictionaries and xarray objects (:issue:`432`). See - :ref:`dictionary IO` for more details. - By `Julia Signell `_. -- Added ``exclude`` and ``indexes`` optional parameters to :py:func:`~xarray.align`, - and ``exclude`` optional parameter to :py:func:`~xarray.broadcast`. - By `Guido Imperiale `_. -- Better error message when assigning variables without dimensions - (:issue:`971`). By `Stephan Hoyer `_. -- Better error message when reindex/align fails due to duplicate index values - (:issue:`956`). By `Stephan Hoyer `_. - -Bug fixes -~~~~~~~~~ - -- Ensure xarray works with h5netcdf v0.3.0 for arrays with ``dtype=str`` - (:issue:`953`). By `Stephan Hoyer `_. -- ``Dataset.__dir__()`` (i.e. the method python calls to get autocomplete - options) failed if one of the dataset's keys was not a string (:issue:`852`). - By `Maximilian Roos `_. -- ``Dataset`` constructor can now take arbitrary objects as values - (:issue:`647`). By `Maximilian Roos `_. -- Clarified ``copy`` argument for :py:meth:`~xarray.DataArray.reindex` and - :py:func:`~xarray.align`, which now consistently always return new xarray - objects (:issue:`927`). -- Fix ``open_mfdataset`` with ``engine='pynio'`` (:issue:`936`). - By `Stephan Hoyer `_. -- ``groupby_bins`` sorted bin labels as strings (:issue:`952`). - By `Stephan Hoyer `_. -- Fix bug introduced by v0.8.0 that broke assignment to datasets when both the - left and right side have the same non-unique index values (:issue:`956`). - -.. _whats-new.0.8.1: - -v0.8.1 (5 August 2016) ----------------------- - -Bug fixes -~~~~~~~~~ - -- Fix bug in v0.8.0 that broke assignment to Datasets with non-unique - indexes (:issue:`943`). By `Stephan Hoyer `_. - -.. _whats-new.0.8.0: - -v0.8.0 (2 August 2016) ----------------------- - -This release includes four months of new features and bug fixes, including -several breaking changes. - -.. _v0.8.0.breaking: - -Breaking changes -~~~~~~~~~~~~~~~~ - -- Dropped support for Python 2.6 (:issue:`855`). -- Indexing on multi-index now drop levels, which is consistent with pandas. - It also changes the name of the dimension / coordinate when the multi-index is - reduced to a single index (:issue:`802`). -- Contour plots no longer add a colorbar per default (:issue:`866`). Filled - contour plots are unchanged. -- ``DataArray.values`` and ``.data`` now always returns an NumPy array-like - object, even for 0-dimensional arrays with object dtype (:issue:`867`). - Previously, ``.values`` returned native Python objects in such cases. To - convert the values of scalar arrays to Python objects, use the ``.item()`` - method. - -Enhancements -~~~~~~~~~~~~ - -- Groupby operations now support grouping over multidimensional variables. A new - method called :py:meth:`~xarray.Dataset.groupby_bins` has also been added to - allow users to specify bins for grouping. The new features are described in - :ref:`groupby.multidim` and :ref:`/examples/multidimensional-coords.ipynb`. - By `Ryan Abernathey `_. - -- DataArray and Dataset method :py:meth:`where` now supports a ``drop=True`` - option that clips coordinate elements that are fully masked. By - `Phillip J. Wolfram `_. - -- New top level :py:func:`merge` function allows for combining variables from - any number of ``Dataset`` and/or ``DataArray`` variables. See :ref:`merge` - for more details. By `Stephan Hoyer `_. - -- :py:meth:`DataArray.resample` and :py:meth:`Dataset.resample` now support the - ``keep_attrs=False`` option that determines whether variable and dataset - attributes are retained in the resampled object. By - `Jeremy McGibbon `_. - -- Better multi-index support in :py:meth:`DataArray.sel`, - :py:meth:`DataArray.loc`, :py:meth:`Dataset.sel` and - :py:meth:`Dataset.loc`, which now behave more closely to pandas and - which also accept dictionaries for indexing based on given level names - and labels (see :ref:`multi-level indexing`). - By `Benoit Bovy `_. - -- New (experimental) decorators :py:func:`~xarray.register_dataset_accessor` and - :py:func:`~xarray.register_dataarray_accessor` for registering custom xarray - extensions without subclassing. They are described in the new documentation - page on :ref:`internals`. By `Stephan Hoyer `_. - -- Round trip boolean datatypes. Previously, writing boolean datatypes to netCDF - formats would raise an error since netCDF does not have a `bool` datatype. - This feature reads/writes a `dtype` attribute to boolean variables in netCDF - files. By `Joe Hamman `_. - -- 2D plotting methods now have two new keywords (`cbar_ax` and `cbar_kwargs`), - allowing more control on the colorbar (:issue:`872`). - By `Fabien Maussion `_. - -- New Dataset method :py:meth:`Dataset.filter_by_attrs`, akin to - ``netCDF4.Dataset.get_variables_by_attributes``, to easily filter - data variables using its attributes. - `Filipe Fernandes `_. - -Bug fixes -~~~~~~~~~ - -- Attributes were being retained by default for some resampling - operations when they should not. With the ``keep_attrs=False`` option, they - will no longer be retained by default. This may be backwards-incompatible - with some scripts, but the attributes may be kept by adding the - ``keep_attrs=True`` option. By - `Jeremy McGibbon `_. - -- Concatenating xarray objects along an axis with a MultiIndex or PeriodIndex - preserves the nature of the index (:issue:`875`). By - `Stephan Hoyer `_. - -- Fixed bug in arithmetic operations on DataArray objects whose dimensions - are numpy structured arrays or recarrays :issue:`861`, :issue:`837`. By - `Maciek Swat `_. - -- ``decode_cf_timedelta`` now accepts arrays with ``ndim`` >1 (:issue:`842`). - This fixes issue :issue:`665`. - `Filipe Fernandes `_. - -- Fix a bug where `xarray.ufuncs` that take two arguments would incorrectly - use to numpy functions instead of dask.array functions (:issue:`876`). By - `Stephan Hoyer `_. - -- Support for pickling functions from ``xarray.ufuncs`` (:issue:`901`). By - `Stephan Hoyer `_. - -- ``Variable.copy(deep=True)`` no longer converts MultiIndex into a base Index - (:issue:`769`). By `Benoit Bovy `_. - -- Fixes for groupby on dimensions with a multi-index (:issue:`867`). By - `Stephan Hoyer `_. - -- Fix printing datasets with unicode attributes on Python 2 (:issue:`892`). By - `Stephan Hoyer `_. - -- Fixed incorrect test for dask version (:issue:`891`). By - `Stephan Hoyer `_. - -- Fixed `dim` argument for `isel_points`/`sel_points` when a `pandas.Index` is - passed. By `Stephan Hoyer `_. - -- :py:func:`~xarray.plot.contour` now plots the correct number of contours - (:issue:`866`). By `Fabien Maussion `_. - -.. _whats-new.0.7.2: - -v0.7.2 (13 March 2016) ----------------------- - -This release includes two new, entirely backwards compatible features and -several bug fixes. - -Enhancements -~~~~~~~~~~~~ - -- New DataArray method :py:meth:`DataArray.dot` for calculating the dot - product of two DataArrays along shared dimensions. By - `Dean Pospisil `_. - -- Rolling window operations on DataArray objects are now supported via a new - :py:meth:`DataArray.rolling` method. For example: - - .. ipython:: - :verbatim: - - In [1]: import xarray as xr - ...: import numpy as np - - In [2]: arr = xr.DataArray(np.arange(0, 7.5, 0.5).reshape(3, 5), dims=("x", "y")) - - In [3]: arr - Out[3]: - - array([[ 0. , 0.5, 1. , 1.5, 2. ], - [ 2.5, 3. , 3.5, 4. , 4.5], - [ 5. , 5.5, 6. , 6.5, 7. ]]) - Coordinates: - * x (x) int64 0 1 2 - * y (y) int64 0 1 2 3 4 - - In [4]: arr.rolling(y=3, min_periods=2).mean() - Out[4]: - - array([[ nan, 0.25, 0.5 , 1. , 1.5 ], - [ nan, 2.75, 3. , 3.5 , 4. ], - [ nan, 5.25, 5.5 , 6. , 6.5 ]]) - Coordinates: - * x (x) int64 0 1 2 - * y (y) int64 0 1 2 3 4 - - See :ref:`comput.rolling` for more details. By - `Joe Hamman `_. - -Bug fixes -~~~~~~~~~ - -- Fixed an issue where plots using pcolormesh and Cartopy axes were being distorted - by the inference of the axis interval breaks. This change chooses not to modify - the coordinate variables when the axes have the attribute ``projection``, allowing - Cartopy to handle the extent of pcolormesh plots (:issue:`781`). By - `Joe Hamman `_. - -- 2D plots now better handle additional coordinates which are not ``DataArray`` - dimensions (:issue:`788`). By `Fabien Maussion `_. - - -.. _whats-new.0.7.1: - -v0.7.1 (16 February 2016) -------------------------- - -This is a bug fix release that includes two small, backwards compatible enhancements. -We recommend that all users upgrade. - -Enhancements -~~~~~~~~~~~~ - -- Numerical operations now return empty objects on no overlapping labels rather - than raising ``ValueError`` (:issue:`739`). -- :py:class:`~pandas.Series` is now supported as valid input to the ``Dataset`` - constructor (:issue:`740`). - -Bug fixes -~~~~~~~~~ - -- Restore checks for shape consistency between data and coordinates in the - DataArray constructor (:issue:`758`). -- Single dimension variables no longer transpose as part of a broader - ``.transpose``. This behavior was causing ``pandas.PeriodIndex`` dimensions - to lose their type (:issue:`749`) -- :py:class:`~xarray.Dataset` labels remain as their native type on ``.to_dataset``. - Previously they were coerced to strings (:issue:`745`) -- Fixed a bug where replacing a ``DataArray`` index coordinate would improperly - align the coordinate (:issue:`725`). -- ``DataArray.reindex_like`` now maintains the dtype of complex numbers when - reindexing leads to NaN values (:issue:`738`). -- ``Dataset.rename`` and ``DataArray.rename`` support the old and new names - being the same (:issue:`724`). -- Fix :py:meth:`~xarray.Dataset.from_dataframe` for DataFrames with Categorical - column and a MultiIndex index (:issue:`737`). -- Fixes to ensure xarray works properly after the upcoming pandas v0.18 and - NumPy v1.11 releases. - -Acknowledgments -~~~~~~~~~~~~~~~ - -The following individuals contributed to this release: - -- Edward Richards -- Maximilian Roos -- Rafael Guedes -- Spencer Hill -- Stephan Hoyer - -.. _whats-new.0.7.0: - -v0.7.0 (21 January 2016) ------------------------- - -This major release includes redesign of :py:class:`~xarray.DataArray` -internals, as well as new methods for reshaping, rolling and shifting -data. It includes preliminary support for :py:class:`pandas.MultiIndex`, -as well as a number of other features and bug fixes, several of which -offer improved compatibility with pandas. - -New name -~~~~~~~~ - -The project formerly known as "xray" is now "xarray", pronounced "x-array"! -This avoids a namespace conflict with the entire field of x-ray science. Renaming -our project seemed like the right thing to do, especially because some -scientists who work with actual x-rays are interested in using this project in -their work. Thanks for your understanding and patience in this transition. You -can now find our documentation and code repository at new URLs: - -- http://xarray.pydata.org -- http://github.com/pydata/xarray/ - -To ease the transition, we have simultaneously released v0.7.0 of both -``xray`` and ``xarray`` on the Python Package Index. These packages are -identical. For now, ``import xray`` still works, except it issues a -deprecation warning. This will be the last xray release. Going forward, we -recommend switching your import statements to ``import xarray as xr``. - -.. _v0.7.0.breaking: - -Breaking changes -~~~~~~~~~~~~~~~~ - -- The internal data model used by ``xray.DataArray`` has been - rewritten to fix several outstanding issues (:issue:`367`, :issue:`634`, - `this stackoverflow report`_). Internally, ``DataArray`` is now implemented - in terms of ``._variable`` and ``._coords`` attributes instead of holding - variables in a ``Dataset`` object. - - This refactor ensures that if a DataArray has the - same name as one of its coordinates, the array and the coordinate no longer - share the same data. - - In practice, this means that creating a DataArray with the same ``name`` as - one of its dimensions no longer automatically uses that array to label the - corresponding coordinate. You will now need to provide coordinate labels - explicitly. Here's the old behavior: - - .. ipython:: - :verbatim: - - In [2]: xray.DataArray([4, 5, 6], dims="x", name="x") - Out[2]: - - array([4, 5, 6]) - Coordinates: - * x (x) int64 4 5 6 - - and the new behavior (compare the values of the ``x`` coordinate): - - .. ipython:: - :verbatim: - - In [2]: xray.DataArray([4, 5, 6], dims="x", name="x") - Out[2]: - - array([4, 5, 6]) - Coordinates: - * x (x) int64 0 1 2 - -- It is no longer possible to convert a DataArray to a Dataset with - ``xray.DataArray.to_dataset`` if it is unnamed. This will now - raise ``ValueError``. If the array is unnamed, you need to supply the - ``name`` argument. - -.. _this stackoverflow report: http://stackoverflow.com/questions/33158558/python-xray-extract-first-and-last-time-value-within-each-month-of-a-timeseries - -Enhancements -~~~~~~~~~~~~ - -- Basic support for :py:class:`~pandas.MultiIndex` coordinates on xray objects, including - indexing, :py:meth:`~DataArray.stack` and :py:meth:`~DataArray.unstack`: - - .. ipython:: - :verbatim: - - In [7]: df = pd.DataFrame({"foo": range(3), "x": ["a", "b", "b"], "y": [0, 0, 1]}) - - In [8]: s = df.set_index(["x", "y"])["foo"] - - In [12]: arr = xray.DataArray(s, dims="z") - - In [13]: arr - Out[13]: - - array([0, 1, 2]) - Coordinates: - * z (z) object ('a', 0) ('b', 0) ('b', 1) - - In [19]: arr.indexes["z"] - Out[19]: - MultiIndex(levels=[[u'a', u'b'], [0, 1]], - labels=[[0, 1, 1], [0, 0, 1]], - names=[u'x', u'y']) - - In [14]: arr.unstack("z") - Out[14]: - - array([[ 0., nan], - [ 1., 2.]]) - Coordinates: - * x (x) object 'a' 'b' - * y (y) int64 0 1 - - In [26]: arr.unstack("z").stack(z=("x", "y")) - Out[26]: - - array([ 0., nan, 1., 2.]) - Coordinates: - * z (z) object ('a', 0) ('a', 1) ('b', 0) ('b', 1) - - See :ref:`reshape.stack` for more details. - - .. warning:: - - xray's MultiIndex support is still experimental, and we have a long to- - do list of desired additions (:issue:`719`), including better display of - multi-index levels when printing a ``Dataset``, and support for saving - datasets with a MultiIndex to a netCDF file. User contributions in this - area would be greatly appreciated. - -- Support for reading GRIB, HDF4 and other file formats via PyNIO_. See - :ref:`io.pynio` for more details. -- Better error message when a variable is supplied with the same name as - one of its dimensions. -- Plotting: more control on colormap parameters (:issue:`642`). ``vmin`` and - ``vmax`` will not be silently ignored anymore. Setting ``center=False`` - prevents automatic selection of a divergent colormap. -- New ``xray.Dataset.shift`` and ``xray.Dataset.roll`` methods - for shifting/rotating datasets or arrays along a dimension: - - .. ipython:: python - :okwarning: - - array = xray.DataArray([5, 6, 7, 8], dims="x") - array.shift(x=2) - array.roll(x=2) - - Notice that ``shift`` moves data independently of coordinates, but ``roll`` - moves both data and coordinates. -- Assigning a ``pandas`` object directly as a ``Dataset`` variable is now permitted. Its - index names correspond to the ``dims`` of the ``Dataset``, and its data is aligned. -- Passing a :py:class:`pandas.DataFrame` or ``pandas.Panel`` to a Dataset constructor - is now permitted. -- New function ``xray.broadcast`` for explicitly broadcasting - ``DataArray`` and ``Dataset`` objects against each other. For example: - - .. ipython:: python - - a = xray.DataArray([1, 2, 3], dims="x") - b = xray.DataArray([5, 6], dims="y") - a - b - a2, b2 = xray.broadcast(a, b) - a2 - b2 - -.. _PyNIO: https://www.pyngl.ucar.edu/Nio.shtml - -Bug fixes -~~~~~~~~~ - -- Fixes for several issues found on ``DataArray`` objects with the same name - as one of their coordinates (see :ref:`v0.7.0.breaking` for more details). -- ``DataArray.to_masked_array`` always returns masked array with mask being an - array (not a scalar value) (:issue:`684`) -- Allows for (imperfect) repr of Coords when underlying index is PeriodIndex (:issue:`645`). -- Fixes for several issues found on ``DataArray`` objects with the same name - as one of their coordinates (see :ref:`v0.7.0.breaking` for more details). -- Attempting to assign a ``Dataset`` or ``DataArray`` variable/attribute using - attribute-style syntax (e.g., ``ds.foo = 42``) now raises an error rather - than silently failing (:issue:`656`, :issue:`714`). -- You can now pass pandas objects with non-numpy dtypes (e.g., ``categorical`` - or ``datetime64`` with a timezone) into xray without an error - (:issue:`716`). - -Acknowledgments -~~~~~~~~~~~~~~~ - -The following individuals contributed to this release: - -- Antony Lee -- Fabien Maussion -- Joe Hamman -- Maximilian Roos -- Stephan Hoyer -- Takeshi Kanmae -- femtotrader - -v0.6.1 (21 October 2015) ------------------------- - -This release contains a number of bug and compatibility fixes, as well -as enhancements to plotting, indexing and writing files to disk. - -Note that the minimum required version of dask for use with xray is now -version 0.6. - -API Changes -~~~~~~~~~~~ - -- The handling of colormaps and discrete color lists for 2D plots in - ``xray.DataArray.plot`` was changed to provide more compatibility - with matplotlib's ``contour`` and ``contourf`` functions (:issue:`538`). - Now discrete lists of colors should be specified using ``colors`` keyword, - rather than ``cmap``. - -Enhancements -~~~~~~~~~~~~ - -- Faceted plotting through ``xray.plot.FacetGrid`` and the - ``xray.plot.plot`` method. See :ref:`plotting.faceting` for more details - and examples. -- ``xray.Dataset.sel`` and ``xray.Dataset.reindex`` now support - the ``tolerance`` argument for controlling nearest-neighbor selection - (:issue:`629`): - - .. ipython:: - :verbatim: - - In [5]: array = xray.DataArray([1, 2, 3], dims="x") - - In [6]: array.reindex(x=[0.9, 1.5], method="nearest", tolerance=0.2) - Out[6]: - - array([ 2., nan]) - Coordinates: - * x (x) float64 0.9 1.5 - - This feature requires pandas v0.17 or newer. -- New ``encoding`` argument in ``xray.Dataset.to_netcdf`` for writing - netCDF files with compression, as described in the new documentation - section on :ref:`io.netcdf.writing_encoded`. -- Add ``xray.Dataset.real`` and ``xray.Dataset.imag`` - attributes to Dataset and DataArray (:issue:`553`). -- More informative error message with ``xray.Dataset.from_dataframe`` - if the frame has duplicate columns. -- xray now uses deterministic names for dask arrays it creates or opens from - disk. This allows xray users to take advantage of dask's nascent support for - caching intermediate computation results. See :issue:`555` for an example. - -Bug fixes -~~~~~~~~~ - -- Forwards compatibility with the latest pandas release (v0.17.0). We were - using some internal pandas routines for datetime conversion, which - unfortunately have now changed upstream (:issue:`569`). -- Aggregation functions now correctly skip ``NaN`` for data for ``complex128`` - dtype (:issue:`554`). -- Fixed indexing 0d arrays with unicode dtype (:issue:`568`). -- ``xray.DataArray.name`` and Dataset keys must be a string or None to - be written to netCDF (:issue:`533`). -- ``xray.DataArray.where`` now uses dask instead of numpy if either the - array or ``other`` is a dask array. Previously, if ``other`` was a numpy array - the method was evaluated eagerly. -- Global attributes are now handled more consistently when loading remote - datasets using ``engine='pydap'`` (:issue:`574`). -- It is now possible to assign to the ``.data`` attribute of DataArray objects. -- ``coordinates`` attribute is now kept in the encoding dictionary after - decoding (:issue:`610`). -- Compatibility with numpy 1.10 (:issue:`617`). - -Acknowledgments -~~~~~~~~~~~~~~~ - -The following individuals contributed to this release: - -- Ryan Abernathey -- Pete Cable -- Clark Fitzgerald -- Joe Hamman -- Stephan Hoyer -- Scott Sinclair - -v0.6.0 (21 August 2015) ------------------------ - -This release includes numerous bug fixes and enhancements. Highlights -include the introduction of a plotting module and the new Dataset and DataArray -methods ``xray.Dataset.isel_points``, ``xray.Dataset.sel_points``, -``xray.Dataset.where`` and ``xray.Dataset.diff``. There are no -breaking changes from v0.5.2. - -Enhancements -~~~~~~~~~~~~ - -- Plotting methods have been implemented on DataArray objects - ``xray.DataArray.plot`` through integration with matplotlib - (:issue:`185`). For an introduction, see :ref:`plotting`. -- Variables in netCDF files with multiple missing values are now decoded as NaN - after issuing a warning if open_dataset is called with mask_and_scale=True. -- We clarified our rules for when the result from an xray operation is a copy - vs. a view (see :ref:`copies_vs_views` for more details). -- Dataset variables are now written to netCDF files in order of appearance - when using the netcdf4 backend (:issue:`479`). - -- Added ``xray.Dataset.isel_points`` and ``xray.Dataset.sel_points`` - to support pointwise indexing of Datasets and DataArrays (:issue:`475`). - - .. ipython:: - :verbatim: - - In [1]: da = xray.DataArray( - ...: np.arange(56).reshape((7, 8)), - ...: coords={"x": list("abcdefg"), "y": 10 * np.arange(8)}, - ...: dims=["x", "y"], - ...: ) - - In [2]: da - Out[2]: - - array([[ 0, 1, 2, 3, 4, 5, 6, 7], - [ 8, 9, 10, 11, 12, 13, 14, 15], - [16, 17, 18, 19, 20, 21, 22, 23], - [24, 25, 26, 27, 28, 29, 30, 31], - [32, 33, 34, 35, 36, 37, 38, 39], - [40, 41, 42, 43, 44, 45, 46, 47], - [48, 49, 50, 51, 52, 53, 54, 55]]) - Coordinates: - * y (y) int64 0 10 20 30 40 50 60 70 - * x (x) |S1 'a' 'b' 'c' 'd' 'e' 'f' 'g' - - # we can index by position along each dimension - In [3]: da.isel_points(x=[0, 1, 6], y=[0, 1, 0], dim="points") - Out[3]: - - array([ 0, 9, 48]) - Coordinates: - y (points) int64 0 10 0 - x (points) |S1 'a' 'b' 'g' - * points (points) int64 0 1 2 - - # or equivalently by label - In [9]: da.sel_points(x=["a", "b", "g"], y=[0, 10, 0], dim="points") - Out[9]: - - array([ 0, 9, 48]) - Coordinates: - y (points) int64 0 10 0 - x (points) |S1 'a' 'b' 'g' - * points (points) int64 0 1 2 - -- New ``xray.Dataset.where`` method for masking xray objects according - to some criteria. This works particularly well with multi-dimensional data: - - .. ipython:: python - - ds = xray.Dataset(coords={"x": range(100), "y": range(100)}) - ds["distance"] = np.sqrt(ds.x ** 2 + ds.y ** 2) - - @savefig where_example.png width=4in height=4in - ds.distance.where(ds.distance < 100).plot() - -- Added new methods ``xray.DataArray.diff`` and ``xray.Dataset.diff`` - for finite difference calculations along a given axis. - -- New ``xray.DataArray.to_masked_array`` convenience method for - returning a numpy.ma.MaskedArray. - - .. ipython:: python - - da = xray.DataArray(np.random.random_sample(size=(5, 4))) - da.where(da < 0.5) - da.where(da < 0.5).to_masked_array(copy=True) - -- Added new flag "drop_variables" to ``xray.open_dataset`` for - excluding variables from being parsed. This may be useful to drop - variables with problems or inconsistent values. - -Bug fixes -~~~~~~~~~ - -- Fixed aggregation functions (e.g., sum and mean) on big-endian arrays when - bottleneck is installed (:issue:`489`). -- Dataset aggregation functions dropped variables with unsigned integer dtype - (:issue:`505`). -- ``.any()`` and ``.all()`` were not lazy when used on xray objects containing - dask arrays. -- Fixed an error when attempting to saving datetime64 variables to netCDF - files when the first element is ``NaT`` (:issue:`528`). -- Fix pickle on DataArray objects (:issue:`515`). -- Fixed unnecessary coercion of float64 to float32 when using netcdf3 and - netcdf4_classic formats (:issue:`526`). - -v0.5.2 (16 July 2015) ---------------------- - -This release contains bug fixes, several additional options for opening and -saving netCDF files, and a backwards incompatible rewrite of the advanced -options for ``xray.concat``. - -Backwards incompatible changes -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- The optional arguments ``concat_over`` and ``mode`` in ``xray.concat`` have - been removed and replaced by ``data_vars`` and ``coords``. The new arguments are both - more easily understood and more robustly implemented, and allowed us to fix a bug - where ``concat`` accidentally loaded data into memory. If you set values for - these optional arguments manually, you will need to update your code. The default - behavior should be unchanged. - -Enhancements -~~~~~~~~~~~~ - -- ``xray.open_mfdataset`` now supports a ``preprocess`` argument for - preprocessing datasets prior to concatenaton. This is useful if datasets - cannot be otherwise merged automatically, e.g., if the original datasets - have conflicting index coordinates (:issue:`443`). -- ``xray.open_dataset`` and ``xray.open_mfdataset`` now use a - global thread lock by default for reading from netCDF files with dask. This - avoids possible segmentation faults for reading from netCDF4 files when HDF5 - is not configured properly for concurrent access (:issue:`444`). -- Added support for serializing arrays of complex numbers with `engine='h5netcdf'`. -- The new ``xray.save_mfdataset`` function allows for saving multiple - datasets to disk simultaneously. This is useful when processing large datasets - with dask.array. For example, to save a dataset too big to fit into memory - to one file per year, we could write: - - .. ipython:: - :verbatim: - - In [1]: years, datasets = zip(*ds.groupby("time.year")) - - In [2]: paths = ["%s.nc" % y for y in years] - - In [3]: xray.save_mfdataset(datasets, paths) - -Bug fixes -~~~~~~~~~ - -- Fixed ``min``, ``max``, ``argmin`` and ``argmax`` for arrays with string or - unicode types (:issue:`453`). -- ``xray.open_dataset`` and ``xray.open_mfdataset`` support - supplying chunks as a single integer. -- Fixed a bug in serializing scalar datetime variable to netCDF. -- Fixed a bug that could occur in serialization of 0-dimensional integer arrays. -- Fixed a bug where concatenating DataArrays was not always lazy (:issue:`464`). -- When reading datasets with h5netcdf, bytes attributes are decoded to strings. - This allows conventions decoding to work properly on Python 3 (:issue:`451`). - -v0.5.1 (15 June 2015) ---------------------- - -This minor release fixes a few bugs and an inconsistency with pandas. It also -adds the ``pipe`` method, copied from pandas. - -Enhancements -~~~~~~~~~~~~ - -- Added ``xray.Dataset.pipe``, replicating the `new pandas method`_ in version - 0.16.2. See :ref:`transforming datasets` for more details. -- ``xray.Dataset.assign`` and ``xray.Dataset.assign_coords`` - now assign new variables in sorted (alphabetical) order, mirroring the - behavior in pandas. Previously, the order was arbitrary. - -.. _new pandas method: http://pandas.pydata.org/pandas-docs/version/0.16.2/whatsnew.html#pipe - -Bug fixes -~~~~~~~~~ - -- ``xray.concat`` fails in an edge case involving identical coordinate variables (:issue:`425`) -- We now decode variables loaded from netCDF3 files with the scipy engine using native - endianness (:issue:`416`). This resolves an issue when aggregating these arrays with - bottleneck installed. - -v0.5 (1 June 2015) ------------------- - -Highlights -~~~~~~~~~~ - -The headline feature in this release is experimental support for out-of-core -computing (data that doesn't fit into memory) with :doc:`user-guide/dask`. This includes a new -top-level function ``xray.open_mfdataset`` that makes it easy to open -a collection of netCDF (using dask) as a single ``xray.Dataset`` object. For -more on dask, read the `blog post introducing xray + dask`_ and the new -documentation section :doc:`user-guide/dask`. - -.. _blog post introducing xray + dask: https://www.anaconda.com/blog/developer-blog/xray-dask-out-core-labeled-arrays-python/ - -Dask makes it possible to harness parallelism and manipulate gigantic datasets -with xray. It is currently an optional dependency, but it may become required -in the future. - -Backwards incompatible changes -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- The logic used for choosing which variables are concatenated with - ``xray.concat`` has changed. Previously, by default any variables - which were equal across a dimension were not concatenated. This lead to some - surprising behavior, where the behavior of groupby and concat operations - could depend on runtime values (:issue:`268`). For example: - - .. ipython:: - :verbatim: - - In [1]: ds = xray.Dataset({"x": 0}) - - In [2]: xray.concat([ds, ds], dim="y") - Out[2]: - - Dimensions: () - Coordinates: - *empty* - Data variables: - x int64 0 - - Now, the default always concatenates data variables: - + What's New + ========== + .. ipython:: python :suppress: - - ds = xray.Dataset({"x": 0}) - - .. ipython:: python - - xray.concat([ds, ds], dim="y") - - To obtain the old behavior, supply the argument ``concat_over=[]``. - -Enhancements -~~~~~~~~~~~~ - -- New ``xray.Dataset.to_array`` and enhanced - ``xray.DataArray.to_dataset`` methods make it easy to switch back - and forth between arrays and datasets: - - .. ipython:: python - - ds = xray.Dataset( - {"a": 1, "b": ("x", [1, 2, 3])}, - coords={"c": 42}, - attrs={"Conventions": "None"}, - ) - ds.to_array() - ds.to_array().to_dataset(dim="variable") - -- New ``xray.Dataset.fillna`` method to fill missing values, modeled - off the pandas method of the same name: - - .. ipython:: python - - array = xray.DataArray([np.nan, 1, np.nan, 3], dims="x") - array.fillna(0) - - ``fillna`` works on both ``Dataset`` and ``DataArray`` objects, and uses - index based alignment and broadcasting like standard binary operations. It - also can be applied by group, as illustrated in - :ref:`/examples/weather-data.ipynb#Fill-missing-values-with-climatology`. -- New ``xray.Dataset.assign`` and ``xray.Dataset.assign_coords`` - methods patterned off the new :py:meth:`DataFrame.assign ` - method in pandas: - - .. ipython:: python - - ds = xray.Dataset({"y": ("x", [1, 2, 3])}) - ds.assign(z=lambda ds: ds.y ** 2) - ds.assign_coords(z=("x", ["a", "b", "c"])) - - These methods return a new Dataset (or DataArray) with updated data or - coordinate variables. -- ``xray.Dataset.sel`` now supports the ``method`` parameter, which works - like the paramter of the same name on ``xray.Dataset.reindex``. It - provides a simple interface for doing nearest-neighbor interpolation: - - .. use verbatim because I can't seem to install pandas 0.16.1 on RTD :( - - .. ipython:: + + import numpy as np + import pandas as pd + import xarray as xray + import xarray + import xarray as xr + + np.random.seed(123456) + + + .. _whats-new.0.19.1: + + v0.19.1 (unreleased) + --------------------- + + New Features + ~~~~~~~~~~~~ + + + Breaking changes + ~~~~~~~~~~~~~~~~ + + + Deprecations + ~~~~~~~~~~~~ + + + Bug fixes + ~~~~~~~~~ + + + Documentation + ~~~~~~~~~~~~~ + + + Internal Changes + ~~~~~~~~~~~~~~~~ + + .. _whats-new.0.19.0: + + v0.19.0 (23 July 2021) + ---------------------- + + This release brings improvements to plotting of categorical data, the ability to specify how attributes + are combined in xarray operations, a new high-level :py:func:`unify_chunks` function, as well as various + deprecations, bug fixes, and minor improvements. + + + Many thanks to the 29 contributors to this release!: + + Andrew Williams, Augustus, Aureliana Barghini, Benoit Bovy, crusaderky, Deepak Cherian, ellesmith88, + Elliott Sales de Andrade, Giacomo Caria, github-actions[bot], Illviljan, Joeperdefloep, joooeey, Julia Kent, + Julius Busecke, keewis, Mathias Hauser, Matthias Göbel, Mattia Almansi, Maximilian Roos, Peter Andreas Entschev, + Ray Bell, Sander, Santiago Soler, Sebastian, Spencer Clark, Stephan Hoyer, Thomas Hirtz, Thomas Nicholas. + + New Features + ~~~~~~~~~~~~ + - Allow passing argument ``missing_dims`` to :py:meth:`Variable.transpose` and :py:meth:`Dataset.transpose` + (:issue:`5550`, :pull:`5586`) + By `Giacomo Caria `_. + - Allow passing a dictionary as coords to a :py:class:`DataArray` (:issue:`5527`, + reverts :pull:`1539`, which had deprecated this due to python's inconsistent ordering in earlier versions). + By `Sander van Rijn `_. + - Added :py:meth:`Dataset.coarsen.construct`, :py:meth:`DataArray.coarsen.construct` (:issue:`5454`, :pull:`5475`). + By `Deepak Cherian `_. + - Xarray now uses consolidated metadata by default when writing and reading Zarr + stores (:issue:`5251`). + By `Stephan Hoyer `_. + - New top-level function :py:func:`unify_chunks`. + By `Mattia Almansi `_. + - Allow assigning values to a subset of a dataset using positional or label-based + indexing (:issue:`3015`, :pull:`5362`). + By `Matthias Göbel `_. + - Attempting to reduce a weighted object over missing dimensions now raises an error (:pull:`5362`). + By `Mattia Almansi `_. + - Add ``.sum`` to :py:meth:`~xarray.DataArray.rolling_exp` and + :py:meth:`~xarray.Dataset.rolling_exp` for exponentially weighted rolling + sums. These require numbagg 0.2.1; + (:pull:`5178`). + By `Maximilian Roos `_. + - :py:func:`xarray.cov` and :py:func:`xarray.corr` now lazily check for missing + values if inputs are dask arrays (:issue:`4804`, :pull:`5284`). + By `Andrew Williams `_. + - Attempting to ``concat`` list of elements that are not all ``Dataset`` or all ``DataArray`` now raises an error (:issue:`5051`, :pull:`5425`). + By `Thomas Hirtz `_. + - allow passing a function to ``combine_attrs`` (:pull:`4896`). + By `Justus Magin `_. + - Allow plotting categorical data (:pull:`5464`). + By `Jimmy Westling `_. + - Allow removal of the coordinate attribute ``coordinates`` on variables by setting ``.attrs['coordinates']= None`` + (:issue:`5510`). + By `Elle Smith `_. + - Added :py:meth:`DataArray.to_numpy`, :py:meth:`DataArray.as_numpy`, and :py:meth:`Dataset.as_numpy`. (:pull:`5568`). + By `Tom Nicholas `_. + - Units in plot labels are now automatically inferred from wrapped :py:meth:`pint.Quantity` arrays. (:pull:`5561`). + By `Tom Nicholas `_. + + Breaking changes + ~~~~~~~~~~~~~~~~ + + - The default ``mode`` for :py:meth:`Dataset.to_zarr` when ``region`` is set + has changed to the new ``mode="r+"``, which only allows for overriding + pre-existing array values. This is a safer default than the prior ``mode="a"``, + and allows for higher performance writes (:pull:`5252`). + By `Stephan Hoyer `_. + - The main parameter to :py:func:`combine_by_coords` is renamed to `data_objects` instead + of `datasets` so anyone calling this method using a named parameter will need to update + the name accordingly (:issue:`3248`, :pull:`4696`). + By `Augustus Ijams `_. + + Deprecations + ~~~~~~~~~~~~ + + - Removed the deprecated ``dim`` kwarg to :py:func:`DataArray.integrate` (:pull:`5630`) + - Removed the deprecated ``keep_attrs`` kwarg to :py:func:`DataArray.rolling` (:pull:`5630`) + - Removed the deprecated ``keep_attrs`` kwarg to :py:func:`DataArray.coarsen` (:pull:`5630`) + - Completed deprecation of passing an ``xarray.DataArray`` to :py:func:`Variable` - will now raise a ``TypeError`` (:pull:`5630`) + + Bug fixes + ~~~~~~~~~ + - Fix a minor incompatibility between partial datetime string indexing with a + :py:class:`CFTimeIndex` and upcoming pandas version 1.3.0 (:issue:`5356`, + :pull:`5359`). + By `Spencer Clark `_. + - Fix 1-level multi-index incorrectly converted to single index (:issue:`5384`, + :pull:`5385`). + By `Benoit Bovy `_. + - Don't cast a duck array in a coordinate to :py:class:`numpy.ndarray` in + :py:meth:`DataArray.differentiate` (:pull:`5408`) + By `Justus Magin `_. + - Fix the ``repr`` of :py:class:`Variable` objects with ``display_expand_data=True`` + (:pull:`5406`) + By `Justus Magin `_. + - Plotting a pcolormesh with ``xscale="log"`` and/or ``yscale="log"`` works as + expected after improving the way the interval breaks are generated (:issue:`5333`). + By `Santiago Soler `_ + - :py:func:`combine_by_coords` can now handle combining a list of unnamed + ``DataArray`` as input (:issue:`3248`, :pull:`4696`). + By `Augustus Ijams `_. + + + Internal Changes + ~~~~~~~~~~~~~~~~ + - Run CI on the first & last python versions supported only; currently 3.7 & 3.9. + (:pull:`5433`) + By `Maximilian Roos `_. + - Publish test results & timings on each PR. + (:pull:`5537`) + By `Maximilian Roos `_. + - Explicit indexes refactor: add a ``xarray.Index.query()`` method in which + one may eventually provide a custom implementation of label-based data + selection (not ready yet for public use). Also refactor the internal, + pandas-specific implementation into ``PandasIndex.query()`` and + ``PandasMultiIndex.query()`` (:pull:`5322`). + By `Benoit Bovy `_. + + .. _whats-new.0.18.2: + + v0.18.2 (19 May 2021) + --------------------- + + This release reverts a regression in xarray's unstacking of dask-backed arrays. + + .. _whats-new.0.18.1: + + v0.18.1 (18 May 2021) + --------------------- + + This release is intended as a small patch release to be compatible with the new + 2021.5.0 ``dask.distributed`` release. It also includes a new + ``drop_duplicates`` method, some documentation improvements, the beginnings of + our internal Index refactoring, and some bug fixes. + + Thank you to all 16 contributors! + + Anderson Banihirwe, Andrew, Benoit Bovy, Brewster Malevich, Giacomo Caria, + Illviljan, James Bourbeau, Keewis, Maximilian Roos, Ravin Kumar, Stephan Hoyer, + Thomas Nicholas, Tom Nicholas, Zachary Moon. + + New Features + ~~~~~~~~~~~~ + - Implement :py:meth:`DataArray.drop_duplicates` + to remove duplicate dimension values (:pull:`5239`). + By `Andrew Huang `_. + - Allow passing ``combine_attrs`` strategy names to the ``keep_attrs`` parameter of + :py:func:`apply_ufunc` (:pull:`5041`) + By `Justus Magin `_. + - :py:meth:`Dataset.interp` now allows interpolation with non-numerical datatypes, + such as booleans, instead of dropping them. (:issue:`4761` :pull:`5008`). + By `Jimmy Westling `_. + - Raise more informative error when decoding time variables with invalid reference dates. + (:issue:`5199`, :pull:`5288`). By `Giacomo Caria `_. + + + Bug fixes + ~~~~~~~~~ + - Opening netCDF files from a path that doesn't end in ``.nc`` without supplying + an explicit ``engine`` works again (:issue:`5295`), fixing a bug introduced in + 0.18.0. + By `Stephan Hoyer `_ + + Documentation + ~~~~~~~~~~~~~ + - Clean up and enhance docstrings for the :py:class:`DataArray.plot` and ``Dataset.plot.*`` + families of methods (:pull:`5285`). + By `Zach Moon `_. + + - Explanation of deprecation cycles and how to implement them added to contributors + guide. (:pull:`5289`) + By `Tom Nicholas `_. + + + Internal Changes + ~~~~~~~~~~~~~~~~ + + - Explicit indexes refactor: add an ``xarray.Index`` base class and + ``Dataset.xindexes`` / ``DataArray.xindexes`` properties. Also rename + ``PandasIndexAdapter`` to ``PandasIndex``, which now inherits from + ``xarray.Index`` (:pull:`5102`). + By `Benoit Bovy `_. + - Replace ``SortedKeysDict`` with python's ``dict``, given dicts are now ordered. + By `Maximilian Roos `_. + - Updated the release guide for developers. Now accounts for actions that are automated via github + actions. (:pull:`5274`). + By `Tom Nicholas `_. + + .. _whats-new.0.18.0: + + v0.18.0 (6 May 2021) + -------------------- + + This release brings a few important performance improvements, a wide range of + usability upgrades, lots of bug fixes, and some new features. These include + a plugin API to add backend engines, a new theme for the documentation, + curve fitting methods, and several new plotting functions. + + Many thanks to the 38 contributors to this release: Aaron Spring, Alessandro Amici, + Alex Marandon, Alistair Miles, Ana Paula Krelling, Anderson Banihirwe, Aureliana Barghini, + Baudouin Raoult, Benoit Bovy, Blair Bonnett, David Trémouilles, Deepak Cherian, + Gabriel Medeiros Abrahão, Giacomo Caria, Hauke Schulz, Illviljan, Mathias Hauser, Matthias Bussonnier, + Mattia Almansi, Maximilian Roos, Ray Bell, Richard Kleijn, Ryan Abernathey, Sam Levang, Spencer Clark, + Spencer Jones, Tammas Loughran, Tobias Kölling, Todd, Tom Nicholas, Tom White, Victor Negîrneac, + Xianxiang Li, Zeb Nicholls, crusaderky, dschwoerer, johnomotani, keewis + + + New Features + ~~~~~~~~~~~~ + + - apply ``combine_attrs`` on data variables and coordinate variables when concatenating + and merging datasets and dataarrays (:pull:`4902`). + By `Justus Magin `_. + - Add :py:meth:`Dataset.to_pandas` (:pull:`5247`) + By `Giacomo Caria `_. + - Add :py:meth:`DataArray.plot.surface` which wraps matplotlib's `plot_surface` to make + surface plots (:issue:`2235` :issue:`5084` :pull:`5101`). + By `John Omotani `_. + - Allow passing multiple arrays to :py:meth:`Dataset.__setitem__` (:pull:`5216`). + By `Giacomo Caria `_. + - Add 'cumulative' option to :py:meth:`Dataset.integrate` and + :py:meth:`DataArray.integrate` so that result is a cumulative integral, like + :py:func:`scipy.integrate.cumulative_trapezoidal` (:pull:`5153`). + By `John Omotani `_. + - Add ``safe_chunks`` option to :py:meth:`Dataset.to_zarr` which allows overriding + checks made to ensure Dask and Zarr chunk compatibility (:issue:`5056`). + By `Ryan Abernathey `_ + - Add :py:meth:`Dataset.query` and :py:meth:`DataArray.query` which enable indexing + of datasets and data arrays by evaluating query expressions against the values of the + data variables (:pull:`4984`). + By `Alistair Miles `_. + - Allow passing ``combine_attrs`` to :py:meth:`Dataset.merge` (:pull:`4895`). + By `Justus Magin `_. + - Support for `dask.graph_manipulation + `_ (requires dask >=2021.3) + By `Guido Imperiale `_ + - Add :py:meth:`Dataset.plot.streamplot` for streamplot plots with :py:class:`Dataset` + variables (:pull:`5003`). + By `John Omotani `_. + - Many of the arguments for the :py:attr:`DataArray.str` methods now support + providing an array-like input. In this case, the array provided to the + arguments is broadcast against the original array and applied elementwise. + - :py:attr:`DataArray.str` now supports ``+``, ``*``, and ``%`` operators. These + behave the same as they do for :py:class:`str`, except that they follow + array broadcasting rules. + - A large number of new :py:attr:`DataArray.str` methods were implemented, + :py:meth:`DataArray.str.casefold`, :py:meth:`DataArray.str.cat`, + :py:meth:`DataArray.str.extract`, :py:meth:`DataArray.str.extractall`, + :py:meth:`DataArray.str.findall`, :py:meth:`DataArray.str.format`, + :py:meth:`DataArray.str.get_dummies`, :py:meth:`DataArray.str.islower`, + :py:meth:`DataArray.str.join`, :py:meth:`DataArray.str.normalize`, + :py:meth:`DataArray.str.partition`, :py:meth:`DataArray.str.rpartition`, + :py:meth:`DataArray.str.rsplit`, and :py:meth:`DataArray.str.split`. + A number of these methods allow for splitting or joining the strings in an + array. (:issue:`4622`) + By `Todd Jennings `_ + - Thanks to the new pluggable backend infrastructure external packages may now + use the ``xarray.backends`` entry point to register additional engines to be used in + :py:func:`open_dataset`, see the documentation in :ref:`add_a_backend` + (:issue:`4309`, :issue:`4803`, :pull:`4989`, :pull:`4810` and many others). + The backend refactor has been sponsored with the "Essential Open Source Software for Science" + grant from the `Chan Zuckerberg Initiative `_ and + developed by `B-Open `_. + By `Aureliana Barghini `_ and `Alessandro Amici `_. + - :py:attr:`~core.accessor_dt.DatetimeAccessor.date` added (:issue:`4983`, :pull:`4994`). + By `Hauke Schulz `_. + - Implement ``__getitem__`` for both :py:class:`~core.groupby.DatasetGroupBy` and + :py:class:`~core.groupby.DataArrayGroupBy`, inspired by pandas' + :py:meth:`~pandas.core.groupby.GroupBy.get_group`. + By `Deepak Cherian `_. + - Switch the tutorial functions to use `pooch `_ + (which is now a optional dependency) and add :py:func:`tutorial.open_rasterio` as a + way to open example rasterio files (:issue:`3986`, :pull:`4102`, :pull:`5074`). + By `Justus Magin `_. + - Add typing information to unary and binary arithmetic operators operating on + :py:class:`Dataset`, :py:class:`DataArray`, :py:class:`Variable`, + :py:class:`~core.groupby.DatasetGroupBy` or + :py:class:`~core.groupby.DataArrayGroupBy` (:pull:`4904`). + By `Richard Kleijn `_. + - Add a ``combine_attrs`` parameter to :py:func:`open_mfdataset` (:pull:`4971`). + By `Justus Magin `_. + - Enable passing arrays with a subset of dimensions to + :py:meth:`DataArray.clip` & :py:meth:`Dataset.clip`; these methods now use + :py:func:`xarray.apply_ufunc`; (:pull:`5184`). + By `Maximilian Roos `_. + - Disable the `cfgrib` backend if the `eccodes` library is not installed (:pull:`5083`). + By `Baudouin Raoult `_. + - Added :py:meth:`DataArray.curvefit` and :py:meth:`Dataset.curvefit` for general curve fitting applications. (:issue:`4300`, :pull:`4849`) + By `Sam Levang `_. + - Add options to control expand/collapse of sections in display of Dataset and + DataArray. The function :py:func:`set_options` now takes keyword aguments + ``display_expand_attrs``, ``display_expand_coords``, ``display_expand_data``, + ``display_expand_data_vars``, all of which can be one of ``True`` to always + expand, ``False`` to always collapse, or ``default`` to expand unless over a + pre-defined limit (:pull:`5126`). + By `Tom White `_. + - Significant speedups in :py:meth:`Dataset.interp` and :py:meth:`DataArray.interp`. + (:issue:`4739`, :pull:`4740`). + By `Deepak Cherian `_. + - Prevent passing `concat_dim` to :py:func:`xarray.open_mfdataset` when + `combine='by_coords'` is specified, which should never have been possible (as + :py:func:`xarray.combine_by_coords` has no `concat_dim` argument to pass to). + Also removes unneeded internal reordering of datasets in + :py:func:`xarray.open_mfdataset` when `combine='by_coords'` is specified. + Fixes (:issue:`5230`). + By `Tom Nicholas `_. + - Implement ``__setitem__`` for ``xarray.core.indexing.DaskIndexingAdapter`` if + dask version supports item assignment. (:issue:`5171`, :pull:`5174`) + By `Tammas Loughran `_. + + Breaking changes + ~~~~~~~~~~~~~~~~ + - The minimum versions of some dependencies were changed: + + ============ ====== ==== + Package Old New + ============ ====== ==== + boto3 1.12 1.13 + cftime 1.0 1.1 + dask 2.11 2.15 + distributed 2.11 2.15 + matplotlib 3.1 3.2 + numba 0.48 0.49 + ============ ====== ==== + + - :py:func:`open_dataset` and :py:func:`open_dataarray` now accept only the first argument + as positional, all others need to be passed are keyword arguments. This is part of the + refactor to support external backends (:issue:`4309`, :pull:`4989`). + By `Alessandro Amici `_. + - Functions that are identities for 0d data return the unchanged data + if axis is empty. This ensures that Datasets where some variables do + not have the averaged dimensions are not accidentially changed + (:issue:`4885`, :pull:`5207`). + By `David Schwörer `_. + - :py:attr:`DataArray.coarsen` and :py:attr:`Dataset.coarsen` no longer support passing ``keep_attrs`` + via its constructor. Pass ``keep_attrs`` via the applied function, i.e. use + ``ds.coarsen(...).mean(keep_attrs=False)`` instead of ``ds.coarsen(..., keep_attrs=False).mean()``. + Further, coarsen now keeps attributes per default (:pull:`5227`). + By `Mathias Hauser `_. + - switch the default of the :py:func:`merge` ``combine_attrs`` parameter to + ``"override"``. This will keep the current behavior for merging the ``attrs`` of + variables but stop dropping the ``attrs`` of the main objects (:pull:`4902`). + By `Justus Magin `_. + + Deprecations + ~~~~~~~~~~~~ + + - Warn when passing `concat_dim` to :py:func:`xarray.open_mfdataset` when + `combine='by_coords'` is specified, which should never have been possible (as + :py:func:`xarray.combine_by_coords` has no `concat_dim` argument to pass to). + Also removes unneeded internal reordering of datasets in + :py:func:`xarray.open_mfdataset` when `combine='by_coords'` is specified. + Fixes (:issue:`5230`), via (:pull:`5231`, :pull:`5255`). + By `Tom Nicholas `_. + - The `lock` keyword argument to :py:func:`open_dataset` and :py:func:`open_dataarray` is now + a backend specific option. It will give a warning if passed to a backend that doesn't support it + instead of being silently ignored. From the next version it will raise an error. + This is part of the refactor to support external backends (:issue:`5073`). + By `Tom Nicholas `_ and `Alessandro Amici `_. + + + Bug fixes + ~~~~~~~~~ + - Properly support :py:meth:`DataArray.ffill`, :py:meth:`DataArray.bfill`, :py:meth:`Dataset.ffill`, :py:meth:`Dataset.bfill` along chunked dimensions. + (:issue:`2699`). + By `Deepak Cherian `_. + - Fix 2d plot failure for certain combinations of dimensions when `x` is 1d and `y` is + 2d (:issue:`5097`, :pull:`5099`). + By `John Omotani `_. + - Ensure standard calendar times encoded with large values (i.e. greater than + approximately 292 years), can be decoded correctly without silently overflowing + (:pull:`5050`). This was a regression in xarray 0.17.0. + By `Zeb Nicholls `_. + - Added support for `numpy.bool_` attributes in roundtrips using `h5netcdf` engine with `invalid_netcdf=True` [which casts `bool`s to `numpy.bool_`] (:issue:`4981`, :pull:`4986`). + By `Victor Negîrneac `_. + - Don't allow passing ``axis`` to :py:meth:`Dataset.reduce` methods (:issue:`3510`, :pull:`4940`). + By `Justus Magin `_. + - Decode values as signed if attribute `_Unsigned = "false"` (:issue:`4954`) + By `Tobias Kölling `_. + - Keep coords attributes when interpolating when the indexer is not a Variable. (:issue:`4239`, :issue:`4839` :pull:`5031`) + By `Jimmy Westling `_. + - Ensure standard calendar dates encoded with a calendar attribute with some or + all uppercase letters can be decoded or encoded to or from + ``np.datetime64[ns]`` dates with or without ``cftime`` installed + (:issue:`5093`, :pull:`5180`). + By `Spencer Clark `_. + - Warn on passing ``keep_attrs`` to ``resample`` and ``rolling_exp`` as they are ignored, pass ``keep_attrs`` + to the applied function instead (:pull:`5265`). + By `Mathias Hauser `_. + + Documentation + ~~~~~~~~~~~~~ + - New section on :ref:`add_a_backend` in the "Internals" chapter aimed to backend developers + (:issue:`4803`, :pull:`4810`). + By `Aureliana Barghini `_. + - Add :py:meth:`Dataset.polyfit` and :py:meth:`DataArray.polyfit` under "See also" in + the docstrings of :py:meth:`Dataset.polyfit` and :py:meth:`DataArray.polyfit` + (:issue:`5016`, :pull:`5020`). + By `Aaron Spring `_. + - New sphinx theme & rearrangement of the docs (:pull:`4835`). + By `Anderson Banihirwe `_. + + Internal Changes + ~~~~~~~~~~~~~~~~ + - Enable displaying mypy error codes and ignore only specific error codes using + ``# type: ignore[error-code]`` (:pull:`5096`). + By `Mathias Hauser `_. + - Replace uses of ``raises_regex`` with the more standard + ``pytest.raises(Exception, match="foo")``; + (:pull:`5188`), (:pull:`5191`). + By `Maximilian Roos `_. + + .. _whats-new.0.17.0: + + v0.17.0 (24 Feb 2021) + --------------------- + + This release brings a few important performance improvements, a wide range of + usability upgrades, lots of bug fixes, and some new features. These include + better ``cftime`` support, a new quiver plot, better ``unstack`` performance, + more efficient memory use in rolling operations, and some python packaging + improvements. We also have a few documentation improvements (and more planned!). + + Many thanks to the 36 contributors to this release: Alessandro Amici, Anderson + Banihirwe, Aureliana Barghini, Ayrton Bourn, Benjamin Bean, Blair Bonnett, Chun + Ho Chow, DWesl, Daniel Mesejo-León, Deepak Cherian, Eric Keenan, Illviljan, Jens + Hedegaard Nielsen, Jody Klymak, Julien Seguinot, Julius Busecke, Kai Mühlbauer, + Leif Denby, Martin Durant, Mathias Hauser, Maximilian Roos, Michael Mann, Ray + Bell, RichardScottOZ, Spencer Clark, Tim Gates, Tom Nicholas, Yunus Sevinchan, + alexamici, aurghs, crusaderky, dcherian, ghislainp, keewis, rhkleijn + + Breaking changes + ~~~~~~~~~~~~~~~~ + - xarray no longer supports python 3.6 + + The minimum version policy was changed to also apply to projects with irregular + releases. As a result, the minimum versions of some dependencies have changed: + + ============ ====== ==== + Package Old New + ============ ====== ==== + Python 3.6 3.7 + setuptools 38.4 40.4 + numpy 1.15 1.17 + pandas 0.25 1.0 + dask 2.9 2.11 + distributed 2.9 2.11 + bottleneck 1.2 1.3 + h5netcdf 0.7 0.8 + iris 2.2 2.4 + netcdf4 1.4 1.5 + pseudonetcdf 3.0 3.1 + rasterio 1.0 1.1 + scipy 1.3 1.4 + seaborn 0.9 0.10 + zarr 2.3 2.4 + ============ ====== ==== + + (:issue:`4688`, :pull:`4720`, :pull:`4907`, :pull:`4942`) + - As a result of :pull:`4684` the default units encoding for + datetime-like values (``np.datetime64[ns]`` or ``cftime.datetime``) will now + always be set such that ``int64`` values can be used. In the past, no units + finer than "seconds" were chosen, which would sometimes mean that ``float64`` + values were required, which would lead to inaccurate I/O round-trips. + - Variables referred to in attributes like ``bounds`` and ``grid_mapping`` + can be set as coordinate variables. These attributes are moved to + :py:attr:`DataArray.encoding` from :py:attr:`DataArray.attrs`. This behaviour + is controlled by the ``decode_coords`` kwarg to :py:func:`open_dataset` and + :py:func:`open_mfdataset`. The full list of decoded attributes is in + :ref:`weather-climate` (:pull:`2844`, :issue:`3689`) + - As a result of :pull:`4911` the output from calling :py:meth:`DataArray.sum` + or :py:meth:`DataArray.prod` on an integer array with ``skipna=True`` and a + non-None value for ``min_count`` will now be a float array rather than an + integer array. + + Deprecations + ~~~~~~~~~~~~ + + - ``dim`` argument to :py:meth:`DataArray.integrate` is being deprecated in + favour of a ``coord`` argument, for consistency with :py:meth:`Dataset.integrate`. + For now using ``dim`` issues a ``FutureWarning``. It will be removed in + version 0.19.0 (:pull:`3993`). + By `Tom Nicholas `_. + - Deprecated ``autoclose`` kwargs from :py:func:`open_dataset` are removed (:pull:`4725`). + By `Aureliana Barghini `_. + - the return value of :py:meth:`Dataset.update` is being deprecated to make it work more + like :py:meth:`dict.update`. It will be removed in version 0.19.0 (:pull:`4932`). + By `Justus Magin `_. + + New Features + ~~~~~~~~~~~~ + - :py:meth:`~xarray.cftime_range` and :py:meth:`DataArray.resample` now support + millisecond (``"L"`` or ``"ms"``) and microsecond (``"U"`` or ``"us"``) frequencies + for ``cftime.datetime`` coordinates (:issue:`4097`, :pull:`4758`). + By `Spencer Clark `_. + - Significantly higher ``unstack`` performance on numpy-backed arrays which + contain missing values; 8x faster than previous versions in our benchmark, and + now 2x faster than pandas (:pull:`4746`). + By `Maximilian Roos `_. + - Add :py:meth:`Dataset.plot.quiver` for quiver plots with :py:class:`Dataset` variables. + By `Deepak Cherian `_. + - Add ``"drop_conflicts"`` to the strategies supported by the ``combine_attrs`` kwarg + (:issue:`4749`, :pull:`4827`). + By `Justus Magin `_. + - Allow installing from git archives (:pull:`4897`). + By `Justus Magin `_. + - :py:class:`~core.rolling.DataArrayCoarsen` and :py:class:`~core.rolling.DatasetCoarsen` + now implement a ``reduce`` method, enabling coarsening operations with custom + reduction functions (:issue:`3741`, :pull:`4939`). + By `Spencer Clark `_. + - Most rolling operations use significantly less memory. (:issue:`4325`). + By `Deepak Cherian `_. + - Add :py:meth:`Dataset.drop_isel` and :py:meth:`DataArray.drop_isel` + (:issue:`4658`, :pull:`4819`). + By `Daniel Mesejo `_. + - Xarray now leverages updates as of cftime version 1.4.1, which enable exact I/O + roundtripping of ``cftime.datetime`` objects (:pull:`4758`). + By `Spencer Clark `_. + - :py:func:`open_dataset` and :py:func:`open_mfdataset` now accept ``fsspec`` URLs + (including globs for the latter) for ``engine="zarr"``, and so allow reading from + many remote and other file systems (:pull:`4461`) + By `Martin Durant `_ + - :py:meth:`DataArray.swap_dims` & :py:meth:`Dataset.swap_dims` now accept dims + in the form of kwargs as well as a dict, like most similar methods. + By `Maximilian Roos `_. + + Bug fixes + ~~~~~~~~~ + - Use specific type checks in ``xarray.core.variable.as_compatible_data`` instead of + blanket access to ``values`` attribute (:issue:`2097`) + By `Yunus Sevinchan `_. + - :py:meth:`DataArray.resample` and :py:meth:`Dataset.resample` do not trigger + computations anymore if :py:meth:`Dataset.weighted` or + :py:meth:`DataArray.weighted` are applied (:issue:`4625`, :pull:`4668`). By + `Julius Busecke `_. + - :py:func:`merge` with ``combine_attrs='override'`` makes a copy of the attrs + (:issue:`4627`). + - By default, when possible, xarray will now always use values of + type ``int64`` when encoding and decoding ``numpy.datetime64[ns]`` datetimes. This + ensures that maximum precision and accuracy are maintained in the round-tripping + process (:issue:`4045`, :pull:`4684`). It also enables encoding and decoding standard + calendar dates with time units of nanoseconds (:pull:`4400`). + By `Spencer Clark `_ and `Mark Harfouche + `_. + - :py:meth:`DataArray.astype`, :py:meth:`Dataset.astype` and :py:meth:`Variable.astype` support + the ``order`` and ``subok`` parameters again. This fixes a regression introduced in version 0.16.1 + (:issue:`4644`, :pull:`4683`). + By `Richard Kleijn `_ . + - Remove dictionary unpacking when using ``.loc`` to avoid collision with ``.sel`` parameters (:pull:`4695`). + By `Anderson Banihirwe `_. + - Fix the legend created by :py:meth:`Dataset.plot.scatter` (:issue:`4641`, :pull:`4723`). + By `Justus Magin `_. + - Fix a crash in orthogonal indexing on geographic coordinates with ``engine='cfgrib'`` + (:issue:`4733` :pull:`4737`). + By `Alessandro Amici `_. + - Coordinates with dtype ``str`` or ``bytes`` now retain their dtype on many operations, + e.g. ``reindex``, ``align``, ``concat``, ``assign``, previously they were cast to an object dtype + (:issue:`2658` and :issue:`4543`). + By `Mathias Hauser `_. + - Limit number of data rows when printing large datasets. (:issue:`4736`, :pull:`4750`). + By `Jimmy Westling `_. + - Add ``missing_dims`` parameter to transpose (:issue:`4647`, :pull:`4767`). + By `Daniel Mesejo `_. + - Resolve intervals before appending other metadata to labels when plotting (:issue:`4322`, :pull:`4794`). + By `Justus Magin `_. + - Fix regression when decoding a variable with a ``scale_factor`` and ``add_offset`` given + as a list of length one (:issue:`4631`). + By `Mathias Hauser `_. + - Expand user directory paths (e.g. ``~/``) in :py:func:`open_mfdataset` and + :py:meth:`Dataset.to_zarr` (:issue:`4783`, :pull:`4795`). + By `Julien Seguinot `_. + - Raise DeprecationWarning when trying to typecast a tuple containing a :py:class:`DataArray`. + User now prompted to first call `.data` on it (:issue:`4483`). + By `Chun Ho Chow `_. + - Ensure that :py:meth:`Dataset.interp` raises ``ValueError`` when interpolating + outside coordinate range and ``bounds_error=True`` (:issue:`4854`, + :pull:`4855`). + By `Leif Denby `_. + - Fix time encoding bug associated with using cftime versions greater than + 1.4.0 with xarray (:issue:`4870`, :pull:`4871`). + By `Spencer Clark `_. + - Stop :py:meth:`DataArray.sum` and :py:meth:`DataArray.prod` computing lazy + arrays when called with a ``min_count`` parameter (:issue:`4898`, :pull:`4911`). + By `Blair Bonnett `_. + - Fix bug preventing the ``min_count`` parameter to :py:meth:`DataArray.sum` and + :py:meth:`DataArray.prod` working correctly when calculating over all axes of + a float64 array (:issue:`4898`, :pull:`4911`). + By `Blair Bonnett `_. + - Fix decoding of vlen strings using h5py versions greater than 3.0.0 with h5netcdf backend (:issue:`4570`, :pull:`4893`). + By `Kai Mühlbauer `_. + - Allow converting :py:class:`Dataset` or :py:class:`DataArray` objects with a ``MultiIndex`` + and at least one other dimension to a ``pandas`` object (:issue:`3008`, :pull:`4442`). + By `ghislainp `_. + + Documentation + ~~~~~~~~~~~~~ + - Add information about requirements for accessor classes (:issue:`2788`, :pull:`4657`). + By `Justus Magin `_. + - Start a list of external I/O integrating with ``xarray`` (:issue:`683`, :pull:`4566`). + By `Justus Magin `_. + - Add concat examples and improve combining documentation (:issue:`4620`, :pull:`4645`). + By `Ray Bell `_ and + `Justus Magin `_. + - explicitly mention that :py:meth:`Dataset.update` updates inplace (:issue:`2951`, :pull:`4932`). + By `Justus Magin `_. + - Added docs on vectorized indexing (:pull:`4711`). + By `Eric Keenan `_. + + Internal Changes + ~~~~~~~~~~~~~~~~ + - Speed up of the continuous integration tests on azure. + + - Switched to mamba and use matplotlib-base for a faster installation of all dependencies (:pull:`4672`). + - Use ``pytest.mark.skip`` instead of ``pytest.mark.xfail`` for some tests that can currently not + succeed (:pull:`4685`). + - Run the tests in parallel using pytest-xdist (:pull:`4694`). + + By `Justus Magin `_ and `Mathias Hauser `_. + - Use ``pyproject.toml`` instead of the ``setup_requires`` option for + ``setuptools`` (:pull:`4897`). + By `Justus Magin `_. + - Replace all usages of ``assert x.identical(y)`` with ``assert_identical(x, y)`` + for clearer error messages (:pull:`4752`). + By `Maximilian Roos `_. + - Speed up attribute style access (e.g. ``ds.somevar`` instead of ``ds["somevar"]``) and + tab completion in IPython (:issue:`4741`, :pull:`4742`). + By `Richard Kleijn `_. + - Added the ``set_close`` method to ``Dataset`` and ``DataArray`` for backends + to specify how to voluntary release all resources. (:pull:`#4809`) + By `Alessandro Amici `_. + - Update type hints to work with numpy v1.20 (:pull:`4878`). + By `Mathias Hauser `_. + - Ensure warnings cannot be turned into exceptions in :py:func:`testing.assert_equal` and + the other ``assert_*`` functions (:pull:`4864`). + By `Mathias Hauser `_. + - Performance improvement when constructing DataArrays. Significantly speeds up + repr for Datasets with large number of variables. + By `Deepak Cherian `_. + + .. _whats-new.0.16.2: + + v0.16.2 (30 Nov 2020) + --------------------- + + This release brings the ability to write to limited regions of ``zarr`` files, + open zarr files with :py:func:`open_dataset` and :py:func:`open_mfdataset`, + increased support for propagating ``attrs`` using the ``keep_attrs`` flag, as + well as numerous bugfixes and documentation improvements. + + Many thanks to the 31 contributors who contributed to this release: Aaron + Spring, Akio Taniguchi, Aleksandar Jelenak, alexamici, Alexandre Poux, Anderson + Banihirwe, Andrew Pauling, Ashwin Vishnu, aurghs, Brian Ward, Caleb, crusaderky, + Dan Nowacki, darikg, David Brochart, David Huard, Deepak Cherian, Dion Häfner, + Gerardo Rivera, Gerrit Holl, Illviljan, inakleinbottle, Jacob Tomlinson, James + A. Bednar, jenssss, Joe Hamman, johnomotani, Joris Van den Bossche, Julia Kent, + Julius Busecke, Kai Mühlbauer, keewis, Keisuke Fujii, Kyle Cranmer, Luke + Volpatti, Mathias Hauser, Maximilian Roos, Michaël Defferrard, Michal + Baumgartner, Nick R. Papior, Pascal Bourgault, Peter Hausamann, PGijsbers, Ray + Bell, Romain Martinez, rpgoldman, Russell Manser, Sahid Velji, Samnan Rahee, + Sander, Spencer Clark, Stephan Hoyer, Thomas Zilio, Tobias Kölling, Tom + Augspurger, Wei Ji, Yash Saboo, Zeb Nicholls, + + Deprecations + ~~~~~~~~~~~~ + + - :py:attr:`~core.accessor_dt.DatetimeAccessor.weekofyear` and :py:attr:`~core.accessor_dt.DatetimeAccessor.week` + have been deprecated. Use ``DataArray.dt.isocalendar().week`` + instead (:pull:`4534`). By `Mathias Hauser `_. + `Maximilian Roos `_, and `Spencer Clark `_. + - :py:attr:`DataArray.rolling` and :py:attr:`Dataset.rolling` no longer support passing ``keep_attrs`` + via its constructor. Pass ``keep_attrs`` via the applied function, i.e. use + ``ds.rolling(...).mean(keep_attrs=False)`` instead of ``ds.rolling(..., keep_attrs=False).mean()`` + Rolling operations now keep their attributes per default (:pull:`4510`). + By `Mathias Hauser `_. + + New Features + ~~~~~~~~~~~~ + + - :py:func:`open_dataset` and :py:func:`open_mfdataset` + now works with ``engine="zarr"`` (:issue:`3668`, :pull:`4003`, :pull:`4187`). + By `Miguel Jimenez `_ and `Wei Ji Leong `_. + - Unary & binary operations follow the ``keep_attrs`` flag (:issue:`3490`, :issue:`4065`, :issue:`3433`, :issue:`3595`, :pull:`4195`). + By `Deepak Cherian `_. + - Added :py:meth:`~core.accessor_dt.DatetimeAccessor.isocalendar()` that returns a Dataset + with year, week, and weekday calculated according to the ISO 8601 calendar. Requires + pandas version 1.1.0 or greater (:pull:`4534`). By `Mathias Hauser `_, + `Maximilian Roos `_, and `Spencer Clark `_. + - :py:meth:`Dataset.to_zarr` now supports a ``region`` keyword for writing to + limited regions of existing Zarr stores (:pull:`4035`). + See :ref:`io.zarr.appending` for full details. + By `Stephan Hoyer `_. + - Added typehints in :py:func:`align` to reflect that the same type received in ``objects`` arg will be returned (:pull:`4522`). + By `Michal Baumgartner `_. + - :py:meth:`Dataset.weighted` and :py:meth:`DataArray.weighted` are now executing value checks lazily if weights are provided as dask arrays (:issue:`4541`, :pull:`4559`). + By `Julius Busecke `_. + - Added the ``keep_attrs`` keyword to ``rolling_exp.mean()``; it now keeps attributes + per default. By `Mathias Hauser `_ (:pull:`4592`). + - Added ``freq`` as property to :py:class:`CFTimeIndex` and into the + ``CFTimeIndex.repr``. (:issue:`2416`, :pull:`4597`) + By `Aaron Spring `_. + + Bug fixes + ~~~~~~~~~ + + - Fix bug where reference times without padded years (e.g. ``since 1-1-1``) would lose their units when + being passed by ``encode_cf_datetime`` (:issue:`4422`, :pull:`4506`). Such units are ambiguous + about which digit represents the years (is it YMD or DMY?). Now, if such formatting is encountered, + it is assumed that the first digit is the years, they are padded appropriately (to e.g. ``since 0001-1-1``) + and a warning that this assumption is being made is issued. Previously, without ``cftime``, such times + would be silently parsed incorrectly (at least based on the CF conventions) e.g. "since 1-1-1" would + be parsed (via ``pandas`` and ``dateutil``) to ``since 2001-1-1``. + By `Zeb Nicholls `_. + - Fix :py:meth:`DataArray.plot.step`. By `Deepak Cherian `_. + - Fix bug where reading a scalar value from a NetCDF file opened with the ``h5netcdf`` backend would raise a ``ValueError`` when ``decode_cf=True`` (:issue:`4471`, :pull:`4485`). + By `Gerrit Holl `_. + - Fix bug where datetime64 times are silently changed to incorrect values if they are outside the valid date range for ns precision when provided in some other units (:issue:`4427`, :pull:`4454`). + By `Andrew Pauling `_ + - Fix silently overwriting the ``engine`` key when passing :py:func:`open_dataset` a file object + to an incompatible netCDF (:issue:`4457`). Now incompatible combinations of files and engines raise + an exception instead. By `Alessandro Amici `_. + - The ``min_count`` argument to :py:meth:`DataArray.sum()` and :py:meth:`DataArray.prod()` + is now ignored when not applicable, i.e. when ``skipna=False`` or when ``skipna=None`` + and the dtype does not have a missing value (:issue:`4352`). + By `Mathias Hauser `_. + - :py:func:`combine_by_coords` now raises an informative error when passing coordinates + with differing calendars (:issue:`4495`). By `Mathias Hauser `_. + - :py:attr:`DataArray.rolling` and :py:attr:`Dataset.rolling` now also keep the attributes and names of of (wrapped) + ``DataArray`` objects, previously only the global attributes were retained (:issue:`4497`, :pull:`4510`). + By `Mathias Hauser `_. + - Improve performance where reading small slices from huge dimensions was slower than necessary (:pull:`4560`). By `Dion Häfner `_. + - Fix bug where ``dask_gufunc_kwargs`` was silently changed in :py:func:`apply_ufunc` (:pull:`4576`). By `Kai Mühlbauer `_. + + Documentation + ~~~~~~~~~~~~~ + - document the API not supported with duck arrays (:pull:`4530`). + By `Justus Magin `_. + - Mention the possibility to pass functions to :py:meth:`Dataset.where` or + :py:meth:`DataArray.where` in the parameter documentation (:issue:`4223`, :pull:`4613`). + By `Justus Magin `_. + - Update the docstring of :py:class:`DataArray` and :py:class:`Dataset`. + (:pull:`4532`); + By `Jimmy Westling `_. + - Raise a more informative error when :py:meth:`DataArray.to_dataframe` is + is called on a scalar, (:issue:`4228`); + By `Pieter Gijsbers `_. + - Fix grammar and typos in the :doc:`contributing` guide (:pull:`4545`). + By `Sahid Velji `_. + - Fix grammar and typos in the :doc:`user-guide/io` guide (:pull:`4553`). + By `Sahid Velji `_. + - Update link to NumPy docstring standard in the :doc:`contributing` guide (:pull:`4558`). + By `Sahid Velji `_. + - Add docstrings to ``isnull`` and ``notnull``, and fix the displayed signature + (:issue:`2760`, :pull:`4618`). + By `Justus Magin `_. + + Internal Changes + ~~~~~~~~~~~~~~~~ + + - Optional dependencies can be installed along with xarray by specifying + extras as ``pip install "xarray[extra]"`` where ``extra`` can be one of ``io``, + ``accel``, ``parallel``, ``viz`` and ``complete``. See docs for updated + :ref:`installation instructions `. + (:issue:`2888`, :pull:`4480`). + By `Ashwin Vishnu `_, `Justus Magin + `_ and `Mathias Hauser + `_. + - Removed stray spaces that stem from black removing new lines (:pull:`4504`). + By `Mathias Hauser `_. + - Ensure tests are not skipped in the ``py38-all-but-dask`` test environment + (:issue:`4509`). By `Mathias Hauser `_. + - Ignore select numpy warnings around missing values, where xarray handles + the values appropriately, (:pull:`4536`); + By `Maximilian Roos `_. + - Replace the internal use of ``pd.Index.__or__`` and ``pd.Index.__and__`` with ``pd.Index.union`` + and ``pd.Index.intersection`` as they will stop working as set operations in the future + (:issue:`4565`). By `Mathias Hauser `_. + - Add GitHub action for running nightly tests against upstream dependencies (:pull:`4583`). + By `Anderson Banihirwe `_. + - Ensure all figures are closed properly in plot tests (:pull:`4600`). + By `Yash Saboo `_, `Nirupam K N + `_ and `Mathias Hauser + `_. + + .. _whats-new.0.16.1: + + v0.16.1 (2020-09-20) + --------------------- + + This patch release fixes an incompatibility with a recent pandas change, which + was causing an issue indexing with a ``datetime64``. It also includes + improvements to ``rolling``, ``to_dataframe``, ``cov`` & ``corr`` methods and + bug fixes. Our documentation has a number of improvements, including fixing all + doctests and confirming their accuracy on every commit. + + Many thanks to the 36 contributors who contributed to this release: + + Aaron Spring, Akio Taniguchi, Aleksandar Jelenak, Alexandre Poux, + Caleb, Dan Nowacki, Deepak Cherian, Gerardo Rivera, Jacob Tomlinson, James A. + Bednar, Joe Hamman, Julia Kent, Kai Mühlbauer, Keisuke Fujii, Mathias Hauser, + Maximilian Roos, Nick R. Papior, Pascal Bourgault, Peter Hausamann, Romain + Martinez, Russell Manser, Samnan Rahee, Sander, Spencer Clark, Stephan Hoyer, + Thomas Zilio, Tobias Kölling, Tom Augspurger, alexamici, crusaderky, darikg, + inakleinbottle, jenssss, johnomotani, keewis, and rpgoldman. + + Breaking changes + ~~~~~~~~~~~~~~~~ + + - :py:meth:`DataArray.astype` and :py:meth:`Dataset.astype` now preserve attributes. Keep the + old behavior by passing `keep_attrs=False` (:issue:`2049`, :pull:`4314`). + By `Dan Nowacki `_ and `Gabriel Joel Mitchell `_. + + New Features + ~~~~~~~~~~~~ + + - :py:meth:`~xarray.DataArray.rolling` and :py:meth:`~xarray.Dataset.rolling` + now accept more than 1 dimension. (:pull:`4219`) + By `Keisuke Fujii `_. + - :py:meth:`~xarray.DataArray.to_dataframe` and :py:meth:`~xarray.Dataset.to_dataframe` + now accept a ``dim_order`` parameter allowing to specify the resulting dataframe's + dimensions order (:issue:`4331`, :pull:`4333`). + By `Thomas Zilio `_. + - Support multiple outputs in :py:func:`xarray.apply_ufunc` when using + ``dask='parallelized'``. (:issue:`1815`, :pull:`4060`). + By `Kai Mühlbauer `_. + - ``min_count`` can be supplied to reductions such as ``.sum`` when specifying + multiple dimension to reduce over; (:pull:`4356`). + By `Maximilian Roos `_. + - :py:func:`xarray.cov` and :py:func:`xarray.corr` now handle missing values; (:pull:`4351`). + By `Maximilian Roos `_. + - Add support for parsing datetime strings formatted following the default + string representation of cftime objects, i.e. YYYY-MM-DD hh:mm:ss, in + partial datetime string indexing, as well as :py:meth:`~xarray.cftime_range` + (:issue:`4337`). By `Spencer Clark `_. + - Build ``CFTimeIndex.__repr__`` explicitly as :py:class:`pandas.Index`. Add ``calendar`` as a new + property for :py:class:`CFTimeIndex` and show ``calendar`` and ``length`` in + ``CFTimeIndex.__repr__`` (:issue:`2416`, :pull:`4092`) + By `Aaron Spring `_. + - Use a wrapped array's ``_repr_inline_`` method to construct the collapsed ``repr`` + of :py:class:`DataArray` and :py:class:`Dataset` objects and + document the new method in :doc:`internals/index`. (:pull:`4248`). + By `Justus Magin `_. + - Allow per-variable fill values in most functions. (:pull:`4237`). + By `Justus Magin `_. + - Expose ``use_cftime`` option in :py:func:`~xarray.open_zarr` (:issue:`2886`, :pull:`3229`) + By `Samnan Rahee `_ and `Anderson Banihirwe `_. + + Bug fixes + ~~~~~~~~~ + + - Fix indexing with datetime64 scalars with pandas 1.1 (:issue:`4283`). + By `Stephan Hoyer `_ and + `Justus Magin `_. + - Variables which are chunked using dask only along some dimensions can be chunked while storing with zarr along previously + unchunked dimensions (:pull:`4312`) By `Tobias Kölling `_. + - Fixed a bug in backend caused by basic installation of Dask (:issue:`4164`, :pull:`4318`) + `Sam Morley `_. + - Fixed a few bugs with :py:meth:`Dataset.polyfit` when encountering deficient matrix ranks (:issue:`4190`, :pull:`4193`). By `Pascal Bourgault `_. + - Fixed inconsistencies between docstring and functionality for :py:meth:`DataArray.str.get` + and :py:meth:`DataArray.str.wrap` (:issue:`4334`). By `Mathias Hauser `_. + - Fixed overflow issue causing incorrect results in computing means of :py:class:`cftime.datetime` + arrays (:issue:`4341`). By `Spencer Clark `_. + - Fixed :py:meth:`Dataset.coarsen`, :py:meth:`DataArray.coarsen` dropping attributes on original object (:issue:`4120`, :pull:`4360`). By `Julia Kent `_. + - fix the signature of the plot methods. (:pull:`4359`) By `Justus Magin `_. + - Fix :py:func:`xarray.apply_ufunc` with ``vectorize=True`` and ``exclude_dims`` (:issue:`3890`). + By `Mathias Hauser `_. + - Fix `KeyError` when doing linear interpolation to an nd `DataArray` + that contains NaNs (:pull:`4233`). + By `Jens Svensmark `_ + - Fix incorrect legend labels for :py:meth:`Dataset.plot.scatter` (:issue:`4126`). + By `Peter Hausamann `_. + - Fix ``dask.optimize`` on ``DataArray`` producing an invalid Dask task graph (:issue:`3698`) + By `Tom Augspurger `_ + - Fix ``pip install .`` when no ``.git`` directory exists; namely when the xarray source + directory has been rsync'ed by PyCharm Professional for a remote deployment over SSH. + By `Guido Imperiale `_ + - Preserve dimension and coordinate order during :py:func:`xarray.concat` (:issue:`2811`, :issue:`4072`, :pull:`4419`). + By `Kai Mühlbauer `_. + - Avoid relying on :py:class:`set` objects for the ordering of the coordinates (:pull:`4409`) + By `Justus Magin `_. + + Documentation + ~~~~~~~~~~~~~ + + - Update the docstring of :py:meth:`DataArray.copy` to remove incorrect mention of 'dataset' (:issue:`3606`) + By `Sander van Rijn `_. + - Removed skipna argument from :py:meth:`DataArray.count`, :py:meth:`DataArray.any`, :py:meth:`DataArray.all`. (:issue:`755`) + By `Sander van Rijn `_ + - Update the contributing guide to use merges instead of rebasing and state + that we squash-merge. (:pull:`4355`). By `Justus Magin `_. + - Make sure the examples from the docstrings actually work (:pull:`4408`). + By `Justus Magin `_. + - Updated Vectorized Indexing to a clearer example. + By `Maximilian Roos `_ + + Internal Changes + ~~~~~~~~~~~~~~~~ + + - Fixed all doctests and enabled their running in CI. + By `Justus Magin `_. + - Relaxed the :ref:`mindeps_policy` to support: + + - all versions of setuptools released in the last 42 months (but no older than 38.4) + - all versions of dask and dask.distributed released in the last 12 months (but no + older than 2.9) + - all versions of other packages released in the last 12 months + + All are up from 6 months (:issue:`4295`) + `Guido Imperiale `_. + - Use :py:func:`dask.array.apply_gufunc ` instead of + :py:func:`dask.array.blockwise` in :py:func:`xarray.apply_ufunc` when using + ``dask='parallelized'``. (:pull:`4060`, :pull:`4391`, :pull:`4392`) + By `Kai Mühlbauer `_. + - Align ``mypy`` versions to ``0.782`` across ``requirements`` and + ``.pre-commit-config.yml`` files. (:pull:`4390`) + By `Maximilian Roos `_ + - Only load resource files when running inside a Jupyter Notebook + (:issue:`4294`) By `Guido Imperiale `_ + - Silenced most ``numpy`` warnings such as ``Mean of empty slice``. (:pull:`4369`) + By `Maximilian Roos `_ + - Enable type checking for :py:func:`concat` (:issue:`4238`) + By `Mathias Hauser `_. + - Updated plot functions for matplotlib version 3.3 and silenced warnings in the + plot tests (:pull:`4365`). By `Mathias Hauser `_. + - Versions in ``pre-commit.yaml`` are now pinned, to reduce the chances of + conflicting versions. (:pull:`4388`) + By `Maximilian Roos `_ + + + + .. _whats-new.0.16.0: + + v0.16.0 (2020-07-11) + --------------------- + + This release adds `xarray.cov` & `xarray.corr` for covariance & correlation + respectively; the `idxmax` & `idxmin` methods, the `polyfit` method & + `xarray.polyval` for fitting polynomials, as well as a number of documentation + improvements, other features, and bug fixes. Many thanks to all 44 contributors + who contributed to this release: + + Akio Taniguchi, Andrew Williams, Aurélien Ponte, Benoit Bovy, Dave Cole, David + Brochart, Deepak Cherian, Elliott Sales de Andrade, Etienne Combrisson, Hossein + Madadi, Huite, Joe Hamman, Kai Mühlbauer, Keisuke Fujii, Maik Riechert, Marek + Jacob, Mathias Hauser, Matthieu Ancellin, Maximilian Roos, Noah D Brenowitz, + Oriol Abril, Pascal Bourgault, Phillip Butcher, Prajjwal Nijhara, Ray Bell, Ryan + Abernathey, Ryan May, Spencer Clark, Spencer Hill, Srijan Saurav, Stephan Hoyer, + Taher Chegini, Todd, Tom Nicholas, Yohai Bar Sinai, Yunus Sevinchan, + arabidopsis, aurghs, clausmichele, dmey, johnomotani, keewis, raphael dussin, + risebell + + Breaking changes + ~~~~~~~~~~~~~~~~ + + - Minimum supported versions for the following packages have changed: ``dask >=2.9``, + ``distributed>=2.9``. + By `Deepak Cherian `_ + - ``groupby`` operations will restore coord dimension order. Pass ``restore_coord_dims=False`` + to revert to previous behavior. + - :meth:`DataArray.transpose` will now transpose coordinates by default. + Pass ``transpose_coords=False`` to revert to previous behaviour. + By `Maximilian Roos `_ + - Alternate draw styles for :py:meth:`plot.step` must be passed using the + ``drawstyle`` (or ``ds``) keyword argument, instead of the ``linestyle`` (or + ``ls``) keyword argument, in line with the `upstream change in Matplotlib + `_. + (:pull:`3274`) + By `Elliott Sales de Andrade `_ + - The old ``auto_combine`` function has now been removed in + favour of the :py:func:`combine_by_coords` and + :py:func:`combine_nested` functions. This also means that + the default behaviour of :py:func:`open_mfdataset` has changed to use + ``combine='by_coords'`` as the default argument value. (:issue:`2616`, :pull:`3926`) + By `Tom Nicholas `_. + - The ``DataArray`` and ``Variable`` HTML reprs now expand the data section by + default (:issue:`4176`) + By `Stephan Hoyer `_. + + New Features + ~~~~~~~~~~~~ + - :py:meth:`DataArray.argmin` and :py:meth:`DataArray.argmax` now support + sequences of 'dim' arguments, and if a sequence is passed return a dict + (which can be passed to :py:meth:`DataArray.isel` to get the value of the minimum) of + the indices for each dimension of the minimum or maximum of a DataArray. + (:pull:`3936`) + By `John Omotani `_, thanks to `Keisuke Fujii + `_ for work in :pull:`1469`. + - Added :py:func:`xarray.cov` and :py:func:`xarray.corr` (:issue:`3784`, :pull:`3550`, :pull:`4089`). + By `Andrew Williams `_ and `Robin Beer `_. + - Implement :py:meth:`DataArray.idxmax`, :py:meth:`DataArray.idxmin`, + :py:meth:`Dataset.idxmax`, :py:meth:`Dataset.idxmin`. (:issue:`60`, :pull:`3871`) + By `Todd Jennings `_ + - Added :py:meth:`DataArray.polyfit` and :py:func:`xarray.polyval` for fitting + polynomials. (:issue:`3349`, :pull:`3733`, :pull:`4099`) + By `Pascal Bourgault `_. + - Added :py:meth:`xarray.infer_freq` for extending frequency inferring to CFTime indexes and data (:pull:`4033`). + By `Pascal Bourgault `_. + - ``chunks='auto'`` is now supported in the ``chunks`` argument of + :py:meth:`Dataset.chunk`. (:issue:`4055`) + By `Andrew Williams `_ + - Control over attributes of result in :py:func:`merge`, :py:func:`concat`, + :py:func:`combine_by_coords` and :py:func:`combine_nested` using + combine_attrs keyword argument. (:issue:`3865`, :pull:`3877`) + By `John Omotani `_ + - `missing_dims` argument to :py:meth:`Dataset.isel`, + :py:meth:`DataArray.isel` and :py:meth:`Variable.isel` to allow replacing + the exception when a dimension passed to ``isel`` is not present with a + warning, or just ignore the dimension. (:issue:`3866`, :pull:`3923`) + By `John Omotani `_ + - Support dask handling for :py:meth:`DataArray.idxmax`, :py:meth:`DataArray.idxmin`, + :py:meth:`Dataset.idxmax`, :py:meth:`Dataset.idxmin`. (:pull:`3922`, :pull:`4135`) + By `Kai Mühlbauer `_ and `Pascal Bourgault `_. + - More support for unit aware arrays with pint (:pull:`3643`, :pull:`3975`, :pull:`4163`) + By `Justus Magin `_. + - Support overriding existing variables in ``to_zarr()`` with ``mode='a'`` even + without ``append_dim``, as long as dimension sizes do not change. + By `Stephan Hoyer `_. + - Allow plotting of boolean arrays. (:pull:`3766`) + By `Marek Jacob `_ + - Enable using MultiIndex levels as coordinates in 1D and 2D plots (:issue:`3927`). + By `Mathias Hauser `_. + - A ``days_in_month`` accessor for :py:class:`xarray.CFTimeIndex`, analogous to + the ``days_in_month`` accessor for a :py:class:`pandas.DatetimeIndex`, which + returns the days in the month each datetime in the index. Now days in month + weights for both standard and non-standard calendars can be obtained using + the :py:class:`~core.accessor_dt.DatetimeAccessor` (:pull:`3935`). This + feature requires cftime version 1.1.0 or greater. By + `Spencer Clark `_. + - For the netCDF3 backend, added dtype coercions for unsigned integer types. + (:issue:`4014`, :pull:`4018`) + By `Yunus Sevinchan `_ + - :py:meth:`map_blocks` now accepts a ``template`` kwarg. This allows use cases + where the result of a computation could not be inferred automatically. + By `Deepak Cherian `_ + - :py:meth:`map_blocks` can now handle dask-backed xarray objects in ``args``. (:pull:`3818`) + By `Deepak Cherian `_ + - Add keyword ``decode_timedelta`` to :py:func:`xarray.open_dataset`, + (:py:func:`xarray.open_dataarray`, :py:func:`xarray.open_dataarray`, + :py:func:`xarray.decode_cf`) that allows to disable/enable the decoding of timedeltas + independently of time decoding (:issue:`1621`) + `Aureliana Barghini `_ + + Enhancements + ~~~~~~~~~~~~ + - Performance improvement of :py:meth:`DataArray.interp` and :py:func:`Dataset.interp` + We performs independant interpolation sequentially rather than interpolating in + one large multidimensional space. (:issue:`2223`) + By `Keisuke Fujii `_. + - :py:meth:`DataArray.interp` now support interpolations over chunked dimensions (:pull:`4155`). By `Alexandre Poux `_. + - Major performance improvement for :py:meth:`Dataset.from_dataframe` when the + dataframe has a MultiIndex (:pull:`4184`). + By `Stephan Hoyer `_. + - :py:meth:`DataArray.reset_index` and :py:meth:`Dataset.reset_index` now keep + coordinate attributes (:pull:`4103`). By `Oriol Abril `_. + - Axes kwargs such as ``facecolor`` can now be passed to :py:meth:`DataArray.plot` in ``subplot_kws``. + This works for both single axes plots and FacetGrid plots. + By `Raphael Dussin `_. + - Array items with long string reprs are now limited to a + reasonable width (:pull:`3900`) + By `Maximilian Roos `_ + - Large arrays whose numpy reprs would have greater than 40 lines are now + limited to a reasonable length. + (:pull:`3905`) + By `Maximilian Roos `_ + + Bug fixes + ~~~~~~~~~ + - Fix errors combining attrs in :py:func:`open_mfdataset` (:issue:`4009`, :pull:`4173`) + By `John Omotani `_ + - If groupby receives a ``DataArray`` with name=None, assign a default name (:issue:`158`) + By `Phil Butcher `_. + - Support dark mode in VS code (:issue:`4024`) + By `Keisuke Fujii `_. + - Fix bug when converting multiindexed Pandas objects to sparse xarray objects. (:issue:`4019`) + By `Deepak Cherian `_. + - ``ValueError`` is raised when ``fill_value`` is not a scalar in :py:meth:`full_like`. (:issue:`3977`) + By `Huite Bootsma `_. + - Fix wrong order in converting a ``pd.Series`` with a MultiIndex to ``DataArray``. + (:issue:`3951`, :issue:`4186`) + By `Keisuke Fujii `_ and `Stephan Hoyer `_. + - Fix renaming of coords when one or more stacked coords is not in + sorted order during stack+groupby+apply operations. (:issue:`3287`, + :pull:`3906`) By `Spencer Hill `_ + - Fix a regression where deleting a coordinate from a copied :py:class:`DataArray` + can affect the original :py:class:`DataArray`. (:issue:`3899`, :pull:`3871`) + By `Todd Jennings `_ + - Fix :py:class:`~xarray.plot.FacetGrid` plots with a single contour. (:issue:`3569`, :pull:`3915`). + By `Deepak Cherian `_ + - Use divergent colormap if ``levels`` spans 0. (:issue:`3524`) + By `Deepak Cherian `_ + - Fix :py:class:`~xarray.plot.FacetGrid` when ``vmin == vmax``. (:issue:`3734`) + By `Deepak Cherian `_ + - Fix plotting when ``levels`` is a scalar and ``norm`` is provided. (:issue:`3735`) + By `Deepak Cherian `_ + - Fix bug where plotting line plots with 2D coordinates depended on dimension + order. (:issue:`3933`) + By `Tom Nicholas `_. + - Fix ``RasterioDeprecationWarning`` when using a ``vrt`` in ``open_rasterio``. (:issue:`3964`) + By `Taher Chegini `_. + - Fix ``AttributeError`` on displaying a :py:class:`Variable` + in a notebook context. (:issue:`3972`, :pull:`3973`) + By `Ian Castleden `_. + - Fix bug causing :py:meth:`DataArray.interpolate_na` to always drop attributes, + and added `keep_attrs` argument. (:issue:`3968`) + By `Tom Nicholas `_. + - Fix bug in time parsing failing to fall back to cftime. This was causing time + variables with a time unit of `'msecs'` to fail to parse. (:pull:`3998`) + By `Ryan May `_. + - Fix weighted mean when passing boolean weights (:issue:`4074`). + By `Mathias Hauser `_. + - Fix html repr in untrusted notebooks: fallback to plain text repr. (:pull:`4053`) + By `Benoit Bovy `_. + - Fix :py:meth:`DataArray.to_unstacked_dataset` for single-dimension variables. (:issue:`4049`) + By `Deepak Cherian `_ + - Fix :py:func:`open_rasterio` for ``WarpedVRT`` with specified ``src_crs``. (:pull:`4104`) + By `Dave Cole `_. + + Documentation + ~~~~~~~~~~~~~ + - update the docstring of :py:meth:`DataArray.assign_coords` : clarify how to + add a new coordinate to an existing dimension and illustrative example + (:issue:`3952`, :pull:`3958`) By + `Etienne Combrisson `_. + - update the docstring of :py:meth:`Dataset.diff` and + :py:meth:`DataArray.diff` so it does document the ``dim`` + parameter as required. (:issue:`1040`, :pull:`3909`) + By `Justus Magin `_. + - Updated :doc:`Calculating Seasonal Averages from Timeseries of Monthly Means + ` example notebook to take advantage of the new + ``days_in_month`` accessor for :py:class:`xarray.CFTimeIndex` + (:pull:`3935`). By `Spencer Clark `_. + - Updated the list of current core developers. (:issue:`3892`) + By `Tom Nicholas `_. + - Add example for multi-dimensional extrapolation and note different behavior + of ``kwargs`` in :py:meth:`Dataset.interp` and :py:meth:`DataArray.interp` + for 1-d and n-d interpolation (:pull:`3956`). + By `Matthias Riße `_. + - Apply ``black`` to all the code in the documentation (:pull:`4012`) + By `Justus Magin `_. + - Narrative documentation now describes :py:meth:`map_blocks`: :ref:`dask.automatic-parallelization`. + By `Deepak Cherian `_. + - Document ``.plot``, ``.dt``, ``.str`` accessors the way they are called. (:issue:`3625`, :pull:`3988`) + By `Justus Magin `_. + - Add documentation for the parameters and return values of :py:meth:`DataArray.sel`. + By `Justus Magin `_. + + Internal Changes + ~~~~~~~~~~~~~~~~ + - Raise more informative error messages for chunk size conflicts when writing to zarr files. + By `Deepak Cherian `_. + - Run the ``isort`` pre-commit hook only on python source files + and update the ``flake8`` version. (:issue:`3750`, :pull:`3711`) + By `Justus Magin `_. + - Add `blackdoc `_ to the list of + checkers for development. (:pull:`4177`) + By `Justus Magin `_. + - Add a CI job that runs the tests with every optional dependency + except ``dask``. (:issue:`3794`, :pull:`3919`) + By `Justus Magin `_. + - Use ``async`` / ``await`` for the asynchronous distributed + tests. (:issue:`3987`, :pull:`3989`) + By `Justus Magin `_. + - Various internal code clean-ups (:pull:`4026`, :pull:`4038`). + By `Prajjwal Nijhara `_. + + .. _whats-new.0.15.1: + + v0.15.1 (23 Mar 2020) + --------------------- + + This release brings many new features such as :py:meth:`Dataset.weighted` methods for weighted array + reductions, a new jupyter repr by default, and the start of units integration with pint. There's also + the usual batch of usability improvements, documentation additions, and bug fixes. + + Breaking changes + ~~~~~~~~~~~~~~~~ + + - Raise an error when assigning to the ``.values`` or ``.data`` attribute of + dimension coordinates i.e. ``IndexVariable`` objects. This has been broken since + v0.12.0. Please use :py:meth:`DataArray.assign_coords` or :py:meth:`Dataset.assign_coords` + instead. (:issue:`3470`, :pull:`3862`) + By `Deepak Cherian `_ + + New Features + ~~~~~~~~~~~~ + + - Weighted array reductions are now supported via the new :py:meth:`DataArray.weighted` + and :py:meth:`Dataset.weighted` methods. See :ref:`comput.weighted`. (:issue:`422`, :pull:`2922`). + By `Mathias Hauser `_. + - The new jupyter notebook repr (``Dataset._repr_html_`` and + ``DataArray._repr_html_``) (introduced in 0.14.1) is now on by default. To + disable, use ``xarray.set_options(display_style="text")``. + By `Julia Signell `_. + - Added support for :py:class:`pandas.DatetimeIndex`-style rounding of + ``cftime.datetime`` objects directly via a :py:class:`CFTimeIndex` or via the + :py:class:`~core.accessor_dt.DatetimeAccessor`. + By `Spencer Clark `_ + - Support new h5netcdf backend keyword `phony_dims` (available from h5netcdf + v0.8.0 for :py:class:`~xarray.backends.H5NetCDFStore`. + By `Kai Mühlbauer `_. + - Add partial support for unit aware arrays with pint. (:pull:`3706`, :pull:`3611`) + By `Justus Magin `_. + - :py:meth:`Dataset.groupby` and :py:meth:`DataArray.groupby` now raise a + `TypeError` on multiple string arguments. Receiving multiple string arguments + often means a user is attempting to pass multiple dimensions as separate + arguments and should instead pass a single list of dimensions. + (:pull:`3802`) + By `Maximilian Roos `_ + - :py:func:`map_blocks` can now apply functions that add new unindexed dimensions. + By `Deepak Cherian `_ + - An ellipsis (``...``) is now supported in the ``dims`` argument of + :py:meth:`Dataset.stack` and :py:meth:`DataArray.stack`, meaning all + unlisted dimensions, similar to its meaning in :py:meth:`DataArray.transpose`. + (:pull:`3826`) + By `Maximilian Roos `_ + - :py:meth:`Dataset.where` and :py:meth:`DataArray.where` accept a lambda as a + first argument, which is then called on the input; replicating pandas' behavior. + By `Maximilian Roos `_. + - ``skipna`` is available in :py:meth:`Dataset.quantile`, :py:meth:`DataArray.quantile`, + :py:meth:`core.groupby.DatasetGroupBy.quantile`, :py:meth:`core.groupby.DataArrayGroupBy.quantile` + (:issue:`3843`, :pull:`3844`) + By `Aaron Spring `_. + - Add a diff summary for `testing.assert_allclose`. (:issue:`3617`, :pull:`3847`) + By `Justus Magin `_. + + Bug fixes + ~~~~~~~~~ + + - Fix :py:meth:`Dataset.interp` when indexing array shares coordinates with the + indexed variable (:issue:`3252`). + By `David Huard `_. + - Fix recombination of groups in :py:meth:`Dataset.groupby` and + :py:meth:`DataArray.groupby` when performing an operation that changes the + size of the groups along the grouped dimension. By `Eric Jansen + `_. + - Fix use of multi-index with categorical values (:issue:`3674`). + By `Matthieu Ancellin `_. + - Fix alignment with ``join="override"`` when some dimensions are unindexed. (:issue:`3681`). + By `Deepak Cherian `_. + - Fix :py:meth:`Dataset.swap_dims` and :py:meth:`DataArray.swap_dims` producing + index with name reflecting the previous dimension name instead of the new one + (:issue:`3748`, :pull:`3752`). By `Joseph K Aicher + `_. + - Use ``dask_array_type`` instead of ``dask_array.Array`` for type + checking. (:issue:`3779`, :pull:`3787`) + By `Justus Magin `_. + - :py:func:`concat` can now handle coordinate variables only present in one of + the objects to be concatenated when ``coords="different"``. + By `Deepak Cherian `_. + - xarray now respects the over, under and bad colors if set on a provided colormap. + (:issue:`3590`, :pull:`3601`) + By `johnomotani `_. + - ``coarsen`` and ``rolling`` now respect ``xr.set_options(keep_attrs=True)`` + to preserve attributes. :py:meth:`Dataset.coarsen` accepts a keyword + argument ``keep_attrs`` to change this setting. (:issue:`3376`, + :pull:`3801`) By `Andrew Thomas `_. + - Delete associated indexes when deleting coordinate variables. (:issue:`3746`). + By `Deepak Cherian `_. + - Fix :py:meth:`Dataset.to_zarr` when using ``append_dim`` and ``group`` + simultaneously. (:issue:`3170`). By `Matthias Meyer `_. + - Fix html repr on :py:class:`Dataset` with non-string keys (:pull:`3807`). + By `Maximilian Roos `_. + + Documentation + ~~~~~~~~~~~~~ + + - Fix documentation of :py:class:`DataArray` removing the deprecated mention + that when omitted, `dims` are inferred from a `coords`-dict. (:pull:`3821`) + By `Sander van Rijn `_. + - Improve the :py:func:`where` docstring. + By `Maximilian Roos `_ + - Update the installation instructions: only explicitly list recommended dependencies + (:issue:`3756`). + By `Mathias Hauser `_. + + Internal Changes + ~~~~~~~~~~~~~~~~ + + - Remove the internal ``import_seaborn`` function which handled the deprecation of + the ``seaborn.apionly`` entry point (:issue:`3747`). + By `Mathias Hauser `_. + - Don't test pint integration in combination with datetime objects. (:issue:`3778`, :pull:`3788`) + By `Justus Magin `_. + - Change test_open_mfdataset_list_attr to only run with dask installed + (:issue:`3777`, :pull:`3780`). + By `Bruno Pagani `_. + - Preserve the ability to index with ``method="nearest"`` with a + :py:class:`CFTimeIndex` with pandas versions greater than 1.0.1 + (:issue:`3751`). By `Spencer Clark `_. + - Greater flexibility and improved test coverage of subtracting various types + of objects from a :py:class:`CFTimeIndex`. By `Spencer Clark + `_. + - Update Azure CI MacOS image, given pending removal. + By `Maximilian Roos `_ + - Remove xfails for scipy 1.0.1 for tests that append to netCDF files (:pull:`3805`). + By `Mathias Hauser `_. + - Remove conversion to ``pandas.Panel``, given its removal in pandas + in favor of xarray's objects. + By `Maximilian Roos `_ + + .. _whats-new.0.15.0: + + + v0.15.0 (30 Jan 2020) + --------------------- + + This release brings many improvements to xarray's documentation: our examples are now binderized notebooks (`click here `_) + and we have new example notebooks from our SciPy 2019 sprint (many thanks to our contributors!). + + This release also features many API improvements such as a new + :py:class:`~core.accessor_dt.TimedeltaAccessor` and support for :py:class:`CFTimeIndex` in + :py:meth:`~DataArray.interpolate_na`); as well as many bug fixes. + + Breaking changes + ~~~~~~~~~~~~~~~~ + - Bumped minimum tested versions for dependencies: + + - numpy 1.15 + - pandas 0.25 + - dask 2.2 + - distributed 2.2 + - scipy 1.3 + + - Remove ``compat`` and ``encoding`` kwargs from ``DataArray``, which + have been deprecated since 0.12. (:pull:`3650`). + Instead, specify the ``encoding`` kwarg when writing to disk or set + the :py:attr:`DataArray.encoding` attribute directly. + By `Maximilian Roos `_. + - :py:func:`xarray.dot`, :py:meth:`DataArray.dot`, and the ``@`` operator now + use ``align="inner"`` (except when ``xarray.set_options(arithmetic_join="exact")``; + :issue:`3694`) by `Mathias Hauser `_. + + New Features + ~~~~~~~~~~~~ + - Implement :py:meth:`DataArray.pad` and :py:meth:`Dataset.pad`. (:issue:`2605`, :pull:`3596`). + By `Mark Boer `_. + - :py:meth:`DataArray.sel` and :py:meth:`Dataset.sel` now support :py:class:`pandas.CategoricalIndex`. (:issue:`3669`) + By `Keisuke Fujii `_. + - Support using an existing, opened h5netcdf ``File`` with + :py:class:`~xarray.backends.H5NetCDFStore`. This permits creating an + :py:class:`~xarray.Dataset` from a h5netcdf ``File`` that has been opened + using other means (:issue:`3618`). + By `Kai Mühlbauer `_. + - Implement ``median`` and ``nanmedian`` for dask arrays. This works by rechunking + to a single chunk along all reduction axes. (:issue:`2999`). + By `Deepak Cherian `_. + - :py:func:`~xarray.concat` now preserves attributes from the first Variable. + (:issue:`2575`, :issue:`2060`, :issue:`1614`) + By `Deepak Cherian `_. + - :py:meth:`Dataset.quantile`, :py:meth:`DataArray.quantile` and ``GroupBy.quantile`` + now work with dask Variables. + By `Deepak Cherian `_. + - Added the ``count`` reduction method to both :py:class:`~core.rolling.DatasetCoarsen` + and :py:class:`~core.rolling.DataArrayCoarsen` objects. (:pull:`3500`) + By `Deepak Cherian `_ + - Add ``meta`` kwarg to :py:func:`~xarray.apply_ufunc`; + this is passed on to :py:func:`dask.array.blockwise`. (:pull:`3660`) + By `Deepak Cherian `_. + - Add ``attrs_file`` option in :py:func:`~xarray.open_mfdataset` to choose the + source file for global attributes in a multi-file dataset (:issue:`2382`, + :pull:`3498`). By `Julien Seguinot `_. + - :py:meth:`Dataset.swap_dims` and :py:meth:`DataArray.swap_dims` + now allow swapping to dimension names that don't exist yet. (:pull:`3636`) + By `Justus Magin `_. + - Extend :py:class:`~core.accessor_dt.DatetimeAccessor` properties + and support ``.dt`` accessor for timedeltas + via :py:class:`~core.accessor_dt.TimedeltaAccessor` (:pull:`3612`) + By `Anderson Banihirwe `_. + - Improvements to interpolating along time axes (:issue:`3641`, :pull:`3631`). + By `David Huard `_. + + - Support :py:class:`CFTimeIndex` in :py:meth:`DataArray.interpolate_na` + - define 1970-01-01 as the default offset for the interpolation index for both + :py:class:`pandas.DatetimeIndex` and :py:class:`CFTimeIndex`, + - use microseconds in the conversion from timedelta objects to floats to avoid + overflow errors. + + Bug fixes + ~~~~~~~~~ + - Applying a user-defined function that adds new dimensions using :py:func:`apply_ufunc` + and ``vectorize=True`` now works with ``dask > 2.0``. (:issue:`3574`, :pull:`3660`). + By `Deepak Cherian `_. + - Fix :py:meth:`~xarray.combine_by_coords` to allow for combining incomplete + hypercubes of Datasets (:issue:`3648`). By `Ian Bolliger + `_. + - Fix :py:func:`~xarray.combine_by_coords` when combining cftime coordinates + which span long time intervals (:issue:`3535`). By `Spencer Clark + `_. + - Fix plotting with transposed 2D non-dimensional coordinates. (:issue:`3138`, :pull:`3441`) + By `Deepak Cherian `_. + - :py:meth:`plot.FacetGrid.set_titles` can now replace existing row titles of a + :py:class:`~xarray.plot.FacetGrid` plot. In addition :py:class:`~xarray.plot.FacetGrid` gained + two new attributes: :py:attr:`~xarray.plot.FacetGrid.col_labels` and + :py:attr:`~xarray.plot.FacetGrid.row_labels` contain :py:class:`matplotlib.text.Text` handles for both column and + row labels. These can be used to manually change the labels. + By `Deepak Cherian `_. + - Fix issue with Dask-backed datasets raising a ``KeyError`` on some computations involving :py:func:`map_blocks` (:pull:`3598`). + By `Tom Augspurger `_. + - Ensure :py:meth:`Dataset.quantile`, :py:meth:`DataArray.quantile` issue the correct error + when ``q`` is out of bounds (:issue:`3634`) by `Mathias Hauser `_. + - Fix regression in xarray 0.14.1 that prevented encoding times with certain + ``dtype``, ``_FillValue``, and ``missing_value`` encodings (:issue:`3624`). + By `Spencer Clark `_ + - Raise an error when trying to use :py:meth:`Dataset.rename_dims` to + rename to an existing name (:issue:`3438`, :pull:`3645`) + By `Justus Magin `_. + - :py:meth:`Dataset.rename`, :py:meth:`DataArray.rename` now check for conflicts with + MultiIndex level names. + - :py:meth:`Dataset.merge` no longer fails when passed a :py:class:`DataArray` instead of a :py:class:`Dataset`. + By `Tom Nicholas `_. + - Fix a regression in :py:meth:`Dataset.drop`: allow passing any + iterable when dropping variables (:issue:`3552`, :pull:`3693`) + By `Justus Magin `_. + - Fixed errors emitted by ``mypy --strict`` in modules that import xarray. + (:issue:`3695`) by `Guido Imperiale `_. + - Allow plotting of binned coordinates on the y axis in :py:meth:`plot.line` + and :py:meth:`plot.step` plots (:issue:`3571`, + :pull:`3685`) by `Julien Seguinot `_. + - setuptools is now marked as a dependency of xarray + (:pull:`3628`) by `Richard Höchenberger `_. + + Documentation + ~~~~~~~~~~~~~ + - Switch doc examples to use `nbsphinx `_ and replace + ``sphinx_gallery`` scripts with Jupyter notebooks. (:pull:`3105`, :pull:`3106`, :pull:`3121`) + By `Ryan Abernathey `_. + - Added :doc:`example notebook ` demonstrating use of xarray with + Regional Ocean Modeling System (ROMS) ocean hydrodynamic model output. (:pull:`3116`) + By `Robert Hetland `_. + - Added :doc:`example notebook ` demonstrating the visualization of + ERA5 GRIB data. (:pull:`3199`) + By `Zach Bruick `_ and + `Stephan Siemen `_. + - Added examples for :py:meth:`DataArray.quantile`, :py:meth:`Dataset.quantile` and + ``GroupBy.quantile``. (:pull:`3576`) + By `Justus Magin `_. + - Add new :doc:`example notebook ` example notebook demonstrating + vectorization of a 1D function using :py:func:`apply_ufunc` , dask and numba. + By `Deepak Cherian `_. + - Added example for :py:func:`~xarray.map_blocks`. (:pull:`3667`) + By `Riley X. Brady `_. + + Internal Changes + ~~~~~~~~~~~~~~~~ + - Make sure dask names change when rechunking by different chunk sizes. Conversely, make sure they + stay the same when rechunking by the same chunk size. (:issue:`3350`) + By `Deepak Cherian `_. + - 2x to 5x speed boost (on small arrays) for :py:meth:`Dataset.isel`, + :py:meth:`DataArray.isel`, and :py:meth:`DataArray.__getitem__` when indexing by int, + slice, list of int, scalar ndarray, or 1-dimensional ndarray. + (:pull:`3533`) by `Guido Imperiale `_. + - Removed internal method ``Dataset._from_vars_and_coord_names``, + which was dominated by ``Dataset._construct_direct``. (:pull:`3565`) + By `Maximilian Roos `_. + - Replaced versioneer with setuptools-scm. Moved contents of setup.py to setup.cfg. + Removed pytest-runner from setup.py, as per deprecation notice on the pytest-runner + project. (:pull:`3714`) by `Guido Imperiale `_. + - Use of isort is now enforced by CI. + (:pull:`3721`) by `Guido Imperiale `_ + + + .. _whats-new.0.14.1: + + v0.14.1 (19 Nov 2019) + --------------------- + + Breaking changes + ~~~~~~~~~~~~~~~~ + + - Broken compatibility with ``cftime < 1.0.3`` . By `Deepak Cherian `_. + + .. warning:: + + cftime version 1.0.4 is broken + (`cftime/126 `_); + please use version 1.0.4.2 instead. + + - All leftover support for dates from non-standard calendars through ``netcdftime``, the + module included in versions of netCDF4 prior to 1.4 that eventually became the + `cftime `_ package, has been removed in favor of relying solely on + the standalone ``cftime`` package (:pull:`3450`). + By `Spencer Clark `_. + + New Features + ~~~~~~~~~~~~ + - Added the ``sparse`` option to :py:meth:`~xarray.DataArray.unstack`, + :py:meth:`~xarray.Dataset.unstack`, :py:meth:`~xarray.DataArray.reindex`, + :py:meth:`~xarray.Dataset.reindex` (:issue:`3518`). + By `Keisuke Fujii `_. + - Added the ``fill_value`` option to :py:meth:`DataArray.unstack` and + :py:meth:`Dataset.unstack` (:issue:`3518`, :pull:`3541`). + By `Keisuke Fujii `_. + - Added the ``max_gap`` kwarg to :py:meth:`~xarray.DataArray.interpolate_na` and + :py:meth:`~xarray.Dataset.interpolate_na`. This controls the maximum size of the data + gap that will be filled by interpolation. By `Deepak Cherian `_. + - Added :py:meth:`Dataset.drop_sel` & :py:meth:`DataArray.drop_sel` for dropping labels. + :py:meth:`Dataset.drop_vars` & :py:meth:`DataArray.drop_vars` have been added for + dropping variables (including coordinates). The existing :py:meth:`Dataset.drop` & + :py:meth:`DataArray.drop` methods remain as a backward compatible + option for dropping either labels or variables, but using the more specific methods is encouraged. + (:pull:`3475`) + By `Maximilian Roos `_ + - Added :py:meth:`Dataset.map` & ``GroupBy.map`` & ``Resample.map`` for + mapping / applying a function over each item in the collection, reflecting the widely used + and least surprising name for this operation. + The existing ``apply`` methods remain for backward compatibility, though using the ``map`` + methods is encouraged. + (:pull:`3459`) + By `Maximilian Roos `_ + - :py:meth:`Dataset.transpose` and :py:meth:`DataArray.transpose` now support an ellipsis (``...``) + to represent all 'other' dimensions. For example, to move one dimension to the front, + use ``.transpose('x', ...)``. (:pull:`3421`) + By `Maximilian Roos `_ + - Changed ``xr.ALL_DIMS`` to equal python's ``Ellipsis`` (``...``), and changed internal usages to use + ``...`` directly. As before, you can use this to instruct a ``groupby`` operation + to reduce over all dimensions. While we have no plans to remove ``xr.ALL_DIMS``, we suggest + using ``...``. (:pull:`3418`) + By `Maximilian Roos `_ + - :py:func:`xarray.dot`, and :py:meth:`DataArray.dot` now support the + ``dims=...`` option to sum over the union of dimensions of all input arrays + (:issue:`3423`) by `Mathias Hauser `_. + - Added new ``Dataset._repr_html_`` and ``DataArray._repr_html_`` to improve + representation of objects in Jupyter. By default this feature is turned off + for now. Enable it with ``xarray.set_options(display_style="html")``. + (:pull:`3425`) by `Benoit Bovy `_ and + `Julia Signell `_. + - Implement `dask deterministic hashing + `_ + for xarray objects. Note that xarray objects with a dask.array backend already used + deterministic hashing in previous releases; this change implements it when whole + xarray objects are embedded in a dask graph, e.g. when :py:meth:`DataArray.map_blocks` is + invoked. (:issue:`3378`, :pull:`3446`, :pull:`3515`) + By `Deepak Cherian `_ and + `Guido Imperiale `_. + - Add the documented-but-missing :py:meth:`~core.groupby.DatasetGroupBy.quantile`. + - xarray now respects the ``DataArray.encoding["coordinates"]`` attribute when writing to disk. + See :ref:`io.coordinates` for more. (:issue:`3351`, :pull:`3487`) + By `Deepak Cherian `_. + - Add the documented-but-missing :py:meth:`~core.groupby.DatasetGroupBy.quantile`. + (:issue:`3525`, :pull:`3527`). By `Justus Magin `_. + + Bug fixes + ~~~~~~~~~ + - Ensure an index of type ``CFTimeIndex`` is not converted to a ``DatetimeIndex`` when + calling :py:meth:`Dataset.rename`, :py:meth:`Dataset.rename_dims` and :py:meth:`Dataset.rename_vars`. + By `Mathias Hauser `_. (:issue:`3522`). + - Fix a bug in :py:meth:`DataArray.set_index` in case that an existing dimension becomes a level + variable of MultiIndex. (:pull:`3520`). By `Keisuke Fujii `_. + - Harmonize ``_FillValue``, ``missing_value`` during encoding and decoding steps. (:pull:`3502`) + By `Anderson Banihirwe `_. + - Fix regression introduced in v0.14.0 that would cause a crash if dask is installed + but cloudpickle isn't (:issue:`3401`) by `Rhys Doyle `_ + - Fix grouping over variables with NaNs. (:issue:`2383`, :pull:`3406`). + By `Deepak Cherian `_. + - Make alignment and concatenation significantly more efficient by using dask names to compare dask + objects prior to comparing values after computation. This change makes it more convenient to carry + around large non-dimensional coordinate variables backed by dask arrays. Existing workarounds involving + ``reset_coords(drop=True)`` should now be unnecessary in most cases. + (:issue:`3068`, :issue:`3311`, :issue:`3454`, :pull:`3453`). + By `Deepak Cherian `_. + - Add support for cftime>=1.0.4. By `Anderson Banihirwe `_. + - Rolling reduction operations no longer compute dask arrays by default. (:issue:`3161`). + In addition, the ``allow_lazy`` kwarg to ``reduce`` is deprecated. + By `Deepak Cherian `_. + - Fix ``GroupBy.reduce`` when reducing over multiple dimensions. + (:issue:`3402`). By `Deepak Cherian `_ + - Allow appending datetime and bool data variables to zarr stores. + (:issue:`3480`). By `Akihiro Matsukawa `_. + - Add support for numpy >=1.18 (); bugfix mean() on datetime64 arrays on dask backend + (:issue:`3409`, :pull:`3537`). By `Guido Imperiale `_. + - Add support for pandas >=0.26 (:issue:`3440`). + By `Deepak Cherian `_. + - Add support for pseudonetcdf >=3.1 (:pull:`3485`). + By `Barron Henderson `_. + + Documentation + ~~~~~~~~~~~~~ + - Fix leap year condition in `monthly means example `_. + By `Mickaël Lalande `_. + - Fix the documentation of :py:meth:`DataArray.resample` and + :py:meth:`Dataset.resample`, explicitly stating that a + datetime-like dimension is required. (:pull:`3400`) + By `Justus Magin `_. + - Update the :ref:`terminology` page to address multidimensional coordinates. (:pull:`3410`) + By `Jon Thielen `_. + - Fix the documentation of :py:meth:`Dataset.integrate` and + :py:meth:`DataArray.integrate` and add an example to + :py:meth:`Dataset.integrate`. (:pull:`3469`) + By `Justus Magin `_. + + Internal Changes + ~~~~~~~~~~~~~~~~ + + - Added integration tests against `pint `_. + (:pull:`3238`, :pull:`3447`, :pull:`3493`, :pull:`3508`) + by `Justus Magin `_. + + .. note:: + + At the moment of writing, these tests *as well as the ability to use pint in general* + require `a highly experimental version of pint + `_ (install with + ``pip install git+https://github.com/andrewgsavage/pint.git@refs/pull/6/head)``. + Even with it, interaction with non-numpy array libraries, e.g. dask or sparse, is broken. + + - Use Python 3.6 idioms throughout the codebase. (:pull:`3419`) + By `Maximilian Roos `_ + + - Run basic CI tests on Python 3.8. (:pull:`3477`) + By `Maximilian Roos `_ + + - Enable type checking on default sentinel values (:pull:`3472`) + By `Maximilian Roos `_ + + - Add ``Variable._replace`` for simpler replacing of a subset of attributes (:pull:`3472`) + By `Maximilian Roos `_ + + .. _whats-new.0.14.0: + + v0.14.0 (14 Oct 2019) + --------------------- + + Breaking changes + ~~~~~~~~~~~~~~~~ + - This release introduces a rolling policy for minimum dependency versions: + :ref:`mindeps_policy`. + + Several minimum versions have been increased: + + ============ ================== ==== + Package Old New + ============ ================== ==== + Python 3.5.3 3.6 + numpy 1.12 1.14 + pandas 0.19.2 0.24 + dask 0.16 (tested: 2.4) 1.2 + bottleneck 1.1 (tested: 1.2) 1.2 + matplotlib 1.5 (tested: 3.1) 3.1 + ============ ================== ==== + + Obsolete patch versions (x.y.Z) are not tested anymore. + The oldest supported versions of all optional dependencies are now covered by + automated tests (before, only the very latest versions were tested). + + (:issue:`3222`, :issue:`3293`, :issue:`3340`, :issue:`3346`, :issue:`3358`). + By `Guido Imperiale `_. + + - Dropped the ``drop=False`` optional parameter from :py:meth:`Variable.isel`. + It was unused and doesn't make sense for a Variable. (:pull:`3375`). + By `Guido Imperiale `_. + + - Remove internal usage of :py:class:`collections.OrderedDict`. After dropping support for + Python <=3.5, most uses of ``OrderedDict`` in Xarray were no longer necessary. We + have removed the internal use of the ``OrderedDict`` in favor of Python's builtin + ``dict`` object which is now ordered itself. This change will be most obvious when + interacting with the ``attrs`` property on Dataset and DataArray objects. + (:issue:`3380`, :pull:`3389`). By `Joe Hamman `_. + + New functions/methods + ~~~~~~~~~~~~~~~~~~~~~ + + - Added :py:func:`~xarray.map_blocks`, modeled after :py:func:`dask.array.map_blocks`. + Also added :py:meth:`Dataset.unify_chunks`, :py:meth:`DataArray.unify_chunks` and + :py:meth:`testing.assert_chunks_equal`. (:pull:`3276`). + By `Deepak Cherian `_ and + `Guido Imperiale `_. + + Enhancements + ~~~~~~~~~~~~ + + - ``core.groupby.GroupBy`` enhancements. By `Deepak Cherian `_. + + - Added a repr (:pull:`3344`). Example:: + + >>> da.groupby("time.season") + DataArrayGroupBy, grouped over 'season' + 4 groups with labels 'DJF', 'JJA', 'MAM', 'SON' + + - Added a ``GroupBy.dims`` property that mirrors the dimensions + of each group (:issue:`3344`). + + - Speed up :py:meth:`Dataset.isel` up to 33% and :py:meth:`DataArray.isel` up to 25% for small + arrays (:issue:`2799`, :pull:`3375`). By + `Guido Imperiale `_. + + Bug fixes + ~~~~~~~~~ + - Reintroduce support for :mod:`weakref` (broken in v0.13.0). Support has been + reinstated for :py:class:`~xarray.DataArray` and :py:class:`~xarray.Dataset` objects only. + Internal xarray objects remain unaddressable by weakref in order to save memory + (:issue:`3317`). By `Guido Imperiale `_. + - Line plots with the ``x`` or ``y`` argument set to a 1D non-dimensional coord + now plot the correct data for 2D DataArrays + (:issue:`3334`). By `Tom Nicholas `_. + - Make :py:func:`~xarray.concat` more robust when merging variables present in some datasets but + not others (:issue:`508`). By `Deepak Cherian `_. + - The default behaviour of reducing across all dimensions for + :py:class:`~xarray.core.groupby.DataArrayGroupBy` objects has now been properly removed + as was done for :py:class:`~xarray.core.groupby.DatasetGroupBy` in 0.13.0 (:issue:`3337`). + Use ``xarray.ALL_DIMS`` if you need to replicate previous behaviour. + Also raise nicer error message when no groups are created (:issue:`1764`). + By `Deepak Cherian `_. + - Fix error in concatenating unlabeled dimensions (:pull:`3362`). + By `Deepak Cherian `_. + - Warn if the ``dim`` kwarg is passed to rolling operations. This is redundant since a dimension is + specified when the :py:class:`~core.rolling.DatasetRolling` or :py:class:`~core.rolling.DataArrayRolling` object is created. + (:pull:`3362`). By `Deepak Cherian `_. + + Documentation + ~~~~~~~~~~~~~ + + - Created a glossary of important xarray terms (:issue:`2410`, :pull:`3352`). + By `Gregory Gundersen `_. + - Created a "How do I..." section (:ref:`howdoi`) for solutions to common questions. (:pull:`3357`). + By `Deepak Cherian `_. + - Add examples for :py:meth:`Dataset.swap_dims` and :py:meth:`DataArray.swap_dims` + (pull:`3331`, pull:`3331`). By `Justus Magin `_. + - Add examples for :py:meth:`align`, :py:meth:`merge`, :py:meth:`combine_by_coords`, + :py:meth:`full_like`, :py:meth:`zeros_like`, :py:meth:`ones_like`, :py:meth:`Dataset.pipe`, + :py:meth:`Dataset.assign`, :py:meth:`Dataset.reindex`, :py:meth:`Dataset.fillna` (:pull:`3328`). + By `Anderson Banihirwe `_. + - Fixed documentation to clean up an unwanted file created in ``ipython`` example + (:pull:`3353`). By `Gregory Gundersen `_. + + .. _whats-new.0.13.0: + + v0.13.0 (17 Sep 2019) + --------------------- + + This release includes many exciting changes: wrapping of + `NEP18 `_ compliant + numpy-like arrays; new :py:meth:`~Dataset.plot.scatter` plotting method that can scatter + two ``DataArrays`` in a ``Dataset`` against each other; support for converting pandas + DataFrames to xarray objects that wrap ``pydata/sparse``; and more! + + Breaking changes + ~~~~~~~~~~~~~~~~ + + - This release increases the minimum required Python version from 3.5.0 to 3.5.3 + (:issue:`3089`). By `Guido Imperiale `_. + - The ``isel_points`` and ``sel_points`` methods are removed, having been deprecated + since v0.10.0. These are redundant with the ``isel`` / ``sel`` methods. + See :ref:`vectorized_indexing` for the details + By `Maximilian Roos `_ + - The ``inplace`` kwarg for public methods now raises an error, having been deprecated + since v0.11.0. + By `Maximilian Roos `_ + - :py:func:`~xarray.concat` now requires the ``dim`` argument. Its ``indexers``, ``mode`` + and ``concat_over`` kwargs have now been removed. + By `Deepak Cherian `_ + - Passing a list of colors in ``cmap`` will now raise an error, having been deprecated since + v0.6.1. + - Most xarray objects now define ``__slots__``. This reduces overall RAM usage by ~22% + (not counting the underlying numpy buffers); on CPython 3.7/x64, a trivial DataArray + has gone down from 1.9kB to 1.5kB. + + Caveats: + + - Pickle streams produced by older versions of xarray can't be loaded using this + release, and vice versa. + - Any user code that was accessing the ``__dict__`` attribute of + xarray objects will break. The best practice to attach custom metadata to xarray + objects is to use the ``attrs`` dictionary. + - Any user code that defines custom subclasses of xarray classes must now explicitly + define ``__slots__`` itself. Subclasses that don't add any attributes must state so + by defining ``__slots__ = ()`` right after the class header. + Omitting ``__slots__`` will now cause a ``FutureWarning`` to be logged, and will raise an + error in a later release. + + (:issue:`3250`) by `Guido Imperiale `_. + - The default dimension for :py:meth:`Dataset.groupby`, :py:meth:`Dataset.resample`, + :py:meth:`DataArray.groupby` and :py:meth:`DataArray.resample` reductions is now the + grouping or resampling dimension. + - :py:meth:`DataArray.to_dataset` requires ``name`` to be passed as a kwarg (previously ambiguous + positional arguments were deprecated) + - Reindexing with variables of a different dimension now raise an error (previously deprecated) + - ``xarray.broadcast_array`` is removed (previously deprecated in favor of + :py:func:`~xarray.broadcast`) + - ``Variable.expand_dims`` is removed (previously deprecated in favor of + :py:meth:`Variable.set_dims`) + + New functions/methods + ~~~~~~~~~~~~~~~~~~~~~ + + - xarray can now wrap around any + `NEP18 `_ compliant + numpy-like library (important: read notes about ``NUMPY_EXPERIMENTAL_ARRAY_FUNCTION`` in + the above link). Added explicit test coverage for + `sparse `_. (:issue:`3117`, :issue:`3202`). + This requires `sparse>=0.8.0`. By `Nezar Abdennur `_ + and `Guido Imperiale `_. + + - :py:meth:`~Dataset.from_dataframe` and :py:meth:`~DataArray.from_series` now + support ``sparse=True`` for converting pandas objects into xarray objects + wrapping sparse arrays. This is particularly useful with sparsely populated + hierarchical indexes. (:issue:`3206`) + By `Stephan Hoyer `_. + + - The xarray package is now discoverable by mypy (although typing hints coverage is not + complete yet). mypy type checking is now enforced by CI. Libraries that depend on + xarray and use mypy can now remove from their setup.cfg the lines:: + + [mypy-xarray] + ignore_missing_imports = True + + (:issue:`2877`, :issue:`3088`, :issue:`3090`, :issue:`3112`, :issue:`3117`, + :issue:`3207`) + By `Guido Imperiale `_ + and `Maximilian Roos `_. + + - Added :py:meth:`DataArray.broadcast_like` and :py:meth:`Dataset.broadcast_like`. + By `Deepak Cherian `_ and `David Mertz + `_. + + - Dataset plotting API for visualizing dependencies between two DataArrays! + Currently only :py:meth:`Dataset.plot.scatter` is implemented. + By `Yohai Bar Sinai `_ and `Deepak Cherian `_ + + - Added :py:meth:`DataArray.head`, :py:meth:`DataArray.tail` and :py:meth:`DataArray.thin`; + as well as :py:meth:`Dataset.head`, :py:meth:`Dataset.tail` and :py:meth:`Dataset.thin` methods. + (:issue:`319`) By `Gerardo Rivera `_. + + Enhancements + ~~~~~~~~~~~~ + + - Multiple enhancements to :py:func:`~xarray.concat` and :py:func:`~xarray.open_mfdataset`. + By `Deepak Cherian `_ + + - Added ``compat='override'``. When merging, this option picks the variable from the first dataset + and skips all comparisons. + + - Added ``join='override'``. When aligning, this only checks that index sizes are equal among objects + and skips checking indexes for equality. + + - :py:func:`~xarray.concat` and :py:func:`~xarray.open_mfdataset` now support the ``join`` kwarg. + It is passed down to :py:func:`~xarray.align`. + + - :py:func:`~xarray.concat` now calls :py:func:`~xarray.merge` on variables that are not concatenated + (i.e. variables without ``concat_dim`` when ``data_vars`` or ``coords`` are ``"minimal"``). + :py:func:`~xarray.concat` passes its new ``compat`` kwarg down to :py:func:`~xarray.merge`. + (:issue:`2064`) + + Users can avoid a common bottleneck when using :py:func:`~xarray.open_mfdataset` on a large number of + files with variables that are known to be aligned and some of which need not be concatenated. + Slow equality comparisons can now be avoided, for e.g.:: + + data = xr.open_mfdataset(files, concat_dim='time', data_vars='minimal', + coords='minimal', compat='override', join='override') + + - In :py:meth:`~xarray.Dataset.to_zarr`, passing ``mode`` is not mandatory if + ``append_dim`` is set, as it will automatically be set to ``'a'`` internally. + By `David Brochart `_. + + - Added the ability to initialize an empty or full DataArray + with a single value. (:issue:`277`) + By `Gerardo Rivera `_. + + - :py:func:`~xarray.Dataset.to_netcdf()` now supports the ``invalid_netcdf`` kwarg when used + with ``engine="h5netcdf"``. It is passed to ``h5netcdf.File``. + By `Ulrich Herter `_. + + - ``xarray.Dataset.drop`` now supports keyword arguments; dropping index + labels by using both ``dim`` and ``labels`` or using a + :py:class:`~core.coordinates.DataArrayCoordinates` object are deprecated (:issue:`2910`). + By `Gregory Gundersen `_. + + - Added examples of :py:meth:`Dataset.set_index` and + :py:meth:`DataArray.set_index`, as well are more specific error messages + when the user passes invalid arguments (:issue:`3176`). + By `Gregory Gundersen `_. + + - :py:meth:`Dataset.filter_by_attrs` now filters the coordinates as well as the variables. + By `Spencer Jones `_. + + Bug fixes + ~~~~~~~~~ + + - Improve "missing dimensions" error message for :py:func:`~xarray.apply_ufunc` + (:issue:`2078`). + By `Rick Russotto `_. + - :py:meth:`~xarray.DataArray.assign_coords` now supports dictionary arguments + (:issue:`3231`). + By `Gregory Gundersen `_. + - Fix regression introduced in v0.12.2 where ``copy(deep=True)`` would convert + unicode indices to dtype=object (:issue:`3094`). + By `Guido Imperiale `_. + - Improved error handling and documentation for `.expand_dims()` + read-only view. + - Fix tests for big-endian systems (:issue:`3125`). + By `Graham Inggs `_. + - XFAIL several tests which are expected to fail on ARM systems + due to a ``datetime`` issue in NumPy (:issue:`2334`). + By `Graham Inggs `_. + - Fix KeyError that arises when using .sel method with float values + different from coords float type (:issue:`3137`). + By `Hasan Ahmad `_. + - Fixed bug in ``combine_by_coords()`` causing a `ValueError` if the input had + an unused dimension with coordinates which were not monotonic (:issue:`3150`). + By `Tom Nicholas `_. + - Fixed crash when applying ``distributed.Client.compute()`` to a DataArray + (:issue:`3171`). By `Guido Imperiale `_. + - Better error message when using groupby on an empty DataArray (:issue:`3037`). + By `Hasan Ahmad `_. + - Fix error that arises when using open_mfdataset on a series of netcdf files + having differing values for a variable attribute of type list. (:issue:`3034`) + By `Hasan Ahmad `_. + - Prevent :py:meth:`~xarray.DataArray.argmax` and :py:meth:`~xarray.DataArray.argmin` from calling + dask compute (:issue:`3237`). By `Ulrich Herter `_. + - Plots in 2 dimensions (pcolormesh, contour) now allow to specify levels as numpy + array (:issue:`3284`). By `Mathias Hauser `_. + - Fixed bug in :meth:`DataArray.quantile` failing to keep attributes when + `keep_attrs` was True (:issue:`3304`). By `David Huard `_. + + Documentation + ~~~~~~~~~~~~~ + + - Created a `PR checklist `_ + as a quick reference for tasks before creating a new PR + or pushing new commits. + By `Gregory Gundersen `_. + + - Fixed documentation to clean up unwanted files created in ``ipython`` examples + (:issue:`3227`). + By `Gregory Gundersen `_. + + .. _whats-new.0.12.3: + + v0.12.3 (10 July 2019) + ---------------------- + + New functions/methods + ~~~~~~~~~~~~~~~~~~~~~ + + - New methods :py:meth:`Dataset.to_stacked_array` and + :py:meth:`DataArray.to_unstacked_dataset` for reshaping Datasets of variables + with different dimensions + (:issue:`1317`). + This is useful for feeding data from xarray into machine learning models, + as described in :ref:`reshape.stacking_different`. + By `Noah Brenowitz `_. + + Enhancements + ~~~~~~~~~~~~ + + - Support for renaming ``Dataset`` variables and dimensions independently + with :py:meth:`~Dataset.rename_vars` and :py:meth:`~Dataset.rename_dims` + (:issue:`3026`). + By `Julia Kent `_. + + - Add ``scales``, ``offsets``, ``units`` and ``descriptions`` + attributes to :py:class:`~xarray.DataArray` returned by + :py:func:`~xarray.open_rasterio`. (:issue:`3013`) + By `Erle Carrara `_. + + Bug fixes + ~~~~~~~~~ + + - Resolved deprecation warnings from newer versions of matplotlib and dask. + - Compatibility fixes for the upcoming pandas 0.25 and NumPy 1.17 releases. + By `Stephan Hoyer `_. + - Fix summaries for multiindex coordinates (:issue:`3079`). + By `Jonas Hörsch `_. + - Fix HDF5 error that could arise when reading multiple groups from a file at + once (:issue:`2954`). + By `Stephan Hoyer `_. + + .. _whats-new.0.12.2: + + v0.12.2 (29 June 2019) + ---------------------- + + New functions/methods + ~~~~~~~~~~~~~~~~~~~~~ + + - Two new functions, :py:func:`~xarray.combine_nested` and + :py:func:`~xarray.combine_by_coords`, allow for combining datasets along any + number of dimensions, instead of the one-dimensional list of datasets + supported by :py:func:`~xarray.concat`. + + The new ``combine_nested`` will accept the datasets as a nested + list-of-lists, and combine by applying a series of concat and merge + operations. The new ``combine_by_coords`` instead uses the dimension + coordinates of datasets to order them. + + :py:func:`~xarray.open_mfdataset` can use either ``combine_nested`` or + ``combine_by_coords`` to combine datasets along multiple dimensions, by + specifying the argument ``combine='nested'`` or ``combine='by_coords'``. + + The older function ``auto_combine`` has been deprecated, + because its functionality has been subsumed by the new functions. + To avoid FutureWarnings switch to using ``combine_nested`` or + ``combine_by_coords``, (or set the ``combine`` argument in + ``open_mfdataset``). (:issue:`2159`) + By `Tom Nicholas `_. + + - :py:meth:`~xarray.DataArray.rolling_exp` and + :py:meth:`~xarray.Dataset.rolling_exp` added, similar to pandas' + ``pd.DataFrame.ewm`` method. Calling ``.mean`` on the resulting object + will return an exponentially weighted moving average. + By `Maximilian Roos `_. + + - New :py:func:`DataArray.str ` for string + related manipulations, based on ``pandas.Series.str``. + By `0x0L `_. + + - Added ``strftime`` method to ``.dt`` accessor, making it simpler to hand a + datetime ``DataArray`` to other code expecting formatted dates and times. + (:issue:`2090`). :py:meth:`~xarray.CFTimeIndex.strftime` is also now + available on :py:class:`CFTimeIndex`. + By `Alan Brammer `_ and + `Ryan May `_. + + - ``GroupBy.quantile`` is now a method of ``GroupBy`` + objects (:issue:`3018`). + By `David Huard `_. + + - Argument and return types are added to most methods on ``DataArray`` and + ``Dataset``, allowing static type checking both within xarray and external + libraries. Type checking with `mypy `_ is enabled in + CI (though not required yet). + By `Guido Imperiale `_ + and `Maximilian Roos `_. + + Enhancements to existing functionality + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + - Add ``keepdims`` argument for reduce operations (:issue:`2170`) + By `Scott Wales `_. + - Enable ``@`` operator for DataArray. This is equivalent to :py:meth:`DataArray.dot` + By `Maximilian Roos `_. + - Add ``fill_value`` argument for reindex, align, and merge operations + to enable custom fill values. (:issue:`2876`) + By `Zach Griffith `_. + - :py:meth:`DataArray.transpose` now accepts a keyword argument + ``transpose_coords`` which enables transposition of coordinates in the + same way as :py:meth:`Dataset.transpose`. :py:meth:`DataArray.groupby` + :py:meth:`DataArray.groupby_bins`, and :py:meth:`DataArray.resample` now + accept a keyword argument ``restore_coord_dims`` which keeps the order + of the dimensions of multi-dimensional coordinates intact (:issue:`1856`). + By `Peter Hausamann `_. + - Clean up Python 2 compatibility in code (:issue:`2950`) + By `Guido Imperiale `_. + - Better warning message when supplying invalid objects to ``xr.merge`` + (:issue:`2948`). By `Mathias Hauser `_. + - Add ``errors`` keyword argument to ``Dataset.drop`` and :py:meth:`Dataset.drop_dims` + that allows ignoring errors if a passed label or dimension is not in the dataset + (:issue:`2994`). + By `Andrew Ross `_. + + IO related enhancements + ~~~~~~~~~~~~~~~~~~~~~~~ + + - Implement :py:func:`~xarray.load_dataset` and + :py:func:`~xarray.load_dataarray` as alternatives to + :py:func:`~xarray.open_dataset` and :py:func:`~xarray.open_dataarray` to + open, load into memory, and close files, returning the Dataset or DataArray. + These functions are helpful for avoiding file-lock errors when trying to + write to files opened using ``open_dataset()`` or ``open_dataarray()``. + (:issue:`2887`) + By `Dan Nowacki `_. + - It is now possible to extend existing :ref:`io.zarr` datasets, by using + ``mode='a'`` and the new ``append_dim`` argument in + :py:meth:`~xarray.Dataset.to_zarr`. + By `Jendrik Jördening `_, + `David Brochart `_, + `Ryan Abernathey `_ and + `Shikhar Goenka `_. + - ``xr.open_zarr`` now accepts manually specified chunks with the ``chunks=`` + parameter. ``auto_chunk=True`` is equivalent to ``chunks='auto'`` for + backwards compatibility. The ``overwrite_encoded_chunks`` parameter is + added to remove the original zarr chunk encoding. + By `Lily Wang `_. + - netCDF chunksizes are now only dropped when original_shape is different, + not when it isn't found. (:issue:`2207`) + By `Karel van de Plassche `_. + - Character arrays' character dimension name decoding and encoding handled by + ``var.encoding['char_dim_name']`` (:issue:`2895`) + By `James McCreight `_. + - open_rasterio() now supports rasterio.vrt.WarpedVRT with custom transform, + width and height (:issue:`2864`). + By `Julien Michel `_. + + Bug fixes + ~~~~~~~~~ + + - Rolling operations on xarray objects containing dask arrays could silently + compute the incorrect result or use large amounts of memory (:issue:`2940`). + By `Stephan Hoyer `_. + - Don't set encoding attributes on bounds variables when writing to netCDF. + (:issue:`2921`) + By `Deepak Cherian `_. + - NetCDF4 output: variables with unlimited dimensions must be chunked (not + contiguous) on output. (:issue:`1849`) + By `James McCreight `_. + - indexing with an empty list creates an object with zero-length axis (:issue:`2882`) + By `Mayeul d'Avezac `_. + - Return correct count for scalar datetime64 arrays (:issue:`2770`) + By `Dan Nowacki `_. + - Fixed max, min exception when applied to a multiIndex (:issue:`2923`) + By `Ian Castleden `_ + - A deep copy deep-copies the coords (:issue:`1463`) + By `Martin Pletcher `_. + - Increased support for `missing_value` (:issue:`2871`) + By `Deepak Cherian `_. + - Removed usages of `pytest.config`, which is deprecated (:issue:`2988`) + By `Maximilian Roos `_. + - Fixed performance issues with cftime installed (:issue:`3000`) + By `0x0L `_. + - Replace incorrect usages of `message` in pytest assertions + with `match` (:issue:`3011`) + By `Maximilian Roos `_. + - Add explicit pytest markers, now required by pytest + (:issue:`3032`). + By `Maximilian Roos `_. + - Test suite fixes for newer versions of pytest (:issue:`3011`, :issue:`3032`). + By `Maximilian Roos `_ + and `Stephan Hoyer `_. + + .. _whats-new.0.12.1: + + v0.12.1 (4 April 2019) + ---------------------- + + Enhancements + ~~~~~~~~~~~~ + + - Allow ``expand_dims`` method to support inserting/broadcasting dimensions + with size > 1. (:issue:`2710`) + By `Martin Pletcher `_. + + Bug fixes + ~~~~~~~~~ + + - Dataset.copy(deep=True) now creates a deep copy of the attrs (:issue:`2835`). + By `Andras Gefferth `_. + - Fix incorrect ``indexes`` resulting from various ``Dataset`` operations + (e.g., ``swap_dims``, ``isel``, ``reindex``, ``[]``) (:issue:`2842`, + :issue:`2856`). + By `Stephan Hoyer `_. + + .. _whats-new.0.12.0: + + v0.12.0 (15 March 2019) + ----------------------- + + Highlights include: + + - Removed support for Python 2. This is the first version of xarray that is + Python 3 only! + - New :py:meth:`~xarray.DataArray.coarsen` and + :py:meth:`~xarray.DataArray.integrate` methods. See :ref:`comput.coarsen` + and :ref:`compute.using_coordinates` for details. + - Many improvements to cftime support. See below for details. + + Deprecations + ~~~~~~~~~~~~ + + - The ``compat`` argument to ``Dataset`` and the ``encoding`` argument to + ``DataArray`` are deprecated and will be removed in a future release. + (:issue:`1188`) + By `Maximilian Roos `_. + + cftime related enhancements + ~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + - Resampling of standard and non-standard calendars indexed by + :py:class:`~xarray.CFTimeIndex` is now possible. (:issue:`2191`). + By `Jwen Fai Low `_ and + `Spencer Clark `_. + + - Taking the mean of arrays of :py:class:`cftime.datetime` objects, and + by extension, use of :py:meth:`~xarray.DataArray.coarsen` with + :py:class:`cftime.datetime` coordinates is now possible. By `Spencer Clark + `_. + + - Internal plotting now supports ``cftime.datetime`` objects as time series. + (:issue:`2164`) + By `Julius Busecke `_ and + `Spencer Clark `_. + + - :py:meth:`~xarray.cftime_range` now supports QuarterBegin and QuarterEnd offsets (:issue:`2663`). + By `Jwen Fai Low `_ + + - :py:meth:`~xarray.open_dataset` now accepts a ``use_cftime`` argument, which + can be used to require that ``cftime.datetime`` objects are always used, or + never used when decoding dates encoded with a standard calendar. This can be + used to ensure consistent date types are returned when using + :py:meth:`~xarray.open_mfdataset` (:issue:`1263`) and/or to silence + serialization warnings raised if dates from a standard calendar are found to + be outside the :py:class:`pandas.Timestamp`-valid range (:issue:`2754`). By + `Spencer Clark `_. + + - :py:meth:`pandas.Series.dropna` is now supported for a + :py:class:`pandas.Series` indexed by a :py:class:`~xarray.CFTimeIndex` + (:issue:`2688`). By `Spencer Clark `_. + + Other enhancements + ~~~~~~~~~~~~~~~~~~ + + - Added ability to open netcdf4/hdf5 file-like objects with ``open_dataset``. + Requires (h5netcdf>0.7 and h5py>2.9.0). (:issue:`2781`) + By `Scott Henderson `_ + - Add ``data=False`` option to ``to_dict()`` methods. (:issue:`2656`) + By `Ryan Abernathey `_ + - :py:meth:`DataArray.coarsen` and + :py:meth:`Dataset.coarsen` are newly added. + See :ref:`comput.coarsen` for details. + (:issue:`2525`) + By `Keisuke Fujii `_. + - Upsampling an array via interpolation with resample is now dask-compatible, + as long as the array is not chunked along the resampling dimension. + By `Spencer Clark `_. + - :py:func:`xarray.testing.assert_equal` and + :py:func:`xarray.testing.assert_identical` now provide a more detailed + report showing what exactly differs between the two objects (dimensions / + coordinates / variables / attributes) (:issue:`1507`). + By `Benoit Bovy `_. + - Add ``tolerance`` option to ``resample()`` methods ``bfill``, ``pad``, + ``nearest``. (:issue:`2695`) + By `Hauke Schulz `_. + - :py:meth:`DataArray.integrate` and + :py:meth:`Dataset.integrate` are newly added. + See :ref:`compute.using_coordinates` for the detail. + (:issue:`1332`) + By `Keisuke Fujii `_. + - Added :py:meth:`~xarray.Dataset.drop_dims` (:issue:`1949`). + By `Kevin Squire `_. + + Bug fixes + ~~~~~~~~~ + + - Silenced warnings that appear when using pandas 0.24. + By `Stephan Hoyer `_ + - Interpolating via resample now internally specifies ``bounds_error=False`` + as an argument to ``scipy.interpolate.interp1d``, allowing for interpolation + from higher frequencies to lower frequencies. Datapoints outside the bounds + of the original time coordinate are now filled with NaN (:issue:`2197`). By + `Spencer Clark `_. + - Line plots with the ``x`` argument set to a non-dimensional coord now plot + the correct data for 1D DataArrays. + (:issue:`2725`). By `Tom Nicholas `_. + - Subtracting a scalar ``cftime.datetime`` object from a + :py:class:`CFTimeIndex` now results in a :py:class:`pandas.TimedeltaIndex` + instead of raising a ``TypeError`` (:issue:`2671`). By `Spencer Clark + `_. + - backend_kwargs are no longer ignored when using open_dataset with pynio engine + (:issue:'2380') + By `Jonathan Joyce `_. + - Fix ``open_rasterio`` creating a WKT CRS instead of PROJ.4 with + ``rasterio`` 1.0.14+ (:issue:`2715`). + By `David Hoese `_. + - Masking data arrays with :py:meth:`xarray.DataArray.where` now returns an + array with the name of the original masked array (:issue:`2748` and :issue:`2457`). + By `Yohai Bar-Sinai `_. + - Fixed error when trying to reduce a DataArray using a function which does not + require an axis argument. (:issue:`2768`) + By `Tom Nicholas `_. + - Concatenating a sequence of :py:class:`~xarray.DataArray` with varying names + sets the name of the output array to ``None``, instead of the name of the + first input array. If the names are the same it sets the name to that, + instead to the name of the first DataArray in the list as it did before. + (:issue:`2775`). By `Tom Nicholas `_. + + - Per the `CF conventions section on calendars + `_, + specifying ``'standard'`` as the calendar type in + :py:meth:`~xarray.cftime_range` now correctly refers to the ``'gregorian'`` + calendar instead of the ``'proleptic_gregorian'`` calendar (:issue:`2761`). + + .. _whats-new.0.11.3: + + v0.11.3 (26 January 2019) + ------------------------- + + Bug fixes + ~~~~~~~~~ + + - Saving files with times encoded with reference dates with timezones + (e.g. '2000-01-01T00:00:00-05:00') no longer raises an error + (:issue:`2649`). By `Spencer Clark `_. + - Fixed performance regression with ``open_mfdataset`` (:issue:`2662`). + By `Tom Nicholas `_. + - Fixed supplying an explicit dimension in the ``concat_dim`` argument to + to ``open_mfdataset`` (:issue:`2647`). + By `Ben Root `_. + + .. _whats-new.0.11.2: + + v0.11.2 (2 January 2019) + ------------------------ + + Removes inadvertently introduced setup dependency on pytest-runner + (:issue:`2641`). Otherwise, this release is exactly equivalent to 0.11.1. + + .. warning:: + + This is the last xarray release that will support Python 2.7. Future releases + will be Python 3 only, but older versions of xarray will always be available + for Python 2.7 users. For the more details, see: + + - `Xarray Github issue discussing dropping Python 2 `__ + - `Python 3 Statement `__ + - `Tips on porting to Python 3 `__ + + .. _whats-new.0.11.1: + + v0.11.1 (29 December 2018) + -------------------------- + + This minor release includes a number of enhancements and bug fixes, and two + (slightly) breaking changes. + + Breaking changes + ~~~~~~~~~~~~~~~~ + + - Minimum rasterio version increased from 0.36 to 1.0 (for ``open_rasterio``) + - Time bounds variables are now also decoded according to CF conventions + (:issue:`2565`). The previous behavior was to decode them only if they + had specific time attributes, now these attributes are copied + automatically from the corresponding time coordinate. This might + break downstream code that was relying on these variables to be + brake downstream code that was relying on these variables to be + not decoded. + By `Fabien Maussion `_. + + Enhancements + ~~~~~~~~~~~~ + + - Ability to read and write consolidated metadata in zarr stores (:issue:`2558`). + By `Ryan Abernathey `_. + - :py:class:`CFTimeIndex` uses slicing for string indexing when possible (like + :py:class:`pandas.DatetimeIndex`), which avoids unnecessary copies. + By `Stephan Hoyer `_ + - Enable passing ``rasterio.io.DatasetReader`` or ``rasterio.vrt.WarpedVRT`` to + ``open_rasterio`` instead of file path string. Allows for in-memory + reprojection, see (:issue:`2588`). + By `Scott Henderson `_. + - Like :py:class:`pandas.DatetimeIndex`, :py:class:`CFTimeIndex` now supports + "dayofyear" and "dayofweek" accessors (:issue:`2597`). Note this requires a + version of cftime greater than 1.0.2. By `Spencer Clark + `_. + - The option ``'warn_for_unclosed_files'`` (False by default) has been added to + allow users to enable a warning when files opened by xarray are deallocated + but were not explicitly closed. This is mostly useful for debugging; we + recommend enabling it in your test suites if you use xarray for IO. + By `Stephan Hoyer `_ + - Support Dask ``HighLevelGraphs`` by `Matthew Rocklin `_. + - :py:meth:`DataArray.resample` and :py:meth:`Dataset.resample` now supports the + ``loffset`` kwarg just like Pandas. + By `Deepak Cherian `_ + - Datasets are now guaranteed to have a ``'source'`` encoding, so the source + file name is always stored (:issue:`2550`). + By `Tom Nicholas `_. + - The ``apply`` methods for ``DatasetGroupBy``, ``DataArrayGroupBy``, + ``DatasetResample`` and ``DataArrayResample`` now support passing positional + arguments to the applied function as a tuple to the ``args`` argument. + By `Matti Eskelinen `_. + - 0d slices of ndarrays are now obtained directly through indexing, rather than + extracting and wrapping a scalar, avoiding unnecessary copying. By `Daniel + Wennberg `_. + - Added support for ``fill_value`` with + :py:meth:`~xarray.DataArray.shift` and :py:meth:`~xarray.Dataset.shift` + By `Maximilian Roos `_ + + Bug fixes + ~~~~~~~~~ + + - Ensure files are automatically closed, if possible, when no longer referenced + by a Python variable (:issue:`2560`). + By `Stephan Hoyer `_ + - Fixed possible race conditions when reading/writing to disk in parallel + (:issue:`2595`). + By `Stephan Hoyer `_ + - Fix h5netcdf saving scalars with filters or chunks (:issue:`2563`). + By `Martin Raspaud `_. + - Fix parsing of ``_Unsigned`` attribute set by OPENDAP servers. (:issue:`2583`). + By `Deepak Cherian `_ + - Fix failure in time encoding when exporting to netCDF with versions of pandas + less than 0.21.1 (:issue:`2623`). By `Spencer Clark + `_. + - Fix MultiIndex selection to update label and level (:issue:`2619`). + By `Keisuke Fujii `_. + + .. _whats-new.0.11.0: + + v0.11.0 (7 November 2018) + ------------------------- + + Breaking changes + ~~~~~~~~~~~~~~~~ + + - Finished deprecations (changed behavior with this release): + + - ``Dataset.T`` has been removed as a shortcut for :py:meth:`Dataset.transpose`. + Call :py:meth:`Dataset.transpose` directly instead. + - Iterating over a ``Dataset`` now includes only data variables, not coordinates. + Similarily, calling ``len`` and ``bool`` on a ``Dataset`` now + includes only data variables. + - ``DataArray.__contains__`` (used by Python's ``in`` operator) now checks + array data, not coordinates. + - The old resample syntax from before xarray 0.10, e.g., + ``data.resample('1D', dim='time', how='mean')``, is no longer supported will + raise an error in most cases. You need to use the new resample syntax + instead, e.g., ``data.resample(time='1D').mean()`` or + ``data.resample({'time': '1D'}).mean()``. + + + - New deprecations (behavior will be changed in xarray 0.12): + + - Reduction of :py:meth:`DataArray.groupby` and :py:meth:`DataArray.resample` + without dimension argument will change in the next release. + Now we warn a FutureWarning. + By `Keisuke Fujii `_. + - The ``inplace`` kwarg of a number of `DataArray` and `Dataset` methods is being + deprecated and will be removed in the next release. + By `Deepak Cherian `_. + + + - Refactored storage backends: + + - Xarray's storage backends now automatically open and close files when + necessary, rather than requiring opening a file with ``autoclose=True``. A + global least-recently-used cache is used to store open files; the default + limit of 128 open files should suffice in most cases, but can be adjusted if + necessary with + ``xarray.set_options(file_cache_maxsize=...)``. The ``autoclose`` argument + to ``open_dataset`` and related functions has been deprecated and is now a + no-op. + + This change, along with an internal refactor of xarray's storage backends, + should significantly improve performance when reading and writing + netCDF files with Dask, especially when working with many files or using + Dask Distributed. By `Stephan Hoyer `_ + + + - Support for non-standard calendars used in climate science: + + - Xarray will now always use :py:class:`cftime.datetime` objects, rather + than by default trying to coerce them into ``np.datetime64[ns]`` objects. + A :py:class:`~xarray.CFTimeIndex` will be used for indexing along time + coordinates in these cases. + - A new method :py:meth:`~xarray.CFTimeIndex.to_datetimeindex` has been added + to aid in converting from a :py:class:`~xarray.CFTimeIndex` to a + :py:class:`pandas.DatetimeIndex` for the remaining use-cases where + using a :py:class:`~xarray.CFTimeIndex` is still a limitation (e.g. for + resample or plotting). + - Setting the ``enable_cftimeindex`` option is now a no-op and emits a + ``FutureWarning``. + + Enhancements + ~~~~~~~~~~~~ + + - :py:meth:`xarray.DataArray.plot.line` can now accept multidimensional + coordinate variables as input. `hue` must be a dimension name in this case. + (:issue:`2407`) + By `Deepak Cherian `_. + - Added support for Python 3.7. (:issue:`2271`). + By `Joe Hamman `_. + - Added support for plotting data with `pandas.Interval` coordinates, such as those + created by :py:meth:`~xarray.DataArray.groupby_bins` + By `Maximilian Maahn `_. + - Added :py:meth:`~xarray.CFTimeIndex.shift` for shifting the values of a + CFTimeIndex by a specified frequency. (:issue:`2244`). + By `Spencer Clark `_. + - Added support for using ``cftime.datetime`` coordinates with + :py:meth:`~xarray.DataArray.differentiate`, + :py:meth:`~xarray.Dataset.differentiate`, + :py:meth:`~xarray.DataArray.interp`, and + :py:meth:`~xarray.Dataset.interp`. + By `Spencer Clark `_ + - There is now a global option to either always keep or always discard + dataset and dataarray attrs upon operations. The option is set with + ``xarray.set_options(keep_attrs=True)``, and the default is to use the old + behaviour. + By `Tom Nicholas `_. + - Added a new backend for the GRIB file format based on ECMWF *cfgrib* + python driver and *ecCodes* C-library. (:issue:`2475`) + By `Alessandro Amici `_, + sponsored by `ECMWF `_. + - Resample now supports a dictionary mapping from dimension to frequency as + its first argument, e.g., ``data.resample({'time': '1D'}).mean()``. This is + consistent with other xarray functions that accept either dictionaries or + keyword arguments. By `Stephan Hoyer `_. + + - The preferred way to access tutorial data is now to load it lazily with + :py:meth:`xarray.tutorial.open_dataset`. + :py:meth:`xarray.tutorial.load_dataset` calls `Dataset.load()` prior + to returning (and is now deprecated). This was changed in order to facilitate + using tutorial datasets with dask. + By `Joe Hamman `_. + - ``DataArray`` can now use ``xr.set_option(keep_attrs=True)`` and retain attributes in binary operations, + such as (``+, -, * ,/``). Default behaviour is unchanged (*Attributes will be dismissed*). By `Michael Blaschek `_ + + Bug fixes + ~~~~~~~~~ + + - ``FacetGrid`` now properly uses the ``cbar_kwargs`` keyword argument. + (:issue:`1504`, :issue:`1717`) + By `Deepak Cherian `_. + - Addition and subtraction operators used with a CFTimeIndex now preserve the + index's type. (:issue:`2244`). + By `Spencer Clark `_. + - We now properly handle arrays of ``datetime.datetime`` and ``datetime.timedelta`` + provided as coordinates. (:issue:`2512`) + By `Deepak Cherian `_. + - ``xarray.DataArray.roll`` correctly handles multidimensional arrays. + (:issue:`2445`) + By `Keisuke Fujii `_. + - ``xarray.plot()`` now properly accepts a ``norm`` argument and does not override + the norm's ``vmin`` and ``vmax``. (:issue:`2381`) + By `Deepak Cherian `_. + - ``xarray.DataArray.std()`` now correctly accepts ``ddof`` keyword argument. + (:issue:`2240`) + By `Keisuke Fujii `_. + - Restore matplotlib's default of plotting dashed negative contours when + a single color is passed to ``DataArray.contour()`` e.g. ``colors='k'``. + By `Deepak Cherian `_. + + + - Fix a bug that caused some indexing operations on arrays opened with + ``open_rasterio`` to error (:issue:`2454`). + By `Stephan Hoyer `_. + + - Subtracting one CFTimeIndex from another now returns a + ``pandas.TimedeltaIndex``, analogous to the behavior for DatetimeIndexes + (:issue:`2484`). By `Spencer Clark `_. + - Adding a TimedeltaIndex to, or subtracting a TimedeltaIndex from a + CFTimeIndex is now allowed (:issue:`2484`). + By `Spencer Clark `_. + - Avoid use of Dask's deprecated ``get=`` parameter in tests + by `Matthew Rocklin `_. + - An ``OverflowError`` is now accurately raised and caught during the + encoding process if a reference date is used that is so distant that + the dates must be encoded using cftime rather than NumPy (:issue:`2272`). + By `Spencer Clark `_. + + - Chunked datasets can now roundtrip to Zarr storage continually + with `to_zarr` and ``open_zarr`` (:issue:`2300`). + By `Lily Wang `_. + + .. _whats-new.0.10.9: + + v0.10.9 (21 September 2018) + --------------------------- + + This minor release contains a number of backwards compatible enhancements. + + Announcements of note: + + - Xarray is now a NumFOCUS fiscally sponsored project! Read + `the anouncement `_ + for more details. + - We have a new :doc:`roadmap` that outlines our future development plans. + + - ``Dataset.apply`` now properly documents the way `func` is called. + By `Matti Eskelinen `_. + + Enhancements + ~~~~~~~~~~~~ + + - :py:meth:`~xarray.DataArray.differentiate` and + :py:meth:`~xarray.Dataset.differentiate` are newly added. + (:issue:`1332`) + By `Keisuke Fujii `_. + + - Default colormap for sequential and divergent data can now be set via + :py:func:`~xarray.set_options()` + (:issue:`2394`) + By `Julius Busecke `_. + + - min_count option is newly supported in :py:meth:`~xarray.DataArray.sum`, + :py:meth:`~xarray.DataArray.prod` and :py:meth:`~xarray.Dataset.sum`, and + :py:meth:`~xarray.Dataset.prod`. + (:issue:`2230`) + By `Keisuke Fujii `_. + + - :py:func:`~plot.plot()` now accepts the kwargs + ``xscale, yscale, xlim, ylim, xticks, yticks`` just like Pandas. Also ``xincrease=False, yincrease=False`` now use matplotlib's axis inverting methods instead of setting limits. + By `Deepak Cherian `_. (:issue:`2224`) + + - DataArray coordinates and Dataset coordinates and data variables are + now displayed as `a b ... y z` rather than `a b c d ...`. + (:issue:`1186`) + By `Seth P `_. + - A new CFTimeIndex-enabled :py:func:`cftime_range` function for use in + generating dates from standard or non-standard calendars. By `Spencer Clark + `_. + + - When interpolating over a ``datetime64`` axis, you can now provide a datetime string instead of a ``datetime64`` object. E.g. ``da.interp(time='1991-02-01')`` + (:issue:`2284`) + By `Deepak Cherian `_. + + - A clear error message is now displayed if a ``set`` or ``dict`` is passed in place of an array + (:issue:`2331`) + By `Maximilian Roos `_. + + - Applying ``unstack`` to a large DataArray or Dataset is now much faster if the MultiIndex has not been modified after stacking the indices. + (:issue:`1560`) + By `Maximilian Maahn `_. + + - You can now control whether or not to offset the coordinates when using + the ``roll`` method and the current behavior, coordinates rolled by default, + raises a deprecation warning unless explicitly setting the keyword argument. + (:issue:`1875`) + By `Andrew Huang `_. + + - You can now call ``unstack`` without arguments to unstack every MultiIndex in a DataArray or Dataset. + By `Julia Signell `_. + + - Added the ability to pass a data kwarg to ``copy`` to create a new object with the + same metadata as the original object but using new values. + By `Julia Signell `_. + + Bug fixes + ~~~~~~~~~ + + - ``xarray.plot.imshow()`` correctly uses the ``origin`` argument. + (:issue:`2379`) + By `Deepak Cherian `_. + + - Fixed ``DataArray.to_iris()`` failure while creating ``DimCoord`` by + falling back to creating ``AuxCoord``. Fixed dependency on ``var_name`` + attribute being set. + (:issue:`2201`) + By `Thomas Voigt `_. + - Fixed a bug in ``zarr`` backend which prevented use with datasets with + invalid chunk size encoding after reading from an existing store + (:issue:`2278`). + By `Joe Hamman `_. + + - Tests can be run in parallel with pytest-xdist + By `Tony Tung `_. + + - Follow up the renamings in dask; from dask.ghost to dask.overlap + By `Keisuke Fujii `_. + + - Now raises a ValueError when there is a conflict between dimension names and + level names of MultiIndex. (:issue:`2299`) + By `Keisuke Fujii `_. + + - Follow up the renamings in dask; from dask.ghost to dask.overlap + By `Keisuke Fujii `_. + + - Now :py:func:`~xarray.apply_ufunc` raises a ValueError when the size of + ``input_core_dims`` is inconsistent with the number of arguments. + (:issue:`2341`) + By `Keisuke Fujii `_. + + - Fixed ``Dataset.filter_by_attrs()`` behavior not matching ``netCDF4.Dataset.get_variables_by_attributes()``. + When more than one ``key=value`` is passed into ``Dataset.filter_by_attrs()`` it will now return a Dataset with variables which pass + all the filters. + (:issue:`2315`) + By `Andrew Barna `_. + + .. _whats-new.0.10.8: + + v0.10.8 (18 July 2018) + ---------------------- + + Breaking changes + ~~~~~~~~~~~~~~~~ + + - Xarray no longer supports python 3.4. Additionally, the minimum supported + versions of the following dependencies has been updated and/or clarified: + + - Pandas: 0.18 -> 0.19 + - NumPy: 1.11 -> 1.12 + - Dask: 0.9 -> 0.16 + - Matplotlib: unspecified -> 1.5 + + (:issue:`2204`). By `Joe Hamman `_. + + Enhancements + ~~~~~~~~~~~~ + + - :py:meth:`~xarray.DataArray.interp_like` and + :py:meth:`~xarray.Dataset.interp_like` methods are newly added. + (:issue:`2218`) + By `Keisuke Fujii `_. + + - Added support for curvilinear and unstructured generic grids + to :py:meth:`~xarray.DataArray.to_cdms2` and + :py:meth:`~xarray.DataArray.from_cdms2` (:issue:`2262`). + By `Stephane Raynaud `_. + + Bug fixes + ~~~~~~~~~ + + - Fixed a bug in ``zarr`` backend which prevented use with datasets with + incomplete chunks in multiple dimensions (:issue:`2225`). + By `Joe Hamman `_. + + - Fixed a bug in :py:meth:`~Dataset.to_netcdf` which prevented writing + datasets when the arrays had different chunk sizes (:issue:`2254`). + By `Mike Neish `_. + + - Fixed masking during the conversion to cdms2 objects by + :py:meth:`~xarray.DataArray.to_cdms2` (:issue:`2262`). + By `Stephane Raynaud `_. + + - Fixed a bug in 2D plots which incorrectly raised an error when 2D coordinates + weren't monotonic (:issue:`2250`). + By `Fabien Maussion `_. + + - Fixed warning raised in :py:meth:`~Dataset.to_netcdf` due to deprecation of + `effective_get` in dask (:issue:`2238`). + By `Joe Hamman `_. + + .. _whats-new.0.10.7: + + v0.10.7 (7 June 2018) + --------------------- + + Enhancements + ~~~~~~~~~~~~ + + - Plot labels now make use of metadata that follow CF conventions + (:issue:`2135`). + By `Deepak Cherian `_ and `Ryan Abernathey `_. + + - Line plots now support facetting with ``row`` and ``col`` arguments + (:issue:`2107`). + By `Yohai Bar Sinai `_. + + - :py:meth:`~xarray.DataArray.interp` and :py:meth:`~xarray.Dataset.interp` + methods are newly added. + See :ref:`interp` for the detail. + (:issue:`2079`) + By `Keisuke Fujii `_. + + Bug fixes + ~~~~~~~~~ + + - Fixed a bug in ``rasterio`` backend which prevented use with ``distributed``. + The ``rasterio`` backend now returns pickleable objects (:issue:`2021`). + By `Joe Hamman `_. + + .. _whats-new.0.10.6: + + v0.10.6 (31 May 2018) + --------------------- + + The minor release includes a number of bug-fixes and backwards compatible + enhancements. + + Enhancements + ~~~~~~~~~~~~ + + - New PseudoNetCDF backend for many Atmospheric data formats including + GEOS-Chem, CAMx, NOAA arlpacked bit and many others. See + :ref:`io.PseudoNetCDF` for more details. + By `Barron Henderson `_. + + - The :py:class:`Dataset` constructor now aligns :py:class:`DataArray` + arguments in ``data_vars`` to indexes set explicitly in ``coords``, + where previously an error would be raised. + (:issue:`674`) + By `Maximilian Roos `_. + + - :py:meth:`~DataArray.sel`, :py:meth:`~DataArray.isel` & :py:meth:`~DataArray.reindex`, + (and their :py:class:`Dataset` counterparts) now support supplying a ``dict`` + as a first argument, as an alternative to the existing approach + of supplying `kwargs`. This allows for more robust behavior + of dimension names which conflict with other keyword names, or are + not strings. + By `Maximilian Roos `_. + + - :py:meth:`~DataArray.rename` now supports supplying ``**kwargs``, as an + alternative to the existing approach of supplying a ``dict`` as the + first argument. + By `Maximilian Roos `_. + + - :py:meth:`~DataArray.cumsum` and :py:meth:`~DataArray.cumprod` now support + aggregation over multiple dimensions at the same time. This is the default + behavior when dimensions are not specified (previously this raised an error). + By `Stephan Hoyer `_ + + - :py:meth:`DataArray.dot` and :py:func:`dot` are partly supported with older + dask<0.17.4. (related to :issue:`2203`) + By `Keisuke Fujii `_. + + - Xarray now uses `Versioneer `__ + to manage its version strings. (:issue:`1300`). + By `Joe Hamman `_. + + Bug fixes + ~~~~~~~~~ + + - Fixed a regression in 0.10.4, where explicitly specifying ``dtype='S1'`` or + ``dtype=str`` in ``encoding`` with ``to_netcdf()`` raised an error + (:issue:`2149`). + `Stephan Hoyer `_ + + - :py:func:`apply_ufunc` now directly validates output variables + (:issue:`1931`). + By `Stephan Hoyer `_. + + - Fixed a bug where ``to_netcdf(..., unlimited_dims='bar')`` yielded NetCDF + files with spurious 0-length dimensions (i.e. ``b``, ``a``, and ``r``) + (:issue:`2134`). + By `Joe Hamman `_. + + - Removed spurious warnings with ``Dataset.update(Dataset)`` (:issue:`2161`) + and ``array.equals(array)`` when ``array`` contains ``NaT`` (:issue:`2162`). + By `Stephan Hoyer `_. + + - Aggregations with :py:meth:`Dataset.reduce` (including ``mean``, ``sum``, + etc) no longer drop unrelated coordinates (:issue:`1470`). Also fixed a + bug where non-scalar data-variables that did not include the aggregation + dimension were improperly skipped. + By `Stephan Hoyer `_ + + - Fix :meth:`~DataArray.stack` with non-unique coordinates on pandas 0.23 + (:issue:`2160`). + By `Stephan Hoyer `_ + + - Selecting data indexed by a length-1 ``CFTimeIndex`` with a slice of strings + now behaves as it does when using a length-1 ``DatetimeIndex`` (i.e. it no + longer falsely returns an empty array when the slice includes the value in + the index) (:issue:`2165`). + By `Spencer Clark `_. + + - Fix ``DataArray.groupby().reduce()`` mutating coordinates on the input array + when grouping over dimension coordinates with duplicated entries + (:issue:`2153`). + By `Stephan Hoyer `_ + + - Fix ``Dataset.to_netcdf()`` cannot create group with ``engine="h5netcdf"`` + (:issue:`2177`). + By `Stephan Hoyer `_ + + .. _whats-new.0.10.4: + + v0.10.4 (16 May 2018) + ---------------------- + + The minor release includes a number of bug-fixes and backwards compatible + enhancements. A highlight is ``CFTimeIndex``, which offers support for + non-standard calendars used in climate modeling. + + Documentation + ~~~~~~~~~~~~~ + + - New FAQ entry, :ref:`ecosystem`. + By `Deepak Cherian `_. + - :ref:`assigning_values` now includes examples on how to select and assign + values to a :py:class:`~xarray.DataArray` with ``.loc``. + By `Chiara Lepore `_. + + Enhancements + ~~~~~~~~~~~~ + + - Add an option for using a ``CFTimeIndex`` for indexing times with + non-standard calendars and/or outside the Timestamp-valid range; this index + enables a subset of the functionality of a standard + ``pandas.DatetimeIndex``. + See :ref:`CFTimeIndex` for full details. + (:issue:`789`, :issue:`1084`, :issue:`1252`) + By `Spencer Clark `_ with help from + `Stephan Hoyer `_. + - Allow for serialization of ``cftime.datetime`` objects (:issue:`789`, + :issue:`1084`, :issue:`2008`, :issue:`1252`) using the standalone ``cftime`` + library. + By `Spencer Clark `_. + - Support writing lists of strings as netCDF attributes (:issue:`2044`). + By `Dan Nowacki `_. + - :py:meth:`~xarray.Dataset.to_netcdf` with ``engine='h5netcdf'`` now accepts h5py + encoding settings ``compression`` and ``compression_opts``, along with the + NetCDF4-Python style settings ``gzip=True`` and ``complevel``. + This allows using any compression plugin installed in hdf5, e.g. LZF + (:issue:`1536`). By `Guido Imperiale `_. + - :py:meth:`~xarray.dot` on dask-backed data will now call :func:`dask.array.einsum`. + This greatly boosts speed and allows chunking on the core dims. + The function now requires dask >= 0.17.3 to work on dask-backed data + (:issue:`2074`). By `Guido Imperiale `_. + - ``plot.line()`` learned new kwargs: ``xincrease``, ``yincrease`` that change + the direction of the respective axes. + By `Deepak Cherian `_. + + - Added the ``parallel`` option to :py:func:`open_mfdataset`. This option uses + ``dask.delayed`` to parallelize the open and preprocessing steps within + ``open_mfdataset``. This is expected to provide performance improvements when + opening many files, particularly when used in conjunction with dask's + multiprocessing or distributed schedulers (:issue:`1981`). + By `Joe Hamman `_. + + - New ``compute`` option in :py:meth:`~xarray.Dataset.to_netcdf`, + :py:meth:`~xarray.Dataset.to_zarr`, and :py:func:`~xarray.save_mfdataset` to + allow for the lazy computation of netCDF and zarr stores. This feature is + currently only supported by the netCDF4 and zarr backends. (:issue:`1784`). + By `Joe Hamman `_. + + + Bug fixes + ~~~~~~~~~ + + - ``ValueError`` is raised when coordinates with the wrong size are assigned to + a :py:class:`DataArray`. (:issue:`2112`) + By `Keisuke Fujii `_. + - Fixed a bug in :py:meth:`~xarray.DataArray.rolling` with bottleneck. Also, + fixed a bug in rolling an integer dask array. (:issue:`2113`) + By `Keisuke Fujii `_. + - Fixed a bug where `keep_attrs=True` flag was neglected if + :py:func:`apply_ufunc` was used with :py:class:`Variable`. (:issue:`2114`) + By `Keisuke Fujii `_. + - When assigning a :py:class:`DataArray` to :py:class:`Dataset`, any conflicted + non-dimensional coordinates of the DataArray are now dropped. + (:issue:`2068`) + By `Keisuke Fujii `_. + - Better error handling in ``open_mfdataset`` (:issue:`2077`). + By `Stephan Hoyer `_. + - ``plot.line()`` does not call ``autofmt_xdate()`` anymore. Instead it changes + the rotation and horizontal alignment of labels without removing the x-axes of + any other subplots in the figure (if any). + By `Deepak Cherian `_. + - Colorbar limits are now determined by excluding ±Infs too. + By `Deepak Cherian `_. + By `Joe Hamman `_. + - Fixed ``to_iris`` to maintain lazy dask array after conversion (:issue:`2046`). + By `Alex Hilson `_ and `Stephan Hoyer `_. + + .. _whats-new.0.10.3: + + v0.10.3 (13 April 2018) + ------------------------ + + The minor release includes a number of bug-fixes and backwards compatible enhancements. + + Enhancements + ~~~~~~~~~~~~ + + - :py:meth:`~xarray.DataArray.isin` and :py:meth:`~xarray.Dataset.isin` methods, + which test each value in the array for whether it is contained in the + supplied list, returning a bool array. See :ref:`selecting values with isin` + for full details. Similar to the ``np.isin`` function. + By `Maximilian Roos `_. + - Some speed improvement to construct :py:class:`~xarray.core.rolling.DataArrayRolling` + object (:issue:`1993`) + By `Keisuke Fujii `_. + - Handle variables with different values for ``missing_value`` and + ``_FillValue`` by masking values for both attributes; previously this + resulted in a ``ValueError``. (:issue:`2016`) + By `Ryan May `_. + + Bug fixes + ~~~~~~~~~ + + - Fixed ``decode_cf`` function to operate lazily on dask arrays + (:issue:`1372`). By `Ryan Abernathey `_. + - Fixed labeled indexing with slice bounds given by xarray objects with + datetime64 or timedelta64 dtypes (:issue:`1240`). + By `Stephan Hoyer `_. + - Attempting to convert an xarray.Dataset into a numpy array now raises an + informative error message. + By `Stephan Hoyer `_. + - Fixed a bug in decode_cf_datetime where ``int32`` arrays weren't parsed + correctly (:issue:`2002`). + By `Fabien Maussion `_. + - When calling `xr.auto_combine()` or `xr.open_mfdataset()` with a `concat_dim`, + the resulting dataset will have that one-element dimension (it was + silently dropped, previously) (:issue:`1988`). + By `Ben Root `_. + + .. _whats-new.0.10.2: + + v0.10.2 (13 March 2018) + ----------------------- + + The minor release includes a number of bug-fixes and enhancements, along with + one possibly **backwards incompatible change**. + + Backwards incompatible changes + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + - The addition of ``__array_ufunc__`` for xarray objects (see below) means that + NumPy `ufunc methods`_ (e.g., ``np.add.reduce``) that previously worked on + ``xarray.DataArray`` objects by converting them into NumPy arrays will now + raise ``NotImplementedError`` instead. In all cases, the work-around is + simple: convert your objects explicitly into NumPy arrays before calling the + ufunc (e.g., with ``.values``). + + .. _ufunc methods: https://docs.scipy.org/doc/numpy/reference/ufuncs.html#methods + + Enhancements + ~~~~~~~~~~~~ + + - Added :py:func:`~xarray.dot`, equivalent to :py:func:`numpy.einsum`. + Also, :py:func:`~xarray.DataArray.dot` now supports ``dims`` option, + which specifies the dimensions to sum over. + (:issue:`1951`) + By `Keisuke Fujii `_. + + - Support for writing xarray datasets to netCDF files (netcdf4 backend only) + when using the `dask.distributed `_ + scheduler (:issue:`1464`). + By `Joe Hamman `_. + + - Support lazy vectorized-indexing. After this change, flexible indexing such + as orthogonal/vectorized indexing, becomes possible for all the backend + arrays. Also, lazy ``transpose`` is now also supported. (:issue:`1897`) + By `Keisuke Fujii `_. + + - Implemented NumPy's ``__array_ufunc__`` protocol for all xarray objects + (:issue:`1617`). This enables using NumPy ufuncs directly on + ``xarray.Dataset`` objects with recent versions of NumPy (v1.13 and newer): + + .. ipython:: python + + ds = xr.Dataset({"a": 1}) + np.sin(ds) + + This obliviates the need for the ``xarray.ufuncs`` module, which will be + deprecated in the future when xarray drops support for older versions of + NumPy. By `Stephan Hoyer `_. + + - Improve :py:func:`~xarray.DataArray.rolling` logic. + :py:func:`~xarray.core.rolling.DataArrayRolling` object now supports + :py:func:`~xarray.core.rolling.DataArrayRolling.construct` method that returns a view + of the DataArray / Dataset object with the rolling-window dimension added + to the last axis. This enables more flexible operation, such as strided + rolling, windowed rolling, ND-rolling, short-time FFT and convolution. + (:issue:`1831`, :issue:`1142`, :issue:`819`) + By `Keisuke Fujii `_. + - :py:func:`~plot.line()` learned to make plots with data on x-axis if so specified. (:issue:`575`) + By `Deepak Cherian `_. + + Bug fixes + ~~~~~~~~~ + + - Raise an informative error message when using ``apply_ufunc`` with numpy + v1.11 (:issue:`1956`). + By `Stephan Hoyer `_. + - Fix the precision drop after indexing datetime64 arrays (:issue:`1932`). + By `Keisuke Fujii `_. + - Silenced irrelevant warnings issued by ``open_rasterio`` (:issue:`1964`). + By `Stephan Hoyer `_. + - Fix kwarg `colors` clashing with auto-inferred `cmap` (:issue:`1461`) + By `Deepak Cherian `_. + - Fix :py:func:`~xarray.plot.imshow` error when passed an RGB array with + size one in a spatial dimension. + By `Zac Hatfield-Dodds `_. + + .. _whats-new.0.10.1: + + v0.10.1 (25 February 2018) + -------------------------- + + The minor release includes a number of bug-fixes and backwards compatible enhancements. + + Documentation + ~~~~~~~~~~~~~ + + - Added a new guide on :ref:`contributing` (:issue:`640`) + By `Joe Hamman `_. + - Added apply_ufunc example to :ref:`/examples/weather-data.ipynb#Toy-weather-data` (:issue:`1844`). + By `Liam Brannigan `_. + - New entry `Why don’t aggregations return Python scalars?` in the + :doc:`getting-started-guide/faq` (:issue:`1726`). + By `0x0L `_. + + Enhancements + ~~~~~~~~~~~~ + **New functions and methods**: + + - Added :py:meth:`DataArray.to_iris` and + :py:meth:`DataArray.from_iris` for + converting data arrays to and from Iris_ Cubes with the same data and coordinates + (:issue:`621` and :issue:`37`). + By `Neil Parley `_ and `Duncan Watson-Parris `_. + - Experimental support for using `Zarr`_ as storage layer for xarray + (:issue:`1223`). + By `Ryan Abernathey `_ and + `Joe Hamman `_. + - New :py:meth:`~xarray.DataArray.rank` on arrays and datasets. Requires + bottleneck (:issue:`1731`). + By `0x0L `_. + - ``.dt`` accessor can now ceil, floor and round timestamps to specified frequency. + By `Deepak Cherian `_. + + **Plotting enhancements**: + + - :func:`xarray.plot.imshow` now handles RGB and RGBA images. + Saturation can be adjusted with ``vmin`` and ``vmax``, or with ``robust=True``. + By `Zac Hatfield-Dodds `_. + - :py:func:`~plot.contourf()` learned to contour 2D variables that have both a + 1D coordinate (e.g. time) and a 2D coordinate (e.g. depth as a function of + time) (:issue:`1737`). + By `Deepak Cherian `_. + - :py:func:`~plot.plot()` rotates x-axis ticks if x-axis is time. + By `Deepak Cherian `_. + - :py:func:`~plot.line()` can draw multiple lines if provided with a + 2D variable. + By `Deepak Cherian `_. + + **Other enhancements**: + + - Reduce methods such as :py:func:`DataArray.sum()` now handles object-type array. + + .. ipython:: python + + da = xr.DataArray(np.array([True, False, np.nan], dtype=object), dims="x") + da.sum() + + (:issue:`1866`) + By `Keisuke Fujii `_. + - Reduce methods such as :py:func:`DataArray.sum()` now accepts ``dtype`` + arguments. (:issue:`1838`) + By `Keisuke Fujii `_. + - Added nodatavals attribute to DataArray when using :py:func:`~xarray.open_rasterio`. (:issue:`1736`). + By `Alan Snow `_. + - Use ``pandas.Grouper`` class in xarray resample methods rather than the + deprecated ``pandas.TimeGrouper`` class (:issue:`1766`). + By `Joe Hamman `_. + - Experimental support for parsing ENVI metadata to coordinates and attributes + in :py:func:`xarray.open_rasterio`. + By `Matti Eskelinen `_. + - Reduce memory usage when decoding a variable with a scale_factor, by + converting 8-bit and 16-bit integers to float32 instead of float64 + (:pull:`1840`), and keeping float16 and float32 as float32 (:issue:`1842`). + Correspondingly, encoded variables may also be saved with a smaller dtype. + By `Zac Hatfield-Dodds `_. + - Speed of reindexing/alignment with dask array is orders of magnitude faster + when inserting missing values (:issue:`1847`). + By `Stephan Hoyer `_. + - Fix ``axis`` keyword ignored when applying ``np.squeeze`` to ``DataArray`` (:issue:`1487`). + By `Florian Pinault `_. + - ``netcdf4-python`` has moved the its time handling in the ``netcdftime`` module to + a standalone package (`netcdftime`_). As such, xarray now considers `netcdftime`_ + an optional dependency. One benefit of this change is that it allows for + encoding/decoding of datetimes with non-standard calendars without the + ``netcdf4-python`` dependency (:issue:`1084`). + By `Joe Hamman `_. + + .. _Zarr: http://zarr.readthedocs.io/ + + .. _Iris: http://scitools.org.uk/iris + + .. _netcdftime: https://unidata.github.io/netcdftime + + **New functions/methods** + + - New :py:meth:`~xarray.DataArray.rank` on arrays and datasets. Requires + bottleneck (:issue:`1731`). + By `0x0L `_. + + Bug fixes + ~~~~~~~~~ + - Rolling aggregation with ``center=True`` option now gives the same result + with pandas including the last element (:issue:`1046`). + By `Keisuke Fujii `_. + + - Support indexing with a 0d-np.ndarray (:issue:`1921`). + By `Keisuke Fujii `_. + - Added warning in api.py of a netCDF4 bug that occurs when + the filepath has 88 characters (:issue:`1745`). + By `Liam Brannigan `_. + - Fixed encoding of multi-dimensional coordinates in + :py:meth:`~Dataset.to_netcdf` (:issue:`1763`). + By `Mike Neish `_. + - Fixed chunking with non-file-based rasterio datasets (:issue:`1816`) and + refactored rasterio test suite. + By `Ryan Abernathey `_ + - Bug fix in open_dataset(engine='pydap') (:issue:`1775`) + By `Keisuke Fujii `_. + - Bug fix in vectorized assignment (:issue:`1743`, :issue:`1744`). + Now item assignment to :py:meth:`~DataArray.__setitem__` checks + - Bug fix in vectorized assignment (:issue:`1743`, :issue:`1744`). + Now item assignment to :py:meth:`DataArray.__setitem__` checks + coordinates of target, destination and keys. If there are any conflict among + these coordinates, ``IndexError`` will be raised. + By `Keisuke Fujii `_. + - Properly point ``DataArray.__dask_scheduler__`` to + ``dask.threaded.get``. By `Matthew Rocklin `_. + - Bug fixes in :py:meth:`DataArray.plot.imshow`: all-NaN arrays and arrays + with size one in some dimension can now be plotted, which is good for + exploring satellite imagery (:issue:`1780`). + By `Zac Hatfield-Dodds `_. + - Fixed ``UnboundLocalError`` when opening netCDF file (:issue:`1781`). + By `Stephan Hoyer `_. + - The ``variables``, ``attrs``, and ``dimensions`` properties have been + deprecated as part of a bug fix addressing an issue where backends were + unintentionally loading the datastores data and attributes repeatedly during + writes (:issue:`1798`). + By `Joe Hamman `_. + - Compatibility fixes to plotting module for Numpy 1.14 and Pandas 0.22 + (:issue:`1813`). + By `Joe Hamman `_. + - Bug fix in encoding coordinates with ``{'_FillValue': None}`` in netCDF + metadata (:issue:`1865`). + By `Chris Roth `_. + - Fix indexing with lists for arrays loaded from netCDF files with + ``engine='h5netcdf`` (:issue:`1864`). + By `Stephan Hoyer `_. + - Corrected a bug with incorrect coordinates for non-georeferenced geotiff + files (:issue:`1686`). Internally, we now use the rasterio coordinate + transform tool instead of doing the computations ourselves. A + ``parse_coordinates`` kwarg has beed added to :py:func:`~open_rasterio` + (set to ``True`` per default). + By `Fabien Maussion `_. + - The colors of discrete colormaps are now the same regardless if `seaborn` + is installed or not (:issue:`1896`). + By `Fabien Maussion `_. + - Fixed dtype promotion rules in :py:func:`where` and :py:func:`concat` to + match pandas (:issue:`1847`). A combination of strings/numbers or + unicode/bytes now promote to object dtype, instead of strings or unicode. + By `Stephan Hoyer `_. + - Fixed bug where :py:meth:`~xarray.DataArray.isnull` was loading data + stored as dask arrays (:issue:`1937`). + By `Joe Hamman `_. + + .. _whats-new.0.10.0: + + v0.10.0 (20 November 2017) + -------------------------- + + This is a major release that includes bug fixes, new features and a few + backwards incompatible changes. Highlights include: + + - Indexing now supports broadcasting over dimensions, similar to NumPy's + vectorized indexing (but better!). + - :py:meth:`~DataArray.resample` has a new groupby-like API like pandas. + - :py:func:`~xarray.apply_ufunc` facilitates wrapping and parallelizing + functions written for NumPy arrays. + - Performance improvements, particularly for dask and :py:func:`open_mfdataset`. + + Breaking changes + ~~~~~~~~~~~~~~~~ + + - xarray now supports a form of vectorized indexing with broadcasting, where + the result of indexing depends on dimensions of indexers, + e.g., ``array.sel(x=ind)`` with ``ind.dims == ('y',)``. Alignment between + coordinates on indexed and indexing objects is also now enforced. + Due to these changes, existing uses of xarray objects to index other xarray + objects will break in some cases. + + The new indexing API is much more powerful, supporting outer, diagonal and + vectorized indexing in a single interface. + The ``isel_points`` and ``sel_points`` methods are deprecated, since they are + now redundant with the ``isel`` / ``sel`` methods. + See :ref:`vectorized_indexing` for the details (:issue:`1444`, + :issue:`1436`). + By `Keisuke Fujii `_ and + `Stephan Hoyer `_. + + - A new resampling interface to match pandas' groupby-like API was added to + :py:meth:`Dataset.resample` and :py:meth:`DataArray.resample` + (:issue:`1272`). :ref:`Timeseries resampling ` is + fully supported for data with arbitrary dimensions as is both downsampling + and upsampling (including linear, quadratic, cubic, and spline interpolation). + + Old syntax: + + .. ipython:: :verbatim: - - In [12]: ds.sel(x=1.1, method="nearest") - Out[12]: - - Dimensions: () - Coordinates: - x int64 1 + + In [1]: ds.resample("24H", dim="time", how="max") + Out[1]: + + [...] + + New syntax: + + .. ipython:: + :verbatim: + + In [1]: ds.resample(time="24H").max() + Out[1]: + + [...] + + Note that both versions are currently supported, but using the old syntax will + produce a warning encouraging users to adopt the new syntax. + By `Daniel Rothenberg `_. + + - Calling ``repr()`` or printing xarray objects at the command line or in a + Jupyter Notebook will not longer automatically compute dask variables or + load data on arrays lazily loaded from disk (:issue:`1522`). + By `Guido Imperiale `_. + + - Supplying ``coords`` as a dictionary to the ``DataArray`` constructor without + also supplying an explicit ``dims`` argument is no longer supported. This + behavior was deprecated in version 0.9 but will now raise an error + (:issue:`727`). + + - Several existing features have been deprecated and will change to new + behavior in xarray v0.11. If you use any of them with xarray v0.10, you + should see a ``FutureWarning`` that describes how to update your code: + + - ``Dataset.T`` has been deprecated an alias for ``Dataset.transpose()`` + (:issue:`1232`). In the next major version of xarray, it will provide short- + cut lookup for variables or attributes with name ``'T'``. + - ``DataArray.__contains__`` (e.g., ``key in data_array``) currently checks + for membership in ``DataArray.coords``. In the next major version of + xarray, it will check membership in the array data found in + ``DataArray.values`` instead (:issue:`1267`). + - Direct iteration over and counting a ``Dataset`` (e.g., ``[k for k in ds]``, + ``ds.keys()``, ``ds.values()``, ``len(ds)`` and ``if ds``) currently + includes all variables, both data and coordinates. For improved usability + and consistency with pandas, in the next major version of xarray these will + change to only include data variables (:issue:`884`). Use ``ds.variables``, + ``ds.data_vars`` or ``ds.coords`` as alternatives. + + - Changes to minimum versions of dependencies: + + - Old numpy < 1.11 and pandas < 0.18 are no longer supported (:issue:`1512`). + By `Keisuke Fujii `_. + - The minimum supported version bottleneck has increased to 1.1 + (:issue:`1279`). + By `Joe Hamman `_. + + Enhancements + ~~~~~~~~~~~~ + + **New functions/methods** + + - New helper function :py:func:`~xarray.apply_ufunc` for wrapping functions + written to work on NumPy arrays to support labels on xarray objects + (:issue:`770`). ``apply_ufunc`` also support automatic parallelization for + many functions with dask. See :ref:`comput.wrapping-custom` and + :ref:`dask.automatic-parallelization` for details. + By `Stephan Hoyer `_. + + - Added new method :py:meth:`Dataset.to_dask_dataframe`, convert a dataset into + a dask dataframe. + This allows lazy loading of data from a dataset containing dask arrays (:issue:`1462`). + By `James Munroe `_. + + - New function :py:func:`~xarray.where` for conditionally switching between + values in xarray objects, like :py:func:`numpy.where`: + + .. ipython:: + :verbatim: + + In [1]: import xarray as xr + + In [2]: arr = xr.DataArray([[1, 2, 3], [4, 5, 6]], dims=("x", "y")) + + In [3]: xr.where(arr % 2, "even", "odd") + Out[3]: + + array([['even', 'odd', 'even'], + ['odd', 'even', 'odd']], + dtype='`_. + + - Added :py:func:`~xarray.show_versions` function to aid in debugging + (:issue:`1485`). + By `Joe Hamman `_. + + **Performance improvements** + + - :py:func:`~xarray.concat` was computing variables that aren't in memory + (e.g. dask-based) multiple times; :py:func:`~xarray.open_mfdataset` + was loading them multiple times from disk. Now, both functions will instead + load them at most once and, if they do, store them in memory in the + concatenated array/dataset (:issue:`1521`). + By `Guido Imperiale `_. + + - Speed-up (x 100) of ``xarray.conventions.decode_cf_datetime``. + By `Christian Chwala `_. + + **IO related improvements** + + - Unicode strings (``str`` on Python 3) are now round-tripped successfully even + when written as character arrays (e.g., as netCDF3 files or when using + ``engine='scipy'``) (:issue:`1638`). This is controlled by the ``_Encoding`` + attribute convention, which is also understood directly by the netCDF4-Python + interface. See :ref:`io.string-encoding` for full details. + By `Stephan Hoyer `_. + + - Support for ``data_vars`` and ``coords`` keywords from + :py:func:`~xarray.concat` added to :py:func:`~xarray.open_mfdataset` + (:issue:`438`). Using these keyword arguments can significantly reduce + memory usage and increase speed. + By `Oleksandr Huziy `_. + + - Support for :py:class:`pathlib.Path` objects added to + :py:func:`~xarray.open_dataset`, :py:func:`~xarray.open_mfdataset`, + ``xarray.to_netcdf``, and :py:func:`~xarray.save_mfdataset` + (:issue:`799`): + + .. ipython:: + :verbatim: + + In [2]: from pathlib import Path # In Python 2, use pathlib2! + + In [3]: data_dir = Path("data/") + + In [4]: one_file = data_dir / "dta_for_month_01.nc" + + In [5]: xr.open_dataset(one_file) + Out[5]: + + [...] + + By `Willi Rath `_. + + - You can now explicitly disable any default ``_FillValue`` (``NaN`` for + floating point values) by passing the enconding ``{'_FillValue': None}`` + (:issue:`1598`). + By `Stephan Hoyer `_. + + - More attributes available in :py:attr:`~xarray.Dataset.attrs` dictionary when + raster files are opened with :py:func:`~xarray.open_rasterio`. + By `Greg Brener `_. + + - Support for NetCDF files using an ``_Unsigned`` attribute to indicate that a + a signed integer data type should be interpreted as unsigned bytes + (:issue:`1444`). + By `Eric Bruning `_. + + - Support using an existing, opened netCDF4 ``Dataset`` with + :py:class:`~xarray.backends.NetCDF4DataStore`. This permits creating an + :py:class:`~xarray.Dataset` from a netCDF4 ``Dataset`` that has been opened using + other means (:issue:`1459`). + By `Ryan May `_. + + - Changed :py:class:`~xarray.backends.PydapDataStore` to take a Pydap dataset. + This permits opening Opendap datasets that require authentication, by + instantiating a Pydap dataset with a session object. Also added + :py:meth:`xarray.backends.PydapDataStore.open` which takes a url and session + object (:issue:`1068`). + By `Philip Graae `_. + + - Support reading and writing unlimited dimensions with h5netcdf (:issue:`1636`). + By `Joe Hamman `_. + + **Other improvements** + + - Added ``_ipython_key_completions_`` to xarray objects, to enable + autocompletion for dictionary-like access in IPython, e.g., + ``ds['tem`` + tab -> ``ds['temperature']`` (:issue:`1628`). + By `Keisuke Fujii `_. + + - Support passing keyword arguments to ``load``, ``compute``, and ``persist`` + methods. Any keyword arguments supplied to these methods are passed on to + the corresponding dask function (:issue:`1523`). + By `Joe Hamman `_. + + - Encoding attributes are now preserved when xarray objects are concatenated. + The encoding is copied from the first object (:issue:`1297`). + By `Joe Hamman `_ and + `Gerrit Holl `_. + + - Support applying rolling window operations using bottleneck's moving window + functions on data stored as dask arrays (:issue:`1279`). + By `Joe Hamman `_. + + - Experimental support for the Dask collection interface (:issue:`1674`). + By `Matthew Rocklin `_. + + Bug fixes + ~~~~~~~~~ + + - Suppress ``RuntimeWarning`` issued by ``numpy`` for "invalid value comparisons" + (e.g. ``NaN``). Xarray now behaves similarly to Pandas in its treatment of + binary and unary operations on objects with NaNs (:issue:`1657`). + By `Joe Hamman `_. + + - Unsigned int support for reduce methods with ``skipna=True`` + (:issue:`1562`). + By `Keisuke Fujii `_. + + - Fixes to ensure xarray works properly with pandas 0.21: + + - Fix :py:meth:`~xarray.DataArray.isnull` method (:issue:`1549`). + - :py:meth:`~xarray.DataArray.to_series` and + :py:meth:`~xarray.Dataset.to_dataframe` should not return a ``pandas.MultiIndex`` + for 1D data (:issue:`1548`). + - Fix plotting with datetime64 axis labels (:issue:`1661`). + + By `Stephan Hoyer `_. + + - :py:func:`~xarray.open_rasterio` method now shifts the rasterio + coordinates so that they are centered in each pixel (:issue:`1468`). + By `Greg Brener `_. + + - :py:meth:`~xarray.Dataset.rename` method now doesn't throw errors + if some ``Variable`` is renamed to the same name as another ``Variable`` + as long as that other ``Variable`` is also renamed (:issue:`1477`). This + method now does throw when two ``Variables`` would end up with the same name + after the rename (since one of them would get overwritten in this case). + By `Prakhar Goel `_. + + - Fix :py:func:`xarray.testing.assert_allclose` to actually use ``atol`` and + ``rtol`` arguments when called on ``DataArray`` objects (:issue:`1488`). + By `Stephan Hoyer `_. + + - xarray ``quantile`` methods now properly raise a ``TypeError`` when applied to + objects with data stored as ``dask`` arrays (:issue:`1529`). + By `Joe Hamman `_. + + - Fix positional indexing to allow the use of unsigned integers (:issue:`1405`). + By `Joe Hamman `_ and + `Gerrit Holl `_. + + - Creating a :py:class:`Dataset` now raises ``MergeError`` if a coordinate + shares a name with a dimension but is comprised of arbitrary dimensions + (:issue:`1120`). + By `Joe Hamman `_. + + - :py:func:`~xarray.open_rasterio` method now skips rasterio's ``crs`` + attribute if its value is ``None`` (:issue:`1520`). + By `Leevi Annala `_. + + - Fix :py:func:`xarray.DataArray.to_netcdf` to return bytes when no path is + provided (:issue:`1410`). + By `Joe Hamman `_. + + - Fix :py:func:`xarray.save_mfdataset` to properly raise an informative error + when objects other than ``Dataset`` are provided (:issue:`1555`). + By `Joe Hamman `_. + + - :py:func:`xarray.Dataset.copy` would not preserve the encoding property + (:issue:`1586`). + By `Guido Imperiale `_. + + - :py:func:`xarray.concat` would eagerly load dask variables into memory if + the first argument was a numpy variable (:issue:`1588`). + By `Guido Imperiale `_. + + - Fix bug in :py:meth:`~xarray.Dataset.to_netcdf` when writing in append mode + (:issue:`1215`). + By `Joe Hamman `_. + + - Fix ``netCDF4`` backend to properly roundtrip the ``shuffle`` encoding option + (:issue:`1606`). + By `Joe Hamman `_. + + - Fix bug when using ``pytest`` class decorators to skiping certain unittests. + The previous behavior unintentionally causing additional tests to be skipped + (:issue:`1531`). By `Joe Hamman `_. + + - Fix pynio backend for upcoming release of pynio with Python 3 support + (:issue:`1611`). By `Ben Hillman `_. + + - Fix ``seaborn`` import warning for Seaborn versions 0.8 and newer when the + ``apionly`` module was deprecated. + (:issue:`1633`). By `Joe Hamman `_. + + - Fix COMPAT: MultiIndex checking is fragile + (:issue:`1833`). By `Florian Pinault `_. + + - Fix ``rasterio`` backend for Rasterio versions 1.0alpha10 and newer. + (:issue:`1641`). By `Chris Holden `_. + + Bug fixes after rc1 + ~~~~~~~~~~~~~~~~~~~ + + - Suppress warning in IPython autocompletion, related to the deprecation + of ``.T`` attributes (:issue:`1675`). + By `Keisuke Fujii `_. + + - Fix a bug in lazily-indexing netCDF array. (:issue:`1688`) + By `Keisuke Fujii `_. + + - (Internal bug) MemoryCachedArray now supports the orthogonal indexing. + Also made some internal cleanups around array wrappers (:issue:`1429`). + By `Keisuke Fujii `_. + + - (Internal bug) MemoryCachedArray now always wraps ``np.ndarray`` by + ``NumpyIndexingAdapter``. (:issue:`1694`) + By `Keisuke Fujii `_. + + - Fix importing xarray when running Python with ``-OO`` (:issue:`1706`). + By `Stephan Hoyer `_. + + - Saving a netCDF file with a coordinates with a spaces in its names now raises + an appropriate warning (:issue:`1689`). + By `Stephan Hoyer `_. + + - Fix two bugs that were preventing dask arrays from being specified as + coordinates in the DataArray constructor (:issue:`1684`). + By `Joe Hamman `_. + + - Fixed ``apply_ufunc`` with ``dask='parallelized'`` for scalar arguments + (:issue:`1697`). + By `Stephan Hoyer `_. + + - Fix "Chunksize cannot exceed dimension size" error when writing netCDF4 files + loaded from disk (:issue:`1225`). + By `Stephan Hoyer `_. + + - Validate the shape of coordinates with names matching dimensions in the + DataArray constructor (:issue:`1709`). + By `Stephan Hoyer `_. + + - Raise ``NotImplementedError`` when attempting to save a MultiIndex to a + netCDF file (:issue:`1547`). + By `Stephan Hoyer `_. + + - Remove netCDF dependency from rasterio backend tests. + By `Matti Eskelinen `_ + + Bug fixes after rc2 + ~~~~~~~~~~~~~~~~~~~ + + - Fixed unexpected behavior in ``Dataset.set_index()`` and + ``DataArray.set_index()`` introduced by Pandas 0.21.0. Setting a new + index with a single variable resulted in 1-level + ``pandas.MultiIndex`` instead of a simple ``pandas.Index`` + (:issue:`1722`). By `Benoit Bovy `_. + + - Fixed unexpected memory loading of backend arrays after ``print``. + (:issue:`1720`). By `Keisuke Fujii `_. + + .. _whats-new.0.9.6: + + v0.9.6 (8 June 2017) + -------------------- + + This release includes a number of backwards compatible enhancements and bug + fixes. + + Enhancements + ~~~~~~~~~~~~ + + - New :py:meth:`~xarray.Dataset.sortby` method to ``Dataset`` and ``DataArray`` + that enable sorting along dimensions (:issue:`967`). + See :ref:`the docs ` for examples. + By `Chun-Wei Yuan `_ and + `Kyle Heuton `_. + + - Add ``.dt`` accessor to DataArrays for computing datetime-like properties + for the values they contain, similar to ``pandas.Series`` (:issue:`358`). + By `Daniel Rothenberg `_. + + - Renamed internal dask arrays created by ``open_dataset`` to match new dask + conventions (:issue:`1343`). + By `Ryan Abernathey `_. + + - :py:meth:`~xarray.as_variable` is now part of the public API (:issue:`1303`). + By `Benoit Bovy `_. + + - :py:func:`~xarray.align` now supports ``join='exact'``, which raises + an error instead of aligning when indexes to be aligned are not equal. + By `Stephan Hoyer `_. + + - New function :py:func:`~xarray.open_rasterio` for opening raster files with + the `rasterio `_ library. + See :ref:`the docs ` for details. + By `Joe Hamman `_, + `Nic Wayand `_ and + `Fabien Maussion `_ + + Bug fixes + ~~~~~~~~~ + + - Fix error from repeated indexing of datasets loaded from disk (:issue:`1374`). + By `Stephan Hoyer `_. + + - Fix a bug where ``.isel_points`` wrongly assigns unselected coordinate to + ``data_vars``. + By `Keisuke Fujii `_. + + - Tutorial datasets are now checked against a reference MD5 sum to confirm + successful download (:issue:`1392`). By `Matthew Gidden + `_. + + - ``DataArray.chunk()`` now accepts dask specific kwargs like + ``Dataset.chunk()`` does. By `Fabien Maussion `_. + + - Support for ``engine='pydap'`` with recent releases of Pydap (3.2.2+), + including on Python 3 (:issue:`1174`). + + Documentation + ~~~~~~~~~~~~~ + + - A new `gallery `_ + allows to add interactive examples to the documentation. + By `Fabien Maussion `_. + + Testing + ~~~~~~~ + + - Fix test suite failure caused by changes to ``pandas.cut`` function + (:issue:`1386`). + By `Ryan Abernathey `_. + + - Enhanced tests suite by use of ``@network`` decorator, which is + controlled via ``--run-network-tests`` command line argument + to ``py.test`` (:issue:`1393`). + By `Matthew Gidden `_. + + .. _whats-new.0.9.5: + + v0.9.5 (17 April, 2017) + ----------------------- + + Remove an inadvertently introduced print statement. + + .. _whats-new.0.9.3: + + v0.9.3 (16 April, 2017) + ----------------------- + + This minor release includes bug-fixes and backwards compatible enhancements. + + Enhancements + ~~~~~~~~~~~~ + + - New :py:meth:`~xarray.DataArray.persist` method to Datasets and DataArrays to + enable persisting data in distributed memory when using Dask (:issue:`1344`). + By `Matthew Rocklin `_. + + - New :py:meth:`~xarray.DataArray.expand_dims` method for ``DataArray`` and + ``Dataset`` (:issue:`1326`). + By `Keisuke Fujii `_. + + Bug fixes + ~~~~~~~~~ + + - Fix ``.where()`` with ``drop=True`` when arguments do not have indexes + (:issue:`1350`). This bug, introduced in v0.9, resulted in xarray producing + incorrect results in some cases. + By `Stephan Hoyer `_. + + - Fixed writing to file-like objects with :py:meth:`~xarray.Dataset.to_netcdf` + (:issue:`1320`). + `Stephan Hoyer `_. + + - Fixed explicitly setting ``engine='scipy'`` with ``to_netcdf`` when not + providing a path (:issue:`1321`). + `Stephan Hoyer `_. + + - Fixed open_dataarray does not pass properly its parameters to open_dataset + (:issue:`1359`). + `Stephan Hoyer `_. + + - Ensure test suite works when runs from an installed version of xarray + (:issue:`1336`). Use ``@pytest.mark.slow`` instead of a custom flag to mark + slow tests. + By `Stephan Hoyer `_ + + .. _whats-new.0.9.2: + + v0.9.2 (2 April 2017) + --------------------- + + The minor release includes bug-fixes and backwards compatible enhancements. + + Enhancements + ~~~~~~~~~~~~ + + - ``rolling`` on Dataset is now supported (:issue:`859`). + + - ``.rolling()`` on Dataset is now supported (:issue:`859`). + By `Keisuke Fujii `_. + + - When bottleneck version 1.1 or later is installed, use bottleneck for rolling + ``var``, ``argmin``, ``argmax``, and ``rank`` computations. Also, rolling + median now accepts a ``min_periods`` argument (:issue:`1276`). + By `Joe Hamman `_. + + - When ``.plot()`` is called on a 2D DataArray and only one dimension is + specified with ``x=`` or ``y=``, the other dimension is now guessed + (:issue:`1291`). + By `Vincent Noel `_. + + - Added new method :py:meth:`~Dataset.assign_attrs` to ``DataArray`` and + ``Dataset``, a chained-method compatible implementation of the + ``dict.update`` method on attrs (:issue:`1281`). + By `Henry S. Harrison `_. + + - Added new ``autoclose=True`` argument to + :py:func:`~xarray.open_mfdataset` to explicitly close opened files when not in + use to prevent occurrence of an OS Error related to too many open files + (:issue:`1198`). + Note, the default is ``autoclose=False``, which is consistent with + previous xarray behavior. + By `Phillip J. Wolfram `_. + + - The ``repr()`` of ``Dataset`` and ``DataArray`` attributes uses a similar + format to coordinates and variables, with vertically aligned entries + truncated to fit on a single line (:issue:`1319`). Hopefully this will stop + people writing ``data.attrs = {}`` and discarding metadata in notebooks for + the sake of cleaner output. The full metadata is still available as + ``data.attrs``. + By `Zac Hatfield-Dodds `_. + + - Enhanced tests suite by use of ``@slow`` and ``@flaky`` decorators, which are + controlled via ``--run-flaky`` and ``--skip-slow`` command line arguments + to ``py.test`` (:issue:`1336`). + By `Stephan Hoyer `_ and + `Phillip J. Wolfram `_. + + - New aggregation on rolling objects :py:meth:`~core.rolling.DataArrayRolling.count` + which providing a rolling count of valid values (:issue:`1138`). + + Bug fixes + ~~~~~~~~~ + - Rolling operations now keep preserve original dimension order (:issue:`1125`). + By `Keisuke Fujii `_. + + - Fixed ``sel`` with ``method='nearest'`` on Python 2.7 and 64-bit Windows + (:issue:`1140`). + `Stephan Hoyer `_. + + - Fixed ``where`` with ``drop='True'`` for empty masks (:issue:`1341`). + By `Stephan Hoyer `_ and + `Phillip J. Wolfram `_. + + .. _whats-new.0.9.1: + + v0.9.1 (30 January 2017) + ------------------------ + + Renamed the "Unindexed dimensions" section in the ``Dataset`` and + ``DataArray`` repr (added in v0.9.0) to "Dimensions without coordinates" + (:issue:`1199`). + + .. _whats-new.0.9.0: + + v0.9.0 (25 January 2017) + ------------------------ + + This major release includes five months worth of enhancements and bug fixes from + 24 contributors, including some significant changes that are not fully backwards + compatible. Highlights include: + + - Coordinates are now *optional* in the xarray data model, even for dimensions. + - Changes to caching, lazy loading and pickling to improve xarray's experience + for parallel computing. + - Improvements for accessing and manipulating ``pandas.MultiIndex`` levels. + - Many new methods and functions, including + :py:meth:`~DataArray.quantile`, + :py:meth:`~DataArray.cumsum`, + :py:meth:`~DataArray.cumprod` + :py:attr:`~DataArray.combine_first` + :py:meth:`~DataArray.set_index`, + :py:meth:`~DataArray.reset_index`, + :py:meth:`~DataArray.reorder_levels`, + :py:func:`~xarray.full_like`, + :py:func:`~xarray.zeros_like`, + :py:func:`~xarray.ones_like` + :py:func:`~xarray.open_dataarray`, + :py:meth:`~DataArray.compute`, + :py:meth:`Dataset.info`, + :py:func:`testing.assert_equal`, + :py:func:`testing.assert_identical`, and + :py:func:`testing.assert_allclose`. + + Breaking changes + ~~~~~~~~~~~~~~~~ + + - Index coordinates for each dimensions are now optional, and no longer created + by default :issue:`1017`. You can identify such dimensions without coordinates + by their appearance in list of "Dimensions without coordinates" in the + ``Dataset`` or ``DataArray`` repr: + + .. ipython:: + :verbatim: + + In [1]: xr.Dataset({"foo": (("x", "y"), [[1, 2]])}) + Out[1]: + + Dimensions: (x: 1, y: 2) + Dimensions without coordinates: x, y Data variables: - y int64 2 - - In [13]: ds.sel(x=[1.1, 2.1], method="pad") - Out[13]: - - Dimensions: (x: 2) + foo (x, y) int64 1 2 + + This has a number of implications: + + - :py:func:`~align` and :py:meth:`~Dataset.reindex` can now error, if + dimensions labels are missing and dimensions have different sizes. + - Because pandas does not support missing indexes, methods such as + ``to_dataframe``/``from_dataframe`` and ``stack``/``unstack`` no longer + roundtrip faithfully on all inputs. Use :py:meth:`~Dataset.reset_index` to + remove undesired indexes. + - ``Dataset.__delitem__`` and :py:meth:`~Dataset.drop` no longer delete/drop + variables that have dimensions matching a deleted/dropped variable. + - ``DataArray.coords.__delitem__`` is now allowed on variables matching + dimension names. + - ``.sel`` and ``.loc`` now handle indexing along a dimension without + coordinate labels by doing integer based indexing. See + :ref:`indexing.missing_coordinates` for an example. + - :py:attr:`~Dataset.indexes` is no longer guaranteed to include all + dimensions names as keys. The new method :py:meth:`~Dataset.get_index` has + been added to get an index for a dimension guaranteed, falling back to + produce a default ``RangeIndex`` if necessary. + + - The default behavior of ``merge`` is now ``compat='no_conflicts'``, so some + merges will now succeed in cases that previously raised + ``xarray.MergeError``. Set ``compat='broadcast_equals'`` to restore the + previous default. See :ref:`combining.no_conflicts` for more details. + + - Reading :py:attr:`~DataArray.values` no longer always caches values in a NumPy + array :issue:`1128`. Caching of ``.values`` on variables read from netCDF + files on disk is still the default when :py:func:`open_dataset` is called with + ``cache=True``. + By `Guido Imperiale `_ and + `Stephan Hoyer `_. + - Pickling a ``Dataset`` or ``DataArray`` linked to a file on disk no longer + caches its values into memory before pickling (:issue:`1128`). Instead, pickle + stores file paths and restores objects by reopening file references. This + enables preliminary, experimental use of xarray for opening files with + `dask.distributed `_. + By `Stephan Hoyer `_. + - Coordinates used to index a dimension are now loaded eagerly into + :py:class:`pandas.Index` objects, instead of loading the values lazily. + By `Guido Imperiale `_. + - Automatic levels for 2d plots are now guaranteed to land on ``vmin`` and + ``vmax`` when these kwargs are explicitly provided (:issue:`1191`). The + automated level selection logic also slightly changed. + By `Fabien Maussion `_. + + - ``DataArray.rename()`` behavior changed to strictly change the ``DataArray.name`` + if called with string argument, or strictly change coordinate names if called with + dict-like argument. + By `Markus Gonser `_. + + - By default ``to_netcdf()`` add a ``_FillValue = NaN`` attributes to float types. + By `Frederic Laliberte `_. + + - ``repr`` on ``DataArray`` objects uses an shortened display for NumPy array + data that is less likely to overflow onto multiple pages (:issue:`1207`). + By `Stephan Hoyer `_. + + - xarray no longer supports python 3.3, versions of dask prior to v0.9.0, + or versions of bottleneck prior to v1.0. + + Deprecations + ~~~~~~~~~~~~ + + - Renamed the ``Coordinate`` class from xarray's low level API to + :py:class:`~xarray.IndexVariable`. ``Variable.to_variable`` and + ``Variable.to_coord`` have been renamed to + :py:meth:`~xarray.Variable.to_base_variable` and + :py:meth:`~xarray.Variable.to_index_variable`. + - Deprecated supplying ``coords`` as a dictionary to the ``DataArray`` + constructor without also supplying an explicit ``dims`` argument. The old + behavior encouraged relying on the iteration order of dictionaries, which is + a bad practice (:issue:`727`). + - Removed a number of methods deprecated since v0.7.0 or earlier: + ``load_data``, ``vars``, ``drop_vars``, ``dump``, ``dumps`` and the + ``variables`` keyword argument to ``Dataset``. + - Removed the dummy module that enabled ``import xray``. + + Enhancements + ~~~~~~~~~~~~ + + - Added new method :py:meth:`~DataArray.combine_first` to ``DataArray`` and + ``Dataset``, based on the pandas method of the same name (see :ref:`combine`). + By `Chun-Wei Yuan `_. + + - Added the ability to change default automatic alignment (arithmetic_join="inner") + for binary operations via :py:func:`~xarray.set_options()` + (see :ref:`math automatic alignment`). + By `Chun-Wei Yuan `_. + + - Add checking of ``attr`` names and values when saving to netCDF, raising useful + error messages if they are invalid. (:issue:`911`). + By `Robin Wilson `_. + - Added ability to save ``DataArray`` objects directly to netCDF files using + :py:meth:`~xarray.DataArray.to_netcdf`, and to load directly from netCDF files + using :py:func:`~xarray.open_dataarray` (:issue:`915`). These remove the need + to convert a ``DataArray`` to a ``Dataset`` before saving as a netCDF file, + and deals with names to ensure a perfect 'roundtrip' capability. + By `Robin Wilson `_. + - Multi-index levels are now accessible as "virtual" coordinate variables, + e.g., ``ds['time']`` can pull out the ``'time'`` level of a multi-index + (see :ref:`coordinates`). ``sel`` also accepts providing multi-index levels + as keyword arguments, e.g., ``ds.sel(time='2000-01')`` + (see :ref:`multi-level indexing`). + By `Benoit Bovy `_. + - Added ``set_index``, ``reset_index`` and ``reorder_levels`` methods to + easily create and manipulate (multi-)indexes (see :ref:`reshape.set_index`). + By `Benoit Bovy `_. + - Added the ``compat`` option ``'no_conflicts'`` to ``merge``, allowing the + combination of xarray objects with disjoint (:issue:`742`) or + overlapping (:issue:`835`) coordinates as long as all present data agrees. + By `Johnnie Gray `_. See + :ref:`combining.no_conflicts` for more details. + - It is now possible to set ``concat_dim=None`` explicitly in + :py:func:`~xarray.open_mfdataset` to disable inferring a dimension along + which to concatenate. + By `Stephan Hoyer `_. + - Added methods :py:meth:`DataArray.compute`, :py:meth:`Dataset.compute`, and + :py:meth:`Variable.compute` as a non-mutating alternative to + :py:meth:`~DataArray.load`. + By `Guido Imperiale `_. + - Adds DataArray and Dataset methods :py:meth:`~xarray.DataArray.cumsum` and + :py:meth:`~xarray.DataArray.cumprod`. By `Phillip J. Wolfram + `_. + + - New properties :py:attr:`Dataset.sizes` and :py:attr:`DataArray.sizes` for + providing consistent access to dimension length on both ``Dataset`` and + ``DataArray`` (:issue:`921`). + By `Stephan Hoyer `_. + - New keyword argument ``drop=True`` for :py:meth:`~DataArray.sel`, + :py:meth:`~DataArray.isel` and :py:meth:`~DataArray.squeeze` for dropping + scalar coordinates that arise from indexing. + ``DataArray`` (:issue:`242`). + By `Stephan Hoyer `_. + + - New top-level functions :py:func:`~xarray.full_like`, + :py:func:`~xarray.zeros_like`, and :py:func:`~xarray.ones_like` + By `Guido Imperiale `_. + - Overriding a preexisting attribute with + :py:func:`~xarray.register_dataset_accessor` or + :py:func:`~xarray.register_dataarray_accessor` now issues a warning instead of + raising an error (:issue:`1082`). + By `Stephan Hoyer `_. + - Options for axes sharing between subplots are exposed to + :py:class:`~xarray.plot.FacetGrid` and :py:func:`~xarray.plot.plot`, so axes + sharing can be disabled for polar plots. + By `Bas Hoonhout `_. + - New utility functions :py:func:`~xarray.testing.assert_equal`, + :py:func:`~xarray.testing.assert_identical`, and + :py:func:`~xarray.testing.assert_allclose` for asserting relationships + between xarray objects, designed for use in a pytest test suite. + - ``figsize``, ``size`` and ``aspect`` plot arguments are now supported for all + plots (:issue:`897`). See :ref:`plotting.figsize` for more details. + By `Stephan Hoyer `_ and + `Fabien Maussion `_. + - New :py:meth:`~Dataset.info` method to summarize ``Dataset`` variables + and attributes. The method prints to a buffer (e.g. ``stdout``) with output + similar to what the command line utility ``ncdump -h`` produces (:issue:`1150`). + By `Joe Hamman `_. + - Added the ability write unlimited netCDF dimensions with the ``scipy`` and + ``netcdf4`` backends via the new ``xray.Dataset.encoding`` attribute + or via the ``unlimited_dims`` argument to ``xray.Dataset.to_netcdf``. + By `Joe Hamman `_. + - New :py:meth:`~DataArray.quantile` method to calculate quantiles from + DataArray objects (:issue:`1187`). + By `Joe Hamman `_. + + + Bug fixes + ~~~~~~~~~ + - ``groupby_bins`` now restores empty bins by default (:issue:`1019`). + By `Ryan Abernathey `_. + + - Fix issues for dates outside the valid range of pandas timestamps + (:issue:`975`). By `Mathias Hauser `_. + + - Unstacking produced flipped array after stacking decreasing coordinate values + (:issue:`980`). + By `Stephan Hoyer `_. + + - Setting ``dtype`` via the ``encoding`` parameter of ``to_netcdf`` failed if + the encoded dtype was the same as the dtype of the original array + (:issue:`873`). + By `Stephan Hoyer `_. + + - Fix issues with variables where both attributes ``_FillValue`` and + ``missing_value`` are set to ``NaN`` (:issue:`997`). + By `Marco Zühlke `_. + + - ``.where()`` and ``.fillna()`` now preserve attributes (:issue:`1009`). + By `Fabien Maussion `_. + + - Applying :py:func:`broadcast()` to an xarray object based on the dask backend + won't accidentally convert the array from dask to numpy anymore (:issue:`978`). + By `Guido Imperiale `_. + + - ``Dataset.concat()`` now preserves variables order (:issue:`1027`). + By `Fabien Maussion `_. + + - Fixed an issue with pcolormesh (:issue:`781`). A new + ``infer_intervals`` keyword gives control on whether the cell intervals + should be computed or not. + By `Fabien Maussion `_. + + - Grouping over an dimension with non-unique values with ``groupby`` gives + correct groups. + By `Stephan Hoyer `_. + + - Fixed accessing coordinate variables with non-string names from ``.coords``. + By `Stephan Hoyer `_. + + - :py:meth:`~xarray.DataArray.rename` now simultaneously renames the array and + any coordinate with the same name, when supplied via a :py:class:`dict` + (:issue:`1116`). + By `Yves Delley `_. + + - Fixed sub-optimal performance in certain operations with object arrays (:issue:`1121`). + By `Yves Delley `_. + + - Fix ``.groupby(group)`` when ``group`` has datetime dtype (:issue:`1132`). + By `Jonas Sølvsteen `_. + + - Fixed a bug with facetgrid (the ``norm`` keyword was ignored, :issue:`1159`). + By `Fabien Maussion `_. + + - Resolved a concurrency bug that could cause Python to crash when + simultaneously reading and writing netCDF4 files with dask (:issue:`1172`). + By `Stephan Hoyer `_. + + - Fix to make ``.copy()`` actually copy dask arrays, which will be relevant for + future releases of dask in which dask arrays will be mutable (:issue:`1180`). + By `Stephan Hoyer `_. + + - Fix opening NetCDF files with multi-dimensional time variables + (:issue:`1229`). + By `Stephan Hoyer `_. + + Performance improvements + ~~~~~~~~~~~~~~~~~~~~~~~~ + + - ``xarray.Dataset.isel_points`` and ``xarray.Dataset.sel_points`` now + use vectorised indexing in numpy and dask (:issue:`1161`), which can + result in several orders of magnitude speedup. + By `Jonathan Chambers `_. + + .. _whats-new.0.8.2: + + v0.8.2 (18 August 2016) + ----------------------- + + This release includes a number of bug fixes and minor enhancements. + + Breaking changes + ~~~~~~~~~~~~~~~~ + + - :py:func:`~xarray.broadcast` and :py:func:`~xarray.concat` now auto-align + inputs, using ``join=outer``. Previously, these functions raised + ``ValueError`` for non-aligned inputs. + By `Guido Imperiale `_. + + Enhancements + ~~~~~~~~~~~~ + + - New documentation on :ref:`panel transition`. By + `Maximilian Roos `_. + - New ``Dataset`` and ``DataArray`` methods :py:meth:`~xarray.Dataset.to_dict` + and :py:meth:`~xarray.Dataset.from_dict` to allow easy conversion between + dictionaries and xarray objects (:issue:`432`). See + :ref:`dictionary IO` for more details. + By `Julia Signell `_. + - Added ``exclude`` and ``indexes`` optional parameters to :py:func:`~xarray.align`, + and ``exclude`` optional parameter to :py:func:`~xarray.broadcast`. + By `Guido Imperiale `_. + - Better error message when assigning variables without dimensions + (:issue:`971`). By `Stephan Hoyer `_. + - Better error message when reindex/align fails due to duplicate index values + (:issue:`956`). By `Stephan Hoyer `_. + + Bug fixes + ~~~~~~~~~ + + - Ensure xarray works with h5netcdf v0.3.0 for arrays with ``dtype=str`` + (:issue:`953`). By `Stephan Hoyer `_. + - ``Dataset.__dir__()`` (i.e. the method python calls to get autocomplete + options) failed if one of the dataset's keys was not a string (:issue:`852`). + By `Maximilian Roos `_. + - ``Dataset`` constructor can now take arbitrary objects as values + (:issue:`647`). By `Maximilian Roos `_. + - Clarified ``copy`` argument for :py:meth:`~xarray.DataArray.reindex` and + :py:func:`~xarray.align`, which now consistently always return new xarray + objects (:issue:`927`). + - Fix ``open_mfdataset`` with ``engine='pynio'`` (:issue:`936`). + By `Stephan Hoyer `_. + - ``groupby_bins`` sorted bin labels as strings (:issue:`952`). + By `Stephan Hoyer `_. + - Fix bug introduced by v0.8.0 that broke assignment to datasets when both the + left and right side have the same non-unique index values (:issue:`956`). + + .. _whats-new.0.8.1: + + v0.8.1 (5 August 2016) + ---------------------- + + Bug fixes + ~~~~~~~~~ + + - Fix bug in v0.8.0 that broke assignment to Datasets with non-unique + indexes (:issue:`943`). By `Stephan Hoyer `_. + + .. _whats-new.0.8.0: + + v0.8.0 (2 August 2016) + ---------------------- + + This release includes four months of new features and bug fixes, including + several breaking changes. + + .. _v0.8.0.breaking: + + Breaking changes + ~~~~~~~~~~~~~~~~ + + - Dropped support for Python 2.6 (:issue:`855`). + - Indexing on multi-index now drop levels, which is consistent with pandas. + It also changes the name of the dimension / coordinate when the multi-index is + reduced to a single index (:issue:`802`). + - Contour plots no longer add a colorbar per default (:issue:`866`). Filled + contour plots are unchanged. + - ``DataArray.values`` and ``.data`` now always returns an NumPy array-like + object, even for 0-dimensional arrays with object dtype (:issue:`867`). + Previously, ``.values`` returned native Python objects in such cases. To + convert the values of scalar arrays to Python objects, use the ``.item()`` + method. + + Enhancements + ~~~~~~~~~~~~ + + - Groupby operations now support grouping over multidimensional variables. A new + method called :py:meth:`~xarray.Dataset.groupby_bins` has also been added to + allow users to specify bins for grouping. The new features are described in + :ref:`groupby.multidim` and :ref:`/examples/multidimensional-coords.ipynb`. + By `Ryan Abernathey `_. + + - DataArray and Dataset method :py:meth:`where` now supports a ``drop=True`` + option that clips coordinate elements that are fully masked. By + `Phillip J. Wolfram `_. + + - New top level :py:func:`merge` function allows for combining variables from + any number of ``Dataset`` and/or ``DataArray`` variables. See :ref:`merge` + for more details. By `Stephan Hoyer `_. + + - :py:meth:`DataArray.resample` and :py:meth:`Dataset.resample` now support the + ``keep_attrs=False`` option that determines whether variable and dataset + attributes are retained in the resampled object. By + `Jeremy McGibbon `_. + + - Better multi-index support in :py:meth:`DataArray.sel`, + :py:meth:`DataArray.loc`, :py:meth:`Dataset.sel` and + :py:meth:`Dataset.loc`, which now behave more closely to pandas and + which also accept dictionaries for indexing based on given level names + and labels (see :ref:`multi-level indexing`). + By `Benoit Bovy `_. + + - New (experimental) decorators :py:func:`~xarray.register_dataset_accessor` and + :py:func:`~xarray.register_dataarray_accessor` for registering custom xarray + extensions without subclassing. They are described in the new documentation + page on :ref:`internals`. By `Stephan Hoyer `_. + + - Round trip boolean datatypes. Previously, writing boolean datatypes to netCDF + formats would raise an error since netCDF does not have a `bool` datatype. + This feature reads/writes a `dtype` attribute to boolean variables in netCDF + files. By `Joe Hamman `_. + + - 2D plotting methods now have two new keywords (`cbar_ax` and `cbar_kwargs`), + allowing more control on the colorbar (:issue:`872`). + By `Fabien Maussion `_. + + - New Dataset method :py:meth:`Dataset.filter_by_attrs`, akin to + ``netCDF4.Dataset.get_variables_by_attributes``, to easily filter + data variables using its attributes. + `Filipe Fernandes `_. + + Bug fixes + ~~~~~~~~~ + + - Attributes were being retained by default for some resampling + operations when they should not. With the ``keep_attrs=False`` option, they + will no longer be retained by default. This may be backwards-incompatible + with some scripts, but the attributes may be kept by adding the + ``keep_attrs=True`` option. By + `Jeremy McGibbon `_. + + - Concatenating xarray objects along an axis with a MultiIndex or PeriodIndex + preserves the nature of the index (:issue:`875`). By + `Stephan Hoyer `_. + + - Fixed bug in arithmetic operations on DataArray objects whose dimensions + are numpy structured arrays or recarrays :issue:`861`, :issue:`837`. By + `Maciek Swat `_. + + - ``decode_cf_timedelta`` now accepts arrays with ``ndim`` >1 (:issue:`842`). + This fixes issue :issue:`665`. + `Filipe Fernandes `_. + + - Fix a bug where `xarray.ufuncs` that take two arguments would incorrectly + use to numpy functions instead of dask.array functions (:issue:`876`). By + `Stephan Hoyer `_. + + - Support for pickling functions from ``xarray.ufuncs`` (:issue:`901`). By + `Stephan Hoyer `_. + + - ``Variable.copy(deep=True)`` no longer converts MultiIndex into a base Index + (:issue:`769`). By `Benoit Bovy `_. + + - Fixes for groupby on dimensions with a multi-index (:issue:`867`). By + `Stephan Hoyer `_. + + - Fix printing datasets with unicode attributes on Python 2 (:issue:`892`). By + `Stephan Hoyer `_. + + - Fixed incorrect test for dask version (:issue:`891`). By + `Stephan Hoyer `_. + + - Fixed `dim` argument for `isel_points`/`sel_points` when a `pandas.Index` is + passed. By `Stephan Hoyer `_. + + - :py:func:`~xarray.plot.contour` now plots the correct number of contours + (:issue:`866`). By `Fabien Maussion `_. + + .. _whats-new.0.7.2: + + v0.7.2 (13 March 2016) + ---------------------- + + This release includes two new, entirely backwards compatible features and + several bug fixes. + + Enhancements + ~~~~~~~~~~~~ + + - New DataArray method :py:meth:`DataArray.dot` for calculating the dot + product of two DataArrays along shared dimensions. By + `Dean Pospisil `_. + + - Rolling window operations on DataArray objects are now supported via a new + :py:meth:`DataArray.rolling` method. For example: + + .. ipython:: + :verbatim: + + In [1]: import xarray as xr + ...: import numpy as np + + In [2]: arr = xr.DataArray(np.arange(0, 7.5, 0.5).reshape(3, 5), dims=("x", "y")) + + In [3]: arr + Out[3]: + + array([[ 0. , 0.5, 1. , 1.5, 2. ], + [ 2.5, 3. , 3.5, 4. , 4.5], + [ 5. , 5.5, 6. , 6.5, 7. ]]) Coordinates: - * x (x) int64 1 2 - Data variables: - y (x) int64 2 3 - - See :ref:`nearest neighbor lookups` for more details. -- You can now control the underlying backend used for accessing remote - datasets (via OPeNDAP) by specifying ``engine='netcdf4'`` or - ``engine='pydap'``. -- xray now provides experimental support for reading and writing netCDF4 files directly - via `h5py`_ with the `h5netcdf`_ package, avoiding the netCDF4-Python package. You - will need to install h5netcdf and specify ``engine='h5netcdf'`` to try this - feature. -- Accessing data from remote datasets now has retrying logic (with exponential - backoff) that should make it robust to occasional bad responses from DAP - servers. -- You can control the width of the Dataset repr with ``xray.set_options``. - It can be used either as a context manager, in which case the default is restored - outside the context: - - .. ipython:: python - - ds = xray.Dataset({"x": np.arange(1000)}) - with xray.set_options(display_width=40): - print(ds) - - Or to set a global option: - - .. ipython:: + * x (x) int64 0 1 2 + * y (y) int64 0 1 2 3 4 + + In [4]: arr.rolling(y=3, min_periods=2).mean() + Out[4]: + + array([[ nan, 0.25, 0.5 , 1. , 1.5 ], + [ nan, 2.75, 3. , 3.5 , 4. ], + [ nan, 5.25, 5.5 , 6. , 6.5 ]]) + Coordinates: + * x (x) int64 0 1 2 + * y (y) int64 0 1 2 3 4 + + See :ref:`comput.rolling` for more details. By + `Joe Hamman `_. + + Bug fixes + ~~~~~~~~~ + + - Fixed an issue where plots using pcolormesh and Cartopy axes were being distorted + by the inference of the axis interval breaks. This change chooses not to modify + the coordinate variables when the axes have the attribute ``projection``, allowing + Cartopy to handle the extent of pcolormesh plots (:issue:`781`). By + `Joe Hamman `_. + + - 2D plots now better handle additional coordinates which are not ``DataArray`` + dimensions (:issue:`788`). By `Fabien Maussion `_. + + + .. _whats-new.0.7.1: + + v0.7.1 (16 February 2016) + ------------------------- + + This is a bug fix release that includes two small, backwards compatible enhancements. + We recommend that all users upgrade. + + Enhancements + ~~~~~~~~~~~~ + + - Numerical operations now return empty objects on no overlapping labels rather + than raising ``ValueError`` (:issue:`739`). + - :py:class:`~pandas.Series` is now supported as valid input to the ``Dataset`` + constructor (:issue:`740`). + + Bug fixes + ~~~~~~~~~ + + - Restore checks for shape consistency between data and coordinates in the + DataArray constructor (:issue:`758`). + - Single dimension variables no longer transpose as part of a broader + ``.transpose``. This behavior was causing ``pandas.PeriodIndex`` dimensions + to lose their type (:issue:`749`) + - :py:class:`~xarray.Dataset` labels remain as their native type on ``.to_dataset``. + Previously they were coerced to strings (:issue:`745`) + - Fixed a bug where replacing a ``DataArray`` index coordinate would improperly + align the coordinate (:issue:`725`). + - ``DataArray.reindex_like`` now maintains the dtype of complex numbers when + reindexing leads to NaN values (:issue:`738`). + - ``Dataset.rename`` and ``DataArray.rename`` support the old and new names + being the same (:issue:`724`). + - Fix :py:meth:`~xarray.Dataset.from_dataframe` for DataFrames with Categorical + column and a MultiIndex index (:issue:`737`). + - Fixes to ensure xarray works properly after the upcoming pandas v0.18 and + NumPy v1.11 releases. + + Acknowledgments + ~~~~~~~~~~~~~~~ + + The following individuals contributed to this release: + + - Edward Richards + - Maximilian Roos + - Rafael Guedes + - Spencer Hill + - Stephan Hoyer + + .. _whats-new.0.7.0: + + v0.7.0 (21 January 2016) + ------------------------ + + This major release includes redesign of :py:class:`~xarray.DataArray` + internals, as well as new methods for reshaping, rolling and shifting + data. It includes preliminary support for :py:class:`pandas.MultiIndex`, + as well as a number of other features and bug fixes, several of which + offer improved compatibility with pandas. + + New name + ~~~~~~~~ + + The project formerly known as "xray" is now "xarray", pronounced "x-array"! + This avoids a namespace conflict with the entire field of x-ray science. Renaming + our project seemed like the right thing to do, especially because some + scientists who work with actual x-rays are interested in using this project in + their work. Thanks for your understanding and patience in this transition. You + can now find our documentation and code repository at new URLs: + + - http://xarray.pydata.org + - http://github.com/pydata/xarray/ + + To ease the transition, we have simultaneously released v0.7.0 of both + ``xray`` and ``xarray`` on the Python Package Index. These packages are + identical. For now, ``import xray`` still works, except it issues a + deprecation warning. This will be the last xray release. Going forward, we + recommend switching your import statements to ``import xarray as xr``. + + .. _v0.7.0.breaking: + + Breaking changes + ~~~~~~~~~~~~~~~~ + + - The internal data model used by ``xray.DataArray`` has been + rewritten to fix several outstanding issues (:issue:`367`, :issue:`634`, + `this stackoverflow report`_). Internally, ``DataArray`` is now implemented + in terms of ``._variable`` and ``._coords`` attributes instead of holding + variables in a ``Dataset`` object. + + This refactor ensures that if a DataArray has the + same name as one of its coordinates, the array and the coordinate no longer + share the same data. + + In practice, this means that creating a DataArray with the same ``name`` as + one of its dimensions no longer automatically uses that array to label the + corresponding coordinate. You will now need to provide coordinate labels + explicitly. Here's the old behavior: + + .. ipython:: :verbatim: - - In [1]: xray.set_options(display_width=80) - - The default value for the ``display_width`` option is 80. - -.. _h5py: http://www.h5py.org/ -.. _h5netcdf: https://github.com/shoyer/h5netcdf - -Deprecations -~~~~~~~~~~~~ - -- The method ``load_data()`` has been renamed to the more succinct - ``xray.Dataset.load``. - -v0.4.1 (18 March 2015) ----------------------- - -The release contains bug fixes and several new features. All changes should be -fully backwards compatible. - -Enhancements -~~~~~~~~~~~~ - -- New documentation sections on :ref:`time-series` and - :ref:`combining multiple files`. -- ``xray.Dataset.resample`` lets you resample a dataset or data array to - a new temporal resolution. The syntax is the `same as pandas`_, except you - need to supply the time dimension explicitly: - - .. ipython:: python + + In [2]: xray.DataArray([4, 5, 6], dims="x", name="x") + Out[2]: + + array([4, 5, 6]) + Coordinates: + * x (x) int64 4 5 6 + + and the new behavior (compare the values of the ``x`` coordinate): + + .. ipython:: :verbatim: - - time = pd.date_range("2000-01-01", freq="6H", periods=10) - array = xray.DataArray(np.arange(10), [("time", time)]) - array.resample("1D", dim="time") - - You can specify how to do the resampling with the ``how`` argument and other - options such as ``closed`` and ``label`` let you control labeling: - - .. ipython:: python + + In [2]: xray.DataArray([4, 5, 6], dims="x", name="x") + Out[2]: + + array([4, 5, 6]) + Coordinates: + * x (x) int64 0 1 2 + + - It is no longer possible to convert a DataArray to a Dataset with + ``xray.DataArray.to_dataset`` if it is unnamed. This will now + raise ``ValueError``. If the array is unnamed, you need to supply the + ``name`` argument. + + .. _this stackoverflow report: http://stackoverflow.com/questions/33158558/python-xray-extract-first-and-last-time-value-within-each-month-of-a-timeseries + + Enhancements + ~~~~~~~~~~~~ + + - Basic support for :py:class:`~pandas.MultiIndex` coordinates on xray objects, including + indexing, :py:meth:`~DataArray.stack` and :py:meth:`~DataArray.unstack`: + + .. ipython:: :verbatim: - - array.resample("1D", dim="time", how="sum", label="right") - - If the desired temporal resolution is higher than the original data - (upsampling), xray will insert missing values: - - .. ipython:: python + + In [7]: df = pd.DataFrame({"foo": range(3), "x": ["a", "b", "b"], "y": [0, 0, 1]}) + + In [8]: s = df.set_index(["x", "y"])["foo"] + + In [12]: arr = xray.DataArray(s, dims="z") + + In [13]: arr + Out[13]: + + array([0, 1, 2]) + Coordinates: + * z (z) object ('a', 0) ('b', 0) ('b', 1) + + In [19]: arr.indexes["z"] + Out[19]: + MultiIndex(levels=[[u'a', u'b'], [0, 1]], + labels=[[0, 1, 1], [0, 0, 1]], + names=[u'x', u'y']) + + In [14]: arr.unstack("z") + Out[14]: + + array([[ 0., nan], + [ 1., 2.]]) + Coordinates: + * x (x) object 'a' 'b' + * y (y) int64 0 1 + + In [26]: arr.unstack("z").stack(z=("x", "y")) + Out[26]: + + array([ 0., nan, 1., 2.]) + Coordinates: + * z (z) object ('a', 0) ('a', 1) ('b', 0) ('b', 1) + + See :ref:`reshape.stack` for more details. + + .. warning:: + + xray's MultiIndex support is still experimental, and we have a long to- + do list of desired additions (:issue:`719`), including better display of + multi-index levels when printing a ``Dataset``, and support for saving + datasets with a MultiIndex to a netCDF file. User contributions in this + area would be greatly appreciated. + + - Support for reading GRIB, HDF4 and other file formats via PyNIO_. See + :ref:`io.pynio` for more details. + - Better error message when a variable is supplied with the same name as + one of its dimensions. + - Plotting: more control on colormap parameters (:issue:`642`). ``vmin`` and + ``vmax`` will not be silently ignored anymore. Setting ``center=False`` + prevents automatic selection of a divergent colormap. + - New ``xray.Dataset.shift`` and ``xray.Dataset.roll`` methods + for shifting/rotating datasets or arrays along a dimension: + + .. ipython:: python + :okwarning: + + array = xray.DataArray([5, 6, 7, 8], dims="x") + array.shift(x=2) + array.roll(x=2) + + Notice that ``shift`` moves data independently of coordinates, but ``roll`` + moves both data and coordinates. + - Assigning a ``pandas`` object directly as a ``Dataset`` variable is now permitted. Its + index names correspond to the ``dims`` of the ``Dataset``, and its data is aligned. + - Passing a :py:class:`pandas.DataFrame` or ``pandas.Panel`` to a Dataset constructor + is now permitted. + - New function ``xray.broadcast`` for explicitly broadcasting + ``DataArray`` and ``Dataset`` objects against each other. For example: + + .. ipython:: python + + a = xray.DataArray([1, 2, 3], dims="x") + b = xray.DataArray([5, 6], dims="y") + a + b + a2, b2 = xray.broadcast(a, b) + a2 + b2 + + .. _PyNIO: https://www.pyngl.ucar.edu/Nio.shtml + + Bug fixes + ~~~~~~~~~ + + - Fixes for several issues found on ``DataArray`` objects with the same name + as one of their coordinates (see :ref:`v0.7.0.breaking` for more details). + - ``DataArray.to_masked_array`` always returns masked array with mask being an + array (not a scalar value) (:issue:`684`) + - Allows for (imperfect) repr of Coords when underlying index is PeriodIndex (:issue:`645`). + - Fixes for several issues found on ``DataArray`` objects with the same name + as one of their coordinates (see :ref:`v0.7.0.breaking` for more details). + - Attempting to assign a ``Dataset`` or ``DataArray`` variable/attribute using + attribute-style syntax (e.g., ``ds.foo = 42``) now raises an error rather + than silently failing (:issue:`656`, :issue:`714`). + - You can now pass pandas objects with non-numpy dtypes (e.g., ``categorical`` + or ``datetime64`` with a timezone) into xray without an error + (:issue:`716`). + + Acknowledgments + ~~~~~~~~~~~~~~~ + + The following individuals contributed to this release: + + - Antony Lee + - Fabien Maussion + - Joe Hamman + - Maximilian Roos + - Stephan Hoyer + - Takeshi Kanmae + - femtotrader + + v0.6.1 (21 October 2015) + ------------------------ + + This release contains a number of bug and compatibility fixes, as well + as enhancements to plotting, indexing and writing files to disk. + + Note that the minimum required version of dask for use with xray is now + version 0.6. + + API Changes + ~~~~~~~~~~~ + + - The handling of colormaps and discrete color lists for 2D plots in + ``xray.DataArray.plot`` was changed to provide more compatibility + with matplotlib's ``contour`` and ``contourf`` functions (:issue:`538`). + Now discrete lists of colors should be specified using ``colors`` keyword, + rather than ``cmap``. + + Enhancements + ~~~~~~~~~~~~ + + - Faceted plotting through ``xray.plot.FacetGrid`` and the + ``xray.plot.plot`` method. See :ref:`plotting.faceting` for more details + and examples. + - ``xray.Dataset.sel`` and ``xray.Dataset.reindex`` now support + the ``tolerance`` argument for controlling nearest-neighbor selection + (:issue:`629`): + + .. ipython:: :verbatim: - - array.resample("3H", "time") - -- ``first`` and ``last`` methods on groupby objects let you take the first or - last examples from each group along the grouped axis: - - .. ipython:: python + + In [5]: array = xray.DataArray([1, 2, 3], dims="x") + + In [6]: array.reindex(x=[0.9, 1.5], method="nearest", tolerance=0.2) + Out[6]: + + array([ 2., nan]) + Coordinates: + * x (x) float64 0.9 1.5 + + This feature requires pandas v0.17 or newer. + - New ``encoding`` argument in ``xray.Dataset.to_netcdf`` for writing + netCDF files with compression, as described in the new documentation + section on :ref:`io.netcdf.writing_encoded`. + - Add ``xray.Dataset.real`` and ``xray.Dataset.imag`` + attributes to Dataset and DataArray (:issue:`553`). + - More informative error message with ``xray.Dataset.from_dataframe`` + if the frame has duplicate columns. + - xray now uses deterministic names for dask arrays it creates or opens from + disk. This allows xray users to take advantage of dask's nascent support for + caching intermediate computation results. See :issue:`555` for an example. + + Bug fixes + ~~~~~~~~~ + + - Forwards compatibility with the latest pandas release (v0.17.0). We were + using some internal pandas routines for datetime conversion, which + unfortunately have now changed upstream (:issue:`569`). + - Aggregation functions now correctly skip ``NaN`` for data for ``complex128`` + dtype (:issue:`554`). + - Fixed indexing 0d arrays with unicode dtype (:issue:`568`). + - ``xray.DataArray.name`` and Dataset keys must be a string or None to + be written to netCDF (:issue:`533`). + - ``xray.DataArray.where`` now uses dask instead of numpy if either the + array or ``other`` is a dask array. Previously, if ``other`` was a numpy array + the method was evaluated eagerly. + - Global attributes are now handled more consistently when loading remote + datasets using ``engine='pydap'`` (:issue:`574`). + - It is now possible to assign to the ``.data`` attribute of DataArray objects. + - ``coordinates`` attribute is now kept in the encoding dictionary after + decoding (:issue:`610`). + - Compatibility with numpy 1.10 (:issue:`617`). + + Acknowledgments + ~~~~~~~~~~~~~~~ + + The following individuals contributed to this release: + + - Ryan Abernathey + - Pete Cable + - Clark Fitzgerald + - Joe Hamman + - Stephan Hoyer + - Scott Sinclair + + v0.6.0 (21 August 2015) + ----------------------- + + This release includes numerous bug fixes and enhancements. Highlights + include the introduction of a plotting module and the new Dataset and DataArray + methods ``xray.Dataset.isel_points``, ``xray.Dataset.sel_points``, + ``xray.Dataset.where`` and ``xray.Dataset.diff``. There are no + breaking changes from v0.5.2. + + Enhancements + ~~~~~~~~~~~~ + + - Plotting methods have been implemented on DataArray objects + ``xray.DataArray.plot`` through integration with matplotlib + (:issue:`185`). For an introduction, see :ref:`plotting`. + - Variables in netCDF files with multiple missing values are now decoded as NaN + after issuing a warning if open_dataset is called with mask_and_scale=True. + - We clarified our rules for when the result from an xray operation is a copy + vs. a view (see :ref:`copies_vs_views` for more details). + - Dataset variables are now written to netCDF files in order of appearance + when using the netcdf4 backend (:issue:`479`). + + - Added ``xray.Dataset.isel_points`` and ``xray.Dataset.sel_points`` + to support pointwise indexing of Datasets and DataArrays (:issue:`475`). + + .. ipython:: :verbatim: - - array.groupby("time.day").first() - - These methods combine well with ``resample``: - - .. ipython:: python + + In [1]: da = xray.DataArray( + ...: np.arange(56).reshape((7, 8)), + ...: coords={"x": list("abcdefg"), "y": 10 * np.arange(8)}, + ...: dims=["x", "y"], + ...: ) + + In [2]: da + Out[2]: + + array([[ 0, 1, 2, 3, 4, 5, 6, 7], + [ 8, 9, 10, 11, 12, 13, 14, 15], + [16, 17, 18, 19, 20, 21, 22, 23], + [24, 25, 26, 27, 28, 29, 30, 31], + [32, 33, 34, 35, 36, 37, 38, 39], + [40, 41, 42, 43, 44, 45, 46, 47], + [48, 49, 50, 51, 52, 53, 54, 55]]) + Coordinates: + * y (y) int64 0 10 20 30 40 50 60 70 + * x (x) |S1 'a' 'b' 'c' 'd' 'e' 'f' 'g' + + # we can index by position along each dimension + In [3]: da.isel_points(x=[0, 1, 6], y=[0, 1, 0], dim="points") + Out[3]: + + array([ 0, 9, 48]) + Coordinates: + y (points) int64 0 10 0 + x (points) |S1 'a' 'b' 'g' + * points (points) int64 0 1 2 + + # or equivalently by label + In [9]: da.sel_points(x=["a", "b", "g"], y=[0, 10, 0], dim="points") + Out[9]: + + array([ 0, 9, 48]) + Coordinates: + y (points) int64 0 10 0 + x (points) |S1 'a' 'b' 'g' + * points (points) int64 0 1 2 + + - New ``xray.Dataset.where`` method for masking xray objects according + to some criteria. This works particularly well with multi-dimensional data: + + .. ipython:: python + + ds = xray.Dataset(coords={"x": range(100), "y": range(100)}) + ds["distance"] = np.sqrt(ds.x ** 2 + ds.y ** 2) + + @savefig where_example.png width=4in height=4in + ds.distance.where(ds.distance < 100).plot() + + - Added new methods ``xray.DataArray.diff`` and ``xray.Dataset.diff`` + for finite difference calculations along a given axis. + + - New ``xray.DataArray.to_masked_array`` convenience method for + returning a numpy.ma.MaskedArray. + + .. ipython:: python + + da = xray.DataArray(np.random.random_sample(size=(5, 4))) + da.where(da < 0.5) + da.where(da < 0.5).to_masked_array(copy=True) + + - Added new flag "drop_variables" to ``xray.open_dataset`` for + excluding variables from being parsed. This may be useful to drop + variables with problems or inconsistent values. + + Bug fixes + ~~~~~~~~~ + + - Fixed aggregation functions (e.g., sum and mean) on big-endian arrays when + bottleneck is installed (:issue:`489`). + - Dataset aggregation functions dropped variables with unsigned integer dtype + (:issue:`505`). + - ``.any()`` and ``.all()`` were not lazy when used on xray objects containing + dask arrays. + - Fixed an error when attempting to saving datetime64 variables to netCDF + files when the first element is ``NaT`` (:issue:`528`). + - Fix pickle on DataArray objects (:issue:`515`). + - Fixed unnecessary coercion of float64 to float32 when using netcdf3 and + netcdf4_classic formats (:issue:`526`). + + v0.5.2 (16 July 2015) + --------------------- + + This release contains bug fixes, several additional options for opening and + saving netCDF files, and a backwards incompatible rewrite of the advanced + options for ``xray.concat``. + + Backwards incompatible changes + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + - The optional arguments ``concat_over`` and ``mode`` in ``xray.concat`` have + been removed and replaced by ``data_vars`` and ``coords``. The new arguments are both + more easily understood and more robustly implemented, and allowed us to fix a bug + where ``concat`` accidentally loaded data into memory. If you set values for + these optional arguments manually, you will need to update your code. The default + behavior should be unchanged. + + Enhancements + ~~~~~~~~~~~~ + + - ``xray.open_mfdataset`` now supports a ``preprocess`` argument for + preprocessing datasets prior to concatenaton. This is useful if datasets + cannot be otherwise merged automatically, e.g., if the original datasets + have conflicting index coordinates (:issue:`443`). + - ``xray.open_dataset`` and ``xray.open_mfdataset`` now use a + global thread lock by default for reading from netCDF files with dask. This + avoids possible segmentation faults for reading from netCDF4 files when HDF5 + is not configured properly for concurrent access (:issue:`444`). + - Added support for serializing arrays of complex numbers with `engine='h5netcdf'`. + - The new ``xray.save_mfdataset`` function allows for saving multiple + datasets to disk simultaneously. This is useful when processing large datasets + with dask.array. For example, to save a dataset too big to fit into memory + to one file per year, we could write: + + .. ipython:: :verbatim: - - array.resample("1D", dim="time", how="first") - - -- ``xray.Dataset.swap_dims`` allows for easily swapping one dimension - out for another: - - .. ipython:: python - - ds = xray.Dataset({"x": range(3), "y": ("x", list("abc"))}) - ds - ds.swap_dims({"x": "y"}) - - This was possible in earlier versions of xray, but required some contortions. -- ``xray.open_dataset`` and ``xray.Dataset.to_netcdf`` now - accept an ``engine`` argument to explicitly select which underlying library - (netcdf4 or scipy) is used for reading/writing a netCDF file. - -.. _same as pandas: http://pandas.pydata.org/pandas-docs/stable/timeseries.html#up-and-downsampling - -Bug fixes -~~~~~~~~~ - -- Fixed a bug where data netCDF variables read from disk with - ``engine='scipy'`` could still be associated with the file on disk, even - after closing the file (:issue:`341`). This manifested itself in warnings - about mmapped arrays and segmentation faults (if the data was accessed). -- Silenced spurious warnings about all-NaN slices when using nan-aware - aggregation methods (:issue:`344`). -- Dataset aggregations with ``keep_attrs=True`` now preserve attributes on - data variables, not just the dataset itself. -- Tests for xray now pass when run on Windows (:issue:`360`). -- Fixed a regression in v0.4 where saving to netCDF could fail with the error - ``ValueError: could not automatically determine time units``. - -v0.4 (2 March, 2015) --------------------- - -This is one of the biggest releases yet for xray: it includes some major -changes that may break existing code, along with the usual collection of minor -enhancements and bug fixes. On the plus side, this release includes all -hitherto planned breaking changes, so the upgrade path for xray should be -smoother going forward. - -Breaking changes -~~~~~~~~~~~~~~~~ - -- We now automatically align index labels in arithmetic, dataset construction, - merging and updating. This means the need for manually invoking methods like - ``xray.align`` and ``xray.Dataset.reindex_like`` should be - vastly reduced. - - :ref:`For arithmetic`, we align - based on the **intersection** of labels: - - .. ipython:: python - - lhs = xray.DataArray([1, 2, 3], [("x", [0, 1, 2])]) - rhs = xray.DataArray([2, 3, 4], [("x", [1, 2, 3])]) - lhs + rhs - - :ref:`For dataset construction and merging`, we align based on the - **union** of labels: - - .. ipython:: python - - xray.Dataset({"foo": lhs, "bar": rhs}) - - :ref:`For update and __setitem__`, we align based on the **original** - object: - - .. ipython:: python - - lhs.coords["rhs"] = rhs - lhs - -- Aggregations like ``mean`` or ``median`` now skip missing values by default: - - .. ipython:: python - - xray.DataArray([1, 2, np.nan, 3]).mean() - - You can turn this behavior off by supplying the keyword arugment - ``skipna=False``. - - These operations are lightning fast thanks to integration with bottleneck_, - which is a new optional dependency for xray (numpy is used if bottleneck is - not installed). -- Scalar coordinates no longer conflict with constant arrays with the same - value (e.g., in arithmetic, merging datasets and concat), even if they have - different shape (:issue:`243`). For example, the coordinate ``c`` here - persists through arithmetic, even though it has different shapes on each - DataArray: - - .. ipython:: python - - a = xray.DataArray([1, 2], coords={"c": 0}, dims="x") - b = xray.DataArray([1, 2], coords={"c": ("x", [0, 0])}, dims="x") - (a + b).coords - - This functionality can be controlled through the ``compat`` option, which - has also been added to the ``xray.Dataset`` constructor. -- Datetime shortcuts such as ``'time.month'`` now return a ``DataArray`` with - the name ``'month'``, not ``'time.month'`` (:issue:`345`). This makes it - easier to index the resulting arrays when they are used with ``groupby``: - - .. ipython:: python - - time = xray.DataArray( - pd.date_range("2000-01-01", periods=365), dims="time", name="time" - ) - counts = time.groupby("time.month").count() - counts.sel(month=2) - - Previously, you would need to use something like - ``counts.sel(**{'time.month': 2}})``, which is much more awkward. -- The ``season`` datetime shortcut now returns an array of string labels - such `'DJF'`: - - .. ipython:: python - - ds = xray.Dataset({"t": pd.date_range("2000-01-01", periods=12, freq="M")}) - ds["t.season"] - - Previously, it returned numbered seasons 1 through 4. -- We have updated our use of the terms of "coordinates" and "variables". What - were known in previous versions of xray as "coordinates" and "variables" are - now referred to throughout the documentation as "coordinate variables" and - "data variables". This brings xray in closer alignment to `CF Conventions`_. - The only visible change besides the documentation is that ``Dataset.vars`` - has been renamed ``Dataset.data_vars``. -- You will need to update your code if you have been ignoring deprecation - warnings: methods and attributes that were deprecated in xray v0.3 or earlier - (e.g., ``dimensions``, ``attributes```) have gone away. - -.. _bottleneck: https://github.com/pydata/bottleneck - -Enhancements -~~~~~~~~~~~~ - -- Support for ``xray.Dataset.reindex`` with a fill method. This - provides a useful shortcut for upsampling: - - .. ipython:: python - - data = xray.DataArray([1, 2, 3], [("x", range(3))]) - data.reindex(x=[0.5, 1, 1.5, 2, 2.5], method="pad") - - This will be especially useful once pandas 0.16 is released, at which point - xray will immediately support reindexing with - `method='nearest' `_. -- Use functions that return generic ndarrays with DataArray.groupby.apply and - Dataset.apply (:issue:`327` and :issue:`329`). Thanks Jeff Gerard! -- Consolidated the functionality of ``dumps`` (writing a dataset to a netCDF3 - bytestring) into ``xray.Dataset.to_netcdf`` (:issue:`333`). -- ``xray.Dataset.to_netcdf`` now supports writing to groups in netCDF4 - files (:issue:`333`). It also finally has a full docstring -- you should read - it! -- ``xray.open_dataset`` and ``xray.Dataset.to_netcdf`` now - work on netCDF3 files when netcdf4-python is not installed as long as scipy - is available (:issue:`333`). -- The new ``xray.Dataset.drop`` and ``xray.DataArray.drop`` methods - makes it easy to drop explicitly listed variables or index labels: - - .. ipython:: python - :okwarning: - - # drop variables - ds = xray.Dataset({"x": 0, "y": 1}) - ds.drop("x") - - # drop index labels - arr = xray.DataArray([1, 2, 3], coords=[("x", list("abc"))]) - arr.drop(["a", "c"], dim="x") - -- ``xray.Dataset.broadcast_equals`` has been added to correspond to - the new ``compat`` option. -- Long attributes are now truncated at 500 characters when printing a dataset - (:issue:`338`). This should make things more convenient for working with - datasets interactively. -- Added a new documentation example, :ref:`/examples/monthly-means.ipynb`. Thanks Joe - Hamman! - -Bug fixes -~~~~~~~~~ - -- Several bug fixes related to decoding time units from netCDF files - (:issue:`316`, :issue:`330`). Thanks Stefan Pfenninger! -- xray no longer requires ``decode_coords=False`` when reading datasets with - unparseable coordinate attributes (:issue:`308`). -- Fixed ``DataArray.loc`` indexing with ``...`` (:issue:`318`). -- Fixed an edge case that resulting in an error when reindexing - multi-dimensional variables (:issue:`315`). -- Slicing with negative step sizes (:issue:`312`). -- Invalid conversion of string arrays to numeric dtype (:issue:`305`). -- Fixed``repr()`` on dataset objects with non-standard dates (:issue:`347`). - -Deprecations -~~~~~~~~~~~~ - -- ``dump`` and ``dumps`` have been deprecated in favor of - ``xray.Dataset.to_netcdf``. -- ``drop_vars`` has been deprecated in favor of ``xray.Dataset.drop``. - -Future plans -~~~~~~~~~~~~ - -The biggest feature I'm excited about working toward in the immediate future -is supporting out-of-core operations in xray using Dask_, a part of the Blaze_ -project. For a preview of using Dask with weather data, read -`this blog post`_ by Matthew Rocklin. See :issue:`328` for more details. - -.. _Dask: http://dask.pydata.org -.. _Blaze: http://blaze.pydata.org -.. _this blog post: http://matthewrocklin.com/blog/work/2015/02/13/Towards-OOC-Slicing-and-Stacking/ - -v0.3.2 (23 December, 2014) --------------------------- - -This release focused on bug-fixes, speedups and resolving some niggling -inconsistencies. - -There are a few cases where the behavior of xray differs from the previous -version. However, I expect that in almost all cases your code will continue to -run unmodified. - -.. warning:: - - xray now requires pandas v0.15.0 or later. This was necessary for - supporting TimedeltaIndex without too many painful hacks. - -Backwards incompatible changes -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- Arrays of :py:class:`datetime.datetime` objects are now automatically cast to - ``datetime64[ns]`` arrays when stored in an xray object, using machinery - borrowed from pandas: - - .. ipython:: python - - from datetime import datetime - - xray.Dataset({"t": [datetime(2000, 1, 1)]}) - -- xray now has support (including serialization to netCDF) for - :py:class:`~pandas.TimedeltaIndex`. :py:class:`datetime.timedelta` objects - are thus accordingly cast to ``timedelta64[ns]`` objects when appropriate. -- Masked arrays are now properly coerced to use ``NaN`` as a sentinel value - (:issue:`259`). - -Enhancements -~~~~~~~~~~~~ - -- Due to popular demand, we have added experimental attribute style access as - a shortcut for dataset variables, coordinates and attributes: - - .. ipython:: python - - ds = xray.Dataset({"tmin": ([], 25, {"units": "celsius"})}) - ds.tmin.units - - Tab-completion for these variables should work in editors such as IPython. - However, setting variables or attributes in this fashion is not yet - supported because there are some unresolved ambiguities (:issue:`300`). -- You can now use a dictionary for indexing with labeled dimensions. This - provides a safe way to do assignment with labeled dimensions: - - .. ipython:: python - - array = xray.DataArray(np.zeros(5), dims=["x"]) - array[dict(x=slice(3))] = 1 - array - -- Non-index coordinates can now be faithfully written to and restored from - netCDF files. This is done according to CF conventions when possible by - using the ``coordinates`` attribute on a data variable. When not possible, - xray defines a global ``coordinates`` attribute. -- Preliminary support for converting ``xray.DataArray`` objects to and from - CDAT_ ``cdms2`` variables. -- We sped up any operation that involves creating a new Dataset or DataArray - (e.g., indexing, aggregation, arithmetic) by a factor of 30 to 50%. The full - speed up requires cyordereddict_ to be installed. - -.. _CDAT: http://uvcdat.llnl.gov/ -.. _cyordereddict: https://github.com/shoyer/cyordereddict - -Bug fixes -~~~~~~~~~ - -- Fix for ``to_dataframe()`` with 0d string/object coordinates (:issue:`287`) -- Fix for ``to_netcdf`` with 0d string variable (:issue:`284`) -- Fix writing datetime64 arrays to netcdf if NaT is present (:issue:`270`) -- Fix align silently upcasts data arrays when NaNs are inserted (:issue:`264`) - -Future plans -~~~~~~~~~~~~ - -- I am contemplating switching to the terms "coordinate variables" and "data - variables" instead of the (currently used) "coordinates" and "variables", - following their use in `CF Conventions`_ (:issue:`293`). This would mostly - have implications for the documentation, but I would also change the - ``Dataset`` attribute ``vars`` to ``data``. -- I no longer certain that automatic label alignment for arithmetic would be a - good idea for xray -- it is a feature from pandas that I have not missed - (:issue:`186`). -- The main API breakage that I *do* anticipate in the next release is finally - making all aggregation operations skip missing values by default - (:issue:`130`). I'm pretty sick of writing ``ds.reduce(np.nanmean, 'time')``. -- The next version of xray (0.4) will remove deprecated features and aliases - whose use currently raises a warning. - -If you have opinions about any of these anticipated changes, I would love to -hear them -- please add a note to any of the referenced GitHub issues. - -.. _CF Conventions: http://cfconventions.org/Data/cf-conventions/cf-conventions-1.6/build/cf-conventions.html - -v0.3.1 (22 October, 2014) -------------------------- - -This is mostly a bug-fix release to make xray compatible with the latest -release of pandas (v0.15). - -We added several features to better support working with missing values and -exporting xray objects to pandas. We also reorganized the internal API for -serializing and deserializing datasets, but this change should be almost -entirely transparent to users. - -Other than breaking the experimental DataStore API, there should be no -backwards incompatible changes. - -New features -~~~~~~~~~~~~ - -- Added ``xray.Dataset.count`` and ``xray.Dataset.dropna`` - methods, copied from pandas, for working with missing values (:issue:`247`, - :issue:`58`). -- Added ``xray.DataArray.to_pandas`` for - converting a data array into the pandas object with the same dimensionality - (1D to Series, 2D to DataFrame, etc.) (:issue:`255`). -- Support for reading gzipped netCDF3 files (:issue:`239`). -- Reduced memory usage when writing netCDF files (:issue:`251`). -- 'missing_value' is now supported as an alias for the '_FillValue' attribute - on netCDF variables (:issue:`245`). -- Trivial indexes, equivalent to ``range(n)`` where ``n`` is the length of the - dimension, are no longer written to disk (:issue:`245`). - -Bug fixes -~~~~~~~~~ - -- Compatibility fixes for pandas v0.15 (:issue:`262`). -- Fixes for display and indexing of ``NaT`` (not-a-time) (:issue:`238`, - :issue:`240`) -- Fix slicing by label was an argument is a data array (:issue:`250`). -- Test data is now shipped with the source distribution (:issue:`253`). -- Ensure order does not matter when doing arithmetic with scalar data arrays - (:issue:`254`). -- Order of dimensions preserved with ``DataArray.to_dataframe`` (:issue:`260`). - -v0.3 (21 September 2014) ------------------------- - -New features -~~~~~~~~~~~~ - -- **Revamped coordinates**: "coordinates" now refer to all arrays that are not - used to index a dimension. Coordinates are intended to allow for keeping track - of arrays of metadata that describe the grid on which the points in "variable" - arrays lie. They are preserved (when unambiguous) even though mathematical - operations. -- **Dataset math** ``xray.Dataset`` objects now support all arithmetic - operations directly. Dataset-array operations map across all dataset - variables; dataset-dataset operations act on each pair of variables with the - same name. -- **GroupBy math**: This provides a convenient shortcut for normalizing by the - average value of a group. -- The dataset ``__repr__`` method has been entirely overhauled; dataset - objects now show their values when printed. -- You can now index a dataset with a list of variables to return a new dataset: - ``ds[['foo', 'bar']]``. - -Backwards incompatible changes -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- ``Dataset.__eq__`` and ``Dataset.__ne__`` are now element-wise operations - instead of comparing all values to obtain a single boolean. Use the method - ``xray.Dataset.equals`` instead. - -Deprecations -~~~~~~~~~~~~ - -- ``Dataset.noncoords`` is deprecated: use ``Dataset.vars`` instead. -- ``Dataset.select_vars`` deprecated: index a ``Dataset`` with a list of - variable names instead. -- ``DataArray.select_vars`` and ``DataArray.drop_vars`` deprecated: use - ``xray.DataArray.reset_coords`` instead. - -v0.2 (14 August 2014) ---------------------- - -This is major release that includes some new features and quite a few bug -fixes. Here are the highlights: - -- There is now a direct constructor for ``DataArray`` objects, which makes it - possible to create a DataArray without using a Dataset. This is highlighted - in the refreshed ``tutorial``. -- You can perform aggregation operations like ``mean`` directly on - ``xray.Dataset`` objects, thanks to Joe Hamman. These aggregation - methods also worked on grouped datasets. -- xray now works on Python 2.6, thanks to Anna Kuznetsova. -- A number of methods and attributes were given more sensible (usually shorter) - names: ``labeled`` -> ``sel``, ``indexed`` -> ``isel``, ``select`` -> - ``select_vars``, ``unselect`` -> ``drop_vars``, ``dimensions`` -> ``dims``, - ``coordinates`` -> ``coords``, ``attributes`` -> ``attrs``. -- New ``xray.Dataset.load_data`` and ``xray.Dataset.close`` - methods for datasets facilitate lower level of control of data loaded from - disk. - -v0.1.1 (20 May 2014) --------------------- - -xray 0.1.1 is a bug-fix release that includes changes that should be almost -entirely backwards compatible with v0.1: - -- Python 3 support (:issue:`53`) -- Required numpy version relaxed to 1.7 (:issue:`129`) -- Return numpy.datetime64 arrays for non-standard calendars (:issue:`126`) -- Support for opening datasets associated with NetCDF4 groups (:issue:`127`) -- Bug-fixes for concatenating datetime arrays (:issue:`134`) - -Special thanks to new contributors Thomas Kluyver, Joe Hamman and Alistair -Miles. - -v0.1 (2 May 2014) ------------------ - -Initial release. + + In [1]: years, datasets = zip(*ds.groupby("time.year")) + + In [2]: paths = ["%s.nc" % y for y in years] + + In [3]: xray.save_mfdataset(datasets, paths) + + Bug fixes + ~~~~~~~~~ + + - Fixed ``min``, ``max``, ``argmin`` and ``argmax`` for arrays with string or + unicode types (:issue:`453`). + - ``xray.open_dataset`` and ``xray.open_mfdataset`` support + supplying chunks as a single integer. + - Fixed a bug in serializing scalar datetime variable to netCDF. + - Fixed a bug that could occur in serialization of 0-dimensional integer arrays. + - Fixed a bug where concatenating DataArrays was not always lazy (:issue:`464`). + - When reading datasets with h5netcdf, bytes attributes are decoded to strings. + This allows conventions decoding to work properly on Python 3 (:issue:`451`). + + v0.5.1 (15 June 2015) + --------------------- + + This minor release fixes a few bugs and an inconsistency with pandas. It also + adds the ``pipe`` method, copied from pandas. + + Enhancements + ~~~~~~~~~~~~ + + - Added ``xray.Dataset.pipe``, replicating the `new pandas method`_ in version + 0.16.2. See :ref:`transforming datasets` for more details. + - ``xray.Dataset.assign`` and ``xray.Dataset.assign_coords`` + now assign new variables in sorted (alphabetical) order, mirroring the + behavior in pandas. Previously, the order was arbitrary. + + .. _new pandas method: http://pandas.pydata.org/pandas-docs/version/0.16.2/whatsnew.html#pipe + + Bug fixes + ~~~~~~~~~ + + - ``xray.concat`` fails in an edge case involving identical coordinate variables (:issue:`425`) + - We now decode variables loaded from netCDF3 files with the scipy engine using native + endianness (:issue:`416`). This resolves an issue when aggregating these arrays with + bottleneck installed. + + v0.5 (1 June 2015) + ------------------ + + Highlights + ~~~~~~~~~~ + + The headline feature in this release is experimental support for out-of-core + computing (data that doesn't fit into memory) with :doc:`user-guide/dask`. This includes a new + top-level function ``xray.open_mfdataset`` that makes it easy to open + a collection of netCDF (using dask) as a single ``xray.Dataset`` object. For + more on dask, read the `blog post introducing xray + dask`_ and the new + documentation section :doc:`user-guide/dask`. + + .. _blog post introducing xray + dask: https://www.anaconda.com/blog/developer-blog/xray-dask-out-core-labeled-arrays-python/ + + Dask makes it possible to harness parallelism and manipulate gigantic datasets + with xray. It is currently an optional dependency, but it may become required + in the future. + + Backwards incompatible changes + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + - The logic used for choosing which variables are concatenated with + ``xray.concat`` has changed. Previously, by default any variables + which were equal across a dimension were not concatenated. This lead to some + surprising behavior, where the behavior of groupby and concat operations + could depend on runtime values (:issue:`268`). For example: + + .. ipython:: + :verbatim: + + In [1]: ds = xray.Dataset({"x": 0}) + + In [2]: xray.concat([ds, ds], dim="y") + Out[2]: + + Dimensions: () + Coordinates: + *empty* + Data variables: + x int64 0 + + Now, the default always concatenates data variables: + + .. ipython:: python + :suppress: + + ds = xray.Dataset({"x": 0}) + + .. ipython:: python + + xray.concat([ds, ds], dim="y") + + To obtain the old behavior, supply the argument ``concat_over=[]``. + + Enhancements + ~~~~~~~~~~~~ + + - New ``xray.Dataset.to_array`` and enhanced + ``xray.DataArray.to_dataset`` methods make it easy to switch back + and forth between arrays and datasets: + + .. ipython:: python + + ds = xray.Dataset( + {"a": 1, "b": ("x", [1, 2, 3])}, + coords={"c": 42}, + attrs={"Conventions": "None"}, + ) + ds.to_array() + ds.to_array().to_dataset(dim="variable") + + - New ``xray.Dataset.fillna`` method to fill missing values, modeled + off the pandas method of the same name: + + .. ipython:: python + + array = xray.DataArray([np.nan, 1, np.nan, 3], dims="x") + array.fillna(0) + + ``fillna`` works on both ``Dataset`` and ``DataArray`` objects, and uses + index based alignment and broadcasting like standard binary operations. It + also can be applied by group, as illustrated in + :ref:`/examples/weather-data.ipynb#Fill-missing-values-with-climatology`. + - New ``xray.Dataset.assign`` and ``xray.Dataset.assign_coords`` + methods patterned off the new :py:meth:`DataFrame.assign ` + method in pandas: + + .. ipython:: python + + ds = xray.Dataset({"y": ("x", [1, 2, 3])}) + ds.assign(z=lambda ds: ds.y ** 2) + ds.assign_coords(z=("x", ["a", "b", "c"])) + + These methods return a new Dataset (or DataArray) with updated data or + coordinate variables. + - ``xray.Dataset.sel`` now supports the ``method`` parameter, which works + like the paramter of the same name on ``xray.Dataset.reindex``. It + provides a simple interface for doing nearest-neighbor interpolation: + + .. use verbatim because I can't seem to install pandas 0.16.1 on RTD :( + + .. ipython:: + :verbatim: + + In [12]: ds.sel(x=1.1, method="nearest") + Out[12]: + + Dimensions: () + Coordinates: + x int64 1 + Data variables: + y int64 2 + + In [13]: ds.sel(x=[1.1, 2.1], method="pad") + Out[13]: + + Dimensions: (x: 2) + Coordinates: + * x (x) int64 1 2 + Data variables: + y (x) int64 2 3 + + See :ref:`nearest neighbor lookups` for more details. + - You can now control the underlying backend used for accessing remote + datasets (via OPeNDAP) by specifying ``engine='netcdf4'`` or + ``engine='pydap'``. + - xray now provides experimental support for reading and writing netCDF4 files directly + via `h5py`_ with the `h5netcdf`_ package, avoiding the netCDF4-Python package. You + will need to install h5netcdf and specify ``engine='h5netcdf'`` to try this + feature. + - Accessing data from remote datasets now has retrying logic (with exponential + backoff) that should make it robust to occasional bad responses from DAP + servers. + - You can control the width of the Dataset repr with ``xray.set_options``. + It can be used either as a context manager, in which case the default is restored + outside the context: + + .. ipython:: python + + ds = xray.Dataset({"x": np.arange(1000)}) + with xray.set_options(display_width=40): + print(ds) + + Or to set a global option: + + .. ipython:: + :verbatim: + + In [1]: xray.set_options(display_width=80) + + The default value for the ``display_width`` option is 80. + + .. _h5py: http://www.h5py.org/ + .. _h5netcdf: https://github.com/shoyer/h5netcdf + + Deprecations + ~~~~~~~~~~~~ + + - The method ``load_data()`` has been renamed to the more succinct + ``xray.Dataset.load``. + + v0.4.1 (18 March 2015) + ---------------------- + + The release contains bug fixes and several new features. All changes should be + fully backwards compatible. + + Enhancements + ~~~~~~~~~~~~ + + - New documentation sections on :ref:`time-series` and + :ref:`combining multiple files`. + - ``xray.Dataset.resample`` lets you resample a dataset or data array to + a new temporal resolution. The syntax is the `same as pandas`_, except you + need to supply the time dimension explicitly: + + .. ipython:: python + :verbatim: + + time = pd.date_range("2000-01-01", freq="6H", periods=10) + array = xray.DataArray(np.arange(10), [("time", time)]) + array.resample("1D", dim="time") + + You can specify how to do the resampling with the ``how`` argument and other + options such as ``closed`` and ``label`` let you control labeling: + + .. ipython:: python + :verbatim: + + array.resample("1D", dim="time", how="sum", label="right") + + If the desired temporal resolution is higher than the original data + (upsampling), xray will insert missing values: + + .. ipython:: python + :verbatim: + + array.resample("3H", "time") + + - ``first`` and ``last`` methods on groupby objects let you take the first or + last examples from each group along the grouped axis: + + .. ipython:: python + :verbatim: + + array.groupby("time.day").first() + + These methods combine well with ``resample``: + + .. ipython:: python + :verbatim: + + array.resample("1D", dim="time", how="first") + + + - ``xray.Dataset.swap_dims`` allows for easily swapping one dimension + out for another: + + .. ipython:: python + + ds = xray.Dataset({"x": range(3), "y": ("x", list("abc"))}) + ds + ds.swap_dims({"x": "y"}) + + This was possible in earlier versions of xray, but required some contortions. + - ``xray.open_dataset`` and ``xray.Dataset.to_netcdf`` now + accept an ``engine`` argument to explicitly select which underlying library + (netcdf4 or scipy) is used for reading/writing a netCDF file. + + .. _same as pandas: http://pandas.pydata.org/pandas-docs/stable/timeseries.html#up-and-downsampling + + Bug fixes + ~~~~~~~~~ + + - Fixed a bug where data netCDF variables read from disk with + ``engine='scipy'`` could still be associated with the file on disk, even + after closing the file (:issue:`341`). This manifested itself in warnings + about mmapped arrays and segmentation faults (if the data was accessed). + - Silenced spurious warnings about all-NaN slices when using nan-aware + aggregation methods (:issue:`344`). + - Dataset aggregations with ``keep_attrs=True`` now preserve attributes on + data variables, not just the dataset itself. + - Tests for xray now pass when run on Windows (:issue:`360`). + - Fixed a regression in v0.4 where saving to netCDF could fail with the error + ``ValueError: could not automatically determine time units``. + + v0.4 (2 March, 2015) + -------------------- + + This is one of the biggest releases yet for xray: it includes some major + changes that may break existing code, along with the usual collection of minor + enhancements and bug fixes. On the plus side, this release includes all + hitherto planned breaking changes, so the upgrade path for xray should be + smoother going forward. + + Breaking changes + ~~~~~~~~~~~~~~~~ + + - We now automatically align index labels in arithmetic, dataset construction, + merging and updating. This means the need for manually invoking methods like + ``xray.align`` and ``xray.Dataset.reindex_like`` should be + vastly reduced. + + :ref:`For arithmetic`, we align + based on the **intersection** of labels: + + .. ipython:: python + + lhs = xray.DataArray([1, 2, 3], [("x", [0, 1, 2])]) + rhs = xray.DataArray([2, 3, 4], [("x", [1, 2, 3])]) + lhs + rhs + + :ref:`For dataset construction and merging`, we align based on the + **union** of labels: + + .. ipython:: python + + xray.Dataset({"foo": lhs, "bar": rhs}) + + :ref:`For update and __setitem__`, we align based on the **original** + object: + + .. ipython:: python + + lhs.coords["rhs"] = rhs + lhs + + - Aggregations like ``mean`` or ``median`` now skip missing values by default: + + .. ipython:: python + + xray.DataArray([1, 2, np.nan, 3]).mean() + + You can turn this behavior off by supplying the keyword arugment + ``skipna=False``. + + These operations are lightning fast thanks to integration with bottleneck_, + which is a new optional dependency for xray (numpy is used if bottleneck is + not installed). + - Scalar coordinates no longer conflict with constant arrays with the same + value (e.g., in arithmetic, merging datasets and concat), even if they have + different shape (:issue:`243`). For example, the coordinate ``c`` here + persists through arithmetic, even though it has different shapes on each + DataArray: + + .. ipython:: python + + a = xray.DataArray([1, 2], coords={"c": 0}, dims="x") + b = xray.DataArray([1, 2], coords={"c": ("x", [0, 0])}, dims="x") + (a + b).coords + + This functionality can be controlled through the ``compat`` option, which + has also been added to the ``xray.Dataset`` constructor. + - Datetime shortcuts such as ``'time.month'`` now return a ``DataArray`` with + the name ``'month'``, not ``'time.month'`` (:issue:`345`). This makes it + easier to index the resulting arrays when they are used with ``groupby``: + + .. ipython:: python + + time = xray.DataArray( + pd.date_range("2000-01-01", periods=365), dims="time", name="time" + ) + counts = time.groupby("time.month").count() + counts.sel(month=2) + + Previously, you would need to use something like + ``counts.sel(**{'time.month': 2}})``, which is much more awkward. + - The ``season`` datetime shortcut now returns an array of string labels + such `'DJF'`: + + .. ipython:: python + + ds = xray.Dataset({"t": pd.date_range("2000-01-01", periods=12, freq="M")}) + ds["t.season"] + + Previously, it returned numbered seasons 1 through 4. + - We have updated our use of the terms of "coordinates" and "variables". What + were known in previous versions of xray as "coordinates" and "variables" are + now referred to throughout the documentation as "coordinate variables" and + "data variables". This brings xray in closer alignment to `CF Conventions`_. + The only visible change besides the documentation is that ``Dataset.vars`` + has been renamed ``Dataset.data_vars``. + - You will need to update your code if you have been ignoring deprecation + warnings: methods and attributes that were deprecated in xray v0.3 or earlier + (e.g., ``dimensions``, ``attributes```) have gone away. + + .. _bottleneck: https://github.com/pydata/bottleneck + + Enhancements + ~~~~~~~~~~~~ + + - Support for ``xray.Dataset.reindex`` with a fill method. This + provides a useful shortcut for upsampling: + + .. ipython:: python + + data = xray.DataArray([1, 2, 3], [("x", range(3))]) + data.reindex(x=[0.5, 1, 1.5, 2, 2.5], method="pad") + + This will be especially useful once pandas 0.16 is released, at which point + xray will immediately support reindexing with + `method='nearest' `_. + - Use functions that return generic ndarrays with DataArray.groupby.apply and + Dataset.apply (:issue:`327` and :issue:`329`). Thanks Jeff Gerard! + - Consolidated the functionality of ``dumps`` (writing a dataset to a netCDF3 + bytestring) into ``xray.Dataset.to_netcdf`` (:issue:`333`). + - ``xray.Dataset.to_netcdf`` now supports writing to groups in netCDF4 + files (:issue:`333`). It also finally has a full docstring -- you should read + it! + - ``xray.open_dataset`` and ``xray.Dataset.to_netcdf`` now + work on netCDF3 files when netcdf4-python is not installed as long as scipy + is available (:issue:`333`). + - The new ``xray.Dataset.drop`` and ``xray.DataArray.drop`` methods + makes it easy to drop explicitly listed variables or index labels: + + .. ipython:: python + :okwarning: + + # drop variables + ds = xray.Dataset({"x": 0, "y": 1}) + ds.drop("x") + + # drop index labels + arr = xray.DataArray([1, 2, 3], coords=[("x", list("abc"))]) + arr.drop(["a", "c"], dim="x") + + - ``xray.Dataset.broadcast_equals`` has been added to correspond to + the new ``compat`` option. + - Long attributes are now truncated at 500 characters when printing a dataset + (:issue:`338`). This should make things more convenient for working with + datasets interactively. + - Added a new documentation example, :ref:`/examples/monthly-means.ipynb`. Thanks Joe + Hamman! + + Bug fixes + ~~~~~~~~~ + + - Several bug fixes related to decoding time units from netCDF files + (:issue:`316`, :issue:`330`). Thanks Stefan Pfenninger! + - xray no longer requires ``decode_coords=False`` when reading datasets with + unparseable coordinate attributes (:issue:`308`). + - Fixed ``DataArray.loc`` indexing with ``...`` (:issue:`318`). + - Fixed an edge case that resulting in an error when reindexing + multi-dimensional variables (:issue:`315`). + - Slicing with negative step sizes (:issue:`312`). + - Invalid conversion of string arrays to numeric dtype (:issue:`305`). + - Fixed``repr()`` on dataset objects with non-standard dates (:issue:`347`). + + Deprecations + ~~~~~~~~~~~~ + + - ``dump`` and ``dumps`` have been deprecated in favor of + ``xray.Dataset.to_netcdf``. + - ``drop_vars`` has been deprecated in favor of ``xray.Dataset.drop``. + + Future plans + ~~~~~~~~~~~~ + + The biggest feature I'm excited about working toward in the immediate future + is supporting out-of-core operations in xray using Dask_, a part of the Blaze_ + project. For a preview of using Dask with weather data, read + `this blog post`_ by Matthew Rocklin. See :issue:`328` for more details. + + .. _Dask: http://dask.pydata.org + .. _Blaze: http://blaze.pydata.org + .. _this blog post: http://matthewrocklin.com/blog/work/2015/02/13/Towards-OOC-Slicing-and-Stacking/ + + v0.3.2 (23 December, 2014) + -------------------------- + + This release focused on bug-fixes, speedups and resolving some niggling + inconsistencies. + + There are a few cases where the behavior of xray differs from the previous + version. However, I expect that in almost all cases your code will continue to + run unmodified. + + .. warning:: + + xray now requires pandas v0.15.0 or later. This was necessary for + supporting TimedeltaIndex without too many painful hacks. + + Backwards incompatible changes + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + - Arrays of :py:class:`datetime.datetime` objects are now automatically cast to + ``datetime64[ns]`` arrays when stored in an xray object, using machinery + borrowed from pandas: + + .. ipython:: python + + from datetime import datetime + + xray.Dataset({"t": [datetime(2000, 1, 1)]}) + + - xray now has support (including serialization to netCDF) for + :py:class:`~pandas.TimedeltaIndex`. :py:class:`datetime.timedelta` objects + are thus accordingly cast to ``timedelta64[ns]`` objects when appropriate. + - Masked arrays are now properly coerced to use ``NaN`` as a sentinel value + (:issue:`259`). + + Enhancements + ~~~~~~~~~~~~ + + - Due to popular demand, we have added experimental attribute style access as + a shortcut for dataset variables, coordinates and attributes: + + .. ipython:: python + + ds = xray.Dataset({"tmin": ([], 25, {"units": "celsius"})}) + ds.tmin.units + + Tab-completion for these variables should work in editors such as IPython. + However, setting variables or attributes in this fashion is not yet + supported because there are some unresolved ambiguities (:issue:`300`). + - You can now use a dictionary for indexing with labeled dimensions. This + provides a safe way to do assignment with labeled dimensions: + + .. ipython:: python + + array = xray.DataArray(np.zeros(5), dims=["x"]) + array[dict(x=slice(3))] = 1 + array + + - Non-index coordinates can now be faithfully written to and restored from + netCDF files. This is done according to CF conventions when possible by + using the ``coordinates`` attribute on a data variable. When not possible, + xray defines a global ``coordinates`` attribute. + - Preliminary support for converting ``xray.DataArray`` objects to and from + CDAT_ ``cdms2`` variables. + - We sped up any operation that involves creating a new Dataset or DataArray + (e.g., indexing, aggregation, arithmetic) by a factor of 30 to 50%. The full + speed up requires cyordereddict_ to be installed. + + .. _CDAT: http://uvcdat.llnl.gov/ + .. _cyordereddict: https://github.com/shoyer/cyordereddict + + Bug fixes + ~~~~~~~~~ + + - Fix for ``to_dataframe()`` with 0d string/object coordinates (:issue:`287`) + - Fix for ``to_netcdf`` with 0d string variable (:issue:`284`) + - Fix writing datetime64 arrays to netcdf if NaT is present (:issue:`270`) + - Fix align silently upcasts data arrays when NaNs are inserted (:issue:`264`) + + Future plans + ~~~~~~~~~~~~ + + - I am contemplating switching to the terms "coordinate variables" and "data + variables" instead of the (currently used) "coordinates" and "variables", + following their use in `CF Conventions`_ (:issue:`293`). This would mostly + have implications for the documentation, but I would also change the + ``Dataset`` attribute ``vars`` to ``data``. + - I no longer certain that automatic label alignment for arithmetic would be a + good idea for xray -- it is a feature from pandas that I have not missed + (:issue:`186`). + - The main API breakage that I *do* anticipate in the next release is finally + making all aggregation operations skip missing values by default + (:issue:`130`). I'm pretty sick of writing ``ds.reduce(np.nanmean, 'time')``. + - The next version of xray (0.4) will remove deprecated features and aliases + whose use currently raises a warning. + + If you have opinions about any of these anticipated changes, I would love to + hear them -- please add a note to any of the referenced GitHub issues. + + .. _CF Conventions: http://cfconventions.org/Data/cf-conventions/cf-conventions-1.6/build/cf-conventions.html + + v0.3.1 (22 October, 2014) + ------------------------- + + This is mostly a bug-fix release to make xray compatible with the latest + release of pandas (v0.15). + + We added several features to better support working with missing values and + exporting xray objects to pandas. We also reorganized the internal API for + serializing and deserializing datasets, but this change should be almost + entirely transparent to users. + + Other than breaking the experimental DataStore API, there should be no + backwards incompatible changes. + + New features + ~~~~~~~~~~~~ + + - Added ``xray.Dataset.count`` and ``xray.Dataset.dropna`` + methods, copied from pandas, for working with missing values (:issue:`247`, + :issue:`58`). + - Added ``xray.DataArray.to_pandas`` for + converting a data array into the pandas object with the same dimensionality + (1D to Series, 2D to DataFrame, etc.) (:issue:`255`). + - Support for reading gzipped netCDF3 files (:issue:`239`). + - Reduced memory usage when writing netCDF files (:issue:`251`). + - 'missing_value' is now supported as an alias for the '_FillValue' attribute + on netCDF variables (:issue:`245`). + - Trivial indexes, equivalent to ``range(n)`` where ``n`` is the length of the + dimension, are no longer written to disk (:issue:`245`). + + Bug fixes + ~~~~~~~~~ + + - Compatibility fixes for pandas v0.15 (:issue:`262`). + - Fixes for display and indexing of ``NaT`` (not-a-time) (:issue:`238`, + :issue:`240`) + - Fix slicing by label was an argument is a data array (:issue:`250`). + - Test data is now shipped with the source distribution (:issue:`253`). + - Ensure order does not matter when doing arithmetic with scalar data arrays + (:issue:`254`). + - Order of dimensions preserved with ``DataArray.to_dataframe`` (:issue:`260`). + + v0.3 (21 September 2014) + ------------------------ + + New features + ~~~~~~~~~~~~ + + - **Revamped coordinates**: "coordinates" now refer to all arrays that are not + used to index a dimension. Coordinates are intended to allow for keeping track + of arrays of metadata that describe the grid on which the points in "variable" + arrays lie. They are preserved (when unambiguous) even though mathematical + operations. + - **Dataset math** ``xray.Dataset`` objects now support all arithmetic + operations directly. Dataset-array operations map across all dataset + variables; dataset-dataset operations act on each pair of variables with the + same name. + - **GroupBy math**: This provides a convenient shortcut for normalizing by the + average value of a group. + - The dataset ``__repr__`` method has been entirely overhauled; dataset + objects now show their values when printed. + - You can now index a dataset with a list of variables to return a new dataset: + ``ds[['foo', 'bar']]``. + + Backwards incompatible changes + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + - ``Dataset.__eq__`` and ``Dataset.__ne__`` are now element-wise operations + instead of comparing all values to obtain a single boolean. Use the method + ``xray.Dataset.equals`` instead. + + Deprecations + ~~~~~~~~~~~~ + + - ``Dataset.noncoords`` is deprecated: use ``Dataset.vars`` instead. + - ``Dataset.select_vars`` deprecated: index a ``Dataset`` with a list of + variable names instead. + - ``DataArray.select_vars`` and ``DataArray.drop_vars`` deprecated: use + ``xray.DataArray.reset_coords`` instead. + + v0.2 (14 August 2014) + --------------------- + + This is major release that includes some new features and quite a few bug + fixes. Here are the highlights: + + - There is now a direct constructor for ``DataArray`` objects, which makes it + possible to create a DataArray without using a Dataset. This is highlighted + in the refreshed ``tutorial``. + - You can perform aggregation operations like ``mean`` directly on + ``xray.Dataset`` objects, thanks to Joe Hamman. These aggregation + methods also worked on grouped datasets. + - xray now works on Python 2.6, thanks to Anna Kuznetsova. + - A number of methods and attributes were given more sensible (usually shorter) + names: ``labeled`` -> ``sel``, ``indexed`` -> ``isel``, ``select`` -> + ``select_vars``, ``unselect`` -> ``drop_vars``, ``dimensions`` -> ``dims``, + ``coordinates`` -> ``coords``, ``attributes`` -> ``attrs``. + - New ``xray.Dataset.load_data`` and ``xray.Dataset.close`` + methods for datasets facilitate lower level of control of data loaded from + disk. + + v0.1.1 (20 May 2014) + -------------------- + + xray 0.1.1 is a bug-fix release that includes changes that should be almost + entirely backwards compatible with v0.1: + + - Python 3 support (:issue:`53`) + - Required numpy version relaxed to 1.7 (:issue:`129`) + - Return numpy.datetime64 arrays for non-standard calendars (:issue:`126`) + - Support for opening datasets associated with NetCDF4 groups (:issue:`127`) + - Bug-fixes for concatenating datetime arrays (:issue:`134`) + + Special thanks to new contributors Thomas Kluyver, Joe Hamman and Alistair + Miles. + + v0.1 (2 May 2014) + ----------------- + + Initial release. \ No newline at end of file From a1519c5b0fe56bdfbb919ad6217e1ad9ef0818a1 Mon Sep 17 00:00:00 2001 From: Ray Bell Date: Wed, 28 Jul 2021 13:41:09 -0400 Subject: [PATCH 05/11] undo whats new --- doc/whats-new.rst | 11078 ++++++++++++++++++++++---------------------- 1 file changed, 5519 insertions(+), 5559 deletions(-) diff --git a/doc/whats-new.rst b/doc/whats-new.rst index 57df47023f3..0053824c87b 100644 --- a/doc/whats-new.rst +++ b/doc/whats-new.rst @@ -1,5573 +1,5533 @@ .. currentmodule:: xarray - What's New - ========== - +What's New +========== + +.. ipython:: python + :suppress: + + import numpy as np + import pandas as pd + import xarray as xray + import xarray + import xarray as xr + + np.random.seed(123456) + +.. _whats-new.0.18.3: + +v0.18.3 (unreleased) +--------------------- + +New Features +~~~~~~~~~~~~ +- Allow passing a dictionary as coords to a :py:class:`DataArray` (:issue:`5527`, + reverts :pull:`1539`, which had deprecated this due to python's inconsistent ordering in earlier versions). + By `Sander van Rijn `_. +- Added :py:meth:`Dataset.coarsen.construct`, :py:meth:`DataArray.coarsen.construct` (:issue:`5454`, :pull:`5475`). + By `Deepak Cherian `_. +- Xarray now uses consolidated metadata by default when writing and reading Zarr + stores (:issue:`5251`). + By `Stephan Hoyer `_. +- New top-level function :py:func:`unify_chunks`. + By `Mattia Almansi `_. +- Allow assigning values to a subset of a dataset using positional or label-based + indexing (:issue:`3015`, :pull:`5362`). + By `Matthias Göbel `_. +- Attempting to reduce a weighted object over missing dimensions now raises an error (:pull:`5362`). + By `Mattia Almansi `_. +- Add ``.sum`` to :py:meth:`~xarray.DataArray.rolling_exp` and + :py:meth:`~xarray.Dataset.rolling_exp` for exponentially weighted rolling + sums. These require numbagg 0.2.1; + (:pull:`5178`). + By `Maximilian Roos `_. +- :py:func:`xarray.cov` and :py:func:`xarray.corr` now lazily check for missing + values if inputs are dask arrays (:issue:`4804`, :pull:`5284`). + By `Andrew Williams `_. +- Attempting to ``concat`` list of elements that are not all ``Dataset`` or all ``DataArray`` now raises an error (:issue:`5051`, :pull:`5425`). + By `Thomas Hirtz `_. +- allow passing a function to ``combine_attrs`` (:pull:`4896`). + By `Justus Magin `_. +- Allow plotting categorical data (:pull:`5464`). + By `Jimmy Westling `_. +- Allow removal of the coordinate attribute ``coordinates`` on variables by setting ``.attrs['coordinates']= None`` + (:issue:`5510`). + By `Elle Smith `_. + +Breaking changes +~~~~~~~~~~~~~~~~ + +- The default ``mode`` for :py:meth:`Dataset.to_zarr` when ``region`` is set + has changed to the new ``mode="r+"``, which only allows for overriding + pre-existing array values. This is a safer default than the prior ``mode="a"``, + and allows for higher performance writes (:pull:`5252`). + By `Stephan Hoyer `_. +- The main parameter to :py:func:`combine_by_coords` is renamed to `data_objects` instead + of `datasets` so anyone calling this method using a named parameter will need to update + the name accordingly (:issue:`3248`, :pull:`4696`). + By `Augustus Ijams `_. + +Deprecations +~~~~~~~~~~~~ + + +Bug fixes +~~~~~~~~~ +- Fix a minor incompatibility between partial datetime string indexing with a + :py:class:`CFTimeIndex` and upcoming pandas version 1.3.0 (:issue:`5356`, + :pull:`5359`). + By `Spencer Clark `_. +- Fix 1-level multi-index incorrectly converted to single index (:issue:`5384`, + :pull:`5385`). + By `Benoit Bovy `_. +- Don't cast a duck array in a coordinate to :py:class:`numpy.ndarray` in + :py:meth:`DataArray.differentiate` (:pull:`5408`) + By `Justus Magin `_. +- Fix the ``repr`` of :py:class:`Variable` objects with ``display_expand_data=True`` + (:pull:`5406`) + By `Justus Magin `_. +- Plotting a pcolormesh with ``xscale="log"`` and/or ``yscale="log"`` works as + expected after improving the way the interval breaks are generated (:issue:`5333`). + By `Santiago Soler `_ +- :py:func:`combine_by_coords` can now handle combining a list of unnamed + ``DataArray`` as input (:issue:`3248`, :pull:`4696`). + By `Augustus Ijams `_. + + +Documentation +~~~~~~~~~~~~~ + + +Internal Changes +~~~~~~~~~~~~~~~~ +- Run CI on the first & last python versions supported only; currently 3.7 & 3.9. + (:pull:`5433`) + By `Maximilian Roos `_. +- Publish test results & timings on each PR. + (:pull:`5537`) + By `Maximilian Roos `_. + +- Explicit indexes refactor: add a ``xarray.Index.query()`` method in which + one may eventually provide a custom implementation of label-based data + selection (not ready yet for public use). Also refactor the internal, + pandas-specific implementation into ``PandasIndex.query()`` and + ``PandasMultiIndex.query()`` (:pull:`5322`). + By `Benoit Bovy `_. + +.. _whats-new.0.18.2: + +v0.18.2 (19 May 2021) +--------------------- + +This release reverts a regression in xarray's unstacking of dask-backed arrays. + +.. _whats-new.0.18.1: + +v0.18.1 (18 May 2021) +--------------------- + +This release is intended as a small patch release to be compatible with the new +2021.5.0 ``dask.distributed`` release. It also includes a new +``drop_duplicates`` method, some documentation improvements, the beginnings of +our internal Index refactoring, and some bug fixes. + +Thank you to all 16 contributors! + +Anderson Banihirwe, Andrew, Benoit Bovy, Brewster Malevich, Giacomo Caria, +Illviljan, James Bourbeau, Keewis, Maximilian Roos, Ravin Kumar, Stephan Hoyer, +Thomas Nicholas, Tom Nicholas, Zachary Moon. + +New Features +~~~~~~~~~~~~ +- Implement :py:meth:`DataArray.drop_duplicates` + to remove duplicate dimension values (:pull:`5239`). + By `Andrew Huang `_. +- Allow passing ``combine_attrs`` strategy names to the ``keep_attrs`` parameter of + :py:func:`apply_ufunc` (:pull:`5041`) + By `Justus Magin `_. +- :py:meth:`Dataset.interp` now allows interpolation with non-numerical datatypes, + such as booleans, instead of dropping them. (:issue:`4761` :pull:`5008`). + By `Jimmy Westling `_. +- Raise more informative error when decoding time variables with invalid reference dates. + (:issue:`5199`, :pull:`5288`). By `Giacomo Caria `_. + +Breaking changes +~~~~~~~~~~~~~~~~ + + +Deprecations +~~~~~~~~~~~~ + + +Bug fixes +~~~~~~~~~ +- Opening netCDF files from a path that doesn't end in ``.nc`` without supplying + an explicit ``engine`` works again (:issue:`5295`), fixing a bug introduced in + 0.18.0. + By `Stephan Hoyer `_ + +Documentation +~~~~~~~~~~~~~ +- Clean up and enhance docstrings for the :py:class:`DataArray.plot` and ``Dataset.plot.*`` + families of methods (:pull:`5285`). + By `Zach Moon `_. + +- Explanation of deprecation cycles and how to implement them added to contributors + guide. (:pull:`5289`) + By `Tom Nicholas `_. + + +Internal Changes +~~~~~~~~~~~~~~~~ + +- Explicit indexes refactor: add an ``xarray.Index`` base class and + ``Dataset.xindexes`` / ``DataArray.xindexes`` properties. Also rename + ``PandasIndexAdapter`` to ``PandasIndex``, which now inherits from + ``xarray.Index`` (:pull:`5102`). + By `Benoit Bovy `_. +- Replace ``SortedKeysDict`` with python's ``dict``, given dicts are now ordered. + By `Maximilian Roos `_. +- Updated the release guide for developers. Now accounts for actions that are automated via github + actions. (:pull:`5274`). + By `Tom Nicholas `_. + +.. _whats-new.0.18.0: + +v0.18.0 (6 May 2021) +-------------------- + +This release brings a few important performance improvements, a wide range of +usability upgrades, lots of bug fixes, and some new features. These include +a plugin API to add backend engines, a new theme for the documentation, +curve fitting methods, and several new plotting functions. + +Many thanks to the 38 contributors to this release: Aaron Spring, Alessandro Amici, +Alex Marandon, Alistair Miles, Ana Paula Krelling, Anderson Banihirwe, Aureliana Barghini, +Baudouin Raoult, Benoit Bovy, Blair Bonnett, David Trémouilles, Deepak Cherian, +Gabriel Medeiros Abrahão, Giacomo Caria, Hauke Schulz, Illviljan, Mathias Hauser, Matthias Bussonnier, +Mattia Almansi, Maximilian Roos, Ray Bell, Richard Kleijn, Ryan Abernathey, Sam Levang, Spencer Clark, +Spencer Jones, Tammas Loughran, Tobias Kölling, Todd, Tom Nicholas, Tom White, Victor Negîrneac, +Xianxiang Li, Zeb Nicholls, crusaderky, dschwoerer, johnomotani, keewis + + +New Features +~~~~~~~~~~~~ + +- apply ``combine_attrs`` on data variables and coordinate variables when concatenating + and merging datasets and dataarrays (:pull:`4902`). + By `Justus Magin `_. +- Add :py:meth:`Dataset.to_pandas` (:pull:`5247`) + By `Giacomo Caria `_. +- Add :py:meth:`DataArray.plot.surface` which wraps matplotlib's `plot_surface` to make + surface plots (:issue:`2235` :issue:`5084` :pull:`5101`). + By `John Omotani `_. +- Allow passing multiple arrays to :py:meth:`Dataset.__setitem__` (:pull:`5216`). + By `Giacomo Caria `_. +- Add 'cumulative' option to :py:meth:`Dataset.integrate` and + :py:meth:`DataArray.integrate` so that result is a cumulative integral, like + :py:func:`scipy.integrate.cumulative_trapezoidal` (:pull:`5153`). + By `John Omotani `_. +- Add ``safe_chunks`` option to :py:meth:`Dataset.to_zarr` which allows overriding + checks made to ensure Dask and Zarr chunk compatibility (:issue:`5056`). + By `Ryan Abernathey `_ +- Add :py:meth:`Dataset.query` and :py:meth:`DataArray.query` which enable indexing + of datasets and data arrays by evaluating query expressions against the values of the + data variables (:pull:`4984`). + By `Alistair Miles `_. +- Allow passing ``combine_attrs`` to :py:meth:`Dataset.merge` (:pull:`4895`). + By `Justus Magin `_. +- Support for `dask.graph_manipulation + `_ (requires dask >=2021.3) + By `Guido Imperiale `_ +- Add :py:meth:`Dataset.plot.streamplot` for streamplot plots with :py:class:`Dataset` + variables (:pull:`5003`). + By `John Omotani `_. +- Many of the arguments for the :py:attr:`DataArray.str` methods now support + providing an array-like input. In this case, the array provided to the + arguments is broadcast against the original array and applied elementwise. +- :py:attr:`DataArray.str` now supports ``+``, ``*``, and ``%`` operators. These + behave the same as they do for :py:class:`str`, except that they follow + array broadcasting rules. +- A large number of new :py:attr:`DataArray.str` methods were implemented, + :py:meth:`DataArray.str.casefold`, :py:meth:`DataArray.str.cat`, + :py:meth:`DataArray.str.extract`, :py:meth:`DataArray.str.extractall`, + :py:meth:`DataArray.str.findall`, :py:meth:`DataArray.str.format`, + :py:meth:`DataArray.str.get_dummies`, :py:meth:`DataArray.str.islower`, + :py:meth:`DataArray.str.join`, :py:meth:`DataArray.str.normalize`, + :py:meth:`DataArray.str.partition`, :py:meth:`DataArray.str.rpartition`, + :py:meth:`DataArray.str.rsplit`, and :py:meth:`DataArray.str.split`. + A number of these methods allow for splitting or joining the strings in an + array. (:issue:`4622`) + By `Todd Jennings `_ +- Thanks to the new pluggable backend infrastructure external packages may now + use the ``xarray.backends`` entry point to register additional engines to be used in + :py:func:`open_dataset`, see the documentation in :ref:`add_a_backend` + (:issue:`4309`, :issue:`4803`, :pull:`4989`, :pull:`4810` and many others). + The backend refactor has been sponsored with the "Essential Open Source Software for Science" + grant from the `Chan Zuckerberg Initiative `_ and + developed by `B-Open `_. + By `Aureliana Barghini `_ and `Alessandro Amici `_. +- :py:attr:`~core.accessor_dt.DatetimeAccessor.date` added (:issue:`4983`, :pull:`4994`). + By `Hauke Schulz `_. +- Implement ``__getitem__`` for both :py:class:`~core.groupby.DatasetGroupBy` and + :py:class:`~core.groupby.DataArrayGroupBy`, inspired by pandas' + :py:meth:`~pandas.core.groupby.GroupBy.get_group`. + By `Deepak Cherian `_. +- Switch the tutorial functions to use `pooch `_ + (which is now a optional dependency) and add :py:func:`tutorial.open_rasterio` as a + way to open example rasterio files (:issue:`3986`, :pull:`4102`, :pull:`5074`). + By `Justus Magin `_. +- Add typing information to unary and binary arithmetic operators operating on + :py:class:`Dataset`, :py:class:`DataArray`, :py:class:`Variable`, + :py:class:`~core.groupby.DatasetGroupBy` or + :py:class:`~core.groupby.DataArrayGroupBy` (:pull:`4904`). + By `Richard Kleijn `_. +- Add a ``combine_attrs`` parameter to :py:func:`open_mfdataset` (:pull:`4971`). + By `Justus Magin `_. +- Enable passing arrays with a subset of dimensions to + :py:meth:`DataArray.clip` & :py:meth:`Dataset.clip`; these methods now use + :py:func:`xarray.apply_ufunc`; (:pull:`5184`). + By `Maximilian Roos `_. +- Disable the `cfgrib` backend if the `eccodes` library is not installed (:pull:`5083`). + By `Baudouin Raoult `_. +- Added :py:meth:`DataArray.curvefit` and :py:meth:`Dataset.curvefit` for general curve fitting applications. (:issue:`4300`, :pull:`4849`) + By `Sam Levang `_. +- Add options to control expand/collapse of sections in display of Dataset and + DataArray. The function :py:func:`set_options` now takes keyword aguments + ``display_expand_attrs``, ``display_expand_coords``, ``display_expand_data``, + ``display_expand_data_vars``, all of which can be one of ``True`` to always + expand, ``False`` to always collapse, or ``default`` to expand unless over a + pre-defined limit (:pull:`5126`). + By `Tom White `_. +- Significant speedups in :py:meth:`Dataset.interp` and :py:meth:`DataArray.interp`. + (:issue:`4739`, :pull:`4740`). + By `Deepak Cherian `_. +- Prevent passing `concat_dim` to :py:func:`xarray.open_mfdataset` when + `combine='by_coords'` is specified, which should never have been possible (as + :py:func:`xarray.combine_by_coords` has no `concat_dim` argument to pass to). + Also removes unneeded internal reordering of datasets in + :py:func:`xarray.open_mfdataset` when `combine='by_coords'` is specified. + Fixes (:issue:`5230`). + By `Tom Nicholas `_. +- Implement ``__setitem__`` for ``xarray.core.indexing.DaskIndexingAdapter`` if + dask version supports item assignment. (:issue:`5171`, :pull:`5174`) + By `Tammas Loughran `_. + +Breaking changes +~~~~~~~~~~~~~~~~ +- The minimum versions of some dependencies were changed: + + ============ ====== ==== + Package Old New + ============ ====== ==== + boto3 1.12 1.13 + cftime 1.0 1.1 + dask 2.11 2.15 + distributed 2.11 2.15 + matplotlib 3.1 3.2 + numba 0.48 0.49 + ============ ====== ==== + +- :py:func:`open_dataset` and :py:func:`open_dataarray` now accept only the first argument + as positional, all others need to be passed are keyword arguments. This is part of the + refactor to support external backends (:issue:`4309`, :pull:`4989`). + By `Alessandro Amici `_. +- Functions that are identities for 0d data return the unchanged data + if axis is empty. This ensures that Datasets where some variables do + not have the averaged dimensions are not accidentially changed + (:issue:`4885`, :pull:`5207`). + By `David Schwörer `_. +- :py:attr:`DataArray.coarsen` and :py:attr:`Dataset.coarsen` no longer support passing ``keep_attrs`` + via its constructor. Pass ``keep_attrs`` via the applied function, i.e. use + ``ds.coarsen(...).mean(keep_attrs=False)`` instead of ``ds.coarsen(..., keep_attrs=False).mean()``. + Further, coarsen now keeps attributes per default (:pull:`5227`). + By `Mathias Hauser `_. +- switch the default of the :py:func:`merge` ``combine_attrs`` parameter to + ``"override"``. This will keep the current behavior for merging the ``attrs`` of + variables but stop dropping the ``attrs`` of the main objects (:pull:`4902`). + By `Justus Magin `_. + +Deprecations +~~~~~~~~~~~~ + +- Warn when passing `concat_dim` to :py:func:`xarray.open_mfdataset` when + `combine='by_coords'` is specified, which should never have been possible (as + :py:func:`xarray.combine_by_coords` has no `concat_dim` argument to pass to). + Also removes unneeded internal reordering of datasets in + :py:func:`xarray.open_mfdataset` when `combine='by_coords'` is specified. + Fixes (:issue:`5230`), via (:pull:`5231`, :pull:`5255`). + By `Tom Nicholas `_. +- The `lock` keyword argument to :py:func:`open_dataset` and :py:func:`open_dataarray` is now + a backend specific option. It will give a warning if passed to a backend that doesn't support it + instead of being silently ignored. From the next version it will raise an error. + This is part of the refactor to support external backends (:issue:`5073`). + By `Tom Nicholas `_ and `Alessandro Amici `_. + + +Bug fixes +~~~~~~~~~ +- Properly support :py:meth:`DataArray.ffill`, :py:meth:`DataArray.bfill`, :py:meth:`Dataset.ffill`, :py:meth:`Dataset.bfill` along chunked dimensions. + (:issue:`2699`). + By `Deepak Cherian `_. +- Fix 2d plot failure for certain combinations of dimensions when `x` is 1d and `y` is + 2d (:issue:`5097`, :pull:`5099`). + By `John Omotani `_. +- Ensure standard calendar times encoded with large values (i.e. greater than + approximately 292 years), can be decoded correctly without silently overflowing + (:pull:`5050`). This was a regression in xarray 0.17.0. + By `Zeb Nicholls `_. +- Added support for `numpy.bool_` attributes in roundtrips using `h5netcdf` engine with `invalid_netcdf=True` [which casts `bool`s to `numpy.bool_`] (:issue:`4981`, :pull:`4986`). + By `Victor Negîrneac `_. +- Don't allow passing ``axis`` to :py:meth:`Dataset.reduce` methods (:issue:`3510`, :pull:`4940`). + By `Justus Magin `_. +- Decode values as signed if attribute `_Unsigned = "false"` (:issue:`4954`) + By `Tobias Kölling `_. +- Keep coords attributes when interpolating when the indexer is not a Variable. (:issue:`4239`, :issue:`4839` :pull:`5031`) + By `Jimmy Westling `_. +- Ensure standard calendar dates encoded with a calendar attribute with some or + all uppercase letters can be decoded or encoded to or from + ``np.datetime64[ns]`` dates with or without ``cftime`` installed + (:issue:`5093`, :pull:`5180`). + By `Spencer Clark `_. +- Warn on passing ``keep_attrs`` to ``resample`` and ``rolling_exp`` as they are ignored, pass ``keep_attrs`` + to the applied function instead (:pull:`5265`). + By `Mathias Hauser `_. + +Documentation +~~~~~~~~~~~~~ +- New section on :ref:`add_a_backend` in the "Internals" chapter aimed to backend developers + (:issue:`4803`, :pull:`4810`). + By `Aureliana Barghini `_. +- Add :py:meth:`Dataset.polyfit` and :py:meth:`DataArray.polyfit` under "See also" in + the docstrings of :py:meth:`Dataset.polyfit` and :py:meth:`DataArray.polyfit` + (:issue:`5016`, :pull:`5020`). + By `Aaron Spring `_. +- New sphinx theme & rearrangement of the docs (:pull:`4835`). + By `Anderson Banihirwe `_. + +Internal Changes +~~~~~~~~~~~~~~~~ +- Enable displaying mypy error codes and ignore only specific error codes using + ``# type: ignore[error-code]`` (:pull:`5096`). + By `Mathias Hauser `_. +- Replace uses of ``raises_regex`` with the more standard + ``pytest.raises(Exception, match="foo")``; + (:pull:`5188`), (:pull:`5191`). + By `Maximilian Roos `_. + +.. _whats-new.0.17.0: + +v0.17.0 (24 Feb 2021) +--------------------- + +This release brings a few important performance improvements, a wide range of +usability upgrades, lots of bug fixes, and some new features. These include +better ``cftime`` support, a new quiver plot, better ``unstack`` performance, +more efficient memory use in rolling operations, and some python packaging +improvements. We also have a few documentation improvements (and more planned!). + +Many thanks to the 36 contributors to this release: Alessandro Amici, Anderson +Banihirwe, Aureliana Barghini, Ayrton Bourn, Benjamin Bean, Blair Bonnett, Chun +Ho Chow, DWesl, Daniel Mesejo-León, Deepak Cherian, Eric Keenan, Illviljan, Jens +Hedegaard Nielsen, Jody Klymak, Julien Seguinot, Julius Busecke, Kai Mühlbauer, +Leif Denby, Martin Durant, Mathias Hauser, Maximilian Roos, Michael Mann, Ray +Bell, RichardScottOZ, Spencer Clark, Tim Gates, Tom Nicholas, Yunus Sevinchan, +alexamici, aurghs, crusaderky, dcherian, ghislainp, keewis, rhkleijn + +Breaking changes +~~~~~~~~~~~~~~~~ +- xarray no longer supports python 3.6 + + The minimum version policy was changed to also apply to projects with irregular + releases. As a result, the minimum versions of some dependencies have changed: + + ============ ====== ==== + Package Old New + ============ ====== ==== + Python 3.6 3.7 + setuptools 38.4 40.4 + numpy 1.15 1.17 + pandas 0.25 1.0 + dask 2.9 2.11 + distributed 2.9 2.11 + bottleneck 1.2 1.3 + h5netcdf 0.7 0.8 + iris 2.2 2.4 + netcdf4 1.4 1.5 + pseudonetcdf 3.0 3.1 + rasterio 1.0 1.1 + scipy 1.3 1.4 + seaborn 0.9 0.10 + zarr 2.3 2.4 + ============ ====== ==== + + (:issue:`4688`, :pull:`4720`, :pull:`4907`, :pull:`4942`) +- As a result of :pull:`4684` the default units encoding for + datetime-like values (``np.datetime64[ns]`` or ``cftime.datetime``) will now + always be set such that ``int64`` values can be used. In the past, no units + finer than "seconds" were chosen, which would sometimes mean that ``float64`` + values were required, which would lead to inaccurate I/O round-trips. +- Variables referred to in attributes like ``bounds`` and ``grid_mapping`` + can be set as coordinate variables. These attributes are moved to + :py:attr:`DataArray.encoding` from :py:attr:`DataArray.attrs`. This behaviour + is controlled by the ``decode_coords`` kwarg to :py:func:`open_dataset` and + :py:func:`open_mfdataset`. The full list of decoded attributes is in + :ref:`weather-climate` (:pull:`2844`, :issue:`3689`) +- As a result of :pull:`4911` the output from calling :py:meth:`DataArray.sum` + or :py:meth:`DataArray.prod` on an integer array with ``skipna=True`` and a + non-None value for ``min_count`` will now be a float array rather than an + integer array. + +Deprecations +~~~~~~~~~~~~ + +- ``dim`` argument to :py:meth:`DataArray.integrate` is being deprecated in + favour of a ``coord`` argument, for consistency with :py:meth:`Dataset.integrate`. + For now using ``dim`` issues a ``FutureWarning``. It will be removed in + version 0.19.0 (:pull:`3993`). + By `Tom Nicholas `_. +- Deprecated ``autoclose`` kwargs from :py:func:`open_dataset` are removed (:pull:`4725`). + By `Aureliana Barghini `_. +- the return value of :py:meth:`Dataset.update` is being deprecated to make it work more + like :py:meth:`dict.update`. It will be removed in version 0.19.0 (:pull:`4932`). + By `Justus Magin `_. + +New Features +~~~~~~~~~~~~ +- :py:meth:`~xarray.cftime_range` and :py:meth:`DataArray.resample` now support + millisecond (``"L"`` or ``"ms"``) and microsecond (``"U"`` or ``"us"``) frequencies + for ``cftime.datetime`` coordinates (:issue:`4097`, :pull:`4758`). + By `Spencer Clark `_. +- Significantly higher ``unstack`` performance on numpy-backed arrays which + contain missing values; 8x faster than previous versions in our benchmark, and + now 2x faster than pandas (:pull:`4746`). + By `Maximilian Roos `_. +- Add :py:meth:`Dataset.plot.quiver` for quiver plots with :py:class:`Dataset` variables. + By `Deepak Cherian `_. +- Add ``"drop_conflicts"`` to the strategies supported by the ``combine_attrs`` kwarg + (:issue:`4749`, :pull:`4827`). + By `Justus Magin `_. +- Allow installing from git archives (:pull:`4897`). + By `Justus Magin `_. +- :py:class:`~core.rolling.DataArrayCoarsen` and :py:class:`~core.rolling.DatasetCoarsen` + now implement a ``reduce`` method, enabling coarsening operations with custom + reduction functions (:issue:`3741`, :pull:`4939`). + By `Spencer Clark `_. +- Most rolling operations use significantly less memory. (:issue:`4325`). + By `Deepak Cherian `_. +- Add :py:meth:`Dataset.drop_isel` and :py:meth:`DataArray.drop_isel` + (:issue:`4658`, :pull:`4819`). + By `Daniel Mesejo `_. +- Xarray now leverages updates as of cftime version 1.4.1, which enable exact I/O + roundtripping of ``cftime.datetime`` objects (:pull:`4758`). + By `Spencer Clark `_. +- :py:func:`open_dataset` and :py:func:`open_mfdataset` now accept ``fsspec`` URLs + (including globs for the latter) for ``engine="zarr"``, and so allow reading from + many remote and other file systems (:pull:`4461`) + By `Martin Durant `_ +- :py:meth:`DataArray.swap_dims` & :py:meth:`Dataset.swap_dims` now accept dims + in the form of kwargs as well as a dict, like most similar methods. + By `Maximilian Roos `_. + +Bug fixes +~~~~~~~~~ +- Use specific type checks in ``xarray.core.variable.as_compatible_data`` instead of + blanket access to ``values`` attribute (:issue:`2097`) + By `Yunus Sevinchan `_. +- :py:meth:`DataArray.resample` and :py:meth:`Dataset.resample` do not trigger + computations anymore if :py:meth:`Dataset.weighted` or + :py:meth:`DataArray.weighted` are applied (:issue:`4625`, :pull:`4668`). By + `Julius Busecke `_. +- :py:func:`merge` with ``combine_attrs='override'`` makes a copy of the attrs + (:issue:`4627`). +- By default, when possible, xarray will now always use values of + type ``int64`` when encoding and decoding ``numpy.datetime64[ns]`` datetimes. This + ensures that maximum precision and accuracy are maintained in the round-tripping + process (:issue:`4045`, :pull:`4684`). It also enables encoding and decoding standard + calendar dates with time units of nanoseconds (:pull:`4400`). + By `Spencer Clark `_ and `Mark Harfouche + `_. +- :py:meth:`DataArray.astype`, :py:meth:`Dataset.astype` and :py:meth:`Variable.astype` support + the ``order`` and ``subok`` parameters again. This fixes a regression introduced in version 0.16.1 + (:issue:`4644`, :pull:`4683`). + By `Richard Kleijn `_ . +- Remove dictionary unpacking when using ``.loc`` to avoid collision with ``.sel`` parameters (:pull:`4695`). + By `Anderson Banihirwe `_. +- Fix the legend created by :py:meth:`Dataset.plot.scatter` (:issue:`4641`, :pull:`4723`). + By `Justus Magin `_. +- Fix a crash in orthogonal indexing on geographic coordinates with ``engine='cfgrib'`` + (:issue:`4733` :pull:`4737`). + By `Alessandro Amici `_. +- Coordinates with dtype ``str`` or ``bytes`` now retain their dtype on many operations, + e.g. ``reindex``, ``align``, ``concat``, ``assign``, previously they were cast to an object dtype + (:issue:`2658` and :issue:`4543`). + By `Mathias Hauser `_. +- Limit number of data rows when printing large datasets. (:issue:`4736`, :pull:`4750`). + By `Jimmy Westling `_. +- Add ``missing_dims`` parameter to transpose (:issue:`4647`, :pull:`4767`). + By `Daniel Mesejo `_. +- Resolve intervals before appending other metadata to labels when plotting (:issue:`4322`, :pull:`4794`). + By `Justus Magin `_. +- Fix regression when decoding a variable with a ``scale_factor`` and ``add_offset`` given + as a list of length one (:issue:`4631`). + By `Mathias Hauser `_. +- Expand user directory paths (e.g. ``~/``) in :py:func:`open_mfdataset` and + :py:meth:`Dataset.to_zarr` (:issue:`4783`, :pull:`4795`). + By `Julien Seguinot `_. +- Raise DeprecationWarning when trying to typecast a tuple containing a :py:class:`DataArray`. + User now prompted to first call `.data` on it (:issue:`4483`). + By `Chun Ho Chow `_. +- Ensure that :py:meth:`Dataset.interp` raises ``ValueError`` when interpolating + outside coordinate range and ``bounds_error=True`` (:issue:`4854`, + :pull:`4855`). + By `Leif Denby `_. +- Fix time encoding bug associated with using cftime versions greater than + 1.4.0 with xarray (:issue:`4870`, :pull:`4871`). + By `Spencer Clark `_. +- Stop :py:meth:`DataArray.sum` and :py:meth:`DataArray.prod` computing lazy + arrays when called with a ``min_count`` parameter (:issue:`4898`, :pull:`4911`). + By `Blair Bonnett `_. +- Fix bug preventing the ``min_count`` parameter to :py:meth:`DataArray.sum` and + :py:meth:`DataArray.prod` working correctly when calculating over all axes of + a float64 array (:issue:`4898`, :pull:`4911`). + By `Blair Bonnett `_. +- Fix decoding of vlen strings using h5py versions greater than 3.0.0 with h5netcdf backend (:issue:`4570`, :pull:`4893`). + By `Kai Mühlbauer `_. +- Allow converting :py:class:`Dataset` or :py:class:`DataArray` objects with a ``MultiIndex`` + and at least one other dimension to a ``pandas`` object (:issue:`3008`, :pull:`4442`). + By `ghislainp `_. + +Documentation +~~~~~~~~~~~~~ +- Add information about requirements for accessor classes (:issue:`2788`, :pull:`4657`). + By `Justus Magin `_. +- Start a list of external I/O integrating with ``xarray`` (:issue:`683`, :pull:`4566`). + By `Justus Magin `_. +- Add concat examples and improve combining documentation (:issue:`4620`, :pull:`4645`). + By `Ray Bell `_ and + `Justus Magin `_. +- explicitly mention that :py:meth:`Dataset.update` updates inplace (:issue:`2951`, :pull:`4932`). + By `Justus Magin `_. +- Added docs on vectorized indexing (:pull:`4711`). + By `Eric Keenan `_. + +Internal Changes +~~~~~~~~~~~~~~~~ +- Speed up of the continuous integration tests on azure. + + - Switched to mamba and use matplotlib-base for a faster installation of all dependencies (:pull:`4672`). + - Use ``pytest.mark.skip`` instead of ``pytest.mark.xfail`` for some tests that can currently not + succeed (:pull:`4685`). + - Run the tests in parallel using pytest-xdist (:pull:`4694`). + + By `Justus Magin `_ and `Mathias Hauser `_. +- Use ``pyproject.toml`` instead of the ``setup_requires`` option for + ``setuptools`` (:pull:`4897`). + By `Justus Magin `_. +- Replace all usages of ``assert x.identical(y)`` with ``assert_identical(x, y)`` + for clearer error messages (:pull:`4752`). + By `Maximilian Roos `_. +- Speed up attribute style access (e.g. ``ds.somevar`` instead of ``ds["somevar"]``) and + tab completion in IPython (:issue:`4741`, :pull:`4742`). + By `Richard Kleijn `_. +- Added the ``set_close`` method to ``Dataset`` and ``DataArray`` for backends + to specify how to voluntary release all resources. (:pull:`#4809`) + By `Alessandro Amici `_. +- Update type hints to work with numpy v1.20 (:pull:`4878`). + By `Mathias Hauser `_. +- Ensure warnings cannot be turned into exceptions in :py:func:`testing.assert_equal` and + the other ``assert_*`` functions (:pull:`4864`). + By `Mathias Hauser `_. +- Performance improvement when constructing DataArrays. Significantly speeds up + repr for Datasets with large number of variables. + By `Deepak Cherian `_. + +.. _whats-new.0.16.2: + +v0.16.2 (30 Nov 2020) +--------------------- + +This release brings the ability to write to limited regions of ``zarr`` files, +open zarr files with :py:func:`open_dataset` and :py:func:`open_mfdataset`, +increased support for propagating ``attrs`` using the ``keep_attrs`` flag, as +well as numerous bugfixes and documentation improvements. + +Many thanks to the 31 contributors who contributed to this release: Aaron +Spring, Akio Taniguchi, Aleksandar Jelenak, alexamici, Alexandre Poux, Anderson +Banihirwe, Andrew Pauling, Ashwin Vishnu, aurghs, Brian Ward, Caleb, crusaderky, +Dan Nowacki, darikg, David Brochart, David Huard, Deepak Cherian, Dion Häfner, +Gerardo Rivera, Gerrit Holl, Illviljan, inakleinbottle, Jacob Tomlinson, James +A. Bednar, jenssss, Joe Hamman, johnomotani, Joris Van den Bossche, Julia Kent, +Julius Busecke, Kai Mühlbauer, keewis, Keisuke Fujii, Kyle Cranmer, Luke +Volpatti, Mathias Hauser, Maximilian Roos, Michaël Defferrard, Michal +Baumgartner, Nick R. Papior, Pascal Bourgault, Peter Hausamann, PGijsbers, Ray +Bell, Romain Martinez, rpgoldman, Russell Manser, Sahid Velji, Samnan Rahee, +Sander, Spencer Clark, Stephan Hoyer, Thomas Zilio, Tobias Kölling, Tom +Augspurger, Wei Ji, Yash Saboo, Zeb Nicholls, + +Deprecations +~~~~~~~~~~~~ + +- :py:attr:`~core.accessor_dt.DatetimeAccessor.weekofyear` and :py:attr:`~core.accessor_dt.DatetimeAccessor.week` + have been deprecated. Use ``DataArray.dt.isocalendar().week`` + instead (:pull:`4534`). By `Mathias Hauser `_. + `Maximilian Roos `_, and `Spencer Clark `_. +- :py:attr:`DataArray.rolling` and :py:attr:`Dataset.rolling` no longer support passing ``keep_attrs`` + via its constructor. Pass ``keep_attrs`` via the applied function, i.e. use + ``ds.rolling(...).mean(keep_attrs=False)`` instead of ``ds.rolling(..., keep_attrs=False).mean()`` + Rolling operations now keep their attributes per default (:pull:`4510`). + By `Mathias Hauser `_. + +New Features +~~~~~~~~~~~~ + +- :py:func:`open_dataset` and :py:func:`open_mfdataset` + now works with ``engine="zarr"`` (:issue:`3668`, :pull:`4003`, :pull:`4187`). + By `Miguel Jimenez `_ and `Wei Ji Leong `_. +- Unary & binary operations follow the ``keep_attrs`` flag (:issue:`3490`, :issue:`4065`, :issue:`3433`, :issue:`3595`, :pull:`4195`). + By `Deepak Cherian `_. +- Added :py:meth:`~core.accessor_dt.DatetimeAccessor.isocalendar()` that returns a Dataset + with year, week, and weekday calculated according to the ISO 8601 calendar. Requires + pandas version 1.1.0 or greater (:pull:`4534`). By `Mathias Hauser `_, + `Maximilian Roos `_, and `Spencer Clark `_. +- :py:meth:`Dataset.to_zarr` now supports a ``region`` keyword for writing to + limited regions of existing Zarr stores (:pull:`4035`). + See :ref:`io.zarr.appending` for full details. + By `Stephan Hoyer `_. +- Added typehints in :py:func:`align` to reflect that the same type received in ``objects`` arg will be returned (:pull:`4522`). + By `Michal Baumgartner `_. +- :py:meth:`Dataset.weighted` and :py:meth:`DataArray.weighted` are now executing value checks lazily if weights are provided as dask arrays (:issue:`4541`, :pull:`4559`). + By `Julius Busecke `_. +- Added the ``keep_attrs`` keyword to ``rolling_exp.mean()``; it now keeps attributes + per default. By `Mathias Hauser `_ (:pull:`4592`). +- Added ``freq`` as property to :py:class:`CFTimeIndex` and into the + ``CFTimeIndex.repr``. (:issue:`2416`, :pull:`4597`) + By `Aaron Spring `_. + +Bug fixes +~~~~~~~~~ + +- Fix bug where reference times without padded years (e.g. ``since 1-1-1``) would lose their units when + being passed by ``encode_cf_datetime`` (:issue:`4422`, :pull:`4506`). Such units are ambiguous + about which digit represents the years (is it YMD or DMY?). Now, if such formatting is encountered, + it is assumed that the first digit is the years, they are padded appropriately (to e.g. ``since 0001-1-1``) + and a warning that this assumption is being made is issued. Previously, without ``cftime``, such times + would be silently parsed incorrectly (at least based on the CF conventions) e.g. "since 1-1-1" would + be parsed (via ``pandas`` and ``dateutil``) to ``since 2001-1-1``. + By `Zeb Nicholls `_. +- Fix :py:meth:`DataArray.plot.step`. By `Deepak Cherian `_. +- Fix bug where reading a scalar value from a NetCDF file opened with the ``h5netcdf`` backend would raise a ``ValueError`` when ``decode_cf=True`` (:issue:`4471`, :pull:`4485`). + By `Gerrit Holl `_. +- Fix bug where datetime64 times are silently changed to incorrect values if they are outside the valid date range for ns precision when provided in some other units (:issue:`4427`, :pull:`4454`). + By `Andrew Pauling `_ +- Fix silently overwriting the ``engine`` key when passing :py:func:`open_dataset` a file object + to an incompatible netCDF (:issue:`4457`). Now incompatible combinations of files and engines raise + an exception instead. By `Alessandro Amici `_. +- The ``min_count`` argument to :py:meth:`DataArray.sum()` and :py:meth:`DataArray.prod()` + is now ignored when not applicable, i.e. when ``skipna=False`` or when ``skipna=None`` + and the dtype does not have a missing value (:issue:`4352`). + By `Mathias Hauser `_. +- :py:func:`combine_by_coords` now raises an informative error when passing coordinates + with differing calendars (:issue:`4495`). By `Mathias Hauser `_. +- :py:attr:`DataArray.rolling` and :py:attr:`Dataset.rolling` now also keep the attributes and names of of (wrapped) + ``DataArray`` objects, previously only the global attributes were retained (:issue:`4497`, :pull:`4510`). + By `Mathias Hauser `_. +- Improve performance where reading small slices from huge dimensions was slower than necessary (:pull:`4560`). By `Dion Häfner `_. +- Fix bug where ``dask_gufunc_kwargs`` was silently changed in :py:func:`apply_ufunc` (:pull:`4576`). By `Kai Mühlbauer `_. + +Documentation +~~~~~~~~~~~~~ +- document the API not supported with duck arrays (:pull:`4530`). + By `Justus Magin `_. +- Mention the possibility to pass functions to :py:meth:`Dataset.where` or + :py:meth:`DataArray.where` in the parameter documentation (:issue:`4223`, :pull:`4613`). + By `Justus Magin `_. +- Update the docstring of :py:class:`DataArray` and :py:class:`Dataset`. + (:pull:`4532`); + By `Jimmy Westling `_. +- Raise a more informative error when :py:meth:`DataArray.to_dataframe` is + is called on a scalar, (:issue:`4228`); + By `Pieter Gijsbers `_. +- Fix grammar and typos in the :doc:`contributing` guide (:pull:`4545`). + By `Sahid Velji `_. +- Fix grammar and typos in the :doc:`user-guide/io` guide (:pull:`4553`). + By `Sahid Velji `_. +- Update link to NumPy docstring standard in the :doc:`contributing` guide (:pull:`4558`). + By `Sahid Velji `_. +- Add docstrings to ``isnull`` and ``notnull``, and fix the displayed signature + (:issue:`2760`, :pull:`4618`). + By `Justus Magin `_. + +Internal Changes +~~~~~~~~~~~~~~~~ + +- Optional dependencies can be installed along with xarray by specifying + extras as ``pip install "xarray[extra]"`` where ``extra`` can be one of ``io``, + ``accel``, ``parallel``, ``viz`` and ``complete``. See docs for updated + :ref:`installation instructions `. + (:issue:`2888`, :pull:`4480`). + By `Ashwin Vishnu `_, `Justus Magin + `_ and `Mathias Hauser + `_. +- Removed stray spaces that stem from black removing new lines (:pull:`4504`). + By `Mathias Hauser `_. +- Ensure tests are not skipped in the ``py38-all-but-dask`` test environment + (:issue:`4509`). By `Mathias Hauser `_. +- Ignore select numpy warnings around missing values, where xarray handles + the values appropriately, (:pull:`4536`); + By `Maximilian Roos `_. +- Replace the internal use of ``pd.Index.__or__`` and ``pd.Index.__and__`` with ``pd.Index.union`` + and ``pd.Index.intersection`` as they will stop working as set operations in the future + (:issue:`4565`). By `Mathias Hauser `_. +- Add GitHub action for running nightly tests against upstream dependencies (:pull:`4583`). + By `Anderson Banihirwe `_. +- Ensure all figures are closed properly in plot tests (:pull:`4600`). + By `Yash Saboo `_, `Nirupam K N + `_ and `Mathias Hauser + `_. + +.. _whats-new.0.16.1: + +v0.16.1 (2020-09-20) +--------------------- + +This patch release fixes an incompatibility with a recent pandas change, which +was causing an issue indexing with a ``datetime64``. It also includes +improvements to ``rolling``, ``to_dataframe``, ``cov`` & ``corr`` methods and +bug fixes. Our documentation has a number of improvements, including fixing all +doctests and confirming their accuracy on every commit. + +Many thanks to the 36 contributors who contributed to this release: + +Aaron Spring, Akio Taniguchi, Aleksandar Jelenak, Alexandre Poux, +Caleb, Dan Nowacki, Deepak Cherian, Gerardo Rivera, Jacob Tomlinson, James A. +Bednar, Joe Hamman, Julia Kent, Kai Mühlbauer, Keisuke Fujii, Mathias Hauser, +Maximilian Roos, Nick R. Papior, Pascal Bourgault, Peter Hausamann, Romain +Martinez, Russell Manser, Samnan Rahee, Sander, Spencer Clark, Stephan Hoyer, +Thomas Zilio, Tobias Kölling, Tom Augspurger, alexamici, crusaderky, darikg, +inakleinbottle, jenssss, johnomotani, keewis, and rpgoldman. + +Breaking changes +~~~~~~~~~~~~~~~~ + +- :py:meth:`DataArray.astype` and :py:meth:`Dataset.astype` now preserve attributes. Keep the + old behavior by passing `keep_attrs=False` (:issue:`2049`, :pull:`4314`). + By `Dan Nowacki `_ and `Gabriel Joel Mitchell `_. + +New Features +~~~~~~~~~~~~ + +- :py:meth:`~xarray.DataArray.rolling` and :py:meth:`~xarray.Dataset.rolling` + now accept more than 1 dimension. (:pull:`4219`) + By `Keisuke Fujii `_. +- :py:meth:`~xarray.DataArray.to_dataframe` and :py:meth:`~xarray.Dataset.to_dataframe` + now accept a ``dim_order`` parameter allowing to specify the resulting dataframe's + dimensions order (:issue:`4331`, :pull:`4333`). + By `Thomas Zilio `_. +- Support multiple outputs in :py:func:`xarray.apply_ufunc` when using + ``dask='parallelized'``. (:issue:`1815`, :pull:`4060`). + By `Kai Mühlbauer `_. +- ``min_count`` can be supplied to reductions such as ``.sum`` when specifying + multiple dimension to reduce over; (:pull:`4356`). + By `Maximilian Roos `_. +- :py:func:`xarray.cov` and :py:func:`xarray.corr` now handle missing values; (:pull:`4351`). + By `Maximilian Roos `_. +- Add support for parsing datetime strings formatted following the default + string representation of cftime objects, i.e. YYYY-MM-DD hh:mm:ss, in + partial datetime string indexing, as well as :py:meth:`~xarray.cftime_range` + (:issue:`4337`). By `Spencer Clark `_. +- Build ``CFTimeIndex.__repr__`` explicitly as :py:class:`pandas.Index`. Add ``calendar`` as a new + property for :py:class:`CFTimeIndex` and show ``calendar`` and ``length`` in + ``CFTimeIndex.__repr__`` (:issue:`2416`, :pull:`4092`) + By `Aaron Spring `_. +- Use a wrapped array's ``_repr_inline_`` method to construct the collapsed ``repr`` + of :py:class:`DataArray` and :py:class:`Dataset` objects and + document the new method in :doc:`internals/index`. (:pull:`4248`). + By `Justus Magin `_. +- Allow per-variable fill values in most functions. (:pull:`4237`). + By `Justus Magin `_. +- Expose ``use_cftime`` option in :py:func:`~xarray.open_zarr` (:issue:`2886`, :pull:`3229`) + By `Samnan Rahee `_ and `Anderson Banihirwe `_. + +Bug fixes +~~~~~~~~~ + +- Fix indexing with datetime64 scalars with pandas 1.1 (:issue:`4283`). + By `Stephan Hoyer `_ and + `Justus Magin `_. +- Variables which are chunked using dask only along some dimensions can be chunked while storing with zarr along previously + unchunked dimensions (:pull:`4312`) By `Tobias Kölling `_. +- Fixed a bug in backend caused by basic installation of Dask (:issue:`4164`, :pull:`4318`) + `Sam Morley `_. +- Fixed a few bugs with :py:meth:`Dataset.polyfit` when encountering deficient matrix ranks (:issue:`4190`, :pull:`4193`). By `Pascal Bourgault `_. +- Fixed inconsistencies between docstring and functionality for :py:meth:`DataArray.str.get` + and :py:meth:`DataArray.str.wrap` (:issue:`4334`). By `Mathias Hauser `_. +- Fixed overflow issue causing incorrect results in computing means of :py:class:`cftime.datetime` + arrays (:issue:`4341`). By `Spencer Clark `_. +- Fixed :py:meth:`Dataset.coarsen`, :py:meth:`DataArray.coarsen` dropping attributes on original object (:issue:`4120`, :pull:`4360`). By `Julia Kent `_. +- fix the signature of the plot methods. (:pull:`4359`) By `Justus Magin `_. +- Fix :py:func:`xarray.apply_ufunc` with ``vectorize=True`` and ``exclude_dims`` (:issue:`3890`). + By `Mathias Hauser `_. +- Fix `KeyError` when doing linear interpolation to an nd `DataArray` + that contains NaNs (:pull:`4233`). + By `Jens Svensmark `_ +- Fix incorrect legend labels for :py:meth:`Dataset.plot.scatter` (:issue:`4126`). + By `Peter Hausamann `_. +- Fix ``dask.optimize`` on ``DataArray`` producing an invalid Dask task graph (:issue:`3698`) + By `Tom Augspurger `_ +- Fix ``pip install .`` when no ``.git`` directory exists; namely when the xarray source + directory has been rsync'ed by PyCharm Professional for a remote deployment over SSH. + By `Guido Imperiale `_ +- Preserve dimension and coordinate order during :py:func:`xarray.concat` (:issue:`2811`, :issue:`4072`, :pull:`4419`). + By `Kai Mühlbauer `_. +- Avoid relying on :py:class:`set` objects for the ordering of the coordinates (:pull:`4409`) + By `Justus Magin `_. + +Documentation +~~~~~~~~~~~~~ + +- Update the docstring of :py:meth:`DataArray.copy` to remove incorrect mention of 'dataset' (:issue:`3606`) + By `Sander van Rijn `_. +- Removed skipna argument from :py:meth:`DataArray.count`, :py:meth:`DataArray.any`, :py:meth:`DataArray.all`. (:issue:`755`) + By `Sander van Rijn `_ +- Update the contributing guide to use merges instead of rebasing and state + that we squash-merge. (:pull:`4355`). By `Justus Magin `_. +- Make sure the examples from the docstrings actually work (:pull:`4408`). + By `Justus Magin `_. +- Updated Vectorized Indexing to a clearer example. + By `Maximilian Roos `_ + +Internal Changes +~~~~~~~~~~~~~~~~ + +- Fixed all doctests and enabled their running in CI. + By `Justus Magin `_. +- Relaxed the :ref:`mindeps_policy` to support: + + - all versions of setuptools released in the last 42 months (but no older than 38.4) + - all versions of dask and dask.distributed released in the last 12 months (but no + older than 2.9) + - all versions of other packages released in the last 12 months + + All are up from 6 months (:issue:`4295`) + `Guido Imperiale `_. +- Use :py:func:`dask.array.apply_gufunc ` instead of + :py:func:`dask.array.blockwise` in :py:func:`xarray.apply_ufunc` when using + ``dask='parallelized'``. (:pull:`4060`, :pull:`4391`, :pull:`4392`) + By `Kai Mühlbauer `_. +- Align ``mypy`` versions to ``0.782`` across ``requirements`` and + ``.pre-commit-config.yml`` files. (:pull:`4390`) + By `Maximilian Roos `_ +- Only load resource files when running inside a Jupyter Notebook + (:issue:`4294`) By `Guido Imperiale `_ +- Silenced most ``numpy`` warnings such as ``Mean of empty slice``. (:pull:`4369`) + By `Maximilian Roos `_ +- Enable type checking for :py:func:`concat` (:issue:`4238`) + By `Mathias Hauser `_. +- Updated plot functions for matplotlib version 3.3 and silenced warnings in the + plot tests (:pull:`4365`). By `Mathias Hauser `_. +- Versions in ``pre-commit.yaml`` are now pinned, to reduce the chances of + conflicting versions. (:pull:`4388`) + By `Maximilian Roos `_ + + + +.. _whats-new.0.16.0: + +v0.16.0 (2020-07-11) +--------------------- + +This release adds `xarray.cov` & `xarray.corr` for covariance & correlation +respectively; the `idxmax` & `idxmin` methods, the `polyfit` method & +`xarray.polyval` for fitting polynomials, as well as a number of documentation +improvements, other features, and bug fixes. Many thanks to all 44 contributors +who contributed to this release: + +Akio Taniguchi, Andrew Williams, Aurélien Ponte, Benoit Bovy, Dave Cole, David +Brochart, Deepak Cherian, Elliott Sales de Andrade, Etienne Combrisson, Hossein +Madadi, Huite, Joe Hamman, Kai Mühlbauer, Keisuke Fujii, Maik Riechert, Marek +Jacob, Mathias Hauser, Matthieu Ancellin, Maximilian Roos, Noah D Brenowitz, +Oriol Abril, Pascal Bourgault, Phillip Butcher, Prajjwal Nijhara, Ray Bell, Ryan +Abernathey, Ryan May, Spencer Clark, Spencer Hill, Srijan Saurav, Stephan Hoyer, +Taher Chegini, Todd, Tom Nicholas, Yohai Bar Sinai, Yunus Sevinchan, +arabidopsis, aurghs, clausmichele, dmey, johnomotani, keewis, raphael dussin, +risebell + +Breaking changes +~~~~~~~~~~~~~~~~ + +- Minimum supported versions for the following packages have changed: ``dask >=2.9``, + ``distributed>=2.9``. + By `Deepak Cherian `_ +- ``groupby`` operations will restore coord dimension order. Pass ``restore_coord_dims=False`` + to revert to previous behavior. +- :meth:`DataArray.transpose` will now transpose coordinates by default. + Pass ``transpose_coords=False`` to revert to previous behaviour. + By `Maximilian Roos `_ +- Alternate draw styles for :py:meth:`plot.step` must be passed using the + ``drawstyle`` (or ``ds``) keyword argument, instead of the ``linestyle`` (or + ``ls``) keyword argument, in line with the `upstream change in Matplotlib + `_. + (:pull:`3274`) + By `Elliott Sales de Andrade `_ +- The old ``auto_combine`` function has now been removed in + favour of the :py:func:`combine_by_coords` and + :py:func:`combine_nested` functions. This also means that + the default behaviour of :py:func:`open_mfdataset` has changed to use + ``combine='by_coords'`` as the default argument value. (:issue:`2616`, :pull:`3926`) + By `Tom Nicholas `_. +- The ``DataArray`` and ``Variable`` HTML reprs now expand the data section by + default (:issue:`4176`) + By `Stephan Hoyer `_. + +New Features +~~~~~~~~~~~~ +- :py:meth:`DataArray.argmin` and :py:meth:`DataArray.argmax` now support + sequences of 'dim' arguments, and if a sequence is passed return a dict + (which can be passed to :py:meth:`DataArray.isel` to get the value of the minimum) of + the indices for each dimension of the minimum or maximum of a DataArray. + (:pull:`3936`) + By `John Omotani `_, thanks to `Keisuke Fujii + `_ for work in :pull:`1469`. +- Added :py:func:`xarray.cov` and :py:func:`xarray.corr` (:issue:`3784`, :pull:`3550`, :pull:`4089`). + By `Andrew Williams `_ and `Robin Beer `_. +- Implement :py:meth:`DataArray.idxmax`, :py:meth:`DataArray.idxmin`, + :py:meth:`Dataset.idxmax`, :py:meth:`Dataset.idxmin`. (:issue:`60`, :pull:`3871`) + By `Todd Jennings `_ +- Added :py:meth:`DataArray.polyfit` and :py:func:`xarray.polyval` for fitting + polynomials. (:issue:`3349`, :pull:`3733`, :pull:`4099`) + By `Pascal Bourgault `_. +- Added :py:meth:`xarray.infer_freq` for extending frequency inferring to CFTime indexes and data (:pull:`4033`). + By `Pascal Bourgault `_. +- ``chunks='auto'`` is now supported in the ``chunks`` argument of + :py:meth:`Dataset.chunk`. (:issue:`4055`) + By `Andrew Williams `_ +- Control over attributes of result in :py:func:`merge`, :py:func:`concat`, + :py:func:`combine_by_coords` and :py:func:`combine_nested` using + combine_attrs keyword argument. (:issue:`3865`, :pull:`3877`) + By `John Omotani `_ +- `missing_dims` argument to :py:meth:`Dataset.isel`, + :py:meth:`DataArray.isel` and :py:meth:`Variable.isel` to allow replacing + the exception when a dimension passed to ``isel`` is not present with a + warning, or just ignore the dimension. (:issue:`3866`, :pull:`3923`) + By `John Omotani `_ +- Support dask handling for :py:meth:`DataArray.idxmax`, :py:meth:`DataArray.idxmin`, + :py:meth:`Dataset.idxmax`, :py:meth:`Dataset.idxmin`. (:pull:`3922`, :pull:`4135`) + By `Kai Mühlbauer `_ and `Pascal Bourgault `_. +- More support for unit aware arrays with pint (:pull:`3643`, :pull:`3975`, :pull:`4163`) + By `Justus Magin `_. +- Support overriding existing variables in ``to_zarr()`` with ``mode='a'`` even + without ``append_dim``, as long as dimension sizes do not change. + By `Stephan Hoyer `_. +- Allow plotting of boolean arrays. (:pull:`3766`) + By `Marek Jacob `_ +- Enable using MultiIndex levels as coordinates in 1D and 2D plots (:issue:`3927`). + By `Mathias Hauser `_. +- A ``days_in_month`` accessor for :py:class:`xarray.CFTimeIndex`, analogous to + the ``days_in_month`` accessor for a :py:class:`pandas.DatetimeIndex`, which + returns the days in the month each datetime in the index. Now days in month + weights for both standard and non-standard calendars can be obtained using + the :py:class:`~core.accessor_dt.DatetimeAccessor` (:pull:`3935`). This + feature requires cftime version 1.1.0 or greater. By + `Spencer Clark `_. +- For the netCDF3 backend, added dtype coercions for unsigned integer types. + (:issue:`4014`, :pull:`4018`) + By `Yunus Sevinchan `_ +- :py:meth:`map_blocks` now accepts a ``template`` kwarg. This allows use cases + where the result of a computation could not be inferred automatically. + By `Deepak Cherian `_ +- :py:meth:`map_blocks` can now handle dask-backed xarray objects in ``args``. (:pull:`3818`) + By `Deepak Cherian `_ +- Add keyword ``decode_timedelta`` to :py:func:`xarray.open_dataset`, + (:py:func:`xarray.open_dataarray`, :py:func:`xarray.open_dataarray`, + :py:func:`xarray.decode_cf`) that allows to disable/enable the decoding of timedeltas + independently of time decoding (:issue:`1621`) + `Aureliana Barghini `_ + +Enhancements +~~~~~~~~~~~~ +- Performance improvement of :py:meth:`DataArray.interp` and :py:func:`Dataset.interp` + We performs independant interpolation sequentially rather than interpolating in + one large multidimensional space. (:issue:`2223`) + By `Keisuke Fujii `_. +- :py:meth:`DataArray.interp` now support interpolations over chunked dimensions (:pull:`4155`). By `Alexandre Poux `_. +- Major performance improvement for :py:meth:`Dataset.from_dataframe` when the + dataframe has a MultiIndex (:pull:`4184`). + By `Stephan Hoyer `_. + - :py:meth:`DataArray.reset_index` and :py:meth:`Dataset.reset_index` now keep + coordinate attributes (:pull:`4103`). By `Oriol Abril `_. +- Axes kwargs such as ``facecolor`` can now be passed to :py:meth:`DataArray.plot` in ``subplot_kws``. + This works for both single axes plots and FacetGrid plots. + By `Raphael Dussin `_. +- Array items with long string reprs are now limited to a + reasonable width (:pull:`3900`) + By `Maximilian Roos `_ +- Large arrays whose numpy reprs would have greater than 40 lines are now + limited to a reasonable length. + (:pull:`3905`) + By `Maximilian Roos `_ + +Bug fixes +~~~~~~~~~ +- Fix errors combining attrs in :py:func:`open_mfdataset` (:issue:`4009`, :pull:`4173`) + By `John Omotani `_ +- If groupby receives a ``DataArray`` with name=None, assign a default name (:issue:`158`) + By `Phil Butcher `_. +- Support dark mode in VS code (:issue:`4024`) + By `Keisuke Fujii `_. +- Fix bug when converting multiindexed Pandas objects to sparse xarray objects. (:issue:`4019`) + By `Deepak Cherian `_. +- ``ValueError`` is raised when ``fill_value`` is not a scalar in :py:meth:`full_like`. (:issue:`3977`) + By `Huite Bootsma `_. +- Fix wrong order in converting a ``pd.Series`` with a MultiIndex to ``DataArray``. + (:issue:`3951`, :issue:`4186`) + By `Keisuke Fujii `_ and `Stephan Hoyer `_. +- Fix renaming of coords when one or more stacked coords is not in + sorted order during stack+groupby+apply operations. (:issue:`3287`, + :pull:`3906`) By `Spencer Hill `_ +- Fix a regression where deleting a coordinate from a copied :py:class:`DataArray` + can affect the original :py:class:`DataArray`. (:issue:`3899`, :pull:`3871`) + By `Todd Jennings `_ +- Fix :py:class:`~xarray.plot.FacetGrid` plots with a single contour. (:issue:`3569`, :pull:`3915`). + By `Deepak Cherian `_ +- Use divergent colormap if ``levels`` spans 0. (:issue:`3524`) + By `Deepak Cherian `_ +- Fix :py:class:`~xarray.plot.FacetGrid` when ``vmin == vmax``. (:issue:`3734`) + By `Deepak Cherian `_ +- Fix plotting when ``levels`` is a scalar and ``norm`` is provided. (:issue:`3735`) + By `Deepak Cherian `_ +- Fix bug where plotting line plots with 2D coordinates depended on dimension + order. (:issue:`3933`) + By `Tom Nicholas `_. +- Fix ``RasterioDeprecationWarning`` when using a ``vrt`` in ``open_rasterio``. (:issue:`3964`) + By `Taher Chegini `_. +- Fix ``AttributeError`` on displaying a :py:class:`Variable` + in a notebook context. (:issue:`3972`, :pull:`3973`) + By `Ian Castleden `_. +- Fix bug causing :py:meth:`DataArray.interpolate_na` to always drop attributes, + and added `keep_attrs` argument. (:issue:`3968`) + By `Tom Nicholas `_. +- Fix bug in time parsing failing to fall back to cftime. This was causing time + variables with a time unit of `'msecs'` to fail to parse. (:pull:`3998`) + By `Ryan May `_. +- Fix weighted mean when passing boolean weights (:issue:`4074`). + By `Mathias Hauser `_. +- Fix html repr in untrusted notebooks: fallback to plain text repr. (:pull:`4053`) + By `Benoit Bovy `_. +- Fix :py:meth:`DataArray.to_unstacked_dataset` for single-dimension variables. (:issue:`4049`) + By `Deepak Cherian `_ +- Fix :py:func:`open_rasterio` for ``WarpedVRT`` with specified ``src_crs``. (:pull:`4104`) + By `Dave Cole `_. + +Documentation +~~~~~~~~~~~~~ +- update the docstring of :py:meth:`DataArray.assign_coords` : clarify how to + add a new coordinate to an existing dimension and illustrative example + (:issue:`3952`, :pull:`3958`) By + `Etienne Combrisson `_. +- update the docstring of :py:meth:`Dataset.diff` and + :py:meth:`DataArray.diff` so it does document the ``dim`` + parameter as required. (:issue:`1040`, :pull:`3909`) + By `Justus Magin `_. +- Updated :doc:`Calculating Seasonal Averages from Timeseries of Monthly Means + ` example notebook to take advantage of the new + ``days_in_month`` accessor for :py:class:`xarray.CFTimeIndex` + (:pull:`3935`). By `Spencer Clark `_. +- Updated the list of current core developers. (:issue:`3892`) + By `Tom Nicholas `_. +- Add example for multi-dimensional extrapolation and note different behavior + of ``kwargs`` in :py:meth:`Dataset.interp` and :py:meth:`DataArray.interp` + for 1-d and n-d interpolation (:pull:`3956`). + By `Matthias Riße `_. +- Apply ``black`` to all the code in the documentation (:pull:`4012`) + By `Justus Magin `_. +- Narrative documentation now describes :py:meth:`map_blocks`: :ref:`dask.automatic-parallelization`. + By `Deepak Cherian `_. +- Document ``.plot``, ``.dt``, ``.str`` accessors the way they are called. (:issue:`3625`, :pull:`3988`) + By `Justus Magin `_. +- Add documentation for the parameters and return values of :py:meth:`DataArray.sel`. + By `Justus Magin `_. + +Internal Changes +~~~~~~~~~~~~~~~~ +- Raise more informative error messages for chunk size conflicts when writing to zarr files. + By `Deepak Cherian `_. +- Run the ``isort`` pre-commit hook only on python source files + and update the ``flake8`` version. (:issue:`3750`, :pull:`3711`) + By `Justus Magin `_. +- Add `blackdoc `_ to the list of + checkers for development. (:pull:`4177`) + By `Justus Magin `_. +- Add a CI job that runs the tests with every optional dependency + except ``dask``. (:issue:`3794`, :pull:`3919`) + By `Justus Magin `_. +- Use ``async`` / ``await`` for the asynchronous distributed + tests. (:issue:`3987`, :pull:`3989`) + By `Justus Magin `_. +- Various internal code clean-ups (:pull:`4026`, :pull:`4038`). + By `Prajjwal Nijhara `_. + +.. _whats-new.0.15.1: + +v0.15.1 (23 Mar 2020) +--------------------- + +This release brings many new features such as :py:meth:`Dataset.weighted` methods for weighted array +reductions, a new jupyter repr by default, and the start of units integration with pint. There's also +the usual batch of usability improvements, documentation additions, and bug fixes. + +Breaking changes +~~~~~~~~~~~~~~~~ + +- Raise an error when assigning to the ``.values`` or ``.data`` attribute of + dimension coordinates i.e. ``IndexVariable`` objects. This has been broken since + v0.12.0. Please use :py:meth:`DataArray.assign_coords` or :py:meth:`Dataset.assign_coords` + instead. (:issue:`3470`, :pull:`3862`) + By `Deepak Cherian `_ + +New Features +~~~~~~~~~~~~ + +- Weighted array reductions are now supported via the new :py:meth:`DataArray.weighted` + and :py:meth:`Dataset.weighted` methods. See :ref:`comput.weighted`. (:issue:`422`, :pull:`2922`). + By `Mathias Hauser `_. +- The new jupyter notebook repr (``Dataset._repr_html_`` and + ``DataArray._repr_html_``) (introduced in 0.14.1) is now on by default. To + disable, use ``xarray.set_options(display_style="text")``. + By `Julia Signell `_. +- Added support for :py:class:`pandas.DatetimeIndex`-style rounding of + ``cftime.datetime`` objects directly via a :py:class:`CFTimeIndex` or via the + :py:class:`~core.accessor_dt.DatetimeAccessor`. + By `Spencer Clark `_ +- Support new h5netcdf backend keyword `phony_dims` (available from h5netcdf + v0.8.0 for :py:class:`~xarray.backends.H5NetCDFStore`. + By `Kai Mühlbauer `_. +- Add partial support for unit aware arrays with pint. (:pull:`3706`, :pull:`3611`) + By `Justus Magin `_. +- :py:meth:`Dataset.groupby` and :py:meth:`DataArray.groupby` now raise a + `TypeError` on multiple string arguments. Receiving multiple string arguments + often means a user is attempting to pass multiple dimensions as separate + arguments and should instead pass a single list of dimensions. + (:pull:`3802`) + By `Maximilian Roos `_ +- :py:func:`map_blocks` can now apply functions that add new unindexed dimensions. + By `Deepak Cherian `_ +- An ellipsis (``...``) is now supported in the ``dims`` argument of + :py:meth:`Dataset.stack` and :py:meth:`DataArray.stack`, meaning all + unlisted dimensions, similar to its meaning in :py:meth:`DataArray.transpose`. + (:pull:`3826`) + By `Maximilian Roos `_ +- :py:meth:`Dataset.where` and :py:meth:`DataArray.where` accept a lambda as a + first argument, which is then called on the input; replicating pandas' behavior. + By `Maximilian Roos `_. +- ``skipna`` is available in :py:meth:`Dataset.quantile`, :py:meth:`DataArray.quantile`, + :py:meth:`core.groupby.DatasetGroupBy.quantile`, :py:meth:`core.groupby.DataArrayGroupBy.quantile` + (:issue:`3843`, :pull:`3844`) + By `Aaron Spring `_. +- Add a diff summary for `testing.assert_allclose`. (:issue:`3617`, :pull:`3847`) + By `Justus Magin `_. + +Bug fixes +~~~~~~~~~ + +- Fix :py:meth:`Dataset.interp` when indexing array shares coordinates with the + indexed variable (:issue:`3252`). + By `David Huard `_. +- Fix recombination of groups in :py:meth:`Dataset.groupby` and + :py:meth:`DataArray.groupby` when performing an operation that changes the + size of the groups along the grouped dimension. By `Eric Jansen + `_. +- Fix use of multi-index with categorical values (:issue:`3674`). + By `Matthieu Ancellin `_. +- Fix alignment with ``join="override"`` when some dimensions are unindexed. (:issue:`3681`). + By `Deepak Cherian `_. +- Fix :py:meth:`Dataset.swap_dims` and :py:meth:`DataArray.swap_dims` producing + index with name reflecting the previous dimension name instead of the new one + (:issue:`3748`, :pull:`3752`). By `Joseph K Aicher + `_. +- Use ``dask_array_type`` instead of ``dask_array.Array`` for type + checking. (:issue:`3779`, :pull:`3787`) + By `Justus Magin `_. +- :py:func:`concat` can now handle coordinate variables only present in one of + the objects to be concatenated when ``coords="different"``. + By `Deepak Cherian `_. +- xarray now respects the over, under and bad colors if set on a provided colormap. + (:issue:`3590`, :pull:`3601`) + By `johnomotani `_. +- ``coarsen`` and ``rolling`` now respect ``xr.set_options(keep_attrs=True)`` + to preserve attributes. :py:meth:`Dataset.coarsen` accepts a keyword + argument ``keep_attrs`` to change this setting. (:issue:`3376`, + :pull:`3801`) By `Andrew Thomas `_. +- Delete associated indexes when deleting coordinate variables. (:issue:`3746`). + By `Deepak Cherian `_. +- Fix :py:meth:`Dataset.to_zarr` when using ``append_dim`` and ``group`` + simultaneously. (:issue:`3170`). By `Matthias Meyer `_. +- Fix html repr on :py:class:`Dataset` with non-string keys (:pull:`3807`). + By `Maximilian Roos `_. + +Documentation +~~~~~~~~~~~~~ + +- Fix documentation of :py:class:`DataArray` removing the deprecated mention + that when omitted, `dims` are inferred from a `coords`-dict. (:pull:`3821`) + By `Sander van Rijn `_. +- Improve the :py:func:`where` docstring. + By `Maximilian Roos `_ +- Update the installation instructions: only explicitly list recommended dependencies + (:issue:`3756`). + By `Mathias Hauser `_. + +Internal Changes +~~~~~~~~~~~~~~~~ + +- Remove the internal ``import_seaborn`` function which handled the deprecation of + the ``seaborn.apionly`` entry point (:issue:`3747`). + By `Mathias Hauser `_. +- Don't test pint integration in combination with datetime objects. (:issue:`3778`, :pull:`3788`) + By `Justus Magin `_. +- Change test_open_mfdataset_list_attr to only run with dask installed + (:issue:`3777`, :pull:`3780`). + By `Bruno Pagani `_. +- Preserve the ability to index with ``method="nearest"`` with a + :py:class:`CFTimeIndex` with pandas versions greater than 1.0.1 + (:issue:`3751`). By `Spencer Clark `_. +- Greater flexibility and improved test coverage of subtracting various types + of objects from a :py:class:`CFTimeIndex`. By `Spencer Clark + `_. +- Update Azure CI MacOS image, given pending removal. + By `Maximilian Roos `_ +- Remove xfails for scipy 1.0.1 for tests that append to netCDF files (:pull:`3805`). + By `Mathias Hauser `_. +- Remove conversion to ``pandas.Panel``, given its removal in pandas + in favor of xarray's objects. + By `Maximilian Roos `_ + +.. _whats-new.0.15.0: + + +v0.15.0 (30 Jan 2020) +--------------------- + +This release brings many improvements to xarray's documentation: our examples are now binderized notebooks (`click here `_) +and we have new example notebooks from our SciPy 2019 sprint (many thanks to our contributors!). + +This release also features many API improvements such as a new +:py:class:`~core.accessor_dt.TimedeltaAccessor` and support for :py:class:`CFTimeIndex` in +:py:meth:`~DataArray.interpolate_na`); as well as many bug fixes. + +Breaking changes +~~~~~~~~~~~~~~~~ +- Bumped minimum tested versions for dependencies: + + - numpy 1.15 + - pandas 0.25 + - dask 2.2 + - distributed 2.2 + - scipy 1.3 + +- Remove ``compat`` and ``encoding`` kwargs from ``DataArray``, which + have been deprecated since 0.12. (:pull:`3650`). + Instead, specify the ``encoding`` kwarg when writing to disk or set + the :py:attr:`DataArray.encoding` attribute directly. + By `Maximilian Roos `_. +- :py:func:`xarray.dot`, :py:meth:`DataArray.dot`, and the ``@`` operator now + use ``align="inner"`` (except when ``xarray.set_options(arithmetic_join="exact")``; + :issue:`3694`) by `Mathias Hauser `_. + +New Features +~~~~~~~~~~~~ +- Implement :py:meth:`DataArray.pad` and :py:meth:`Dataset.pad`. (:issue:`2605`, :pull:`3596`). + By `Mark Boer `_. +- :py:meth:`DataArray.sel` and :py:meth:`Dataset.sel` now support :py:class:`pandas.CategoricalIndex`. (:issue:`3669`) + By `Keisuke Fujii `_. +- Support using an existing, opened h5netcdf ``File`` with + :py:class:`~xarray.backends.H5NetCDFStore`. This permits creating an + :py:class:`~xarray.Dataset` from a h5netcdf ``File`` that has been opened + using other means (:issue:`3618`). + By `Kai Mühlbauer `_. +- Implement ``median`` and ``nanmedian`` for dask arrays. This works by rechunking + to a single chunk along all reduction axes. (:issue:`2999`). + By `Deepak Cherian `_. +- :py:func:`~xarray.concat` now preserves attributes from the first Variable. + (:issue:`2575`, :issue:`2060`, :issue:`1614`) + By `Deepak Cherian `_. +- :py:meth:`Dataset.quantile`, :py:meth:`DataArray.quantile` and ``GroupBy.quantile`` + now work with dask Variables. + By `Deepak Cherian `_. +- Added the ``count`` reduction method to both :py:class:`~core.rolling.DatasetCoarsen` + and :py:class:`~core.rolling.DataArrayCoarsen` objects. (:pull:`3500`) + By `Deepak Cherian `_ +- Add ``meta`` kwarg to :py:func:`~xarray.apply_ufunc`; + this is passed on to :py:func:`dask.array.blockwise`. (:pull:`3660`) + By `Deepak Cherian `_. +- Add ``attrs_file`` option in :py:func:`~xarray.open_mfdataset` to choose the + source file for global attributes in a multi-file dataset (:issue:`2382`, + :pull:`3498`). By `Julien Seguinot `_. +- :py:meth:`Dataset.swap_dims` and :py:meth:`DataArray.swap_dims` + now allow swapping to dimension names that don't exist yet. (:pull:`3636`) + By `Justus Magin `_. +- Extend :py:class:`~core.accessor_dt.DatetimeAccessor` properties + and support ``.dt`` accessor for timedeltas + via :py:class:`~core.accessor_dt.TimedeltaAccessor` (:pull:`3612`) + By `Anderson Banihirwe `_. +- Improvements to interpolating along time axes (:issue:`3641`, :pull:`3631`). + By `David Huard `_. + + - Support :py:class:`CFTimeIndex` in :py:meth:`DataArray.interpolate_na` + - define 1970-01-01 as the default offset for the interpolation index for both + :py:class:`pandas.DatetimeIndex` and :py:class:`CFTimeIndex`, + - use microseconds in the conversion from timedelta objects to floats to avoid + overflow errors. + +Bug fixes +~~~~~~~~~ +- Applying a user-defined function that adds new dimensions using :py:func:`apply_ufunc` + and ``vectorize=True`` now works with ``dask > 2.0``. (:issue:`3574`, :pull:`3660`). + By `Deepak Cherian `_. +- Fix :py:meth:`~xarray.combine_by_coords` to allow for combining incomplete + hypercubes of Datasets (:issue:`3648`). By `Ian Bolliger + `_. +- Fix :py:func:`~xarray.combine_by_coords` when combining cftime coordinates + which span long time intervals (:issue:`3535`). By `Spencer Clark + `_. +- Fix plotting with transposed 2D non-dimensional coordinates. (:issue:`3138`, :pull:`3441`) + By `Deepak Cherian `_. +- :py:meth:`plot.FacetGrid.set_titles` can now replace existing row titles of a + :py:class:`~xarray.plot.FacetGrid` plot. In addition :py:class:`~xarray.plot.FacetGrid` gained + two new attributes: :py:attr:`~xarray.plot.FacetGrid.col_labels` and + :py:attr:`~xarray.plot.FacetGrid.row_labels` contain :py:class:`matplotlib.text.Text` handles for both column and + row labels. These can be used to manually change the labels. + By `Deepak Cherian `_. +- Fix issue with Dask-backed datasets raising a ``KeyError`` on some computations involving :py:func:`map_blocks` (:pull:`3598`). + By `Tom Augspurger `_. +- Ensure :py:meth:`Dataset.quantile`, :py:meth:`DataArray.quantile` issue the correct error + when ``q`` is out of bounds (:issue:`3634`) by `Mathias Hauser `_. +- Fix regression in xarray 0.14.1 that prevented encoding times with certain + ``dtype``, ``_FillValue``, and ``missing_value`` encodings (:issue:`3624`). + By `Spencer Clark `_ +- Raise an error when trying to use :py:meth:`Dataset.rename_dims` to + rename to an existing name (:issue:`3438`, :pull:`3645`) + By `Justus Magin `_. +- :py:meth:`Dataset.rename`, :py:meth:`DataArray.rename` now check for conflicts with + MultiIndex level names. +- :py:meth:`Dataset.merge` no longer fails when passed a :py:class:`DataArray` instead of a :py:class:`Dataset`. + By `Tom Nicholas `_. +- Fix a regression in :py:meth:`Dataset.drop`: allow passing any + iterable when dropping variables (:issue:`3552`, :pull:`3693`) + By `Justus Magin `_. +- Fixed errors emitted by ``mypy --strict`` in modules that import xarray. + (:issue:`3695`) by `Guido Imperiale `_. +- Allow plotting of binned coordinates on the y axis in :py:meth:`plot.line` + and :py:meth:`plot.step` plots (:issue:`3571`, + :pull:`3685`) by `Julien Seguinot `_. +- setuptools is now marked as a dependency of xarray + (:pull:`3628`) by `Richard Höchenberger `_. + +Documentation +~~~~~~~~~~~~~ +- Switch doc examples to use `nbsphinx `_ and replace + ``sphinx_gallery`` scripts with Jupyter notebooks. (:pull:`3105`, :pull:`3106`, :pull:`3121`) + By `Ryan Abernathey `_. +- Added :doc:`example notebook ` demonstrating use of xarray with + Regional Ocean Modeling System (ROMS) ocean hydrodynamic model output. (:pull:`3116`) + By `Robert Hetland `_. +- Added :doc:`example notebook ` demonstrating the visualization of + ERA5 GRIB data. (:pull:`3199`) + By `Zach Bruick `_ and + `Stephan Siemen `_. +- Added examples for :py:meth:`DataArray.quantile`, :py:meth:`Dataset.quantile` and + ``GroupBy.quantile``. (:pull:`3576`) + By `Justus Magin `_. +- Add new :doc:`example notebook ` example notebook demonstrating + vectorization of a 1D function using :py:func:`apply_ufunc` , dask and numba. + By `Deepak Cherian `_. +- Added example for :py:func:`~xarray.map_blocks`. (:pull:`3667`) + By `Riley X. Brady `_. + +Internal Changes +~~~~~~~~~~~~~~~~ +- Make sure dask names change when rechunking by different chunk sizes. Conversely, make sure they + stay the same when rechunking by the same chunk size. (:issue:`3350`) + By `Deepak Cherian `_. +- 2x to 5x speed boost (on small arrays) for :py:meth:`Dataset.isel`, + :py:meth:`DataArray.isel`, and :py:meth:`DataArray.__getitem__` when indexing by int, + slice, list of int, scalar ndarray, or 1-dimensional ndarray. + (:pull:`3533`) by `Guido Imperiale `_. +- Removed internal method ``Dataset._from_vars_and_coord_names``, + which was dominated by ``Dataset._construct_direct``. (:pull:`3565`) + By `Maximilian Roos `_. +- Replaced versioneer with setuptools-scm. Moved contents of setup.py to setup.cfg. + Removed pytest-runner from setup.py, as per deprecation notice on the pytest-runner + project. (:pull:`3714`) by `Guido Imperiale `_. +- Use of isort is now enforced by CI. + (:pull:`3721`) by `Guido Imperiale `_ + + +.. _whats-new.0.14.1: + +v0.14.1 (19 Nov 2019) +--------------------- + +Breaking changes +~~~~~~~~~~~~~~~~ + +- Broken compatibility with ``cftime < 1.0.3`` . By `Deepak Cherian `_. + + .. warning:: + + cftime version 1.0.4 is broken + (`cftime/126 `_); + please use version 1.0.4.2 instead. + +- All leftover support for dates from non-standard calendars through ``netcdftime``, the + module included in versions of netCDF4 prior to 1.4 that eventually became the + `cftime `_ package, has been removed in favor of relying solely on + the standalone ``cftime`` package (:pull:`3450`). + By `Spencer Clark `_. + +New Features +~~~~~~~~~~~~ +- Added the ``sparse`` option to :py:meth:`~xarray.DataArray.unstack`, + :py:meth:`~xarray.Dataset.unstack`, :py:meth:`~xarray.DataArray.reindex`, + :py:meth:`~xarray.Dataset.reindex` (:issue:`3518`). + By `Keisuke Fujii `_. +- Added the ``fill_value`` option to :py:meth:`DataArray.unstack` and + :py:meth:`Dataset.unstack` (:issue:`3518`, :pull:`3541`). + By `Keisuke Fujii `_. +- Added the ``max_gap`` kwarg to :py:meth:`~xarray.DataArray.interpolate_na` and + :py:meth:`~xarray.Dataset.interpolate_na`. This controls the maximum size of the data + gap that will be filled by interpolation. By `Deepak Cherian `_. +- Added :py:meth:`Dataset.drop_sel` & :py:meth:`DataArray.drop_sel` for dropping labels. + :py:meth:`Dataset.drop_vars` & :py:meth:`DataArray.drop_vars` have been added for + dropping variables (including coordinates). The existing :py:meth:`Dataset.drop` & + :py:meth:`DataArray.drop` methods remain as a backward compatible + option for dropping either labels or variables, but using the more specific methods is encouraged. + (:pull:`3475`) + By `Maximilian Roos `_ +- Added :py:meth:`Dataset.map` & ``GroupBy.map`` & ``Resample.map`` for + mapping / applying a function over each item in the collection, reflecting the widely used + and least surprising name for this operation. + The existing ``apply`` methods remain for backward compatibility, though using the ``map`` + methods is encouraged. + (:pull:`3459`) + By `Maximilian Roos `_ +- :py:meth:`Dataset.transpose` and :py:meth:`DataArray.transpose` now support an ellipsis (``...``) + to represent all 'other' dimensions. For example, to move one dimension to the front, + use ``.transpose('x', ...)``. (:pull:`3421`) + By `Maximilian Roos `_ +- Changed ``xr.ALL_DIMS`` to equal python's ``Ellipsis`` (``...``), and changed internal usages to use + ``...`` directly. As before, you can use this to instruct a ``groupby`` operation + to reduce over all dimensions. While we have no plans to remove ``xr.ALL_DIMS``, we suggest + using ``...``. (:pull:`3418`) + By `Maximilian Roos `_ +- :py:func:`xarray.dot`, and :py:meth:`DataArray.dot` now support the + ``dims=...`` option to sum over the union of dimensions of all input arrays + (:issue:`3423`) by `Mathias Hauser `_. +- Added new ``Dataset._repr_html_`` and ``DataArray._repr_html_`` to improve + representation of objects in Jupyter. By default this feature is turned off + for now. Enable it with ``xarray.set_options(display_style="html")``. + (:pull:`3425`) by `Benoit Bovy `_ and + `Julia Signell `_. +- Implement `dask deterministic hashing + `_ + for xarray objects. Note that xarray objects with a dask.array backend already used + deterministic hashing in previous releases; this change implements it when whole + xarray objects are embedded in a dask graph, e.g. when :py:meth:`DataArray.map_blocks` is + invoked. (:issue:`3378`, :pull:`3446`, :pull:`3515`) + By `Deepak Cherian `_ and + `Guido Imperiale `_. +- Add the documented-but-missing :py:meth:`~core.groupby.DatasetGroupBy.quantile`. +- xarray now respects the ``DataArray.encoding["coordinates"]`` attribute when writing to disk. + See :ref:`io.coordinates` for more. (:issue:`3351`, :pull:`3487`) + By `Deepak Cherian `_. +- Add the documented-but-missing :py:meth:`~core.groupby.DatasetGroupBy.quantile`. + (:issue:`3525`, :pull:`3527`). By `Justus Magin `_. + +Bug fixes +~~~~~~~~~ +- Ensure an index of type ``CFTimeIndex`` is not converted to a ``DatetimeIndex`` when + calling :py:meth:`Dataset.rename`, :py:meth:`Dataset.rename_dims` and :py:meth:`Dataset.rename_vars`. + By `Mathias Hauser `_. (:issue:`3522`). +- Fix a bug in :py:meth:`DataArray.set_index` in case that an existing dimension becomes a level + variable of MultiIndex. (:pull:`3520`). By `Keisuke Fujii `_. +- Harmonize ``_FillValue``, ``missing_value`` during encoding and decoding steps. (:pull:`3502`) + By `Anderson Banihirwe `_. +- Fix regression introduced in v0.14.0 that would cause a crash if dask is installed + but cloudpickle isn't (:issue:`3401`) by `Rhys Doyle `_ +- Fix grouping over variables with NaNs. (:issue:`2383`, :pull:`3406`). + By `Deepak Cherian `_. +- Make alignment and concatenation significantly more efficient by using dask names to compare dask + objects prior to comparing values after computation. This change makes it more convenient to carry + around large non-dimensional coordinate variables backed by dask arrays. Existing workarounds involving + ``reset_coords(drop=True)`` should now be unnecessary in most cases. + (:issue:`3068`, :issue:`3311`, :issue:`3454`, :pull:`3453`). + By `Deepak Cherian `_. +- Add support for cftime>=1.0.4. By `Anderson Banihirwe `_. +- Rolling reduction operations no longer compute dask arrays by default. (:issue:`3161`). + In addition, the ``allow_lazy`` kwarg to ``reduce`` is deprecated. + By `Deepak Cherian `_. +- Fix ``GroupBy.reduce`` when reducing over multiple dimensions. + (:issue:`3402`). By `Deepak Cherian `_ +- Allow appending datetime and bool data variables to zarr stores. + (:issue:`3480`). By `Akihiro Matsukawa `_. +- Add support for numpy >=1.18 (); bugfix mean() on datetime64 arrays on dask backend + (:issue:`3409`, :pull:`3537`). By `Guido Imperiale `_. +- Add support for pandas >=0.26 (:issue:`3440`). + By `Deepak Cherian `_. +- Add support for pseudonetcdf >=3.1 (:pull:`3485`). + By `Barron Henderson `_. + +Documentation +~~~~~~~~~~~~~ +- Fix leap year condition in `monthly means example `_. + By `Mickaël Lalande `_. +- Fix the documentation of :py:meth:`DataArray.resample` and + :py:meth:`Dataset.resample`, explicitly stating that a + datetime-like dimension is required. (:pull:`3400`) + By `Justus Magin `_. +- Update the :ref:`terminology` page to address multidimensional coordinates. (:pull:`3410`) + By `Jon Thielen `_. +- Fix the documentation of :py:meth:`Dataset.integrate` and + :py:meth:`DataArray.integrate` and add an example to + :py:meth:`Dataset.integrate`. (:pull:`3469`) + By `Justus Magin `_. + +Internal Changes +~~~~~~~~~~~~~~~~ + +- Added integration tests against `pint `_. + (:pull:`3238`, :pull:`3447`, :pull:`3493`, :pull:`3508`) + by `Justus Magin `_. + + .. note:: + + At the moment of writing, these tests *as well as the ability to use pint in general* + require `a highly experimental version of pint + `_ (install with + ``pip install git+https://github.com/andrewgsavage/pint.git@refs/pull/6/head)``. + Even with it, interaction with non-numpy array libraries, e.g. dask or sparse, is broken. + +- Use Python 3.6 idioms throughout the codebase. (:pull:`3419`) + By `Maximilian Roos `_ + +- Run basic CI tests on Python 3.8. (:pull:`3477`) + By `Maximilian Roos `_ + +- Enable type checking on default sentinel values (:pull:`3472`) + By `Maximilian Roos `_ + +- Add ``Variable._replace`` for simpler replacing of a subset of attributes (:pull:`3472`) + By `Maximilian Roos `_ + +.. _whats-new.0.14.0: + +v0.14.0 (14 Oct 2019) +--------------------- + +Breaking changes +~~~~~~~~~~~~~~~~ +- This release introduces a rolling policy for minimum dependency versions: + :ref:`mindeps_policy`. + + Several minimum versions have been increased: + + ============ ================== ==== + Package Old New + ============ ================== ==== + Python 3.5.3 3.6 + numpy 1.12 1.14 + pandas 0.19.2 0.24 + dask 0.16 (tested: 2.4) 1.2 + bottleneck 1.1 (tested: 1.2) 1.2 + matplotlib 1.5 (tested: 3.1) 3.1 + ============ ================== ==== + + Obsolete patch versions (x.y.Z) are not tested anymore. + The oldest supported versions of all optional dependencies are now covered by + automated tests (before, only the very latest versions were tested). + + (:issue:`3222`, :issue:`3293`, :issue:`3340`, :issue:`3346`, :issue:`3358`). + By `Guido Imperiale `_. + +- Dropped the ``drop=False`` optional parameter from :py:meth:`Variable.isel`. + It was unused and doesn't make sense for a Variable. (:pull:`3375`). + By `Guido Imperiale `_. + +- Remove internal usage of :py:class:`collections.OrderedDict`. After dropping support for + Python <=3.5, most uses of ``OrderedDict`` in Xarray were no longer necessary. We + have removed the internal use of the ``OrderedDict`` in favor of Python's builtin + ``dict`` object which is now ordered itself. This change will be most obvious when + interacting with the ``attrs`` property on Dataset and DataArray objects. + (:issue:`3380`, :pull:`3389`). By `Joe Hamman `_. + +New functions/methods +~~~~~~~~~~~~~~~~~~~~~ + +- Added :py:func:`~xarray.map_blocks`, modeled after :py:func:`dask.array.map_blocks`. + Also added :py:meth:`Dataset.unify_chunks`, :py:meth:`DataArray.unify_chunks` and + :py:meth:`testing.assert_chunks_equal`. (:pull:`3276`). + By `Deepak Cherian `_ and + `Guido Imperiale `_. + +Enhancements +~~~~~~~~~~~~ + +- ``core.groupby.GroupBy`` enhancements. By `Deepak Cherian `_. + + - Added a repr (:pull:`3344`). Example:: + + >>> da.groupby("time.season") + DataArrayGroupBy, grouped over 'season' + 4 groups with labels 'DJF', 'JJA', 'MAM', 'SON' + + - Added a ``GroupBy.dims`` property that mirrors the dimensions + of each group (:issue:`3344`). + +- Speed up :py:meth:`Dataset.isel` up to 33% and :py:meth:`DataArray.isel` up to 25% for small + arrays (:issue:`2799`, :pull:`3375`). By + `Guido Imperiale `_. + +Bug fixes +~~~~~~~~~ +- Reintroduce support for :mod:`weakref` (broken in v0.13.0). Support has been + reinstated for :py:class:`~xarray.DataArray` and :py:class:`~xarray.Dataset` objects only. + Internal xarray objects remain unaddressable by weakref in order to save memory + (:issue:`3317`). By `Guido Imperiale `_. +- Line plots with the ``x`` or ``y`` argument set to a 1D non-dimensional coord + now plot the correct data for 2D DataArrays + (:issue:`3334`). By `Tom Nicholas `_. +- Make :py:func:`~xarray.concat` more robust when merging variables present in some datasets but + not others (:issue:`508`). By `Deepak Cherian `_. +- The default behaviour of reducing across all dimensions for + :py:class:`~xarray.core.groupby.DataArrayGroupBy` objects has now been properly removed + as was done for :py:class:`~xarray.core.groupby.DatasetGroupBy` in 0.13.0 (:issue:`3337`). + Use ``xarray.ALL_DIMS`` if you need to replicate previous behaviour. + Also raise nicer error message when no groups are created (:issue:`1764`). + By `Deepak Cherian `_. +- Fix error in concatenating unlabeled dimensions (:pull:`3362`). + By `Deepak Cherian `_. +- Warn if the ``dim`` kwarg is passed to rolling operations. This is redundant since a dimension is + specified when the :py:class:`~core.rolling.DatasetRolling` or :py:class:`~core.rolling.DataArrayRolling` object is created. + (:pull:`3362`). By `Deepak Cherian `_. + +Documentation +~~~~~~~~~~~~~ + +- Created a glossary of important xarray terms (:issue:`2410`, :pull:`3352`). + By `Gregory Gundersen `_. +- Created a "How do I..." section (:ref:`howdoi`) for solutions to common questions. (:pull:`3357`). + By `Deepak Cherian `_. +- Add examples for :py:meth:`Dataset.swap_dims` and :py:meth:`DataArray.swap_dims` + (pull:`3331`, pull:`3331`). By `Justus Magin `_. +- Add examples for :py:meth:`align`, :py:meth:`merge`, :py:meth:`combine_by_coords`, + :py:meth:`full_like`, :py:meth:`zeros_like`, :py:meth:`ones_like`, :py:meth:`Dataset.pipe`, + :py:meth:`Dataset.assign`, :py:meth:`Dataset.reindex`, :py:meth:`Dataset.fillna` (:pull:`3328`). + By `Anderson Banihirwe `_. +- Fixed documentation to clean up an unwanted file created in ``ipython`` example + (:pull:`3353`). By `Gregory Gundersen `_. + +.. _whats-new.0.13.0: + +v0.13.0 (17 Sep 2019) +--------------------- + +This release includes many exciting changes: wrapping of +`NEP18 `_ compliant +numpy-like arrays; new :py:meth:`~Dataset.plot.scatter` plotting method that can scatter +two ``DataArrays`` in a ``Dataset`` against each other; support for converting pandas +DataFrames to xarray objects that wrap ``pydata/sparse``; and more! + +Breaking changes +~~~~~~~~~~~~~~~~ + +- This release increases the minimum required Python version from 3.5.0 to 3.5.3 + (:issue:`3089`). By `Guido Imperiale `_. +- The ``isel_points`` and ``sel_points`` methods are removed, having been deprecated + since v0.10.0. These are redundant with the ``isel`` / ``sel`` methods. + See :ref:`vectorized_indexing` for the details + By `Maximilian Roos `_ +- The ``inplace`` kwarg for public methods now raises an error, having been deprecated + since v0.11.0. + By `Maximilian Roos `_ +- :py:func:`~xarray.concat` now requires the ``dim`` argument. Its ``indexers``, ``mode`` + and ``concat_over`` kwargs have now been removed. + By `Deepak Cherian `_ +- Passing a list of colors in ``cmap`` will now raise an error, having been deprecated since + v0.6.1. +- Most xarray objects now define ``__slots__``. This reduces overall RAM usage by ~22% + (not counting the underlying numpy buffers); on CPython 3.7/x64, a trivial DataArray + has gone down from 1.9kB to 1.5kB. + + Caveats: + + - Pickle streams produced by older versions of xarray can't be loaded using this + release, and vice versa. + - Any user code that was accessing the ``__dict__`` attribute of + xarray objects will break. The best practice to attach custom metadata to xarray + objects is to use the ``attrs`` dictionary. + - Any user code that defines custom subclasses of xarray classes must now explicitly + define ``__slots__`` itself. Subclasses that don't add any attributes must state so + by defining ``__slots__ = ()`` right after the class header. + Omitting ``__slots__`` will now cause a ``FutureWarning`` to be logged, and will raise an + error in a later release. + + (:issue:`3250`) by `Guido Imperiale `_. +- The default dimension for :py:meth:`Dataset.groupby`, :py:meth:`Dataset.resample`, + :py:meth:`DataArray.groupby` and :py:meth:`DataArray.resample` reductions is now the + grouping or resampling dimension. +- :py:meth:`DataArray.to_dataset` requires ``name`` to be passed as a kwarg (previously ambiguous + positional arguments were deprecated) +- Reindexing with variables of a different dimension now raise an error (previously deprecated) +- ``xarray.broadcast_array`` is removed (previously deprecated in favor of + :py:func:`~xarray.broadcast`) +- ``Variable.expand_dims`` is removed (previously deprecated in favor of + :py:meth:`Variable.set_dims`) + +New functions/methods +~~~~~~~~~~~~~~~~~~~~~ + +- xarray can now wrap around any + `NEP18 `_ compliant + numpy-like library (important: read notes about ``NUMPY_EXPERIMENTAL_ARRAY_FUNCTION`` in + the above link). Added explicit test coverage for + `sparse `_. (:issue:`3117`, :issue:`3202`). + This requires `sparse>=0.8.0`. By `Nezar Abdennur `_ + and `Guido Imperiale `_. + +- :py:meth:`~Dataset.from_dataframe` and :py:meth:`~DataArray.from_series` now + support ``sparse=True`` for converting pandas objects into xarray objects + wrapping sparse arrays. This is particularly useful with sparsely populated + hierarchical indexes. (:issue:`3206`) + By `Stephan Hoyer `_. + +- The xarray package is now discoverable by mypy (although typing hints coverage is not + complete yet). mypy type checking is now enforced by CI. Libraries that depend on + xarray and use mypy can now remove from their setup.cfg the lines:: + + [mypy-xarray] + ignore_missing_imports = True + + (:issue:`2877`, :issue:`3088`, :issue:`3090`, :issue:`3112`, :issue:`3117`, + :issue:`3207`) + By `Guido Imperiale `_ + and `Maximilian Roos `_. + +- Added :py:meth:`DataArray.broadcast_like` and :py:meth:`Dataset.broadcast_like`. + By `Deepak Cherian `_ and `David Mertz + `_. + +- Dataset plotting API for visualizing dependencies between two DataArrays! + Currently only :py:meth:`Dataset.plot.scatter` is implemented. + By `Yohai Bar Sinai `_ and `Deepak Cherian `_ + +- Added :py:meth:`DataArray.head`, :py:meth:`DataArray.tail` and :py:meth:`DataArray.thin`; + as well as :py:meth:`Dataset.head`, :py:meth:`Dataset.tail` and :py:meth:`Dataset.thin` methods. + (:issue:`319`) By `Gerardo Rivera `_. + +Enhancements +~~~~~~~~~~~~ + +- Multiple enhancements to :py:func:`~xarray.concat` and :py:func:`~xarray.open_mfdataset`. + By `Deepak Cherian `_ + + - Added ``compat='override'``. When merging, this option picks the variable from the first dataset + and skips all comparisons. + + - Added ``join='override'``. When aligning, this only checks that index sizes are equal among objects + and skips checking indexes for equality. + + - :py:func:`~xarray.concat` and :py:func:`~xarray.open_mfdataset` now support the ``join`` kwarg. + It is passed down to :py:func:`~xarray.align`. + + - :py:func:`~xarray.concat` now calls :py:func:`~xarray.merge` on variables that are not concatenated + (i.e. variables without ``concat_dim`` when ``data_vars`` or ``coords`` are ``"minimal"``). + :py:func:`~xarray.concat` passes its new ``compat`` kwarg down to :py:func:`~xarray.merge`. + (:issue:`2064`) + + Users can avoid a common bottleneck when using :py:func:`~xarray.open_mfdataset` on a large number of + files with variables that are known to be aligned and some of which need not be concatenated. + Slow equality comparisons can now be avoided, for e.g.:: + + data = xr.open_mfdataset(files, concat_dim='time', data_vars='minimal', + coords='minimal', compat='override', join='override') + +- In :py:meth:`~xarray.Dataset.to_zarr`, passing ``mode`` is not mandatory if + ``append_dim`` is set, as it will automatically be set to ``'a'`` internally. + By `David Brochart `_. + +- Added the ability to initialize an empty or full DataArray + with a single value. (:issue:`277`) + By `Gerardo Rivera `_. + +- :py:func:`~xarray.Dataset.to_netcdf()` now supports the ``invalid_netcdf`` kwarg when used + with ``engine="h5netcdf"``. It is passed to ``h5netcdf.File``. + By `Ulrich Herter `_. + +- ``xarray.Dataset.drop`` now supports keyword arguments; dropping index + labels by using both ``dim`` and ``labels`` or using a + :py:class:`~core.coordinates.DataArrayCoordinates` object are deprecated (:issue:`2910`). + By `Gregory Gundersen `_. + +- Added examples of :py:meth:`Dataset.set_index` and + :py:meth:`DataArray.set_index`, as well are more specific error messages + when the user passes invalid arguments (:issue:`3176`). + By `Gregory Gundersen `_. + +- :py:meth:`Dataset.filter_by_attrs` now filters the coordinates as well as the variables. + By `Spencer Jones `_. + +Bug fixes +~~~~~~~~~ + +- Improve "missing dimensions" error message for :py:func:`~xarray.apply_ufunc` + (:issue:`2078`). + By `Rick Russotto `_. +- :py:meth:`~xarray.DataArray.assign_coords` now supports dictionary arguments + (:issue:`3231`). + By `Gregory Gundersen `_. +- Fix regression introduced in v0.12.2 where ``copy(deep=True)`` would convert + unicode indices to dtype=object (:issue:`3094`). + By `Guido Imperiale `_. +- Improved error handling and documentation for `.expand_dims()` + read-only view. +- Fix tests for big-endian systems (:issue:`3125`). + By `Graham Inggs `_. +- XFAIL several tests which are expected to fail on ARM systems + due to a ``datetime`` issue in NumPy (:issue:`2334`). + By `Graham Inggs `_. +- Fix KeyError that arises when using .sel method with float values + different from coords float type (:issue:`3137`). + By `Hasan Ahmad `_. +- Fixed bug in ``combine_by_coords()`` causing a `ValueError` if the input had + an unused dimension with coordinates which were not monotonic (:issue:`3150`). + By `Tom Nicholas `_. +- Fixed crash when applying ``distributed.Client.compute()`` to a DataArray + (:issue:`3171`). By `Guido Imperiale `_. +- Better error message when using groupby on an empty DataArray (:issue:`3037`). + By `Hasan Ahmad `_. +- Fix error that arises when using open_mfdataset on a series of netcdf files + having differing values for a variable attribute of type list. (:issue:`3034`) + By `Hasan Ahmad `_. +- Prevent :py:meth:`~xarray.DataArray.argmax` and :py:meth:`~xarray.DataArray.argmin` from calling + dask compute (:issue:`3237`). By `Ulrich Herter `_. +- Plots in 2 dimensions (pcolormesh, contour) now allow to specify levels as numpy + array (:issue:`3284`). By `Mathias Hauser `_. +- Fixed bug in :meth:`DataArray.quantile` failing to keep attributes when + `keep_attrs` was True (:issue:`3304`). By `David Huard `_. + +Documentation +~~~~~~~~~~~~~ + +- Created a `PR checklist `_ + as a quick reference for tasks before creating a new PR + or pushing new commits. + By `Gregory Gundersen `_. + +- Fixed documentation to clean up unwanted files created in ``ipython`` examples + (:issue:`3227`). + By `Gregory Gundersen `_. + +.. _whats-new.0.12.3: + +v0.12.3 (10 July 2019) +---------------------- + +New functions/methods +~~~~~~~~~~~~~~~~~~~~~ + +- New methods :py:meth:`Dataset.to_stacked_array` and + :py:meth:`DataArray.to_unstacked_dataset` for reshaping Datasets of variables + with different dimensions + (:issue:`1317`). + This is useful for feeding data from xarray into machine learning models, + as described in :ref:`reshape.stacking_different`. + By `Noah Brenowitz `_. + +Enhancements +~~~~~~~~~~~~ + +- Support for renaming ``Dataset`` variables and dimensions independently + with :py:meth:`~Dataset.rename_vars` and :py:meth:`~Dataset.rename_dims` + (:issue:`3026`). + By `Julia Kent `_. + +- Add ``scales``, ``offsets``, ``units`` and ``descriptions`` + attributes to :py:class:`~xarray.DataArray` returned by + :py:func:`~xarray.open_rasterio`. (:issue:`3013`) + By `Erle Carrara `_. + +Bug fixes +~~~~~~~~~ + +- Resolved deprecation warnings from newer versions of matplotlib and dask. +- Compatibility fixes for the upcoming pandas 0.25 and NumPy 1.17 releases. + By `Stephan Hoyer `_. +- Fix summaries for multiindex coordinates (:issue:`3079`). + By `Jonas Hörsch `_. +- Fix HDF5 error that could arise when reading multiple groups from a file at + once (:issue:`2954`). + By `Stephan Hoyer `_. + +.. _whats-new.0.12.2: + +v0.12.2 (29 June 2019) +---------------------- + +New functions/methods +~~~~~~~~~~~~~~~~~~~~~ + +- Two new functions, :py:func:`~xarray.combine_nested` and + :py:func:`~xarray.combine_by_coords`, allow for combining datasets along any + number of dimensions, instead of the one-dimensional list of datasets + supported by :py:func:`~xarray.concat`. + + The new ``combine_nested`` will accept the datasets as a nested + list-of-lists, and combine by applying a series of concat and merge + operations. The new ``combine_by_coords`` instead uses the dimension + coordinates of datasets to order them. + + :py:func:`~xarray.open_mfdataset` can use either ``combine_nested`` or + ``combine_by_coords`` to combine datasets along multiple dimensions, by + specifying the argument ``combine='nested'`` or ``combine='by_coords'``. + + The older function ``auto_combine`` has been deprecated, + because its functionality has been subsumed by the new functions. + To avoid FutureWarnings switch to using ``combine_nested`` or + ``combine_by_coords``, (or set the ``combine`` argument in + ``open_mfdataset``). (:issue:`2159`) + By `Tom Nicholas `_. + +- :py:meth:`~xarray.DataArray.rolling_exp` and + :py:meth:`~xarray.Dataset.rolling_exp` added, similar to pandas' + ``pd.DataFrame.ewm`` method. Calling ``.mean`` on the resulting object + will return an exponentially weighted moving average. + By `Maximilian Roos `_. + +- New :py:func:`DataArray.str ` for string + related manipulations, based on ``pandas.Series.str``. + By `0x0L `_. + +- Added ``strftime`` method to ``.dt`` accessor, making it simpler to hand a + datetime ``DataArray`` to other code expecting formatted dates and times. + (:issue:`2090`). :py:meth:`~xarray.CFTimeIndex.strftime` is also now + available on :py:class:`CFTimeIndex`. + By `Alan Brammer `_ and + `Ryan May `_. + +- ``GroupBy.quantile`` is now a method of ``GroupBy`` + objects (:issue:`3018`). + By `David Huard `_. + +- Argument and return types are added to most methods on ``DataArray`` and + ``Dataset``, allowing static type checking both within xarray and external + libraries. Type checking with `mypy `_ is enabled in + CI (though not required yet). + By `Guido Imperiale `_ + and `Maximilian Roos `_. + +Enhancements to existing functionality +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Add ``keepdims`` argument for reduce operations (:issue:`2170`) + By `Scott Wales `_. +- Enable ``@`` operator for DataArray. This is equivalent to :py:meth:`DataArray.dot` + By `Maximilian Roos `_. +- Add ``fill_value`` argument for reindex, align, and merge operations + to enable custom fill values. (:issue:`2876`) + By `Zach Griffith `_. +- :py:meth:`DataArray.transpose` now accepts a keyword argument + ``transpose_coords`` which enables transposition of coordinates in the + same way as :py:meth:`Dataset.transpose`. :py:meth:`DataArray.groupby` + :py:meth:`DataArray.groupby_bins`, and :py:meth:`DataArray.resample` now + accept a keyword argument ``restore_coord_dims`` which keeps the order + of the dimensions of multi-dimensional coordinates intact (:issue:`1856`). + By `Peter Hausamann `_. +- Clean up Python 2 compatibility in code (:issue:`2950`) + By `Guido Imperiale `_. +- Better warning message when supplying invalid objects to ``xr.merge`` + (:issue:`2948`). By `Mathias Hauser `_. +- Add ``errors`` keyword argument to ``Dataset.drop`` and :py:meth:`Dataset.drop_dims` + that allows ignoring errors if a passed label or dimension is not in the dataset + (:issue:`2994`). + By `Andrew Ross `_. + +IO related enhancements +~~~~~~~~~~~~~~~~~~~~~~~ + +- Implement :py:func:`~xarray.load_dataset` and + :py:func:`~xarray.load_dataarray` as alternatives to + :py:func:`~xarray.open_dataset` and :py:func:`~xarray.open_dataarray` to + open, load into memory, and close files, returning the Dataset or DataArray. + These functions are helpful for avoiding file-lock errors when trying to + write to files opened using ``open_dataset()`` or ``open_dataarray()``. + (:issue:`2887`) + By `Dan Nowacki `_. +- It is now possible to extend existing :ref:`io.zarr` datasets, by using + ``mode='a'`` and the new ``append_dim`` argument in + :py:meth:`~xarray.Dataset.to_zarr`. + By `Jendrik Jördening `_, + `David Brochart `_, + `Ryan Abernathey `_ and + `Shikhar Goenka `_. +- ``xr.open_zarr`` now accepts manually specified chunks with the ``chunks=`` + parameter. ``auto_chunk=True`` is equivalent to ``chunks='auto'`` for + backwards compatibility. The ``overwrite_encoded_chunks`` parameter is + added to remove the original zarr chunk encoding. + By `Lily Wang `_. +- netCDF chunksizes are now only dropped when original_shape is different, + not when it isn't found. (:issue:`2207`) + By `Karel van de Plassche `_. +- Character arrays' character dimension name decoding and encoding handled by + ``var.encoding['char_dim_name']`` (:issue:`2895`) + By `James McCreight `_. +- open_rasterio() now supports rasterio.vrt.WarpedVRT with custom transform, + width and height (:issue:`2864`). + By `Julien Michel `_. + +Bug fixes +~~~~~~~~~ + +- Rolling operations on xarray objects containing dask arrays could silently + compute the incorrect result or use large amounts of memory (:issue:`2940`). + By `Stephan Hoyer `_. +- Don't set encoding attributes on bounds variables when writing to netCDF. + (:issue:`2921`) + By `Deepak Cherian `_. +- NetCDF4 output: variables with unlimited dimensions must be chunked (not + contiguous) on output. (:issue:`1849`) + By `James McCreight `_. +- indexing with an empty list creates an object with zero-length axis (:issue:`2882`) + By `Mayeul d'Avezac `_. +- Return correct count for scalar datetime64 arrays (:issue:`2770`) + By `Dan Nowacki `_. +- Fixed max, min exception when applied to a multiIndex (:issue:`2923`) + By `Ian Castleden `_ +- A deep copy deep-copies the coords (:issue:`1463`) + By `Martin Pletcher `_. +- Increased support for `missing_value` (:issue:`2871`) + By `Deepak Cherian `_. +- Removed usages of `pytest.config`, which is deprecated (:issue:`2988`) + By `Maximilian Roos `_. +- Fixed performance issues with cftime installed (:issue:`3000`) + By `0x0L `_. +- Replace incorrect usages of `message` in pytest assertions + with `match` (:issue:`3011`) + By `Maximilian Roos `_. +- Add explicit pytest markers, now required by pytest + (:issue:`3032`). + By `Maximilian Roos `_. +- Test suite fixes for newer versions of pytest (:issue:`3011`, :issue:`3032`). + By `Maximilian Roos `_ + and `Stephan Hoyer `_. + +.. _whats-new.0.12.1: + +v0.12.1 (4 April 2019) +---------------------- + +Enhancements +~~~~~~~~~~~~ + +- Allow ``expand_dims`` method to support inserting/broadcasting dimensions + with size > 1. (:issue:`2710`) + By `Martin Pletcher `_. + +Bug fixes +~~~~~~~~~ + +- Dataset.copy(deep=True) now creates a deep copy of the attrs (:issue:`2835`). + By `Andras Gefferth `_. +- Fix incorrect ``indexes`` resulting from various ``Dataset`` operations + (e.g., ``swap_dims``, ``isel``, ``reindex``, ``[]``) (:issue:`2842`, + :issue:`2856`). + By `Stephan Hoyer `_. + +.. _whats-new.0.12.0: + +v0.12.0 (15 March 2019) +----------------------- + +Highlights include: + +- Removed support for Python 2. This is the first version of xarray that is + Python 3 only! +- New :py:meth:`~xarray.DataArray.coarsen` and + :py:meth:`~xarray.DataArray.integrate` methods. See :ref:`comput.coarsen` + and :ref:`compute.using_coordinates` for details. +- Many improvements to cftime support. See below for details. + +Deprecations +~~~~~~~~~~~~ + +- The ``compat`` argument to ``Dataset`` and the ``encoding`` argument to + ``DataArray`` are deprecated and will be removed in a future release. + (:issue:`1188`) + By `Maximilian Roos `_. + +cftime related enhancements +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Resampling of standard and non-standard calendars indexed by + :py:class:`~xarray.CFTimeIndex` is now possible. (:issue:`2191`). + By `Jwen Fai Low `_ and + `Spencer Clark `_. + +- Taking the mean of arrays of :py:class:`cftime.datetime` objects, and + by extension, use of :py:meth:`~xarray.DataArray.coarsen` with + :py:class:`cftime.datetime` coordinates is now possible. By `Spencer Clark + `_. + +- Internal plotting now supports ``cftime.datetime`` objects as time series. + (:issue:`2164`) + By `Julius Busecke `_ and + `Spencer Clark `_. + +- :py:meth:`~xarray.cftime_range` now supports QuarterBegin and QuarterEnd offsets (:issue:`2663`). + By `Jwen Fai Low `_ + +- :py:meth:`~xarray.open_dataset` now accepts a ``use_cftime`` argument, which + can be used to require that ``cftime.datetime`` objects are always used, or + never used when decoding dates encoded with a standard calendar. This can be + used to ensure consistent date types are returned when using + :py:meth:`~xarray.open_mfdataset` (:issue:`1263`) and/or to silence + serialization warnings raised if dates from a standard calendar are found to + be outside the :py:class:`pandas.Timestamp`-valid range (:issue:`2754`). By + `Spencer Clark `_. + +- :py:meth:`pandas.Series.dropna` is now supported for a + :py:class:`pandas.Series` indexed by a :py:class:`~xarray.CFTimeIndex` + (:issue:`2688`). By `Spencer Clark `_. + +Other enhancements +~~~~~~~~~~~~~~~~~~ + +- Added ability to open netcdf4/hdf5 file-like objects with ``open_dataset``. + Requires (h5netcdf>0.7 and h5py>2.9.0). (:issue:`2781`) + By `Scott Henderson `_ +- Add ``data=False`` option to ``to_dict()`` methods. (:issue:`2656`) + By `Ryan Abernathey `_ +- :py:meth:`DataArray.coarsen` and + :py:meth:`Dataset.coarsen` are newly added. + See :ref:`comput.coarsen` for details. + (:issue:`2525`) + By `Keisuke Fujii `_. +- Upsampling an array via interpolation with resample is now dask-compatible, + as long as the array is not chunked along the resampling dimension. + By `Spencer Clark `_. +- :py:func:`xarray.testing.assert_equal` and + :py:func:`xarray.testing.assert_identical` now provide a more detailed + report showing what exactly differs between the two objects (dimensions / + coordinates / variables / attributes) (:issue:`1507`). + By `Benoit Bovy `_. +- Add ``tolerance`` option to ``resample()`` methods ``bfill``, ``pad``, + ``nearest``. (:issue:`2695`) + By `Hauke Schulz `_. +- :py:meth:`DataArray.integrate` and + :py:meth:`Dataset.integrate` are newly added. + See :ref:`compute.using_coordinates` for the detail. + (:issue:`1332`) + By `Keisuke Fujii `_. +- Added :py:meth:`~xarray.Dataset.drop_dims` (:issue:`1949`). + By `Kevin Squire `_. + +Bug fixes +~~~~~~~~~ + +- Silenced warnings that appear when using pandas 0.24. + By `Stephan Hoyer `_ +- Interpolating via resample now internally specifies ``bounds_error=False`` + as an argument to ``scipy.interpolate.interp1d``, allowing for interpolation + from higher frequencies to lower frequencies. Datapoints outside the bounds + of the original time coordinate are now filled with NaN (:issue:`2197`). By + `Spencer Clark `_. +- Line plots with the ``x`` argument set to a non-dimensional coord now plot + the correct data for 1D DataArrays. + (:issue:`2725`). By `Tom Nicholas `_. +- Subtracting a scalar ``cftime.datetime`` object from a + :py:class:`CFTimeIndex` now results in a :py:class:`pandas.TimedeltaIndex` + instead of raising a ``TypeError`` (:issue:`2671`). By `Spencer Clark + `_. +- backend_kwargs are no longer ignored when using open_dataset with pynio engine + (:issue:'2380') + By `Jonathan Joyce `_. +- Fix ``open_rasterio`` creating a WKT CRS instead of PROJ.4 with + ``rasterio`` 1.0.14+ (:issue:`2715`). + By `David Hoese `_. +- Masking data arrays with :py:meth:`xarray.DataArray.where` now returns an + array with the name of the original masked array (:issue:`2748` and :issue:`2457`). + By `Yohai Bar-Sinai `_. +- Fixed error when trying to reduce a DataArray using a function which does not + require an axis argument. (:issue:`2768`) + By `Tom Nicholas `_. +- Concatenating a sequence of :py:class:`~xarray.DataArray` with varying names + sets the name of the output array to ``None``, instead of the name of the + first input array. If the names are the same it sets the name to that, + instead to the name of the first DataArray in the list as it did before. + (:issue:`2775`). By `Tom Nicholas `_. + +- Per the `CF conventions section on calendars + `_, + specifying ``'standard'`` as the calendar type in + :py:meth:`~xarray.cftime_range` now correctly refers to the ``'gregorian'`` + calendar instead of the ``'proleptic_gregorian'`` calendar (:issue:`2761`). + +.. _whats-new.0.11.3: + +v0.11.3 (26 January 2019) +------------------------- + +Bug fixes +~~~~~~~~~ + +- Saving files with times encoded with reference dates with timezones + (e.g. '2000-01-01T00:00:00-05:00') no longer raises an error + (:issue:`2649`). By `Spencer Clark `_. +- Fixed performance regression with ``open_mfdataset`` (:issue:`2662`). + By `Tom Nicholas `_. +- Fixed supplying an explicit dimension in the ``concat_dim`` argument to + to ``open_mfdataset`` (:issue:`2647`). + By `Ben Root `_. + +.. _whats-new.0.11.2: + +v0.11.2 (2 January 2019) +------------------------ + +Removes inadvertently introduced setup dependency on pytest-runner +(:issue:`2641`). Otherwise, this release is exactly equivalent to 0.11.1. + +.. warning:: + + This is the last xarray release that will support Python 2.7. Future releases + will be Python 3 only, but older versions of xarray will always be available + for Python 2.7 users. For the more details, see: + + - `Xarray Github issue discussing dropping Python 2 `__ + - `Python 3 Statement `__ + - `Tips on porting to Python 3 `__ + +.. _whats-new.0.11.1: + +v0.11.1 (29 December 2018) +-------------------------- + +This minor release includes a number of enhancements and bug fixes, and two +(slightly) breaking changes. + +Breaking changes +~~~~~~~~~~~~~~~~ + +- Minimum rasterio version increased from 0.36 to 1.0 (for ``open_rasterio``) +- Time bounds variables are now also decoded according to CF conventions + (:issue:`2565`). The previous behavior was to decode them only if they + had specific time attributes, now these attributes are copied + automatically from the corresponding time coordinate. This might + break downstream code that was relying on these variables to be + brake downstream code that was relying on these variables to be + not decoded. + By `Fabien Maussion `_. + +Enhancements +~~~~~~~~~~~~ + +- Ability to read and write consolidated metadata in zarr stores (:issue:`2558`). + By `Ryan Abernathey `_. +- :py:class:`CFTimeIndex` uses slicing for string indexing when possible (like + :py:class:`pandas.DatetimeIndex`), which avoids unnecessary copies. + By `Stephan Hoyer `_ +- Enable passing ``rasterio.io.DatasetReader`` or ``rasterio.vrt.WarpedVRT`` to + ``open_rasterio`` instead of file path string. Allows for in-memory + reprojection, see (:issue:`2588`). + By `Scott Henderson `_. +- Like :py:class:`pandas.DatetimeIndex`, :py:class:`CFTimeIndex` now supports + "dayofyear" and "dayofweek" accessors (:issue:`2597`). Note this requires a + version of cftime greater than 1.0.2. By `Spencer Clark + `_. +- The option ``'warn_for_unclosed_files'`` (False by default) has been added to + allow users to enable a warning when files opened by xarray are deallocated + but were not explicitly closed. This is mostly useful for debugging; we + recommend enabling it in your test suites if you use xarray for IO. + By `Stephan Hoyer `_ +- Support Dask ``HighLevelGraphs`` by `Matthew Rocklin `_. +- :py:meth:`DataArray.resample` and :py:meth:`Dataset.resample` now supports the + ``loffset`` kwarg just like Pandas. + By `Deepak Cherian `_ +- Datasets are now guaranteed to have a ``'source'`` encoding, so the source + file name is always stored (:issue:`2550`). + By `Tom Nicholas `_. +- The ``apply`` methods for ``DatasetGroupBy``, ``DataArrayGroupBy``, + ``DatasetResample`` and ``DataArrayResample`` now support passing positional + arguments to the applied function as a tuple to the ``args`` argument. + By `Matti Eskelinen `_. +- 0d slices of ndarrays are now obtained directly through indexing, rather than + extracting and wrapping a scalar, avoiding unnecessary copying. By `Daniel + Wennberg `_. +- Added support for ``fill_value`` with + :py:meth:`~xarray.DataArray.shift` and :py:meth:`~xarray.Dataset.shift` + By `Maximilian Roos `_ + +Bug fixes +~~~~~~~~~ + +- Ensure files are automatically closed, if possible, when no longer referenced + by a Python variable (:issue:`2560`). + By `Stephan Hoyer `_ +- Fixed possible race conditions when reading/writing to disk in parallel + (:issue:`2595`). + By `Stephan Hoyer `_ +- Fix h5netcdf saving scalars with filters or chunks (:issue:`2563`). + By `Martin Raspaud `_. +- Fix parsing of ``_Unsigned`` attribute set by OPENDAP servers. (:issue:`2583`). + By `Deepak Cherian `_ +- Fix failure in time encoding when exporting to netCDF with versions of pandas + less than 0.21.1 (:issue:`2623`). By `Spencer Clark + `_. +- Fix MultiIndex selection to update label and level (:issue:`2619`). + By `Keisuke Fujii `_. + +.. _whats-new.0.11.0: + +v0.11.0 (7 November 2018) +------------------------- + +Breaking changes +~~~~~~~~~~~~~~~~ + +- Finished deprecations (changed behavior with this release): + + - ``Dataset.T`` has been removed as a shortcut for :py:meth:`Dataset.transpose`. + Call :py:meth:`Dataset.transpose` directly instead. + - Iterating over a ``Dataset`` now includes only data variables, not coordinates. + Similarily, calling ``len`` and ``bool`` on a ``Dataset`` now + includes only data variables. + - ``DataArray.__contains__`` (used by Python's ``in`` operator) now checks + array data, not coordinates. + - The old resample syntax from before xarray 0.10, e.g., + ``data.resample('1D', dim='time', how='mean')``, is no longer supported will + raise an error in most cases. You need to use the new resample syntax + instead, e.g., ``data.resample(time='1D').mean()`` or + ``data.resample({'time': '1D'}).mean()``. + + +- New deprecations (behavior will be changed in xarray 0.12): + + - Reduction of :py:meth:`DataArray.groupby` and :py:meth:`DataArray.resample` + without dimension argument will change in the next release. + Now we warn a FutureWarning. + By `Keisuke Fujii `_. + - The ``inplace`` kwarg of a number of `DataArray` and `Dataset` methods is being + deprecated and will be removed in the next release. + By `Deepak Cherian `_. + + +- Refactored storage backends: + + - Xarray's storage backends now automatically open and close files when + necessary, rather than requiring opening a file with ``autoclose=True``. A + global least-recently-used cache is used to store open files; the default + limit of 128 open files should suffice in most cases, but can be adjusted if + necessary with + ``xarray.set_options(file_cache_maxsize=...)``. The ``autoclose`` argument + to ``open_dataset`` and related functions has been deprecated and is now a + no-op. + + This change, along with an internal refactor of xarray's storage backends, + should significantly improve performance when reading and writing + netCDF files with Dask, especially when working with many files or using + Dask Distributed. By `Stephan Hoyer `_ + + +- Support for non-standard calendars used in climate science: + + - Xarray will now always use :py:class:`cftime.datetime` objects, rather + than by default trying to coerce them into ``np.datetime64[ns]`` objects. + A :py:class:`~xarray.CFTimeIndex` will be used for indexing along time + coordinates in these cases. + - A new method :py:meth:`~xarray.CFTimeIndex.to_datetimeindex` has been added + to aid in converting from a :py:class:`~xarray.CFTimeIndex` to a + :py:class:`pandas.DatetimeIndex` for the remaining use-cases where + using a :py:class:`~xarray.CFTimeIndex` is still a limitation (e.g. for + resample or plotting). + - Setting the ``enable_cftimeindex`` option is now a no-op and emits a + ``FutureWarning``. + +Enhancements +~~~~~~~~~~~~ + +- :py:meth:`xarray.DataArray.plot.line` can now accept multidimensional + coordinate variables as input. `hue` must be a dimension name in this case. + (:issue:`2407`) + By `Deepak Cherian `_. +- Added support for Python 3.7. (:issue:`2271`). + By `Joe Hamman `_. +- Added support for plotting data with `pandas.Interval` coordinates, such as those + created by :py:meth:`~xarray.DataArray.groupby_bins` + By `Maximilian Maahn `_. +- Added :py:meth:`~xarray.CFTimeIndex.shift` for shifting the values of a + CFTimeIndex by a specified frequency. (:issue:`2244`). + By `Spencer Clark `_. +- Added support for using ``cftime.datetime`` coordinates with + :py:meth:`~xarray.DataArray.differentiate`, + :py:meth:`~xarray.Dataset.differentiate`, + :py:meth:`~xarray.DataArray.interp`, and + :py:meth:`~xarray.Dataset.interp`. + By `Spencer Clark `_ +- There is now a global option to either always keep or always discard + dataset and dataarray attrs upon operations. The option is set with + ``xarray.set_options(keep_attrs=True)``, and the default is to use the old + behaviour. + By `Tom Nicholas `_. +- Added a new backend for the GRIB file format based on ECMWF *cfgrib* + python driver and *ecCodes* C-library. (:issue:`2475`) + By `Alessandro Amici `_, + sponsored by `ECMWF `_. +- Resample now supports a dictionary mapping from dimension to frequency as + its first argument, e.g., ``data.resample({'time': '1D'}).mean()``. This is + consistent with other xarray functions that accept either dictionaries or + keyword arguments. By `Stephan Hoyer `_. + +- The preferred way to access tutorial data is now to load it lazily with + :py:meth:`xarray.tutorial.open_dataset`. + :py:meth:`xarray.tutorial.load_dataset` calls `Dataset.load()` prior + to returning (and is now deprecated). This was changed in order to facilitate + using tutorial datasets with dask. + By `Joe Hamman `_. +- ``DataArray`` can now use ``xr.set_option(keep_attrs=True)`` and retain attributes in binary operations, + such as (``+, -, * ,/``). Default behaviour is unchanged (*Attributes will be dismissed*). By `Michael Blaschek `_ + +Bug fixes +~~~~~~~~~ + +- ``FacetGrid`` now properly uses the ``cbar_kwargs`` keyword argument. + (:issue:`1504`, :issue:`1717`) + By `Deepak Cherian `_. +- Addition and subtraction operators used with a CFTimeIndex now preserve the + index's type. (:issue:`2244`). + By `Spencer Clark `_. +- We now properly handle arrays of ``datetime.datetime`` and ``datetime.timedelta`` + provided as coordinates. (:issue:`2512`) + By `Deepak Cherian `_. +- ``xarray.DataArray.roll`` correctly handles multidimensional arrays. + (:issue:`2445`) + By `Keisuke Fujii `_. +- ``xarray.plot()`` now properly accepts a ``norm`` argument and does not override + the norm's ``vmin`` and ``vmax``. (:issue:`2381`) + By `Deepak Cherian `_. +- ``xarray.DataArray.std()`` now correctly accepts ``ddof`` keyword argument. + (:issue:`2240`) + By `Keisuke Fujii `_. +- Restore matplotlib's default of plotting dashed negative contours when + a single color is passed to ``DataArray.contour()`` e.g. ``colors='k'``. + By `Deepak Cherian `_. + + +- Fix a bug that caused some indexing operations on arrays opened with + ``open_rasterio`` to error (:issue:`2454`). + By `Stephan Hoyer `_. + +- Subtracting one CFTimeIndex from another now returns a + ``pandas.TimedeltaIndex``, analogous to the behavior for DatetimeIndexes + (:issue:`2484`). By `Spencer Clark `_. +- Adding a TimedeltaIndex to, or subtracting a TimedeltaIndex from a + CFTimeIndex is now allowed (:issue:`2484`). + By `Spencer Clark `_. +- Avoid use of Dask's deprecated ``get=`` parameter in tests + by `Matthew Rocklin `_. +- An ``OverflowError`` is now accurately raised and caught during the + encoding process if a reference date is used that is so distant that + the dates must be encoded using cftime rather than NumPy (:issue:`2272`). + By `Spencer Clark `_. + +- Chunked datasets can now roundtrip to Zarr storage continually + with `to_zarr` and ``open_zarr`` (:issue:`2300`). + By `Lily Wang `_. + +.. _whats-new.0.10.9: + +v0.10.9 (21 September 2018) +--------------------------- + +This minor release contains a number of backwards compatible enhancements. + +Announcements of note: + +- Xarray is now a NumFOCUS fiscally sponsored project! Read + `the anouncement `_ + for more details. +- We have a new :doc:`roadmap` that outlines our future development plans. + +- ``Dataset.apply`` now properly documents the way `func` is called. + By `Matti Eskelinen `_. + +Enhancements +~~~~~~~~~~~~ + +- :py:meth:`~xarray.DataArray.differentiate` and + :py:meth:`~xarray.Dataset.differentiate` are newly added. + (:issue:`1332`) + By `Keisuke Fujii `_. + +- Default colormap for sequential and divergent data can now be set via + :py:func:`~xarray.set_options()` + (:issue:`2394`) + By `Julius Busecke `_. + +- min_count option is newly supported in :py:meth:`~xarray.DataArray.sum`, + :py:meth:`~xarray.DataArray.prod` and :py:meth:`~xarray.Dataset.sum`, and + :py:meth:`~xarray.Dataset.prod`. + (:issue:`2230`) + By `Keisuke Fujii `_. + +- :py:func:`~plot.plot()` now accepts the kwargs + ``xscale, yscale, xlim, ylim, xticks, yticks`` just like Pandas. Also ``xincrease=False, yincrease=False`` now use matplotlib's axis inverting methods instead of setting limits. + By `Deepak Cherian `_. (:issue:`2224`) + +- DataArray coordinates and Dataset coordinates and data variables are + now displayed as `a b ... y z` rather than `a b c d ...`. + (:issue:`1186`) + By `Seth P `_. +- A new CFTimeIndex-enabled :py:func:`cftime_range` function for use in + generating dates from standard or non-standard calendars. By `Spencer Clark + `_. + +- When interpolating over a ``datetime64`` axis, you can now provide a datetime string instead of a ``datetime64`` object. E.g. ``da.interp(time='1991-02-01')`` + (:issue:`2284`) + By `Deepak Cherian `_. + +- A clear error message is now displayed if a ``set`` or ``dict`` is passed in place of an array + (:issue:`2331`) + By `Maximilian Roos `_. + +- Applying ``unstack`` to a large DataArray or Dataset is now much faster if the MultiIndex has not been modified after stacking the indices. + (:issue:`1560`) + By `Maximilian Maahn `_. + +- You can now control whether or not to offset the coordinates when using + the ``roll`` method and the current behavior, coordinates rolled by default, + raises a deprecation warning unless explicitly setting the keyword argument. + (:issue:`1875`) + By `Andrew Huang `_. + +- You can now call ``unstack`` without arguments to unstack every MultiIndex in a DataArray or Dataset. + By `Julia Signell `_. + +- Added the ability to pass a data kwarg to ``copy`` to create a new object with the + same metadata as the original object but using new values. + By `Julia Signell `_. + +Bug fixes +~~~~~~~~~ + +- ``xarray.plot.imshow()`` correctly uses the ``origin`` argument. + (:issue:`2379`) + By `Deepak Cherian `_. + +- Fixed ``DataArray.to_iris()`` failure while creating ``DimCoord`` by + falling back to creating ``AuxCoord``. Fixed dependency on ``var_name`` + attribute being set. + (:issue:`2201`) + By `Thomas Voigt `_. +- Fixed a bug in ``zarr`` backend which prevented use with datasets with + invalid chunk size encoding after reading from an existing store + (:issue:`2278`). + By `Joe Hamman `_. + +- Tests can be run in parallel with pytest-xdist + By `Tony Tung `_. + +- Follow up the renamings in dask; from dask.ghost to dask.overlap + By `Keisuke Fujii `_. + +- Now raises a ValueError when there is a conflict between dimension names and + level names of MultiIndex. (:issue:`2299`) + By `Keisuke Fujii `_. + +- Follow up the renamings in dask; from dask.ghost to dask.overlap + By `Keisuke Fujii `_. + +- Now :py:func:`~xarray.apply_ufunc` raises a ValueError when the size of + ``input_core_dims`` is inconsistent with the number of arguments. + (:issue:`2341`) + By `Keisuke Fujii `_. + +- Fixed ``Dataset.filter_by_attrs()`` behavior not matching ``netCDF4.Dataset.get_variables_by_attributes()``. + When more than one ``key=value`` is passed into ``Dataset.filter_by_attrs()`` it will now return a Dataset with variables which pass + all the filters. + (:issue:`2315`) + By `Andrew Barna `_. + +.. _whats-new.0.10.8: + +v0.10.8 (18 July 2018) +---------------------- + +Breaking changes +~~~~~~~~~~~~~~~~ + +- Xarray no longer supports python 3.4. Additionally, the minimum supported + versions of the following dependencies has been updated and/or clarified: + + - Pandas: 0.18 -> 0.19 + - NumPy: 1.11 -> 1.12 + - Dask: 0.9 -> 0.16 + - Matplotlib: unspecified -> 1.5 + + (:issue:`2204`). By `Joe Hamman `_. + +Enhancements +~~~~~~~~~~~~ + +- :py:meth:`~xarray.DataArray.interp_like` and + :py:meth:`~xarray.Dataset.interp_like` methods are newly added. + (:issue:`2218`) + By `Keisuke Fujii `_. + +- Added support for curvilinear and unstructured generic grids + to :py:meth:`~xarray.DataArray.to_cdms2` and + :py:meth:`~xarray.DataArray.from_cdms2` (:issue:`2262`). + By `Stephane Raynaud `_. + +Bug fixes +~~~~~~~~~ + +- Fixed a bug in ``zarr`` backend which prevented use with datasets with + incomplete chunks in multiple dimensions (:issue:`2225`). + By `Joe Hamman `_. + +- Fixed a bug in :py:meth:`~Dataset.to_netcdf` which prevented writing + datasets when the arrays had different chunk sizes (:issue:`2254`). + By `Mike Neish `_. + +- Fixed masking during the conversion to cdms2 objects by + :py:meth:`~xarray.DataArray.to_cdms2` (:issue:`2262`). + By `Stephane Raynaud `_. + +- Fixed a bug in 2D plots which incorrectly raised an error when 2D coordinates + weren't monotonic (:issue:`2250`). + By `Fabien Maussion `_. + +- Fixed warning raised in :py:meth:`~Dataset.to_netcdf` due to deprecation of + `effective_get` in dask (:issue:`2238`). + By `Joe Hamman `_. + +.. _whats-new.0.10.7: + +v0.10.7 (7 June 2018) +--------------------- + +Enhancements +~~~~~~~~~~~~ + +- Plot labels now make use of metadata that follow CF conventions + (:issue:`2135`). + By `Deepak Cherian `_ and `Ryan Abernathey `_. + +- Line plots now support facetting with ``row`` and ``col`` arguments + (:issue:`2107`). + By `Yohai Bar Sinai `_. + +- :py:meth:`~xarray.DataArray.interp` and :py:meth:`~xarray.Dataset.interp` + methods are newly added. + See :ref:`interp` for the detail. + (:issue:`2079`) + By `Keisuke Fujii `_. + +Bug fixes +~~~~~~~~~ + +- Fixed a bug in ``rasterio`` backend which prevented use with ``distributed``. + The ``rasterio`` backend now returns pickleable objects (:issue:`2021`). + By `Joe Hamman `_. + +.. _whats-new.0.10.6: + +v0.10.6 (31 May 2018) +--------------------- + +The minor release includes a number of bug-fixes and backwards compatible +enhancements. + +Enhancements +~~~~~~~~~~~~ + +- New PseudoNetCDF backend for many Atmospheric data formats including + GEOS-Chem, CAMx, NOAA arlpacked bit and many others. See + :ref:`io.PseudoNetCDF` for more details. + By `Barron Henderson `_. + +- The :py:class:`Dataset` constructor now aligns :py:class:`DataArray` + arguments in ``data_vars`` to indexes set explicitly in ``coords``, + where previously an error would be raised. + (:issue:`674`) + By `Maximilian Roos `_. + +- :py:meth:`~DataArray.sel`, :py:meth:`~DataArray.isel` & :py:meth:`~DataArray.reindex`, + (and their :py:class:`Dataset` counterparts) now support supplying a ``dict`` + as a first argument, as an alternative to the existing approach + of supplying `kwargs`. This allows for more robust behavior + of dimension names which conflict with other keyword names, or are + not strings. + By `Maximilian Roos `_. + +- :py:meth:`~DataArray.rename` now supports supplying ``**kwargs``, as an + alternative to the existing approach of supplying a ``dict`` as the + first argument. + By `Maximilian Roos `_. + +- :py:meth:`~DataArray.cumsum` and :py:meth:`~DataArray.cumprod` now support + aggregation over multiple dimensions at the same time. This is the default + behavior when dimensions are not specified (previously this raised an error). + By `Stephan Hoyer `_ + +- :py:meth:`DataArray.dot` and :py:func:`dot` are partly supported with older + dask<0.17.4. (related to :issue:`2203`) + By `Keisuke Fujii `_. + +- Xarray now uses `Versioneer `__ + to manage its version strings. (:issue:`1300`). + By `Joe Hamman `_. + +Bug fixes +~~~~~~~~~ + +- Fixed a regression in 0.10.4, where explicitly specifying ``dtype='S1'`` or + ``dtype=str`` in ``encoding`` with ``to_netcdf()`` raised an error + (:issue:`2149`). + `Stephan Hoyer `_ + +- :py:func:`apply_ufunc` now directly validates output variables + (:issue:`1931`). + By `Stephan Hoyer `_. + +- Fixed a bug where ``to_netcdf(..., unlimited_dims='bar')`` yielded NetCDF + files with spurious 0-length dimensions (i.e. ``b``, ``a``, and ``r``) + (:issue:`2134`). + By `Joe Hamman `_. + +- Removed spurious warnings with ``Dataset.update(Dataset)`` (:issue:`2161`) + and ``array.equals(array)`` when ``array`` contains ``NaT`` (:issue:`2162`). + By `Stephan Hoyer `_. + +- Aggregations with :py:meth:`Dataset.reduce` (including ``mean``, ``sum``, + etc) no longer drop unrelated coordinates (:issue:`1470`). Also fixed a + bug where non-scalar data-variables that did not include the aggregation + dimension were improperly skipped. + By `Stephan Hoyer `_ + +- Fix :meth:`~DataArray.stack` with non-unique coordinates on pandas 0.23 + (:issue:`2160`). + By `Stephan Hoyer `_ + +- Selecting data indexed by a length-1 ``CFTimeIndex`` with a slice of strings + now behaves as it does when using a length-1 ``DatetimeIndex`` (i.e. it no + longer falsely returns an empty array when the slice includes the value in + the index) (:issue:`2165`). + By `Spencer Clark `_. + +- Fix ``DataArray.groupby().reduce()`` mutating coordinates on the input array + when grouping over dimension coordinates with duplicated entries + (:issue:`2153`). + By `Stephan Hoyer `_ + +- Fix ``Dataset.to_netcdf()`` cannot create group with ``engine="h5netcdf"`` + (:issue:`2177`). + By `Stephan Hoyer `_ + +.. _whats-new.0.10.4: + +v0.10.4 (16 May 2018) +---------------------- + +The minor release includes a number of bug-fixes and backwards compatible +enhancements. A highlight is ``CFTimeIndex``, which offers support for +non-standard calendars used in climate modeling. + +Documentation +~~~~~~~~~~~~~ + +- New FAQ entry, :ref:`ecosystem`. + By `Deepak Cherian `_. +- :ref:`assigning_values` now includes examples on how to select and assign + values to a :py:class:`~xarray.DataArray` with ``.loc``. + By `Chiara Lepore `_. + +Enhancements +~~~~~~~~~~~~ + +- Add an option for using a ``CFTimeIndex`` for indexing times with + non-standard calendars and/or outside the Timestamp-valid range; this index + enables a subset of the functionality of a standard + ``pandas.DatetimeIndex``. + See :ref:`CFTimeIndex` for full details. + (:issue:`789`, :issue:`1084`, :issue:`1252`) + By `Spencer Clark `_ with help from + `Stephan Hoyer `_. +- Allow for serialization of ``cftime.datetime`` objects (:issue:`789`, + :issue:`1084`, :issue:`2008`, :issue:`1252`) using the standalone ``cftime`` + library. + By `Spencer Clark `_. +- Support writing lists of strings as netCDF attributes (:issue:`2044`). + By `Dan Nowacki `_. +- :py:meth:`~xarray.Dataset.to_netcdf` with ``engine='h5netcdf'`` now accepts h5py + encoding settings ``compression`` and ``compression_opts``, along with the + NetCDF4-Python style settings ``gzip=True`` and ``complevel``. + This allows using any compression plugin installed in hdf5, e.g. LZF + (:issue:`1536`). By `Guido Imperiale `_. +- :py:meth:`~xarray.dot` on dask-backed data will now call :func:`dask.array.einsum`. + This greatly boosts speed and allows chunking on the core dims. + The function now requires dask >= 0.17.3 to work on dask-backed data + (:issue:`2074`). By `Guido Imperiale `_. +- ``plot.line()`` learned new kwargs: ``xincrease``, ``yincrease`` that change + the direction of the respective axes. + By `Deepak Cherian `_. + +- Added the ``parallel`` option to :py:func:`open_mfdataset`. This option uses + ``dask.delayed`` to parallelize the open and preprocessing steps within + ``open_mfdataset``. This is expected to provide performance improvements when + opening many files, particularly when used in conjunction with dask's + multiprocessing or distributed schedulers (:issue:`1981`). + By `Joe Hamman `_. + +- New ``compute`` option in :py:meth:`~xarray.Dataset.to_netcdf`, + :py:meth:`~xarray.Dataset.to_zarr`, and :py:func:`~xarray.save_mfdataset` to + allow for the lazy computation of netCDF and zarr stores. This feature is + currently only supported by the netCDF4 and zarr backends. (:issue:`1784`). + By `Joe Hamman `_. + + +Bug fixes +~~~~~~~~~ + +- ``ValueError`` is raised when coordinates with the wrong size are assigned to + a :py:class:`DataArray`. (:issue:`2112`) + By `Keisuke Fujii `_. +- Fixed a bug in :py:meth:`~xarray.DataArray.rolling` with bottleneck. Also, + fixed a bug in rolling an integer dask array. (:issue:`2113`) + By `Keisuke Fujii `_. +- Fixed a bug where `keep_attrs=True` flag was neglected if + :py:func:`apply_ufunc` was used with :py:class:`Variable`. (:issue:`2114`) + By `Keisuke Fujii `_. +- When assigning a :py:class:`DataArray` to :py:class:`Dataset`, any conflicted + non-dimensional coordinates of the DataArray are now dropped. + (:issue:`2068`) + By `Keisuke Fujii `_. +- Better error handling in ``open_mfdataset`` (:issue:`2077`). + By `Stephan Hoyer `_. +- ``plot.line()`` does not call ``autofmt_xdate()`` anymore. Instead it changes + the rotation and horizontal alignment of labels without removing the x-axes of + any other subplots in the figure (if any). + By `Deepak Cherian `_. +- Colorbar limits are now determined by excluding ±Infs too. + By `Deepak Cherian `_. + By `Joe Hamman `_. +- Fixed ``to_iris`` to maintain lazy dask array after conversion (:issue:`2046`). + By `Alex Hilson `_ and `Stephan Hoyer `_. + +.. _whats-new.0.10.3: + +v0.10.3 (13 April 2018) +------------------------ + +The minor release includes a number of bug-fixes and backwards compatible enhancements. + +Enhancements +~~~~~~~~~~~~ + +- :py:meth:`~xarray.DataArray.isin` and :py:meth:`~xarray.Dataset.isin` methods, + which test each value in the array for whether it is contained in the + supplied list, returning a bool array. See :ref:`selecting values with isin` + for full details. Similar to the ``np.isin`` function. + By `Maximilian Roos `_. +- Some speed improvement to construct :py:class:`~xarray.core.rolling.DataArrayRolling` + object (:issue:`1993`) + By `Keisuke Fujii `_. +- Handle variables with different values for ``missing_value`` and + ``_FillValue`` by masking values for both attributes; previously this + resulted in a ``ValueError``. (:issue:`2016`) + By `Ryan May `_. + +Bug fixes +~~~~~~~~~ + +- Fixed ``decode_cf`` function to operate lazily on dask arrays + (:issue:`1372`). By `Ryan Abernathey `_. +- Fixed labeled indexing with slice bounds given by xarray objects with + datetime64 or timedelta64 dtypes (:issue:`1240`). + By `Stephan Hoyer `_. +- Attempting to convert an xarray.Dataset into a numpy array now raises an + informative error message. + By `Stephan Hoyer `_. +- Fixed a bug in decode_cf_datetime where ``int32`` arrays weren't parsed + correctly (:issue:`2002`). + By `Fabien Maussion `_. +- When calling `xr.auto_combine()` or `xr.open_mfdataset()` with a `concat_dim`, + the resulting dataset will have that one-element dimension (it was + silently dropped, previously) (:issue:`1988`). + By `Ben Root `_. + +.. _whats-new.0.10.2: + +v0.10.2 (13 March 2018) +----------------------- + +The minor release includes a number of bug-fixes and enhancements, along with +one possibly **backwards incompatible change**. + +Backwards incompatible changes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- The addition of ``__array_ufunc__`` for xarray objects (see below) means that + NumPy `ufunc methods`_ (e.g., ``np.add.reduce``) that previously worked on + ``xarray.DataArray`` objects by converting them into NumPy arrays will now + raise ``NotImplementedError`` instead. In all cases, the work-around is + simple: convert your objects explicitly into NumPy arrays before calling the + ufunc (e.g., with ``.values``). + +.. _ufunc methods: https://docs.scipy.org/doc/numpy/reference/ufuncs.html#methods + +Enhancements +~~~~~~~~~~~~ + +- Added :py:func:`~xarray.dot`, equivalent to :py:func:`numpy.einsum`. + Also, :py:func:`~xarray.DataArray.dot` now supports ``dims`` option, + which specifies the dimensions to sum over. + (:issue:`1951`) + By `Keisuke Fujii `_. + +- Support for writing xarray datasets to netCDF files (netcdf4 backend only) + when using the `dask.distributed `_ + scheduler (:issue:`1464`). + By `Joe Hamman `_. + +- Support lazy vectorized-indexing. After this change, flexible indexing such + as orthogonal/vectorized indexing, becomes possible for all the backend + arrays. Also, lazy ``transpose`` is now also supported. (:issue:`1897`) + By `Keisuke Fujii `_. + +- Implemented NumPy's ``__array_ufunc__`` protocol for all xarray objects + (:issue:`1617`). This enables using NumPy ufuncs directly on + ``xarray.Dataset`` objects with recent versions of NumPy (v1.13 and newer): + .. ipython:: python - :suppress: - - import numpy as np - import pandas as pd - import xarray as xray - import xarray - import xarray as xr - - np.random.seed(123456) - - - .. _whats-new.0.19.1: - - v0.19.1 (unreleased) - --------------------- - - New Features - ~~~~~~~~~~~~ - - - Breaking changes - ~~~~~~~~~~~~~~~~ - - - Deprecations - ~~~~~~~~~~~~ - - - Bug fixes - ~~~~~~~~~ - - - Documentation - ~~~~~~~~~~~~~ - - - Internal Changes - ~~~~~~~~~~~~~~~~ - - .. _whats-new.0.19.0: - - v0.19.0 (23 July 2021) - ---------------------- - - This release brings improvements to plotting of categorical data, the ability to specify how attributes - are combined in xarray operations, a new high-level :py:func:`unify_chunks` function, as well as various - deprecations, bug fixes, and minor improvements. - - - Many thanks to the 29 contributors to this release!: - - Andrew Williams, Augustus, Aureliana Barghini, Benoit Bovy, crusaderky, Deepak Cherian, ellesmith88, - Elliott Sales de Andrade, Giacomo Caria, github-actions[bot], Illviljan, Joeperdefloep, joooeey, Julia Kent, - Julius Busecke, keewis, Mathias Hauser, Matthias Göbel, Mattia Almansi, Maximilian Roos, Peter Andreas Entschev, - Ray Bell, Sander, Santiago Soler, Sebastian, Spencer Clark, Stephan Hoyer, Thomas Hirtz, Thomas Nicholas. - - New Features - ~~~~~~~~~~~~ - - Allow passing argument ``missing_dims`` to :py:meth:`Variable.transpose` and :py:meth:`Dataset.transpose` - (:issue:`5550`, :pull:`5586`) - By `Giacomo Caria `_. - - Allow passing a dictionary as coords to a :py:class:`DataArray` (:issue:`5527`, - reverts :pull:`1539`, which had deprecated this due to python's inconsistent ordering in earlier versions). - By `Sander van Rijn `_. - - Added :py:meth:`Dataset.coarsen.construct`, :py:meth:`DataArray.coarsen.construct` (:issue:`5454`, :pull:`5475`). - By `Deepak Cherian `_. - - Xarray now uses consolidated metadata by default when writing and reading Zarr - stores (:issue:`5251`). - By `Stephan Hoyer `_. - - New top-level function :py:func:`unify_chunks`. - By `Mattia Almansi `_. - - Allow assigning values to a subset of a dataset using positional or label-based - indexing (:issue:`3015`, :pull:`5362`). - By `Matthias Göbel `_. - - Attempting to reduce a weighted object over missing dimensions now raises an error (:pull:`5362`). - By `Mattia Almansi `_. - - Add ``.sum`` to :py:meth:`~xarray.DataArray.rolling_exp` and - :py:meth:`~xarray.Dataset.rolling_exp` for exponentially weighted rolling - sums. These require numbagg 0.2.1; - (:pull:`5178`). - By `Maximilian Roos `_. - - :py:func:`xarray.cov` and :py:func:`xarray.corr` now lazily check for missing - values if inputs are dask arrays (:issue:`4804`, :pull:`5284`). - By `Andrew Williams `_. - - Attempting to ``concat`` list of elements that are not all ``Dataset`` or all ``DataArray`` now raises an error (:issue:`5051`, :pull:`5425`). - By `Thomas Hirtz `_. - - allow passing a function to ``combine_attrs`` (:pull:`4896`). - By `Justus Magin `_. - - Allow plotting categorical data (:pull:`5464`). - By `Jimmy Westling `_. - - Allow removal of the coordinate attribute ``coordinates`` on variables by setting ``.attrs['coordinates']= None`` - (:issue:`5510`). - By `Elle Smith `_. - - Added :py:meth:`DataArray.to_numpy`, :py:meth:`DataArray.as_numpy`, and :py:meth:`Dataset.as_numpy`. (:pull:`5568`). - By `Tom Nicholas `_. - - Units in plot labels are now automatically inferred from wrapped :py:meth:`pint.Quantity` arrays. (:pull:`5561`). - By `Tom Nicholas `_. - - Breaking changes - ~~~~~~~~~~~~~~~~ - - - The default ``mode`` for :py:meth:`Dataset.to_zarr` when ``region`` is set - has changed to the new ``mode="r+"``, which only allows for overriding - pre-existing array values. This is a safer default than the prior ``mode="a"``, - and allows for higher performance writes (:pull:`5252`). - By `Stephan Hoyer `_. - - The main parameter to :py:func:`combine_by_coords` is renamed to `data_objects` instead - of `datasets` so anyone calling this method using a named parameter will need to update - the name accordingly (:issue:`3248`, :pull:`4696`). - By `Augustus Ijams `_. - - Deprecations - ~~~~~~~~~~~~ - - - Removed the deprecated ``dim`` kwarg to :py:func:`DataArray.integrate` (:pull:`5630`) - - Removed the deprecated ``keep_attrs`` kwarg to :py:func:`DataArray.rolling` (:pull:`5630`) - - Removed the deprecated ``keep_attrs`` kwarg to :py:func:`DataArray.coarsen` (:pull:`5630`) - - Completed deprecation of passing an ``xarray.DataArray`` to :py:func:`Variable` - will now raise a ``TypeError`` (:pull:`5630`) - - Bug fixes - ~~~~~~~~~ - - Fix a minor incompatibility between partial datetime string indexing with a - :py:class:`CFTimeIndex` and upcoming pandas version 1.3.0 (:issue:`5356`, - :pull:`5359`). - By `Spencer Clark `_. - - Fix 1-level multi-index incorrectly converted to single index (:issue:`5384`, - :pull:`5385`). - By `Benoit Bovy `_. - - Don't cast a duck array in a coordinate to :py:class:`numpy.ndarray` in - :py:meth:`DataArray.differentiate` (:pull:`5408`) - By `Justus Magin `_. - - Fix the ``repr`` of :py:class:`Variable` objects with ``display_expand_data=True`` - (:pull:`5406`) - By `Justus Magin `_. - - Plotting a pcolormesh with ``xscale="log"`` and/or ``yscale="log"`` works as - expected after improving the way the interval breaks are generated (:issue:`5333`). - By `Santiago Soler `_ - - :py:func:`combine_by_coords` can now handle combining a list of unnamed - ``DataArray`` as input (:issue:`3248`, :pull:`4696`). - By `Augustus Ijams `_. - - - Internal Changes - ~~~~~~~~~~~~~~~~ - - Run CI on the first & last python versions supported only; currently 3.7 & 3.9. - (:pull:`5433`) - By `Maximilian Roos `_. - - Publish test results & timings on each PR. - (:pull:`5537`) - By `Maximilian Roos `_. - - Explicit indexes refactor: add a ``xarray.Index.query()`` method in which - one may eventually provide a custom implementation of label-based data - selection (not ready yet for public use). Also refactor the internal, - pandas-specific implementation into ``PandasIndex.query()`` and - ``PandasMultiIndex.query()`` (:pull:`5322`). - By `Benoit Bovy `_. - - .. _whats-new.0.18.2: - - v0.18.2 (19 May 2021) - --------------------- - - This release reverts a regression in xarray's unstacking of dask-backed arrays. - - .. _whats-new.0.18.1: - - v0.18.1 (18 May 2021) - --------------------- - - This release is intended as a small patch release to be compatible with the new - 2021.5.0 ``dask.distributed`` release. It also includes a new - ``drop_duplicates`` method, some documentation improvements, the beginnings of - our internal Index refactoring, and some bug fixes. - - Thank you to all 16 contributors! - - Anderson Banihirwe, Andrew, Benoit Bovy, Brewster Malevich, Giacomo Caria, - Illviljan, James Bourbeau, Keewis, Maximilian Roos, Ravin Kumar, Stephan Hoyer, - Thomas Nicholas, Tom Nicholas, Zachary Moon. - - New Features - ~~~~~~~~~~~~ - - Implement :py:meth:`DataArray.drop_duplicates` - to remove duplicate dimension values (:pull:`5239`). - By `Andrew Huang `_. - - Allow passing ``combine_attrs`` strategy names to the ``keep_attrs`` parameter of - :py:func:`apply_ufunc` (:pull:`5041`) - By `Justus Magin `_. - - :py:meth:`Dataset.interp` now allows interpolation with non-numerical datatypes, - such as booleans, instead of dropping them. (:issue:`4761` :pull:`5008`). - By `Jimmy Westling `_. - - Raise more informative error when decoding time variables with invalid reference dates. - (:issue:`5199`, :pull:`5288`). By `Giacomo Caria `_. - - - Bug fixes - ~~~~~~~~~ - - Opening netCDF files from a path that doesn't end in ``.nc`` without supplying - an explicit ``engine`` works again (:issue:`5295`), fixing a bug introduced in - 0.18.0. - By `Stephan Hoyer `_ - - Documentation - ~~~~~~~~~~~~~ - - Clean up and enhance docstrings for the :py:class:`DataArray.plot` and ``Dataset.plot.*`` - families of methods (:pull:`5285`). - By `Zach Moon `_. - - - Explanation of deprecation cycles and how to implement them added to contributors - guide. (:pull:`5289`) - By `Tom Nicholas `_. - - - Internal Changes - ~~~~~~~~~~~~~~~~ - - - Explicit indexes refactor: add an ``xarray.Index`` base class and - ``Dataset.xindexes`` / ``DataArray.xindexes`` properties. Also rename - ``PandasIndexAdapter`` to ``PandasIndex``, which now inherits from - ``xarray.Index`` (:pull:`5102`). - By `Benoit Bovy `_. - - Replace ``SortedKeysDict`` with python's ``dict``, given dicts are now ordered. - By `Maximilian Roos `_. - - Updated the release guide for developers. Now accounts for actions that are automated via github - actions. (:pull:`5274`). - By `Tom Nicholas `_. - - .. _whats-new.0.18.0: - - v0.18.0 (6 May 2021) - -------------------- - - This release brings a few important performance improvements, a wide range of - usability upgrades, lots of bug fixes, and some new features. These include - a plugin API to add backend engines, a new theme for the documentation, - curve fitting methods, and several new plotting functions. - - Many thanks to the 38 contributors to this release: Aaron Spring, Alessandro Amici, - Alex Marandon, Alistair Miles, Ana Paula Krelling, Anderson Banihirwe, Aureliana Barghini, - Baudouin Raoult, Benoit Bovy, Blair Bonnett, David Trémouilles, Deepak Cherian, - Gabriel Medeiros Abrahão, Giacomo Caria, Hauke Schulz, Illviljan, Mathias Hauser, Matthias Bussonnier, - Mattia Almansi, Maximilian Roos, Ray Bell, Richard Kleijn, Ryan Abernathey, Sam Levang, Spencer Clark, - Spencer Jones, Tammas Loughran, Tobias Kölling, Todd, Tom Nicholas, Tom White, Victor Negîrneac, - Xianxiang Li, Zeb Nicholls, crusaderky, dschwoerer, johnomotani, keewis - - - New Features - ~~~~~~~~~~~~ - - - apply ``combine_attrs`` on data variables and coordinate variables when concatenating - and merging datasets and dataarrays (:pull:`4902`). - By `Justus Magin `_. - - Add :py:meth:`Dataset.to_pandas` (:pull:`5247`) - By `Giacomo Caria `_. - - Add :py:meth:`DataArray.plot.surface` which wraps matplotlib's `plot_surface` to make - surface plots (:issue:`2235` :issue:`5084` :pull:`5101`). - By `John Omotani `_. - - Allow passing multiple arrays to :py:meth:`Dataset.__setitem__` (:pull:`5216`). - By `Giacomo Caria `_. - - Add 'cumulative' option to :py:meth:`Dataset.integrate` and - :py:meth:`DataArray.integrate` so that result is a cumulative integral, like - :py:func:`scipy.integrate.cumulative_trapezoidal` (:pull:`5153`). - By `John Omotani `_. - - Add ``safe_chunks`` option to :py:meth:`Dataset.to_zarr` which allows overriding - checks made to ensure Dask and Zarr chunk compatibility (:issue:`5056`). - By `Ryan Abernathey `_ - - Add :py:meth:`Dataset.query` and :py:meth:`DataArray.query` which enable indexing - of datasets and data arrays by evaluating query expressions against the values of the - data variables (:pull:`4984`). - By `Alistair Miles `_. - - Allow passing ``combine_attrs`` to :py:meth:`Dataset.merge` (:pull:`4895`). - By `Justus Magin `_. - - Support for `dask.graph_manipulation - `_ (requires dask >=2021.3) - By `Guido Imperiale `_ - - Add :py:meth:`Dataset.plot.streamplot` for streamplot plots with :py:class:`Dataset` - variables (:pull:`5003`). - By `John Omotani `_. - - Many of the arguments for the :py:attr:`DataArray.str` methods now support - providing an array-like input. In this case, the array provided to the - arguments is broadcast against the original array and applied elementwise. - - :py:attr:`DataArray.str` now supports ``+``, ``*``, and ``%`` operators. These - behave the same as they do for :py:class:`str`, except that they follow - array broadcasting rules. - - A large number of new :py:attr:`DataArray.str` methods were implemented, - :py:meth:`DataArray.str.casefold`, :py:meth:`DataArray.str.cat`, - :py:meth:`DataArray.str.extract`, :py:meth:`DataArray.str.extractall`, - :py:meth:`DataArray.str.findall`, :py:meth:`DataArray.str.format`, - :py:meth:`DataArray.str.get_dummies`, :py:meth:`DataArray.str.islower`, - :py:meth:`DataArray.str.join`, :py:meth:`DataArray.str.normalize`, - :py:meth:`DataArray.str.partition`, :py:meth:`DataArray.str.rpartition`, - :py:meth:`DataArray.str.rsplit`, and :py:meth:`DataArray.str.split`. - A number of these methods allow for splitting or joining the strings in an - array. (:issue:`4622`) - By `Todd Jennings `_ - - Thanks to the new pluggable backend infrastructure external packages may now - use the ``xarray.backends`` entry point to register additional engines to be used in - :py:func:`open_dataset`, see the documentation in :ref:`add_a_backend` - (:issue:`4309`, :issue:`4803`, :pull:`4989`, :pull:`4810` and many others). - The backend refactor has been sponsored with the "Essential Open Source Software for Science" - grant from the `Chan Zuckerberg Initiative `_ and - developed by `B-Open `_. - By `Aureliana Barghini `_ and `Alessandro Amici `_. - - :py:attr:`~core.accessor_dt.DatetimeAccessor.date` added (:issue:`4983`, :pull:`4994`). - By `Hauke Schulz `_. - - Implement ``__getitem__`` for both :py:class:`~core.groupby.DatasetGroupBy` and - :py:class:`~core.groupby.DataArrayGroupBy`, inspired by pandas' - :py:meth:`~pandas.core.groupby.GroupBy.get_group`. - By `Deepak Cherian `_. - - Switch the tutorial functions to use `pooch `_ - (which is now a optional dependency) and add :py:func:`tutorial.open_rasterio` as a - way to open example rasterio files (:issue:`3986`, :pull:`4102`, :pull:`5074`). - By `Justus Magin `_. - - Add typing information to unary and binary arithmetic operators operating on - :py:class:`Dataset`, :py:class:`DataArray`, :py:class:`Variable`, - :py:class:`~core.groupby.DatasetGroupBy` or - :py:class:`~core.groupby.DataArrayGroupBy` (:pull:`4904`). - By `Richard Kleijn `_. - - Add a ``combine_attrs`` parameter to :py:func:`open_mfdataset` (:pull:`4971`). - By `Justus Magin `_. - - Enable passing arrays with a subset of dimensions to - :py:meth:`DataArray.clip` & :py:meth:`Dataset.clip`; these methods now use - :py:func:`xarray.apply_ufunc`; (:pull:`5184`). - By `Maximilian Roos `_. - - Disable the `cfgrib` backend if the `eccodes` library is not installed (:pull:`5083`). - By `Baudouin Raoult `_. - - Added :py:meth:`DataArray.curvefit` and :py:meth:`Dataset.curvefit` for general curve fitting applications. (:issue:`4300`, :pull:`4849`) - By `Sam Levang `_. - - Add options to control expand/collapse of sections in display of Dataset and - DataArray. The function :py:func:`set_options` now takes keyword aguments - ``display_expand_attrs``, ``display_expand_coords``, ``display_expand_data``, - ``display_expand_data_vars``, all of which can be one of ``True`` to always - expand, ``False`` to always collapse, or ``default`` to expand unless over a - pre-defined limit (:pull:`5126`). - By `Tom White `_. - - Significant speedups in :py:meth:`Dataset.interp` and :py:meth:`DataArray.interp`. - (:issue:`4739`, :pull:`4740`). - By `Deepak Cherian `_. - - Prevent passing `concat_dim` to :py:func:`xarray.open_mfdataset` when - `combine='by_coords'` is specified, which should never have been possible (as - :py:func:`xarray.combine_by_coords` has no `concat_dim` argument to pass to). - Also removes unneeded internal reordering of datasets in - :py:func:`xarray.open_mfdataset` when `combine='by_coords'` is specified. - Fixes (:issue:`5230`). - By `Tom Nicholas `_. - - Implement ``__setitem__`` for ``xarray.core.indexing.DaskIndexingAdapter`` if - dask version supports item assignment. (:issue:`5171`, :pull:`5174`) - By `Tammas Loughran `_. - - Breaking changes - ~~~~~~~~~~~~~~~~ - - The minimum versions of some dependencies were changed: - - ============ ====== ==== - Package Old New - ============ ====== ==== - boto3 1.12 1.13 - cftime 1.0 1.1 - dask 2.11 2.15 - distributed 2.11 2.15 - matplotlib 3.1 3.2 - numba 0.48 0.49 - ============ ====== ==== - - - :py:func:`open_dataset` and :py:func:`open_dataarray` now accept only the first argument - as positional, all others need to be passed are keyword arguments. This is part of the - refactor to support external backends (:issue:`4309`, :pull:`4989`). - By `Alessandro Amici `_. - - Functions that are identities for 0d data return the unchanged data - if axis is empty. This ensures that Datasets where some variables do - not have the averaged dimensions are not accidentially changed - (:issue:`4885`, :pull:`5207`). - By `David Schwörer `_. - - :py:attr:`DataArray.coarsen` and :py:attr:`Dataset.coarsen` no longer support passing ``keep_attrs`` - via its constructor. Pass ``keep_attrs`` via the applied function, i.e. use - ``ds.coarsen(...).mean(keep_attrs=False)`` instead of ``ds.coarsen(..., keep_attrs=False).mean()``. - Further, coarsen now keeps attributes per default (:pull:`5227`). - By `Mathias Hauser `_. - - switch the default of the :py:func:`merge` ``combine_attrs`` parameter to - ``"override"``. This will keep the current behavior for merging the ``attrs`` of - variables but stop dropping the ``attrs`` of the main objects (:pull:`4902`). - By `Justus Magin `_. - - Deprecations - ~~~~~~~~~~~~ - - - Warn when passing `concat_dim` to :py:func:`xarray.open_mfdataset` when - `combine='by_coords'` is specified, which should never have been possible (as - :py:func:`xarray.combine_by_coords` has no `concat_dim` argument to pass to). - Also removes unneeded internal reordering of datasets in - :py:func:`xarray.open_mfdataset` when `combine='by_coords'` is specified. - Fixes (:issue:`5230`), via (:pull:`5231`, :pull:`5255`). - By `Tom Nicholas `_. - - The `lock` keyword argument to :py:func:`open_dataset` and :py:func:`open_dataarray` is now - a backend specific option. It will give a warning if passed to a backend that doesn't support it - instead of being silently ignored. From the next version it will raise an error. - This is part of the refactor to support external backends (:issue:`5073`). - By `Tom Nicholas `_ and `Alessandro Amici `_. - - - Bug fixes - ~~~~~~~~~ - - Properly support :py:meth:`DataArray.ffill`, :py:meth:`DataArray.bfill`, :py:meth:`Dataset.ffill`, :py:meth:`Dataset.bfill` along chunked dimensions. - (:issue:`2699`). - By `Deepak Cherian `_. - - Fix 2d plot failure for certain combinations of dimensions when `x` is 1d and `y` is - 2d (:issue:`5097`, :pull:`5099`). - By `John Omotani `_. - - Ensure standard calendar times encoded with large values (i.e. greater than - approximately 292 years), can be decoded correctly without silently overflowing - (:pull:`5050`). This was a regression in xarray 0.17.0. - By `Zeb Nicholls `_. - - Added support for `numpy.bool_` attributes in roundtrips using `h5netcdf` engine with `invalid_netcdf=True` [which casts `bool`s to `numpy.bool_`] (:issue:`4981`, :pull:`4986`). - By `Victor Negîrneac `_. - - Don't allow passing ``axis`` to :py:meth:`Dataset.reduce` methods (:issue:`3510`, :pull:`4940`). - By `Justus Magin `_. - - Decode values as signed if attribute `_Unsigned = "false"` (:issue:`4954`) - By `Tobias Kölling `_. - - Keep coords attributes when interpolating when the indexer is not a Variable. (:issue:`4239`, :issue:`4839` :pull:`5031`) - By `Jimmy Westling `_. - - Ensure standard calendar dates encoded with a calendar attribute with some or - all uppercase letters can be decoded or encoded to or from - ``np.datetime64[ns]`` dates with or without ``cftime`` installed - (:issue:`5093`, :pull:`5180`). - By `Spencer Clark `_. - - Warn on passing ``keep_attrs`` to ``resample`` and ``rolling_exp`` as they are ignored, pass ``keep_attrs`` - to the applied function instead (:pull:`5265`). - By `Mathias Hauser `_. - - Documentation - ~~~~~~~~~~~~~ - - New section on :ref:`add_a_backend` in the "Internals" chapter aimed to backend developers - (:issue:`4803`, :pull:`4810`). - By `Aureliana Barghini `_. - - Add :py:meth:`Dataset.polyfit` and :py:meth:`DataArray.polyfit` under "See also" in - the docstrings of :py:meth:`Dataset.polyfit` and :py:meth:`DataArray.polyfit` - (:issue:`5016`, :pull:`5020`). - By `Aaron Spring `_. - - New sphinx theme & rearrangement of the docs (:pull:`4835`). - By `Anderson Banihirwe `_. - - Internal Changes - ~~~~~~~~~~~~~~~~ - - Enable displaying mypy error codes and ignore only specific error codes using - ``# type: ignore[error-code]`` (:pull:`5096`). - By `Mathias Hauser `_. - - Replace uses of ``raises_regex`` with the more standard - ``pytest.raises(Exception, match="foo")``; - (:pull:`5188`), (:pull:`5191`). - By `Maximilian Roos `_. - - .. _whats-new.0.17.0: - - v0.17.0 (24 Feb 2021) - --------------------- - - This release brings a few important performance improvements, a wide range of - usability upgrades, lots of bug fixes, and some new features. These include - better ``cftime`` support, a new quiver plot, better ``unstack`` performance, - more efficient memory use in rolling operations, and some python packaging - improvements. We also have a few documentation improvements (and more planned!). - - Many thanks to the 36 contributors to this release: Alessandro Amici, Anderson - Banihirwe, Aureliana Barghini, Ayrton Bourn, Benjamin Bean, Blair Bonnett, Chun - Ho Chow, DWesl, Daniel Mesejo-León, Deepak Cherian, Eric Keenan, Illviljan, Jens - Hedegaard Nielsen, Jody Klymak, Julien Seguinot, Julius Busecke, Kai Mühlbauer, - Leif Denby, Martin Durant, Mathias Hauser, Maximilian Roos, Michael Mann, Ray - Bell, RichardScottOZ, Spencer Clark, Tim Gates, Tom Nicholas, Yunus Sevinchan, - alexamici, aurghs, crusaderky, dcherian, ghislainp, keewis, rhkleijn - - Breaking changes - ~~~~~~~~~~~~~~~~ - - xarray no longer supports python 3.6 - - The minimum version policy was changed to also apply to projects with irregular - releases. As a result, the minimum versions of some dependencies have changed: - - ============ ====== ==== - Package Old New - ============ ====== ==== - Python 3.6 3.7 - setuptools 38.4 40.4 - numpy 1.15 1.17 - pandas 0.25 1.0 - dask 2.9 2.11 - distributed 2.9 2.11 - bottleneck 1.2 1.3 - h5netcdf 0.7 0.8 - iris 2.2 2.4 - netcdf4 1.4 1.5 - pseudonetcdf 3.0 3.1 - rasterio 1.0 1.1 - scipy 1.3 1.4 - seaborn 0.9 0.10 - zarr 2.3 2.4 - ============ ====== ==== - - (:issue:`4688`, :pull:`4720`, :pull:`4907`, :pull:`4942`) - - As a result of :pull:`4684` the default units encoding for - datetime-like values (``np.datetime64[ns]`` or ``cftime.datetime``) will now - always be set such that ``int64`` values can be used. In the past, no units - finer than "seconds" were chosen, which would sometimes mean that ``float64`` - values were required, which would lead to inaccurate I/O round-trips. - - Variables referred to in attributes like ``bounds`` and ``grid_mapping`` - can be set as coordinate variables. These attributes are moved to - :py:attr:`DataArray.encoding` from :py:attr:`DataArray.attrs`. This behaviour - is controlled by the ``decode_coords`` kwarg to :py:func:`open_dataset` and - :py:func:`open_mfdataset`. The full list of decoded attributes is in - :ref:`weather-climate` (:pull:`2844`, :issue:`3689`) - - As a result of :pull:`4911` the output from calling :py:meth:`DataArray.sum` - or :py:meth:`DataArray.prod` on an integer array with ``skipna=True`` and a - non-None value for ``min_count`` will now be a float array rather than an - integer array. - - Deprecations - ~~~~~~~~~~~~ - - - ``dim`` argument to :py:meth:`DataArray.integrate` is being deprecated in - favour of a ``coord`` argument, for consistency with :py:meth:`Dataset.integrate`. - For now using ``dim`` issues a ``FutureWarning``. It will be removed in - version 0.19.0 (:pull:`3993`). - By `Tom Nicholas `_. - - Deprecated ``autoclose`` kwargs from :py:func:`open_dataset` are removed (:pull:`4725`). - By `Aureliana Barghini `_. - - the return value of :py:meth:`Dataset.update` is being deprecated to make it work more - like :py:meth:`dict.update`. It will be removed in version 0.19.0 (:pull:`4932`). - By `Justus Magin `_. - - New Features - ~~~~~~~~~~~~ - - :py:meth:`~xarray.cftime_range` and :py:meth:`DataArray.resample` now support - millisecond (``"L"`` or ``"ms"``) and microsecond (``"U"`` or ``"us"``) frequencies - for ``cftime.datetime`` coordinates (:issue:`4097`, :pull:`4758`). - By `Spencer Clark `_. - - Significantly higher ``unstack`` performance on numpy-backed arrays which - contain missing values; 8x faster than previous versions in our benchmark, and - now 2x faster than pandas (:pull:`4746`). - By `Maximilian Roos `_. - - Add :py:meth:`Dataset.plot.quiver` for quiver plots with :py:class:`Dataset` variables. - By `Deepak Cherian `_. - - Add ``"drop_conflicts"`` to the strategies supported by the ``combine_attrs`` kwarg - (:issue:`4749`, :pull:`4827`). - By `Justus Magin `_. - - Allow installing from git archives (:pull:`4897`). - By `Justus Magin `_. - - :py:class:`~core.rolling.DataArrayCoarsen` and :py:class:`~core.rolling.DatasetCoarsen` - now implement a ``reduce`` method, enabling coarsening operations with custom - reduction functions (:issue:`3741`, :pull:`4939`). - By `Spencer Clark `_. - - Most rolling operations use significantly less memory. (:issue:`4325`). - By `Deepak Cherian `_. - - Add :py:meth:`Dataset.drop_isel` and :py:meth:`DataArray.drop_isel` - (:issue:`4658`, :pull:`4819`). - By `Daniel Mesejo `_. - - Xarray now leverages updates as of cftime version 1.4.1, which enable exact I/O - roundtripping of ``cftime.datetime`` objects (:pull:`4758`). - By `Spencer Clark `_. - - :py:func:`open_dataset` and :py:func:`open_mfdataset` now accept ``fsspec`` URLs - (including globs for the latter) for ``engine="zarr"``, and so allow reading from - many remote and other file systems (:pull:`4461`) - By `Martin Durant `_ - - :py:meth:`DataArray.swap_dims` & :py:meth:`Dataset.swap_dims` now accept dims - in the form of kwargs as well as a dict, like most similar methods. - By `Maximilian Roos `_. - - Bug fixes - ~~~~~~~~~ - - Use specific type checks in ``xarray.core.variable.as_compatible_data`` instead of - blanket access to ``values`` attribute (:issue:`2097`) - By `Yunus Sevinchan `_. - - :py:meth:`DataArray.resample` and :py:meth:`Dataset.resample` do not trigger - computations anymore if :py:meth:`Dataset.weighted` or - :py:meth:`DataArray.weighted` are applied (:issue:`4625`, :pull:`4668`). By - `Julius Busecke `_. - - :py:func:`merge` with ``combine_attrs='override'`` makes a copy of the attrs - (:issue:`4627`). - - By default, when possible, xarray will now always use values of - type ``int64`` when encoding and decoding ``numpy.datetime64[ns]`` datetimes. This - ensures that maximum precision and accuracy are maintained in the round-tripping - process (:issue:`4045`, :pull:`4684`). It also enables encoding and decoding standard - calendar dates with time units of nanoseconds (:pull:`4400`). - By `Spencer Clark `_ and `Mark Harfouche - `_. - - :py:meth:`DataArray.astype`, :py:meth:`Dataset.astype` and :py:meth:`Variable.astype` support - the ``order`` and ``subok`` parameters again. This fixes a regression introduced in version 0.16.1 - (:issue:`4644`, :pull:`4683`). - By `Richard Kleijn `_ . - - Remove dictionary unpacking when using ``.loc`` to avoid collision with ``.sel`` parameters (:pull:`4695`). - By `Anderson Banihirwe `_. - - Fix the legend created by :py:meth:`Dataset.plot.scatter` (:issue:`4641`, :pull:`4723`). - By `Justus Magin `_. - - Fix a crash in orthogonal indexing on geographic coordinates with ``engine='cfgrib'`` - (:issue:`4733` :pull:`4737`). - By `Alessandro Amici `_. - - Coordinates with dtype ``str`` or ``bytes`` now retain their dtype on many operations, - e.g. ``reindex``, ``align``, ``concat``, ``assign``, previously they were cast to an object dtype - (:issue:`2658` and :issue:`4543`). - By `Mathias Hauser `_. - - Limit number of data rows when printing large datasets. (:issue:`4736`, :pull:`4750`). - By `Jimmy Westling `_. - - Add ``missing_dims`` parameter to transpose (:issue:`4647`, :pull:`4767`). - By `Daniel Mesejo `_. - - Resolve intervals before appending other metadata to labels when plotting (:issue:`4322`, :pull:`4794`). - By `Justus Magin `_. - - Fix regression when decoding a variable with a ``scale_factor`` and ``add_offset`` given - as a list of length one (:issue:`4631`). - By `Mathias Hauser `_. - - Expand user directory paths (e.g. ``~/``) in :py:func:`open_mfdataset` and - :py:meth:`Dataset.to_zarr` (:issue:`4783`, :pull:`4795`). - By `Julien Seguinot `_. - - Raise DeprecationWarning when trying to typecast a tuple containing a :py:class:`DataArray`. - User now prompted to first call `.data` on it (:issue:`4483`). - By `Chun Ho Chow `_. - - Ensure that :py:meth:`Dataset.interp` raises ``ValueError`` when interpolating - outside coordinate range and ``bounds_error=True`` (:issue:`4854`, - :pull:`4855`). - By `Leif Denby `_. - - Fix time encoding bug associated with using cftime versions greater than - 1.4.0 with xarray (:issue:`4870`, :pull:`4871`). - By `Spencer Clark `_. - - Stop :py:meth:`DataArray.sum` and :py:meth:`DataArray.prod` computing lazy - arrays when called with a ``min_count`` parameter (:issue:`4898`, :pull:`4911`). - By `Blair Bonnett `_. - - Fix bug preventing the ``min_count`` parameter to :py:meth:`DataArray.sum` and - :py:meth:`DataArray.prod` working correctly when calculating over all axes of - a float64 array (:issue:`4898`, :pull:`4911`). - By `Blair Bonnett `_. - - Fix decoding of vlen strings using h5py versions greater than 3.0.0 with h5netcdf backend (:issue:`4570`, :pull:`4893`). - By `Kai Mühlbauer `_. - - Allow converting :py:class:`Dataset` or :py:class:`DataArray` objects with a ``MultiIndex`` - and at least one other dimension to a ``pandas`` object (:issue:`3008`, :pull:`4442`). - By `ghislainp `_. - - Documentation - ~~~~~~~~~~~~~ - - Add information about requirements for accessor classes (:issue:`2788`, :pull:`4657`). - By `Justus Magin `_. - - Start a list of external I/O integrating with ``xarray`` (:issue:`683`, :pull:`4566`). - By `Justus Magin `_. - - Add concat examples and improve combining documentation (:issue:`4620`, :pull:`4645`). - By `Ray Bell `_ and - `Justus Magin `_. - - explicitly mention that :py:meth:`Dataset.update` updates inplace (:issue:`2951`, :pull:`4932`). - By `Justus Magin `_. - - Added docs on vectorized indexing (:pull:`4711`). - By `Eric Keenan `_. - - Internal Changes - ~~~~~~~~~~~~~~~~ - - Speed up of the continuous integration tests on azure. - - - Switched to mamba and use matplotlib-base for a faster installation of all dependencies (:pull:`4672`). - - Use ``pytest.mark.skip`` instead of ``pytest.mark.xfail`` for some tests that can currently not - succeed (:pull:`4685`). - - Run the tests in parallel using pytest-xdist (:pull:`4694`). - - By `Justus Magin `_ and `Mathias Hauser `_. - - Use ``pyproject.toml`` instead of the ``setup_requires`` option for - ``setuptools`` (:pull:`4897`). - By `Justus Magin `_. - - Replace all usages of ``assert x.identical(y)`` with ``assert_identical(x, y)`` - for clearer error messages (:pull:`4752`). - By `Maximilian Roos `_. - - Speed up attribute style access (e.g. ``ds.somevar`` instead of ``ds["somevar"]``) and - tab completion in IPython (:issue:`4741`, :pull:`4742`). - By `Richard Kleijn `_. - - Added the ``set_close`` method to ``Dataset`` and ``DataArray`` for backends - to specify how to voluntary release all resources. (:pull:`#4809`) - By `Alessandro Amici `_. - - Update type hints to work with numpy v1.20 (:pull:`4878`). - By `Mathias Hauser `_. - - Ensure warnings cannot be turned into exceptions in :py:func:`testing.assert_equal` and - the other ``assert_*`` functions (:pull:`4864`). - By `Mathias Hauser `_. - - Performance improvement when constructing DataArrays. Significantly speeds up - repr for Datasets with large number of variables. - By `Deepak Cherian `_. - - .. _whats-new.0.16.2: - - v0.16.2 (30 Nov 2020) - --------------------- - - This release brings the ability to write to limited regions of ``zarr`` files, - open zarr files with :py:func:`open_dataset` and :py:func:`open_mfdataset`, - increased support for propagating ``attrs`` using the ``keep_attrs`` flag, as - well as numerous bugfixes and documentation improvements. - - Many thanks to the 31 contributors who contributed to this release: Aaron - Spring, Akio Taniguchi, Aleksandar Jelenak, alexamici, Alexandre Poux, Anderson - Banihirwe, Andrew Pauling, Ashwin Vishnu, aurghs, Brian Ward, Caleb, crusaderky, - Dan Nowacki, darikg, David Brochart, David Huard, Deepak Cherian, Dion Häfner, - Gerardo Rivera, Gerrit Holl, Illviljan, inakleinbottle, Jacob Tomlinson, James - A. Bednar, jenssss, Joe Hamman, johnomotani, Joris Van den Bossche, Julia Kent, - Julius Busecke, Kai Mühlbauer, keewis, Keisuke Fujii, Kyle Cranmer, Luke - Volpatti, Mathias Hauser, Maximilian Roos, Michaël Defferrard, Michal - Baumgartner, Nick R. Papior, Pascal Bourgault, Peter Hausamann, PGijsbers, Ray - Bell, Romain Martinez, rpgoldman, Russell Manser, Sahid Velji, Samnan Rahee, - Sander, Spencer Clark, Stephan Hoyer, Thomas Zilio, Tobias Kölling, Tom - Augspurger, Wei Ji, Yash Saboo, Zeb Nicholls, - - Deprecations - ~~~~~~~~~~~~ - - - :py:attr:`~core.accessor_dt.DatetimeAccessor.weekofyear` and :py:attr:`~core.accessor_dt.DatetimeAccessor.week` - have been deprecated. Use ``DataArray.dt.isocalendar().week`` - instead (:pull:`4534`). By `Mathias Hauser `_. - `Maximilian Roos `_, and `Spencer Clark `_. - - :py:attr:`DataArray.rolling` and :py:attr:`Dataset.rolling` no longer support passing ``keep_attrs`` - via its constructor. Pass ``keep_attrs`` via the applied function, i.e. use - ``ds.rolling(...).mean(keep_attrs=False)`` instead of ``ds.rolling(..., keep_attrs=False).mean()`` - Rolling operations now keep their attributes per default (:pull:`4510`). - By `Mathias Hauser `_. - - New Features - ~~~~~~~~~~~~ - - - :py:func:`open_dataset` and :py:func:`open_mfdataset` - now works with ``engine="zarr"`` (:issue:`3668`, :pull:`4003`, :pull:`4187`). - By `Miguel Jimenez `_ and `Wei Ji Leong `_. - - Unary & binary operations follow the ``keep_attrs`` flag (:issue:`3490`, :issue:`4065`, :issue:`3433`, :issue:`3595`, :pull:`4195`). - By `Deepak Cherian `_. - - Added :py:meth:`~core.accessor_dt.DatetimeAccessor.isocalendar()` that returns a Dataset - with year, week, and weekday calculated according to the ISO 8601 calendar. Requires - pandas version 1.1.0 or greater (:pull:`4534`). By `Mathias Hauser `_, - `Maximilian Roos `_, and `Spencer Clark `_. - - :py:meth:`Dataset.to_zarr` now supports a ``region`` keyword for writing to - limited regions of existing Zarr stores (:pull:`4035`). - See :ref:`io.zarr.appending` for full details. - By `Stephan Hoyer `_. - - Added typehints in :py:func:`align` to reflect that the same type received in ``objects`` arg will be returned (:pull:`4522`). - By `Michal Baumgartner `_. - - :py:meth:`Dataset.weighted` and :py:meth:`DataArray.weighted` are now executing value checks lazily if weights are provided as dask arrays (:issue:`4541`, :pull:`4559`). - By `Julius Busecke `_. - - Added the ``keep_attrs`` keyword to ``rolling_exp.mean()``; it now keeps attributes - per default. By `Mathias Hauser `_ (:pull:`4592`). - - Added ``freq`` as property to :py:class:`CFTimeIndex` and into the - ``CFTimeIndex.repr``. (:issue:`2416`, :pull:`4597`) - By `Aaron Spring `_. - - Bug fixes - ~~~~~~~~~ - - - Fix bug where reference times without padded years (e.g. ``since 1-1-1``) would lose their units when - being passed by ``encode_cf_datetime`` (:issue:`4422`, :pull:`4506`). Such units are ambiguous - about which digit represents the years (is it YMD or DMY?). Now, if such formatting is encountered, - it is assumed that the first digit is the years, they are padded appropriately (to e.g. ``since 0001-1-1``) - and a warning that this assumption is being made is issued. Previously, without ``cftime``, such times - would be silently parsed incorrectly (at least based on the CF conventions) e.g. "since 1-1-1" would - be parsed (via ``pandas`` and ``dateutil``) to ``since 2001-1-1``. - By `Zeb Nicholls `_. - - Fix :py:meth:`DataArray.plot.step`. By `Deepak Cherian `_. - - Fix bug where reading a scalar value from a NetCDF file opened with the ``h5netcdf`` backend would raise a ``ValueError`` when ``decode_cf=True`` (:issue:`4471`, :pull:`4485`). - By `Gerrit Holl `_. - - Fix bug where datetime64 times are silently changed to incorrect values if they are outside the valid date range for ns precision when provided in some other units (:issue:`4427`, :pull:`4454`). - By `Andrew Pauling `_ - - Fix silently overwriting the ``engine`` key when passing :py:func:`open_dataset` a file object - to an incompatible netCDF (:issue:`4457`). Now incompatible combinations of files and engines raise - an exception instead. By `Alessandro Amici `_. - - The ``min_count`` argument to :py:meth:`DataArray.sum()` and :py:meth:`DataArray.prod()` - is now ignored when not applicable, i.e. when ``skipna=False`` or when ``skipna=None`` - and the dtype does not have a missing value (:issue:`4352`). - By `Mathias Hauser `_. - - :py:func:`combine_by_coords` now raises an informative error when passing coordinates - with differing calendars (:issue:`4495`). By `Mathias Hauser `_. - - :py:attr:`DataArray.rolling` and :py:attr:`Dataset.rolling` now also keep the attributes and names of of (wrapped) - ``DataArray`` objects, previously only the global attributes were retained (:issue:`4497`, :pull:`4510`). - By `Mathias Hauser `_. - - Improve performance where reading small slices from huge dimensions was slower than necessary (:pull:`4560`). By `Dion Häfner `_. - - Fix bug where ``dask_gufunc_kwargs`` was silently changed in :py:func:`apply_ufunc` (:pull:`4576`). By `Kai Mühlbauer `_. - - Documentation - ~~~~~~~~~~~~~ - - document the API not supported with duck arrays (:pull:`4530`). - By `Justus Magin `_. - - Mention the possibility to pass functions to :py:meth:`Dataset.where` or - :py:meth:`DataArray.where` in the parameter documentation (:issue:`4223`, :pull:`4613`). - By `Justus Magin `_. - - Update the docstring of :py:class:`DataArray` and :py:class:`Dataset`. - (:pull:`4532`); - By `Jimmy Westling `_. - - Raise a more informative error when :py:meth:`DataArray.to_dataframe` is - is called on a scalar, (:issue:`4228`); - By `Pieter Gijsbers `_. - - Fix grammar and typos in the :doc:`contributing` guide (:pull:`4545`). - By `Sahid Velji `_. - - Fix grammar and typos in the :doc:`user-guide/io` guide (:pull:`4553`). - By `Sahid Velji `_. - - Update link to NumPy docstring standard in the :doc:`contributing` guide (:pull:`4558`). - By `Sahid Velji `_. - - Add docstrings to ``isnull`` and ``notnull``, and fix the displayed signature - (:issue:`2760`, :pull:`4618`). - By `Justus Magin `_. - - Internal Changes - ~~~~~~~~~~~~~~~~ - - - Optional dependencies can be installed along with xarray by specifying - extras as ``pip install "xarray[extra]"`` where ``extra`` can be one of ``io``, - ``accel``, ``parallel``, ``viz`` and ``complete``. See docs for updated - :ref:`installation instructions `. - (:issue:`2888`, :pull:`4480`). - By `Ashwin Vishnu `_, `Justus Magin - `_ and `Mathias Hauser - `_. - - Removed stray spaces that stem from black removing new lines (:pull:`4504`). - By `Mathias Hauser `_. - - Ensure tests are not skipped in the ``py38-all-but-dask`` test environment - (:issue:`4509`). By `Mathias Hauser `_. - - Ignore select numpy warnings around missing values, where xarray handles - the values appropriately, (:pull:`4536`); - By `Maximilian Roos `_. - - Replace the internal use of ``pd.Index.__or__`` and ``pd.Index.__and__`` with ``pd.Index.union`` - and ``pd.Index.intersection`` as they will stop working as set operations in the future - (:issue:`4565`). By `Mathias Hauser `_. - - Add GitHub action for running nightly tests against upstream dependencies (:pull:`4583`). - By `Anderson Banihirwe `_. - - Ensure all figures are closed properly in plot tests (:pull:`4600`). - By `Yash Saboo `_, `Nirupam K N - `_ and `Mathias Hauser - `_. - - .. _whats-new.0.16.1: - - v0.16.1 (2020-09-20) - --------------------- - - This patch release fixes an incompatibility with a recent pandas change, which - was causing an issue indexing with a ``datetime64``. It also includes - improvements to ``rolling``, ``to_dataframe``, ``cov`` & ``corr`` methods and - bug fixes. Our documentation has a number of improvements, including fixing all - doctests and confirming their accuracy on every commit. - - Many thanks to the 36 contributors who contributed to this release: - - Aaron Spring, Akio Taniguchi, Aleksandar Jelenak, Alexandre Poux, - Caleb, Dan Nowacki, Deepak Cherian, Gerardo Rivera, Jacob Tomlinson, James A. - Bednar, Joe Hamman, Julia Kent, Kai Mühlbauer, Keisuke Fujii, Mathias Hauser, - Maximilian Roos, Nick R. Papior, Pascal Bourgault, Peter Hausamann, Romain - Martinez, Russell Manser, Samnan Rahee, Sander, Spencer Clark, Stephan Hoyer, - Thomas Zilio, Tobias Kölling, Tom Augspurger, alexamici, crusaderky, darikg, - inakleinbottle, jenssss, johnomotani, keewis, and rpgoldman. - - Breaking changes - ~~~~~~~~~~~~~~~~ - - - :py:meth:`DataArray.astype` and :py:meth:`Dataset.astype` now preserve attributes. Keep the - old behavior by passing `keep_attrs=False` (:issue:`2049`, :pull:`4314`). - By `Dan Nowacki `_ and `Gabriel Joel Mitchell `_. - - New Features - ~~~~~~~~~~~~ - - - :py:meth:`~xarray.DataArray.rolling` and :py:meth:`~xarray.Dataset.rolling` - now accept more than 1 dimension. (:pull:`4219`) - By `Keisuke Fujii `_. - - :py:meth:`~xarray.DataArray.to_dataframe` and :py:meth:`~xarray.Dataset.to_dataframe` - now accept a ``dim_order`` parameter allowing to specify the resulting dataframe's - dimensions order (:issue:`4331`, :pull:`4333`). - By `Thomas Zilio `_. - - Support multiple outputs in :py:func:`xarray.apply_ufunc` when using - ``dask='parallelized'``. (:issue:`1815`, :pull:`4060`). - By `Kai Mühlbauer `_. - - ``min_count`` can be supplied to reductions such as ``.sum`` when specifying - multiple dimension to reduce over; (:pull:`4356`). - By `Maximilian Roos `_. - - :py:func:`xarray.cov` and :py:func:`xarray.corr` now handle missing values; (:pull:`4351`). - By `Maximilian Roos `_. - - Add support for parsing datetime strings formatted following the default - string representation of cftime objects, i.e. YYYY-MM-DD hh:mm:ss, in - partial datetime string indexing, as well as :py:meth:`~xarray.cftime_range` - (:issue:`4337`). By `Spencer Clark `_. - - Build ``CFTimeIndex.__repr__`` explicitly as :py:class:`pandas.Index`. Add ``calendar`` as a new - property for :py:class:`CFTimeIndex` and show ``calendar`` and ``length`` in - ``CFTimeIndex.__repr__`` (:issue:`2416`, :pull:`4092`) - By `Aaron Spring `_. - - Use a wrapped array's ``_repr_inline_`` method to construct the collapsed ``repr`` - of :py:class:`DataArray` and :py:class:`Dataset` objects and - document the new method in :doc:`internals/index`. (:pull:`4248`). - By `Justus Magin `_. - - Allow per-variable fill values in most functions. (:pull:`4237`). - By `Justus Magin `_. - - Expose ``use_cftime`` option in :py:func:`~xarray.open_zarr` (:issue:`2886`, :pull:`3229`) - By `Samnan Rahee `_ and `Anderson Banihirwe `_. - - Bug fixes - ~~~~~~~~~ - - - Fix indexing with datetime64 scalars with pandas 1.1 (:issue:`4283`). - By `Stephan Hoyer `_ and - `Justus Magin `_. - - Variables which are chunked using dask only along some dimensions can be chunked while storing with zarr along previously - unchunked dimensions (:pull:`4312`) By `Tobias Kölling `_. - - Fixed a bug in backend caused by basic installation of Dask (:issue:`4164`, :pull:`4318`) - `Sam Morley `_. - - Fixed a few bugs with :py:meth:`Dataset.polyfit` when encountering deficient matrix ranks (:issue:`4190`, :pull:`4193`). By `Pascal Bourgault `_. - - Fixed inconsistencies between docstring and functionality for :py:meth:`DataArray.str.get` - and :py:meth:`DataArray.str.wrap` (:issue:`4334`). By `Mathias Hauser `_. - - Fixed overflow issue causing incorrect results in computing means of :py:class:`cftime.datetime` - arrays (:issue:`4341`). By `Spencer Clark `_. - - Fixed :py:meth:`Dataset.coarsen`, :py:meth:`DataArray.coarsen` dropping attributes on original object (:issue:`4120`, :pull:`4360`). By `Julia Kent `_. - - fix the signature of the plot methods. (:pull:`4359`) By `Justus Magin `_. - - Fix :py:func:`xarray.apply_ufunc` with ``vectorize=True`` and ``exclude_dims`` (:issue:`3890`). - By `Mathias Hauser `_. - - Fix `KeyError` when doing linear interpolation to an nd `DataArray` - that contains NaNs (:pull:`4233`). - By `Jens Svensmark `_ - - Fix incorrect legend labels for :py:meth:`Dataset.plot.scatter` (:issue:`4126`). - By `Peter Hausamann `_. - - Fix ``dask.optimize`` on ``DataArray`` producing an invalid Dask task graph (:issue:`3698`) - By `Tom Augspurger `_ - - Fix ``pip install .`` when no ``.git`` directory exists; namely when the xarray source - directory has been rsync'ed by PyCharm Professional for a remote deployment over SSH. - By `Guido Imperiale `_ - - Preserve dimension and coordinate order during :py:func:`xarray.concat` (:issue:`2811`, :issue:`4072`, :pull:`4419`). - By `Kai Mühlbauer `_. - - Avoid relying on :py:class:`set` objects for the ordering of the coordinates (:pull:`4409`) - By `Justus Magin `_. - - Documentation - ~~~~~~~~~~~~~ - - - Update the docstring of :py:meth:`DataArray.copy` to remove incorrect mention of 'dataset' (:issue:`3606`) - By `Sander van Rijn `_. - - Removed skipna argument from :py:meth:`DataArray.count`, :py:meth:`DataArray.any`, :py:meth:`DataArray.all`. (:issue:`755`) - By `Sander van Rijn `_ - - Update the contributing guide to use merges instead of rebasing and state - that we squash-merge. (:pull:`4355`). By `Justus Magin `_. - - Make sure the examples from the docstrings actually work (:pull:`4408`). - By `Justus Magin `_. - - Updated Vectorized Indexing to a clearer example. - By `Maximilian Roos `_ - - Internal Changes - ~~~~~~~~~~~~~~~~ - - - Fixed all doctests and enabled their running in CI. - By `Justus Magin `_. - - Relaxed the :ref:`mindeps_policy` to support: - - - all versions of setuptools released in the last 42 months (but no older than 38.4) - - all versions of dask and dask.distributed released in the last 12 months (but no - older than 2.9) - - all versions of other packages released in the last 12 months - - All are up from 6 months (:issue:`4295`) - `Guido Imperiale `_. - - Use :py:func:`dask.array.apply_gufunc ` instead of - :py:func:`dask.array.blockwise` in :py:func:`xarray.apply_ufunc` when using - ``dask='parallelized'``. (:pull:`4060`, :pull:`4391`, :pull:`4392`) - By `Kai Mühlbauer `_. - - Align ``mypy`` versions to ``0.782`` across ``requirements`` and - ``.pre-commit-config.yml`` files. (:pull:`4390`) - By `Maximilian Roos `_ - - Only load resource files when running inside a Jupyter Notebook - (:issue:`4294`) By `Guido Imperiale `_ - - Silenced most ``numpy`` warnings such as ``Mean of empty slice``. (:pull:`4369`) - By `Maximilian Roos `_ - - Enable type checking for :py:func:`concat` (:issue:`4238`) - By `Mathias Hauser `_. - - Updated plot functions for matplotlib version 3.3 and silenced warnings in the - plot tests (:pull:`4365`). By `Mathias Hauser `_. - - Versions in ``pre-commit.yaml`` are now pinned, to reduce the chances of - conflicting versions. (:pull:`4388`) - By `Maximilian Roos `_ - - - - .. _whats-new.0.16.0: - - v0.16.0 (2020-07-11) - --------------------- - - This release adds `xarray.cov` & `xarray.corr` for covariance & correlation - respectively; the `idxmax` & `idxmin` methods, the `polyfit` method & - `xarray.polyval` for fitting polynomials, as well as a number of documentation - improvements, other features, and bug fixes. Many thanks to all 44 contributors - who contributed to this release: - - Akio Taniguchi, Andrew Williams, Aurélien Ponte, Benoit Bovy, Dave Cole, David - Brochart, Deepak Cherian, Elliott Sales de Andrade, Etienne Combrisson, Hossein - Madadi, Huite, Joe Hamman, Kai Mühlbauer, Keisuke Fujii, Maik Riechert, Marek - Jacob, Mathias Hauser, Matthieu Ancellin, Maximilian Roos, Noah D Brenowitz, - Oriol Abril, Pascal Bourgault, Phillip Butcher, Prajjwal Nijhara, Ray Bell, Ryan - Abernathey, Ryan May, Spencer Clark, Spencer Hill, Srijan Saurav, Stephan Hoyer, - Taher Chegini, Todd, Tom Nicholas, Yohai Bar Sinai, Yunus Sevinchan, - arabidopsis, aurghs, clausmichele, dmey, johnomotani, keewis, raphael dussin, - risebell - - Breaking changes - ~~~~~~~~~~~~~~~~ - - - Minimum supported versions for the following packages have changed: ``dask >=2.9``, - ``distributed>=2.9``. - By `Deepak Cherian `_ - - ``groupby`` operations will restore coord dimension order. Pass ``restore_coord_dims=False`` - to revert to previous behavior. - - :meth:`DataArray.transpose` will now transpose coordinates by default. - Pass ``transpose_coords=False`` to revert to previous behaviour. - By `Maximilian Roos `_ - - Alternate draw styles for :py:meth:`plot.step` must be passed using the - ``drawstyle`` (or ``ds``) keyword argument, instead of the ``linestyle`` (or - ``ls``) keyword argument, in line with the `upstream change in Matplotlib - `_. - (:pull:`3274`) - By `Elliott Sales de Andrade `_ - - The old ``auto_combine`` function has now been removed in - favour of the :py:func:`combine_by_coords` and - :py:func:`combine_nested` functions. This also means that - the default behaviour of :py:func:`open_mfdataset` has changed to use - ``combine='by_coords'`` as the default argument value. (:issue:`2616`, :pull:`3926`) - By `Tom Nicholas `_. - - The ``DataArray`` and ``Variable`` HTML reprs now expand the data section by - default (:issue:`4176`) - By `Stephan Hoyer `_. - - New Features - ~~~~~~~~~~~~ - - :py:meth:`DataArray.argmin` and :py:meth:`DataArray.argmax` now support - sequences of 'dim' arguments, and if a sequence is passed return a dict - (which can be passed to :py:meth:`DataArray.isel` to get the value of the minimum) of - the indices for each dimension of the minimum or maximum of a DataArray. - (:pull:`3936`) - By `John Omotani `_, thanks to `Keisuke Fujii - `_ for work in :pull:`1469`. - - Added :py:func:`xarray.cov` and :py:func:`xarray.corr` (:issue:`3784`, :pull:`3550`, :pull:`4089`). - By `Andrew Williams `_ and `Robin Beer `_. - - Implement :py:meth:`DataArray.idxmax`, :py:meth:`DataArray.idxmin`, - :py:meth:`Dataset.idxmax`, :py:meth:`Dataset.idxmin`. (:issue:`60`, :pull:`3871`) - By `Todd Jennings `_ - - Added :py:meth:`DataArray.polyfit` and :py:func:`xarray.polyval` for fitting - polynomials. (:issue:`3349`, :pull:`3733`, :pull:`4099`) - By `Pascal Bourgault `_. - - Added :py:meth:`xarray.infer_freq` for extending frequency inferring to CFTime indexes and data (:pull:`4033`). - By `Pascal Bourgault `_. - - ``chunks='auto'`` is now supported in the ``chunks`` argument of - :py:meth:`Dataset.chunk`. (:issue:`4055`) - By `Andrew Williams `_ - - Control over attributes of result in :py:func:`merge`, :py:func:`concat`, - :py:func:`combine_by_coords` and :py:func:`combine_nested` using - combine_attrs keyword argument. (:issue:`3865`, :pull:`3877`) - By `John Omotani `_ - - `missing_dims` argument to :py:meth:`Dataset.isel`, - :py:meth:`DataArray.isel` and :py:meth:`Variable.isel` to allow replacing - the exception when a dimension passed to ``isel`` is not present with a - warning, or just ignore the dimension. (:issue:`3866`, :pull:`3923`) - By `John Omotani `_ - - Support dask handling for :py:meth:`DataArray.idxmax`, :py:meth:`DataArray.idxmin`, - :py:meth:`Dataset.idxmax`, :py:meth:`Dataset.idxmin`. (:pull:`3922`, :pull:`4135`) - By `Kai Mühlbauer `_ and `Pascal Bourgault `_. - - More support for unit aware arrays with pint (:pull:`3643`, :pull:`3975`, :pull:`4163`) - By `Justus Magin `_. - - Support overriding existing variables in ``to_zarr()`` with ``mode='a'`` even - without ``append_dim``, as long as dimension sizes do not change. - By `Stephan Hoyer `_. - - Allow plotting of boolean arrays. (:pull:`3766`) - By `Marek Jacob `_ - - Enable using MultiIndex levels as coordinates in 1D and 2D plots (:issue:`3927`). - By `Mathias Hauser `_. - - A ``days_in_month`` accessor for :py:class:`xarray.CFTimeIndex`, analogous to - the ``days_in_month`` accessor for a :py:class:`pandas.DatetimeIndex`, which - returns the days in the month each datetime in the index. Now days in month - weights for both standard and non-standard calendars can be obtained using - the :py:class:`~core.accessor_dt.DatetimeAccessor` (:pull:`3935`). This - feature requires cftime version 1.1.0 or greater. By - `Spencer Clark `_. - - For the netCDF3 backend, added dtype coercions for unsigned integer types. - (:issue:`4014`, :pull:`4018`) - By `Yunus Sevinchan `_ - - :py:meth:`map_blocks` now accepts a ``template`` kwarg. This allows use cases - where the result of a computation could not be inferred automatically. - By `Deepak Cherian `_ - - :py:meth:`map_blocks` can now handle dask-backed xarray objects in ``args``. (:pull:`3818`) - By `Deepak Cherian `_ - - Add keyword ``decode_timedelta`` to :py:func:`xarray.open_dataset`, - (:py:func:`xarray.open_dataarray`, :py:func:`xarray.open_dataarray`, - :py:func:`xarray.decode_cf`) that allows to disable/enable the decoding of timedeltas - independently of time decoding (:issue:`1621`) - `Aureliana Barghini `_ - - Enhancements - ~~~~~~~~~~~~ - - Performance improvement of :py:meth:`DataArray.interp` and :py:func:`Dataset.interp` - We performs independant interpolation sequentially rather than interpolating in - one large multidimensional space. (:issue:`2223`) - By `Keisuke Fujii `_. - - :py:meth:`DataArray.interp` now support interpolations over chunked dimensions (:pull:`4155`). By `Alexandre Poux `_. - - Major performance improvement for :py:meth:`Dataset.from_dataframe` when the - dataframe has a MultiIndex (:pull:`4184`). - By `Stephan Hoyer `_. - - :py:meth:`DataArray.reset_index` and :py:meth:`Dataset.reset_index` now keep - coordinate attributes (:pull:`4103`). By `Oriol Abril `_. - - Axes kwargs such as ``facecolor`` can now be passed to :py:meth:`DataArray.plot` in ``subplot_kws``. - This works for both single axes plots and FacetGrid plots. - By `Raphael Dussin `_. - - Array items with long string reprs are now limited to a - reasonable width (:pull:`3900`) - By `Maximilian Roos `_ - - Large arrays whose numpy reprs would have greater than 40 lines are now - limited to a reasonable length. - (:pull:`3905`) - By `Maximilian Roos `_ - - Bug fixes - ~~~~~~~~~ - - Fix errors combining attrs in :py:func:`open_mfdataset` (:issue:`4009`, :pull:`4173`) - By `John Omotani `_ - - If groupby receives a ``DataArray`` with name=None, assign a default name (:issue:`158`) - By `Phil Butcher `_. - - Support dark mode in VS code (:issue:`4024`) - By `Keisuke Fujii `_. - - Fix bug when converting multiindexed Pandas objects to sparse xarray objects. (:issue:`4019`) - By `Deepak Cherian `_. - - ``ValueError`` is raised when ``fill_value`` is not a scalar in :py:meth:`full_like`. (:issue:`3977`) - By `Huite Bootsma `_. - - Fix wrong order in converting a ``pd.Series`` with a MultiIndex to ``DataArray``. - (:issue:`3951`, :issue:`4186`) - By `Keisuke Fujii `_ and `Stephan Hoyer `_. - - Fix renaming of coords when one or more stacked coords is not in - sorted order during stack+groupby+apply operations. (:issue:`3287`, - :pull:`3906`) By `Spencer Hill `_ - - Fix a regression where deleting a coordinate from a copied :py:class:`DataArray` - can affect the original :py:class:`DataArray`. (:issue:`3899`, :pull:`3871`) - By `Todd Jennings `_ - - Fix :py:class:`~xarray.plot.FacetGrid` plots with a single contour. (:issue:`3569`, :pull:`3915`). - By `Deepak Cherian `_ - - Use divergent colormap if ``levels`` spans 0. (:issue:`3524`) - By `Deepak Cherian `_ - - Fix :py:class:`~xarray.plot.FacetGrid` when ``vmin == vmax``. (:issue:`3734`) - By `Deepak Cherian `_ - - Fix plotting when ``levels`` is a scalar and ``norm`` is provided. (:issue:`3735`) - By `Deepak Cherian `_ - - Fix bug where plotting line plots with 2D coordinates depended on dimension - order. (:issue:`3933`) - By `Tom Nicholas `_. - - Fix ``RasterioDeprecationWarning`` when using a ``vrt`` in ``open_rasterio``. (:issue:`3964`) - By `Taher Chegini `_. - - Fix ``AttributeError`` on displaying a :py:class:`Variable` - in a notebook context. (:issue:`3972`, :pull:`3973`) - By `Ian Castleden `_. - - Fix bug causing :py:meth:`DataArray.interpolate_na` to always drop attributes, - and added `keep_attrs` argument. (:issue:`3968`) - By `Tom Nicholas `_. - - Fix bug in time parsing failing to fall back to cftime. This was causing time - variables with a time unit of `'msecs'` to fail to parse. (:pull:`3998`) - By `Ryan May `_. - - Fix weighted mean when passing boolean weights (:issue:`4074`). - By `Mathias Hauser `_. - - Fix html repr in untrusted notebooks: fallback to plain text repr. (:pull:`4053`) - By `Benoit Bovy `_. - - Fix :py:meth:`DataArray.to_unstacked_dataset` for single-dimension variables. (:issue:`4049`) - By `Deepak Cherian `_ - - Fix :py:func:`open_rasterio` for ``WarpedVRT`` with specified ``src_crs``. (:pull:`4104`) - By `Dave Cole `_. - - Documentation - ~~~~~~~~~~~~~ - - update the docstring of :py:meth:`DataArray.assign_coords` : clarify how to - add a new coordinate to an existing dimension and illustrative example - (:issue:`3952`, :pull:`3958`) By - `Etienne Combrisson `_. - - update the docstring of :py:meth:`Dataset.diff` and - :py:meth:`DataArray.diff` so it does document the ``dim`` - parameter as required. (:issue:`1040`, :pull:`3909`) - By `Justus Magin `_. - - Updated :doc:`Calculating Seasonal Averages from Timeseries of Monthly Means - ` example notebook to take advantage of the new - ``days_in_month`` accessor for :py:class:`xarray.CFTimeIndex` - (:pull:`3935`). By `Spencer Clark `_. - - Updated the list of current core developers. (:issue:`3892`) - By `Tom Nicholas `_. - - Add example for multi-dimensional extrapolation and note different behavior - of ``kwargs`` in :py:meth:`Dataset.interp` and :py:meth:`DataArray.interp` - for 1-d and n-d interpolation (:pull:`3956`). - By `Matthias Riße `_. - - Apply ``black`` to all the code in the documentation (:pull:`4012`) - By `Justus Magin `_. - - Narrative documentation now describes :py:meth:`map_blocks`: :ref:`dask.automatic-parallelization`. - By `Deepak Cherian `_. - - Document ``.plot``, ``.dt``, ``.str`` accessors the way they are called. (:issue:`3625`, :pull:`3988`) - By `Justus Magin `_. - - Add documentation for the parameters and return values of :py:meth:`DataArray.sel`. - By `Justus Magin `_. - - Internal Changes - ~~~~~~~~~~~~~~~~ - - Raise more informative error messages for chunk size conflicts when writing to zarr files. - By `Deepak Cherian `_. - - Run the ``isort`` pre-commit hook only on python source files - and update the ``flake8`` version. (:issue:`3750`, :pull:`3711`) - By `Justus Magin `_. - - Add `blackdoc `_ to the list of - checkers for development. (:pull:`4177`) - By `Justus Magin `_. - - Add a CI job that runs the tests with every optional dependency - except ``dask``. (:issue:`3794`, :pull:`3919`) - By `Justus Magin `_. - - Use ``async`` / ``await`` for the asynchronous distributed - tests. (:issue:`3987`, :pull:`3989`) - By `Justus Magin `_. - - Various internal code clean-ups (:pull:`4026`, :pull:`4038`). - By `Prajjwal Nijhara `_. - - .. _whats-new.0.15.1: - - v0.15.1 (23 Mar 2020) - --------------------- - - This release brings many new features such as :py:meth:`Dataset.weighted` methods for weighted array - reductions, a new jupyter repr by default, and the start of units integration with pint. There's also - the usual batch of usability improvements, documentation additions, and bug fixes. - - Breaking changes - ~~~~~~~~~~~~~~~~ - - - Raise an error when assigning to the ``.values`` or ``.data`` attribute of - dimension coordinates i.e. ``IndexVariable`` objects. This has been broken since - v0.12.0. Please use :py:meth:`DataArray.assign_coords` or :py:meth:`Dataset.assign_coords` - instead. (:issue:`3470`, :pull:`3862`) - By `Deepak Cherian `_ - - New Features - ~~~~~~~~~~~~ - - - Weighted array reductions are now supported via the new :py:meth:`DataArray.weighted` - and :py:meth:`Dataset.weighted` methods. See :ref:`comput.weighted`. (:issue:`422`, :pull:`2922`). - By `Mathias Hauser `_. - - The new jupyter notebook repr (``Dataset._repr_html_`` and - ``DataArray._repr_html_``) (introduced in 0.14.1) is now on by default. To - disable, use ``xarray.set_options(display_style="text")``. - By `Julia Signell `_. - - Added support for :py:class:`pandas.DatetimeIndex`-style rounding of - ``cftime.datetime`` objects directly via a :py:class:`CFTimeIndex` or via the - :py:class:`~core.accessor_dt.DatetimeAccessor`. - By `Spencer Clark `_ - - Support new h5netcdf backend keyword `phony_dims` (available from h5netcdf - v0.8.0 for :py:class:`~xarray.backends.H5NetCDFStore`. - By `Kai Mühlbauer `_. - - Add partial support for unit aware arrays with pint. (:pull:`3706`, :pull:`3611`) - By `Justus Magin `_. - - :py:meth:`Dataset.groupby` and :py:meth:`DataArray.groupby` now raise a - `TypeError` on multiple string arguments. Receiving multiple string arguments - often means a user is attempting to pass multiple dimensions as separate - arguments and should instead pass a single list of dimensions. - (:pull:`3802`) - By `Maximilian Roos `_ - - :py:func:`map_blocks` can now apply functions that add new unindexed dimensions. - By `Deepak Cherian `_ - - An ellipsis (``...``) is now supported in the ``dims`` argument of - :py:meth:`Dataset.stack` and :py:meth:`DataArray.stack`, meaning all - unlisted dimensions, similar to its meaning in :py:meth:`DataArray.transpose`. - (:pull:`3826`) - By `Maximilian Roos `_ - - :py:meth:`Dataset.where` and :py:meth:`DataArray.where` accept a lambda as a - first argument, which is then called on the input; replicating pandas' behavior. - By `Maximilian Roos `_. - - ``skipna`` is available in :py:meth:`Dataset.quantile`, :py:meth:`DataArray.quantile`, - :py:meth:`core.groupby.DatasetGroupBy.quantile`, :py:meth:`core.groupby.DataArrayGroupBy.quantile` - (:issue:`3843`, :pull:`3844`) - By `Aaron Spring `_. - - Add a diff summary for `testing.assert_allclose`. (:issue:`3617`, :pull:`3847`) - By `Justus Magin `_. - - Bug fixes - ~~~~~~~~~ - - - Fix :py:meth:`Dataset.interp` when indexing array shares coordinates with the - indexed variable (:issue:`3252`). - By `David Huard `_. - - Fix recombination of groups in :py:meth:`Dataset.groupby` and - :py:meth:`DataArray.groupby` when performing an operation that changes the - size of the groups along the grouped dimension. By `Eric Jansen - `_. - - Fix use of multi-index with categorical values (:issue:`3674`). - By `Matthieu Ancellin `_. - - Fix alignment with ``join="override"`` when some dimensions are unindexed. (:issue:`3681`). - By `Deepak Cherian `_. - - Fix :py:meth:`Dataset.swap_dims` and :py:meth:`DataArray.swap_dims` producing - index with name reflecting the previous dimension name instead of the new one - (:issue:`3748`, :pull:`3752`). By `Joseph K Aicher - `_. - - Use ``dask_array_type`` instead of ``dask_array.Array`` for type - checking. (:issue:`3779`, :pull:`3787`) - By `Justus Magin `_. - - :py:func:`concat` can now handle coordinate variables only present in one of - the objects to be concatenated when ``coords="different"``. - By `Deepak Cherian `_. - - xarray now respects the over, under and bad colors if set on a provided colormap. - (:issue:`3590`, :pull:`3601`) - By `johnomotani `_. - - ``coarsen`` and ``rolling`` now respect ``xr.set_options(keep_attrs=True)`` - to preserve attributes. :py:meth:`Dataset.coarsen` accepts a keyword - argument ``keep_attrs`` to change this setting. (:issue:`3376`, - :pull:`3801`) By `Andrew Thomas `_. - - Delete associated indexes when deleting coordinate variables. (:issue:`3746`). - By `Deepak Cherian `_. - - Fix :py:meth:`Dataset.to_zarr` when using ``append_dim`` and ``group`` - simultaneously. (:issue:`3170`). By `Matthias Meyer `_. - - Fix html repr on :py:class:`Dataset` with non-string keys (:pull:`3807`). - By `Maximilian Roos `_. - - Documentation - ~~~~~~~~~~~~~ - - - Fix documentation of :py:class:`DataArray` removing the deprecated mention - that when omitted, `dims` are inferred from a `coords`-dict. (:pull:`3821`) - By `Sander van Rijn `_. - - Improve the :py:func:`where` docstring. - By `Maximilian Roos `_ - - Update the installation instructions: only explicitly list recommended dependencies - (:issue:`3756`). - By `Mathias Hauser `_. - - Internal Changes - ~~~~~~~~~~~~~~~~ - - - Remove the internal ``import_seaborn`` function which handled the deprecation of - the ``seaborn.apionly`` entry point (:issue:`3747`). - By `Mathias Hauser `_. - - Don't test pint integration in combination with datetime objects. (:issue:`3778`, :pull:`3788`) - By `Justus Magin `_. - - Change test_open_mfdataset_list_attr to only run with dask installed - (:issue:`3777`, :pull:`3780`). - By `Bruno Pagani `_. - - Preserve the ability to index with ``method="nearest"`` with a - :py:class:`CFTimeIndex` with pandas versions greater than 1.0.1 - (:issue:`3751`). By `Spencer Clark `_. - - Greater flexibility and improved test coverage of subtracting various types - of objects from a :py:class:`CFTimeIndex`. By `Spencer Clark - `_. - - Update Azure CI MacOS image, given pending removal. - By `Maximilian Roos `_ - - Remove xfails for scipy 1.0.1 for tests that append to netCDF files (:pull:`3805`). - By `Mathias Hauser `_. - - Remove conversion to ``pandas.Panel``, given its removal in pandas - in favor of xarray's objects. - By `Maximilian Roos `_ - - .. _whats-new.0.15.0: - - - v0.15.0 (30 Jan 2020) - --------------------- - - This release brings many improvements to xarray's documentation: our examples are now binderized notebooks (`click here `_) - and we have new example notebooks from our SciPy 2019 sprint (many thanks to our contributors!). - - This release also features many API improvements such as a new - :py:class:`~core.accessor_dt.TimedeltaAccessor` and support for :py:class:`CFTimeIndex` in - :py:meth:`~DataArray.interpolate_na`); as well as many bug fixes. - - Breaking changes - ~~~~~~~~~~~~~~~~ - - Bumped minimum tested versions for dependencies: - - - numpy 1.15 - - pandas 0.25 - - dask 2.2 - - distributed 2.2 - - scipy 1.3 - - - Remove ``compat`` and ``encoding`` kwargs from ``DataArray``, which - have been deprecated since 0.12. (:pull:`3650`). - Instead, specify the ``encoding`` kwarg when writing to disk or set - the :py:attr:`DataArray.encoding` attribute directly. - By `Maximilian Roos `_. - - :py:func:`xarray.dot`, :py:meth:`DataArray.dot`, and the ``@`` operator now - use ``align="inner"`` (except when ``xarray.set_options(arithmetic_join="exact")``; - :issue:`3694`) by `Mathias Hauser `_. - - New Features - ~~~~~~~~~~~~ - - Implement :py:meth:`DataArray.pad` and :py:meth:`Dataset.pad`. (:issue:`2605`, :pull:`3596`). - By `Mark Boer `_. - - :py:meth:`DataArray.sel` and :py:meth:`Dataset.sel` now support :py:class:`pandas.CategoricalIndex`. (:issue:`3669`) - By `Keisuke Fujii `_. - - Support using an existing, opened h5netcdf ``File`` with - :py:class:`~xarray.backends.H5NetCDFStore`. This permits creating an - :py:class:`~xarray.Dataset` from a h5netcdf ``File`` that has been opened - using other means (:issue:`3618`). - By `Kai Mühlbauer `_. - - Implement ``median`` and ``nanmedian`` for dask arrays. This works by rechunking - to a single chunk along all reduction axes. (:issue:`2999`). - By `Deepak Cherian `_. - - :py:func:`~xarray.concat` now preserves attributes from the first Variable. - (:issue:`2575`, :issue:`2060`, :issue:`1614`) - By `Deepak Cherian `_. - - :py:meth:`Dataset.quantile`, :py:meth:`DataArray.quantile` and ``GroupBy.quantile`` - now work with dask Variables. - By `Deepak Cherian `_. - - Added the ``count`` reduction method to both :py:class:`~core.rolling.DatasetCoarsen` - and :py:class:`~core.rolling.DataArrayCoarsen` objects. (:pull:`3500`) - By `Deepak Cherian `_ - - Add ``meta`` kwarg to :py:func:`~xarray.apply_ufunc`; - this is passed on to :py:func:`dask.array.blockwise`. (:pull:`3660`) - By `Deepak Cherian `_. - - Add ``attrs_file`` option in :py:func:`~xarray.open_mfdataset` to choose the - source file for global attributes in a multi-file dataset (:issue:`2382`, - :pull:`3498`). By `Julien Seguinot `_. - - :py:meth:`Dataset.swap_dims` and :py:meth:`DataArray.swap_dims` - now allow swapping to dimension names that don't exist yet. (:pull:`3636`) - By `Justus Magin `_. - - Extend :py:class:`~core.accessor_dt.DatetimeAccessor` properties - and support ``.dt`` accessor for timedeltas - via :py:class:`~core.accessor_dt.TimedeltaAccessor` (:pull:`3612`) - By `Anderson Banihirwe `_. - - Improvements to interpolating along time axes (:issue:`3641`, :pull:`3631`). - By `David Huard `_. - - - Support :py:class:`CFTimeIndex` in :py:meth:`DataArray.interpolate_na` - - define 1970-01-01 as the default offset for the interpolation index for both - :py:class:`pandas.DatetimeIndex` and :py:class:`CFTimeIndex`, - - use microseconds in the conversion from timedelta objects to floats to avoid - overflow errors. - - Bug fixes - ~~~~~~~~~ - - Applying a user-defined function that adds new dimensions using :py:func:`apply_ufunc` - and ``vectorize=True`` now works with ``dask > 2.0``. (:issue:`3574`, :pull:`3660`). - By `Deepak Cherian `_. - - Fix :py:meth:`~xarray.combine_by_coords` to allow for combining incomplete - hypercubes of Datasets (:issue:`3648`). By `Ian Bolliger - `_. - - Fix :py:func:`~xarray.combine_by_coords` when combining cftime coordinates - which span long time intervals (:issue:`3535`). By `Spencer Clark - `_. - - Fix plotting with transposed 2D non-dimensional coordinates. (:issue:`3138`, :pull:`3441`) - By `Deepak Cherian `_. - - :py:meth:`plot.FacetGrid.set_titles` can now replace existing row titles of a - :py:class:`~xarray.plot.FacetGrid` plot. In addition :py:class:`~xarray.plot.FacetGrid` gained - two new attributes: :py:attr:`~xarray.plot.FacetGrid.col_labels` and - :py:attr:`~xarray.plot.FacetGrid.row_labels` contain :py:class:`matplotlib.text.Text` handles for both column and - row labels. These can be used to manually change the labels. - By `Deepak Cherian `_. - - Fix issue with Dask-backed datasets raising a ``KeyError`` on some computations involving :py:func:`map_blocks` (:pull:`3598`). - By `Tom Augspurger `_. - - Ensure :py:meth:`Dataset.quantile`, :py:meth:`DataArray.quantile` issue the correct error - when ``q`` is out of bounds (:issue:`3634`) by `Mathias Hauser `_. - - Fix regression in xarray 0.14.1 that prevented encoding times with certain - ``dtype``, ``_FillValue``, and ``missing_value`` encodings (:issue:`3624`). - By `Spencer Clark `_ - - Raise an error when trying to use :py:meth:`Dataset.rename_dims` to - rename to an existing name (:issue:`3438`, :pull:`3645`) - By `Justus Magin `_. - - :py:meth:`Dataset.rename`, :py:meth:`DataArray.rename` now check for conflicts with - MultiIndex level names. - - :py:meth:`Dataset.merge` no longer fails when passed a :py:class:`DataArray` instead of a :py:class:`Dataset`. - By `Tom Nicholas `_. - - Fix a regression in :py:meth:`Dataset.drop`: allow passing any - iterable when dropping variables (:issue:`3552`, :pull:`3693`) - By `Justus Magin `_. - - Fixed errors emitted by ``mypy --strict`` in modules that import xarray. - (:issue:`3695`) by `Guido Imperiale `_. - - Allow plotting of binned coordinates on the y axis in :py:meth:`plot.line` - and :py:meth:`plot.step` plots (:issue:`3571`, - :pull:`3685`) by `Julien Seguinot `_. - - setuptools is now marked as a dependency of xarray - (:pull:`3628`) by `Richard Höchenberger `_. - - Documentation - ~~~~~~~~~~~~~ - - Switch doc examples to use `nbsphinx `_ and replace - ``sphinx_gallery`` scripts with Jupyter notebooks. (:pull:`3105`, :pull:`3106`, :pull:`3121`) - By `Ryan Abernathey `_. - - Added :doc:`example notebook ` demonstrating use of xarray with - Regional Ocean Modeling System (ROMS) ocean hydrodynamic model output. (:pull:`3116`) - By `Robert Hetland `_. - - Added :doc:`example notebook ` demonstrating the visualization of - ERA5 GRIB data. (:pull:`3199`) - By `Zach Bruick `_ and - `Stephan Siemen `_. - - Added examples for :py:meth:`DataArray.quantile`, :py:meth:`Dataset.quantile` and - ``GroupBy.quantile``. (:pull:`3576`) - By `Justus Magin `_. - - Add new :doc:`example notebook ` example notebook demonstrating - vectorization of a 1D function using :py:func:`apply_ufunc` , dask and numba. - By `Deepak Cherian `_. - - Added example for :py:func:`~xarray.map_blocks`. (:pull:`3667`) - By `Riley X. Brady `_. - - Internal Changes - ~~~~~~~~~~~~~~~~ - - Make sure dask names change when rechunking by different chunk sizes. Conversely, make sure they - stay the same when rechunking by the same chunk size. (:issue:`3350`) - By `Deepak Cherian `_. - - 2x to 5x speed boost (on small arrays) for :py:meth:`Dataset.isel`, - :py:meth:`DataArray.isel`, and :py:meth:`DataArray.__getitem__` when indexing by int, - slice, list of int, scalar ndarray, or 1-dimensional ndarray. - (:pull:`3533`) by `Guido Imperiale `_. - - Removed internal method ``Dataset._from_vars_and_coord_names``, - which was dominated by ``Dataset._construct_direct``. (:pull:`3565`) - By `Maximilian Roos `_. - - Replaced versioneer with setuptools-scm. Moved contents of setup.py to setup.cfg. - Removed pytest-runner from setup.py, as per deprecation notice on the pytest-runner - project. (:pull:`3714`) by `Guido Imperiale `_. - - Use of isort is now enforced by CI. - (:pull:`3721`) by `Guido Imperiale `_ - - - .. _whats-new.0.14.1: - - v0.14.1 (19 Nov 2019) - --------------------- - - Breaking changes - ~~~~~~~~~~~~~~~~ - - - Broken compatibility with ``cftime < 1.0.3`` . By `Deepak Cherian `_. - - .. warning:: - - cftime version 1.0.4 is broken - (`cftime/126 `_); - please use version 1.0.4.2 instead. - - - All leftover support for dates from non-standard calendars through ``netcdftime``, the - module included in versions of netCDF4 prior to 1.4 that eventually became the - `cftime `_ package, has been removed in favor of relying solely on - the standalone ``cftime`` package (:pull:`3450`). - By `Spencer Clark `_. - - New Features - ~~~~~~~~~~~~ - - Added the ``sparse`` option to :py:meth:`~xarray.DataArray.unstack`, - :py:meth:`~xarray.Dataset.unstack`, :py:meth:`~xarray.DataArray.reindex`, - :py:meth:`~xarray.Dataset.reindex` (:issue:`3518`). - By `Keisuke Fujii `_. - - Added the ``fill_value`` option to :py:meth:`DataArray.unstack` and - :py:meth:`Dataset.unstack` (:issue:`3518`, :pull:`3541`). - By `Keisuke Fujii `_. - - Added the ``max_gap`` kwarg to :py:meth:`~xarray.DataArray.interpolate_na` and - :py:meth:`~xarray.Dataset.interpolate_na`. This controls the maximum size of the data - gap that will be filled by interpolation. By `Deepak Cherian `_. - - Added :py:meth:`Dataset.drop_sel` & :py:meth:`DataArray.drop_sel` for dropping labels. - :py:meth:`Dataset.drop_vars` & :py:meth:`DataArray.drop_vars` have been added for - dropping variables (including coordinates). The existing :py:meth:`Dataset.drop` & - :py:meth:`DataArray.drop` methods remain as a backward compatible - option for dropping either labels or variables, but using the more specific methods is encouraged. - (:pull:`3475`) - By `Maximilian Roos `_ - - Added :py:meth:`Dataset.map` & ``GroupBy.map`` & ``Resample.map`` for - mapping / applying a function over each item in the collection, reflecting the widely used - and least surprising name for this operation. - The existing ``apply`` methods remain for backward compatibility, though using the ``map`` - methods is encouraged. - (:pull:`3459`) - By `Maximilian Roos `_ - - :py:meth:`Dataset.transpose` and :py:meth:`DataArray.transpose` now support an ellipsis (``...``) - to represent all 'other' dimensions. For example, to move one dimension to the front, - use ``.transpose('x', ...)``. (:pull:`3421`) - By `Maximilian Roos `_ - - Changed ``xr.ALL_DIMS`` to equal python's ``Ellipsis`` (``...``), and changed internal usages to use - ``...`` directly. As before, you can use this to instruct a ``groupby`` operation - to reduce over all dimensions. While we have no plans to remove ``xr.ALL_DIMS``, we suggest - using ``...``. (:pull:`3418`) - By `Maximilian Roos `_ - - :py:func:`xarray.dot`, and :py:meth:`DataArray.dot` now support the - ``dims=...`` option to sum over the union of dimensions of all input arrays - (:issue:`3423`) by `Mathias Hauser `_. - - Added new ``Dataset._repr_html_`` and ``DataArray._repr_html_`` to improve - representation of objects in Jupyter. By default this feature is turned off - for now. Enable it with ``xarray.set_options(display_style="html")``. - (:pull:`3425`) by `Benoit Bovy `_ and - `Julia Signell `_. - - Implement `dask deterministic hashing - `_ - for xarray objects. Note that xarray objects with a dask.array backend already used - deterministic hashing in previous releases; this change implements it when whole - xarray objects are embedded in a dask graph, e.g. when :py:meth:`DataArray.map_blocks` is - invoked. (:issue:`3378`, :pull:`3446`, :pull:`3515`) - By `Deepak Cherian `_ and - `Guido Imperiale `_. - - Add the documented-but-missing :py:meth:`~core.groupby.DatasetGroupBy.quantile`. - - xarray now respects the ``DataArray.encoding["coordinates"]`` attribute when writing to disk. - See :ref:`io.coordinates` for more. (:issue:`3351`, :pull:`3487`) - By `Deepak Cherian `_. - - Add the documented-but-missing :py:meth:`~core.groupby.DatasetGroupBy.quantile`. - (:issue:`3525`, :pull:`3527`). By `Justus Magin `_. - - Bug fixes - ~~~~~~~~~ - - Ensure an index of type ``CFTimeIndex`` is not converted to a ``DatetimeIndex`` when - calling :py:meth:`Dataset.rename`, :py:meth:`Dataset.rename_dims` and :py:meth:`Dataset.rename_vars`. - By `Mathias Hauser `_. (:issue:`3522`). - - Fix a bug in :py:meth:`DataArray.set_index` in case that an existing dimension becomes a level - variable of MultiIndex. (:pull:`3520`). By `Keisuke Fujii `_. - - Harmonize ``_FillValue``, ``missing_value`` during encoding and decoding steps. (:pull:`3502`) - By `Anderson Banihirwe `_. - - Fix regression introduced in v0.14.0 that would cause a crash if dask is installed - but cloudpickle isn't (:issue:`3401`) by `Rhys Doyle `_ - - Fix grouping over variables with NaNs. (:issue:`2383`, :pull:`3406`). - By `Deepak Cherian `_. - - Make alignment and concatenation significantly more efficient by using dask names to compare dask - objects prior to comparing values after computation. This change makes it more convenient to carry - around large non-dimensional coordinate variables backed by dask arrays. Existing workarounds involving - ``reset_coords(drop=True)`` should now be unnecessary in most cases. - (:issue:`3068`, :issue:`3311`, :issue:`3454`, :pull:`3453`). - By `Deepak Cherian `_. - - Add support for cftime>=1.0.4. By `Anderson Banihirwe `_. - - Rolling reduction operations no longer compute dask arrays by default. (:issue:`3161`). - In addition, the ``allow_lazy`` kwarg to ``reduce`` is deprecated. - By `Deepak Cherian `_. - - Fix ``GroupBy.reduce`` when reducing over multiple dimensions. - (:issue:`3402`). By `Deepak Cherian `_ - - Allow appending datetime and bool data variables to zarr stores. - (:issue:`3480`). By `Akihiro Matsukawa `_. - - Add support for numpy >=1.18 (); bugfix mean() on datetime64 arrays on dask backend - (:issue:`3409`, :pull:`3537`). By `Guido Imperiale `_. - - Add support for pandas >=0.26 (:issue:`3440`). - By `Deepak Cherian `_. - - Add support for pseudonetcdf >=3.1 (:pull:`3485`). - By `Barron Henderson `_. - - Documentation - ~~~~~~~~~~~~~ - - Fix leap year condition in `monthly means example `_. - By `Mickaël Lalande `_. - - Fix the documentation of :py:meth:`DataArray.resample` and - :py:meth:`Dataset.resample`, explicitly stating that a - datetime-like dimension is required. (:pull:`3400`) - By `Justus Magin `_. - - Update the :ref:`terminology` page to address multidimensional coordinates. (:pull:`3410`) - By `Jon Thielen `_. - - Fix the documentation of :py:meth:`Dataset.integrate` and - :py:meth:`DataArray.integrate` and add an example to - :py:meth:`Dataset.integrate`. (:pull:`3469`) - By `Justus Magin `_. - - Internal Changes - ~~~~~~~~~~~~~~~~ - - - Added integration tests against `pint `_. - (:pull:`3238`, :pull:`3447`, :pull:`3493`, :pull:`3508`) - by `Justus Magin `_. - - .. note:: - - At the moment of writing, these tests *as well as the ability to use pint in general* - require `a highly experimental version of pint - `_ (install with - ``pip install git+https://github.com/andrewgsavage/pint.git@refs/pull/6/head)``. - Even with it, interaction with non-numpy array libraries, e.g. dask or sparse, is broken. - - - Use Python 3.6 idioms throughout the codebase. (:pull:`3419`) - By `Maximilian Roos `_ - - - Run basic CI tests on Python 3.8. (:pull:`3477`) - By `Maximilian Roos `_ - - - Enable type checking on default sentinel values (:pull:`3472`) - By `Maximilian Roos `_ - - - Add ``Variable._replace`` for simpler replacing of a subset of attributes (:pull:`3472`) - By `Maximilian Roos `_ - - .. _whats-new.0.14.0: - - v0.14.0 (14 Oct 2019) - --------------------- - - Breaking changes - ~~~~~~~~~~~~~~~~ - - This release introduces a rolling policy for minimum dependency versions: - :ref:`mindeps_policy`. - - Several minimum versions have been increased: - - ============ ================== ==== - Package Old New - ============ ================== ==== - Python 3.5.3 3.6 - numpy 1.12 1.14 - pandas 0.19.2 0.24 - dask 0.16 (tested: 2.4) 1.2 - bottleneck 1.1 (tested: 1.2) 1.2 - matplotlib 1.5 (tested: 3.1) 3.1 - ============ ================== ==== - - Obsolete patch versions (x.y.Z) are not tested anymore. - The oldest supported versions of all optional dependencies are now covered by - automated tests (before, only the very latest versions were tested). - - (:issue:`3222`, :issue:`3293`, :issue:`3340`, :issue:`3346`, :issue:`3358`). - By `Guido Imperiale `_. - - - Dropped the ``drop=False`` optional parameter from :py:meth:`Variable.isel`. - It was unused and doesn't make sense for a Variable. (:pull:`3375`). - By `Guido Imperiale `_. - - - Remove internal usage of :py:class:`collections.OrderedDict`. After dropping support for - Python <=3.5, most uses of ``OrderedDict`` in Xarray were no longer necessary. We - have removed the internal use of the ``OrderedDict`` in favor of Python's builtin - ``dict`` object which is now ordered itself. This change will be most obvious when - interacting with the ``attrs`` property on Dataset and DataArray objects. - (:issue:`3380`, :pull:`3389`). By `Joe Hamman `_. - - New functions/methods - ~~~~~~~~~~~~~~~~~~~~~ - - - Added :py:func:`~xarray.map_blocks`, modeled after :py:func:`dask.array.map_blocks`. - Also added :py:meth:`Dataset.unify_chunks`, :py:meth:`DataArray.unify_chunks` and - :py:meth:`testing.assert_chunks_equal`. (:pull:`3276`). - By `Deepak Cherian `_ and - `Guido Imperiale `_. - - Enhancements - ~~~~~~~~~~~~ - - - ``core.groupby.GroupBy`` enhancements. By `Deepak Cherian `_. - - - Added a repr (:pull:`3344`). Example:: - - >>> da.groupby("time.season") - DataArrayGroupBy, grouped over 'season' - 4 groups with labels 'DJF', 'JJA', 'MAM', 'SON' - - - Added a ``GroupBy.dims`` property that mirrors the dimensions - of each group (:issue:`3344`). - - - Speed up :py:meth:`Dataset.isel` up to 33% and :py:meth:`DataArray.isel` up to 25% for small - arrays (:issue:`2799`, :pull:`3375`). By - `Guido Imperiale `_. - - Bug fixes - ~~~~~~~~~ - - Reintroduce support for :mod:`weakref` (broken in v0.13.0). Support has been - reinstated for :py:class:`~xarray.DataArray` and :py:class:`~xarray.Dataset` objects only. - Internal xarray objects remain unaddressable by weakref in order to save memory - (:issue:`3317`). By `Guido Imperiale `_. - - Line plots with the ``x`` or ``y`` argument set to a 1D non-dimensional coord - now plot the correct data for 2D DataArrays - (:issue:`3334`). By `Tom Nicholas `_. - - Make :py:func:`~xarray.concat` more robust when merging variables present in some datasets but - not others (:issue:`508`). By `Deepak Cherian `_. - - The default behaviour of reducing across all dimensions for - :py:class:`~xarray.core.groupby.DataArrayGroupBy` objects has now been properly removed - as was done for :py:class:`~xarray.core.groupby.DatasetGroupBy` in 0.13.0 (:issue:`3337`). - Use ``xarray.ALL_DIMS`` if you need to replicate previous behaviour. - Also raise nicer error message when no groups are created (:issue:`1764`). - By `Deepak Cherian `_. - - Fix error in concatenating unlabeled dimensions (:pull:`3362`). - By `Deepak Cherian `_. - - Warn if the ``dim`` kwarg is passed to rolling operations. This is redundant since a dimension is - specified when the :py:class:`~core.rolling.DatasetRolling` or :py:class:`~core.rolling.DataArrayRolling` object is created. - (:pull:`3362`). By `Deepak Cherian `_. - - Documentation - ~~~~~~~~~~~~~ - - - Created a glossary of important xarray terms (:issue:`2410`, :pull:`3352`). - By `Gregory Gundersen `_. - - Created a "How do I..." section (:ref:`howdoi`) for solutions to common questions. (:pull:`3357`). - By `Deepak Cherian `_. - - Add examples for :py:meth:`Dataset.swap_dims` and :py:meth:`DataArray.swap_dims` - (pull:`3331`, pull:`3331`). By `Justus Magin `_. - - Add examples for :py:meth:`align`, :py:meth:`merge`, :py:meth:`combine_by_coords`, - :py:meth:`full_like`, :py:meth:`zeros_like`, :py:meth:`ones_like`, :py:meth:`Dataset.pipe`, - :py:meth:`Dataset.assign`, :py:meth:`Dataset.reindex`, :py:meth:`Dataset.fillna` (:pull:`3328`). - By `Anderson Banihirwe `_. - - Fixed documentation to clean up an unwanted file created in ``ipython`` example - (:pull:`3353`). By `Gregory Gundersen `_. - - .. _whats-new.0.13.0: - - v0.13.0 (17 Sep 2019) - --------------------- - - This release includes many exciting changes: wrapping of - `NEP18 `_ compliant - numpy-like arrays; new :py:meth:`~Dataset.plot.scatter` plotting method that can scatter - two ``DataArrays`` in a ``Dataset`` against each other; support for converting pandas - DataFrames to xarray objects that wrap ``pydata/sparse``; and more! - - Breaking changes - ~~~~~~~~~~~~~~~~ - - - This release increases the minimum required Python version from 3.5.0 to 3.5.3 - (:issue:`3089`). By `Guido Imperiale `_. - - The ``isel_points`` and ``sel_points`` methods are removed, having been deprecated - since v0.10.0. These are redundant with the ``isel`` / ``sel`` methods. - See :ref:`vectorized_indexing` for the details - By `Maximilian Roos `_ - - The ``inplace`` kwarg for public methods now raises an error, having been deprecated - since v0.11.0. - By `Maximilian Roos `_ - - :py:func:`~xarray.concat` now requires the ``dim`` argument. Its ``indexers``, ``mode`` - and ``concat_over`` kwargs have now been removed. - By `Deepak Cherian `_ - - Passing a list of colors in ``cmap`` will now raise an error, having been deprecated since - v0.6.1. - - Most xarray objects now define ``__slots__``. This reduces overall RAM usage by ~22% - (not counting the underlying numpy buffers); on CPython 3.7/x64, a trivial DataArray - has gone down from 1.9kB to 1.5kB. - - Caveats: - - - Pickle streams produced by older versions of xarray can't be loaded using this - release, and vice versa. - - Any user code that was accessing the ``__dict__`` attribute of - xarray objects will break. The best practice to attach custom metadata to xarray - objects is to use the ``attrs`` dictionary. - - Any user code that defines custom subclasses of xarray classes must now explicitly - define ``__slots__`` itself. Subclasses that don't add any attributes must state so - by defining ``__slots__ = ()`` right after the class header. - Omitting ``__slots__`` will now cause a ``FutureWarning`` to be logged, and will raise an - error in a later release. - - (:issue:`3250`) by `Guido Imperiale `_. - - The default dimension for :py:meth:`Dataset.groupby`, :py:meth:`Dataset.resample`, - :py:meth:`DataArray.groupby` and :py:meth:`DataArray.resample` reductions is now the - grouping or resampling dimension. - - :py:meth:`DataArray.to_dataset` requires ``name`` to be passed as a kwarg (previously ambiguous - positional arguments were deprecated) - - Reindexing with variables of a different dimension now raise an error (previously deprecated) - - ``xarray.broadcast_array`` is removed (previously deprecated in favor of - :py:func:`~xarray.broadcast`) - - ``Variable.expand_dims`` is removed (previously deprecated in favor of - :py:meth:`Variable.set_dims`) - - New functions/methods - ~~~~~~~~~~~~~~~~~~~~~ - - - xarray can now wrap around any - `NEP18 `_ compliant - numpy-like library (important: read notes about ``NUMPY_EXPERIMENTAL_ARRAY_FUNCTION`` in - the above link). Added explicit test coverage for - `sparse `_. (:issue:`3117`, :issue:`3202`). - This requires `sparse>=0.8.0`. By `Nezar Abdennur `_ - and `Guido Imperiale `_. - - - :py:meth:`~Dataset.from_dataframe` and :py:meth:`~DataArray.from_series` now - support ``sparse=True`` for converting pandas objects into xarray objects - wrapping sparse arrays. This is particularly useful with sparsely populated - hierarchical indexes. (:issue:`3206`) - By `Stephan Hoyer `_. - - - The xarray package is now discoverable by mypy (although typing hints coverage is not - complete yet). mypy type checking is now enforced by CI. Libraries that depend on - xarray and use mypy can now remove from their setup.cfg the lines:: - - [mypy-xarray] - ignore_missing_imports = True - - (:issue:`2877`, :issue:`3088`, :issue:`3090`, :issue:`3112`, :issue:`3117`, - :issue:`3207`) - By `Guido Imperiale `_ - and `Maximilian Roos `_. - - - Added :py:meth:`DataArray.broadcast_like` and :py:meth:`Dataset.broadcast_like`. - By `Deepak Cherian `_ and `David Mertz - `_. - - - Dataset plotting API for visualizing dependencies between two DataArrays! - Currently only :py:meth:`Dataset.plot.scatter` is implemented. - By `Yohai Bar Sinai `_ and `Deepak Cherian `_ - - - Added :py:meth:`DataArray.head`, :py:meth:`DataArray.tail` and :py:meth:`DataArray.thin`; - as well as :py:meth:`Dataset.head`, :py:meth:`Dataset.tail` and :py:meth:`Dataset.thin` methods. - (:issue:`319`) By `Gerardo Rivera `_. - - Enhancements - ~~~~~~~~~~~~ - - - Multiple enhancements to :py:func:`~xarray.concat` and :py:func:`~xarray.open_mfdataset`. - By `Deepak Cherian `_ - - - Added ``compat='override'``. When merging, this option picks the variable from the first dataset - and skips all comparisons. - - - Added ``join='override'``. When aligning, this only checks that index sizes are equal among objects - and skips checking indexes for equality. - - - :py:func:`~xarray.concat` and :py:func:`~xarray.open_mfdataset` now support the ``join`` kwarg. - It is passed down to :py:func:`~xarray.align`. - - - :py:func:`~xarray.concat` now calls :py:func:`~xarray.merge` on variables that are not concatenated - (i.e. variables without ``concat_dim`` when ``data_vars`` or ``coords`` are ``"minimal"``). - :py:func:`~xarray.concat` passes its new ``compat`` kwarg down to :py:func:`~xarray.merge`. - (:issue:`2064`) - - Users can avoid a common bottleneck when using :py:func:`~xarray.open_mfdataset` on a large number of - files with variables that are known to be aligned and some of which need not be concatenated. - Slow equality comparisons can now be avoided, for e.g.:: - - data = xr.open_mfdataset(files, concat_dim='time', data_vars='minimal', - coords='minimal', compat='override', join='override') - - - In :py:meth:`~xarray.Dataset.to_zarr`, passing ``mode`` is not mandatory if - ``append_dim`` is set, as it will automatically be set to ``'a'`` internally. - By `David Brochart `_. - - - Added the ability to initialize an empty or full DataArray - with a single value. (:issue:`277`) - By `Gerardo Rivera `_. - - - :py:func:`~xarray.Dataset.to_netcdf()` now supports the ``invalid_netcdf`` kwarg when used - with ``engine="h5netcdf"``. It is passed to ``h5netcdf.File``. - By `Ulrich Herter `_. - - - ``xarray.Dataset.drop`` now supports keyword arguments; dropping index - labels by using both ``dim`` and ``labels`` or using a - :py:class:`~core.coordinates.DataArrayCoordinates` object are deprecated (:issue:`2910`). - By `Gregory Gundersen `_. - - - Added examples of :py:meth:`Dataset.set_index` and - :py:meth:`DataArray.set_index`, as well are more specific error messages - when the user passes invalid arguments (:issue:`3176`). - By `Gregory Gundersen `_. - - - :py:meth:`Dataset.filter_by_attrs` now filters the coordinates as well as the variables. - By `Spencer Jones `_. - - Bug fixes - ~~~~~~~~~ - - - Improve "missing dimensions" error message for :py:func:`~xarray.apply_ufunc` - (:issue:`2078`). - By `Rick Russotto `_. - - :py:meth:`~xarray.DataArray.assign_coords` now supports dictionary arguments - (:issue:`3231`). - By `Gregory Gundersen `_. - - Fix regression introduced in v0.12.2 where ``copy(deep=True)`` would convert - unicode indices to dtype=object (:issue:`3094`). - By `Guido Imperiale `_. - - Improved error handling and documentation for `.expand_dims()` - read-only view. - - Fix tests for big-endian systems (:issue:`3125`). - By `Graham Inggs `_. - - XFAIL several tests which are expected to fail on ARM systems - due to a ``datetime`` issue in NumPy (:issue:`2334`). - By `Graham Inggs `_. - - Fix KeyError that arises when using .sel method with float values - different from coords float type (:issue:`3137`). - By `Hasan Ahmad `_. - - Fixed bug in ``combine_by_coords()`` causing a `ValueError` if the input had - an unused dimension with coordinates which were not monotonic (:issue:`3150`). - By `Tom Nicholas `_. - - Fixed crash when applying ``distributed.Client.compute()`` to a DataArray - (:issue:`3171`). By `Guido Imperiale `_. - - Better error message when using groupby on an empty DataArray (:issue:`3037`). - By `Hasan Ahmad `_. - - Fix error that arises when using open_mfdataset on a series of netcdf files - having differing values for a variable attribute of type list. (:issue:`3034`) - By `Hasan Ahmad `_. - - Prevent :py:meth:`~xarray.DataArray.argmax` and :py:meth:`~xarray.DataArray.argmin` from calling - dask compute (:issue:`3237`). By `Ulrich Herter `_. - - Plots in 2 dimensions (pcolormesh, contour) now allow to specify levels as numpy - array (:issue:`3284`). By `Mathias Hauser `_. - - Fixed bug in :meth:`DataArray.quantile` failing to keep attributes when - `keep_attrs` was True (:issue:`3304`). By `David Huard `_. - - Documentation - ~~~~~~~~~~~~~ - - - Created a `PR checklist `_ - as a quick reference for tasks before creating a new PR - or pushing new commits. - By `Gregory Gundersen `_. - - - Fixed documentation to clean up unwanted files created in ``ipython`` examples - (:issue:`3227`). - By `Gregory Gundersen `_. - - .. _whats-new.0.12.3: - - v0.12.3 (10 July 2019) - ---------------------- - - New functions/methods - ~~~~~~~~~~~~~~~~~~~~~ - - - New methods :py:meth:`Dataset.to_stacked_array` and - :py:meth:`DataArray.to_unstacked_dataset` for reshaping Datasets of variables - with different dimensions - (:issue:`1317`). - This is useful for feeding data from xarray into machine learning models, - as described in :ref:`reshape.stacking_different`. - By `Noah Brenowitz `_. - - Enhancements - ~~~~~~~~~~~~ - - - Support for renaming ``Dataset`` variables and dimensions independently - with :py:meth:`~Dataset.rename_vars` and :py:meth:`~Dataset.rename_dims` - (:issue:`3026`). - By `Julia Kent `_. - - - Add ``scales``, ``offsets``, ``units`` and ``descriptions`` - attributes to :py:class:`~xarray.DataArray` returned by - :py:func:`~xarray.open_rasterio`. (:issue:`3013`) - By `Erle Carrara `_. - - Bug fixes - ~~~~~~~~~ - - - Resolved deprecation warnings from newer versions of matplotlib and dask. - - Compatibility fixes for the upcoming pandas 0.25 and NumPy 1.17 releases. - By `Stephan Hoyer `_. - - Fix summaries for multiindex coordinates (:issue:`3079`). - By `Jonas Hörsch `_. - - Fix HDF5 error that could arise when reading multiple groups from a file at - once (:issue:`2954`). - By `Stephan Hoyer `_. - - .. _whats-new.0.12.2: - - v0.12.2 (29 June 2019) - ---------------------- - - New functions/methods - ~~~~~~~~~~~~~~~~~~~~~ - - - Two new functions, :py:func:`~xarray.combine_nested` and - :py:func:`~xarray.combine_by_coords`, allow for combining datasets along any - number of dimensions, instead of the one-dimensional list of datasets - supported by :py:func:`~xarray.concat`. - - The new ``combine_nested`` will accept the datasets as a nested - list-of-lists, and combine by applying a series of concat and merge - operations. The new ``combine_by_coords`` instead uses the dimension - coordinates of datasets to order them. - - :py:func:`~xarray.open_mfdataset` can use either ``combine_nested`` or - ``combine_by_coords`` to combine datasets along multiple dimensions, by - specifying the argument ``combine='nested'`` or ``combine='by_coords'``. - - The older function ``auto_combine`` has been deprecated, - because its functionality has been subsumed by the new functions. - To avoid FutureWarnings switch to using ``combine_nested`` or - ``combine_by_coords``, (or set the ``combine`` argument in - ``open_mfdataset``). (:issue:`2159`) - By `Tom Nicholas `_. - - - :py:meth:`~xarray.DataArray.rolling_exp` and - :py:meth:`~xarray.Dataset.rolling_exp` added, similar to pandas' - ``pd.DataFrame.ewm`` method. Calling ``.mean`` on the resulting object - will return an exponentially weighted moving average. - By `Maximilian Roos `_. - - - New :py:func:`DataArray.str ` for string - related manipulations, based on ``pandas.Series.str``. - By `0x0L `_. - - - Added ``strftime`` method to ``.dt`` accessor, making it simpler to hand a - datetime ``DataArray`` to other code expecting formatted dates and times. - (:issue:`2090`). :py:meth:`~xarray.CFTimeIndex.strftime` is also now - available on :py:class:`CFTimeIndex`. - By `Alan Brammer `_ and - `Ryan May `_. - - - ``GroupBy.quantile`` is now a method of ``GroupBy`` - objects (:issue:`3018`). - By `David Huard `_. - - - Argument and return types are added to most methods on ``DataArray`` and - ``Dataset``, allowing static type checking both within xarray and external - libraries. Type checking with `mypy `_ is enabled in - CI (though not required yet). - By `Guido Imperiale `_ - and `Maximilian Roos `_. - - Enhancements to existing functionality - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - - Add ``keepdims`` argument for reduce operations (:issue:`2170`) - By `Scott Wales `_. - - Enable ``@`` operator for DataArray. This is equivalent to :py:meth:`DataArray.dot` - By `Maximilian Roos `_. - - Add ``fill_value`` argument for reindex, align, and merge operations - to enable custom fill values. (:issue:`2876`) - By `Zach Griffith `_. - - :py:meth:`DataArray.transpose` now accepts a keyword argument - ``transpose_coords`` which enables transposition of coordinates in the - same way as :py:meth:`Dataset.transpose`. :py:meth:`DataArray.groupby` - :py:meth:`DataArray.groupby_bins`, and :py:meth:`DataArray.resample` now - accept a keyword argument ``restore_coord_dims`` which keeps the order - of the dimensions of multi-dimensional coordinates intact (:issue:`1856`). - By `Peter Hausamann `_. - - Clean up Python 2 compatibility in code (:issue:`2950`) - By `Guido Imperiale `_. - - Better warning message when supplying invalid objects to ``xr.merge`` - (:issue:`2948`). By `Mathias Hauser `_. - - Add ``errors`` keyword argument to ``Dataset.drop`` and :py:meth:`Dataset.drop_dims` - that allows ignoring errors if a passed label or dimension is not in the dataset - (:issue:`2994`). - By `Andrew Ross `_. - - IO related enhancements - ~~~~~~~~~~~~~~~~~~~~~~~ - - - Implement :py:func:`~xarray.load_dataset` and - :py:func:`~xarray.load_dataarray` as alternatives to - :py:func:`~xarray.open_dataset` and :py:func:`~xarray.open_dataarray` to - open, load into memory, and close files, returning the Dataset or DataArray. - These functions are helpful for avoiding file-lock errors when trying to - write to files opened using ``open_dataset()`` or ``open_dataarray()``. - (:issue:`2887`) - By `Dan Nowacki `_. - - It is now possible to extend existing :ref:`io.zarr` datasets, by using - ``mode='a'`` and the new ``append_dim`` argument in - :py:meth:`~xarray.Dataset.to_zarr`. - By `Jendrik Jördening `_, - `David Brochart `_, - `Ryan Abernathey `_ and - `Shikhar Goenka `_. - - ``xr.open_zarr`` now accepts manually specified chunks with the ``chunks=`` - parameter. ``auto_chunk=True`` is equivalent to ``chunks='auto'`` for - backwards compatibility. The ``overwrite_encoded_chunks`` parameter is - added to remove the original zarr chunk encoding. - By `Lily Wang `_. - - netCDF chunksizes are now only dropped when original_shape is different, - not when it isn't found. (:issue:`2207`) - By `Karel van de Plassche `_. - - Character arrays' character dimension name decoding and encoding handled by - ``var.encoding['char_dim_name']`` (:issue:`2895`) - By `James McCreight `_. - - open_rasterio() now supports rasterio.vrt.WarpedVRT with custom transform, - width and height (:issue:`2864`). - By `Julien Michel `_. - - Bug fixes - ~~~~~~~~~ - - - Rolling operations on xarray objects containing dask arrays could silently - compute the incorrect result or use large amounts of memory (:issue:`2940`). - By `Stephan Hoyer `_. - - Don't set encoding attributes on bounds variables when writing to netCDF. - (:issue:`2921`) - By `Deepak Cherian `_. - - NetCDF4 output: variables with unlimited dimensions must be chunked (not - contiguous) on output. (:issue:`1849`) - By `James McCreight `_. - - indexing with an empty list creates an object with zero-length axis (:issue:`2882`) - By `Mayeul d'Avezac `_. - - Return correct count for scalar datetime64 arrays (:issue:`2770`) - By `Dan Nowacki `_. - - Fixed max, min exception when applied to a multiIndex (:issue:`2923`) - By `Ian Castleden `_ - - A deep copy deep-copies the coords (:issue:`1463`) - By `Martin Pletcher `_. - - Increased support for `missing_value` (:issue:`2871`) - By `Deepak Cherian `_. - - Removed usages of `pytest.config`, which is deprecated (:issue:`2988`) - By `Maximilian Roos `_. - - Fixed performance issues with cftime installed (:issue:`3000`) - By `0x0L `_. - - Replace incorrect usages of `message` in pytest assertions - with `match` (:issue:`3011`) - By `Maximilian Roos `_. - - Add explicit pytest markers, now required by pytest - (:issue:`3032`). - By `Maximilian Roos `_. - - Test suite fixes for newer versions of pytest (:issue:`3011`, :issue:`3032`). - By `Maximilian Roos `_ - and `Stephan Hoyer `_. - - .. _whats-new.0.12.1: - - v0.12.1 (4 April 2019) - ---------------------- - - Enhancements - ~~~~~~~~~~~~ - - - Allow ``expand_dims`` method to support inserting/broadcasting dimensions - with size > 1. (:issue:`2710`) - By `Martin Pletcher `_. - - Bug fixes - ~~~~~~~~~ - - - Dataset.copy(deep=True) now creates a deep copy of the attrs (:issue:`2835`). - By `Andras Gefferth `_. - - Fix incorrect ``indexes`` resulting from various ``Dataset`` operations - (e.g., ``swap_dims``, ``isel``, ``reindex``, ``[]``) (:issue:`2842`, - :issue:`2856`). - By `Stephan Hoyer `_. - - .. _whats-new.0.12.0: - - v0.12.0 (15 March 2019) - ----------------------- - - Highlights include: - - - Removed support for Python 2. This is the first version of xarray that is - Python 3 only! - - New :py:meth:`~xarray.DataArray.coarsen` and - :py:meth:`~xarray.DataArray.integrate` methods. See :ref:`comput.coarsen` - and :ref:`compute.using_coordinates` for details. - - Many improvements to cftime support. See below for details. - - Deprecations - ~~~~~~~~~~~~ - - - The ``compat`` argument to ``Dataset`` and the ``encoding`` argument to - ``DataArray`` are deprecated and will be removed in a future release. - (:issue:`1188`) - By `Maximilian Roos `_. - - cftime related enhancements - ~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - - Resampling of standard and non-standard calendars indexed by - :py:class:`~xarray.CFTimeIndex` is now possible. (:issue:`2191`). - By `Jwen Fai Low `_ and - `Spencer Clark `_. - - - Taking the mean of arrays of :py:class:`cftime.datetime` objects, and - by extension, use of :py:meth:`~xarray.DataArray.coarsen` with - :py:class:`cftime.datetime` coordinates is now possible. By `Spencer Clark - `_. - - - Internal plotting now supports ``cftime.datetime`` objects as time series. - (:issue:`2164`) - By `Julius Busecke `_ and - `Spencer Clark `_. - - - :py:meth:`~xarray.cftime_range` now supports QuarterBegin and QuarterEnd offsets (:issue:`2663`). - By `Jwen Fai Low `_ - - - :py:meth:`~xarray.open_dataset` now accepts a ``use_cftime`` argument, which - can be used to require that ``cftime.datetime`` objects are always used, or - never used when decoding dates encoded with a standard calendar. This can be - used to ensure consistent date types are returned when using - :py:meth:`~xarray.open_mfdataset` (:issue:`1263`) and/or to silence - serialization warnings raised if dates from a standard calendar are found to - be outside the :py:class:`pandas.Timestamp`-valid range (:issue:`2754`). By - `Spencer Clark `_. - - - :py:meth:`pandas.Series.dropna` is now supported for a - :py:class:`pandas.Series` indexed by a :py:class:`~xarray.CFTimeIndex` - (:issue:`2688`). By `Spencer Clark `_. - - Other enhancements - ~~~~~~~~~~~~~~~~~~ - - - Added ability to open netcdf4/hdf5 file-like objects with ``open_dataset``. - Requires (h5netcdf>0.7 and h5py>2.9.0). (:issue:`2781`) - By `Scott Henderson `_ - - Add ``data=False`` option to ``to_dict()`` methods. (:issue:`2656`) - By `Ryan Abernathey `_ - - :py:meth:`DataArray.coarsen` and - :py:meth:`Dataset.coarsen` are newly added. - See :ref:`comput.coarsen` for details. - (:issue:`2525`) - By `Keisuke Fujii `_. - - Upsampling an array via interpolation with resample is now dask-compatible, - as long as the array is not chunked along the resampling dimension. - By `Spencer Clark `_. - - :py:func:`xarray.testing.assert_equal` and - :py:func:`xarray.testing.assert_identical` now provide a more detailed - report showing what exactly differs between the two objects (dimensions / - coordinates / variables / attributes) (:issue:`1507`). - By `Benoit Bovy `_. - - Add ``tolerance`` option to ``resample()`` methods ``bfill``, ``pad``, - ``nearest``. (:issue:`2695`) - By `Hauke Schulz `_. - - :py:meth:`DataArray.integrate` and - :py:meth:`Dataset.integrate` are newly added. - See :ref:`compute.using_coordinates` for the detail. - (:issue:`1332`) + + ds = xr.Dataset({"a": 1}) + np.sin(ds) + + This obliviates the need for the ``xarray.ufuncs`` module, which will be + deprecated in the future when xarray drops support for older versions of + NumPy. By `Stephan Hoyer `_. + +- Improve :py:func:`~xarray.DataArray.rolling` logic. + :py:func:`~xarray.core.rolling.DataArrayRolling` object now supports + :py:func:`~xarray.core.rolling.DataArrayRolling.construct` method that returns a view + of the DataArray / Dataset object with the rolling-window dimension added + to the last axis. This enables more flexible operation, such as strided + rolling, windowed rolling, ND-rolling, short-time FFT and convolution. + (:issue:`1831`, :issue:`1142`, :issue:`819`) + By `Keisuke Fujii `_. +- :py:func:`~plot.line()` learned to make plots with data on x-axis if so specified. (:issue:`575`) + By `Deepak Cherian `_. + +Bug fixes +~~~~~~~~~ + +- Raise an informative error message when using ``apply_ufunc`` with numpy + v1.11 (:issue:`1956`). + By `Stephan Hoyer `_. +- Fix the precision drop after indexing datetime64 arrays (:issue:`1932`). + By `Keisuke Fujii `_. +- Silenced irrelevant warnings issued by ``open_rasterio`` (:issue:`1964`). + By `Stephan Hoyer `_. +- Fix kwarg `colors` clashing with auto-inferred `cmap` (:issue:`1461`) + By `Deepak Cherian `_. +- Fix :py:func:`~xarray.plot.imshow` error when passed an RGB array with + size one in a spatial dimension. + By `Zac Hatfield-Dodds `_. + +.. _whats-new.0.10.1: + +v0.10.1 (25 February 2018) +-------------------------- + +The minor release includes a number of bug-fixes and backwards compatible enhancements. + +Documentation +~~~~~~~~~~~~~ + +- Added a new guide on :ref:`contributing` (:issue:`640`) + By `Joe Hamman `_. +- Added apply_ufunc example to :ref:`/examples/weather-data.ipynb#Toy-weather-data` (:issue:`1844`). + By `Liam Brannigan `_. +- New entry `Why don’t aggregations return Python scalars?` in the + :doc:`getting-started-guide/faq` (:issue:`1726`). + By `0x0L `_. + +Enhancements +~~~~~~~~~~~~ +**New functions and methods**: + +- Added :py:meth:`DataArray.to_iris` and + :py:meth:`DataArray.from_iris` for + converting data arrays to and from Iris_ Cubes with the same data and coordinates + (:issue:`621` and :issue:`37`). + By `Neil Parley `_ and `Duncan Watson-Parris `_. +- Experimental support for using `Zarr`_ as storage layer for xarray + (:issue:`1223`). + By `Ryan Abernathey `_ and + `Joe Hamman `_. +- New :py:meth:`~xarray.DataArray.rank` on arrays and datasets. Requires + bottleneck (:issue:`1731`). + By `0x0L `_. +- ``.dt`` accessor can now ceil, floor and round timestamps to specified frequency. + By `Deepak Cherian `_. + +**Plotting enhancements**: + +- :func:`xarray.plot.imshow` now handles RGB and RGBA images. + Saturation can be adjusted with ``vmin`` and ``vmax``, or with ``robust=True``. + By `Zac Hatfield-Dodds `_. +- :py:func:`~plot.contourf()` learned to contour 2D variables that have both a + 1D coordinate (e.g. time) and a 2D coordinate (e.g. depth as a function of + time) (:issue:`1737`). + By `Deepak Cherian `_. +- :py:func:`~plot.plot()` rotates x-axis ticks if x-axis is time. + By `Deepak Cherian `_. +- :py:func:`~plot.line()` can draw multiple lines if provided with a + 2D variable. + By `Deepak Cherian `_. + +**Other enhancements**: + +- Reduce methods such as :py:func:`DataArray.sum()` now handles object-type array. + + .. ipython:: python + + da = xr.DataArray(np.array([True, False, np.nan], dtype=object), dims="x") + da.sum() + + (:issue:`1866`) + By `Keisuke Fujii `_. +- Reduce methods such as :py:func:`DataArray.sum()` now accepts ``dtype`` + arguments. (:issue:`1838`) + By `Keisuke Fujii `_. +- Added nodatavals attribute to DataArray when using :py:func:`~xarray.open_rasterio`. (:issue:`1736`). + By `Alan Snow `_. +- Use ``pandas.Grouper`` class in xarray resample methods rather than the + deprecated ``pandas.TimeGrouper`` class (:issue:`1766`). + By `Joe Hamman `_. +- Experimental support for parsing ENVI metadata to coordinates and attributes + in :py:func:`xarray.open_rasterio`. + By `Matti Eskelinen `_. +- Reduce memory usage when decoding a variable with a scale_factor, by + converting 8-bit and 16-bit integers to float32 instead of float64 + (:pull:`1840`), and keeping float16 and float32 as float32 (:issue:`1842`). + Correspondingly, encoded variables may also be saved with a smaller dtype. + By `Zac Hatfield-Dodds `_. +- Speed of reindexing/alignment with dask array is orders of magnitude faster + when inserting missing values (:issue:`1847`). + By `Stephan Hoyer `_. +- Fix ``axis`` keyword ignored when applying ``np.squeeze`` to ``DataArray`` (:issue:`1487`). + By `Florian Pinault `_. +- ``netcdf4-python`` has moved the its time handling in the ``netcdftime`` module to + a standalone package (`netcdftime`_). As such, xarray now considers `netcdftime`_ + an optional dependency. One benefit of this change is that it allows for + encoding/decoding of datetimes with non-standard calendars without the + ``netcdf4-python`` dependency (:issue:`1084`). + By `Joe Hamman `_. + +.. _Zarr: http://zarr.readthedocs.io/ + +.. _Iris: http://scitools.org.uk/iris + +.. _netcdftime: https://unidata.github.io/netcdftime + +**New functions/methods** + +- New :py:meth:`~xarray.DataArray.rank` on arrays and datasets. Requires + bottleneck (:issue:`1731`). + By `0x0L `_. + +Bug fixes +~~~~~~~~~ +- Rolling aggregation with ``center=True`` option now gives the same result + with pandas including the last element (:issue:`1046`). + By `Keisuke Fujii `_. + +- Support indexing with a 0d-np.ndarray (:issue:`1921`). + By `Keisuke Fujii `_. +- Added warning in api.py of a netCDF4 bug that occurs when + the filepath has 88 characters (:issue:`1745`). + By `Liam Brannigan `_. +- Fixed encoding of multi-dimensional coordinates in + :py:meth:`~Dataset.to_netcdf` (:issue:`1763`). + By `Mike Neish `_. +- Fixed chunking with non-file-based rasterio datasets (:issue:`1816`) and + refactored rasterio test suite. + By `Ryan Abernathey `_ +- Bug fix in open_dataset(engine='pydap') (:issue:`1775`) + By `Keisuke Fujii `_. +- Bug fix in vectorized assignment (:issue:`1743`, :issue:`1744`). + Now item assignment to :py:meth:`~DataArray.__setitem__` checks +- Bug fix in vectorized assignment (:issue:`1743`, :issue:`1744`). + Now item assignment to :py:meth:`DataArray.__setitem__` checks + coordinates of target, destination and keys. If there are any conflict among + these coordinates, ``IndexError`` will be raised. + By `Keisuke Fujii `_. +- Properly point ``DataArray.__dask_scheduler__`` to + ``dask.threaded.get``. By `Matthew Rocklin `_. +- Bug fixes in :py:meth:`DataArray.plot.imshow`: all-NaN arrays and arrays + with size one in some dimension can now be plotted, which is good for + exploring satellite imagery (:issue:`1780`). + By `Zac Hatfield-Dodds `_. +- Fixed ``UnboundLocalError`` when opening netCDF file (:issue:`1781`). + By `Stephan Hoyer `_. +- The ``variables``, ``attrs``, and ``dimensions`` properties have been + deprecated as part of a bug fix addressing an issue where backends were + unintentionally loading the datastores data and attributes repeatedly during + writes (:issue:`1798`). + By `Joe Hamman `_. +- Compatibility fixes to plotting module for Numpy 1.14 and Pandas 0.22 + (:issue:`1813`). + By `Joe Hamman `_. +- Bug fix in encoding coordinates with ``{'_FillValue': None}`` in netCDF + metadata (:issue:`1865`). + By `Chris Roth `_. +- Fix indexing with lists for arrays loaded from netCDF files with + ``engine='h5netcdf`` (:issue:`1864`). + By `Stephan Hoyer `_. +- Corrected a bug with incorrect coordinates for non-georeferenced geotiff + files (:issue:`1686`). Internally, we now use the rasterio coordinate + transform tool instead of doing the computations ourselves. A + ``parse_coordinates`` kwarg has beed added to :py:func:`~open_rasterio` + (set to ``True`` per default). + By `Fabien Maussion `_. +- The colors of discrete colormaps are now the same regardless if `seaborn` + is installed or not (:issue:`1896`). + By `Fabien Maussion `_. +- Fixed dtype promotion rules in :py:func:`where` and :py:func:`concat` to + match pandas (:issue:`1847`). A combination of strings/numbers or + unicode/bytes now promote to object dtype, instead of strings or unicode. + By `Stephan Hoyer `_. +- Fixed bug where :py:meth:`~xarray.DataArray.isnull` was loading data + stored as dask arrays (:issue:`1937`). + By `Joe Hamman `_. + +.. _whats-new.0.10.0: + +v0.10.0 (20 November 2017) +-------------------------- + +This is a major release that includes bug fixes, new features and a few +backwards incompatible changes. Highlights include: + +- Indexing now supports broadcasting over dimensions, similar to NumPy's + vectorized indexing (but better!). +- :py:meth:`~DataArray.resample` has a new groupby-like API like pandas. +- :py:func:`~xarray.apply_ufunc` facilitates wrapping and parallelizing + functions written for NumPy arrays. +- Performance improvements, particularly for dask and :py:func:`open_mfdataset`. + +Breaking changes +~~~~~~~~~~~~~~~~ + +- xarray now supports a form of vectorized indexing with broadcasting, where + the result of indexing depends on dimensions of indexers, + e.g., ``array.sel(x=ind)`` with ``ind.dims == ('y',)``. Alignment between + coordinates on indexed and indexing objects is also now enforced. + Due to these changes, existing uses of xarray objects to index other xarray + objects will break in some cases. + + The new indexing API is much more powerful, supporting outer, diagonal and + vectorized indexing in a single interface. + The ``isel_points`` and ``sel_points`` methods are deprecated, since they are + now redundant with the ``isel`` / ``sel`` methods. + See :ref:`vectorized_indexing` for the details (:issue:`1444`, + :issue:`1436`). + By `Keisuke Fujii `_ and + `Stephan Hoyer `_. + +- A new resampling interface to match pandas' groupby-like API was added to + :py:meth:`Dataset.resample` and :py:meth:`DataArray.resample` + (:issue:`1272`). :ref:`Timeseries resampling ` is + fully supported for data with arbitrary dimensions as is both downsampling + and upsampling (including linear, quadratic, cubic, and spline interpolation). + + Old syntax: + + .. ipython:: + :verbatim: + + In [1]: ds.resample("24H", dim="time", how="max") + Out[1]: + + [...] + + New syntax: + + .. ipython:: + :verbatim: + + In [1]: ds.resample(time="24H").max() + Out[1]: + + [...] + + Note that both versions are currently supported, but using the old syntax will + produce a warning encouraging users to adopt the new syntax. + By `Daniel Rothenberg `_. + +- Calling ``repr()`` or printing xarray objects at the command line or in a + Jupyter Notebook will not longer automatically compute dask variables or + load data on arrays lazily loaded from disk (:issue:`1522`). + By `Guido Imperiale `_. + +- Supplying ``coords`` as a dictionary to the ``DataArray`` constructor without + also supplying an explicit ``dims`` argument is no longer supported. This + behavior was deprecated in version 0.9 but will now raise an error + (:issue:`727`). + +- Several existing features have been deprecated and will change to new + behavior in xarray v0.11. If you use any of them with xarray v0.10, you + should see a ``FutureWarning`` that describes how to update your code: + + - ``Dataset.T`` has been deprecated an alias for ``Dataset.transpose()`` + (:issue:`1232`). In the next major version of xarray, it will provide short- + cut lookup for variables or attributes with name ``'T'``. + - ``DataArray.__contains__`` (e.g., ``key in data_array``) currently checks + for membership in ``DataArray.coords``. In the next major version of + xarray, it will check membership in the array data found in + ``DataArray.values`` instead (:issue:`1267`). + - Direct iteration over and counting a ``Dataset`` (e.g., ``[k for k in ds]``, + ``ds.keys()``, ``ds.values()``, ``len(ds)`` and ``if ds``) currently + includes all variables, both data and coordinates. For improved usability + and consistency with pandas, in the next major version of xarray these will + change to only include data variables (:issue:`884`). Use ``ds.variables``, + ``ds.data_vars`` or ``ds.coords`` as alternatives. + +- Changes to minimum versions of dependencies: + + - Old numpy < 1.11 and pandas < 0.18 are no longer supported (:issue:`1512`). By `Keisuke Fujii `_. - - Added :py:meth:`~xarray.Dataset.drop_dims` (:issue:`1949`). - By `Kevin Squire `_. - - Bug fixes - ~~~~~~~~~ - - - Silenced warnings that appear when using pandas 0.24. - By `Stephan Hoyer `_ - - Interpolating via resample now internally specifies ``bounds_error=False`` - as an argument to ``scipy.interpolate.interp1d``, allowing for interpolation - from higher frequencies to lower frequencies. Datapoints outside the bounds - of the original time coordinate are now filled with NaN (:issue:`2197`). By - `Spencer Clark `_. - - Line plots with the ``x`` argument set to a non-dimensional coord now plot - the correct data for 1D DataArrays. - (:issue:`2725`). By `Tom Nicholas `_. - - Subtracting a scalar ``cftime.datetime`` object from a - :py:class:`CFTimeIndex` now results in a :py:class:`pandas.TimedeltaIndex` - instead of raising a ``TypeError`` (:issue:`2671`). By `Spencer Clark - `_. - - backend_kwargs are no longer ignored when using open_dataset with pynio engine - (:issue:'2380') - By `Jonathan Joyce `_. - - Fix ``open_rasterio`` creating a WKT CRS instead of PROJ.4 with - ``rasterio`` 1.0.14+ (:issue:`2715`). - By `David Hoese `_. - - Masking data arrays with :py:meth:`xarray.DataArray.where` now returns an - array with the name of the original masked array (:issue:`2748` and :issue:`2457`). - By `Yohai Bar-Sinai `_. - - Fixed error when trying to reduce a DataArray using a function which does not - require an axis argument. (:issue:`2768`) - By `Tom Nicholas `_. - - Concatenating a sequence of :py:class:`~xarray.DataArray` with varying names - sets the name of the output array to ``None``, instead of the name of the - first input array. If the names are the same it sets the name to that, - instead to the name of the first DataArray in the list as it did before. - (:issue:`2775`). By `Tom Nicholas `_. - - - Per the `CF conventions section on calendars - `_, - specifying ``'standard'`` as the calendar type in - :py:meth:`~xarray.cftime_range` now correctly refers to the ``'gregorian'`` - calendar instead of the ``'proleptic_gregorian'`` calendar (:issue:`2761`). - - .. _whats-new.0.11.3: - - v0.11.3 (26 January 2019) - ------------------------- - - Bug fixes - ~~~~~~~~~ - - - Saving files with times encoded with reference dates with timezones - (e.g. '2000-01-01T00:00:00-05:00') no longer raises an error - (:issue:`2649`). By `Spencer Clark `_. - - Fixed performance regression with ``open_mfdataset`` (:issue:`2662`). - By `Tom Nicholas `_. - - Fixed supplying an explicit dimension in the ``concat_dim`` argument to - to ``open_mfdataset`` (:issue:`2647`). - By `Ben Root `_. - - .. _whats-new.0.11.2: - - v0.11.2 (2 January 2019) - ------------------------ - - Removes inadvertently introduced setup dependency on pytest-runner - (:issue:`2641`). Otherwise, this release is exactly equivalent to 0.11.1. - + - The minimum supported version bottleneck has increased to 1.1 + (:issue:`1279`). + By `Joe Hamman `_. + +Enhancements +~~~~~~~~~~~~ + +**New functions/methods** + +- New helper function :py:func:`~xarray.apply_ufunc` for wrapping functions + written to work on NumPy arrays to support labels on xarray objects + (:issue:`770`). ``apply_ufunc`` also support automatic parallelization for + many functions with dask. See :ref:`comput.wrapping-custom` and + :ref:`dask.automatic-parallelization` for details. + By `Stephan Hoyer `_. + +- Added new method :py:meth:`Dataset.to_dask_dataframe`, convert a dataset into + a dask dataframe. + This allows lazy loading of data from a dataset containing dask arrays (:issue:`1462`). + By `James Munroe `_. + +- New function :py:func:`~xarray.where` for conditionally switching between + values in xarray objects, like :py:func:`numpy.where`: + + .. ipython:: + :verbatim: + + In [1]: import xarray as xr + + In [2]: arr = xr.DataArray([[1, 2, 3], [4, 5, 6]], dims=("x", "y")) + + In [3]: xr.where(arr % 2, "even", "odd") + Out[3]: + + array([['even', 'odd', 'even'], + ['odd', 'even', 'odd']], + dtype='`_. + +- Added :py:func:`~xarray.show_versions` function to aid in debugging + (:issue:`1485`). + By `Joe Hamman `_. + +**Performance improvements** + +- :py:func:`~xarray.concat` was computing variables that aren't in memory + (e.g. dask-based) multiple times; :py:func:`~xarray.open_mfdataset` + was loading them multiple times from disk. Now, both functions will instead + load them at most once and, if they do, store them in memory in the + concatenated array/dataset (:issue:`1521`). + By `Guido Imperiale `_. + +- Speed-up (x 100) of ``xarray.conventions.decode_cf_datetime``. + By `Christian Chwala `_. + +**IO related improvements** + +- Unicode strings (``str`` on Python 3) are now round-tripped successfully even + when written as character arrays (e.g., as netCDF3 files or when using + ``engine='scipy'``) (:issue:`1638`). This is controlled by the ``_Encoding`` + attribute convention, which is also understood directly by the netCDF4-Python + interface. See :ref:`io.string-encoding` for full details. + By `Stephan Hoyer `_. + +- Support for ``data_vars`` and ``coords`` keywords from + :py:func:`~xarray.concat` added to :py:func:`~xarray.open_mfdataset` + (:issue:`438`). Using these keyword arguments can significantly reduce + memory usage and increase speed. + By `Oleksandr Huziy `_. + +- Support for :py:class:`pathlib.Path` objects added to + :py:func:`~xarray.open_dataset`, :py:func:`~xarray.open_mfdataset`, + ``xarray.to_netcdf``, and :py:func:`~xarray.save_mfdataset` + (:issue:`799`): + + .. ipython:: + :verbatim: + + In [2]: from pathlib import Path # In Python 2, use pathlib2! + + In [3]: data_dir = Path("data/") + + In [4]: one_file = data_dir / "dta_for_month_01.nc" + + In [5]: xr.open_dataset(one_file) + Out[5]: + + [...] + + By `Willi Rath `_. + +- You can now explicitly disable any default ``_FillValue`` (``NaN`` for + floating point values) by passing the enconding ``{'_FillValue': None}`` + (:issue:`1598`). + By `Stephan Hoyer `_. + +- More attributes available in :py:attr:`~xarray.Dataset.attrs` dictionary when + raster files are opened with :py:func:`~xarray.open_rasterio`. + By `Greg Brener `_. + +- Support for NetCDF files using an ``_Unsigned`` attribute to indicate that a + a signed integer data type should be interpreted as unsigned bytes + (:issue:`1444`). + By `Eric Bruning `_. + +- Support using an existing, opened netCDF4 ``Dataset`` with + :py:class:`~xarray.backends.NetCDF4DataStore`. This permits creating an + :py:class:`~xarray.Dataset` from a netCDF4 ``Dataset`` that has been opened using + other means (:issue:`1459`). + By `Ryan May `_. + +- Changed :py:class:`~xarray.backends.PydapDataStore` to take a Pydap dataset. + This permits opening Opendap datasets that require authentication, by + instantiating a Pydap dataset with a session object. Also added + :py:meth:`xarray.backends.PydapDataStore.open` which takes a url and session + object (:issue:`1068`). + By `Philip Graae `_. + +- Support reading and writing unlimited dimensions with h5netcdf (:issue:`1636`). + By `Joe Hamman `_. + +**Other improvements** + +- Added ``_ipython_key_completions_`` to xarray objects, to enable + autocompletion for dictionary-like access in IPython, e.g., + ``ds['tem`` + tab -> ``ds['temperature']`` (:issue:`1628`). + By `Keisuke Fujii `_. + +- Support passing keyword arguments to ``load``, ``compute``, and ``persist`` + methods. Any keyword arguments supplied to these methods are passed on to + the corresponding dask function (:issue:`1523`). + By `Joe Hamman `_. + +- Encoding attributes are now preserved when xarray objects are concatenated. + The encoding is copied from the first object (:issue:`1297`). + By `Joe Hamman `_ and + `Gerrit Holl `_. + +- Support applying rolling window operations using bottleneck's moving window + functions on data stored as dask arrays (:issue:`1279`). + By `Joe Hamman `_. + +- Experimental support for the Dask collection interface (:issue:`1674`). + By `Matthew Rocklin `_. + +Bug fixes +~~~~~~~~~ + +- Suppress ``RuntimeWarning`` issued by ``numpy`` for "invalid value comparisons" + (e.g. ``NaN``). Xarray now behaves similarly to Pandas in its treatment of + binary and unary operations on objects with NaNs (:issue:`1657`). + By `Joe Hamman `_. + +- Unsigned int support for reduce methods with ``skipna=True`` + (:issue:`1562`). + By `Keisuke Fujii `_. + +- Fixes to ensure xarray works properly with pandas 0.21: + + - Fix :py:meth:`~xarray.DataArray.isnull` method (:issue:`1549`). + - :py:meth:`~xarray.DataArray.to_series` and + :py:meth:`~xarray.Dataset.to_dataframe` should not return a ``pandas.MultiIndex`` + for 1D data (:issue:`1548`). + - Fix plotting with datetime64 axis labels (:issue:`1661`). + + By `Stephan Hoyer `_. + +- :py:func:`~xarray.open_rasterio` method now shifts the rasterio + coordinates so that they are centered in each pixel (:issue:`1468`). + By `Greg Brener `_. + +- :py:meth:`~xarray.Dataset.rename` method now doesn't throw errors + if some ``Variable`` is renamed to the same name as another ``Variable`` + as long as that other ``Variable`` is also renamed (:issue:`1477`). This + method now does throw when two ``Variables`` would end up with the same name + after the rename (since one of them would get overwritten in this case). + By `Prakhar Goel `_. + +- Fix :py:func:`xarray.testing.assert_allclose` to actually use ``atol`` and + ``rtol`` arguments when called on ``DataArray`` objects (:issue:`1488`). + By `Stephan Hoyer `_. + +- xarray ``quantile`` methods now properly raise a ``TypeError`` when applied to + objects with data stored as ``dask`` arrays (:issue:`1529`). + By `Joe Hamman `_. + +- Fix positional indexing to allow the use of unsigned integers (:issue:`1405`). + By `Joe Hamman `_ and + `Gerrit Holl `_. + +- Creating a :py:class:`Dataset` now raises ``MergeError`` if a coordinate + shares a name with a dimension but is comprised of arbitrary dimensions + (:issue:`1120`). + By `Joe Hamman `_. + +- :py:func:`~xarray.open_rasterio` method now skips rasterio's ``crs`` + attribute if its value is ``None`` (:issue:`1520`). + By `Leevi Annala `_. + +- Fix :py:func:`xarray.DataArray.to_netcdf` to return bytes when no path is + provided (:issue:`1410`). + By `Joe Hamman `_. + +- Fix :py:func:`xarray.save_mfdataset` to properly raise an informative error + when objects other than ``Dataset`` are provided (:issue:`1555`). + By `Joe Hamman `_. + +- :py:func:`xarray.Dataset.copy` would not preserve the encoding property + (:issue:`1586`). + By `Guido Imperiale `_. + +- :py:func:`xarray.concat` would eagerly load dask variables into memory if + the first argument was a numpy variable (:issue:`1588`). + By `Guido Imperiale `_. + +- Fix bug in :py:meth:`~xarray.Dataset.to_netcdf` when writing in append mode + (:issue:`1215`). + By `Joe Hamman `_. + +- Fix ``netCDF4`` backend to properly roundtrip the ``shuffle`` encoding option + (:issue:`1606`). + By `Joe Hamman `_. + +- Fix bug when using ``pytest`` class decorators to skiping certain unittests. + The previous behavior unintentionally causing additional tests to be skipped + (:issue:`1531`). By `Joe Hamman `_. + +- Fix pynio backend for upcoming release of pynio with Python 3 support + (:issue:`1611`). By `Ben Hillman `_. + +- Fix ``seaborn`` import warning for Seaborn versions 0.8 and newer when the + ``apionly`` module was deprecated. + (:issue:`1633`). By `Joe Hamman `_. + +- Fix COMPAT: MultiIndex checking is fragile + (:issue:`1833`). By `Florian Pinault `_. + +- Fix ``rasterio`` backend for Rasterio versions 1.0alpha10 and newer. + (:issue:`1641`). By `Chris Holden `_. + +Bug fixes after rc1 +~~~~~~~~~~~~~~~~~~~ + +- Suppress warning in IPython autocompletion, related to the deprecation + of ``.T`` attributes (:issue:`1675`). + By `Keisuke Fujii `_. + +- Fix a bug in lazily-indexing netCDF array. (:issue:`1688`) + By `Keisuke Fujii `_. + +- (Internal bug) MemoryCachedArray now supports the orthogonal indexing. + Also made some internal cleanups around array wrappers (:issue:`1429`). + By `Keisuke Fujii `_. + +- (Internal bug) MemoryCachedArray now always wraps ``np.ndarray`` by + ``NumpyIndexingAdapter``. (:issue:`1694`) + By `Keisuke Fujii `_. + +- Fix importing xarray when running Python with ``-OO`` (:issue:`1706`). + By `Stephan Hoyer `_. + +- Saving a netCDF file with a coordinates with a spaces in its names now raises + an appropriate warning (:issue:`1689`). + By `Stephan Hoyer `_. + +- Fix two bugs that were preventing dask arrays from being specified as + coordinates in the DataArray constructor (:issue:`1684`). + By `Joe Hamman `_. + +- Fixed ``apply_ufunc`` with ``dask='parallelized'`` for scalar arguments + (:issue:`1697`). + By `Stephan Hoyer `_. + +- Fix "Chunksize cannot exceed dimension size" error when writing netCDF4 files + loaded from disk (:issue:`1225`). + By `Stephan Hoyer `_. + +- Validate the shape of coordinates with names matching dimensions in the + DataArray constructor (:issue:`1709`). + By `Stephan Hoyer `_. + +- Raise ``NotImplementedError`` when attempting to save a MultiIndex to a + netCDF file (:issue:`1547`). + By `Stephan Hoyer `_. + +- Remove netCDF dependency from rasterio backend tests. + By `Matti Eskelinen `_ + +Bug fixes after rc2 +~~~~~~~~~~~~~~~~~~~ + +- Fixed unexpected behavior in ``Dataset.set_index()`` and + ``DataArray.set_index()`` introduced by Pandas 0.21.0. Setting a new + index with a single variable resulted in 1-level + ``pandas.MultiIndex`` instead of a simple ``pandas.Index`` + (:issue:`1722`). By `Benoit Bovy `_. + +- Fixed unexpected memory loading of backend arrays after ``print``. + (:issue:`1720`). By `Keisuke Fujii `_. + +.. _whats-new.0.9.6: + +v0.9.6 (8 June 2017) +-------------------- + +This release includes a number of backwards compatible enhancements and bug +fixes. + +Enhancements +~~~~~~~~~~~~ + +- New :py:meth:`~xarray.Dataset.sortby` method to ``Dataset`` and ``DataArray`` + that enable sorting along dimensions (:issue:`967`). + See :ref:`the docs ` for examples. + By `Chun-Wei Yuan `_ and + `Kyle Heuton `_. + +- Add ``.dt`` accessor to DataArrays for computing datetime-like properties + for the values they contain, similar to ``pandas.Series`` (:issue:`358`). + By `Daniel Rothenberg `_. + +- Renamed internal dask arrays created by ``open_dataset`` to match new dask + conventions (:issue:`1343`). + By `Ryan Abernathey `_. + +- :py:meth:`~xarray.as_variable` is now part of the public API (:issue:`1303`). + By `Benoit Bovy `_. + +- :py:func:`~xarray.align` now supports ``join='exact'``, which raises + an error instead of aligning when indexes to be aligned are not equal. + By `Stephan Hoyer `_. + +- New function :py:func:`~xarray.open_rasterio` for opening raster files with + the `rasterio `_ library. + See :ref:`the docs ` for details. + By `Joe Hamman `_, + `Nic Wayand `_ and + `Fabien Maussion `_ + +Bug fixes +~~~~~~~~~ + +- Fix error from repeated indexing of datasets loaded from disk (:issue:`1374`). + By `Stephan Hoyer `_. + +- Fix a bug where ``.isel_points`` wrongly assigns unselected coordinate to + ``data_vars``. + By `Keisuke Fujii `_. + +- Tutorial datasets are now checked against a reference MD5 sum to confirm + successful download (:issue:`1392`). By `Matthew Gidden + `_. + +- ``DataArray.chunk()`` now accepts dask specific kwargs like + ``Dataset.chunk()`` does. By `Fabien Maussion `_. + +- Support for ``engine='pydap'`` with recent releases of Pydap (3.2.2+), + including on Python 3 (:issue:`1174`). + +Documentation +~~~~~~~~~~~~~ + +- A new `gallery `_ + allows to add interactive examples to the documentation. + By `Fabien Maussion `_. + +Testing +~~~~~~~ + +- Fix test suite failure caused by changes to ``pandas.cut`` function + (:issue:`1386`). + By `Ryan Abernathey `_. + +- Enhanced tests suite by use of ``@network`` decorator, which is + controlled via ``--run-network-tests`` command line argument + to ``py.test`` (:issue:`1393`). + By `Matthew Gidden `_. + +.. _whats-new.0.9.5: + +v0.9.5 (17 April, 2017) +----------------------- + +Remove an inadvertently introduced print statement. + +.. _whats-new.0.9.3: + +v0.9.3 (16 April, 2017) +----------------------- + +This minor release includes bug-fixes and backwards compatible enhancements. + +Enhancements +~~~~~~~~~~~~ + +- New :py:meth:`~xarray.DataArray.persist` method to Datasets and DataArrays to + enable persisting data in distributed memory when using Dask (:issue:`1344`). + By `Matthew Rocklin `_. + +- New :py:meth:`~xarray.DataArray.expand_dims` method for ``DataArray`` and + ``Dataset`` (:issue:`1326`). + By `Keisuke Fujii `_. + +Bug fixes +~~~~~~~~~ + +- Fix ``.where()`` with ``drop=True`` when arguments do not have indexes + (:issue:`1350`). This bug, introduced in v0.9, resulted in xarray producing + incorrect results in some cases. + By `Stephan Hoyer `_. + +- Fixed writing to file-like objects with :py:meth:`~xarray.Dataset.to_netcdf` + (:issue:`1320`). + `Stephan Hoyer `_. + +- Fixed explicitly setting ``engine='scipy'`` with ``to_netcdf`` when not + providing a path (:issue:`1321`). + `Stephan Hoyer `_. + +- Fixed open_dataarray does not pass properly its parameters to open_dataset + (:issue:`1359`). + `Stephan Hoyer `_. + +- Ensure test suite works when runs from an installed version of xarray + (:issue:`1336`). Use ``@pytest.mark.slow`` instead of a custom flag to mark + slow tests. + By `Stephan Hoyer `_ + +.. _whats-new.0.9.2: + +v0.9.2 (2 April 2017) +--------------------- + +The minor release includes bug-fixes and backwards compatible enhancements. + +Enhancements +~~~~~~~~~~~~ + +- ``rolling`` on Dataset is now supported (:issue:`859`). + +- ``.rolling()`` on Dataset is now supported (:issue:`859`). + By `Keisuke Fujii `_. + +- When bottleneck version 1.1 or later is installed, use bottleneck for rolling + ``var``, ``argmin``, ``argmax``, and ``rank`` computations. Also, rolling + median now accepts a ``min_periods`` argument (:issue:`1276`). + By `Joe Hamman `_. + +- When ``.plot()`` is called on a 2D DataArray and only one dimension is + specified with ``x=`` or ``y=``, the other dimension is now guessed + (:issue:`1291`). + By `Vincent Noel `_. + +- Added new method :py:meth:`~Dataset.assign_attrs` to ``DataArray`` and + ``Dataset``, a chained-method compatible implementation of the + ``dict.update`` method on attrs (:issue:`1281`). + By `Henry S. Harrison `_. + +- Added new ``autoclose=True`` argument to + :py:func:`~xarray.open_mfdataset` to explicitly close opened files when not in + use to prevent occurrence of an OS Error related to too many open files + (:issue:`1198`). + Note, the default is ``autoclose=False``, which is consistent with + previous xarray behavior. + By `Phillip J. Wolfram `_. + +- The ``repr()`` of ``Dataset`` and ``DataArray`` attributes uses a similar + format to coordinates and variables, with vertically aligned entries + truncated to fit on a single line (:issue:`1319`). Hopefully this will stop + people writing ``data.attrs = {}`` and discarding metadata in notebooks for + the sake of cleaner output. The full metadata is still available as + ``data.attrs``. + By `Zac Hatfield-Dodds `_. + +- Enhanced tests suite by use of ``@slow`` and ``@flaky`` decorators, which are + controlled via ``--run-flaky`` and ``--skip-slow`` command line arguments + to ``py.test`` (:issue:`1336`). + By `Stephan Hoyer `_ and + `Phillip J. Wolfram `_. + +- New aggregation on rolling objects :py:meth:`~core.rolling.DataArrayRolling.count` + which providing a rolling count of valid values (:issue:`1138`). + +Bug fixes +~~~~~~~~~ +- Rolling operations now keep preserve original dimension order (:issue:`1125`). + By `Keisuke Fujii `_. + +- Fixed ``sel`` with ``method='nearest'`` on Python 2.7 and 64-bit Windows + (:issue:`1140`). + `Stephan Hoyer `_. + +- Fixed ``where`` with ``drop='True'`` for empty masks (:issue:`1341`). + By `Stephan Hoyer `_ and + `Phillip J. Wolfram `_. + +.. _whats-new.0.9.1: + +v0.9.1 (30 January 2017) +------------------------ + +Renamed the "Unindexed dimensions" section in the ``Dataset`` and +``DataArray`` repr (added in v0.9.0) to "Dimensions without coordinates" +(:issue:`1199`). + +.. _whats-new.0.9.0: + +v0.9.0 (25 January 2017) +------------------------ + +This major release includes five months worth of enhancements and bug fixes from +24 contributors, including some significant changes that are not fully backwards +compatible. Highlights include: + +- Coordinates are now *optional* in the xarray data model, even for dimensions. +- Changes to caching, lazy loading and pickling to improve xarray's experience + for parallel computing. +- Improvements for accessing and manipulating ``pandas.MultiIndex`` levels. +- Many new methods and functions, including + :py:meth:`~DataArray.quantile`, + :py:meth:`~DataArray.cumsum`, + :py:meth:`~DataArray.cumprod` + :py:attr:`~DataArray.combine_first` + :py:meth:`~DataArray.set_index`, + :py:meth:`~DataArray.reset_index`, + :py:meth:`~DataArray.reorder_levels`, + :py:func:`~xarray.full_like`, + :py:func:`~xarray.zeros_like`, + :py:func:`~xarray.ones_like` + :py:func:`~xarray.open_dataarray`, + :py:meth:`~DataArray.compute`, + :py:meth:`Dataset.info`, + :py:func:`testing.assert_equal`, + :py:func:`testing.assert_identical`, and + :py:func:`testing.assert_allclose`. + +Breaking changes +~~~~~~~~~~~~~~~~ + +- Index coordinates for each dimensions are now optional, and no longer created + by default :issue:`1017`. You can identify such dimensions without coordinates + by their appearance in list of "Dimensions without coordinates" in the + ``Dataset`` or ``DataArray`` repr: + + .. ipython:: + :verbatim: + + In [1]: xr.Dataset({"foo": (("x", "y"), [[1, 2]])}) + Out[1]: + + Dimensions: (x: 1, y: 2) + Dimensions without coordinates: x, y + Data variables: + foo (x, y) int64 1 2 + + This has a number of implications: + + - :py:func:`~align` and :py:meth:`~Dataset.reindex` can now error, if + dimensions labels are missing and dimensions have different sizes. + - Because pandas does not support missing indexes, methods such as + ``to_dataframe``/``from_dataframe`` and ``stack``/``unstack`` no longer + roundtrip faithfully on all inputs. Use :py:meth:`~Dataset.reset_index` to + remove undesired indexes. + - ``Dataset.__delitem__`` and :py:meth:`~Dataset.drop` no longer delete/drop + variables that have dimensions matching a deleted/dropped variable. + - ``DataArray.coords.__delitem__`` is now allowed on variables matching + dimension names. + - ``.sel`` and ``.loc`` now handle indexing along a dimension without + coordinate labels by doing integer based indexing. See + :ref:`indexing.missing_coordinates` for an example. + - :py:attr:`~Dataset.indexes` is no longer guaranteed to include all + dimensions names as keys. The new method :py:meth:`~Dataset.get_index` has + been added to get an index for a dimension guaranteed, falling back to + produce a default ``RangeIndex`` if necessary. + +- The default behavior of ``merge`` is now ``compat='no_conflicts'``, so some + merges will now succeed in cases that previously raised + ``xarray.MergeError``. Set ``compat='broadcast_equals'`` to restore the + previous default. See :ref:`combining.no_conflicts` for more details. + +- Reading :py:attr:`~DataArray.values` no longer always caches values in a NumPy + array :issue:`1128`. Caching of ``.values`` on variables read from netCDF + files on disk is still the default when :py:func:`open_dataset` is called with + ``cache=True``. + By `Guido Imperiale `_ and + `Stephan Hoyer `_. +- Pickling a ``Dataset`` or ``DataArray`` linked to a file on disk no longer + caches its values into memory before pickling (:issue:`1128`). Instead, pickle + stores file paths and restores objects by reopening file references. This + enables preliminary, experimental use of xarray for opening files with + `dask.distributed `_. + By `Stephan Hoyer `_. +- Coordinates used to index a dimension are now loaded eagerly into + :py:class:`pandas.Index` objects, instead of loading the values lazily. + By `Guido Imperiale `_. +- Automatic levels for 2d plots are now guaranteed to land on ``vmin`` and + ``vmax`` when these kwargs are explicitly provided (:issue:`1191`). The + automated level selection logic also slightly changed. + By `Fabien Maussion `_. + +- ``DataArray.rename()`` behavior changed to strictly change the ``DataArray.name`` + if called with string argument, or strictly change coordinate names if called with + dict-like argument. + By `Markus Gonser `_. + +- By default ``to_netcdf()`` add a ``_FillValue = NaN`` attributes to float types. + By `Frederic Laliberte `_. + +- ``repr`` on ``DataArray`` objects uses an shortened display for NumPy array + data that is less likely to overflow onto multiple pages (:issue:`1207`). + By `Stephan Hoyer `_. + +- xarray no longer supports python 3.3, versions of dask prior to v0.9.0, + or versions of bottleneck prior to v1.0. + +Deprecations +~~~~~~~~~~~~ + +- Renamed the ``Coordinate`` class from xarray's low level API to + :py:class:`~xarray.IndexVariable`. ``Variable.to_variable`` and + ``Variable.to_coord`` have been renamed to + :py:meth:`~xarray.Variable.to_base_variable` and + :py:meth:`~xarray.Variable.to_index_variable`. +- Deprecated supplying ``coords`` as a dictionary to the ``DataArray`` + constructor without also supplying an explicit ``dims`` argument. The old + behavior encouraged relying on the iteration order of dictionaries, which is + a bad practice (:issue:`727`). +- Removed a number of methods deprecated since v0.7.0 or earlier: + ``load_data``, ``vars``, ``drop_vars``, ``dump``, ``dumps`` and the + ``variables`` keyword argument to ``Dataset``. +- Removed the dummy module that enabled ``import xray``. + +Enhancements +~~~~~~~~~~~~ + +- Added new method :py:meth:`~DataArray.combine_first` to ``DataArray`` and + ``Dataset``, based on the pandas method of the same name (see :ref:`combine`). + By `Chun-Wei Yuan `_. + +- Added the ability to change default automatic alignment (arithmetic_join="inner") + for binary operations via :py:func:`~xarray.set_options()` + (see :ref:`math automatic alignment`). + By `Chun-Wei Yuan `_. + +- Add checking of ``attr`` names and values when saving to netCDF, raising useful + error messages if they are invalid. (:issue:`911`). + By `Robin Wilson `_. +- Added ability to save ``DataArray`` objects directly to netCDF files using + :py:meth:`~xarray.DataArray.to_netcdf`, and to load directly from netCDF files + using :py:func:`~xarray.open_dataarray` (:issue:`915`). These remove the need + to convert a ``DataArray`` to a ``Dataset`` before saving as a netCDF file, + and deals with names to ensure a perfect 'roundtrip' capability. + By `Robin Wilson `_. +- Multi-index levels are now accessible as "virtual" coordinate variables, + e.g., ``ds['time']`` can pull out the ``'time'`` level of a multi-index + (see :ref:`coordinates`). ``sel`` also accepts providing multi-index levels + as keyword arguments, e.g., ``ds.sel(time='2000-01')`` + (see :ref:`multi-level indexing`). + By `Benoit Bovy `_. +- Added ``set_index``, ``reset_index`` and ``reorder_levels`` methods to + easily create and manipulate (multi-)indexes (see :ref:`reshape.set_index`). + By `Benoit Bovy `_. +- Added the ``compat`` option ``'no_conflicts'`` to ``merge``, allowing the + combination of xarray objects with disjoint (:issue:`742`) or + overlapping (:issue:`835`) coordinates as long as all present data agrees. + By `Johnnie Gray `_. See + :ref:`combining.no_conflicts` for more details. +- It is now possible to set ``concat_dim=None`` explicitly in + :py:func:`~xarray.open_mfdataset` to disable inferring a dimension along + which to concatenate. + By `Stephan Hoyer `_. +- Added methods :py:meth:`DataArray.compute`, :py:meth:`Dataset.compute`, and + :py:meth:`Variable.compute` as a non-mutating alternative to + :py:meth:`~DataArray.load`. + By `Guido Imperiale `_. +- Adds DataArray and Dataset methods :py:meth:`~xarray.DataArray.cumsum` and + :py:meth:`~xarray.DataArray.cumprod`. By `Phillip J. Wolfram + `_. + +- New properties :py:attr:`Dataset.sizes` and :py:attr:`DataArray.sizes` for + providing consistent access to dimension length on both ``Dataset`` and + ``DataArray`` (:issue:`921`). + By `Stephan Hoyer `_. +- New keyword argument ``drop=True`` for :py:meth:`~DataArray.sel`, + :py:meth:`~DataArray.isel` and :py:meth:`~DataArray.squeeze` for dropping + scalar coordinates that arise from indexing. + ``DataArray`` (:issue:`242`). + By `Stephan Hoyer `_. + +- New top-level functions :py:func:`~xarray.full_like`, + :py:func:`~xarray.zeros_like`, and :py:func:`~xarray.ones_like` + By `Guido Imperiale `_. +- Overriding a preexisting attribute with + :py:func:`~xarray.register_dataset_accessor` or + :py:func:`~xarray.register_dataarray_accessor` now issues a warning instead of + raising an error (:issue:`1082`). + By `Stephan Hoyer `_. +- Options for axes sharing between subplots are exposed to + :py:class:`~xarray.plot.FacetGrid` and :py:func:`~xarray.plot.plot`, so axes + sharing can be disabled for polar plots. + By `Bas Hoonhout `_. +- New utility functions :py:func:`~xarray.testing.assert_equal`, + :py:func:`~xarray.testing.assert_identical`, and + :py:func:`~xarray.testing.assert_allclose` for asserting relationships + between xarray objects, designed for use in a pytest test suite. +- ``figsize``, ``size`` and ``aspect`` plot arguments are now supported for all + plots (:issue:`897`). See :ref:`plotting.figsize` for more details. + By `Stephan Hoyer `_ and + `Fabien Maussion `_. +- New :py:meth:`~Dataset.info` method to summarize ``Dataset`` variables + and attributes. The method prints to a buffer (e.g. ``stdout``) with output + similar to what the command line utility ``ncdump -h`` produces (:issue:`1150`). + By `Joe Hamman `_. +- Added the ability write unlimited netCDF dimensions with the ``scipy`` and + ``netcdf4`` backends via the new ``xray.Dataset.encoding`` attribute + or via the ``unlimited_dims`` argument to ``xray.Dataset.to_netcdf``. + By `Joe Hamman `_. +- New :py:meth:`~DataArray.quantile` method to calculate quantiles from + DataArray objects (:issue:`1187`). + By `Joe Hamman `_. + + +Bug fixes +~~~~~~~~~ +- ``groupby_bins`` now restores empty bins by default (:issue:`1019`). + By `Ryan Abernathey `_. + +- Fix issues for dates outside the valid range of pandas timestamps + (:issue:`975`). By `Mathias Hauser `_. + +- Unstacking produced flipped array after stacking decreasing coordinate values + (:issue:`980`). + By `Stephan Hoyer `_. + +- Setting ``dtype`` via the ``encoding`` parameter of ``to_netcdf`` failed if + the encoded dtype was the same as the dtype of the original array + (:issue:`873`). + By `Stephan Hoyer `_. + +- Fix issues with variables where both attributes ``_FillValue`` and + ``missing_value`` are set to ``NaN`` (:issue:`997`). + By `Marco Zühlke `_. + +- ``.where()`` and ``.fillna()`` now preserve attributes (:issue:`1009`). + By `Fabien Maussion `_. + +- Applying :py:func:`broadcast()` to an xarray object based on the dask backend + won't accidentally convert the array from dask to numpy anymore (:issue:`978`). + By `Guido Imperiale `_. + +- ``Dataset.concat()`` now preserves variables order (:issue:`1027`). + By `Fabien Maussion `_. + +- Fixed an issue with pcolormesh (:issue:`781`). A new + ``infer_intervals`` keyword gives control on whether the cell intervals + should be computed or not. + By `Fabien Maussion `_. + +- Grouping over an dimension with non-unique values with ``groupby`` gives + correct groups. + By `Stephan Hoyer `_. + +- Fixed accessing coordinate variables with non-string names from ``.coords``. + By `Stephan Hoyer `_. + +- :py:meth:`~xarray.DataArray.rename` now simultaneously renames the array and + any coordinate with the same name, when supplied via a :py:class:`dict` + (:issue:`1116`). + By `Yves Delley `_. + +- Fixed sub-optimal performance in certain operations with object arrays (:issue:`1121`). + By `Yves Delley `_. + +- Fix ``.groupby(group)`` when ``group`` has datetime dtype (:issue:`1132`). + By `Jonas Sølvsteen `_. + +- Fixed a bug with facetgrid (the ``norm`` keyword was ignored, :issue:`1159`). + By `Fabien Maussion `_. + +- Resolved a concurrency bug that could cause Python to crash when + simultaneously reading and writing netCDF4 files with dask (:issue:`1172`). + By `Stephan Hoyer `_. + +- Fix to make ``.copy()`` actually copy dask arrays, which will be relevant for + future releases of dask in which dask arrays will be mutable (:issue:`1180`). + By `Stephan Hoyer `_. + +- Fix opening NetCDF files with multi-dimensional time variables + (:issue:`1229`). + By `Stephan Hoyer `_. + +Performance improvements +~~~~~~~~~~~~~~~~~~~~~~~~ + +- ``xarray.Dataset.isel_points`` and ``xarray.Dataset.sel_points`` now + use vectorised indexing in numpy and dask (:issue:`1161`), which can + result in several orders of magnitude speedup. + By `Jonathan Chambers `_. + +.. _whats-new.0.8.2: + +v0.8.2 (18 August 2016) +----------------------- + +This release includes a number of bug fixes and minor enhancements. + +Breaking changes +~~~~~~~~~~~~~~~~ + +- :py:func:`~xarray.broadcast` and :py:func:`~xarray.concat` now auto-align + inputs, using ``join=outer``. Previously, these functions raised + ``ValueError`` for non-aligned inputs. + By `Guido Imperiale `_. + +Enhancements +~~~~~~~~~~~~ + +- New documentation on :ref:`panel transition`. By + `Maximilian Roos `_. +- New ``Dataset`` and ``DataArray`` methods :py:meth:`~xarray.Dataset.to_dict` + and :py:meth:`~xarray.Dataset.from_dict` to allow easy conversion between + dictionaries and xarray objects (:issue:`432`). See + :ref:`dictionary IO` for more details. + By `Julia Signell `_. +- Added ``exclude`` and ``indexes`` optional parameters to :py:func:`~xarray.align`, + and ``exclude`` optional parameter to :py:func:`~xarray.broadcast`. + By `Guido Imperiale `_. +- Better error message when assigning variables without dimensions + (:issue:`971`). By `Stephan Hoyer `_. +- Better error message when reindex/align fails due to duplicate index values + (:issue:`956`). By `Stephan Hoyer `_. + +Bug fixes +~~~~~~~~~ + +- Ensure xarray works with h5netcdf v0.3.0 for arrays with ``dtype=str`` + (:issue:`953`). By `Stephan Hoyer `_. +- ``Dataset.__dir__()`` (i.e. the method python calls to get autocomplete + options) failed if one of the dataset's keys was not a string (:issue:`852`). + By `Maximilian Roos `_. +- ``Dataset`` constructor can now take arbitrary objects as values + (:issue:`647`). By `Maximilian Roos `_. +- Clarified ``copy`` argument for :py:meth:`~xarray.DataArray.reindex` and + :py:func:`~xarray.align`, which now consistently always return new xarray + objects (:issue:`927`). +- Fix ``open_mfdataset`` with ``engine='pynio'`` (:issue:`936`). + By `Stephan Hoyer `_. +- ``groupby_bins`` sorted bin labels as strings (:issue:`952`). + By `Stephan Hoyer `_. +- Fix bug introduced by v0.8.0 that broke assignment to datasets when both the + left and right side have the same non-unique index values (:issue:`956`). + +.. _whats-new.0.8.1: + +v0.8.1 (5 August 2016) +---------------------- + +Bug fixes +~~~~~~~~~ + +- Fix bug in v0.8.0 that broke assignment to Datasets with non-unique + indexes (:issue:`943`). By `Stephan Hoyer `_. + +.. _whats-new.0.8.0: + +v0.8.0 (2 August 2016) +---------------------- + +This release includes four months of new features and bug fixes, including +several breaking changes. + +.. _v0.8.0.breaking: + +Breaking changes +~~~~~~~~~~~~~~~~ + +- Dropped support for Python 2.6 (:issue:`855`). +- Indexing on multi-index now drop levels, which is consistent with pandas. + It also changes the name of the dimension / coordinate when the multi-index is + reduced to a single index (:issue:`802`). +- Contour plots no longer add a colorbar per default (:issue:`866`). Filled + contour plots are unchanged. +- ``DataArray.values`` and ``.data`` now always returns an NumPy array-like + object, even for 0-dimensional arrays with object dtype (:issue:`867`). + Previously, ``.values`` returned native Python objects in such cases. To + convert the values of scalar arrays to Python objects, use the ``.item()`` + method. + +Enhancements +~~~~~~~~~~~~ + +- Groupby operations now support grouping over multidimensional variables. A new + method called :py:meth:`~xarray.Dataset.groupby_bins` has also been added to + allow users to specify bins for grouping. The new features are described in + :ref:`groupby.multidim` and :ref:`/examples/multidimensional-coords.ipynb`. + By `Ryan Abernathey `_. + +- DataArray and Dataset method :py:meth:`where` now supports a ``drop=True`` + option that clips coordinate elements that are fully masked. By + `Phillip J. Wolfram `_. + +- New top level :py:func:`merge` function allows for combining variables from + any number of ``Dataset`` and/or ``DataArray`` variables. See :ref:`merge` + for more details. By `Stephan Hoyer `_. + +- :py:meth:`DataArray.resample` and :py:meth:`Dataset.resample` now support the + ``keep_attrs=False`` option that determines whether variable and dataset + attributes are retained in the resampled object. By + `Jeremy McGibbon `_. + +- Better multi-index support in :py:meth:`DataArray.sel`, + :py:meth:`DataArray.loc`, :py:meth:`Dataset.sel` and + :py:meth:`Dataset.loc`, which now behave more closely to pandas and + which also accept dictionaries for indexing based on given level names + and labels (see :ref:`multi-level indexing`). + By `Benoit Bovy `_. + +- New (experimental) decorators :py:func:`~xarray.register_dataset_accessor` and + :py:func:`~xarray.register_dataarray_accessor` for registering custom xarray + extensions without subclassing. They are described in the new documentation + page on :ref:`internals`. By `Stephan Hoyer `_. + +- Round trip boolean datatypes. Previously, writing boolean datatypes to netCDF + formats would raise an error since netCDF does not have a `bool` datatype. + This feature reads/writes a `dtype` attribute to boolean variables in netCDF + files. By `Joe Hamman `_. + +- 2D plotting methods now have two new keywords (`cbar_ax` and `cbar_kwargs`), + allowing more control on the colorbar (:issue:`872`). + By `Fabien Maussion `_. + +- New Dataset method :py:meth:`Dataset.filter_by_attrs`, akin to + ``netCDF4.Dataset.get_variables_by_attributes``, to easily filter + data variables using its attributes. + `Filipe Fernandes `_. + +Bug fixes +~~~~~~~~~ + +- Attributes were being retained by default for some resampling + operations when they should not. With the ``keep_attrs=False`` option, they + will no longer be retained by default. This may be backwards-incompatible + with some scripts, but the attributes may be kept by adding the + ``keep_attrs=True`` option. By + `Jeremy McGibbon `_. + +- Concatenating xarray objects along an axis with a MultiIndex or PeriodIndex + preserves the nature of the index (:issue:`875`). By + `Stephan Hoyer `_. + +- Fixed bug in arithmetic operations on DataArray objects whose dimensions + are numpy structured arrays or recarrays :issue:`861`, :issue:`837`. By + `Maciek Swat `_. + +- ``decode_cf_timedelta`` now accepts arrays with ``ndim`` >1 (:issue:`842`). + This fixes issue :issue:`665`. + `Filipe Fernandes `_. + +- Fix a bug where `xarray.ufuncs` that take two arguments would incorrectly + use to numpy functions instead of dask.array functions (:issue:`876`). By + `Stephan Hoyer `_. + +- Support for pickling functions from ``xarray.ufuncs`` (:issue:`901`). By + `Stephan Hoyer `_. + +- ``Variable.copy(deep=True)`` no longer converts MultiIndex into a base Index + (:issue:`769`). By `Benoit Bovy `_. + +- Fixes for groupby on dimensions with a multi-index (:issue:`867`). By + `Stephan Hoyer `_. + +- Fix printing datasets with unicode attributes on Python 2 (:issue:`892`). By + `Stephan Hoyer `_. + +- Fixed incorrect test for dask version (:issue:`891`). By + `Stephan Hoyer `_. + +- Fixed `dim` argument for `isel_points`/`sel_points` when a `pandas.Index` is + passed. By `Stephan Hoyer `_. + +- :py:func:`~xarray.plot.contour` now plots the correct number of contours + (:issue:`866`). By `Fabien Maussion `_. + +.. _whats-new.0.7.2: + +v0.7.2 (13 March 2016) +---------------------- + +This release includes two new, entirely backwards compatible features and +several bug fixes. + +Enhancements +~~~~~~~~~~~~ + +- New DataArray method :py:meth:`DataArray.dot` for calculating the dot + product of two DataArrays along shared dimensions. By + `Dean Pospisil `_. + +- Rolling window operations on DataArray objects are now supported via a new + :py:meth:`DataArray.rolling` method. For example: + + .. ipython:: + :verbatim: + + In [1]: import xarray as xr + ...: import numpy as np + + In [2]: arr = xr.DataArray(np.arange(0, 7.5, 0.5).reshape(3, 5), dims=("x", "y")) + + In [3]: arr + Out[3]: + + array([[ 0. , 0.5, 1. , 1.5, 2. ], + [ 2.5, 3. , 3.5, 4. , 4.5], + [ 5. , 5.5, 6. , 6.5, 7. ]]) + Coordinates: + * x (x) int64 0 1 2 + * y (y) int64 0 1 2 3 4 + + In [4]: arr.rolling(y=3, min_periods=2).mean() + Out[4]: + + array([[ nan, 0.25, 0.5 , 1. , 1.5 ], + [ nan, 2.75, 3. , 3.5 , 4. ], + [ nan, 5.25, 5.5 , 6. , 6.5 ]]) + Coordinates: + * x (x) int64 0 1 2 + * y (y) int64 0 1 2 3 4 + + See :ref:`comput.rolling` for more details. By + `Joe Hamman `_. + +Bug fixes +~~~~~~~~~ + +- Fixed an issue where plots using pcolormesh and Cartopy axes were being distorted + by the inference of the axis interval breaks. This change chooses not to modify + the coordinate variables when the axes have the attribute ``projection``, allowing + Cartopy to handle the extent of pcolormesh plots (:issue:`781`). By + `Joe Hamman `_. + +- 2D plots now better handle additional coordinates which are not ``DataArray`` + dimensions (:issue:`788`). By `Fabien Maussion `_. + + +.. _whats-new.0.7.1: + +v0.7.1 (16 February 2016) +------------------------- + +This is a bug fix release that includes two small, backwards compatible enhancements. +We recommend that all users upgrade. + +Enhancements +~~~~~~~~~~~~ + +- Numerical operations now return empty objects on no overlapping labels rather + than raising ``ValueError`` (:issue:`739`). +- :py:class:`~pandas.Series` is now supported as valid input to the ``Dataset`` + constructor (:issue:`740`). + +Bug fixes +~~~~~~~~~ + +- Restore checks for shape consistency between data and coordinates in the + DataArray constructor (:issue:`758`). +- Single dimension variables no longer transpose as part of a broader + ``.transpose``. This behavior was causing ``pandas.PeriodIndex`` dimensions + to lose their type (:issue:`749`) +- :py:class:`~xarray.Dataset` labels remain as their native type on ``.to_dataset``. + Previously they were coerced to strings (:issue:`745`) +- Fixed a bug where replacing a ``DataArray`` index coordinate would improperly + align the coordinate (:issue:`725`). +- ``DataArray.reindex_like`` now maintains the dtype of complex numbers when + reindexing leads to NaN values (:issue:`738`). +- ``Dataset.rename`` and ``DataArray.rename`` support the old and new names + being the same (:issue:`724`). +- Fix :py:meth:`~xarray.Dataset.from_dataframe` for DataFrames with Categorical + column and a MultiIndex index (:issue:`737`). +- Fixes to ensure xarray works properly after the upcoming pandas v0.18 and + NumPy v1.11 releases. + +Acknowledgments +~~~~~~~~~~~~~~~ + +The following individuals contributed to this release: + +- Edward Richards +- Maximilian Roos +- Rafael Guedes +- Spencer Hill +- Stephan Hoyer + +.. _whats-new.0.7.0: + +v0.7.0 (21 January 2016) +------------------------ + +This major release includes redesign of :py:class:`~xarray.DataArray` +internals, as well as new methods for reshaping, rolling and shifting +data. It includes preliminary support for :py:class:`pandas.MultiIndex`, +as well as a number of other features and bug fixes, several of which +offer improved compatibility with pandas. + +New name +~~~~~~~~ + +The project formerly known as "xray" is now "xarray", pronounced "x-array"! +This avoids a namespace conflict with the entire field of x-ray science. Renaming +our project seemed like the right thing to do, especially because some +scientists who work with actual x-rays are interested in using this project in +their work. Thanks for your understanding and patience in this transition. You +can now find our documentation and code repository at new URLs: + +- http://xarray.pydata.org +- http://github.com/pydata/xarray/ + +To ease the transition, we have simultaneously released v0.7.0 of both +``xray`` and ``xarray`` on the Python Package Index. These packages are +identical. For now, ``import xray`` still works, except it issues a +deprecation warning. This will be the last xray release. Going forward, we +recommend switching your import statements to ``import xarray as xr``. + +.. _v0.7.0.breaking: + +Breaking changes +~~~~~~~~~~~~~~~~ + +- The internal data model used by ``xray.DataArray`` has been + rewritten to fix several outstanding issues (:issue:`367`, :issue:`634`, + `this stackoverflow report`_). Internally, ``DataArray`` is now implemented + in terms of ``._variable`` and ``._coords`` attributes instead of holding + variables in a ``Dataset`` object. + + This refactor ensures that if a DataArray has the + same name as one of its coordinates, the array and the coordinate no longer + share the same data. + + In practice, this means that creating a DataArray with the same ``name`` as + one of its dimensions no longer automatically uses that array to label the + corresponding coordinate. You will now need to provide coordinate labels + explicitly. Here's the old behavior: + + .. ipython:: + :verbatim: + + In [2]: xray.DataArray([4, 5, 6], dims="x", name="x") + Out[2]: + + array([4, 5, 6]) + Coordinates: + * x (x) int64 4 5 6 + + and the new behavior (compare the values of the ``x`` coordinate): + + .. ipython:: + :verbatim: + + In [2]: xray.DataArray([4, 5, 6], dims="x", name="x") + Out[2]: + + array([4, 5, 6]) + Coordinates: + * x (x) int64 0 1 2 + +- It is no longer possible to convert a DataArray to a Dataset with + ``xray.DataArray.to_dataset`` if it is unnamed. This will now + raise ``ValueError``. If the array is unnamed, you need to supply the + ``name`` argument. + +.. _this stackoverflow report: http://stackoverflow.com/questions/33158558/python-xray-extract-first-and-last-time-value-within-each-month-of-a-timeseries + +Enhancements +~~~~~~~~~~~~ + +- Basic support for :py:class:`~pandas.MultiIndex` coordinates on xray objects, including + indexing, :py:meth:`~DataArray.stack` and :py:meth:`~DataArray.unstack`: + + .. ipython:: + :verbatim: + + In [7]: df = pd.DataFrame({"foo": range(3), "x": ["a", "b", "b"], "y": [0, 0, 1]}) + + In [8]: s = df.set_index(["x", "y"])["foo"] + + In [12]: arr = xray.DataArray(s, dims="z") + + In [13]: arr + Out[13]: + + array([0, 1, 2]) + Coordinates: + * z (z) object ('a', 0) ('b', 0) ('b', 1) + + In [19]: arr.indexes["z"] + Out[19]: + MultiIndex(levels=[[u'a', u'b'], [0, 1]], + labels=[[0, 1, 1], [0, 0, 1]], + names=[u'x', u'y']) + + In [14]: arr.unstack("z") + Out[14]: + + array([[ 0., nan], + [ 1., 2.]]) + Coordinates: + * x (x) object 'a' 'b' + * y (y) int64 0 1 + + In [26]: arr.unstack("z").stack(z=("x", "y")) + Out[26]: + + array([ 0., nan, 1., 2.]) + Coordinates: + * z (z) object ('a', 0) ('a', 1) ('b', 0) ('b', 1) + + See :ref:`reshape.stack` for more details. + .. warning:: - - This is the last xarray release that will support Python 2.7. Future releases - will be Python 3 only, but older versions of xarray will always be available - for Python 2.7 users. For the more details, see: - - - `Xarray Github issue discussing dropping Python 2 `__ - - `Python 3 Statement `__ - - `Tips on porting to Python 3 `__ - - .. _whats-new.0.11.1: - - v0.11.1 (29 December 2018) - -------------------------- - - This minor release includes a number of enhancements and bug fixes, and two - (slightly) breaking changes. - - Breaking changes - ~~~~~~~~~~~~~~~~ - - - Minimum rasterio version increased from 0.36 to 1.0 (for ``open_rasterio``) - - Time bounds variables are now also decoded according to CF conventions - (:issue:`2565`). The previous behavior was to decode them only if they - had specific time attributes, now these attributes are copied - automatically from the corresponding time coordinate. This might - break downstream code that was relying on these variables to be - brake downstream code that was relying on these variables to be - not decoded. - By `Fabien Maussion `_. - - Enhancements - ~~~~~~~~~~~~ - - - Ability to read and write consolidated metadata in zarr stores (:issue:`2558`). - By `Ryan Abernathey `_. - - :py:class:`CFTimeIndex` uses slicing for string indexing when possible (like - :py:class:`pandas.DatetimeIndex`), which avoids unnecessary copies. - By `Stephan Hoyer `_ - - Enable passing ``rasterio.io.DatasetReader`` or ``rasterio.vrt.WarpedVRT`` to - ``open_rasterio`` instead of file path string. Allows for in-memory - reprojection, see (:issue:`2588`). - By `Scott Henderson `_. - - Like :py:class:`pandas.DatetimeIndex`, :py:class:`CFTimeIndex` now supports - "dayofyear" and "dayofweek" accessors (:issue:`2597`). Note this requires a - version of cftime greater than 1.0.2. By `Spencer Clark - `_. - - The option ``'warn_for_unclosed_files'`` (False by default) has been added to - allow users to enable a warning when files opened by xarray are deallocated - but were not explicitly closed. This is mostly useful for debugging; we - recommend enabling it in your test suites if you use xarray for IO. - By `Stephan Hoyer `_ - - Support Dask ``HighLevelGraphs`` by `Matthew Rocklin `_. - - :py:meth:`DataArray.resample` and :py:meth:`Dataset.resample` now supports the - ``loffset`` kwarg just like Pandas. - By `Deepak Cherian `_ - - Datasets are now guaranteed to have a ``'source'`` encoding, so the source - file name is always stored (:issue:`2550`). - By `Tom Nicholas `_. - - The ``apply`` methods for ``DatasetGroupBy``, ``DataArrayGroupBy``, - ``DatasetResample`` and ``DataArrayResample`` now support passing positional - arguments to the applied function as a tuple to the ``args`` argument. - By `Matti Eskelinen `_. - - 0d slices of ndarrays are now obtained directly through indexing, rather than - extracting and wrapping a scalar, avoiding unnecessary copying. By `Daniel - Wennberg `_. - - Added support for ``fill_value`` with - :py:meth:`~xarray.DataArray.shift` and :py:meth:`~xarray.Dataset.shift` - By `Maximilian Roos `_ - - Bug fixes - ~~~~~~~~~ - - - Ensure files are automatically closed, if possible, when no longer referenced - by a Python variable (:issue:`2560`). - By `Stephan Hoyer `_ - - Fixed possible race conditions when reading/writing to disk in parallel - (:issue:`2595`). - By `Stephan Hoyer `_ - - Fix h5netcdf saving scalars with filters or chunks (:issue:`2563`). - By `Martin Raspaud `_. - - Fix parsing of ``_Unsigned`` attribute set by OPENDAP servers. (:issue:`2583`). - By `Deepak Cherian `_ - - Fix failure in time encoding when exporting to netCDF with versions of pandas - less than 0.21.1 (:issue:`2623`). By `Spencer Clark - `_. - - Fix MultiIndex selection to update label and level (:issue:`2619`). - By `Keisuke Fujii `_. - - .. _whats-new.0.11.0: - - v0.11.0 (7 November 2018) - ------------------------- - - Breaking changes - ~~~~~~~~~~~~~~~~ - - - Finished deprecations (changed behavior with this release): - - - ``Dataset.T`` has been removed as a shortcut for :py:meth:`Dataset.transpose`. - Call :py:meth:`Dataset.transpose` directly instead. - - Iterating over a ``Dataset`` now includes only data variables, not coordinates. - Similarily, calling ``len`` and ``bool`` on a ``Dataset`` now - includes only data variables. - - ``DataArray.__contains__`` (used by Python's ``in`` operator) now checks - array data, not coordinates. - - The old resample syntax from before xarray 0.10, e.g., - ``data.resample('1D', dim='time', how='mean')``, is no longer supported will - raise an error in most cases. You need to use the new resample syntax - instead, e.g., ``data.resample(time='1D').mean()`` or - ``data.resample({'time': '1D'}).mean()``. - - - - New deprecations (behavior will be changed in xarray 0.12): - - - Reduction of :py:meth:`DataArray.groupby` and :py:meth:`DataArray.resample` - without dimension argument will change in the next release. - Now we warn a FutureWarning. - By `Keisuke Fujii `_. - - The ``inplace`` kwarg of a number of `DataArray` and `Dataset` methods is being - deprecated and will be removed in the next release. - By `Deepak Cherian `_. - - - - Refactored storage backends: - - - Xarray's storage backends now automatically open and close files when - necessary, rather than requiring opening a file with ``autoclose=True``. A - global least-recently-used cache is used to store open files; the default - limit of 128 open files should suffice in most cases, but can be adjusted if - necessary with - ``xarray.set_options(file_cache_maxsize=...)``. The ``autoclose`` argument - to ``open_dataset`` and related functions has been deprecated and is now a - no-op. - - This change, along with an internal refactor of xarray's storage backends, - should significantly improve performance when reading and writing - netCDF files with Dask, especially when working with many files or using - Dask Distributed. By `Stephan Hoyer `_ - - - - Support for non-standard calendars used in climate science: - - - Xarray will now always use :py:class:`cftime.datetime` objects, rather - than by default trying to coerce them into ``np.datetime64[ns]`` objects. - A :py:class:`~xarray.CFTimeIndex` will be used for indexing along time - coordinates in these cases. - - A new method :py:meth:`~xarray.CFTimeIndex.to_datetimeindex` has been added - to aid in converting from a :py:class:`~xarray.CFTimeIndex` to a - :py:class:`pandas.DatetimeIndex` for the remaining use-cases where - using a :py:class:`~xarray.CFTimeIndex` is still a limitation (e.g. for - resample or plotting). - - Setting the ``enable_cftimeindex`` option is now a no-op and emits a - ``FutureWarning``. - - Enhancements - ~~~~~~~~~~~~ - - - :py:meth:`xarray.DataArray.plot.line` can now accept multidimensional - coordinate variables as input. `hue` must be a dimension name in this case. - (:issue:`2407`) - By `Deepak Cherian `_. - - Added support for Python 3.7. (:issue:`2271`). - By `Joe Hamman `_. - - Added support for plotting data with `pandas.Interval` coordinates, such as those - created by :py:meth:`~xarray.DataArray.groupby_bins` - By `Maximilian Maahn `_. - - Added :py:meth:`~xarray.CFTimeIndex.shift` for shifting the values of a - CFTimeIndex by a specified frequency. (:issue:`2244`). - By `Spencer Clark `_. - - Added support for using ``cftime.datetime`` coordinates with - :py:meth:`~xarray.DataArray.differentiate`, - :py:meth:`~xarray.Dataset.differentiate`, - :py:meth:`~xarray.DataArray.interp`, and - :py:meth:`~xarray.Dataset.interp`. - By `Spencer Clark `_ - - There is now a global option to either always keep or always discard - dataset and dataarray attrs upon operations. The option is set with - ``xarray.set_options(keep_attrs=True)``, and the default is to use the old - behaviour. - By `Tom Nicholas `_. - - Added a new backend for the GRIB file format based on ECMWF *cfgrib* - python driver and *ecCodes* C-library. (:issue:`2475`) - By `Alessandro Amici `_, - sponsored by `ECMWF `_. - - Resample now supports a dictionary mapping from dimension to frequency as - its first argument, e.g., ``data.resample({'time': '1D'}).mean()``. This is - consistent with other xarray functions that accept either dictionaries or - keyword arguments. By `Stephan Hoyer `_. - - - The preferred way to access tutorial data is now to load it lazily with - :py:meth:`xarray.tutorial.open_dataset`. - :py:meth:`xarray.tutorial.load_dataset` calls `Dataset.load()` prior - to returning (and is now deprecated). This was changed in order to facilitate - using tutorial datasets with dask. - By `Joe Hamman `_. - - ``DataArray`` can now use ``xr.set_option(keep_attrs=True)`` and retain attributes in binary operations, - such as (``+, -, * ,/``). Default behaviour is unchanged (*Attributes will be dismissed*). By `Michael Blaschek `_ - - Bug fixes - ~~~~~~~~~ - - - ``FacetGrid`` now properly uses the ``cbar_kwargs`` keyword argument. - (:issue:`1504`, :issue:`1717`) - By `Deepak Cherian `_. - - Addition and subtraction operators used with a CFTimeIndex now preserve the - index's type. (:issue:`2244`). - By `Spencer Clark `_. - - We now properly handle arrays of ``datetime.datetime`` and ``datetime.timedelta`` - provided as coordinates. (:issue:`2512`) - By `Deepak Cherian `_. - - ``xarray.DataArray.roll`` correctly handles multidimensional arrays. - (:issue:`2445`) - By `Keisuke Fujii `_. - - ``xarray.plot()`` now properly accepts a ``norm`` argument and does not override - the norm's ``vmin`` and ``vmax``. (:issue:`2381`) - By `Deepak Cherian `_. - - ``xarray.DataArray.std()`` now correctly accepts ``ddof`` keyword argument. - (:issue:`2240`) - By `Keisuke Fujii `_. - - Restore matplotlib's default of plotting dashed negative contours when - a single color is passed to ``DataArray.contour()`` e.g. ``colors='k'``. - By `Deepak Cherian `_. - - - - Fix a bug that caused some indexing operations on arrays opened with - ``open_rasterio`` to error (:issue:`2454`). - By `Stephan Hoyer `_. - - - Subtracting one CFTimeIndex from another now returns a - ``pandas.TimedeltaIndex``, analogous to the behavior for DatetimeIndexes - (:issue:`2484`). By `Spencer Clark `_. - - Adding a TimedeltaIndex to, or subtracting a TimedeltaIndex from a - CFTimeIndex is now allowed (:issue:`2484`). - By `Spencer Clark `_. - - Avoid use of Dask's deprecated ``get=`` parameter in tests - by `Matthew Rocklin `_. - - An ``OverflowError`` is now accurately raised and caught during the - encoding process if a reference date is used that is so distant that - the dates must be encoded using cftime rather than NumPy (:issue:`2272`). - By `Spencer Clark `_. - - - Chunked datasets can now roundtrip to Zarr storage continually - with `to_zarr` and ``open_zarr`` (:issue:`2300`). - By `Lily Wang `_. - - .. _whats-new.0.10.9: - - v0.10.9 (21 September 2018) - --------------------------- - - This minor release contains a number of backwards compatible enhancements. - - Announcements of note: - - - Xarray is now a NumFOCUS fiscally sponsored project! Read - `the anouncement `_ - for more details. - - We have a new :doc:`roadmap` that outlines our future development plans. - - - ``Dataset.apply`` now properly documents the way `func` is called. - By `Matti Eskelinen `_. - - Enhancements - ~~~~~~~~~~~~ - - - :py:meth:`~xarray.DataArray.differentiate` and - :py:meth:`~xarray.Dataset.differentiate` are newly added. - (:issue:`1332`) - By `Keisuke Fujii `_. - - - Default colormap for sequential and divergent data can now be set via - :py:func:`~xarray.set_options()` - (:issue:`2394`) - By `Julius Busecke `_. - - - min_count option is newly supported in :py:meth:`~xarray.DataArray.sum`, - :py:meth:`~xarray.DataArray.prod` and :py:meth:`~xarray.Dataset.sum`, and - :py:meth:`~xarray.Dataset.prod`. - (:issue:`2230`) - By `Keisuke Fujii `_. - - - :py:func:`~plot.plot()` now accepts the kwargs - ``xscale, yscale, xlim, ylim, xticks, yticks`` just like Pandas. Also ``xincrease=False, yincrease=False`` now use matplotlib's axis inverting methods instead of setting limits. - By `Deepak Cherian `_. (:issue:`2224`) - - - DataArray coordinates and Dataset coordinates and data variables are - now displayed as `a b ... y z` rather than `a b c d ...`. - (:issue:`1186`) - By `Seth P `_. - - A new CFTimeIndex-enabled :py:func:`cftime_range` function for use in - generating dates from standard or non-standard calendars. By `Spencer Clark - `_. - - - When interpolating over a ``datetime64`` axis, you can now provide a datetime string instead of a ``datetime64`` object. E.g. ``da.interp(time='1991-02-01')`` - (:issue:`2284`) - By `Deepak Cherian `_. - - - A clear error message is now displayed if a ``set`` or ``dict`` is passed in place of an array - (:issue:`2331`) - By `Maximilian Roos `_. - - - Applying ``unstack`` to a large DataArray or Dataset is now much faster if the MultiIndex has not been modified after stacking the indices. - (:issue:`1560`) - By `Maximilian Maahn `_. - - - You can now control whether or not to offset the coordinates when using - the ``roll`` method and the current behavior, coordinates rolled by default, - raises a deprecation warning unless explicitly setting the keyword argument. - (:issue:`1875`) - By `Andrew Huang `_. - - - You can now call ``unstack`` without arguments to unstack every MultiIndex in a DataArray or Dataset. - By `Julia Signell `_. - - - Added the ability to pass a data kwarg to ``copy`` to create a new object with the - same metadata as the original object but using new values. - By `Julia Signell `_. - - Bug fixes - ~~~~~~~~~ - - - ``xarray.plot.imshow()`` correctly uses the ``origin`` argument. - (:issue:`2379`) - By `Deepak Cherian `_. - - - Fixed ``DataArray.to_iris()`` failure while creating ``DimCoord`` by - falling back to creating ``AuxCoord``. Fixed dependency on ``var_name`` - attribute being set. - (:issue:`2201`) - By `Thomas Voigt `_. - - Fixed a bug in ``zarr`` backend which prevented use with datasets with - invalid chunk size encoding after reading from an existing store - (:issue:`2278`). - By `Joe Hamman `_. - - - Tests can be run in parallel with pytest-xdist - By `Tony Tung `_. - - - Follow up the renamings in dask; from dask.ghost to dask.overlap - By `Keisuke Fujii `_. - - - Now raises a ValueError when there is a conflict between dimension names and - level names of MultiIndex. (:issue:`2299`) - By `Keisuke Fujii `_. - - - Follow up the renamings in dask; from dask.ghost to dask.overlap - By `Keisuke Fujii `_. - - - Now :py:func:`~xarray.apply_ufunc` raises a ValueError when the size of - ``input_core_dims`` is inconsistent with the number of arguments. - (:issue:`2341`) - By `Keisuke Fujii `_. - - - Fixed ``Dataset.filter_by_attrs()`` behavior not matching ``netCDF4.Dataset.get_variables_by_attributes()``. - When more than one ``key=value`` is passed into ``Dataset.filter_by_attrs()`` it will now return a Dataset with variables which pass - all the filters. - (:issue:`2315`) - By `Andrew Barna `_. - - .. _whats-new.0.10.8: - - v0.10.8 (18 July 2018) - ---------------------- - - Breaking changes - ~~~~~~~~~~~~~~~~ - - - Xarray no longer supports python 3.4. Additionally, the minimum supported - versions of the following dependencies has been updated and/or clarified: - - - Pandas: 0.18 -> 0.19 - - NumPy: 1.11 -> 1.12 - - Dask: 0.9 -> 0.16 - - Matplotlib: unspecified -> 1.5 - - (:issue:`2204`). By `Joe Hamman `_. - - Enhancements - ~~~~~~~~~~~~ - - - :py:meth:`~xarray.DataArray.interp_like` and - :py:meth:`~xarray.Dataset.interp_like` methods are newly added. - (:issue:`2218`) - By `Keisuke Fujii `_. - - - Added support for curvilinear and unstructured generic grids - to :py:meth:`~xarray.DataArray.to_cdms2` and - :py:meth:`~xarray.DataArray.from_cdms2` (:issue:`2262`). - By `Stephane Raynaud `_. - - Bug fixes - ~~~~~~~~~ - - - Fixed a bug in ``zarr`` backend which prevented use with datasets with - incomplete chunks in multiple dimensions (:issue:`2225`). - By `Joe Hamman `_. - - - Fixed a bug in :py:meth:`~Dataset.to_netcdf` which prevented writing - datasets when the arrays had different chunk sizes (:issue:`2254`). - By `Mike Neish `_. - - - Fixed masking during the conversion to cdms2 objects by - :py:meth:`~xarray.DataArray.to_cdms2` (:issue:`2262`). - By `Stephane Raynaud `_. - - - Fixed a bug in 2D plots which incorrectly raised an error when 2D coordinates - weren't monotonic (:issue:`2250`). - By `Fabien Maussion `_. - - - Fixed warning raised in :py:meth:`~Dataset.to_netcdf` due to deprecation of - `effective_get` in dask (:issue:`2238`). - By `Joe Hamman `_. - - .. _whats-new.0.10.7: - - v0.10.7 (7 June 2018) - --------------------- - - Enhancements - ~~~~~~~~~~~~ - - - Plot labels now make use of metadata that follow CF conventions - (:issue:`2135`). - By `Deepak Cherian `_ and `Ryan Abernathey `_. - - - Line plots now support facetting with ``row`` and ``col`` arguments - (:issue:`2107`). - By `Yohai Bar Sinai `_. - - - :py:meth:`~xarray.DataArray.interp` and :py:meth:`~xarray.Dataset.interp` - methods are newly added. - See :ref:`interp` for the detail. - (:issue:`2079`) - By `Keisuke Fujii `_. - - Bug fixes - ~~~~~~~~~ - - - Fixed a bug in ``rasterio`` backend which prevented use with ``distributed``. - The ``rasterio`` backend now returns pickleable objects (:issue:`2021`). - By `Joe Hamman `_. - - .. _whats-new.0.10.6: - - v0.10.6 (31 May 2018) - --------------------- - - The minor release includes a number of bug-fixes and backwards compatible - enhancements. - - Enhancements - ~~~~~~~~~~~~ - - - New PseudoNetCDF backend for many Atmospheric data formats including - GEOS-Chem, CAMx, NOAA arlpacked bit and many others. See - :ref:`io.PseudoNetCDF` for more details. - By `Barron Henderson `_. - - - The :py:class:`Dataset` constructor now aligns :py:class:`DataArray` - arguments in ``data_vars`` to indexes set explicitly in ``coords``, - where previously an error would be raised. - (:issue:`674`) - By `Maximilian Roos `_. - - - :py:meth:`~DataArray.sel`, :py:meth:`~DataArray.isel` & :py:meth:`~DataArray.reindex`, - (and their :py:class:`Dataset` counterparts) now support supplying a ``dict`` - as a first argument, as an alternative to the existing approach - of supplying `kwargs`. This allows for more robust behavior - of dimension names which conflict with other keyword names, or are - not strings. - By `Maximilian Roos `_. - - - :py:meth:`~DataArray.rename` now supports supplying ``**kwargs``, as an - alternative to the existing approach of supplying a ``dict`` as the - first argument. - By `Maximilian Roos `_. - - - :py:meth:`~DataArray.cumsum` and :py:meth:`~DataArray.cumprod` now support - aggregation over multiple dimensions at the same time. This is the default - behavior when dimensions are not specified (previously this raised an error). - By `Stephan Hoyer `_ - - - :py:meth:`DataArray.dot` and :py:func:`dot` are partly supported with older - dask<0.17.4. (related to :issue:`2203`) - By `Keisuke Fujii `_. - - - Xarray now uses `Versioneer `__ - to manage its version strings. (:issue:`1300`). - By `Joe Hamman `_. - - Bug fixes - ~~~~~~~~~ - - - Fixed a regression in 0.10.4, where explicitly specifying ``dtype='S1'`` or - ``dtype=str`` in ``encoding`` with ``to_netcdf()`` raised an error - (:issue:`2149`). - `Stephan Hoyer `_ - - - :py:func:`apply_ufunc` now directly validates output variables - (:issue:`1931`). - By `Stephan Hoyer `_. - - - Fixed a bug where ``to_netcdf(..., unlimited_dims='bar')`` yielded NetCDF - files with spurious 0-length dimensions (i.e. ``b``, ``a``, and ``r``) - (:issue:`2134`). - By `Joe Hamman `_. - - - Removed spurious warnings with ``Dataset.update(Dataset)`` (:issue:`2161`) - and ``array.equals(array)`` when ``array`` contains ``NaT`` (:issue:`2162`). - By `Stephan Hoyer `_. - - - Aggregations with :py:meth:`Dataset.reduce` (including ``mean``, ``sum``, - etc) no longer drop unrelated coordinates (:issue:`1470`). Also fixed a - bug where non-scalar data-variables that did not include the aggregation - dimension were improperly skipped. - By `Stephan Hoyer `_ - - - Fix :meth:`~DataArray.stack` with non-unique coordinates on pandas 0.23 - (:issue:`2160`). - By `Stephan Hoyer `_ - - - Selecting data indexed by a length-1 ``CFTimeIndex`` with a slice of strings - now behaves as it does when using a length-1 ``DatetimeIndex`` (i.e. it no - longer falsely returns an empty array when the slice includes the value in - the index) (:issue:`2165`). - By `Spencer Clark `_. - - - Fix ``DataArray.groupby().reduce()`` mutating coordinates on the input array - when grouping over dimension coordinates with duplicated entries - (:issue:`2153`). - By `Stephan Hoyer `_ - - - Fix ``Dataset.to_netcdf()`` cannot create group with ``engine="h5netcdf"`` - (:issue:`2177`). - By `Stephan Hoyer `_ - - .. _whats-new.0.10.4: - - v0.10.4 (16 May 2018) - ---------------------- - - The minor release includes a number of bug-fixes and backwards compatible - enhancements. A highlight is ``CFTimeIndex``, which offers support for - non-standard calendars used in climate modeling. - - Documentation - ~~~~~~~~~~~~~ - - - New FAQ entry, :ref:`ecosystem`. - By `Deepak Cherian `_. - - :ref:`assigning_values` now includes examples on how to select and assign - values to a :py:class:`~xarray.DataArray` with ``.loc``. - By `Chiara Lepore `_. - - Enhancements - ~~~~~~~~~~~~ - - - Add an option for using a ``CFTimeIndex`` for indexing times with - non-standard calendars and/or outside the Timestamp-valid range; this index - enables a subset of the functionality of a standard - ``pandas.DatetimeIndex``. - See :ref:`CFTimeIndex` for full details. - (:issue:`789`, :issue:`1084`, :issue:`1252`) - By `Spencer Clark `_ with help from - `Stephan Hoyer `_. - - Allow for serialization of ``cftime.datetime`` objects (:issue:`789`, - :issue:`1084`, :issue:`2008`, :issue:`1252`) using the standalone ``cftime`` - library. - By `Spencer Clark `_. - - Support writing lists of strings as netCDF attributes (:issue:`2044`). - By `Dan Nowacki `_. - - :py:meth:`~xarray.Dataset.to_netcdf` with ``engine='h5netcdf'`` now accepts h5py - encoding settings ``compression`` and ``compression_opts``, along with the - NetCDF4-Python style settings ``gzip=True`` and ``complevel``. - This allows using any compression plugin installed in hdf5, e.g. LZF - (:issue:`1536`). By `Guido Imperiale `_. - - :py:meth:`~xarray.dot` on dask-backed data will now call :func:`dask.array.einsum`. - This greatly boosts speed and allows chunking on the core dims. - The function now requires dask >= 0.17.3 to work on dask-backed data - (:issue:`2074`). By `Guido Imperiale `_. - - ``plot.line()`` learned new kwargs: ``xincrease``, ``yincrease`` that change - the direction of the respective axes. - By `Deepak Cherian `_. - - - Added the ``parallel`` option to :py:func:`open_mfdataset`. This option uses - ``dask.delayed`` to parallelize the open and preprocessing steps within - ``open_mfdataset``. This is expected to provide performance improvements when - opening many files, particularly when used in conjunction with dask's - multiprocessing or distributed schedulers (:issue:`1981`). - By `Joe Hamman `_. - - - New ``compute`` option in :py:meth:`~xarray.Dataset.to_netcdf`, - :py:meth:`~xarray.Dataset.to_zarr`, and :py:func:`~xarray.save_mfdataset` to - allow for the lazy computation of netCDF and zarr stores. This feature is - currently only supported by the netCDF4 and zarr backends. (:issue:`1784`). - By `Joe Hamman `_. - - - Bug fixes - ~~~~~~~~~ - - - ``ValueError`` is raised when coordinates with the wrong size are assigned to - a :py:class:`DataArray`. (:issue:`2112`) - By `Keisuke Fujii `_. - - Fixed a bug in :py:meth:`~xarray.DataArray.rolling` with bottleneck. Also, - fixed a bug in rolling an integer dask array. (:issue:`2113`) - By `Keisuke Fujii `_. - - Fixed a bug where `keep_attrs=True` flag was neglected if - :py:func:`apply_ufunc` was used with :py:class:`Variable`. (:issue:`2114`) - By `Keisuke Fujii `_. - - When assigning a :py:class:`DataArray` to :py:class:`Dataset`, any conflicted - non-dimensional coordinates of the DataArray are now dropped. - (:issue:`2068`) - By `Keisuke Fujii `_. - - Better error handling in ``open_mfdataset`` (:issue:`2077`). - By `Stephan Hoyer `_. - - ``plot.line()`` does not call ``autofmt_xdate()`` anymore. Instead it changes - the rotation and horizontal alignment of labels without removing the x-axes of - any other subplots in the figure (if any). - By `Deepak Cherian `_. - - Colorbar limits are now determined by excluding ±Infs too. - By `Deepak Cherian `_. - By `Joe Hamman `_. - - Fixed ``to_iris`` to maintain lazy dask array after conversion (:issue:`2046`). - By `Alex Hilson `_ and `Stephan Hoyer `_. - - .. _whats-new.0.10.3: - - v0.10.3 (13 April 2018) - ------------------------ - - The minor release includes a number of bug-fixes and backwards compatible enhancements. - - Enhancements - ~~~~~~~~~~~~ - - - :py:meth:`~xarray.DataArray.isin` and :py:meth:`~xarray.Dataset.isin` methods, - which test each value in the array for whether it is contained in the - supplied list, returning a bool array. See :ref:`selecting values with isin` - for full details. Similar to the ``np.isin`` function. - By `Maximilian Roos `_. - - Some speed improvement to construct :py:class:`~xarray.core.rolling.DataArrayRolling` - object (:issue:`1993`) - By `Keisuke Fujii `_. - - Handle variables with different values for ``missing_value`` and - ``_FillValue`` by masking values for both attributes; previously this - resulted in a ``ValueError``. (:issue:`2016`) - By `Ryan May `_. - - Bug fixes - ~~~~~~~~~ - - - Fixed ``decode_cf`` function to operate lazily on dask arrays - (:issue:`1372`). By `Ryan Abernathey `_. - - Fixed labeled indexing with slice bounds given by xarray objects with - datetime64 or timedelta64 dtypes (:issue:`1240`). - By `Stephan Hoyer `_. - - Attempting to convert an xarray.Dataset into a numpy array now raises an - informative error message. - By `Stephan Hoyer `_. - - Fixed a bug in decode_cf_datetime where ``int32`` arrays weren't parsed - correctly (:issue:`2002`). - By `Fabien Maussion `_. - - When calling `xr.auto_combine()` or `xr.open_mfdataset()` with a `concat_dim`, - the resulting dataset will have that one-element dimension (it was - silently dropped, previously) (:issue:`1988`). - By `Ben Root `_. - - .. _whats-new.0.10.2: - - v0.10.2 (13 March 2018) - ----------------------- - - The minor release includes a number of bug-fixes and enhancements, along with - one possibly **backwards incompatible change**. - - Backwards incompatible changes - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - - The addition of ``__array_ufunc__`` for xarray objects (see below) means that - NumPy `ufunc methods`_ (e.g., ``np.add.reduce``) that previously worked on - ``xarray.DataArray`` objects by converting them into NumPy arrays will now - raise ``NotImplementedError`` instead. In all cases, the work-around is - simple: convert your objects explicitly into NumPy arrays before calling the - ufunc (e.g., with ``.values``). - - .. _ufunc methods: https://docs.scipy.org/doc/numpy/reference/ufuncs.html#methods - - Enhancements - ~~~~~~~~~~~~ - - - Added :py:func:`~xarray.dot`, equivalent to :py:func:`numpy.einsum`. - Also, :py:func:`~xarray.DataArray.dot` now supports ``dims`` option, - which specifies the dimensions to sum over. - (:issue:`1951`) - By `Keisuke Fujii `_. - - - Support for writing xarray datasets to netCDF files (netcdf4 backend only) - when using the `dask.distributed `_ - scheduler (:issue:`1464`). - By `Joe Hamman `_. - - - Support lazy vectorized-indexing. After this change, flexible indexing such - as orthogonal/vectorized indexing, becomes possible for all the backend - arrays. Also, lazy ``transpose`` is now also supported. (:issue:`1897`) - By `Keisuke Fujii `_. - - - Implemented NumPy's ``__array_ufunc__`` protocol for all xarray objects - (:issue:`1617`). This enables using NumPy ufuncs directly on - ``xarray.Dataset`` objects with recent versions of NumPy (v1.13 and newer): - - .. ipython:: python - - ds = xr.Dataset({"a": 1}) - np.sin(ds) - - This obliviates the need for the ``xarray.ufuncs`` module, which will be - deprecated in the future when xarray drops support for older versions of - NumPy. By `Stephan Hoyer `_. - - - Improve :py:func:`~xarray.DataArray.rolling` logic. - :py:func:`~xarray.core.rolling.DataArrayRolling` object now supports - :py:func:`~xarray.core.rolling.DataArrayRolling.construct` method that returns a view - of the DataArray / Dataset object with the rolling-window dimension added - to the last axis. This enables more flexible operation, such as strided - rolling, windowed rolling, ND-rolling, short-time FFT and convolution. - (:issue:`1831`, :issue:`1142`, :issue:`819`) - By `Keisuke Fujii `_. - - :py:func:`~plot.line()` learned to make plots with data on x-axis if so specified. (:issue:`575`) - By `Deepak Cherian `_. - - Bug fixes - ~~~~~~~~~ - - - Raise an informative error message when using ``apply_ufunc`` with numpy - v1.11 (:issue:`1956`). - By `Stephan Hoyer `_. - - Fix the precision drop after indexing datetime64 arrays (:issue:`1932`). - By `Keisuke Fujii `_. - - Silenced irrelevant warnings issued by ``open_rasterio`` (:issue:`1964`). - By `Stephan Hoyer `_. - - Fix kwarg `colors` clashing with auto-inferred `cmap` (:issue:`1461`) - By `Deepak Cherian `_. - - Fix :py:func:`~xarray.plot.imshow` error when passed an RGB array with - size one in a spatial dimension. - By `Zac Hatfield-Dodds `_. - - .. _whats-new.0.10.1: - - v0.10.1 (25 February 2018) - -------------------------- - - The minor release includes a number of bug-fixes and backwards compatible enhancements. - - Documentation - ~~~~~~~~~~~~~ - - - Added a new guide on :ref:`contributing` (:issue:`640`) - By `Joe Hamman `_. - - Added apply_ufunc example to :ref:`/examples/weather-data.ipynb#Toy-weather-data` (:issue:`1844`). - By `Liam Brannigan `_. - - New entry `Why don’t aggregations return Python scalars?` in the - :doc:`getting-started-guide/faq` (:issue:`1726`). - By `0x0L `_. - - Enhancements - ~~~~~~~~~~~~ - **New functions and methods**: - - - Added :py:meth:`DataArray.to_iris` and - :py:meth:`DataArray.from_iris` for - converting data arrays to and from Iris_ Cubes with the same data and coordinates - (:issue:`621` and :issue:`37`). - By `Neil Parley `_ and `Duncan Watson-Parris `_. - - Experimental support for using `Zarr`_ as storage layer for xarray - (:issue:`1223`). - By `Ryan Abernathey `_ and - `Joe Hamman `_. - - New :py:meth:`~xarray.DataArray.rank` on arrays and datasets. Requires - bottleneck (:issue:`1731`). - By `0x0L `_. - - ``.dt`` accessor can now ceil, floor and round timestamps to specified frequency. - By `Deepak Cherian `_. - - **Plotting enhancements**: - - - :func:`xarray.plot.imshow` now handles RGB and RGBA images. - Saturation can be adjusted with ``vmin`` and ``vmax``, or with ``robust=True``. - By `Zac Hatfield-Dodds `_. - - :py:func:`~plot.contourf()` learned to contour 2D variables that have both a - 1D coordinate (e.g. time) and a 2D coordinate (e.g. depth as a function of - time) (:issue:`1737`). - By `Deepak Cherian `_. - - :py:func:`~plot.plot()` rotates x-axis ticks if x-axis is time. - By `Deepak Cherian `_. - - :py:func:`~plot.line()` can draw multiple lines if provided with a - 2D variable. - By `Deepak Cherian `_. - - **Other enhancements**: - - - Reduce methods such as :py:func:`DataArray.sum()` now handles object-type array. - - .. ipython:: python - - da = xr.DataArray(np.array([True, False, np.nan], dtype=object), dims="x") - da.sum() - - (:issue:`1866`) - By `Keisuke Fujii `_. - - Reduce methods such as :py:func:`DataArray.sum()` now accepts ``dtype`` - arguments. (:issue:`1838`) - By `Keisuke Fujii `_. - - Added nodatavals attribute to DataArray when using :py:func:`~xarray.open_rasterio`. (:issue:`1736`). - By `Alan Snow `_. - - Use ``pandas.Grouper`` class in xarray resample methods rather than the - deprecated ``pandas.TimeGrouper`` class (:issue:`1766`). - By `Joe Hamman `_. - - Experimental support for parsing ENVI metadata to coordinates and attributes - in :py:func:`xarray.open_rasterio`. - By `Matti Eskelinen `_. - - Reduce memory usage when decoding a variable with a scale_factor, by - converting 8-bit and 16-bit integers to float32 instead of float64 - (:pull:`1840`), and keeping float16 and float32 as float32 (:issue:`1842`). - Correspondingly, encoded variables may also be saved with a smaller dtype. - By `Zac Hatfield-Dodds `_. - - Speed of reindexing/alignment with dask array is orders of magnitude faster - when inserting missing values (:issue:`1847`). - By `Stephan Hoyer `_. - - Fix ``axis`` keyword ignored when applying ``np.squeeze`` to ``DataArray`` (:issue:`1487`). - By `Florian Pinault `_. - - ``netcdf4-python`` has moved the its time handling in the ``netcdftime`` module to - a standalone package (`netcdftime`_). As such, xarray now considers `netcdftime`_ - an optional dependency. One benefit of this change is that it allows for - encoding/decoding of datetimes with non-standard calendars without the - ``netcdf4-python`` dependency (:issue:`1084`). - By `Joe Hamman `_. - - .. _Zarr: http://zarr.readthedocs.io/ - - .. _Iris: http://scitools.org.uk/iris - - .. _netcdftime: https://unidata.github.io/netcdftime - - **New functions/methods** - - - New :py:meth:`~xarray.DataArray.rank` on arrays and datasets. Requires - bottleneck (:issue:`1731`). - By `0x0L `_. - - Bug fixes - ~~~~~~~~~ - - Rolling aggregation with ``center=True`` option now gives the same result - with pandas including the last element (:issue:`1046`). - By `Keisuke Fujii `_. - - - Support indexing with a 0d-np.ndarray (:issue:`1921`). - By `Keisuke Fujii `_. - - Added warning in api.py of a netCDF4 bug that occurs when - the filepath has 88 characters (:issue:`1745`). - By `Liam Brannigan `_. - - Fixed encoding of multi-dimensional coordinates in - :py:meth:`~Dataset.to_netcdf` (:issue:`1763`). - By `Mike Neish `_. - - Fixed chunking with non-file-based rasterio datasets (:issue:`1816`) and - refactored rasterio test suite. - By `Ryan Abernathey `_ - - Bug fix in open_dataset(engine='pydap') (:issue:`1775`) - By `Keisuke Fujii `_. - - Bug fix in vectorized assignment (:issue:`1743`, :issue:`1744`). - Now item assignment to :py:meth:`~DataArray.__setitem__` checks - - Bug fix in vectorized assignment (:issue:`1743`, :issue:`1744`). - Now item assignment to :py:meth:`DataArray.__setitem__` checks - coordinates of target, destination and keys. If there are any conflict among - these coordinates, ``IndexError`` will be raised. - By `Keisuke Fujii `_. - - Properly point ``DataArray.__dask_scheduler__`` to - ``dask.threaded.get``. By `Matthew Rocklin `_. - - Bug fixes in :py:meth:`DataArray.plot.imshow`: all-NaN arrays and arrays - with size one in some dimension can now be plotted, which is good for - exploring satellite imagery (:issue:`1780`). - By `Zac Hatfield-Dodds `_. - - Fixed ``UnboundLocalError`` when opening netCDF file (:issue:`1781`). - By `Stephan Hoyer `_. - - The ``variables``, ``attrs``, and ``dimensions`` properties have been - deprecated as part of a bug fix addressing an issue where backends were - unintentionally loading the datastores data and attributes repeatedly during - writes (:issue:`1798`). - By `Joe Hamman `_. - - Compatibility fixes to plotting module for Numpy 1.14 and Pandas 0.22 - (:issue:`1813`). - By `Joe Hamman `_. - - Bug fix in encoding coordinates with ``{'_FillValue': None}`` in netCDF - metadata (:issue:`1865`). - By `Chris Roth `_. - - Fix indexing with lists for arrays loaded from netCDF files with - ``engine='h5netcdf`` (:issue:`1864`). - By `Stephan Hoyer `_. - - Corrected a bug with incorrect coordinates for non-georeferenced geotiff - files (:issue:`1686`). Internally, we now use the rasterio coordinate - transform tool instead of doing the computations ourselves. A - ``parse_coordinates`` kwarg has beed added to :py:func:`~open_rasterio` - (set to ``True`` per default). - By `Fabien Maussion `_. - - The colors of discrete colormaps are now the same regardless if `seaborn` - is installed or not (:issue:`1896`). - By `Fabien Maussion `_. - - Fixed dtype promotion rules in :py:func:`where` and :py:func:`concat` to - match pandas (:issue:`1847`). A combination of strings/numbers or - unicode/bytes now promote to object dtype, instead of strings or unicode. - By `Stephan Hoyer `_. - - Fixed bug where :py:meth:`~xarray.DataArray.isnull` was loading data - stored as dask arrays (:issue:`1937`). - By `Joe Hamman `_. - - .. _whats-new.0.10.0: - - v0.10.0 (20 November 2017) - -------------------------- - - This is a major release that includes bug fixes, new features and a few - backwards incompatible changes. Highlights include: - - - Indexing now supports broadcasting over dimensions, similar to NumPy's - vectorized indexing (but better!). - - :py:meth:`~DataArray.resample` has a new groupby-like API like pandas. - - :py:func:`~xarray.apply_ufunc` facilitates wrapping and parallelizing - functions written for NumPy arrays. - - Performance improvements, particularly for dask and :py:func:`open_mfdataset`. - - Breaking changes - ~~~~~~~~~~~~~~~~ - - - xarray now supports a form of vectorized indexing with broadcasting, where - the result of indexing depends on dimensions of indexers, - e.g., ``array.sel(x=ind)`` with ``ind.dims == ('y',)``. Alignment between - coordinates on indexed and indexing objects is also now enforced. - Due to these changes, existing uses of xarray objects to index other xarray - objects will break in some cases. - - The new indexing API is much more powerful, supporting outer, diagonal and - vectorized indexing in a single interface. - The ``isel_points`` and ``sel_points`` methods are deprecated, since they are - now redundant with the ``isel`` / ``sel`` methods. - See :ref:`vectorized_indexing` for the details (:issue:`1444`, - :issue:`1436`). - By `Keisuke Fujii `_ and - `Stephan Hoyer `_. - - - A new resampling interface to match pandas' groupby-like API was added to - :py:meth:`Dataset.resample` and :py:meth:`DataArray.resample` - (:issue:`1272`). :ref:`Timeseries resampling ` is - fully supported for data with arbitrary dimensions as is both downsampling - and upsampling (including linear, quadratic, cubic, and spline interpolation). - - Old syntax: - - .. ipython:: - :verbatim: - - In [1]: ds.resample("24H", dim="time", how="max") - Out[1]: - - [...] - - New syntax: - - .. ipython:: - :verbatim: - - In [1]: ds.resample(time="24H").max() - Out[1]: - - [...] - - Note that both versions are currently supported, but using the old syntax will - produce a warning encouraging users to adopt the new syntax. - By `Daniel Rothenberg `_. - - - Calling ``repr()`` or printing xarray objects at the command line or in a - Jupyter Notebook will not longer automatically compute dask variables or - load data on arrays lazily loaded from disk (:issue:`1522`). - By `Guido Imperiale `_. - - - Supplying ``coords`` as a dictionary to the ``DataArray`` constructor without - also supplying an explicit ``dims`` argument is no longer supported. This - behavior was deprecated in version 0.9 but will now raise an error - (:issue:`727`). - - - Several existing features have been deprecated and will change to new - behavior in xarray v0.11. If you use any of them with xarray v0.10, you - should see a ``FutureWarning`` that describes how to update your code: - - - ``Dataset.T`` has been deprecated an alias for ``Dataset.transpose()`` - (:issue:`1232`). In the next major version of xarray, it will provide short- - cut lookup for variables or attributes with name ``'T'``. - - ``DataArray.__contains__`` (e.g., ``key in data_array``) currently checks - for membership in ``DataArray.coords``. In the next major version of - xarray, it will check membership in the array data found in - ``DataArray.values`` instead (:issue:`1267`). - - Direct iteration over and counting a ``Dataset`` (e.g., ``[k for k in ds]``, - ``ds.keys()``, ``ds.values()``, ``len(ds)`` and ``if ds``) currently - includes all variables, both data and coordinates. For improved usability - and consistency with pandas, in the next major version of xarray these will - change to only include data variables (:issue:`884`). Use ``ds.variables``, - ``ds.data_vars`` or ``ds.coords`` as alternatives. - - - Changes to minimum versions of dependencies: - - - Old numpy < 1.11 and pandas < 0.18 are no longer supported (:issue:`1512`). - By `Keisuke Fujii `_. - - The minimum supported version bottleneck has increased to 1.1 - (:issue:`1279`). - By `Joe Hamman `_. - - Enhancements - ~~~~~~~~~~~~ - - **New functions/methods** - - - New helper function :py:func:`~xarray.apply_ufunc` for wrapping functions - written to work on NumPy arrays to support labels on xarray objects - (:issue:`770`). ``apply_ufunc`` also support automatic parallelization for - many functions with dask. See :ref:`comput.wrapping-custom` and - :ref:`dask.automatic-parallelization` for details. - By `Stephan Hoyer `_. - - - Added new method :py:meth:`Dataset.to_dask_dataframe`, convert a dataset into - a dask dataframe. - This allows lazy loading of data from a dataset containing dask arrays (:issue:`1462`). - By `James Munroe `_. - - - New function :py:func:`~xarray.where` for conditionally switching between - values in xarray objects, like :py:func:`numpy.where`: - - .. ipython:: - :verbatim: - - In [1]: import xarray as xr - - In [2]: arr = xr.DataArray([[1, 2, 3], [4, 5, 6]], dims=("x", "y")) - - In [3]: xr.where(arr % 2, "even", "odd") - Out[3]: - - array([['even', 'odd', 'even'], - ['odd', 'even', 'odd']], - dtype='`_. - - - Added :py:func:`~xarray.show_versions` function to aid in debugging - (:issue:`1485`). - By `Joe Hamman `_. - - **Performance improvements** - - - :py:func:`~xarray.concat` was computing variables that aren't in memory - (e.g. dask-based) multiple times; :py:func:`~xarray.open_mfdataset` - was loading them multiple times from disk. Now, both functions will instead - load them at most once and, if they do, store them in memory in the - concatenated array/dataset (:issue:`1521`). - By `Guido Imperiale `_. - - - Speed-up (x 100) of ``xarray.conventions.decode_cf_datetime``. - By `Christian Chwala `_. - - **IO related improvements** - - - Unicode strings (``str`` on Python 3) are now round-tripped successfully even - when written as character arrays (e.g., as netCDF3 files or when using - ``engine='scipy'``) (:issue:`1638`). This is controlled by the ``_Encoding`` - attribute convention, which is also understood directly by the netCDF4-Python - interface. See :ref:`io.string-encoding` for full details. - By `Stephan Hoyer `_. - - - Support for ``data_vars`` and ``coords`` keywords from - :py:func:`~xarray.concat` added to :py:func:`~xarray.open_mfdataset` - (:issue:`438`). Using these keyword arguments can significantly reduce - memory usage and increase speed. - By `Oleksandr Huziy `_. - - - Support for :py:class:`pathlib.Path` objects added to - :py:func:`~xarray.open_dataset`, :py:func:`~xarray.open_mfdataset`, - ``xarray.to_netcdf``, and :py:func:`~xarray.save_mfdataset` - (:issue:`799`): - - .. ipython:: - :verbatim: - - In [2]: from pathlib import Path # In Python 2, use pathlib2! - - In [3]: data_dir = Path("data/") - - In [4]: one_file = data_dir / "dta_for_month_01.nc" - - In [5]: xr.open_dataset(one_file) - Out[5]: - - [...] - - By `Willi Rath `_. - - - You can now explicitly disable any default ``_FillValue`` (``NaN`` for - floating point values) by passing the enconding ``{'_FillValue': None}`` - (:issue:`1598`). - By `Stephan Hoyer `_. - - - More attributes available in :py:attr:`~xarray.Dataset.attrs` dictionary when - raster files are opened with :py:func:`~xarray.open_rasterio`. - By `Greg Brener `_. - - - Support for NetCDF files using an ``_Unsigned`` attribute to indicate that a - a signed integer data type should be interpreted as unsigned bytes - (:issue:`1444`). - By `Eric Bruning `_. - - - Support using an existing, opened netCDF4 ``Dataset`` with - :py:class:`~xarray.backends.NetCDF4DataStore`. This permits creating an - :py:class:`~xarray.Dataset` from a netCDF4 ``Dataset`` that has been opened using - other means (:issue:`1459`). - By `Ryan May `_. - - - Changed :py:class:`~xarray.backends.PydapDataStore` to take a Pydap dataset. - This permits opening Opendap datasets that require authentication, by - instantiating a Pydap dataset with a session object. Also added - :py:meth:`xarray.backends.PydapDataStore.open` which takes a url and session - object (:issue:`1068`). - By `Philip Graae `_. - - - Support reading and writing unlimited dimensions with h5netcdf (:issue:`1636`). - By `Joe Hamman `_. - - **Other improvements** - - - Added ``_ipython_key_completions_`` to xarray objects, to enable - autocompletion for dictionary-like access in IPython, e.g., - ``ds['tem`` + tab -> ``ds['temperature']`` (:issue:`1628`). - By `Keisuke Fujii `_. - - - Support passing keyword arguments to ``load``, ``compute``, and ``persist`` - methods. Any keyword arguments supplied to these methods are passed on to - the corresponding dask function (:issue:`1523`). - By `Joe Hamman `_. - - - Encoding attributes are now preserved when xarray objects are concatenated. - The encoding is copied from the first object (:issue:`1297`). - By `Joe Hamman `_ and - `Gerrit Holl `_. - - - Support applying rolling window operations using bottleneck's moving window - functions on data stored as dask arrays (:issue:`1279`). - By `Joe Hamman `_. - - - Experimental support for the Dask collection interface (:issue:`1674`). - By `Matthew Rocklin `_. - - Bug fixes - ~~~~~~~~~ - - - Suppress ``RuntimeWarning`` issued by ``numpy`` for "invalid value comparisons" - (e.g. ``NaN``). Xarray now behaves similarly to Pandas in its treatment of - binary and unary operations on objects with NaNs (:issue:`1657`). - By `Joe Hamman `_. - - - Unsigned int support for reduce methods with ``skipna=True`` - (:issue:`1562`). - By `Keisuke Fujii `_. - - - Fixes to ensure xarray works properly with pandas 0.21: - - - Fix :py:meth:`~xarray.DataArray.isnull` method (:issue:`1549`). - - :py:meth:`~xarray.DataArray.to_series` and - :py:meth:`~xarray.Dataset.to_dataframe` should not return a ``pandas.MultiIndex`` - for 1D data (:issue:`1548`). - - Fix plotting with datetime64 axis labels (:issue:`1661`). - - By `Stephan Hoyer `_. - - - :py:func:`~xarray.open_rasterio` method now shifts the rasterio - coordinates so that they are centered in each pixel (:issue:`1468`). - By `Greg Brener `_. - - - :py:meth:`~xarray.Dataset.rename` method now doesn't throw errors - if some ``Variable`` is renamed to the same name as another ``Variable`` - as long as that other ``Variable`` is also renamed (:issue:`1477`). This - method now does throw when two ``Variables`` would end up with the same name - after the rename (since one of them would get overwritten in this case). - By `Prakhar Goel `_. - - - Fix :py:func:`xarray.testing.assert_allclose` to actually use ``atol`` and - ``rtol`` arguments when called on ``DataArray`` objects (:issue:`1488`). - By `Stephan Hoyer `_. - - - xarray ``quantile`` methods now properly raise a ``TypeError`` when applied to - objects with data stored as ``dask`` arrays (:issue:`1529`). - By `Joe Hamman `_. - - - Fix positional indexing to allow the use of unsigned integers (:issue:`1405`). - By `Joe Hamman `_ and - `Gerrit Holl `_. - - - Creating a :py:class:`Dataset` now raises ``MergeError`` if a coordinate - shares a name with a dimension but is comprised of arbitrary dimensions - (:issue:`1120`). - By `Joe Hamman `_. - - - :py:func:`~xarray.open_rasterio` method now skips rasterio's ``crs`` - attribute if its value is ``None`` (:issue:`1520`). - By `Leevi Annala `_. - - - Fix :py:func:`xarray.DataArray.to_netcdf` to return bytes when no path is - provided (:issue:`1410`). - By `Joe Hamman `_. - - - Fix :py:func:`xarray.save_mfdataset` to properly raise an informative error - when objects other than ``Dataset`` are provided (:issue:`1555`). - By `Joe Hamman `_. - - - :py:func:`xarray.Dataset.copy` would not preserve the encoding property - (:issue:`1586`). - By `Guido Imperiale `_. - - - :py:func:`xarray.concat` would eagerly load dask variables into memory if - the first argument was a numpy variable (:issue:`1588`). - By `Guido Imperiale `_. - - - Fix bug in :py:meth:`~xarray.Dataset.to_netcdf` when writing in append mode - (:issue:`1215`). - By `Joe Hamman `_. - - - Fix ``netCDF4`` backend to properly roundtrip the ``shuffle`` encoding option - (:issue:`1606`). - By `Joe Hamman `_. - - - Fix bug when using ``pytest`` class decorators to skiping certain unittests. - The previous behavior unintentionally causing additional tests to be skipped - (:issue:`1531`). By `Joe Hamman `_. - - - Fix pynio backend for upcoming release of pynio with Python 3 support - (:issue:`1611`). By `Ben Hillman `_. - - - Fix ``seaborn`` import warning for Seaborn versions 0.8 and newer when the - ``apionly`` module was deprecated. - (:issue:`1633`). By `Joe Hamman `_. - - - Fix COMPAT: MultiIndex checking is fragile - (:issue:`1833`). By `Florian Pinault `_. - - - Fix ``rasterio`` backend for Rasterio versions 1.0alpha10 and newer. - (:issue:`1641`). By `Chris Holden `_. - - Bug fixes after rc1 - ~~~~~~~~~~~~~~~~~~~ - - - Suppress warning in IPython autocompletion, related to the deprecation - of ``.T`` attributes (:issue:`1675`). - By `Keisuke Fujii `_. - - - Fix a bug in lazily-indexing netCDF array. (:issue:`1688`) - By `Keisuke Fujii `_. - - - (Internal bug) MemoryCachedArray now supports the orthogonal indexing. - Also made some internal cleanups around array wrappers (:issue:`1429`). - By `Keisuke Fujii `_. - - - (Internal bug) MemoryCachedArray now always wraps ``np.ndarray`` by - ``NumpyIndexingAdapter``. (:issue:`1694`) - By `Keisuke Fujii `_. - - - Fix importing xarray when running Python with ``-OO`` (:issue:`1706`). - By `Stephan Hoyer `_. - - - Saving a netCDF file with a coordinates with a spaces in its names now raises - an appropriate warning (:issue:`1689`). - By `Stephan Hoyer `_. - - - Fix two bugs that were preventing dask arrays from being specified as - coordinates in the DataArray constructor (:issue:`1684`). - By `Joe Hamman `_. - - - Fixed ``apply_ufunc`` with ``dask='parallelized'`` for scalar arguments - (:issue:`1697`). - By `Stephan Hoyer `_. - - - Fix "Chunksize cannot exceed dimension size" error when writing netCDF4 files - loaded from disk (:issue:`1225`). - By `Stephan Hoyer `_. - - - Validate the shape of coordinates with names matching dimensions in the - DataArray constructor (:issue:`1709`). - By `Stephan Hoyer `_. - - - Raise ``NotImplementedError`` when attempting to save a MultiIndex to a - netCDF file (:issue:`1547`). - By `Stephan Hoyer `_. - - - Remove netCDF dependency from rasterio backend tests. - By `Matti Eskelinen `_ - - Bug fixes after rc2 - ~~~~~~~~~~~~~~~~~~~ - - - Fixed unexpected behavior in ``Dataset.set_index()`` and - ``DataArray.set_index()`` introduced by Pandas 0.21.0. Setting a new - index with a single variable resulted in 1-level - ``pandas.MultiIndex`` instead of a simple ``pandas.Index`` - (:issue:`1722`). By `Benoit Bovy `_. - - - Fixed unexpected memory loading of backend arrays after ``print``. - (:issue:`1720`). By `Keisuke Fujii `_. - - .. _whats-new.0.9.6: - - v0.9.6 (8 June 2017) - -------------------- - - This release includes a number of backwards compatible enhancements and bug - fixes. - - Enhancements - ~~~~~~~~~~~~ - - - New :py:meth:`~xarray.Dataset.sortby` method to ``Dataset`` and ``DataArray`` - that enable sorting along dimensions (:issue:`967`). - See :ref:`the docs ` for examples. - By `Chun-Wei Yuan `_ and - `Kyle Heuton `_. - - - Add ``.dt`` accessor to DataArrays for computing datetime-like properties - for the values they contain, similar to ``pandas.Series`` (:issue:`358`). - By `Daniel Rothenberg `_. - - - Renamed internal dask arrays created by ``open_dataset`` to match new dask - conventions (:issue:`1343`). - By `Ryan Abernathey `_. - - - :py:meth:`~xarray.as_variable` is now part of the public API (:issue:`1303`). - By `Benoit Bovy `_. - - - :py:func:`~xarray.align` now supports ``join='exact'``, which raises - an error instead of aligning when indexes to be aligned are not equal. - By `Stephan Hoyer `_. - - - New function :py:func:`~xarray.open_rasterio` for opening raster files with - the `rasterio `_ library. - See :ref:`the docs ` for details. - By `Joe Hamman `_, - `Nic Wayand `_ and - `Fabien Maussion `_ - - Bug fixes - ~~~~~~~~~ - - - Fix error from repeated indexing of datasets loaded from disk (:issue:`1374`). - By `Stephan Hoyer `_. - - - Fix a bug where ``.isel_points`` wrongly assigns unselected coordinate to - ``data_vars``. - By `Keisuke Fujii `_. - - - Tutorial datasets are now checked against a reference MD5 sum to confirm - successful download (:issue:`1392`). By `Matthew Gidden - `_. - - - ``DataArray.chunk()`` now accepts dask specific kwargs like - ``Dataset.chunk()`` does. By `Fabien Maussion `_. - - - Support for ``engine='pydap'`` with recent releases of Pydap (3.2.2+), - including on Python 3 (:issue:`1174`). - - Documentation - ~~~~~~~~~~~~~ - - - A new `gallery `_ - allows to add interactive examples to the documentation. - By `Fabien Maussion `_. - - Testing - ~~~~~~~ - - - Fix test suite failure caused by changes to ``pandas.cut`` function - (:issue:`1386`). - By `Ryan Abernathey `_. - - - Enhanced tests suite by use of ``@network`` decorator, which is - controlled via ``--run-network-tests`` command line argument - to ``py.test`` (:issue:`1393`). - By `Matthew Gidden `_. - - .. _whats-new.0.9.5: - - v0.9.5 (17 April, 2017) - ----------------------- - - Remove an inadvertently introduced print statement. - - .. _whats-new.0.9.3: - - v0.9.3 (16 April, 2017) - ----------------------- - - This minor release includes bug-fixes and backwards compatible enhancements. - - Enhancements - ~~~~~~~~~~~~ - - - New :py:meth:`~xarray.DataArray.persist` method to Datasets and DataArrays to - enable persisting data in distributed memory when using Dask (:issue:`1344`). - By `Matthew Rocklin `_. - - - New :py:meth:`~xarray.DataArray.expand_dims` method for ``DataArray`` and - ``Dataset`` (:issue:`1326`). - By `Keisuke Fujii `_. - - Bug fixes - ~~~~~~~~~ - - - Fix ``.where()`` with ``drop=True`` when arguments do not have indexes - (:issue:`1350`). This bug, introduced in v0.9, resulted in xarray producing - incorrect results in some cases. - By `Stephan Hoyer `_. - - - Fixed writing to file-like objects with :py:meth:`~xarray.Dataset.to_netcdf` - (:issue:`1320`). - `Stephan Hoyer `_. - - - Fixed explicitly setting ``engine='scipy'`` with ``to_netcdf`` when not - providing a path (:issue:`1321`). - `Stephan Hoyer `_. - - - Fixed open_dataarray does not pass properly its parameters to open_dataset - (:issue:`1359`). - `Stephan Hoyer `_. - - - Ensure test suite works when runs from an installed version of xarray - (:issue:`1336`). Use ``@pytest.mark.slow`` instead of a custom flag to mark - slow tests. - By `Stephan Hoyer `_ - - .. _whats-new.0.9.2: - - v0.9.2 (2 April 2017) - --------------------- - - The minor release includes bug-fixes and backwards compatible enhancements. - - Enhancements - ~~~~~~~~~~~~ - - - ``rolling`` on Dataset is now supported (:issue:`859`). - - - ``.rolling()`` on Dataset is now supported (:issue:`859`). - By `Keisuke Fujii `_. - - - When bottleneck version 1.1 or later is installed, use bottleneck for rolling - ``var``, ``argmin``, ``argmax``, and ``rank`` computations. Also, rolling - median now accepts a ``min_periods`` argument (:issue:`1276`). - By `Joe Hamman `_. - - - When ``.plot()`` is called on a 2D DataArray and only one dimension is - specified with ``x=`` or ``y=``, the other dimension is now guessed - (:issue:`1291`). - By `Vincent Noel `_. - - - Added new method :py:meth:`~Dataset.assign_attrs` to ``DataArray`` and - ``Dataset``, a chained-method compatible implementation of the - ``dict.update`` method on attrs (:issue:`1281`). - By `Henry S. Harrison `_. - - - Added new ``autoclose=True`` argument to - :py:func:`~xarray.open_mfdataset` to explicitly close opened files when not in - use to prevent occurrence of an OS Error related to too many open files - (:issue:`1198`). - Note, the default is ``autoclose=False``, which is consistent with - previous xarray behavior. - By `Phillip J. Wolfram `_. - - - The ``repr()`` of ``Dataset`` and ``DataArray`` attributes uses a similar - format to coordinates and variables, with vertically aligned entries - truncated to fit on a single line (:issue:`1319`). Hopefully this will stop - people writing ``data.attrs = {}`` and discarding metadata in notebooks for - the sake of cleaner output. The full metadata is still available as - ``data.attrs``. - By `Zac Hatfield-Dodds `_. - - - Enhanced tests suite by use of ``@slow`` and ``@flaky`` decorators, which are - controlled via ``--run-flaky`` and ``--skip-slow`` command line arguments - to ``py.test`` (:issue:`1336`). - By `Stephan Hoyer `_ and - `Phillip J. Wolfram `_. - - - New aggregation on rolling objects :py:meth:`~core.rolling.DataArrayRolling.count` - which providing a rolling count of valid values (:issue:`1138`). - - Bug fixes - ~~~~~~~~~ - - Rolling operations now keep preserve original dimension order (:issue:`1125`). - By `Keisuke Fujii `_. - - - Fixed ``sel`` with ``method='nearest'`` on Python 2.7 and 64-bit Windows - (:issue:`1140`). - `Stephan Hoyer `_. - - - Fixed ``where`` with ``drop='True'`` for empty masks (:issue:`1341`). - By `Stephan Hoyer `_ and - `Phillip J. Wolfram `_. - - .. _whats-new.0.9.1: - - v0.9.1 (30 January 2017) - ------------------------ - - Renamed the "Unindexed dimensions" section in the ``Dataset`` and - ``DataArray`` repr (added in v0.9.0) to "Dimensions without coordinates" - (:issue:`1199`). - - .. _whats-new.0.9.0: - - v0.9.0 (25 January 2017) - ------------------------ - - This major release includes five months worth of enhancements and bug fixes from - 24 contributors, including some significant changes that are not fully backwards - compatible. Highlights include: - - - Coordinates are now *optional* in the xarray data model, even for dimensions. - - Changes to caching, lazy loading and pickling to improve xarray's experience - for parallel computing. - - Improvements for accessing and manipulating ``pandas.MultiIndex`` levels. - - Many new methods and functions, including - :py:meth:`~DataArray.quantile`, - :py:meth:`~DataArray.cumsum`, - :py:meth:`~DataArray.cumprod` - :py:attr:`~DataArray.combine_first` - :py:meth:`~DataArray.set_index`, - :py:meth:`~DataArray.reset_index`, - :py:meth:`~DataArray.reorder_levels`, - :py:func:`~xarray.full_like`, - :py:func:`~xarray.zeros_like`, - :py:func:`~xarray.ones_like` - :py:func:`~xarray.open_dataarray`, - :py:meth:`~DataArray.compute`, - :py:meth:`Dataset.info`, - :py:func:`testing.assert_equal`, - :py:func:`testing.assert_identical`, and - :py:func:`testing.assert_allclose`. - - Breaking changes - ~~~~~~~~~~~~~~~~ - - - Index coordinates for each dimensions are now optional, and no longer created - by default :issue:`1017`. You can identify such dimensions without coordinates - by their appearance in list of "Dimensions without coordinates" in the - ``Dataset`` or ``DataArray`` repr: - - .. ipython:: - :verbatim: - - In [1]: xr.Dataset({"foo": (("x", "y"), [[1, 2]])}) - Out[1]: - - Dimensions: (x: 1, y: 2) - Dimensions without coordinates: x, y - Data variables: - foo (x, y) int64 1 2 - - This has a number of implications: - - - :py:func:`~align` and :py:meth:`~Dataset.reindex` can now error, if - dimensions labels are missing and dimensions have different sizes. - - Because pandas does not support missing indexes, methods such as - ``to_dataframe``/``from_dataframe`` and ``stack``/``unstack`` no longer - roundtrip faithfully on all inputs. Use :py:meth:`~Dataset.reset_index` to - remove undesired indexes. - - ``Dataset.__delitem__`` and :py:meth:`~Dataset.drop` no longer delete/drop - variables that have dimensions matching a deleted/dropped variable. - - ``DataArray.coords.__delitem__`` is now allowed on variables matching - dimension names. - - ``.sel`` and ``.loc`` now handle indexing along a dimension without - coordinate labels by doing integer based indexing. See - :ref:`indexing.missing_coordinates` for an example. - - :py:attr:`~Dataset.indexes` is no longer guaranteed to include all - dimensions names as keys. The new method :py:meth:`~Dataset.get_index` has - been added to get an index for a dimension guaranteed, falling back to - produce a default ``RangeIndex`` if necessary. - - - The default behavior of ``merge`` is now ``compat='no_conflicts'``, so some - merges will now succeed in cases that previously raised - ``xarray.MergeError``. Set ``compat='broadcast_equals'`` to restore the - previous default. See :ref:`combining.no_conflicts` for more details. - - - Reading :py:attr:`~DataArray.values` no longer always caches values in a NumPy - array :issue:`1128`. Caching of ``.values`` on variables read from netCDF - files on disk is still the default when :py:func:`open_dataset` is called with - ``cache=True``. - By `Guido Imperiale `_ and - `Stephan Hoyer `_. - - Pickling a ``Dataset`` or ``DataArray`` linked to a file on disk no longer - caches its values into memory before pickling (:issue:`1128`). Instead, pickle - stores file paths and restores objects by reopening file references. This - enables preliminary, experimental use of xarray for opening files with - `dask.distributed `_. - By `Stephan Hoyer `_. - - Coordinates used to index a dimension are now loaded eagerly into - :py:class:`pandas.Index` objects, instead of loading the values lazily. - By `Guido Imperiale `_. - - Automatic levels for 2d plots are now guaranteed to land on ``vmin`` and - ``vmax`` when these kwargs are explicitly provided (:issue:`1191`). The - automated level selection logic also slightly changed. - By `Fabien Maussion `_. - - - ``DataArray.rename()`` behavior changed to strictly change the ``DataArray.name`` - if called with string argument, or strictly change coordinate names if called with - dict-like argument. - By `Markus Gonser `_. - - - By default ``to_netcdf()`` add a ``_FillValue = NaN`` attributes to float types. - By `Frederic Laliberte `_. - - - ``repr`` on ``DataArray`` objects uses an shortened display for NumPy array - data that is less likely to overflow onto multiple pages (:issue:`1207`). - By `Stephan Hoyer `_. - - - xarray no longer supports python 3.3, versions of dask prior to v0.9.0, - or versions of bottleneck prior to v1.0. - - Deprecations - ~~~~~~~~~~~~ - - - Renamed the ``Coordinate`` class from xarray's low level API to - :py:class:`~xarray.IndexVariable`. ``Variable.to_variable`` and - ``Variable.to_coord`` have been renamed to - :py:meth:`~xarray.Variable.to_base_variable` and - :py:meth:`~xarray.Variable.to_index_variable`. - - Deprecated supplying ``coords`` as a dictionary to the ``DataArray`` - constructor without also supplying an explicit ``dims`` argument. The old - behavior encouraged relying on the iteration order of dictionaries, which is - a bad practice (:issue:`727`). - - Removed a number of methods deprecated since v0.7.0 or earlier: - ``load_data``, ``vars``, ``drop_vars``, ``dump``, ``dumps`` and the - ``variables`` keyword argument to ``Dataset``. - - Removed the dummy module that enabled ``import xray``. - - Enhancements - ~~~~~~~~~~~~ - - - Added new method :py:meth:`~DataArray.combine_first` to ``DataArray`` and - ``Dataset``, based on the pandas method of the same name (see :ref:`combine`). - By `Chun-Wei Yuan `_. - - - Added the ability to change default automatic alignment (arithmetic_join="inner") - for binary operations via :py:func:`~xarray.set_options()` - (see :ref:`math automatic alignment`). - By `Chun-Wei Yuan `_. - - - Add checking of ``attr`` names and values when saving to netCDF, raising useful - error messages if they are invalid. (:issue:`911`). - By `Robin Wilson `_. - - Added ability to save ``DataArray`` objects directly to netCDF files using - :py:meth:`~xarray.DataArray.to_netcdf`, and to load directly from netCDF files - using :py:func:`~xarray.open_dataarray` (:issue:`915`). These remove the need - to convert a ``DataArray`` to a ``Dataset`` before saving as a netCDF file, - and deals with names to ensure a perfect 'roundtrip' capability. - By `Robin Wilson `_. - - Multi-index levels are now accessible as "virtual" coordinate variables, - e.g., ``ds['time']`` can pull out the ``'time'`` level of a multi-index - (see :ref:`coordinates`). ``sel`` also accepts providing multi-index levels - as keyword arguments, e.g., ``ds.sel(time='2000-01')`` - (see :ref:`multi-level indexing`). - By `Benoit Bovy `_. - - Added ``set_index``, ``reset_index`` and ``reorder_levels`` methods to - easily create and manipulate (multi-)indexes (see :ref:`reshape.set_index`). - By `Benoit Bovy `_. - - Added the ``compat`` option ``'no_conflicts'`` to ``merge``, allowing the - combination of xarray objects with disjoint (:issue:`742`) or - overlapping (:issue:`835`) coordinates as long as all present data agrees. - By `Johnnie Gray `_. See - :ref:`combining.no_conflicts` for more details. - - It is now possible to set ``concat_dim=None`` explicitly in - :py:func:`~xarray.open_mfdataset` to disable inferring a dimension along - which to concatenate. - By `Stephan Hoyer `_. - - Added methods :py:meth:`DataArray.compute`, :py:meth:`Dataset.compute`, and - :py:meth:`Variable.compute` as a non-mutating alternative to - :py:meth:`~DataArray.load`. - By `Guido Imperiale `_. - - Adds DataArray and Dataset methods :py:meth:`~xarray.DataArray.cumsum` and - :py:meth:`~xarray.DataArray.cumprod`. By `Phillip J. Wolfram - `_. - - - New properties :py:attr:`Dataset.sizes` and :py:attr:`DataArray.sizes` for - providing consistent access to dimension length on both ``Dataset`` and - ``DataArray`` (:issue:`921`). - By `Stephan Hoyer `_. - - New keyword argument ``drop=True`` for :py:meth:`~DataArray.sel`, - :py:meth:`~DataArray.isel` and :py:meth:`~DataArray.squeeze` for dropping - scalar coordinates that arise from indexing. - ``DataArray`` (:issue:`242`). - By `Stephan Hoyer `_. - - - New top-level functions :py:func:`~xarray.full_like`, - :py:func:`~xarray.zeros_like`, and :py:func:`~xarray.ones_like` - By `Guido Imperiale `_. - - Overriding a preexisting attribute with - :py:func:`~xarray.register_dataset_accessor` or - :py:func:`~xarray.register_dataarray_accessor` now issues a warning instead of - raising an error (:issue:`1082`). - By `Stephan Hoyer `_. - - Options for axes sharing between subplots are exposed to - :py:class:`~xarray.plot.FacetGrid` and :py:func:`~xarray.plot.plot`, so axes - sharing can be disabled for polar plots. - By `Bas Hoonhout `_. - - New utility functions :py:func:`~xarray.testing.assert_equal`, - :py:func:`~xarray.testing.assert_identical`, and - :py:func:`~xarray.testing.assert_allclose` for asserting relationships - between xarray objects, designed for use in a pytest test suite. - - ``figsize``, ``size`` and ``aspect`` plot arguments are now supported for all - plots (:issue:`897`). See :ref:`plotting.figsize` for more details. - By `Stephan Hoyer `_ and - `Fabien Maussion `_. - - New :py:meth:`~Dataset.info` method to summarize ``Dataset`` variables - and attributes. The method prints to a buffer (e.g. ``stdout``) with output - similar to what the command line utility ``ncdump -h`` produces (:issue:`1150`). - By `Joe Hamman `_. - - Added the ability write unlimited netCDF dimensions with the ``scipy`` and - ``netcdf4`` backends via the new ``xray.Dataset.encoding`` attribute - or via the ``unlimited_dims`` argument to ``xray.Dataset.to_netcdf``. - By `Joe Hamman `_. - - New :py:meth:`~DataArray.quantile` method to calculate quantiles from - DataArray objects (:issue:`1187`). - By `Joe Hamman `_. - - - Bug fixes - ~~~~~~~~~ - - ``groupby_bins`` now restores empty bins by default (:issue:`1019`). - By `Ryan Abernathey `_. - - - Fix issues for dates outside the valid range of pandas timestamps - (:issue:`975`). By `Mathias Hauser `_. - - - Unstacking produced flipped array after stacking decreasing coordinate values - (:issue:`980`). - By `Stephan Hoyer `_. - - - Setting ``dtype`` via the ``encoding`` parameter of ``to_netcdf`` failed if - the encoded dtype was the same as the dtype of the original array - (:issue:`873`). - By `Stephan Hoyer `_. - - - Fix issues with variables where both attributes ``_FillValue`` and - ``missing_value`` are set to ``NaN`` (:issue:`997`). - By `Marco Zühlke `_. - - - ``.where()`` and ``.fillna()`` now preserve attributes (:issue:`1009`). - By `Fabien Maussion `_. - - - Applying :py:func:`broadcast()` to an xarray object based on the dask backend - won't accidentally convert the array from dask to numpy anymore (:issue:`978`). - By `Guido Imperiale `_. - - - ``Dataset.concat()`` now preserves variables order (:issue:`1027`). - By `Fabien Maussion `_. - - - Fixed an issue with pcolormesh (:issue:`781`). A new - ``infer_intervals`` keyword gives control on whether the cell intervals - should be computed or not. - By `Fabien Maussion `_. - - - Grouping over an dimension with non-unique values with ``groupby`` gives - correct groups. - By `Stephan Hoyer `_. - - - Fixed accessing coordinate variables with non-string names from ``.coords``. - By `Stephan Hoyer `_. - - - :py:meth:`~xarray.DataArray.rename` now simultaneously renames the array and - any coordinate with the same name, when supplied via a :py:class:`dict` - (:issue:`1116`). - By `Yves Delley `_. - - - Fixed sub-optimal performance in certain operations with object arrays (:issue:`1121`). - By `Yves Delley `_. - - - Fix ``.groupby(group)`` when ``group`` has datetime dtype (:issue:`1132`). - By `Jonas Sølvsteen `_. - - - Fixed a bug with facetgrid (the ``norm`` keyword was ignored, :issue:`1159`). - By `Fabien Maussion `_. - - - Resolved a concurrency bug that could cause Python to crash when - simultaneously reading and writing netCDF4 files with dask (:issue:`1172`). - By `Stephan Hoyer `_. - - - Fix to make ``.copy()`` actually copy dask arrays, which will be relevant for - future releases of dask in which dask arrays will be mutable (:issue:`1180`). - By `Stephan Hoyer `_. - - - Fix opening NetCDF files with multi-dimensional time variables - (:issue:`1229`). - By `Stephan Hoyer `_. - - Performance improvements - ~~~~~~~~~~~~~~~~~~~~~~~~ - - - ``xarray.Dataset.isel_points`` and ``xarray.Dataset.sel_points`` now - use vectorised indexing in numpy and dask (:issue:`1161`), which can - result in several orders of magnitude speedup. - By `Jonathan Chambers `_. - - .. _whats-new.0.8.2: - - v0.8.2 (18 August 2016) - ----------------------- - - This release includes a number of bug fixes and minor enhancements. - - Breaking changes - ~~~~~~~~~~~~~~~~ - - - :py:func:`~xarray.broadcast` and :py:func:`~xarray.concat` now auto-align - inputs, using ``join=outer``. Previously, these functions raised - ``ValueError`` for non-aligned inputs. - By `Guido Imperiale `_. - - Enhancements - ~~~~~~~~~~~~ - - - New documentation on :ref:`panel transition`. By - `Maximilian Roos `_. - - New ``Dataset`` and ``DataArray`` methods :py:meth:`~xarray.Dataset.to_dict` - and :py:meth:`~xarray.Dataset.from_dict` to allow easy conversion between - dictionaries and xarray objects (:issue:`432`). See - :ref:`dictionary IO` for more details. - By `Julia Signell `_. - - Added ``exclude`` and ``indexes`` optional parameters to :py:func:`~xarray.align`, - and ``exclude`` optional parameter to :py:func:`~xarray.broadcast`. - By `Guido Imperiale `_. - - Better error message when assigning variables without dimensions - (:issue:`971`). By `Stephan Hoyer `_. - - Better error message when reindex/align fails due to duplicate index values - (:issue:`956`). By `Stephan Hoyer `_. - - Bug fixes - ~~~~~~~~~ - - - Ensure xarray works with h5netcdf v0.3.0 for arrays with ``dtype=str`` - (:issue:`953`). By `Stephan Hoyer `_. - - ``Dataset.__dir__()`` (i.e. the method python calls to get autocomplete - options) failed if one of the dataset's keys was not a string (:issue:`852`). - By `Maximilian Roos `_. - - ``Dataset`` constructor can now take arbitrary objects as values - (:issue:`647`). By `Maximilian Roos `_. - - Clarified ``copy`` argument for :py:meth:`~xarray.DataArray.reindex` and - :py:func:`~xarray.align`, which now consistently always return new xarray - objects (:issue:`927`). - - Fix ``open_mfdataset`` with ``engine='pynio'`` (:issue:`936`). - By `Stephan Hoyer `_. - - ``groupby_bins`` sorted bin labels as strings (:issue:`952`). - By `Stephan Hoyer `_. - - Fix bug introduced by v0.8.0 that broke assignment to datasets when both the - left and right side have the same non-unique index values (:issue:`956`). - - .. _whats-new.0.8.1: - - v0.8.1 (5 August 2016) - ---------------------- - - Bug fixes - ~~~~~~~~~ - - - Fix bug in v0.8.0 that broke assignment to Datasets with non-unique - indexes (:issue:`943`). By `Stephan Hoyer `_. - - .. _whats-new.0.8.0: - - v0.8.0 (2 August 2016) - ---------------------- - - This release includes four months of new features and bug fixes, including - several breaking changes. - - .. _v0.8.0.breaking: - - Breaking changes - ~~~~~~~~~~~~~~~~ - - - Dropped support for Python 2.6 (:issue:`855`). - - Indexing on multi-index now drop levels, which is consistent with pandas. - It also changes the name of the dimension / coordinate when the multi-index is - reduced to a single index (:issue:`802`). - - Contour plots no longer add a colorbar per default (:issue:`866`). Filled - contour plots are unchanged. - - ``DataArray.values`` and ``.data`` now always returns an NumPy array-like - object, even for 0-dimensional arrays with object dtype (:issue:`867`). - Previously, ``.values`` returned native Python objects in such cases. To - convert the values of scalar arrays to Python objects, use the ``.item()`` - method. - - Enhancements - ~~~~~~~~~~~~ - - - Groupby operations now support grouping over multidimensional variables. A new - method called :py:meth:`~xarray.Dataset.groupby_bins` has also been added to - allow users to specify bins for grouping. The new features are described in - :ref:`groupby.multidim` and :ref:`/examples/multidimensional-coords.ipynb`. - By `Ryan Abernathey `_. - - - DataArray and Dataset method :py:meth:`where` now supports a ``drop=True`` - option that clips coordinate elements that are fully masked. By - `Phillip J. Wolfram `_. - - - New top level :py:func:`merge` function allows for combining variables from - any number of ``Dataset`` and/or ``DataArray`` variables. See :ref:`merge` - for more details. By `Stephan Hoyer `_. - - - :py:meth:`DataArray.resample` and :py:meth:`Dataset.resample` now support the - ``keep_attrs=False`` option that determines whether variable and dataset - attributes are retained in the resampled object. By - `Jeremy McGibbon `_. - - - Better multi-index support in :py:meth:`DataArray.sel`, - :py:meth:`DataArray.loc`, :py:meth:`Dataset.sel` and - :py:meth:`Dataset.loc`, which now behave more closely to pandas and - which also accept dictionaries for indexing based on given level names - and labels (see :ref:`multi-level indexing`). - By `Benoit Bovy `_. - - - New (experimental) decorators :py:func:`~xarray.register_dataset_accessor` and - :py:func:`~xarray.register_dataarray_accessor` for registering custom xarray - extensions without subclassing. They are described in the new documentation - page on :ref:`internals`. By `Stephan Hoyer `_. - - - Round trip boolean datatypes. Previously, writing boolean datatypes to netCDF - formats would raise an error since netCDF does not have a `bool` datatype. - This feature reads/writes a `dtype` attribute to boolean variables in netCDF - files. By `Joe Hamman `_. - - - 2D plotting methods now have two new keywords (`cbar_ax` and `cbar_kwargs`), - allowing more control on the colorbar (:issue:`872`). - By `Fabien Maussion `_. - - - New Dataset method :py:meth:`Dataset.filter_by_attrs`, akin to - ``netCDF4.Dataset.get_variables_by_attributes``, to easily filter - data variables using its attributes. - `Filipe Fernandes `_. - - Bug fixes - ~~~~~~~~~ - - - Attributes were being retained by default for some resampling - operations when they should not. With the ``keep_attrs=False`` option, they - will no longer be retained by default. This may be backwards-incompatible - with some scripts, but the attributes may be kept by adding the - ``keep_attrs=True`` option. By - `Jeremy McGibbon `_. - - - Concatenating xarray objects along an axis with a MultiIndex or PeriodIndex - preserves the nature of the index (:issue:`875`). By - `Stephan Hoyer `_. - - - Fixed bug in arithmetic operations on DataArray objects whose dimensions - are numpy structured arrays or recarrays :issue:`861`, :issue:`837`. By - `Maciek Swat `_. - - - ``decode_cf_timedelta`` now accepts arrays with ``ndim`` >1 (:issue:`842`). - This fixes issue :issue:`665`. - `Filipe Fernandes `_. - - - Fix a bug where `xarray.ufuncs` that take two arguments would incorrectly - use to numpy functions instead of dask.array functions (:issue:`876`). By - `Stephan Hoyer `_. - - - Support for pickling functions from ``xarray.ufuncs`` (:issue:`901`). By - `Stephan Hoyer `_. - - - ``Variable.copy(deep=True)`` no longer converts MultiIndex into a base Index - (:issue:`769`). By `Benoit Bovy `_. - - - Fixes for groupby on dimensions with a multi-index (:issue:`867`). By - `Stephan Hoyer `_. - - - Fix printing datasets with unicode attributes on Python 2 (:issue:`892`). By - `Stephan Hoyer `_. - - - Fixed incorrect test for dask version (:issue:`891`). By - `Stephan Hoyer `_. - - - Fixed `dim` argument for `isel_points`/`sel_points` when a `pandas.Index` is - passed. By `Stephan Hoyer `_. - - - :py:func:`~xarray.plot.contour` now plots the correct number of contours - (:issue:`866`). By `Fabien Maussion `_. - - .. _whats-new.0.7.2: - - v0.7.2 (13 March 2016) - ---------------------- - - This release includes two new, entirely backwards compatible features and - several bug fixes. - - Enhancements - ~~~~~~~~~~~~ - - - New DataArray method :py:meth:`DataArray.dot` for calculating the dot - product of two DataArrays along shared dimensions. By - `Dean Pospisil `_. - - - Rolling window operations on DataArray objects are now supported via a new - :py:meth:`DataArray.rolling` method. For example: - - .. ipython:: + + xray's MultiIndex support is still experimental, and we have a long to- + do list of desired additions (:issue:`719`), including better display of + multi-index levels when printing a ``Dataset``, and support for saving + datasets with a MultiIndex to a netCDF file. User contributions in this + area would be greatly appreciated. + +- Support for reading GRIB, HDF4 and other file formats via PyNIO_. See + :ref:`io.pynio` for more details. +- Better error message when a variable is supplied with the same name as + one of its dimensions. +- Plotting: more control on colormap parameters (:issue:`642`). ``vmin`` and + ``vmax`` will not be silently ignored anymore. Setting ``center=False`` + prevents automatic selection of a divergent colormap. +- New ``xray.Dataset.shift`` and ``xray.Dataset.roll`` methods + for shifting/rotating datasets or arrays along a dimension: + + .. ipython:: python + :okwarning: + + array = xray.DataArray([5, 6, 7, 8], dims="x") + array.shift(x=2) + array.roll(x=2) + + Notice that ``shift`` moves data independently of coordinates, but ``roll`` + moves both data and coordinates. +- Assigning a ``pandas`` object directly as a ``Dataset`` variable is now permitted. Its + index names correspond to the ``dims`` of the ``Dataset``, and its data is aligned. +- Passing a :py:class:`pandas.DataFrame` or ``pandas.Panel`` to a Dataset constructor + is now permitted. +- New function ``xray.broadcast`` for explicitly broadcasting + ``DataArray`` and ``Dataset`` objects against each other. For example: + + .. ipython:: python + + a = xray.DataArray([1, 2, 3], dims="x") + b = xray.DataArray([5, 6], dims="y") + a + b + a2, b2 = xray.broadcast(a, b) + a2 + b2 + +.. _PyNIO: https://www.pyngl.ucar.edu/Nio.shtml + +Bug fixes +~~~~~~~~~ + +- Fixes for several issues found on ``DataArray`` objects with the same name + as one of their coordinates (see :ref:`v0.7.0.breaking` for more details). +- ``DataArray.to_masked_array`` always returns masked array with mask being an + array (not a scalar value) (:issue:`684`) +- Allows for (imperfect) repr of Coords when underlying index is PeriodIndex (:issue:`645`). +- Fixes for several issues found on ``DataArray`` objects with the same name + as one of their coordinates (see :ref:`v0.7.0.breaking` for more details). +- Attempting to assign a ``Dataset`` or ``DataArray`` variable/attribute using + attribute-style syntax (e.g., ``ds.foo = 42``) now raises an error rather + than silently failing (:issue:`656`, :issue:`714`). +- You can now pass pandas objects with non-numpy dtypes (e.g., ``categorical`` + or ``datetime64`` with a timezone) into xray without an error + (:issue:`716`). + +Acknowledgments +~~~~~~~~~~~~~~~ + +The following individuals contributed to this release: + +- Antony Lee +- Fabien Maussion +- Joe Hamman +- Maximilian Roos +- Stephan Hoyer +- Takeshi Kanmae +- femtotrader + +v0.6.1 (21 October 2015) +------------------------ + +This release contains a number of bug and compatibility fixes, as well +as enhancements to plotting, indexing and writing files to disk. + +Note that the minimum required version of dask for use with xray is now +version 0.6. + +API Changes +~~~~~~~~~~~ + +- The handling of colormaps and discrete color lists for 2D plots in + ``xray.DataArray.plot`` was changed to provide more compatibility + with matplotlib's ``contour`` and ``contourf`` functions (:issue:`538`). + Now discrete lists of colors should be specified using ``colors`` keyword, + rather than ``cmap``. + +Enhancements +~~~~~~~~~~~~ + +- Faceted plotting through ``xray.plot.FacetGrid`` and the + ``xray.plot.plot`` method. See :ref:`plotting.faceting` for more details + and examples. +- ``xray.Dataset.sel`` and ``xray.Dataset.reindex`` now support + the ``tolerance`` argument for controlling nearest-neighbor selection + (:issue:`629`): + + .. ipython:: + :verbatim: + + In [5]: array = xray.DataArray([1, 2, 3], dims="x") + + In [6]: array.reindex(x=[0.9, 1.5], method="nearest", tolerance=0.2) + Out[6]: + + array([ 2., nan]) + Coordinates: + * x (x) float64 0.9 1.5 + + This feature requires pandas v0.17 or newer. +- New ``encoding`` argument in ``xray.Dataset.to_netcdf`` for writing + netCDF files with compression, as described in the new documentation + section on :ref:`io.netcdf.writing_encoded`. +- Add ``xray.Dataset.real`` and ``xray.Dataset.imag`` + attributes to Dataset and DataArray (:issue:`553`). +- More informative error message with ``xray.Dataset.from_dataframe`` + if the frame has duplicate columns. +- xray now uses deterministic names for dask arrays it creates or opens from + disk. This allows xray users to take advantage of dask's nascent support for + caching intermediate computation results. See :issue:`555` for an example. + +Bug fixes +~~~~~~~~~ + +- Forwards compatibility with the latest pandas release (v0.17.0). We were + using some internal pandas routines for datetime conversion, which + unfortunately have now changed upstream (:issue:`569`). +- Aggregation functions now correctly skip ``NaN`` for data for ``complex128`` + dtype (:issue:`554`). +- Fixed indexing 0d arrays with unicode dtype (:issue:`568`). +- ``xray.DataArray.name`` and Dataset keys must be a string or None to + be written to netCDF (:issue:`533`). +- ``xray.DataArray.where`` now uses dask instead of numpy if either the + array or ``other`` is a dask array. Previously, if ``other`` was a numpy array + the method was evaluated eagerly. +- Global attributes are now handled more consistently when loading remote + datasets using ``engine='pydap'`` (:issue:`574`). +- It is now possible to assign to the ``.data`` attribute of DataArray objects. +- ``coordinates`` attribute is now kept in the encoding dictionary after + decoding (:issue:`610`). +- Compatibility with numpy 1.10 (:issue:`617`). + +Acknowledgments +~~~~~~~~~~~~~~~ + +The following individuals contributed to this release: + +- Ryan Abernathey +- Pete Cable +- Clark Fitzgerald +- Joe Hamman +- Stephan Hoyer +- Scott Sinclair + +v0.6.0 (21 August 2015) +----------------------- + +This release includes numerous bug fixes and enhancements. Highlights +include the introduction of a plotting module and the new Dataset and DataArray +methods ``xray.Dataset.isel_points``, ``xray.Dataset.sel_points``, +``xray.Dataset.where`` and ``xray.Dataset.diff``. There are no +breaking changes from v0.5.2. + +Enhancements +~~~~~~~~~~~~ + +- Plotting methods have been implemented on DataArray objects + ``xray.DataArray.plot`` through integration with matplotlib + (:issue:`185`). For an introduction, see :ref:`plotting`. +- Variables in netCDF files with multiple missing values are now decoded as NaN + after issuing a warning if open_dataset is called with mask_and_scale=True. +- We clarified our rules for when the result from an xray operation is a copy + vs. a view (see :ref:`copies_vs_views` for more details). +- Dataset variables are now written to netCDF files in order of appearance + when using the netcdf4 backend (:issue:`479`). + +- Added ``xray.Dataset.isel_points`` and ``xray.Dataset.sel_points`` + to support pointwise indexing of Datasets and DataArrays (:issue:`475`). + + .. ipython:: + :verbatim: + + In [1]: da = xray.DataArray( + ...: np.arange(56).reshape((7, 8)), + ...: coords={"x": list("abcdefg"), "y": 10 * np.arange(8)}, + ...: dims=["x", "y"], + ...: ) + + In [2]: da + Out[2]: + + array([[ 0, 1, 2, 3, 4, 5, 6, 7], + [ 8, 9, 10, 11, 12, 13, 14, 15], + [16, 17, 18, 19, 20, 21, 22, 23], + [24, 25, 26, 27, 28, 29, 30, 31], + [32, 33, 34, 35, 36, 37, 38, 39], + [40, 41, 42, 43, 44, 45, 46, 47], + [48, 49, 50, 51, 52, 53, 54, 55]]) + Coordinates: + * y (y) int64 0 10 20 30 40 50 60 70 + * x (x) |S1 'a' 'b' 'c' 'd' 'e' 'f' 'g' + + # we can index by position along each dimension + In [3]: da.isel_points(x=[0, 1, 6], y=[0, 1, 0], dim="points") + Out[3]: + + array([ 0, 9, 48]) + Coordinates: + y (points) int64 0 10 0 + x (points) |S1 'a' 'b' 'g' + * points (points) int64 0 1 2 + + # or equivalently by label + In [9]: da.sel_points(x=["a", "b", "g"], y=[0, 10, 0], dim="points") + Out[9]: + + array([ 0, 9, 48]) + Coordinates: + y (points) int64 0 10 0 + x (points) |S1 'a' 'b' 'g' + * points (points) int64 0 1 2 + +- New ``xray.Dataset.where`` method for masking xray objects according + to some criteria. This works particularly well with multi-dimensional data: + + .. ipython:: python + + ds = xray.Dataset(coords={"x": range(100), "y": range(100)}) + ds["distance"] = np.sqrt(ds.x ** 2 + ds.y ** 2) + + @savefig where_example.png width=4in height=4in + ds.distance.where(ds.distance < 100).plot() + +- Added new methods ``xray.DataArray.diff`` and ``xray.Dataset.diff`` + for finite difference calculations along a given axis. + +- New ``xray.DataArray.to_masked_array`` convenience method for + returning a numpy.ma.MaskedArray. + + .. ipython:: python + + da = xray.DataArray(np.random.random_sample(size=(5, 4))) + da.where(da < 0.5) + da.where(da < 0.5).to_masked_array(copy=True) + +- Added new flag "drop_variables" to ``xray.open_dataset`` for + excluding variables from being parsed. This may be useful to drop + variables with problems or inconsistent values. + +Bug fixes +~~~~~~~~~ + +- Fixed aggregation functions (e.g., sum and mean) on big-endian arrays when + bottleneck is installed (:issue:`489`). +- Dataset aggregation functions dropped variables with unsigned integer dtype + (:issue:`505`). +- ``.any()`` and ``.all()`` were not lazy when used on xray objects containing + dask arrays. +- Fixed an error when attempting to saving datetime64 variables to netCDF + files when the first element is ``NaT`` (:issue:`528`). +- Fix pickle on DataArray objects (:issue:`515`). +- Fixed unnecessary coercion of float64 to float32 when using netcdf3 and + netcdf4_classic formats (:issue:`526`). + +v0.5.2 (16 July 2015) +--------------------- + +This release contains bug fixes, several additional options for opening and +saving netCDF files, and a backwards incompatible rewrite of the advanced +options for ``xray.concat``. + +Backwards incompatible changes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- The optional arguments ``concat_over`` and ``mode`` in ``xray.concat`` have + been removed and replaced by ``data_vars`` and ``coords``. The new arguments are both + more easily understood and more robustly implemented, and allowed us to fix a bug + where ``concat`` accidentally loaded data into memory. If you set values for + these optional arguments manually, you will need to update your code. The default + behavior should be unchanged. + +Enhancements +~~~~~~~~~~~~ + +- ``xray.open_mfdataset`` now supports a ``preprocess`` argument for + preprocessing datasets prior to concatenaton. This is useful if datasets + cannot be otherwise merged automatically, e.g., if the original datasets + have conflicting index coordinates (:issue:`443`). +- ``xray.open_dataset`` and ``xray.open_mfdataset`` now use a + global thread lock by default for reading from netCDF files with dask. This + avoids possible segmentation faults for reading from netCDF4 files when HDF5 + is not configured properly for concurrent access (:issue:`444`). +- Added support for serializing arrays of complex numbers with `engine='h5netcdf'`. +- The new ``xray.save_mfdataset`` function allows for saving multiple + datasets to disk simultaneously. This is useful when processing large datasets + with dask.array. For example, to save a dataset too big to fit into memory + to one file per year, we could write: + + .. ipython:: + :verbatim: + + In [1]: years, datasets = zip(*ds.groupby("time.year")) + + In [2]: paths = ["%s.nc" % y for y in years] + + In [3]: xray.save_mfdataset(datasets, paths) + +Bug fixes +~~~~~~~~~ + +- Fixed ``min``, ``max``, ``argmin`` and ``argmax`` for arrays with string or + unicode types (:issue:`453`). +- ``xray.open_dataset`` and ``xray.open_mfdataset`` support + supplying chunks as a single integer. +- Fixed a bug in serializing scalar datetime variable to netCDF. +- Fixed a bug that could occur in serialization of 0-dimensional integer arrays. +- Fixed a bug where concatenating DataArrays was not always lazy (:issue:`464`). +- When reading datasets with h5netcdf, bytes attributes are decoded to strings. + This allows conventions decoding to work properly on Python 3 (:issue:`451`). + +v0.5.1 (15 June 2015) +--------------------- + +This minor release fixes a few bugs and an inconsistency with pandas. It also +adds the ``pipe`` method, copied from pandas. + +Enhancements +~~~~~~~~~~~~ + +- Added ``xray.Dataset.pipe``, replicating the `new pandas method`_ in version + 0.16.2. See :ref:`transforming datasets` for more details. +- ``xray.Dataset.assign`` and ``xray.Dataset.assign_coords`` + now assign new variables in sorted (alphabetical) order, mirroring the + behavior in pandas. Previously, the order was arbitrary. + +.. _new pandas method: http://pandas.pydata.org/pandas-docs/version/0.16.2/whatsnew.html#pipe + +Bug fixes +~~~~~~~~~ + +- ``xray.concat`` fails in an edge case involving identical coordinate variables (:issue:`425`) +- We now decode variables loaded from netCDF3 files with the scipy engine using native + endianness (:issue:`416`). This resolves an issue when aggregating these arrays with + bottleneck installed. + +v0.5 (1 June 2015) +------------------ + +Highlights +~~~~~~~~~~ + +The headline feature in this release is experimental support for out-of-core +computing (data that doesn't fit into memory) with :doc:`user-guide/dask`. This includes a new +top-level function ``xray.open_mfdataset`` that makes it easy to open +a collection of netCDF (using dask) as a single ``xray.Dataset`` object. For +more on dask, read the `blog post introducing xray + dask`_ and the new +documentation section :doc:`user-guide/dask`. + +.. _blog post introducing xray + dask: https://www.anaconda.com/blog/developer-blog/xray-dask-out-core-labeled-arrays-python/ + +Dask makes it possible to harness parallelism and manipulate gigantic datasets +with xray. It is currently an optional dependency, but it may become required +in the future. + +Backwards incompatible changes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- The logic used for choosing which variables are concatenated with + ``xray.concat`` has changed. Previously, by default any variables + which were equal across a dimension were not concatenated. This lead to some + surprising behavior, where the behavior of groupby and concat operations + could depend on runtime values (:issue:`268`). For example: + + .. ipython:: + :verbatim: + + In [1]: ds = xray.Dataset({"x": 0}) + + In [2]: xray.concat([ds, ds], dim="y") + Out[2]: + + Dimensions: () + Coordinates: + *empty* + Data variables: + x int64 0 + + Now, the default always concatenates data variables: + + .. ipython:: python + :suppress: + + ds = xray.Dataset({"x": 0}) + + .. ipython:: python + + xray.concat([ds, ds], dim="y") + + To obtain the old behavior, supply the argument ``concat_over=[]``. + +Enhancements +~~~~~~~~~~~~ + +- New ``xray.Dataset.to_array`` and enhanced + ``xray.DataArray.to_dataset`` methods make it easy to switch back + and forth between arrays and datasets: + + .. ipython:: python + + ds = xray.Dataset( + {"a": 1, "b": ("x", [1, 2, 3])}, + coords={"c": 42}, + attrs={"Conventions": "None"}, + ) + ds.to_array() + ds.to_array().to_dataset(dim="variable") + +- New ``xray.Dataset.fillna`` method to fill missing values, modeled + off the pandas method of the same name: + + .. ipython:: python + + array = xray.DataArray([np.nan, 1, np.nan, 3], dims="x") + array.fillna(0) + + ``fillna`` works on both ``Dataset`` and ``DataArray`` objects, and uses + index based alignment and broadcasting like standard binary operations. It + also can be applied by group, as illustrated in + :ref:`/examples/weather-data.ipynb#Fill-missing-values-with-climatology`. +- New ``xray.Dataset.assign`` and ``xray.Dataset.assign_coords`` + methods patterned off the new :py:meth:`DataFrame.assign ` + method in pandas: + + .. ipython:: python + + ds = xray.Dataset({"y": ("x", [1, 2, 3])}) + ds.assign(z=lambda ds: ds.y ** 2) + ds.assign_coords(z=("x", ["a", "b", "c"])) + + These methods return a new Dataset (or DataArray) with updated data or + coordinate variables. +- ``xray.Dataset.sel`` now supports the ``method`` parameter, which works + like the paramter of the same name on ``xray.Dataset.reindex``. It + provides a simple interface for doing nearest-neighbor interpolation: + + .. use verbatim because I can't seem to install pandas 0.16.1 on RTD :( + + .. ipython:: :verbatim: - - In [1]: import xarray as xr - ...: import numpy as np - - In [2]: arr = xr.DataArray(np.arange(0, 7.5, 0.5).reshape(3, 5), dims=("x", "y")) - - In [3]: arr - Out[3]: - - array([[ 0. , 0.5, 1. , 1.5, 2. ], - [ 2.5, 3. , 3.5, 4. , 4.5], - [ 5. , 5.5, 6. , 6.5, 7. ]]) - Coordinates: - * x (x) int64 0 1 2 - * y (y) int64 0 1 2 3 4 - - In [4]: arr.rolling(y=3, min_periods=2).mean() - Out[4]: - - array([[ nan, 0.25, 0.5 , 1. , 1.5 ], - [ nan, 2.75, 3. , 3.5 , 4. ], - [ nan, 5.25, 5.5 , 6. , 6.5 ]]) + + In [12]: ds.sel(x=1.1, method="nearest") + Out[12]: + + Dimensions: () Coordinates: - * x (x) int64 0 1 2 - * y (y) int64 0 1 2 3 4 - - See :ref:`comput.rolling` for more details. By - `Joe Hamman `_. - - Bug fixes - ~~~~~~~~~ - - - Fixed an issue where plots using pcolormesh and Cartopy axes were being distorted - by the inference of the axis interval breaks. This change chooses not to modify - the coordinate variables when the axes have the attribute ``projection``, allowing - Cartopy to handle the extent of pcolormesh plots (:issue:`781`). By - `Joe Hamman `_. - - - 2D plots now better handle additional coordinates which are not ``DataArray`` - dimensions (:issue:`788`). By `Fabien Maussion `_. - - - .. _whats-new.0.7.1: - - v0.7.1 (16 February 2016) - ------------------------- - - This is a bug fix release that includes two small, backwards compatible enhancements. - We recommend that all users upgrade. - - Enhancements - ~~~~~~~~~~~~ - - - Numerical operations now return empty objects on no overlapping labels rather - than raising ``ValueError`` (:issue:`739`). - - :py:class:`~pandas.Series` is now supported as valid input to the ``Dataset`` - constructor (:issue:`740`). - - Bug fixes - ~~~~~~~~~ - - - Restore checks for shape consistency between data and coordinates in the - DataArray constructor (:issue:`758`). - - Single dimension variables no longer transpose as part of a broader - ``.transpose``. This behavior was causing ``pandas.PeriodIndex`` dimensions - to lose their type (:issue:`749`) - - :py:class:`~xarray.Dataset` labels remain as their native type on ``.to_dataset``. - Previously they were coerced to strings (:issue:`745`) - - Fixed a bug where replacing a ``DataArray`` index coordinate would improperly - align the coordinate (:issue:`725`). - - ``DataArray.reindex_like`` now maintains the dtype of complex numbers when - reindexing leads to NaN values (:issue:`738`). - - ``Dataset.rename`` and ``DataArray.rename`` support the old and new names - being the same (:issue:`724`). - - Fix :py:meth:`~xarray.Dataset.from_dataframe` for DataFrames with Categorical - column and a MultiIndex index (:issue:`737`). - - Fixes to ensure xarray works properly after the upcoming pandas v0.18 and - NumPy v1.11 releases. - - Acknowledgments - ~~~~~~~~~~~~~~~ - - The following individuals contributed to this release: - - - Edward Richards - - Maximilian Roos - - Rafael Guedes - - Spencer Hill - - Stephan Hoyer - - .. _whats-new.0.7.0: - - v0.7.0 (21 January 2016) - ------------------------ - - This major release includes redesign of :py:class:`~xarray.DataArray` - internals, as well as new methods for reshaping, rolling and shifting - data. It includes preliminary support for :py:class:`pandas.MultiIndex`, - as well as a number of other features and bug fixes, several of which - offer improved compatibility with pandas. - - New name - ~~~~~~~~ - - The project formerly known as "xray" is now "xarray", pronounced "x-array"! - This avoids a namespace conflict with the entire field of x-ray science. Renaming - our project seemed like the right thing to do, especially because some - scientists who work with actual x-rays are interested in using this project in - their work. Thanks for your understanding and patience in this transition. You - can now find our documentation and code repository at new URLs: - - - http://xarray.pydata.org - - http://github.com/pydata/xarray/ - - To ease the transition, we have simultaneously released v0.7.0 of both - ``xray`` and ``xarray`` on the Python Package Index. These packages are - identical. For now, ``import xray`` still works, except it issues a - deprecation warning. This will be the last xray release. Going forward, we - recommend switching your import statements to ``import xarray as xr``. - - .. _v0.7.0.breaking: - - Breaking changes - ~~~~~~~~~~~~~~~~ - - - The internal data model used by ``xray.DataArray`` has been - rewritten to fix several outstanding issues (:issue:`367`, :issue:`634`, - `this stackoverflow report`_). Internally, ``DataArray`` is now implemented - in terms of ``._variable`` and ``._coords`` attributes instead of holding - variables in a ``Dataset`` object. - - This refactor ensures that if a DataArray has the - same name as one of its coordinates, the array and the coordinate no longer - share the same data. - - In practice, this means that creating a DataArray with the same ``name`` as - one of its dimensions no longer automatically uses that array to label the - corresponding coordinate. You will now need to provide coordinate labels - explicitly. Here's the old behavior: - - .. ipython:: - :verbatim: - - In [2]: xray.DataArray([4, 5, 6], dims="x", name="x") - Out[2]: - - array([4, 5, 6]) + x int64 1 + Data variables: + y int64 2 + + In [13]: ds.sel(x=[1.1, 2.1], method="pad") + Out[13]: + + Dimensions: (x: 2) Coordinates: - * x (x) int64 4 5 6 - - and the new behavior (compare the values of the ``x`` coordinate): - - .. ipython:: + * x (x) int64 1 2 + Data variables: + y (x) int64 2 3 + + See :ref:`nearest neighbor lookups` for more details. +- You can now control the underlying backend used for accessing remote + datasets (via OPeNDAP) by specifying ``engine='netcdf4'`` or + ``engine='pydap'``. +- xray now provides experimental support for reading and writing netCDF4 files directly + via `h5py`_ with the `h5netcdf`_ package, avoiding the netCDF4-Python package. You + will need to install h5netcdf and specify ``engine='h5netcdf'`` to try this + feature. +- Accessing data from remote datasets now has retrying logic (with exponential + backoff) that should make it robust to occasional bad responses from DAP + servers. +- You can control the width of the Dataset repr with ``xray.set_options``. + It can be used either as a context manager, in which case the default is restored + outside the context: + + .. ipython:: python + + ds = xray.Dataset({"x": np.arange(1000)}) + with xray.set_options(display_width=40): + print(ds) + + Or to set a global option: + + .. ipython:: :verbatim: - - In [2]: xray.DataArray([4, 5, 6], dims="x", name="x") - Out[2]: - - array([4, 5, 6]) - Coordinates: - * x (x) int64 0 1 2 - - - It is no longer possible to convert a DataArray to a Dataset with - ``xray.DataArray.to_dataset`` if it is unnamed. This will now - raise ``ValueError``. If the array is unnamed, you need to supply the - ``name`` argument. - - .. _this stackoverflow report: http://stackoverflow.com/questions/33158558/python-xray-extract-first-and-last-time-value-within-each-month-of-a-timeseries - - Enhancements - ~~~~~~~~~~~~ - - - Basic support for :py:class:`~pandas.MultiIndex` coordinates on xray objects, including - indexing, :py:meth:`~DataArray.stack` and :py:meth:`~DataArray.unstack`: - - .. ipython:: + + In [1]: xray.set_options(display_width=80) + + The default value for the ``display_width`` option is 80. + +.. _h5py: http://www.h5py.org/ +.. _h5netcdf: https://github.com/shoyer/h5netcdf + +Deprecations +~~~~~~~~~~~~ + +- The method ``load_data()`` has been renamed to the more succinct + ``xray.Dataset.load``. + +v0.4.1 (18 March 2015) +---------------------- + +The release contains bug fixes and several new features. All changes should be +fully backwards compatible. + +Enhancements +~~~~~~~~~~~~ + +- New documentation sections on :ref:`time-series` and + :ref:`combining multiple files`. +- ``xray.Dataset.resample`` lets you resample a dataset or data array to + a new temporal resolution. The syntax is the `same as pandas`_, except you + need to supply the time dimension explicitly: + + .. ipython:: python :verbatim: - - In [7]: df = pd.DataFrame({"foo": range(3), "x": ["a", "b", "b"], "y": [0, 0, 1]}) - - In [8]: s = df.set_index(["x", "y"])["foo"] - - In [12]: arr = xray.DataArray(s, dims="z") - - In [13]: arr - Out[13]: - - array([0, 1, 2]) - Coordinates: - * z (z) object ('a', 0) ('b', 0) ('b', 1) - - In [19]: arr.indexes["z"] - Out[19]: - MultiIndex(levels=[[u'a', u'b'], [0, 1]], - labels=[[0, 1, 1], [0, 0, 1]], - names=[u'x', u'y']) - - In [14]: arr.unstack("z") - Out[14]: - - array([[ 0., nan], - [ 1., 2.]]) - Coordinates: - * x (x) object 'a' 'b' - * y (y) int64 0 1 - - In [26]: arr.unstack("z").stack(z=("x", "y")) - Out[26]: - - array([ 0., nan, 1., 2.]) - Coordinates: - * z (z) object ('a', 0) ('a', 1) ('b', 0) ('b', 1) - - See :ref:`reshape.stack` for more details. - - .. warning:: - - xray's MultiIndex support is still experimental, and we have a long to- - do list of desired additions (:issue:`719`), including better display of - multi-index levels when printing a ``Dataset``, and support for saving - datasets with a MultiIndex to a netCDF file. User contributions in this - area would be greatly appreciated. - - - Support for reading GRIB, HDF4 and other file formats via PyNIO_. See - :ref:`io.pynio` for more details. - - Better error message when a variable is supplied with the same name as - one of its dimensions. - - Plotting: more control on colormap parameters (:issue:`642`). ``vmin`` and - ``vmax`` will not be silently ignored anymore. Setting ``center=False`` - prevents automatic selection of a divergent colormap. - - New ``xray.Dataset.shift`` and ``xray.Dataset.roll`` methods - for shifting/rotating datasets or arrays along a dimension: - - .. ipython:: python - :okwarning: - - array = xray.DataArray([5, 6, 7, 8], dims="x") - array.shift(x=2) - array.roll(x=2) - - Notice that ``shift`` moves data independently of coordinates, but ``roll`` - moves both data and coordinates. - - Assigning a ``pandas`` object directly as a ``Dataset`` variable is now permitted. Its - index names correspond to the ``dims`` of the ``Dataset``, and its data is aligned. - - Passing a :py:class:`pandas.DataFrame` or ``pandas.Panel`` to a Dataset constructor - is now permitted. - - New function ``xray.broadcast`` for explicitly broadcasting - ``DataArray`` and ``Dataset`` objects against each other. For example: - - .. ipython:: python - - a = xray.DataArray([1, 2, 3], dims="x") - b = xray.DataArray([5, 6], dims="y") - a - b - a2, b2 = xray.broadcast(a, b) - a2 - b2 - - .. _PyNIO: https://www.pyngl.ucar.edu/Nio.shtml - - Bug fixes - ~~~~~~~~~ - - - Fixes for several issues found on ``DataArray`` objects with the same name - as one of their coordinates (see :ref:`v0.7.0.breaking` for more details). - - ``DataArray.to_masked_array`` always returns masked array with mask being an - array (not a scalar value) (:issue:`684`) - - Allows for (imperfect) repr of Coords when underlying index is PeriodIndex (:issue:`645`). - - Fixes for several issues found on ``DataArray`` objects with the same name - as one of their coordinates (see :ref:`v0.7.0.breaking` for more details). - - Attempting to assign a ``Dataset`` or ``DataArray`` variable/attribute using - attribute-style syntax (e.g., ``ds.foo = 42``) now raises an error rather - than silently failing (:issue:`656`, :issue:`714`). - - You can now pass pandas objects with non-numpy dtypes (e.g., ``categorical`` - or ``datetime64`` with a timezone) into xray without an error - (:issue:`716`). - - Acknowledgments - ~~~~~~~~~~~~~~~ - - The following individuals contributed to this release: - - - Antony Lee - - Fabien Maussion - - Joe Hamman - - Maximilian Roos - - Stephan Hoyer - - Takeshi Kanmae - - femtotrader - - v0.6.1 (21 October 2015) - ------------------------ - - This release contains a number of bug and compatibility fixes, as well - as enhancements to plotting, indexing and writing files to disk. - - Note that the minimum required version of dask for use with xray is now - version 0.6. - - API Changes - ~~~~~~~~~~~ - - - The handling of colormaps and discrete color lists for 2D plots in - ``xray.DataArray.plot`` was changed to provide more compatibility - with matplotlib's ``contour`` and ``contourf`` functions (:issue:`538`). - Now discrete lists of colors should be specified using ``colors`` keyword, - rather than ``cmap``. - - Enhancements - ~~~~~~~~~~~~ - - - Faceted plotting through ``xray.plot.FacetGrid`` and the - ``xray.plot.plot`` method. See :ref:`plotting.faceting` for more details - and examples. - - ``xray.Dataset.sel`` and ``xray.Dataset.reindex`` now support - the ``tolerance`` argument for controlling nearest-neighbor selection - (:issue:`629`): - - .. ipython:: + + time = pd.date_range("2000-01-01", freq="6H", periods=10) + array = xray.DataArray(np.arange(10), [("time", time)]) + array.resample("1D", dim="time") + + You can specify how to do the resampling with the ``how`` argument and other + options such as ``closed`` and ``label`` let you control labeling: + + .. ipython:: python :verbatim: - - In [5]: array = xray.DataArray([1, 2, 3], dims="x") - - In [6]: array.reindex(x=[0.9, 1.5], method="nearest", tolerance=0.2) - Out[6]: - - array([ 2., nan]) - Coordinates: - * x (x) float64 0.9 1.5 - - This feature requires pandas v0.17 or newer. - - New ``encoding`` argument in ``xray.Dataset.to_netcdf`` for writing - netCDF files with compression, as described in the new documentation - section on :ref:`io.netcdf.writing_encoded`. - - Add ``xray.Dataset.real`` and ``xray.Dataset.imag`` - attributes to Dataset and DataArray (:issue:`553`). - - More informative error message with ``xray.Dataset.from_dataframe`` - if the frame has duplicate columns. - - xray now uses deterministic names for dask arrays it creates or opens from - disk. This allows xray users to take advantage of dask's nascent support for - caching intermediate computation results. See :issue:`555` for an example. - - Bug fixes - ~~~~~~~~~ - - - Forwards compatibility with the latest pandas release (v0.17.0). We were - using some internal pandas routines for datetime conversion, which - unfortunately have now changed upstream (:issue:`569`). - - Aggregation functions now correctly skip ``NaN`` for data for ``complex128`` - dtype (:issue:`554`). - - Fixed indexing 0d arrays with unicode dtype (:issue:`568`). - - ``xray.DataArray.name`` and Dataset keys must be a string or None to - be written to netCDF (:issue:`533`). - - ``xray.DataArray.where`` now uses dask instead of numpy if either the - array or ``other`` is a dask array. Previously, if ``other`` was a numpy array - the method was evaluated eagerly. - - Global attributes are now handled more consistently when loading remote - datasets using ``engine='pydap'`` (:issue:`574`). - - It is now possible to assign to the ``.data`` attribute of DataArray objects. - - ``coordinates`` attribute is now kept in the encoding dictionary after - decoding (:issue:`610`). - - Compatibility with numpy 1.10 (:issue:`617`). - - Acknowledgments - ~~~~~~~~~~~~~~~ - - The following individuals contributed to this release: - - - Ryan Abernathey - - Pete Cable - - Clark Fitzgerald - - Joe Hamman - - Stephan Hoyer - - Scott Sinclair - - v0.6.0 (21 August 2015) - ----------------------- - - This release includes numerous bug fixes and enhancements. Highlights - include the introduction of a plotting module and the new Dataset and DataArray - methods ``xray.Dataset.isel_points``, ``xray.Dataset.sel_points``, - ``xray.Dataset.where`` and ``xray.Dataset.diff``. There are no - breaking changes from v0.5.2. - - Enhancements - ~~~~~~~~~~~~ - - - Plotting methods have been implemented on DataArray objects - ``xray.DataArray.plot`` through integration with matplotlib - (:issue:`185`). For an introduction, see :ref:`plotting`. - - Variables in netCDF files with multiple missing values are now decoded as NaN - after issuing a warning if open_dataset is called with mask_and_scale=True. - - We clarified our rules for when the result from an xray operation is a copy - vs. a view (see :ref:`copies_vs_views` for more details). - - Dataset variables are now written to netCDF files in order of appearance - when using the netcdf4 backend (:issue:`479`). - - - Added ``xray.Dataset.isel_points`` and ``xray.Dataset.sel_points`` - to support pointwise indexing of Datasets and DataArrays (:issue:`475`). - - .. ipython:: + + array.resample("1D", dim="time", how="sum", label="right") + + If the desired temporal resolution is higher than the original data + (upsampling), xray will insert missing values: + + .. ipython:: python :verbatim: - - In [1]: da = xray.DataArray( - ...: np.arange(56).reshape((7, 8)), - ...: coords={"x": list("abcdefg"), "y": 10 * np.arange(8)}, - ...: dims=["x", "y"], - ...: ) - - In [2]: da - Out[2]: - - array([[ 0, 1, 2, 3, 4, 5, 6, 7], - [ 8, 9, 10, 11, 12, 13, 14, 15], - [16, 17, 18, 19, 20, 21, 22, 23], - [24, 25, 26, 27, 28, 29, 30, 31], - [32, 33, 34, 35, 36, 37, 38, 39], - [40, 41, 42, 43, 44, 45, 46, 47], - [48, 49, 50, 51, 52, 53, 54, 55]]) - Coordinates: - * y (y) int64 0 10 20 30 40 50 60 70 - * x (x) |S1 'a' 'b' 'c' 'd' 'e' 'f' 'g' - - # we can index by position along each dimension - In [3]: da.isel_points(x=[0, 1, 6], y=[0, 1, 0], dim="points") - Out[3]: - - array([ 0, 9, 48]) - Coordinates: - y (points) int64 0 10 0 - x (points) |S1 'a' 'b' 'g' - * points (points) int64 0 1 2 - - # or equivalently by label - In [9]: da.sel_points(x=["a", "b", "g"], y=[0, 10, 0], dim="points") - Out[9]: - - array([ 0, 9, 48]) - Coordinates: - y (points) int64 0 10 0 - x (points) |S1 'a' 'b' 'g' - * points (points) int64 0 1 2 - - - New ``xray.Dataset.where`` method for masking xray objects according - to some criteria. This works particularly well with multi-dimensional data: - - .. ipython:: python - - ds = xray.Dataset(coords={"x": range(100), "y": range(100)}) - ds["distance"] = np.sqrt(ds.x ** 2 + ds.y ** 2) - - @savefig where_example.png width=4in height=4in - ds.distance.where(ds.distance < 100).plot() - - - Added new methods ``xray.DataArray.diff`` and ``xray.Dataset.diff`` - for finite difference calculations along a given axis. - - - New ``xray.DataArray.to_masked_array`` convenience method for - returning a numpy.ma.MaskedArray. - - .. ipython:: python - - da = xray.DataArray(np.random.random_sample(size=(5, 4))) - da.where(da < 0.5) - da.where(da < 0.5).to_masked_array(copy=True) - - - Added new flag "drop_variables" to ``xray.open_dataset`` for - excluding variables from being parsed. This may be useful to drop - variables with problems or inconsistent values. - - Bug fixes - ~~~~~~~~~ - - - Fixed aggregation functions (e.g., sum and mean) on big-endian arrays when - bottleneck is installed (:issue:`489`). - - Dataset aggregation functions dropped variables with unsigned integer dtype - (:issue:`505`). - - ``.any()`` and ``.all()`` were not lazy when used on xray objects containing - dask arrays. - - Fixed an error when attempting to saving datetime64 variables to netCDF - files when the first element is ``NaT`` (:issue:`528`). - - Fix pickle on DataArray objects (:issue:`515`). - - Fixed unnecessary coercion of float64 to float32 when using netcdf3 and - netcdf4_classic formats (:issue:`526`). - - v0.5.2 (16 July 2015) - --------------------- - - This release contains bug fixes, several additional options for opening and - saving netCDF files, and a backwards incompatible rewrite of the advanced - options for ``xray.concat``. - - Backwards incompatible changes - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - - The optional arguments ``concat_over`` and ``mode`` in ``xray.concat`` have - been removed and replaced by ``data_vars`` and ``coords``. The new arguments are both - more easily understood and more robustly implemented, and allowed us to fix a bug - where ``concat`` accidentally loaded data into memory. If you set values for - these optional arguments manually, you will need to update your code. The default - behavior should be unchanged. - - Enhancements - ~~~~~~~~~~~~ - - - ``xray.open_mfdataset`` now supports a ``preprocess`` argument for - preprocessing datasets prior to concatenaton. This is useful if datasets - cannot be otherwise merged automatically, e.g., if the original datasets - have conflicting index coordinates (:issue:`443`). - - ``xray.open_dataset`` and ``xray.open_mfdataset`` now use a - global thread lock by default for reading from netCDF files with dask. This - avoids possible segmentation faults for reading from netCDF4 files when HDF5 - is not configured properly for concurrent access (:issue:`444`). - - Added support for serializing arrays of complex numbers with `engine='h5netcdf'`. - - The new ``xray.save_mfdataset`` function allows for saving multiple - datasets to disk simultaneously. This is useful when processing large datasets - with dask.array. For example, to save a dataset too big to fit into memory - to one file per year, we could write: - - .. ipython:: + + array.resample("3H", "time") + +- ``first`` and ``last`` methods on groupby objects let you take the first or + last examples from each group along the grouped axis: + + .. ipython:: python :verbatim: - - In [1]: years, datasets = zip(*ds.groupby("time.year")) - - In [2]: paths = ["%s.nc" % y for y in years] - - In [3]: xray.save_mfdataset(datasets, paths) - - Bug fixes - ~~~~~~~~~ - - - Fixed ``min``, ``max``, ``argmin`` and ``argmax`` for arrays with string or - unicode types (:issue:`453`). - - ``xray.open_dataset`` and ``xray.open_mfdataset`` support - supplying chunks as a single integer. - - Fixed a bug in serializing scalar datetime variable to netCDF. - - Fixed a bug that could occur in serialization of 0-dimensional integer arrays. - - Fixed a bug where concatenating DataArrays was not always lazy (:issue:`464`). - - When reading datasets with h5netcdf, bytes attributes are decoded to strings. - This allows conventions decoding to work properly on Python 3 (:issue:`451`). - - v0.5.1 (15 June 2015) - --------------------- - - This minor release fixes a few bugs and an inconsistency with pandas. It also - adds the ``pipe`` method, copied from pandas. - - Enhancements - ~~~~~~~~~~~~ - - - Added ``xray.Dataset.pipe``, replicating the `new pandas method`_ in version - 0.16.2. See :ref:`transforming datasets` for more details. - - ``xray.Dataset.assign`` and ``xray.Dataset.assign_coords`` - now assign new variables in sorted (alphabetical) order, mirroring the - behavior in pandas. Previously, the order was arbitrary. - - .. _new pandas method: http://pandas.pydata.org/pandas-docs/version/0.16.2/whatsnew.html#pipe - - Bug fixes - ~~~~~~~~~ - - - ``xray.concat`` fails in an edge case involving identical coordinate variables (:issue:`425`) - - We now decode variables loaded from netCDF3 files with the scipy engine using native - endianness (:issue:`416`). This resolves an issue when aggregating these arrays with - bottleneck installed. - - v0.5 (1 June 2015) - ------------------ - - Highlights - ~~~~~~~~~~ - - The headline feature in this release is experimental support for out-of-core - computing (data that doesn't fit into memory) with :doc:`user-guide/dask`. This includes a new - top-level function ``xray.open_mfdataset`` that makes it easy to open - a collection of netCDF (using dask) as a single ``xray.Dataset`` object. For - more on dask, read the `blog post introducing xray + dask`_ and the new - documentation section :doc:`user-guide/dask`. - - .. _blog post introducing xray + dask: https://www.anaconda.com/blog/developer-blog/xray-dask-out-core-labeled-arrays-python/ - - Dask makes it possible to harness parallelism and manipulate gigantic datasets - with xray. It is currently an optional dependency, but it may become required - in the future. - - Backwards incompatible changes - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - - The logic used for choosing which variables are concatenated with - ``xray.concat`` has changed. Previously, by default any variables - which were equal across a dimension were not concatenated. This lead to some - surprising behavior, where the behavior of groupby and concat operations - could depend on runtime values (:issue:`268`). For example: - - .. ipython:: + + array.groupby("time.day").first() + + These methods combine well with ``resample``: + + .. ipython:: python :verbatim: - - In [1]: ds = xray.Dataset({"x": 0}) - - In [2]: xray.concat([ds, ds], dim="y") - Out[2]: - - Dimensions: () - Coordinates: - *empty* - Data variables: - x int64 0 - - Now, the default always concatenates data variables: - - .. ipython:: python - :suppress: - - ds = xray.Dataset({"x": 0}) - - .. ipython:: python - - xray.concat([ds, ds], dim="y") - - To obtain the old behavior, supply the argument ``concat_over=[]``. - - Enhancements - ~~~~~~~~~~~~ - - - New ``xray.Dataset.to_array`` and enhanced - ``xray.DataArray.to_dataset`` methods make it easy to switch back - and forth between arrays and datasets: - - .. ipython:: python - - ds = xray.Dataset( - {"a": 1, "b": ("x", [1, 2, 3])}, - coords={"c": 42}, - attrs={"Conventions": "None"}, - ) - ds.to_array() - ds.to_array().to_dataset(dim="variable") - - - New ``xray.Dataset.fillna`` method to fill missing values, modeled - off the pandas method of the same name: - - .. ipython:: python - - array = xray.DataArray([np.nan, 1, np.nan, 3], dims="x") - array.fillna(0) - - ``fillna`` works on both ``Dataset`` and ``DataArray`` objects, and uses - index based alignment and broadcasting like standard binary operations. It - also can be applied by group, as illustrated in - :ref:`/examples/weather-data.ipynb#Fill-missing-values-with-climatology`. - - New ``xray.Dataset.assign`` and ``xray.Dataset.assign_coords`` - methods patterned off the new :py:meth:`DataFrame.assign ` - method in pandas: - - .. ipython:: python - - ds = xray.Dataset({"y": ("x", [1, 2, 3])}) - ds.assign(z=lambda ds: ds.y ** 2) - ds.assign_coords(z=("x", ["a", "b", "c"])) - - These methods return a new Dataset (or DataArray) with updated data or - coordinate variables. - - ``xray.Dataset.sel`` now supports the ``method`` parameter, which works - like the paramter of the same name on ``xray.Dataset.reindex``. It - provides a simple interface for doing nearest-neighbor interpolation: - - .. use verbatim because I can't seem to install pandas 0.16.1 on RTD :( - - .. ipython:: - :verbatim: - - In [12]: ds.sel(x=1.1, method="nearest") - Out[12]: - - Dimensions: () - Coordinates: - x int64 1 - Data variables: - y int64 2 - - In [13]: ds.sel(x=[1.1, 2.1], method="pad") - Out[13]: - - Dimensions: (x: 2) - Coordinates: - * x (x) int64 1 2 - Data variables: - y (x) int64 2 3 - - See :ref:`nearest neighbor lookups` for more details. - - You can now control the underlying backend used for accessing remote - datasets (via OPeNDAP) by specifying ``engine='netcdf4'`` or - ``engine='pydap'``. - - xray now provides experimental support for reading and writing netCDF4 files directly - via `h5py`_ with the `h5netcdf`_ package, avoiding the netCDF4-Python package. You - will need to install h5netcdf and specify ``engine='h5netcdf'`` to try this - feature. - - Accessing data from remote datasets now has retrying logic (with exponential - backoff) that should make it robust to occasional bad responses from DAP - servers. - - You can control the width of the Dataset repr with ``xray.set_options``. - It can be used either as a context manager, in which case the default is restored - outside the context: - - .. ipython:: python - - ds = xray.Dataset({"x": np.arange(1000)}) - with xray.set_options(display_width=40): - print(ds) - - Or to set a global option: - - .. ipython:: - :verbatim: - - In [1]: xray.set_options(display_width=80) - - The default value for the ``display_width`` option is 80. - - .. _h5py: http://www.h5py.org/ - .. _h5netcdf: https://github.com/shoyer/h5netcdf - - Deprecations - ~~~~~~~~~~~~ - - - The method ``load_data()`` has been renamed to the more succinct - ``xray.Dataset.load``. - - v0.4.1 (18 March 2015) - ---------------------- - - The release contains bug fixes and several new features. All changes should be - fully backwards compatible. - - Enhancements - ~~~~~~~~~~~~ - - - New documentation sections on :ref:`time-series` and - :ref:`combining multiple files`. - - ``xray.Dataset.resample`` lets you resample a dataset or data array to - a new temporal resolution. The syntax is the `same as pandas`_, except you - need to supply the time dimension explicitly: - - .. ipython:: python - :verbatim: - - time = pd.date_range("2000-01-01", freq="6H", periods=10) - array = xray.DataArray(np.arange(10), [("time", time)]) - array.resample("1D", dim="time") - - You can specify how to do the resampling with the ``how`` argument and other - options such as ``closed`` and ``label`` let you control labeling: - - .. ipython:: python - :verbatim: - - array.resample("1D", dim="time", how="sum", label="right") - - If the desired temporal resolution is higher than the original data - (upsampling), xray will insert missing values: - - .. ipython:: python - :verbatim: - - array.resample("3H", "time") - - - ``first`` and ``last`` methods on groupby objects let you take the first or - last examples from each group along the grouped axis: - - .. ipython:: python - :verbatim: - - array.groupby("time.day").first() - - These methods combine well with ``resample``: - - .. ipython:: python - :verbatim: - - array.resample("1D", dim="time", how="first") - - - - ``xray.Dataset.swap_dims`` allows for easily swapping one dimension - out for another: - - .. ipython:: python - - ds = xray.Dataset({"x": range(3), "y": ("x", list("abc"))}) - ds - ds.swap_dims({"x": "y"}) - - This was possible in earlier versions of xray, but required some contortions. - - ``xray.open_dataset`` and ``xray.Dataset.to_netcdf`` now - accept an ``engine`` argument to explicitly select which underlying library - (netcdf4 or scipy) is used for reading/writing a netCDF file. - - .. _same as pandas: http://pandas.pydata.org/pandas-docs/stable/timeseries.html#up-and-downsampling - - Bug fixes - ~~~~~~~~~ - - - Fixed a bug where data netCDF variables read from disk with - ``engine='scipy'`` could still be associated with the file on disk, even - after closing the file (:issue:`341`). This manifested itself in warnings - about mmapped arrays and segmentation faults (if the data was accessed). - - Silenced spurious warnings about all-NaN slices when using nan-aware - aggregation methods (:issue:`344`). - - Dataset aggregations with ``keep_attrs=True`` now preserve attributes on - data variables, not just the dataset itself. - - Tests for xray now pass when run on Windows (:issue:`360`). - - Fixed a regression in v0.4 where saving to netCDF could fail with the error - ``ValueError: could not automatically determine time units``. - - v0.4 (2 March, 2015) - -------------------- - - This is one of the biggest releases yet for xray: it includes some major - changes that may break existing code, along with the usual collection of minor - enhancements and bug fixes. On the plus side, this release includes all - hitherto planned breaking changes, so the upgrade path for xray should be - smoother going forward. - - Breaking changes - ~~~~~~~~~~~~~~~~ - - - We now automatically align index labels in arithmetic, dataset construction, - merging and updating. This means the need for manually invoking methods like - ``xray.align`` and ``xray.Dataset.reindex_like`` should be - vastly reduced. - - :ref:`For arithmetic`, we align - based on the **intersection** of labels: - - .. ipython:: python - - lhs = xray.DataArray([1, 2, 3], [("x", [0, 1, 2])]) - rhs = xray.DataArray([2, 3, 4], [("x", [1, 2, 3])]) - lhs + rhs - - :ref:`For dataset construction and merging`, we align based on the - **union** of labels: - - .. ipython:: python - - xray.Dataset({"foo": lhs, "bar": rhs}) - - :ref:`For update and __setitem__`, we align based on the **original** - object: - - .. ipython:: python - - lhs.coords["rhs"] = rhs - lhs - - - Aggregations like ``mean`` or ``median`` now skip missing values by default: - - .. ipython:: python - - xray.DataArray([1, 2, np.nan, 3]).mean() - - You can turn this behavior off by supplying the keyword arugment - ``skipna=False``. - - These operations are lightning fast thanks to integration with bottleneck_, - which is a new optional dependency for xray (numpy is used if bottleneck is - not installed). - - Scalar coordinates no longer conflict with constant arrays with the same - value (e.g., in arithmetic, merging datasets and concat), even if they have - different shape (:issue:`243`). For example, the coordinate ``c`` here - persists through arithmetic, even though it has different shapes on each - DataArray: - - .. ipython:: python - - a = xray.DataArray([1, 2], coords={"c": 0}, dims="x") - b = xray.DataArray([1, 2], coords={"c": ("x", [0, 0])}, dims="x") - (a + b).coords - - This functionality can be controlled through the ``compat`` option, which - has also been added to the ``xray.Dataset`` constructor. - - Datetime shortcuts such as ``'time.month'`` now return a ``DataArray`` with - the name ``'month'``, not ``'time.month'`` (:issue:`345`). This makes it - easier to index the resulting arrays when they are used with ``groupby``: - - .. ipython:: python - - time = xray.DataArray( - pd.date_range("2000-01-01", periods=365), dims="time", name="time" - ) - counts = time.groupby("time.month").count() - counts.sel(month=2) - - Previously, you would need to use something like - ``counts.sel(**{'time.month': 2}})``, which is much more awkward. - - The ``season`` datetime shortcut now returns an array of string labels - such `'DJF'`: - - .. ipython:: python - - ds = xray.Dataset({"t": pd.date_range("2000-01-01", periods=12, freq="M")}) - ds["t.season"] - - Previously, it returned numbered seasons 1 through 4. - - We have updated our use of the terms of "coordinates" and "variables". What - were known in previous versions of xray as "coordinates" and "variables" are - now referred to throughout the documentation as "coordinate variables" and - "data variables". This brings xray in closer alignment to `CF Conventions`_. - The only visible change besides the documentation is that ``Dataset.vars`` - has been renamed ``Dataset.data_vars``. - - You will need to update your code if you have been ignoring deprecation - warnings: methods and attributes that were deprecated in xray v0.3 or earlier - (e.g., ``dimensions``, ``attributes```) have gone away. - - .. _bottleneck: https://github.com/pydata/bottleneck - - Enhancements - ~~~~~~~~~~~~ - - - Support for ``xray.Dataset.reindex`` with a fill method. This - provides a useful shortcut for upsampling: - - .. ipython:: python - - data = xray.DataArray([1, 2, 3], [("x", range(3))]) - data.reindex(x=[0.5, 1, 1.5, 2, 2.5], method="pad") - - This will be especially useful once pandas 0.16 is released, at which point - xray will immediately support reindexing with - `method='nearest' `_. - - Use functions that return generic ndarrays with DataArray.groupby.apply and - Dataset.apply (:issue:`327` and :issue:`329`). Thanks Jeff Gerard! - - Consolidated the functionality of ``dumps`` (writing a dataset to a netCDF3 - bytestring) into ``xray.Dataset.to_netcdf`` (:issue:`333`). - - ``xray.Dataset.to_netcdf`` now supports writing to groups in netCDF4 - files (:issue:`333`). It also finally has a full docstring -- you should read - it! - - ``xray.open_dataset`` and ``xray.Dataset.to_netcdf`` now - work on netCDF3 files when netcdf4-python is not installed as long as scipy - is available (:issue:`333`). - - The new ``xray.Dataset.drop`` and ``xray.DataArray.drop`` methods - makes it easy to drop explicitly listed variables or index labels: - - .. ipython:: python - :okwarning: - - # drop variables - ds = xray.Dataset({"x": 0, "y": 1}) - ds.drop("x") - - # drop index labels - arr = xray.DataArray([1, 2, 3], coords=[("x", list("abc"))]) - arr.drop(["a", "c"], dim="x") - - - ``xray.Dataset.broadcast_equals`` has been added to correspond to - the new ``compat`` option. - - Long attributes are now truncated at 500 characters when printing a dataset - (:issue:`338`). This should make things more convenient for working with - datasets interactively. - - Added a new documentation example, :ref:`/examples/monthly-means.ipynb`. Thanks Joe - Hamman! - - Bug fixes - ~~~~~~~~~ - - - Several bug fixes related to decoding time units from netCDF files - (:issue:`316`, :issue:`330`). Thanks Stefan Pfenninger! - - xray no longer requires ``decode_coords=False`` when reading datasets with - unparseable coordinate attributes (:issue:`308`). - - Fixed ``DataArray.loc`` indexing with ``...`` (:issue:`318`). - - Fixed an edge case that resulting in an error when reindexing - multi-dimensional variables (:issue:`315`). - - Slicing with negative step sizes (:issue:`312`). - - Invalid conversion of string arrays to numeric dtype (:issue:`305`). - - Fixed``repr()`` on dataset objects with non-standard dates (:issue:`347`). - - Deprecations - ~~~~~~~~~~~~ - - - ``dump`` and ``dumps`` have been deprecated in favor of - ``xray.Dataset.to_netcdf``. - - ``drop_vars`` has been deprecated in favor of ``xray.Dataset.drop``. - - Future plans - ~~~~~~~~~~~~ - - The biggest feature I'm excited about working toward in the immediate future - is supporting out-of-core operations in xray using Dask_, a part of the Blaze_ - project. For a preview of using Dask with weather data, read - `this blog post`_ by Matthew Rocklin. See :issue:`328` for more details. - - .. _Dask: http://dask.pydata.org - .. _Blaze: http://blaze.pydata.org - .. _this blog post: http://matthewrocklin.com/blog/work/2015/02/13/Towards-OOC-Slicing-and-Stacking/ - - v0.3.2 (23 December, 2014) - -------------------------- - - This release focused on bug-fixes, speedups and resolving some niggling - inconsistencies. - - There are a few cases where the behavior of xray differs from the previous - version. However, I expect that in almost all cases your code will continue to - run unmodified. - - .. warning:: - - xray now requires pandas v0.15.0 or later. This was necessary for - supporting TimedeltaIndex without too many painful hacks. - - Backwards incompatible changes - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - - Arrays of :py:class:`datetime.datetime` objects are now automatically cast to - ``datetime64[ns]`` arrays when stored in an xray object, using machinery - borrowed from pandas: - - .. ipython:: python - - from datetime import datetime - - xray.Dataset({"t": [datetime(2000, 1, 1)]}) - - - xray now has support (including serialization to netCDF) for - :py:class:`~pandas.TimedeltaIndex`. :py:class:`datetime.timedelta` objects - are thus accordingly cast to ``timedelta64[ns]`` objects when appropriate. - - Masked arrays are now properly coerced to use ``NaN`` as a sentinel value - (:issue:`259`). - - Enhancements - ~~~~~~~~~~~~ - - - Due to popular demand, we have added experimental attribute style access as - a shortcut for dataset variables, coordinates and attributes: - - .. ipython:: python - - ds = xray.Dataset({"tmin": ([], 25, {"units": "celsius"})}) - ds.tmin.units - - Tab-completion for these variables should work in editors such as IPython. - However, setting variables or attributes in this fashion is not yet - supported because there are some unresolved ambiguities (:issue:`300`). - - You can now use a dictionary for indexing with labeled dimensions. This - provides a safe way to do assignment with labeled dimensions: - - .. ipython:: python - - array = xray.DataArray(np.zeros(5), dims=["x"]) - array[dict(x=slice(3))] = 1 - array - - - Non-index coordinates can now be faithfully written to and restored from - netCDF files. This is done according to CF conventions when possible by - using the ``coordinates`` attribute on a data variable. When not possible, - xray defines a global ``coordinates`` attribute. - - Preliminary support for converting ``xray.DataArray`` objects to and from - CDAT_ ``cdms2`` variables. - - We sped up any operation that involves creating a new Dataset or DataArray - (e.g., indexing, aggregation, arithmetic) by a factor of 30 to 50%. The full - speed up requires cyordereddict_ to be installed. - - .. _CDAT: http://uvcdat.llnl.gov/ - .. _cyordereddict: https://github.com/shoyer/cyordereddict - - Bug fixes - ~~~~~~~~~ - - - Fix for ``to_dataframe()`` with 0d string/object coordinates (:issue:`287`) - - Fix for ``to_netcdf`` with 0d string variable (:issue:`284`) - - Fix writing datetime64 arrays to netcdf if NaT is present (:issue:`270`) - - Fix align silently upcasts data arrays when NaNs are inserted (:issue:`264`) - - Future plans - ~~~~~~~~~~~~ - - - I am contemplating switching to the terms "coordinate variables" and "data - variables" instead of the (currently used) "coordinates" and "variables", - following their use in `CF Conventions`_ (:issue:`293`). This would mostly - have implications for the documentation, but I would also change the - ``Dataset`` attribute ``vars`` to ``data``. - - I no longer certain that automatic label alignment for arithmetic would be a - good idea for xray -- it is a feature from pandas that I have not missed - (:issue:`186`). - - The main API breakage that I *do* anticipate in the next release is finally - making all aggregation operations skip missing values by default - (:issue:`130`). I'm pretty sick of writing ``ds.reduce(np.nanmean, 'time')``. - - The next version of xray (0.4) will remove deprecated features and aliases - whose use currently raises a warning. - - If you have opinions about any of these anticipated changes, I would love to - hear them -- please add a note to any of the referenced GitHub issues. - - .. _CF Conventions: http://cfconventions.org/Data/cf-conventions/cf-conventions-1.6/build/cf-conventions.html - - v0.3.1 (22 October, 2014) - ------------------------- - - This is mostly a bug-fix release to make xray compatible with the latest - release of pandas (v0.15). - - We added several features to better support working with missing values and - exporting xray objects to pandas. We also reorganized the internal API for - serializing and deserializing datasets, but this change should be almost - entirely transparent to users. - - Other than breaking the experimental DataStore API, there should be no - backwards incompatible changes. - - New features - ~~~~~~~~~~~~ - - - Added ``xray.Dataset.count`` and ``xray.Dataset.dropna`` - methods, copied from pandas, for working with missing values (:issue:`247`, - :issue:`58`). - - Added ``xray.DataArray.to_pandas`` for - converting a data array into the pandas object with the same dimensionality - (1D to Series, 2D to DataFrame, etc.) (:issue:`255`). - - Support for reading gzipped netCDF3 files (:issue:`239`). - - Reduced memory usage when writing netCDF files (:issue:`251`). - - 'missing_value' is now supported as an alias for the '_FillValue' attribute - on netCDF variables (:issue:`245`). - - Trivial indexes, equivalent to ``range(n)`` where ``n`` is the length of the - dimension, are no longer written to disk (:issue:`245`). - - Bug fixes - ~~~~~~~~~ - - - Compatibility fixes for pandas v0.15 (:issue:`262`). - - Fixes for display and indexing of ``NaT`` (not-a-time) (:issue:`238`, - :issue:`240`) - - Fix slicing by label was an argument is a data array (:issue:`250`). - - Test data is now shipped with the source distribution (:issue:`253`). - - Ensure order does not matter when doing arithmetic with scalar data arrays - (:issue:`254`). - - Order of dimensions preserved with ``DataArray.to_dataframe`` (:issue:`260`). - - v0.3 (21 September 2014) - ------------------------ - - New features - ~~~~~~~~~~~~ - - - **Revamped coordinates**: "coordinates" now refer to all arrays that are not - used to index a dimension. Coordinates are intended to allow for keeping track - of arrays of metadata that describe the grid on which the points in "variable" - arrays lie. They are preserved (when unambiguous) even though mathematical - operations. - - **Dataset math** ``xray.Dataset`` objects now support all arithmetic - operations directly. Dataset-array operations map across all dataset - variables; dataset-dataset operations act on each pair of variables with the - same name. - - **GroupBy math**: This provides a convenient shortcut for normalizing by the - average value of a group. - - The dataset ``__repr__`` method has been entirely overhauled; dataset - objects now show their values when printed. - - You can now index a dataset with a list of variables to return a new dataset: - ``ds[['foo', 'bar']]``. - - Backwards incompatible changes - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - - ``Dataset.__eq__`` and ``Dataset.__ne__`` are now element-wise operations - instead of comparing all values to obtain a single boolean. Use the method - ``xray.Dataset.equals`` instead. - - Deprecations - ~~~~~~~~~~~~ - - - ``Dataset.noncoords`` is deprecated: use ``Dataset.vars`` instead. - - ``Dataset.select_vars`` deprecated: index a ``Dataset`` with a list of - variable names instead. - - ``DataArray.select_vars`` and ``DataArray.drop_vars`` deprecated: use - ``xray.DataArray.reset_coords`` instead. - - v0.2 (14 August 2014) - --------------------- - - This is major release that includes some new features and quite a few bug - fixes. Here are the highlights: - - - There is now a direct constructor for ``DataArray`` objects, which makes it - possible to create a DataArray without using a Dataset. This is highlighted - in the refreshed ``tutorial``. - - You can perform aggregation operations like ``mean`` directly on - ``xray.Dataset`` objects, thanks to Joe Hamman. These aggregation - methods also worked on grouped datasets. - - xray now works on Python 2.6, thanks to Anna Kuznetsova. - - A number of methods and attributes were given more sensible (usually shorter) - names: ``labeled`` -> ``sel``, ``indexed`` -> ``isel``, ``select`` -> - ``select_vars``, ``unselect`` -> ``drop_vars``, ``dimensions`` -> ``dims``, - ``coordinates`` -> ``coords``, ``attributes`` -> ``attrs``. - - New ``xray.Dataset.load_data`` and ``xray.Dataset.close`` - methods for datasets facilitate lower level of control of data loaded from - disk. - - v0.1.1 (20 May 2014) - -------------------- - - xray 0.1.1 is a bug-fix release that includes changes that should be almost - entirely backwards compatible with v0.1: - - - Python 3 support (:issue:`53`) - - Required numpy version relaxed to 1.7 (:issue:`129`) - - Return numpy.datetime64 arrays for non-standard calendars (:issue:`126`) - - Support for opening datasets associated with NetCDF4 groups (:issue:`127`) - - Bug-fixes for concatenating datetime arrays (:issue:`134`) - - Special thanks to new contributors Thomas Kluyver, Joe Hamman and Alistair - Miles. - - v0.1 (2 May 2014) - ----------------- - - Initial release. \ No newline at end of file + + array.resample("1D", dim="time", how="first") + + +- ``xray.Dataset.swap_dims`` allows for easily swapping one dimension + out for another: + + .. ipython:: python + + ds = xray.Dataset({"x": range(3), "y": ("x", list("abc"))}) + ds + ds.swap_dims({"x": "y"}) + + This was possible in earlier versions of xray, but required some contortions. +- ``xray.open_dataset`` and ``xray.Dataset.to_netcdf`` now + accept an ``engine`` argument to explicitly select which underlying library + (netcdf4 or scipy) is used for reading/writing a netCDF file. + +.. _same as pandas: http://pandas.pydata.org/pandas-docs/stable/timeseries.html#up-and-downsampling + +Bug fixes +~~~~~~~~~ + +- Fixed a bug where data netCDF variables read from disk with + ``engine='scipy'`` could still be associated with the file on disk, even + after closing the file (:issue:`341`). This manifested itself in warnings + about mmapped arrays and segmentation faults (if the data was accessed). +- Silenced spurious warnings about all-NaN slices when using nan-aware + aggregation methods (:issue:`344`). +- Dataset aggregations with ``keep_attrs=True`` now preserve attributes on + data variables, not just the dataset itself. +- Tests for xray now pass when run on Windows (:issue:`360`). +- Fixed a regression in v0.4 where saving to netCDF could fail with the error + ``ValueError: could not automatically determine time units``. + +v0.4 (2 March, 2015) +-------------------- + +This is one of the biggest releases yet for xray: it includes some major +changes that may break existing code, along with the usual collection of minor +enhancements and bug fixes. On the plus side, this release includes all +hitherto planned breaking changes, so the upgrade path for xray should be +smoother going forward. + +Breaking changes +~~~~~~~~~~~~~~~~ + +- We now automatically align index labels in arithmetic, dataset construction, + merging and updating. This means the need for manually invoking methods like + ``xray.align`` and ``xray.Dataset.reindex_like`` should be + vastly reduced. + + :ref:`For arithmetic`, we align + based on the **intersection** of labels: + + .. ipython:: python + + lhs = xray.DataArray([1, 2, 3], [("x", [0, 1, 2])]) + rhs = xray.DataArray([2, 3, 4], [("x", [1, 2, 3])]) + lhs + rhs + + :ref:`For dataset construction and merging`, we align based on the + **union** of labels: + + .. ipython:: python + + xray.Dataset({"foo": lhs, "bar": rhs}) + + :ref:`For update and __setitem__`, we align based on the **original** + object: + + .. ipython:: python + + lhs.coords["rhs"] = rhs + lhs + +- Aggregations like ``mean`` or ``median`` now skip missing values by default: + + .. ipython:: python + + xray.DataArray([1, 2, np.nan, 3]).mean() + + You can turn this behavior off by supplying the keyword arugment + ``skipna=False``. + + These operations are lightning fast thanks to integration with bottleneck_, + which is a new optional dependency for xray (numpy is used if bottleneck is + not installed). +- Scalar coordinates no longer conflict with constant arrays with the same + value (e.g., in arithmetic, merging datasets and concat), even if they have + different shape (:issue:`243`). For example, the coordinate ``c`` here + persists through arithmetic, even though it has different shapes on each + DataArray: + + .. ipython:: python + + a = xray.DataArray([1, 2], coords={"c": 0}, dims="x") + b = xray.DataArray([1, 2], coords={"c": ("x", [0, 0])}, dims="x") + (a + b).coords + + This functionality can be controlled through the ``compat`` option, which + has also been added to the ``xray.Dataset`` constructor. +- Datetime shortcuts such as ``'time.month'`` now return a ``DataArray`` with + the name ``'month'``, not ``'time.month'`` (:issue:`345`). This makes it + easier to index the resulting arrays when they are used with ``groupby``: + + .. ipython:: python + + time = xray.DataArray( + pd.date_range("2000-01-01", periods=365), dims="time", name="time" + ) + counts = time.groupby("time.month").count() + counts.sel(month=2) + + Previously, you would need to use something like + ``counts.sel(**{'time.month': 2}})``, which is much more awkward. +- The ``season`` datetime shortcut now returns an array of string labels + such `'DJF'`: + + .. ipython:: python + + ds = xray.Dataset({"t": pd.date_range("2000-01-01", periods=12, freq="M")}) + ds["t.season"] + + Previously, it returned numbered seasons 1 through 4. +- We have updated our use of the terms of "coordinates" and "variables". What + were known in previous versions of xray as "coordinates" and "variables" are + now referred to throughout the documentation as "coordinate variables" and + "data variables". This brings xray in closer alignment to `CF Conventions`_. + The only visible change besides the documentation is that ``Dataset.vars`` + has been renamed ``Dataset.data_vars``. +- You will need to update your code if you have been ignoring deprecation + warnings: methods and attributes that were deprecated in xray v0.3 or earlier + (e.g., ``dimensions``, ``attributes```) have gone away. + +.. _bottleneck: https://github.com/pydata/bottleneck + +Enhancements +~~~~~~~~~~~~ + +- Support for ``xray.Dataset.reindex`` with a fill method. This + provides a useful shortcut for upsampling: + + .. ipython:: python + + data = xray.DataArray([1, 2, 3], [("x", range(3))]) + data.reindex(x=[0.5, 1, 1.5, 2, 2.5], method="pad") + + This will be especially useful once pandas 0.16 is released, at which point + xray will immediately support reindexing with + `method='nearest' `_. +- Use functions that return generic ndarrays with DataArray.groupby.apply and + Dataset.apply (:issue:`327` and :issue:`329`). Thanks Jeff Gerard! +- Consolidated the functionality of ``dumps`` (writing a dataset to a netCDF3 + bytestring) into ``xray.Dataset.to_netcdf`` (:issue:`333`). +- ``xray.Dataset.to_netcdf`` now supports writing to groups in netCDF4 + files (:issue:`333`). It also finally has a full docstring -- you should read + it! +- ``xray.open_dataset`` and ``xray.Dataset.to_netcdf`` now + work on netCDF3 files when netcdf4-python is not installed as long as scipy + is available (:issue:`333`). +- The new ``xray.Dataset.drop`` and ``xray.DataArray.drop`` methods + makes it easy to drop explicitly listed variables or index labels: + + .. ipython:: python + :okwarning: + + # drop variables + ds = xray.Dataset({"x": 0, "y": 1}) + ds.drop("x") + + # drop index labels + arr = xray.DataArray([1, 2, 3], coords=[("x", list("abc"))]) + arr.drop(["a", "c"], dim="x") + +- ``xray.Dataset.broadcast_equals`` has been added to correspond to + the new ``compat`` option. +- Long attributes are now truncated at 500 characters when printing a dataset + (:issue:`338`). This should make things more convenient for working with + datasets interactively. +- Added a new documentation example, :ref:`/examples/monthly-means.ipynb`. Thanks Joe + Hamman! + +Bug fixes +~~~~~~~~~ + +- Several bug fixes related to decoding time units from netCDF files + (:issue:`316`, :issue:`330`). Thanks Stefan Pfenninger! +- xray no longer requires ``decode_coords=False`` when reading datasets with + unparseable coordinate attributes (:issue:`308`). +- Fixed ``DataArray.loc`` indexing with ``...`` (:issue:`318`). +- Fixed an edge case that resulting in an error when reindexing + multi-dimensional variables (:issue:`315`). +- Slicing with negative step sizes (:issue:`312`). +- Invalid conversion of string arrays to numeric dtype (:issue:`305`). +- Fixed``repr()`` on dataset objects with non-standard dates (:issue:`347`). + +Deprecations +~~~~~~~~~~~~ + +- ``dump`` and ``dumps`` have been deprecated in favor of + ``xray.Dataset.to_netcdf``. +- ``drop_vars`` has been deprecated in favor of ``xray.Dataset.drop``. + +Future plans +~~~~~~~~~~~~ + +The biggest feature I'm excited about working toward in the immediate future +is supporting out-of-core operations in xray using Dask_, a part of the Blaze_ +project. For a preview of using Dask with weather data, read +`this blog post`_ by Matthew Rocklin. See :issue:`328` for more details. + +.. _Dask: http://dask.pydata.org +.. _Blaze: http://blaze.pydata.org +.. _this blog post: http://matthewrocklin.com/blog/work/2015/02/13/Towards-OOC-Slicing-and-Stacking/ + +v0.3.2 (23 December, 2014) +-------------------------- + +This release focused on bug-fixes, speedups and resolving some niggling +inconsistencies. + +There are a few cases where the behavior of xray differs from the previous +version. However, I expect that in almost all cases your code will continue to +run unmodified. + +.. warning:: + + xray now requires pandas v0.15.0 or later. This was necessary for + supporting TimedeltaIndex without too many painful hacks. + +Backwards incompatible changes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Arrays of :py:class:`datetime.datetime` objects are now automatically cast to + ``datetime64[ns]`` arrays when stored in an xray object, using machinery + borrowed from pandas: + + .. ipython:: python + + from datetime import datetime + + xray.Dataset({"t": [datetime(2000, 1, 1)]}) + +- xray now has support (including serialization to netCDF) for + :py:class:`~pandas.TimedeltaIndex`. :py:class:`datetime.timedelta` objects + are thus accordingly cast to ``timedelta64[ns]`` objects when appropriate. +- Masked arrays are now properly coerced to use ``NaN`` as a sentinel value + (:issue:`259`). + +Enhancements +~~~~~~~~~~~~ + +- Due to popular demand, we have added experimental attribute style access as + a shortcut for dataset variables, coordinates and attributes: + + .. ipython:: python + + ds = xray.Dataset({"tmin": ([], 25, {"units": "celsius"})}) + ds.tmin.units + + Tab-completion for these variables should work in editors such as IPython. + However, setting variables or attributes in this fashion is not yet + supported because there are some unresolved ambiguities (:issue:`300`). +- You can now use a dictionary for indexing with labeled dimensions. This + provides a safe way to do assignment with labeled dimensions: + + .. ipython:: python + + array = xray.DataArray(np.zeros(5), dims=["x"]) + array[dict(x=slice(3))] = 1 + array + +- Non-index coordinates can now be faithfully written to and restored from + netCDF files. This is done according to CF conventions when possible by + using the ``coordinates`` attribute on a data variable. When not possible, + xray defines a global ``coordinates`` attribute. +- Preliminary support for converting ``xray.DataArray`` objects to and from + CDAT_ ``cdms2`` variables. +- We sped up any operation that involves creating a new Dataset or DataArray + (e.g., indexing, aggregation, arithmetic) by a factor of 30 to 50%. The full + speed up requires cyordereddict_ to be installed. + +.. _CDAT: http://uvcdat.llnl.gov/ +.. _cyordereddict: https://github.com/shoyer/cyordereddict + +Bug fixes +~~~~~~~~~ + +- Fix for ``to_dataframe()`` with 0d string/object coordinates (:issue:`287`) +- Fix for ``to_netcdf`` with 0d string variable (:issue:`284`) +- Fix writing datetime64 arrays to netcdf if NaT is present (:issue:`270`) +- Fix align silently upcasts data arrays when NaNs are inserted (:issue:`264`) + +Future plans +~~~~~~~~~~~~ + +- I am contemplating switching to the terms "coordinate variables" and "data + variables" instead of the (currently used) "coordinates" and "variables", + following their use in `CF Conventions`_ (:issue:`293`). This would mostly + have implications for the documentation, but I would also change the + ``Dataset`` attribute ``vars`` to ``data``. +- I no longer certain that automatic label alignment for arithmetic would be a + good idea for xray -- it is a feature from pandas that I have not missed + (:issue:`186`). +- The main API breakage that I *do* anticipate in the next release is finally + making all aggregation operations skip missing values by default + (:issue:`130`). I'm pretty sick of writing ``ds.reduce(np.nanmean, 'time')``. +- The next version of xray (0.4) will remove deprecated features and aliases + whose use currently raises a warning. + +If you have opinions about any of these anticipated changes, I would love to +hear them -- please add a note to any of the referenced GitHub issues. + +.. _CF Conventions: http://cfconventions.org/Data/cf-conventions/cf-conventions-1.6/build/cf-conventions.html + +v0.3.1 (22 October, 2014) +------------------------- + +This is mostly a bug-fix release to make xray compatible with the latest +release of pandas (v0.15). + +We added several features to better support working with missing values and +exporting xray objects to pandas. We also reorganized the internal API for +serializing and deserializing datasets, but this change should be almost +entirely transparent to users. + +Other than breaking the experimental DataStore API, there should be no +backwards incompatible changes. + +New features +~~~~~~~~~~~~ + +- Added ``xray.Dataset.count`` and ``xray.Dataset.dropna`` + methods, copied from pandas, for working with missing values (:issue:`247`, + :issue:`58`). +- Added ``xray.DataArray.to_pandas`` for + converting a data array into the pandas object with the same dimensionality + (1D to Series, 2D to DataFrame, etc.) (:issue:`255`). +- Support for reading gzipped netCDF3 files (:issue:`239`). +- Reduced memory usage when writing netCDF files (:issue:`251`). +- 'missing_value' is now supported as an alias for the '_FillValue' attribute + on netCDF variables (:issue:`245`). +- Trivial indexes, equivalent to ``range(n)`` where ``n`` is the length of the + dimension, are no longer written to disk (:issue:`245`). + +Bug fixes +~~~~~~~~~ + +- Compatibility fixes for pandas v0.15 (:issue:`262`). +- Fixes for display and indexing of ``NaT`` (not-a-time) (:issue:`238`, + :issue:`240`) +- Fix slicing by label was an argument is a data array (:issue:`250`). +- Test data is now shipped with the source distribution (:issue:`253`). +- Ensure order does not matter when doing arithmetic with scalar data arrays + (:issue:`254`). +- Order of dimensions preserved with ``DataArray.to_dataframe`` (:issue:`260`). + +v0.3 (21 September 2014) +------------------------ + +New features +~~~~~~~~~~~~ + +- **Revamped coordinates**: "coordinates" now refer to all arrays that are not + used to index a dimension. Coordinates are intended to allow for keeping track + of arrays of metadata that describe the grid on which the points in "variable" + arrays lie. They are preserved (when unambiguous) even though mathematical + operations. +- **Dataset math** ``xray.Dataset`` objects now support all arithmetic + operations directly. Dataset-array operations map across all dataset + variables; dataset-dataset operations act on each pair of variables with the + same name. +- **GroupBy math**: This provides a convenient shortcut for normalizing by the + average value of a group. +- The dataset ``__repr__`` method has been entirely overhauled; dataset + objects now show their values when printed. +- You can now index a dataset with a list of variables to return a new dataset: + ``ds[['foo', 'bar']]``. + +Backwards incompatible changes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- ``Dataset.__eq__`` and ``Dataset.__ne__`` are now element-wise operations + instead of comparing all values to obtain a single boolean. Use the method + ``xray.Dataset.equals`` instead. + +Deprecations +~~~~~~~~~~~~ + +- ``Dataset.noncoords`` is deprecated: use ``Dataset.vars`` instead. +- ``Dataset.select_vars`` deprecated: index a ``Dataset`` with a list of + variable names instead. +- ``DataArray.select_vars`` and ``DataArray.drop_vars`` deprecated: use + ``xray.DataArray.reset_coords`` instead. + +v0.2 (14 August 2014) +--------------------- + +This is major release that includes some new features and quite a few bug +fixes. Here are the highlights: + +- There is now a direct constructor for ``DataArray`` objects, which makes it + possible to create a DataArray without using a Dataset. This is highlighted + in the refreshed ``tutorial``. +- You can perform aggregation operations like ``mean`` directly on + ``xray.Dataset`` objects, thanks to Joe Hamman. These aggregation + methods also worked on grouped datasets. +- xray now works on Python 2.6, thanks to Anna Kuznetsova. +- A number of methods and attributes were given more sensible (usually shorter) + names: ``labeled`` -> ``sel``, ``indexed`` -> ``isel``, ``select`` -> + ``select_vars``, ``unselect`` -> ``drop_vars``, ``dimensions`` -> ``dims``, + ``coordinates`` -> ``coords``, ``attributes`` -> ``attrs``. +- New ``xray.Dataset.load_data`` and ``xray.Dataset.close`` + methods for datasets facilitate lower level of control of data loaded from + disk. + +v0.1.1 (20 May 2014) +-------------------- + +xray 0.1.1 is a bug-fix release that includes changes that should be almost +entirely backwards compatible with v0.1: + +- Python 3 support (:issue:`53`) +- Required numpy version relaxed to 1.7 (:issue:`129`) +- Return numpy.datetime64 arrays for non-standard calendars (:issue:`126`) +- Support for opening datasets associated with NetCDF4 groups (:issue:`127`) +- Bug-fixes for concatenating datetime arrays (:issue:`134`) + +Special thanks to new contributors Thomas Kluyver, Joe Hamman and Alistair +Miles. + +v0.1 (2 May 2014) +----------------- + +Initial release. From 753c6d4b87314962803f671f1b17e804d3c1e09d Mon Sep 17 00:00:00 2001 From: Ray Bell Date: Fri, 6 Aug 2021 14:41:47 -0400 Subject: [PATCH 06/11] move import fsspec lower --- xarray/backends/api.py | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/xarray/backends/api.py b/xarray/backends/api.py index be0c03d0b21..30db8e96544 100644 --- a/xarray/backends/api.py +++ b/xarray/backends/api.py @@ -38,10 +38,6 @@ from dask.delayed import Delayed except ImportError: Delayed = None - try: - from fsspec import get_mapper - except ImportError: - get_mapper = None DATAARRAY_NAME = "__xarray_dataarray_name__" @@ -1339,8 +1335,12 @@ def to_zarr( mapper = store chunk_mapper = chunk_store else: + try: + from fsspec import get_mapper + except ModuleNotFoundError: + raise ModuleNotFoundError("fsspec is required for storage_options arg") mapper = get_mapper(store, **storage_options) - chunk_mapper = get_mapper(store, **storage_options) + chunk_mapper = get_mapper(chunk_store, **storage_options) if encoding is None: encoding = {} From e0ba649b1e577d37ae7aacc379a19cb6ae50ee89 Mon Sep 17 00:00:00 2001 From: Ray Bell Date: Fri, 6 Aug 2021 15:14:07 -0400 Subject: [PATCH 07/11] fsspec in to_zarr --- xarray/backends/api.py | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/xarray/backends/api.py b/xarray/backends/api.py index 30db8e96544..1fb1caab138 100644 --- a/xarray/backends/api.py +++ b/xarray/backends/api.py @@ -1335,10 +1335,8 @@ def to_zarr( mapper = store chunk_mapper = chunk_store else: - try: - from fsspec import get_mapper - except ModuleNotFoundError: - raise ModuleNotFoundError("fsspec is required for storage_options arg") + from fsspec import get_mapper + mapper = get_mapper(store, **storage_options) chunk_mapper = get_mapper(chunk_store, **storage_options) From 67ccce2f9b31eebf38fffb5dc86b90810299111c Mon Sep 17 00:00:00 2001 From: Ray Bell Date: Fri, 13 Aug 2021 16:04:42 -0400 Subject: [PATCH 08/11] add a test. Co-authored-by: Zachary Blackwood Co-authored-by: Nathan Lis --- xarray/backends/api.py | 9 ++++++++- xarray/backends/zarr.py | 3 +++ xarray/tests/test_backends.py | 9 +++++++++ 3 files changed, 20 insertions(+), 1 deletion(-) diff --git a/xarray/backends/api.py b/xarray/backends/api.py index 1fb1caab138..56b8d15a173 100644 --- a/xarray/backends/api.py +++ b/xarray/backends/api.py @@ -1337,8 +1337,15 @@ def to_zarr( else: from fsspec import get_mapper + if not isinstance(store, str): + raise ValueError( + f"store must be a string to use storage_options. Got {type(store)}" + ) mapper = get_mapper(store, **storage_options) - chunk_mapper = get_mapper(chunk_store, **storage_options) + if chunk_store is not None: + chunk_mapper = get_mapper(chunk_store, **storage_options) + else: + chunk_mapper = chunk_store if encoding is None: encoding = {} diff --git a/xarray/backends/zarr.py b/xarray/backends/zarr.py index aec12d2b154..12499103fb9 100644 --- a/xarray/backends/zarr.py +++ b/xarray/backends/zarr.py @@ -713,6 +713,9 @@ def open_zarr( falling back to read non-consolidated metadata if that fails. chunk_store : MutableMapping, optional A separate Zarr store only for chunk data. + storage_options : dict, optional + Any additional parameters for the storage backend (ignored for local + paths). decode_timedelta : bool, optional If True, decode variables and coordinates with time units in {'days', 'hours', 'minutes', 'seconds', 'milliseconds', 'microseconds'} diff --git a/xarray/tests/test_backends.py b/xarray/tests/test_backends.py index ed4b80587e5..ba5811ad6fc 100644 --- a/xarray/tests/test_backends.py +++ b/xarray/tests/test_backends.py @@ -2388,6 +2388,15 @@ def create_zarr_target(self): yield tmp +@requires_fsspec +def test_zarr_storage_options(): + ds = create_test_data() + store_target = "memory://test.zarr" + ds.to_zarr(store_target, storage_options={"test": "zarr_write"}) + ds_a = xr.open_zarr(store_target, storage_options={"test": "zarr_read"}) + assert_identical(ds, ds_a) + + @requires_scipy class TestScipyInMemoryData(CFEncodedBase, NetCDF3Only): engine = "scipy" From 1584c89af259d3c9d8387fce68478724efbd1cc1 Mon Sep 17 00:00:00 2001 From: Ray Bell Date: Fri, 13 Aug 2021 22:17:43 -0400 Subject: [PATCH 09/11] add requires_zarr_2_5_0 --- xarray/tests/__init__.py | 1 + xarray/tests/test_backends.py | 3 +++ 2 files changed, 4 insertions(+) diff --git a/xarray/tests/__init__.py b/xarray/tests/__init__.py index d757fb451cc..f610941914b 100644 --- a/xarray/tests/__init__.py +++ b/xarray/tests/__init__.py @@ -77,6 +77,7 @@ def LooseVersion(vstring): has_nc_time_axis, requires_nc_time_axis = _importorskip("nc_time_axis") has_rasterio, requires_rasterio = _importorskip("rasterio") has_zarr, requires_zarr = _importorskip("zarr") +has_zarr_2_5_0, requires_zarr_2_5_0 = _importorskip("zarr", minversion="2.5.0") has_fsspec, requires_fsspec = _importorskip("fsspec") has_iris, requires_iris = _importorskip("iris") has_cfgrib, requires_cfgrib = _importorskip("cfgrib") diff --git a/xarray/tests/test_backends.py b/xarray/tests/test_backends.py index ba5811ad6fc..a78ca7d3607 100644 --- a/xarray/tests/test_backends.py +++ b/xarray/tests/test_backends.py @@ -71,6 +71,7 @@ requires_scipy, requires_scipy_or_netCDF4, requires_zarr, + requires_zarr_2_5_0, ) from .test_coding_times import ( _ALL_CALENDARS, @@ -2389,7 +2390,9 @@ def create_zarr_target(self): @requires_fsspec +@requires_zarr_2_5_0 def test_zarr_storage_options(): + pytest.importorskip("aiobotocore") ds = create_test_data() store_target = "memory://test.zarr" ds.to_zarr(store_target, storage_options={"test": "zarr_write"}) From 53bdec2874a9a799ab8b75312a1878984d82dfda Mon Sep 17 00:00:00 2001 From: Ray Bell Date: Fri, 20 Aug 2021 14:23:12 -0400 Subject: [PATCH 10/11] add what's new --- doc/whats-new.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/doc/whats-new.rst b/doc/whats-new.rst index 4f79a37eb4b..4059b5a1ae3 100644 --- a/doc/whats-new.rst +++ b/doc/whats-new.rst @@ -28,6 +28,9 @@ New Features By `Justus Magin `_. - Added ``**kwargs`` argument to :py:meth:`open_rasterio` to access overviews (:issue:`3269`). By `Pushkar Kopparla `_. +- Added ``storage_options`` argument to :py:meth:`to_zarr` (:issue:`5601`). + By `Ray Bell `_, `Zachary Blackwood `_ and + `Nathan Lis `_. Breaking changes From 9194359ba0dadb89c9b43819575dcf832ff04fcc Mon Sep 17 00:00:00 2001 From: Ray Bell Date: Fri, 20 Aug 2021 14:28:38 -0400 Subject: [PATCH 11/11] add storage options arg to end --- xarray/backends/api.py | 2 +- xarray/core/dataset.py | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/xarray/backends/api.py b/xarray/backends/api.py index 56b8d15a173..2c9b25f860f 100644 --- a/xarray/backends/api.py +++ b/xarray/backends/api.py @@ -1310,7 +1310,6 @@ def to_zarr( dataset: Dataset, store: Union[MutableMapping, str, Path] = None, chunk_store=None, - storage_options: Dict[str, str] = None, mode: str = None, synchronizer=None, group: str = None, @@ -1320,6 +1319,7 @@ def to_zarr( append_dim: Hashable = None, region: Mapping[str, slice] = None, safe_chunks: bool = True, + storage_options: Dict[str, str] = None, ): """This function creates an appropriate datastore for writing a dataset to a zarr ztore diff --git a/xarray/core/dataset.py b/xarray/core/dataset.py index 7601fdfdc89..a5eaa82cfdd 100644 --- a/xarray/core/dataset.py +++ b/xarray/core/dataset.py @@ -1913,7 +1913,6 @@ def to_zarr( self, store: Union[MutableMapping, str, Path] = None, chunk_store: Union[MutableMapping, str, Path] = None, - storage_options: Dict[str, str] = None, mode: str = None, synchronizer=None, group: str = None, @@ -1923,6 +1922,7 @@ def to_zarr( append_dim: Hashable = None, region: Mapping[str, slice] = None, safe_chunks: bool = True, + storage_options: Dict[str, str] = None, ) -> "ZarrStore": """Write dataset contents to a zarr group. @@ -1946,9 +1946,6 @@ def to_zarr( chunk_store : MutableMapping, str or Path, optional Store or path to directory in local or remote file system only for Zarr array chunks. Requires zarr-python v2.4.0 or later. - storage_options : dict, optional - Any additional parameters for the storage backend (ignored for local - paths). mode : {"w", "w-", "a", "r+", None}, optional Persistence mode: "w" means create (overwrite if exists); "w-" means create (fail if exists); @@ -2003,6 +2000,9 @@ def to_zarr( if Zarr arrays are written in parallel. This option may be useful in combination with ``compute=False`` to initialize a Zarr from an existing Dataset with aribtrary chunk structure. + storage_options : dict, optional + Any additional parameters for the storage backend (ignored for local + paths). References ----------