Skip to content

Latest commit

 

History

History
4596 lines (3734 loc) · 200 KB

whats-new.rst

File metadata and controls

4596 lines (3734 loc) · 200 KB
.. 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)

v0.16.0 (unreleased)

Breaking changes

Enhancements

New Features

Bug fixes

Documentation

Internal Changes

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

New Features

Bug fixes

Documentation

Internal Changes

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

New Features

Bug fixes

Documentation

Internal Changes

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

Bug fixes

Documentation

Internal Changes

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

Enhancements

Bug fixes

Documentation

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

Enhancements

Bug fixes

Documentation

v0.12.3 (10 July 2019)

New functions/methods

Enhancements

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.

v0.12.2 (29 June 2019)

New functions/methods

Enhancements to existing functionality

IO related enhancements

Bug fixes

v0.12.1 (4 April 2019)

Enhancements

Bug fixes

v0.12.0 (15 March 2019)

Highlights include:

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

Other enhancements

Bug fixes

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.

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:

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

Bug fixes

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

  • 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:

Enhancements

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.

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

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.

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

Bug fixes

v0.10.7 (7 June 2018)

Enhancements

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.

v0.10.6 (31 May 2018)

The minor release includes a number of bug-fixes and backwards compatible enhancements.

Enhancements

Bug fixes

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

Enhancements

Bug fixes

v0.10.3 (13 April 2018)

The minor release includes a number of bug-fixes and backwards compatible enhancements.

Enhancements

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.

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).

Enhancements

Bug fixes

v0.10.1 (25 February 2018)

The minor release includes a number of bug-fixes and backwards compatible enhancements.

Documentation

Enhancements

New functions and methods:

Plotting enhancements:

Other enhancements:

New functions/methods

Bug fixes

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:

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 <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]:
  <xarray.Dataset>
  [...]

    New syntax:

    .. ipython::
  :verbatim:

  In [1]: ds.resample(time="24H").max()
  Out[1]:
  <xarray.Dataset>
  [...]

    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:

Enhancements

New functions/methods

Performance improvements

IO related improvements

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

Bug fixes after rc1

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.

v0.9.6 (8 June 2017)

This release includes a number of backwards compatible enhancements and bug fixes.

Enhancements

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

Testing

v0.9.5 (17 April, 2017)

Remove an inadvertently introduced print statement.

v0.9.3 (16 April, 2017)

This minor release includes bug-fixes and backwards compatible enhancements.

Enhancements

Bug fixes

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

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`).

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:

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]:
  <xarray.Dataset>
  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

Bug fixes

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.

v0.8.2 (18 August 2016)

This release includes a number of bug fixes and minor enhancements.

Breaking changes

Enhancements

Bug fixes

v0.8.1 (5 August 2016)

Bug fixes

v0.8.0 (2 August 2016)

This release includes four months of new features and bug fixes, including several breaking changes.

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

Bug fixes

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]:
  <xarray.DataArray (x: 3, y: 5)>
  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]:
  <xarray.DataArray (x: 3, y: 5)>
  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.

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

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

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:

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.

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]:
  <xray.DataArray 'x' (x: 3)>
  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]:
  <xray.DataArray 'x' (x: 3)>
  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.

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]:
  <xray.DataArray 'foo' (z: 3)>
  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]:
  <xray.DataArray 'foo' (x: 2, y: 2)>
  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]:
  <xray.DataArray 'foo' (z: 4)>
  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

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]:
  <xray.DataArray (x: 2)>
  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]:
  <xray.DataArray (x: 7, y: 8)>
  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]:
  <xray.DataArray (points: 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]:
  <xray.DataArray (points: 3)>
  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.

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

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]:
  <xray.Dataset>
  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 <pandas.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:

    .. ipython::
    :verbatim:

    In [12]: ds.sel(x=1.1, method="nearest")
    Out[12]:
    <xray.Dataset>
    Dimensions:  ()
    Coordinates:
        x        int64 1
    Data variables:
        y        int64 2

    In [13]: ds.sel(x=[1.1, 2.1], method="pad")
    Out[13]:
    <xray.Dataset>
    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.

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.

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<math automatic alignment>`, 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<merge>`, we align based on the union of labels:

    .. ipython:: python

    xray.Dataset({"foo": lhs, "bar": rhs})

    :ref:`For update and __setitem__<update>`, 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.

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.

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.

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.

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:

Special thanks to new contributors Thomas Kluyver, Joe Hamman and Alistair Miles.

v0.1 (2 May 2014)

Initial release.