N-D labeled arrays and datasets in Python¶

Breaking changes¶

• Dropped support for Python 2.6 (GH855).
• 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 (GH802).
• Contour plots no longer add a colorbar per default (GH866). 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 (GH867). 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 groupby_bins() has also been added to allow users to specify bins for grouping. The new features are described in Multidimensional Grouping and Working with Multidimensional Coordinates. By Ryan Abernathey.
• DataArray and Dataset method where() now supports a drop=True option that clips coordinate elements that are fully masked. By Phillip J. Wolfram.
• New top level merge() function allows for combining variables from any number of Dataset and/or DataArray variables. See Merge for more details. By Stephan Hoyer.
• DataArray and Dataset method resample() now supports 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 DataArray and Dataset sel() and loc() methods, which now behave more closely to pandas and which also accept dictionaries for indexing based on given level names and labels (see Multi-level indexing). By Benoit Bovy.
• New (experimental) decorators register_dataset_accessor() and register_dataarray_accessor() for registering custom xarray extensions without subclassing. They are described in the new documentation page on xarray 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 (GH872). By Fabien Maussion.
• New Dataset method 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 (GH875). By Stephan Hoyer.

• Fixed bug in arithmetic operations on DataArray objects whose dimensions are numpy structured arrays or recarrays GH861, GH837. Maciek Swat.

• decode_cf_timedelta now accepts arrays with ndim >1 (GH842).

  This fixes issue GH665. Filipe Fernandes.

• Fix a bug where xarray.ufuncs that take two arguments would incorrectly use to numpy functions instead of dask.array functions (GH876). By Stephan Hoyer.

• Support for pickling functions from xarray.ufuncs (GH901). By Stephan Hoyer.

• Variable.copy(deep=True) no longer converts MultiIndex into a base Index (GH769). By Benoit Bovy.

• Fixes for groupby on dimensions with a multi-index (GH867). By Stephan Hoyer.

• Fix printing datasets with unicode attributes on Python 2 (GH892). By Stephan Hoyer.

• Fixed incorrect test for dask version (GH891). By Stephan Hoyer.

• Fixed dim argument for isel_points/sel_points when a pandas.Index is passed. By Stephan Hoyer.

• contour() now plots the correct number of contours (GH866). By Fabien Maussion.

Enhancements¶

• New DataArray method 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 DataArray.rolling() method. For example:

  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 Rolling window operations 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 (GH781). By Joe Hamman.
• 2D plots now better handle additional coordinates which are not DataArray dimensions (GH788). By Fabien Maussion.

Enhancements¶

• Numerical operations now return empty objects on no overlapping labels rather than raising ValueError (GH739).
• Series is now supported as valid input to the Dataset constructor (GH740).

Bug fixes¶

• Restore checks for shape consistency between data and coordinates in the DataArray constructor (GH758).
• Single dimension variables no longer transpose as part of a broader .transpose. This behavior was causing pandas.PeriodIndex dimensions to lose their type (GH749)
• Dataset labels remain as their native type on .to_dataset. Previously they were coerced to strings (GH745)
• Fixed a bug where replacing a DataArray index coordinate would improperly align the coordinate (GH725).
• DataArray.reindex_like now maintains the dtype of complex numbers when reindexing leads to NaN values (GH738).
• Dataset.rename and DataArray.rename support the old and new names being the same (GH724).
• Fix from_dataset() for DataFrames with Categorical column and a MultiIndex index (GH737).
• 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

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.

Breaking changes¶

• The internal data model used by DataArray has been rewritten to fix several outstanding issues (GH367, GH634, 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:

  In [5]: xray.DataArray([4, 5, 6], dims='x', name='x')
  Out[5]: 
  <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):

  In [6]: xray.DataArray([4, 5, 6], dims='x', name='x')
  Out[6]: 
  <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 MultiIndex coordinates on xray objects, including indexing, stack() and unstack():

  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 [9]: arr = xray.DataArray(s, dims='z')
  
  In [10]: arr
  Out[10]: 
  <xray.DataArray 'foo' (z: 3)>
  array([0, 1, 2])
  Coordinates:
    * z        (z) object ('a', 0) ('b', 0) ('b', 1)
  
  In [11]: arr.indexes['z']
  Out[11]: 
  MultiIndex(levels=[[u'a', u'b'], [0, 1]],
             labels=[[0, 1, 1], [0, 0, 1]],
             names=[u'x', u'y'])
  
  In [12]: arr.unstack('z')
  Out[12]: 
  <xray.DataArray 'foo' (x: 2, y: 2)>
  array([[  0.,  nan],
         [  1.,   2.]])
  Coordinates:
    * x        (x) object 'a' 'b'
    * y        (y) int64 0 1
  
  In [13]: arr.unstack('z').stack(z=('x', 'y'))
  Out[13]: 
  <xray.DataArray 'foo' (z: 4)>
  array([  0.,  nan,   1.,   2.])
  Coordinates:
    * z        (z) object ('a', 0) ('a', 1) ('b', 0) ('b', 1)
  

  See Stack and unstack for more details.

  Warning

  xray’s MultiIndex support is still experimental, and we have a long to- do list of desired additions (GH719), 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 Formats supported by 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 (GH642). vmin and vmax will not be silently ignored anymore. Setting center=False prevents automatic selection of a divergent colormap.

• New shift() and roll() methods for shifting/rotating datasets or arrays along a dimension:

  In [14]: array = xray.DataArray([5, 6, 7, 8], dims='x')
  
  In [15]: array.shift(x=2)
  Out[15]: 
  <xarray.DataArray (x: 4)>
  array([ nan,  nan,   5.,   6.])
  Coordinates:
    * x        (x) int64 0 1 2 3
  
  In [16]: array.roll(x=2)
  Out[16]: 
  <xarray.DataArray (x: 4)>
  array([7, 8, 5, 6])
  Coordinates:
    * x        (x) int64 2 3 0 1
  

  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 pandas.DataFrame or pandas.Panel to a Dataset constructor is now permitted.

• New function broadcast() for explicitly broadcasting DataArray and Dataset objects against each other. For example:

  In [17]: a = xray.DataArray([1, 2, 3], dims='x')
  
  In [18]: b = xray.DataArray([5, 6], dims='y')
  
  In [19]: a
  Out[19]: 
  <xarray.DataArray (x: 3)>
  array([1, 2, 3])
  Coordinates:
    * x        (x) int64 0 1 2
  
  In [20]: b
  Out[20]: 
  <xarray.DataArray (y: 2)>
  array([5, 6])
  Coordinates:
    * y        (y) int64 0 1
  
  In [21]: a2, b2 = xray.broadcast(a, b)
  
  In [22]: a2
  Out[22]: 
  <xarray.DataArray (x: 3, y: 2)>
  array([[1, 1],
         [2, 2],
         [3, 3]])
  Coordinates:
    * x        (x) int64 0 1 2
    * y        (y) int64 0 1
  
  In [23]: b2
  Out[23]: 
  <xarray.DataArray (x: 3, y: 2)>
  array([[5, 6],
         [5, 6],
         [5, 6]])
  Coordinates:
    * y        (y) int64 0 1
    * x        (x) int64 0 1 2
  

Bug fixes¶

• Fixes for several issues found on DataArray objects with the same name as one of their coordinates (see Breaking changes for more details).
• DataArray.to_masked_array always returns masked array with mask being an array (not a scalar value) (GH684)
• Allows for (imperfect) repr of Coords when underlying index is PeriodIndex (GH645).
• Fixes for several issues found on DataArray objects with the same name as one of their coordinates (see Breaking changes 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 (GH656, GH714).
• You can now pass pandas objects with non-numpy dtypes (e.g., categorical or datetime64 with a timezone) into xray without an error (GH716).

Acknowledgments¶

The following individuals contributed to this release:

• Antony Lee
• Fabien Maussion
• Joe Hamman
• Maximilian Roos
• Stephan Hoyer
• Takeshi Kanmae
• femtotrader

API Changes¶

• The handling of colormaps and discrete color lists for 2D plots in plot() was changed to provide more compatibility with matplotlib’s contour and contourf functions (GH538). Now discrete lists of colors should be specified using colors keyword, rather than cmap.

Enhancements¶

• Faceted plotting through FacetGrid and the plot() method. See Faceting for more details and examples.

• sel() and reindex() now support the tolerance argument for controlling nearest-neighbor selection (GH629):

  In [24]: array = xray.DataArray([1, 2, 3], dims='x')
  
  In [25]: array.reindex(x=[0.9, 1.5], method='nearest', tolerance=0.2)
  Out[25]: 
  <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 to_netcdf() for writing netCDF files with compression, as described in the new documentation section on Writing encoded data.

• Add real and imag attributes to Dataset and DataArray (GH553).

• More informative error message with 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 GH555 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 (GH569).
• Aggregation functions now correctly skip NaN for data for complex128 dtype (GH554).
• Fixed indexing 0d arrays with unicode dtype (GH568).
• name() and Dataset keys must be a string or None to be written to netCDF (GH533).
• 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' (GH574).
• It is now possible to assign to the .data attribute of DataArray objects.
• coordinates attribute is now kept in the encoding dictionary after decoding (GH610).
• Compatibility with numpy 1.10 (GH617).

Acknowledgments¶

The following individuals contributed to this release:

• Ryan Abernathey
• Pete Cable
• Clark Fitzgerald
• Joe Hamman
• Stephan Hoyer
• Scott Sinclair

Enhancements¶

• Plotting methods have been implemented on DataArray objects plot() through integration with matplotlib (GH185). For an introduction, see 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 Copies vs. views for more details).

• Dataset variables are now written to netCDF files in order of appearance when using the netcdf4 backend (GH479).

• Added isel_points() and sel_points() to support pointwise indexing of Datasets and DataArrays (GH475).

  In [26]: da = xray.DataArray(np.arange(56).reshape((7, 8)),
     ....:                     coords={'x': list('abcdefg'),
     ....:                             'y': 10 * np.arange(8)},
     ....:                     dims=['x', 'y'])
     ....: 
  
  In [27]: da
  Out[27]: 
  <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 [28]: da.isel_points(x=[0, 1, 6], y=[0, 1, 0], dim='points')
  Out[28]: 
  <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 [29]: da.sel_points(x=['a', 'b', 'g'], y=[0, 10, 0], dim='points')
  Out[29]: 
  <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 where() method for masking xray objects according to some criteria. This works particularly well with multi-dimensional data:

  In [30]: ds = xray.Dataset(coords={'x': range(100), 'y': range(100)})
  
  In [31]: ds['distance'] = np.sqrt(ds.x ** 2 + ds.y ** 2)
  
  In [32]: ds.distance.where(ds.distance < 100).plot()
  Out[32]: <matplotlib.collections.QuadMesh at 0x7f23b4eac950>
  

  

• Added new methods DataArray.diff and Dataset.diff for finite difference calculations along a given axis.

• New to_masked_array() convenience method for returning a numpy.ma.MaskedArray.

  In [33]: da = xray.DataArray(np.random.random_sample(size=(5, 4)))
  
  In [34]: da.where(da < 0.5)
  Out[34]: 
  <xarray.DataArray (dim_0: 5, dim_1: 4)>
  array([[ 0.127,    nan,  0.26 ,    nan],
         [ 0.377,  0.336,  0.451,    nan],
         [ 0.123,    nan,  0.373,  0.448],
         [ 0.129,    nan,    nan,  0.352],
         [ 0.229,    nan,    nan,  0.138]])
  Coordinates:
    * dim_0    (dim_0) int64 0 1 2 3 4
    * dim_1    (dim_1) int64 0 1 2 3
  
  In [35]: da.where(da < 0.5).to_masked_array(copy=True)
  Out[35]: 
  masked_array(data =
   [[0.12696983303810094 -- 0.26047600586578334 --]
   [0.37674971618967135 0.33622174433445307 0.45137647047539964 --]
   [0.12310214428849964 -- 0.37301222522143085 0.4479968246859435]
   [0.12944067971751294 -- -- 0.35205353914802473]
   [0.2288873043216132 -- -- 0.1375535565632705]],
               mask =
   [[False  True False  True]
   [False False False  True]
   [False  True False False]
   [False  True  True False]
   [False  True  True False]],
         fill_value = 1e+20)
  

• Added new flag “drop_variables” to 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 (GH489).
• Dataset aggregation functions dropped variables with unsigned integer dtype (GH505).
• .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 (GH528).
• Fix pickle on DataArray objects (GH515).
• Fixed unnecessary coercion of float64 to float32 when using netcdf3 and netcdf4_classic formats (GH526).

Backwards incompatible changes¶

• The optional arguments concat_over and mode in 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¶

• 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 (GH443).

• open_dataset() and 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 (GH444).

• Added support for serializing arrays of complex numbers with engine=’h5netcdf’.

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

  In [36]: years, datasets = zip(*ds.groupby('time.year'))
  
  In [37]: paths = ['%s.nc' % y for y in years]
  
  In [38]: xray.save_mfdataset(datasets, paths)
  

Bug fixes¶

• Fixed min, max, argmin and argmax for arrays with string or unicode types (GH453).
• open_dataset() and 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 (GH464).
• When reading datasets with h5netcdf, bytes attributes are decoded to strings. This allows conventions decoding to work properly on Python 3 (GH451).

Enhancements¶

• Added pipe(), replicating the new pandas method in version 0.16.2. See Transforming datasets for more details.
• assign() and 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 (GH425)
• We now decode variables loaded from netCDF3 files with the scipy engine using native endianness (GH416). This resolves an issue when aggregating these arrays with bottleneck installed.

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 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 Out of core computation with 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 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 (GH268). For example:

  In [39]: ds = xray.Dataset({'x': 0})
  
  In [40]: xray.concat([ds, ds], dim='y')
  Out[40]: 
  <xray.Dataset>
  Dimensions:  ()
  Coordinates:
      *empty*
  Data variables:
      x        int64 0
  

  Now, the default always concatenates data variables:

  In [41]: xray.concat([ds, ds], dim='y')
  Out[41]: 
  <xarray.Dataset>
  Dimensions:  (y: 2)
  Coordinates:
    * y        (y) int64 0 1
  Data variables:
      x        (y) int64 0 0
  

  To obtain the old behavior, supply the argument concat_over=[].

Enhancements¶

• New to_array() and enhanced to_dataset() methods make it easy to switch back and forth between arrays and datasets:

  In [42]: ds = xray.Dataset({'a': 1, 'b': ('x', [1, 2, 3])},
     ....:                   coords={'c': 42}, attrs={'Conventions': 'None'})
     ....: 
  
  In [43]: ds.to_array()
  Out[43]: 
  <xarray.DataArray (variable: 2, x: 3)>
  array([[1, 1, 1],
         [1, 2, 3]])
  Coordinates:
    * variable  (variable) |S1 'a' 'b'
    * x         (x) int64 0 1 2
      c         int64 42
  Attributes:
      Conventions: None
  
  In [44]: ds.to_array().to_dataset(dim='variable')
  Out[44]: 
  <xarray.Dataset>
  Dimensions:  (x: 3)
  Coordinates:
    * x        (x) int64 0 1 2
      c        int64 42
  Data variables:
      a        (x) int64 1 1 1
      b        (x) int64 1 2 3
  Attributes:
      Conventions: None
  

• New fillna() method to fill missing values, modeled off the pandas method of the same name:

  In [45]: array = xray.DataArray([np.nan, 1, np.nan, 3], dims='x')
  
  In [46]: array.fillna(0)
  Out[46]: 
  <xarray.DataArray (x: 4)>
  array([ 0.,  1.,  0.,  3.])
  Coordinates:
    * x        (x) int64 0 1 2 3
  

  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 Fill missing values with climatology.

• New assign() and assign_coords() methods patterned off the new DataFrame.assign method in pandas:

  In [47]: ds = xray.Dataset({'y': ('x', [1, 2, 3])})
  
  In [48]: ds.assign(z = lambda ds: ds.y ** 2)
  Out[48]: 
  <xarray.Dataset>
  Dimensions:  (x: 3)
  Coordinates:
    * x        (x) int64 0 1 2
  Data variables:
      y        (x) int64 1 2 3
      z        (x) int64 1 4 9
  
  In [49]: ds.assign_coords(z = ('x', ['a', 'b', 'c']))
  Out[49]: 
  <xarray.Dataset>
  Dimensions:  (x: 3)
  Coordinates:
    * x        (x) int64 0 1 2
      z        (x) |S1 'a' 'b' 'c'
  Data variables:
      y        (x) int64 1 2 3
  

  These methods return a new Dataset (or DataArray) with updated data or coordinate variables.

• sel() now supports the method parameter, which works like the paramter of the same name on reindex(). It provides a simple interface for doing nearest-neighbor interpolation:

  In [50]: ds.sel(x=1.1, method='nearest')
  Out[50]: 
  <xray.Dataset>
  Dimensions:  ()
  Coordinates:
      x        int64 1
  Data variables:
      y        int64 2
  
  In [51]: ds.sel(x=[1.1, 2.1], method='pad')
  Out[51]: 
  <xray.Dataset>
  Dimensions:  (x: 2)
  Coordinates:
    * x        (x) int64 1 2
  Data variables:
      y        (x) int64 2 3
  

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

  In [52]: ds = xray.Dataset({'x': np.arange(1000)})
  
  In [53]: with xray.set_options(display_width=40):
     ....:     print(ds)
     ....: 
  <xarray.Dataset>
  Dimensions:  (x: 1000)
  Coordinates:
    * x        (x) int64 0 1 2 3 4 5 6 ...
  Data variables:
      *empty*
  

  Or to set a global option:

  In [54]: 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 load().

Enhancements¶

• New documentation sections on Time series data and Combining multiple files.

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

  In [55]: time = pd.date_range('2000-01-01', freq='6H', periods=10)
  
  In [56]: array = xray.DataArray(np.arange(10), [('time', time)])
  
  In [57]: array.resample('1D', dim='time')
  Out[57]: 
  <xarray.DataArray (time: 3)>
  array([ 1.5,  5.5,  8.5])
  Coordinates:
    * time     (time) datetime64[ns] 2000-01-01 2000-01-02 2000-01-03
  

  You can specify how to do the resampling with the how argument and other options such as closed and label let you control labeling:

  In [58]: array.resample('1D', dim='time', how='sum', label='right')
  Out[58]: 
  <xarray.DataArray (time: 3)>
  array([ 6, 22, 17])
  Coordinates:
    * time     (time) datetime64[ns] 2000-01-02 2000-01-03 2000-01-04
  

  If the desired temporal resolution is higher than the original data (upsampling), xray will insert missing values:

  In [59]: array.resample('3H', 'time')
  Out[59]: 
  <xarray.DataArray (time: 19)>
  array([  0.,  nan,   1., ...,   8.,  nan,   9.])
  Coordinates:
    * time     (time) datetime64[ns] 2000-01-01 2000-01-01T03:00:00 ...
  

• first and last methods on groupby objects let you take the first or last examples from each group along the grouped axis:

  In [60]: array.groupby('time.day').first()
  Out[60]: 
  <xarray.DataArray (day: 3)>
  array([0, 4, 8])
  Coordinates:
    * day      (day) int64 1 2 3
  

  These methods combine well with resample:

  In [61]: array.resample('1D', dim='time', how='first')
  Out[61]: 
  <xarray.DataArray (time: 3)>
  array([0, 4, 8])
  Coordinates:
    * time     (time) datetime64[ns] 2000-01-01 2000-01-02 2000-01-03
  

• swap_dims() allows for easily swapping one dimension out for another:

  In [62]: ds = xray.Dataset({'x': range(3), 'y': ('x', list('abc'))})
  
  In [63]: ds
  Out[63]: 
  <xarray.Dataset>
  Dimensions:  (x: 3)
  Coordinates:
    * x        (x) int64 0 1 2
  Data variables:
      y        (x) |S1 'a' 'b' 'c'
  
  In [64]: ds.swap_dims({'x': 'y'})
  Out[64]: 
  <xarray.Dataset>
  Dimensions:  (y: 3)
  Coordinates:
    * y        (y) |S1 'a' 'b' 'c'
      x        (y) int64 0 1 2
  Data variables:
      *empty*
  

  This was possible in earlier versions of xray, but required some contortions.

• open_dataset() and 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 (GH341). 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 (GH344).
• 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 (GH360).
• Fixed a regression in v0.4 where saving to netCDF could fail with the error ValueError: could not automatically determine time units.

Breaking changes¶

• We now automatically align index labels in arithmetic, dataset construction, merging and updating. This means the need for manually invoking methods like align() and reindex_like() should be vastly reduced.

  For arithmetic, we align based on the intersection of labels:

  In [65]: lhs = xray.DataArray([1, 2, 3], [('x', [0, 1, 2])])
  
  In [66]: rhs = xray.DataArray([2, 3, 4], [('x', [1, 2, 3])])
  
  In [67]: lhs + rhs
  Out[67]: 
  <xarray.DataArray (x: 2)>
  array([4, 6])
  Coordinates:
    * x        (x) int64 1 2
  

  For dataset construction and merging, we align based on the union of labels:

  In [68]: xray.Dataset({'foo': lhs, 'bar': rhs})
  Out[68]: 
  <xarray.Dataset>
  Dimensions:  (x: 4)
  Coordinates:
    * x        (x) int64 0 1 2 3
  Data variables:
      foo      (x) float64 1.0 2.0 3.0 nan
      bar      (x) float64 nan 2.0 3.0 4.0
  

  For update and __setitem__, we align based on the original object:

  In [69]: lhs.coords['rhs'] = rhs
  
  In [70]: lhs
  Out[70]: 
  <xarray.DataArray (x: 3)>
  array([1, 2, 3])
  Coordinates:
    * x        (x) int64 0 1 2
      rhs      (x) float64 nan 2.0 3.0
  

• Aggregations like mean or median now skip missing values by default:

  In [71]: xray.DataArray([1, 2, np.nan, 3]).mean()
  Out[71]: 
  <xarray.DataArray ()>
  array(2.0)
  

  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 (GH243). For example, the coordinate c here persists through arithmetic, even though it has different shapes on each DataArray:

  In [72]: a = xray.DataArray([1, 2], coords={'c': 0}, dims='x')
  
  In [73]: b = xray.DataArray([1, 2], coords={'c': ('x', [0, 0])}, dims='x')
  
  In [74]: (a + b).coords
  Out[74]: 
  Coordinates:
      c        (x) int64 0 0
    * x        (x) int64 0 1
  

  This functionality can be controlled through the compat option, which has also been added to the Dataset constructor.

• Datetime shortcuts such as 'time.month' now return a DataArray with the name 'month', not 'time.month' (GH345). This makes it easier to index the resulting arrays when they are used with groupby:

  In [75]: time = xray.DataArray(pd.date_range('2000-01-01', periods=365),
     ....:                       dims='time', name='time')
     ....: 
  
  In [76]: counts = time.groupby('time.month').count()
  
  In [77]: counts.sel(month=2)
  Out[77]: 
  <xarray.DataArray 'time' ()>
  array(29)
  Coordinates:
      month    int64 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’:

  In [78]: ds = xray.Dataset({'t': pd.date_range('2000-01-01', periods=12, freq='M')})
  
  In [79]: ds['t.season']
  Out[79]: 
  <xarray.DataArray 'season' (t: 12)>
  array(['DJF', 'DJF', 'MAM', ..., 'SON', 'SON', 'DJF'], 
        dtype='|S3')
  Coordinates:
    * t        (t) datetime64[ns] 2000-01-31 2000-02-29 2000-03-31 2000-04-30 ...
  

  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 reindex() with a fill method. This provides a useful shortcut for upsampling:

  In [80]: data = xray.DataArray([1, 2, 3], dims='x')
  
  In [81]: data.reindex(x=[0.5, 1, 1.5, 2, 2.5], method='pad')
  Out[81]: 
  <xarray.DataArray (x: 5)>
  array([1, 2, 2, 3, 3])
  Coordinates:
    * x        (x) float64 0.5 1.0 1.5 2.0 2.5
  

  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 (GH327 and GH329). Thanks Jeff Gerard!

• Consolidated the functionality of dumps (writing a dataset to a netCDF3 bytestring) into to_netcdf() (GH333).

• to_netcdf() now supports writing to groups in netCDF4 files (GH333). It also finally has a full docstring – you should read it!

• open_dataset() and to_netcdf() now work on netCDF3 files when netcdf4-python is not installed as long as scipy is available (GH333).

• The new Dataset.drop and DataArray.drop methods makes it easy to drop explicitly listed variables or index labels:

  # drop variables
  In [82]: ds = xray.Dataset({'x': 0, 'y': 1})
  
  In [83]: ds.drop('x')
  Out[83]: 
  <xarray.Dataset>
  Dimensions:  ()
  Coordinates:
      *empty*
  Data variables:
      y        int64 1
  
  # drop index labels
  In [84]: arr = xray.DataArray([1, 2, 3], coords=[('x', list('abc'))])
  
  In [85]: arr.drop(['a', 'c'], dim='x')
  Out[85]: 
  <xarray.DataArray (x: 1)>
  array([2])
  Coordinates:
    * x        (x) |S1 'b'
  

• broadcast_equals() has been added to correspond to the new compat option.

• Long attributes are now truncated at 500 characters when printing a dataset (GH338). This should make things more convenient for working with datasets interactively.

• Added a new documentation example, Calculating Seasonal Averages from Timeseries of Monthly Means. Thanks Joe Hamman!

Bug fixes¶

• Several bug fixes related to decoding time units from netCDF files (GH316, GH330). Thanks Stefan Pfenninger!
• xray no longer requires decode_coords=False when reading datasets with unparseable coordinate attributes (GH308).
• Fixed DataArray.loc indexing with ... (GH318).
• Fixed an edge case that resulting in an error when reindexing multi-dimensional variables (GH315).
• Slicing with negative step sizes (GH312).
• Invalid conversion of string arrays to numeric dtype (GH305).
• Fixed``repr()`` on dataset objects with non-standard dates (GH347).

Deprecations¶

• dump and dumps have been deprecated in favor of to_netcdf().
• drop_vars has been deprecated in favor of 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 GH328 for more details.

Backwards incompatible changes¶

• Arrays of datetime.datetime objects are now automatically cast to datetime64[ns] arrays when stored in an xray object, using machinery borrowed from pandas:

  In [86]: from datetime import datetime
  
  In [87]: xray.Dataset({'t': [datetime(2000, 1, 1)]})
  Out[87]: 
  <xarray.Dataset>
  Dimensions:  (t: 1)
  Coordinates:
    * t        (t) datetime64[ns] 2000-01-01
  Data variables:
      *empty*
  

• xray now has support (including serialization to netCDF) for TimedeltaIndex. 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 (GH259).

Enhancements¶

• Due to popular demand, we have added experimental attribute style access as a shortcut for dataset variables, coordinates and attributes:

  In [88]: ds = xray.Dataset({'tmin': ([], 25, {'units': 'celcius'})})
  
  In [89]: ds.tmin.units
  Out[89]: 'celcius'
  

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

• You can now use a dictionary for indexing with labeled dimensions. This provides a safe way to do assignment with labeled dimensions:

  In [90]: array = xray.DataArray(np.zeros(5), dims=['x'])
  
  In [91]: array[dict(x=slice(3))] = 1
  
  In [92]: array
  Out[92]: 
  <xarray.DataArray (x: 5)>
  array([ 1.,  1.,  1.,  0.,  0.])
  Coordinates:
    * x        (x) int64 0 1 2 3 4
  

• 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 (GH287)
• Fix for to_netcdf with 0d string variable (GH284)
• Fix writing datetime64 arrays to netcdf if NaT is present (GH270)
• Fix align silently upcasts data arrays when NaNs are inserted (GH264)

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 (GH293). 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 (GH186).
• The main API breakage that I do anticipate in the next release is finally making all aggregation operations skip missing values by default (GH130). 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.

New features¶

• Added count() and dropna() methods, copied from pandas, for working with missing values (GH247, GH58).
• Added DataArray.to_pandas for converting a data array into the pandas object with the same dimensionality (1D to Series, 2D to DataFrame, etc.) (GH255).
• Support for reading gzipped netCDF3 files (GH239).
• Reduced memory usage when writing netCDF files (GH251).
• ‘missing_value’ is now supported as an alias for the ‘_FillValue’ attribute on netCDF variables (GH245).
• Trivial indexes, equivalent to range(n) where n is the length of the dimension, are no longer written to disk (GH245).

Bug fixes¶

• Compatibility fixes for pandas v0.15 (GH262).
• Fixes for display and indexing of NaT (not-a-time) (GH238, GH240)
• Fix slicing by label was an argument is a data array (GH250).
• Test data is now shipped with the source distribution (GH253).
• Ensure order does not matter when doing arithmetic with scalar data arrays (GH254).
• Order of dimensions preserved with DataArray.to_dataframe (GH260).

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 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 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 reset_coords() instead.

For netCDF and IO¶

• netCDF4: recommended if you want to use xarray for reading or writing netCDF files
• scipy: used as a fallback for reading/writing netCDF3
• pydap: used as a fallback for accessing OPeNDAP
• h5netcdf: an alternative library for reading and writing netCDF4 files that does not use the netCDF-C libraries

For accelerating xarray¶

• bottleneck: speeds up NaN-skipping and rolling window aggregations by a large factor
• cyordereddict: speeds up most internal operations with xarray data structures

For parallel computing¶

• dask.array: required for Out of core computation with dask.

For plotting¶

• matplotlib: required for Plotting.
• cartopy: recommended for Maps.

Creating a DataArray¶

The DataArray constructor takes:

• data: a multi-dimensional array of values (e.g., a numpy ndarray, Series, DataFrame or Panel)
• coords: a list or dictionary of coordinates
• dims: a list of dimension names. If omitted, dimension names are taken from coords if possible
• attrs: a dictionary of attributes to add to the instance
• name: a string that names the instance

In [1]: data = np.random.rand(4, 3)

In [2]: locs = ['IA', 'IL', 'IN']

In [3]: times = pd.date_range('2000-01-01', periods=4)

In [4]: foo = xr.DataArray(data, coords=[times, locs], dims=['time', 'space'])

In [5]: foo
Out[5]: 
<xarray.DataArray (time: 4, space: 3)>
array([[ 0.127,  0.967,  0.26 ],
       [ 0.897,  0.377,  0.336],
       [ 0.451,  0.84 ,  0.123],
       [ 0.543,  0.373,  0.448]])
Coordinates:
  * time     (time) datetime64[ns] 2000-01-01 2000-01-02 2000-01-03 2000-01-04
  * space    (space) |S2 'IA' 'IL' 'IN'

Only data is required; all of other arguments will be filled in with default values:

In [6]: xr.DataArray(data)
Out[6]: 
<xarray.DataArray (dim_0: 4, dim_1: 3)>
array([[ 0.127,  0.967,  0.26 ],
       [ 0.897,  0.377,  0.336],
       [ 0.451,  0.84 ,  0.123],
       [ 0.543,  0.373,  0.448]])
Coordinates:
  * dim_0    (dim_0) int64 0 1 2 3
  * dim_1    (dim_1) int64 0 1 2

As you can see, dimensions and coordinate arrays corresponding to each dimension are always present. This behavior is similar to pandas, which fills in index values in the same way.

Coordinates can take the following forms:

• A list of (dim, ticks[, attrs]) pairs with length equal to the number of dimensions
• A dictionary of {coord_name: coord} where the values are each a scalar value, a 1D array or a tuple. Tuples are be in the same form as the above, and multiple dimensions can be supplied with the form (dims, data[, attrs]). Supplying as a tuple allows other coordinates than those corresponding to dimensions (more on these later).

As a list of tuples:

In [7]: xr.DataArray(data, coords=[('time', times), ('space', locs)])
Out[7]: 
<xarray.DataArray (time: 4, space: 3)>
array([[ 0.127,  0.967,  0.26 ],
       [ 0.897,  0.377,  0.336],
       [ 0.451,  0.84 ,  0.123],
       [ 0.543,  0.373,  0.448]])
Coordinates:
  * time     (time) datetime64[ns] 2000-01-01 2000-01-02 2000-01-03 2000-01-04
  * space    (space) |S2 'IA' 'IL' 'IN'

As a dictionary:

In [8]: xr.DataArray(data, coords={'time': times, 'space': locs, 'const': 42,
   ...:                            'ranking': ('space', [1, 2, 3])},
   ...:              dims=['time', 'space'])
   ...: 
Out[8]: 
<xarray.DataArray (time: 4, space: 3)>
array([[ 0.127,  0.967,  0.26 ],
       [ 0.897,  0.377,  0.336],
       [ 0.451,  0.84 ,  0.123],
       [ 0.543,  0.373,  0.448]])
Coordinates:
    ranking  (space) int64 1 2 3
  * space    (space) |S2 'IA' 'IL' 'IN'
    const    int64 42
  * time     (time) datetime64[ns] 2000-01-01 2000-01-02 2000-01-03 2000-01-04

As a dictionary with coords across multiple dimensions:

In [9]: xr.DataArray(data, coords={'time': times, 'space': locs, 'const': 42,
   ...:                            'ranking': (('time', 'space'), np.arange(12).reshape(4,3))},
   ...:              dims=['time', 'space'])
   ...: 
Out[9]: 
<xarray.DataArray (time: 4, space: 3)>
array([[ 0.127,  0.967,  0.26 ],
       [ 0.897,  0.377,  0.336],
       [ 0.451,  0.84 ,  0.123],
       [ 0.543,  0.373,  0.448]])
Coordinates:
    ranking  (time, space) int64 0 1 2 3 4 5 6 7 8 9 10 11
  * space    (space) |S2 'IA' 'IL' 'IN'
    const    int64 42
  * time     (time) datetime64[ns] 2000-01-01 2000-01-02 2000-01-03 2000-01-04

If you create a DataArray by supplying a pandas Series, DataFrame or Panel, any non-specified arguments in the DataArray constructor will be filled in from the pandas object:

In [10]: df = pd.DataFrame({'x': [0, 1], 'y': [2, 3]}, index=['a', 'b'])

In [11]: df.index.name = 'abc'

In [12]: df.columns.name = 'xyz'

In [13]: df
Out[13]: 
xyz  x  y
abc      
a    0  2
b    1  3

In [14]: xr.DataArray(df)
Out[14]: 
<xarray.DataArray (abc: 2, xyz: 2)>
array([[0, 2],
       [1, 3]])
Coordinates:
  * abc      (abc) object 'a' 'b'
  * xyz      (xyz) object 'x' 'y'

Xarray supports labeling coordinate values with a pandas.MultiIndex. While it handles multi-indexes with unnamed levels, it is recommended that you explicitly set the names of the levels.

DataArray properties¶

Let’s take a look at the important properties on our array:

In [15]: foo.values
Out[15]: 
array([[ 0.127,  0.967,  0.26 ],
       [ 0.897,  0.377,  0.336],
       [ 0.451,  0.84 ,  0.123],
       [ 0.543,  0.373,  0.448]])

In [16]: foo.dims
Out[16]: ('time', 'space')

In [17]: foo.coords
Out[17]: 
Coordinates:
  * time     (time) datetime64[ns] 2000-01-01 2000-01-02 2000-01-03 2000-01-04
  * space    (space) |S2 'IA' 'IL' 'IN'

In [18]: foo.attrs
Out[18]: OrderedDict()

In [19]: print(foo.name)
None

You can even modify values inplace:

In [20]: foo.values = 1.0 * foo.values

Now fill in some of that missing metadata:

In [21]: foo.name = 'foo'

In [22]: foo.attrs['units'] = 'meters'

In [23]: foo
Out[23]: 
<xarray.DataArray 'foo' (time: 4, space: 3)>
array([[ 0.127,  0.967,  0.26 ],
       [ 0.897,  0.377,  0.336],
       [ 0.451,  0.84 ,  0.123],
       [ 0.543,  0.373,  0.448]])
Coordinates:
  * time     (time) datetime64[ns] 2000-01-01 2000-01-02 2000-01-03 2000-01-04
  * space    (space) |S2 'IA' 'IL' 'IN'
Attributes:
    units: meters

The rename() method is another option, returning a new data array:

In [24]: foo.rename('bar')
Out[24]: 
<xarray.DataArray 'bar' (time: 4, space: 3)>
array([[ 0.127,  0.967,  0.26 ],
       [ 0.897,  0.377,  0.336],
       [ 0.451,  0.84 ,  0.123],
       [ 0.543,  0.373,  0.448]])
Coordinates:
  * time     (time) datetime64[ns] 2000-01-01 2000-01-02 2000-01-03 2000-01-04
  * space    (space) |S2 'IA' 'IL' 'IN'
Attributes:
    units: meters

DataArray Coordinates¶

The coords property is dict like. Individual coordinates can be accessed from the coordinates by name, or even by indexing the data array itself:

In [25]: foo.coords['time']
Out[25]: 
<xarray.DataArray 'time' (time: 4)>
array(['2000-01-01T00:00:00.000000000+0000', '2000-01-02T00:00:00.000000000+0000',
       '2000-01-03T00:00:00.000000000+0000', '2000-01-04T00:00:00.000000000+0000'], dtype='datetime64[ns]')
Coordinates:
  * time     (time) datetime64[ns] 2000-01-01 2000-01-02 2000-01-03 2000-01-04

In [26]: foo['time']
Out[26]: 
<xarray.DataArray 'time' (time: 4)>
array(['2000-01-01T00:00:00.000000000+0000', '2000-01-02T00:00:00.000000000+0000',
       '2000-01-03T00:00:00.000000000+0000', '2000-01-04T00:00:00.000000000+0000'], dtype='datetime64[ns]')
Coordinates:
  * time     (time) datetime64[ns] 2000-01-01 2000-01-02 2000-01-03 2000-01-04

These are also DataArray objects, which contain tick-labels for each dimension.

Coordinates can also be set or removed by using the dictionary like syntax:

In [27]: foo['ranking'] = ('space', [1, 2, 3])

In [28]: foo.coords
Out[28]: 
Coordinates:
  * time     (time) datetime64[ns] 2000-01-01 2000-01-02 2000-01-03 2000-01-04
  * space    (space) |S2 'IA' 'IL' 'IN'
    ranking  (space) int64 1 2 3

In [29]: del foo['ranking']

In [30]: foo.coords
Out[30]: 
Coordinates:
  * time     (time) datetime64[ns] 2000-01-01 2000-01-02 2000-01-03 2000-01-04
  * space    (space) |S2 'IA' 'IL' 'IN'

Creating a Dataset¶

To make an Dataset from scratch, supply dictionaries for any variables (data_vars), coordinates (coords) and attributes (attrs).

data_vars are supplied as a dictionary with each key as the name of the variable and each value as one of: - A DataArray - A tuple of the form (dims, data[, attrs]) - A pandas object

coords are supplied as dictionary of {coord_name: coord} where the values are scalar values, arrays or tuples in the form of (dims, data[, attrs]).

Let’s create some fake data for the example we show above:

In [31]: temp = 15 + 8 * np.random.randn(2, 2, 3)

In [32]: precip = 10 * np.random.rand(2, 2, 3)

In [33]: lon = [[-99.83, -99.32], [-99.79, -99.23]]

In [34]: lat = [[42.25, 42.21], [42.63, 42.59]]

# for real use cases, its good practice to supply array attributes such as
# units, but we won't bother here for the sake of brevity
In [35]: ds = xr.Dataset({'temperature': (['x', 'y', 'time'],  temp),
   ....:                  'precipitation': (['x', 'y', 'time'], precip)},
   ....:                 coords={'lon': (['x', 'y'], lon),
   ....:                         'lat': (['x', 'y'], lat),
   ....:                         'time': pd.date_range('2014-09-06', periods=3),
   ....:                         'reference_time': pd.Timestamp('2014-09-05')})
   ....: 

In [36]: ds
Out[36]: 
<xarray.Dataset>
Dimensions:         (time: 3, x: 2, y: 2)
Coordinates:
    lat             (x, y) float64 42.25 42.21 42.63 42.59
    reference_time  datetime64[ns] 2014-09-05
    lon             (x, y) float64 -99.83 -99.32 -99.79 -99.23
  * time            (time) datetime64[ns] 2014-09-06 2014-09-07 2014-09-08
  * x               (x) int64 0 1
  * y               (y) int64 0 1
Data variables:
    precipitation   (x, y, time) float64 5.904 2.453 3.404 9.847 9.195 ...
    temperature     (x, y, time) float64 11.04 23.57 20.77 9.346 6.683 17.17 ...

Notice that we did not explicitly include coordinates for the “x” or “y” dimensions, so they were filled in array of ascending integers of the proper length.

Here we pass xarray.DataArray objects or a pandas object as values in the dictionary:

In [37]: xr.Dataset({'bar': foo})
Out[37]: 
<xarray.Dataset>
Dimensions:  (space: 3, time: 4)
Coordinates:
  * time     (time) datetime64[ns] 2000-01-01 2000-01-02 2000-01-03 2000-01-04
  * space    (space) |S2 'IA' 'IL' 'IN'
Data variables:
    bar      (time, space) float64 0.127 0.9667 0.2605 0.8972 0.3767 0.3362 ...

In [38]: xr.Dataset({'bar': foo.to_pandas()})
Out[38]: 
<xarray.Dataset>
Dimensions:  (space: 3, time: 4)
Coordinates:
  * time     (time) datetime64[ns] 2000-01-01 2000-01-02 2000-01-03 2000-01-04
  * space    (space) object 'IA' 'IL' 'IN'
Data variables:
    bar      (time, space) float64 0.127 0.9667 0.2605 0.8972 0.3767 0.3362 ...

Where a pandas object is supplied as a value, the names of its indexes are used as dimension names, and its data is aligned to any existing dimensions.

You can also create an dataset from: - A pandas.DataFrame or pandas.Panel along its columns and items

respectively, by passing it into the xarray.Dataset directly

• A pandas.DataFrame with Dataset.from_dataframe, which will additionally handle MultiIndexes See Working with pandas
• A netCDF file on disk with open_dataset(). See Serialization and IO.

Dataset contents¶

Dataset implements the Python dictionary interface, with values given by xarray.DataArray objects:

In [39]: 'temperature' in ds
Out[39]: True

In [40]: ds.keys()
Out[40]: 
['precipitation',
 'temperature',
 'lat',
 'reference_time',
 'lon',
 'time',
 'x',
 'y']

In [41]: ds['temperature']
Out[41]: 
<xarray.DataArray 'temperature' (x: 2, y: 2, time: 3)>
array([[[ 11.041,  23.574,  20.772],
        [  9.346,   6.683,  17.175]],

       [[ 11.6  ,  19.536,  17.21 ],
        [  6.301,   9.61 ,  15.909]]])
Coordinates:
    lat             (x, y) float64 42.25 42.21 42.63 42.59
    reference_time  datetime64[ns] 2014-09-05
    lon             (x, y) float64 -99.83 -99.32 -99.79 -99.23
  * time            (time) datetime64[ns] 2014-09-06 2014-09-07 2014-09-08
  * x               (x) int64 0 1
  * y               (y) int64 0 1

The valid keys include each listed coordinate and data variable.

Data and coordinate variables are also contained separately in the data_vars and coords dictionary-like attributes:

In [42]: ds.data_vars
Out[42]: 
Data variables:
    precipitation  (x, y, time) float64 5.904 2.453 3.404 9.847 9.195 0.3777 ...
    temperature    (x, y, time) float64 11.04 23.57 20.77 9.346 6.683 17.17 ...

In [43]: ds.coords
Out[43]: 
Coordinates:
    lat             (x, y) float64 42.25 42.21 42.63 42.59
    reference_time  datetime64[ns] 2014-09-05
    lon             (x, y) float64 -99.83 -99.32 -99.79 -99.23
  * time            (time) datetime64[ns] 2014-09-06 2014-09-07 2014-09-08
  * x               (x) int64 0 1
  * y               (y) int64 0 1

Finally, like data arrays, datasets also store arbitrary metadata in the form of attributes:

In [44]: ds.attrs
Out[44]: OrderedDict()

In [45]: ds.attrs['title'] = 'example attribute'

In [46]: ds
Out[46]: 
<xarray.Dataset>
Dimensions:         (time: 3, x: 2, y: 2)
Coordinates:
    lat             (x, y) float64 42.25 42.21 42.63 42.59
    reference_time  datetime64[ns] 2014-09-05
    lon             (x, y) float64 -99.83 -99.32 -99.79 -99.23
  * time            (time) datetime64[ns] 2014-09-06 2014-09-07 2014-09-08
  * x               (x) int64 0 1
  * y               (y) int64 0 1
Data variables:
    precipitation   (x, y, time) float64 5.904 2.453 3.404 9.847 9.195 ...
    temperature     (x, y, time) float64 11.04 23.57 20.77 9.346 6.683 17.17 ...
Attributes:
    title: example attribute

xarray does not enforce any restrictions on attributes, but serialization to some file formats may fail if you use objects that are not strings, numbers or numpy.ndarray objects.

As a useful shortcut, you can use attribute style access for reading (but not setting) variables and attributes:

In [47]: ds.temperature
Out[47]: 
<xarray.DataArray 'temperature' (x: 2, y: 2, time: 3)>
array([[[ 11.041,  23.574,  20.772],
        [  9.346,   6.683,  17.175]],

       [[ 11.6  ,  19.536,  17.21 ],
        [  6.301,   9.61 ,  15.909]]])
Coordinates:
    lat             (x, y) float64 42.25 42.21 42.63 42.59
    reference_time  datetime64[ns] 2014-09-05
    lon             (x, y) float64 -99.83 -99.32 -99.79 -99.23
  * time            (time) datetime64[ns] 2014-09-06 2014-09-07 2014-09-08
  * x               (x) int64 0 1
  * y               (y) int64 0 1

This is particularly useful in an exploratory context, because you can tab-complete these variable names with tools like IPython.

Dictionary like methods¶

We can update a dataset in-place using Python’s standard dictionary syntax. For example, to create this example dataset from scratch, we could have written:

In [48]: ds = xr.Dataset()

In [49]: ds['temperature'] = (('x', 'y', 'time'), temp)

In [50]: ds['precipitation'] = (('x', 'y', 'time'), precip)

In [51]: ds.coords['lat'] = (('x', 'y'), lat)

In [52]: ds.coords['lon'] = (('x', 'y'), lon)

In [53]: ds.coords['time'] = pd.date_range('2014-09-06', periods=3)

In [54]: ds.coords['reference_time'] = pd.Timestamp('2014-09-05')

To change the variables in a Dataset, you can use all the standard dictionary methods, including values, items, __delitem__, get and update(). Note that assigning a DataArray or pandas object to a Dataset variable using __setitem__ or update will automatically align the array(s) to the original dataset’s indexes.

You can copy a Dataset by calling the copy() method. By default, the copy is shallow, so only the container will be copied: the arrays in the Dataset will still be stored in the same underlying numpy.ndarray objects. You can copy all data by calling ds.copy(deep=True).

Transforming datasets¶

In addition to dictionary-like methods (described above), xarray has additional methods (like pandas) for transforming datasets into new objects.

For removing variables, you can select and drop an explicit list of variables by indexing with a list of names or using the drop() methods to return a new Dataset. These operations keep around coordinates:

In [55]: list(ds[['temperature']])
Out[55]: ['temperature', 'reference_time', 'lon', 'y', 'time', 'lat', 'x']

In [56]: list(ds[['x']])
Out[56]: ['x', 'reference_time']

In [57]: list(ds.drop('temperature'))
Out[57]: ['x', 'y', 'time', 'precipitation', 'lat', 'lon', 'reference_time']

If a dimension name is given as an argument to drop, it also drops all variables that use that dimension:

In [58]: list(ds.drop('time'))
Out[58]: ['x', 'y', 'lat', 'lon', 'reference_time']

As an alternate to dictionary-like modifications, you can use assign() and assign_coords(). These methods return a new dataset with additional (or replaced) or values:

In [59]: ds.assign(temperature2 = 2 * ds.temperature)
Out[59]: 
<xarray.Dataset>
Dimensions:         (time: 3, x: 2, y: 2)
Coordinates:
  * x               (x) int64 0 1
  * y               (y) int64 0 1
  * time            (time) datetime64[ns] 2014-09-06 2014-09-07 2014-09-08
    lat             (x, y) float64 42.25 42.21 42.63 42.59
    lon             (x, y) float64 -99.83 -99.32 -99.79 -99.23
    reference_time  datetime64[ns] 2014-09-05
Data variables:
    temperature     (x, y, time) float64 11.04 23.57 20.77 9.346 6.683 17.17 ...
    precipitation   (x, y, time) float64 5.904 2.453 3.404 9.847 9.195 ...
    temperature2    (x, y, time) float64 22.08 47.15 41.54 18.69 13.37 34.35 ...

There is also the pipe() method that allows you to use a method call with an external function (e.g., ds.pipe(func)) instead of simply calling it (e.g., func(ds)). This allows you to write pipelines for transforming you data (using “method chaining”) instead of writing hard to follow nested function calls:

# these lines are equivalent, but with pipe we can make the logic flow
# entirely from left to right
In [60]: plt.plot((2 * ds.temperature.sel(x=0)).mean('y'))
Out[60]: [<matplotlib.lines.Line2D at 0x7f23ac296190>]

In [61]: (ds.temperature
   ....:  .sel(x=0)
   ....:  .pipe(lambda x: 2 * x)
   ....:  .mean('y')
   ....:  .pipe(plt.plot))
   ....: 
Out[61]: [<matplotlib.lines.Line2D at 0x7f23ac296650>]

Both pipe and assign replicate the pandas methods of the same names (DataFrame.pipe and DataFrame.assign).

With xarray, there is no performance penalty for creating new datasets, even if variables are lazily loaded from a file on disk. Creating new objects instead of mutating existing objects often results in easier to understand code, so we encourage using this approach.

Renaming variables¶

Another useful option is the rename() method to rename dataset variables:

In [62]: ds.rename({'temperature': 'temp', 'precipitation': 'precip'})
Out[62]: 
<xarray.Dataset>
Dimensions:         (time: 3, x: 2, y: 2)
Coordinates:
  * x               (x) int64 0 1
  * y               (y) int64 0 1
  * time            (time) datetime64[ns] 2014-09-06 2014-09-07 2014-09-08
    lat             (x, y) float64 42.25 42.21 42.63 42.59
    lon             (x, y) float64 -99.83 -99.32 -99.79 -99.23
    reference_time  datetime64[ns] 2014-09-05
Data variables:
    temp            (x, y, time) float64 11.04 23.57 20.77 9.346 6.683 17.17 ...
    precip          (x, y, time) float64 5.904 2.453 3.404 9.847 9.195 ...

The related swap_dims() method allows you do to swap dimension and non-dimension variables:

In [63]: ds.coords['day'] = ('time', [6, 7, 8])

In [64]: ds.swap_dims({'time': 'day'})
Out[64]: 
<xarray.Dataset>
Dimensions:         (day: 3, x: 2, y: 2)
Coordinates:
  * x               (x) int64 0 1
  * y               (y) int64 0 1
    time            (day) datetime64[ns] 2014-09-06 2014-09-07 2014-09-08
    lat             (x, y) float64 42.25 42.21 42.63 42.59
    lon             (x, y) float64 -99.83 -99.32 -99.79 -99.23
    reference_time  datetime64[ns] 2014-09-05
  * day             (day) int64 6 7 8
Data variables:
    temperature     (x, y, day) float64 11.04 23.57 20.77 9.346 6.683 17.17 ...
    precipitation   (x, y, day) float64 5.904 2.453 3.404 9.847 9.195 0.3777 ...

Modifying coordinates¶

To entirely add or remove coordinate arrays, you can use dictionary like syntax, as shown above.

To convert back and forth between data and coordinates, you can use the set_coords() and reset_coords() methods:

In [66]: ds.reset_coords()
Out[66]: 
<xarray.Dataset>
Dimensions:         (time: 3, x: 2, y: 2)
Coordinates:
  * x               (x) int64 0 1
  * y               (y) int64 0 1
  * time            (time) datetime64[ns] 2014-09-06 2014-09-07 2014-09-08
Data variables:
    temperature     (x, y, time) float64 11.04 23.57 20.77 9.346 6.683 17.17 ...
    precipitation   (x, y, time) float64 5.904 2.453 3.404 9.847 9.195 ...
    lat             (x, y) float64 42.25 42.21 42.63 42.59
    lon             (x, y) float64 -99.83 -99.32 -99.79 -99.23
    reference_time  datetime64[ns] 2014-09-05
    day             (time) int64 6 7 8

In [67]: ds.set_coords(['temperature', 'precipitation'])
Out[67]: 
<xarray.Dataset>
Dimensions:         (time: 3, x: 2, y: 2)
Coordinates:
    temperature     (x, y, time) float64 11.04 23.57 20.77 9.346 6.683 17.17 ...
  * x               (x) int64 0 1
  * y               (y) int64 0 1
  * time            (time) datetime64[ns] 2014-09-06 2014-09-07 2014-09-08
    precipitation   (x, y, time) float64 5.904 2.453 3.404 9.847 9.195 ...
    lat             (x, y) float64 42.25 42.21 42.63 42.59
    lon             (x, y) float64 -99.83 -99.32 -99.79 -99.23
    reference_time  datetime64[ns] 2014-09-05
    day             (time) int64 6 7 8
Data variables:
    *empty*

In [68]: ds['temperature'].reset_coords(drop=True)
Out[68]: 
<xarray.DataArray 'temperature' (x: 2, y: 2, time: 3)>
array([[[ 11.041,  23.574,  20.772],
        [  9.346,   6.683,  17.175]],

       [[ 11.6  ,  19.536,  17.21 ],
        [  6.301,   9.61 ,  15.909]]])
Coordinates:
  * x        (x) int64 0 1
  * y        (y) int64 0 1
  * time     (time) datetime64[ns] 2014-09-06 2014-09-07 2014-09-08

Notice that these operations skip coordinates with names given by dimensions, as used for indexing. This mostly because we are not entirely sure how to design the interface around the fact that xarray cannot store a coordinate and variable with the name but different values in the same dictionary. But we do recognize that supporting something like this would be useful.

Coordinates methods¶

Coordinates objects also have a few useful methods, mostly for converting them into dataset objects:

In [69]: ds.coords.to_dataset()
Out[69]: 
<xarray.Dataset>
Dimensions:         (time: 3, x: 2, y: 2)
Coordinates:
    reference_time  datetime64[ns] 2014-09-05
    lon             (x, y) float64 -99.83 -99.32 -99.79 -99.23
  * y               (y) int64 0 1
  * time            (time) datetime64[ns] 2014-09-06 2014-09-07 2014-09-08
    lat             (x, y) float64 42.25 42.21 42.63 42.59
  * x               (x) int64 0 1
    day             (time) int64 6 7 8
Data variables:
    *empty*