Data Structures¶
DataArray¶
xarray.DataArray is xarray’s implementation of a labeled,
multi-dimensional array. It has several key properties:
values: anumpy.ndarrayholding the array’s valuesdims: dimension names for each axis (e.g.,('x', 'y', 'z'))coords: a dict-like container of arrays (coordinates) that label each point (e.g., 1-dimensional arrays of numbers, datetime objects or strings)attrs: anOrderedDictto hold arbitrary metadata (attributes)
xarray uses dims and coords to enable its core metadata aware operations.
Dimensions provide names that xarray uses instead of the axis argument found
in many numpy functions. Coordinates enable fast label based indexing and
alignment, building on the functionality of the index found on a pandas
DataFrame or Series.
DataArray objects also can have a name and can hold arbitrary metadata in
the form of their attrs property (an ordered dictionary). Names and
attributes are strictly for users and user-written code: xarray makes no attempt
to interpret them, and propagates them only in unambiguous cases (see FAQ,
What is your approach to metadata?).
Creating a DataArray¶
The DataArray constructor takes:
data: a multi-dimensional array of values (e.g., a numpy ndarray,Series,DataFrameorPanel)coords: a list or dictionary of coordinatesdims: a list of dimension names. If omitted, dimension names are taken fromcoordsif possibleattrs: a dictionary of attributes to add to the instancename: 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
Note
The array values in a DataArray have a single
(homogeneous) data type. To work with heterogeneous or structured data
types in xarray, use coordinates, or put separate DataArray objects
in a single Dataset (see below).
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', '2000-01-02T00:00:00.000000000',
'2000-01-03T00:00:00.000000000', '2000-01-04T00:00:00.000000000'], 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', '2000-01-02T00:00:00.000000000',
'2000-01-03T00:00:00.000000000', '2000-01-04T00:00:00.000000000'], 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'
Dataset¶
xarray.Dataset is xarray’s multi-dimensional equivalent of a
DataFrame. It is a dict-like
container of labeled arrays (DataArray objects) with aligned
dimensions. It is designed as an in-memory representation of the data model
from the netCDF file format.
In addition to the dict-like interface of the dataset itself, which can be used to access any variable in a dataset, datasets have four key properties:
dims: a dictionary mapping from dimension names to the fixed length of each dimension (e.g.,{'x': 6, 'y': 6, 'time': 8})data_vars: a dict-like container of DataArrays corresponding to variablescoords: another dict-like container of DataArrays intended to label points used indata_vars(e.g., arrays of numbers, datetime objects or strings)attrs: anOrderedDictto hold arbitrary metadata
The distinction between whether a variables falls in data or coordinates (borrowed from CF conventions) is mostly semantic, and you can probably get away with ignoring it if you like: dictionary like access on a dataset will supply variables found in either category. However, xarray does make use of the distinction for indexing and computations. Coordinates indicate constant/fixed/independent quantities, unlike the varying/measured/dependent quantities that belong in data.
Here is an example of how we might structure a dataset for a weather forecast:
In this example, it would be natural to call temperature and
precipitation “data variables” and all the other arrays “coordinate
variables” because they label the points along the dimensions. (see [1] for
more background on this example).
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 thexarray.Datasetdirectly
- A
pandas.DataFramewithDataset.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 0x7f07db10ea10>]
In [61]: (ds.temperature
....: .sel(x=0)
....: .pipe(lambda x: 2 * x)
....: .mean('y')
....: .pipe(plt.plot))
....:
Out[61]: [<matplotlib.lines.Line2D at 0x7f07db0f45d0>]
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 ...
Coordinates¶
Coordinates are ancillary variables stored for DataArray and Dataset
objects in the coords attribute:
In [65]: ds.coords
Out[65]:
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
day (time) int64 6 7 8
Unlike attributes, xarray does interpret and persist coordinates in operations that transform xarray objects.
One dimensional coordinates with a name equal to their sole dimension (marked
by * when printing a dataset or data array) take on a special meaning in
xarray. They are used for label based indexing and alignment,
like the index found on a pandas DataFrame or
Series. Indeed, these “dimension” coordinates use a
pandas.Index internally to store their values.
Other than for indexing, xarray does not make any direct use of the values associated with coordinates. Coordinates with names not matching a dimension are not used for alignment or indexing, nor are they required to match when doing arithmetic (see Coordinates).
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*
The merge method is particularly interesting, because it implements the same logic used for merging coordinates in arithmetic operations (see Computation):
In [70]: alt = xr.Dataset(coords={'z': [10], 'lat': 0, 'lon': 0})
In [71]: ds.coords.merge(alt.coords)
Out[71]:
<xarray.Dataset>
Dimensions: (time: 3, x: 2, y: 2, z: 1)
Coordinates:
* x (x) int64 0 1
* y (y) int64 0 1
* time (time) datetime64[ns] 2014-09-06 2014-09-07 2014-09-08
reference_time datetime64[ns] 2014-09-05
day (time) int64 6 7 8
* z (z) int64 10
Data variables:
*empty*
The coords.merge method may be useful if you want to implement your own
binary operations that act on xarray objects. In the future, we hope to write
more helper functions so that you can easily make your functions act like
xarray’s built-in arithmetic.
Indexes¶
To convert a coordinate (or any DataArray) into an actual
pandas.Index, use the to_index() method:
In [72]: ds['time'].to_index()
Out[72]: DatetimeIndex(['2014-09-06', '2014-09-07', '2014-09-08'], dtype='datetime64[ns]', name=u'time', freq='D')
A useful shortcut is the indexes property (on both DataArray and
Dataset), which lazily constructs a dictionary whose keys are given by each
dimension and whose the values are Index objects:
In [73]: ds.indexes
Out[73]:
y: Int64Index([0, 1], dtype='int64', name=u'y')
x: Int64Index([0, 1], dtype='int64', name=u'x')
time: DatetimeIndex(['2014-09-06', '2014-09-07', '2014-09-08'], dtype='datetime64[ns]', name=u'time', freq='D')
| [1] | Latitude and longitude are 2D arrays because the dataset uses
projected coordinates. reference_time refers to the reference time
at which the forecast was made, rather than time which is the valid time
for which the forecast applies. |