<xarray.DataArray (x: 2, y: 1)> Size: 16B
array([[0],
[3]])
Coordinates:
\* x (x) <U1 8B 'a' 'b'
\* y (y) int64 8B 10
```ipython3
# This resembles how you would use np.concatenate:
xr.concat([da[:, :1], da[:, 1:]], dim="y")
```
```none
<xarray.DataArray (x: 2, y: 3)> Size: 48B
array([[0, 1, 2],
[3, 4, 5]])
Coordinates:
\* x (x) <U1 8B 'a' 'b'
\* y (y) int64 24B 10 20 30
```ipython3
# For more friendly pandas-like indexing you can use:
xr.concat([da.isel(y=slice(0, 1)), da.isel(y=slice(1, None))], dim="y")
```
```none
<xarray.DataArray (x: 2, y: 3)> Size: 48B
array([[0, 1, 2],
[3, 4, 5]])
Coordinates:
\* x (x) <U1 8B 'a' 'b'
\* y (y) int64 24B 10 20 30
In addition to combining along an existing dimension, `concat` can create a
new dimension by stacking lower dimensional arrays together:
```ipython3
da.sel(x="a")
```
```none
<xarray.DataArray (y: 3)> Size: 24B
array([0, 1, 2])
Coordinates:
\* y (y) int64 24B 10 20 30
x <U1 4B 'a'
```ipython3
xr.concat([da.isel(x=0), da.isel(x=1)], "x")
```
```none
<xarray.DataArray (x: 2, y: 3)> Size: 48B
array([[0, 1, 2],
[3, 4, 5]])
Coordinates:
\* x (x) <U1 8B 'a' 'b'
\* y (y) int64 24B 10 20 30
If the second argument to `concat` is a new dimension name, the arrays will
be concatenated along that new dimension, which is always inserted as the first
dimension:
```ipython3
da0 = da.isel(x=0, drop=True)
da1 = da.isel(x=1, drop=True)
xr.concat([da0, da1], "new_dim")
```
```none
<xarray.DataArray (new_dim: 2, y: 3)> Size: 48B
array([[0, 1, 2],
[3, 4, 5]])
Coordinates:
\* y (y) int64 24B 10 20 30
Dimensions without coordinates: new_dim<xarray.DataArray (new_dim: 2, y: 3)> Size: 48B
array([[0, 1, 2],
[3, 4, 5]])
Coordinates:
\* new_dim (new_dim) int64 16B -90 -100
\* y (y) int64 24B 10 20 30<xarray.Dataset> Size: 80B
Dimensions: (x: 2, y: 3)
Coordinates:
\* x (x) <U1 8B 'a' 'b'
\* y (y) int64 24B 10 20 30
Data variables:
foo (x, y) int64 48B 0 1 2 3 4 5
[`concat()`](../generated/xarray.concat.md#xarray.concat) has a number of options which provide deeper control
over which variables are concatenated and how it handles conflicting variables
between datasets. With the default parameters, xarray will load some coordinate
variables into memory to compare them between datasets. This may be prohibitively
expensive if you are manipulating your dataset lazily using [Parallel Computing with Dask](dask.md#dask).
#### NOTE
In a future version of xarray the default values for many of these options
will change. You can opt into the new default values early using
`xr.set_options(use_new_combine_kwarg_defaults=True)`.
## Merge
To combine variables and coordinates between multiple `DataArray` and/or
`Dataset` objects, use [`merge()`](../generated/xarray.merge.md#xarray.merge). It can merge a list of
`Dataset`, `DataArray` or dictionaries of objects convertible to
`DataArray` objects:
```ipython3
xr.merge([ds, ds.rename({"foo": "bar"})])
```
```none
<xarray.Dataset> Size: 128B
Dimensions: (x: 2, y: 3)
Coordinates:
\* x (x) <U1 8B 'a' 'b'
\* y (y) int64 24B 10 20 30
Data variables:
foo (x, y) int64 48B 0 1 2 3 4 5
bar (x, y) int64 48B 0 1 2 3 4 5
```ipython3
xr.merge([xr.DataArray(n, name="var%d" % n) for n in range(5)])
```
```none
<xarray.Dataset> Size: 40B
Dimensions: ()
Data variables:
var0 int64 8B 0
var1 int64 8B 1
var2 int64 8B 2
var3 int64 8B 3
var4 int64 8B 4<xarray.Dataset> Size: 168B
Dimensions: (x: 4, y: 3)
Coordinates:
\* x (x) <U1 16B 'a' 'b' 'c' 'd'
\* y (y) int64 24B 10 20 30
Data variables:
foo (x, y) float64 96B 0.0 1.0 2.0 3.0 4.0 5.0 nan nan nan nan nan nan
bar (x) int64 32B 1 2 3 4
This ensures that `merge` is non-destructive. `xarray.MergeError` is raised
if you attempt to merge two variables with the same name but different values:
```ipython3
xr.merge([ds, ds + 1])
```
```ipythontb
MergeError: conflicting values for variable 'foo' on objects to be combined. You can skip this check by specifying compat='override'.
```
#### NOTE
In a future version of xarray the default value for `compat` will change
from `compat='no_conflicts'` to `compat='override'`. In this scenario
the values in the first object override all the values in other objects.
```ipython3
xr.merge([ds, ds + 1], compat="override")
```
```none
<xarray.Dataset> Size: 80B
Dimensions: (x: 2, y: 3)
Coordinates:
\* x (x) <U1 8B 'a' 'b'
\* y (y) int64 24B 10 20 30
Data variables:
foo (x, y) int64 48B 0 1 2 3 4 5
The same non-destructive merging between `DataArray` index coordinates is
used in the [`Dataset`](../generated/xarray.Dataset.md#xarray.Dataset) constructor:
```ipython3
xr.Dataset({"a": da.isel(x=slice(0, 1)), "b": da.isel(x=slice(1, 2))})
```
```none
<xarray.Dataset> Size: 128B
Dimensions: (x: 2, y: 3)
Coordinates:
\* x (x) <U1 8B 'a' 'b'
\* y (y) int64 24B 10 20 30
Data variables:
a (x, y) float64 48B 0.0 1.0 2.0 nan nan nan
b (x, y) float64 48B nan nan nan 3.0 4.0 5.0
## Combine
The instance method [`combine_first()`](../generated/xarray.DataArray.combine_first.md#xarray.DataArray.combine_first) combines two
datasets/data arrays and defaults to non-null values in the calling object,
using values from the called object to fill holes. The resulting coordinates
are the union of coordinate labels. Vacant cells as a result of the outer-join
are filled with `NaN`. For example:
```ipython3
ar0 = xr.DataArray([[0, 0], [0, 0]], [("x", ["a", "b"]), ("y", [-1, 0])])
ar1 = xr.DataArray([[1, 1], [1, 1]], [("x", ["b", "c"]), ("y", [0, 1])])
ar0.combine_first(ar1)
```
```none
<xarray.DataArray (x: 3, y: 3)> Size: 72B
array([[ 0., 0., nan],
[ 0., 0., 1.],
[nan, 1., 1.]])
Coordinates:
\* x (x) <U1 12B 'a' 'b' 'c'
\* y (y) int64 24B -1 0 1
```ipython3
ar1.combine_first(ar0)
```
```none
<xarray.DataArray (x: 3, y: 3)> Size: 72B
array([[ 0., 0., nan],
[ 0., 1., 1.],
[nan, 1., 1.]])
Coordinates:
\* x (x) <U1 12B 'a' 'b' 'c'
\* y (y) int64 24B -1 0 1
For datasets, `ds0.combine_first(ds1)` works similarly to
`xr.merge([ds0, ds1])`, except that `xr.merge` raises `MergeError` when
there are conflicting values in variables to be merged, whereas
`.combine_first` defaults to the calling object’s values.
#### NOTE
In a future version of xarray the default options for `xr.merge` will change
such that the behavior matches `combine_first`.
## Update
In contrast to `merge`, [`update()`](../generated/xarray.Dataset.update.md#xarray.Dataset.update) modifies a dataset
in-place without checking for conflicts, and will overwrite any existing
variables with new values:
```ipython3
ds.update({"space": ("space", [10.2, 9.4, 3.9])})
```
However, dimensions are still required to be consistent between different
Dataset variables, so you cannot change the size of a dimension unless you
replace all dataset variables that use it.
`update` also performs automatic alignment if necessary. Unlike `merge`, it
maintains the alignment of the original array instead of merging indexes:
```ipython3
ds.update(other)
```
The exact same alignment logic when setting a variable with `__setitem__`
syntax:
```ipython3
ds["baz"] = xr.DataArray([9, 9, 9, 9, 9], coords=[("x", list("abcde"))])
ds.baz
```
```none
<xarray.DataArray 'baz' (x: 2)> Size: 16B array([9, 9]) Coordinates: \* x (x) <U1 8B 'a' 'b'## Equals and identical Xarray objects can be compared by using the [`equals()`](../generated/xarray.Dataset.equals.md#xarray.Dataset.equals), [`identical()`](../generated/xarray.Dataset.identical.md#xarray.Dataset.identical) and [`broadcast_equals()`](../generated/xarray.Dataset.broadcast_equals.md#xarray.Dataset.broadcast_equals) methods. These methods are used by the optional `compat` argument on `concat` and `merge`. [`equals`](../generated/xarray.Dataset.equals.md#xarray.Dataset.equals) checks dimension names, indexes and array values: ```ipython3 da.equals(da.copy()) ``` ```none True ``` [`identical`](../generated/xarray.Dataset.identical.md#xarray.Dataset.identical) also checks attributes, and the name of each object: ```ipython3 da.identical(da.rename("bar")) ``` ```none False ``` [`broadcast_equals`](../generated/xarray.Dataset.broadcast_equals.md#xarray.Dataset.broadcast_equals) does a more relaxed form of equality check that allows variables to have different dimensions, as long as values are constant along those new dimensions: ```ipython3 left = xr.Dataset(coords={"x": 0}) right = xr.Dataset({"x": [0, 0, 0]}) left.broadcast_equals(right) ``` ```none True ``` Like pandas objects, two xarray objects are still equal or identical if they have missing values marked by `NaN` in the same locations. In contrast, the `==` operation performs element-wise comparison (like numpy): ```ipython3 da == da.copy() ``` ```none
<xarray.DataArray (x: 2, y: 3)> Size: 6B
array([[ True, True, True],
[ True, True, True]])
Coordinates:
\* x (x) <U1 8B 'a' 'b'
\* y (y) int64 24B 10 20 30
Note that `NaN` does not compare equal to `NaN` in element-wise comparison;
you may need to deal with missing values explicitly.
## Merging with ‘no_conflicts’
The `compat` argument `'no_conflicts'` is only available when
combining xarray objects with `merge`. In addition to the above comparison
methods it allows the merging of xarray objects with locations where *either*
have `NaN` values. This can be used to combine data with overlapping
coordinates as long as any non-missing values agree or are disjoint:
```ipython3
ds1 = xr.Dataset({"a": ("x", [10, 20, 30, np.nan])}, {"x": [1, 2, 3, 4]})
ds2 = xr.Dataset({"a": ("x", [np.nan, 30, 40, 50])}, {"x": [2, 3, 4, 5]})
xr.merge([ds1, ds2], join="outer", compat="no_conflicts")
```
```none
<xarray.Dataset> Size: 80B
Dimensions: (x: 5)
Coordinates:
\* x (x) int64 40B 1 2 3 4 5
Data variables:
a (x) float64 40B 10.0 20.0 30.0 40.0 50.0<xarray.DataArray 'temperature' (x: 2, y: 2)> Size: 32B
array([[1, 2],
[2, 1]])
Dimensions without coordinates: x, y<xarray.DataArray 'temperature' (x: 4, y: 4)> Size: 128B
array([[1, 2, 1, 2],
[2, 1, 2, 1],
[1, 2, 1, 2],
[2, 1, 2, 1]])
Dimensions without coordinates: x, y<xarray.Dataset> Size: 64B
Dimensions: (t: 4)
Dimensions without coordinates: t
Data variables:
temperature (t) float64 32B 0.4691 -0.2829 0.4691 -0.2829
precipitation (t) float64 32B -1.509 -1.136 -1.509 -1.136<xarray.Dataset> Size: 96B
Dimensions: (x: 6)
Coordinates:
\* x (x) int64 48B 0 1 2 3 4 5
Data variables:
foo (x) float64 48B 1.212 -0.1732 0.1192 -1.044 -0.8618 -2.105<xarray.DataArray 'complex_nums' (x: 2, y: 2)> Size: 32B
array([[1., 3.],
[5., 7.]])
Coordinates:
\* x (x) <U1 8B 'a' 'b'
\* y (y) int64 16B 1 2
```ipython3
np.abs(da)
```
```none
<xarray.DataArray 'complex_nums' (x: 2, y: 2)> Size: 32B
array([[ 2.23606798, 5. ],
[ 7.81024968, 10.63014581]])
Coordinates:
\* x (x) <U1 8B 'a' 'b'
\* y (y) int64 16B 1 2
#### NOTE
Like NumPy, `.real` and `.imag` typically return *views*, not copies, of the original data.
## Reading and Writing Complex Data
Writing complex data to NetCDF files (see [netCDF](io.md#io-netcdf)) is supported via [`to_netcdf()`](../generated/xarray.DataArray.to_netcdf.md#xarray.DataArray.to_netcdf) using specific backend engines that handle complex types:
This requires the [h5netcdf](https://h5netcdf.org) library to be installed.
```ipython3
complex_nums_h5_filename = "complex_nums_h5.nc"
```
```ipython3
# write the data to disk
da.to_netcdf(complex_nums_h5_filename, engine="h5netcdf")
# read the file back into memory
ds_h5 = xr.open_dataset(complex_nums_h5_filename, engine="h5netcdf")
# check the dtype
ds_h5[da.name].dtype
```
```none
dtype('complex128')
```
Requires the [netcdf4-python (>= 1.7.1)](https://github.com/Unidata/netcdf4-python) library and you have to enable `auto_complex=True`.
```ipython3
complex_nums_nc4_filename = "complex_nums_nc4.nc"
```
```ipython3
# write the data to disk
da.to_netcdf(complex_nums_nc4_filename, engine="netcdf4", auto_complex=True)
# read the file back into memory
ds_nc4 = xr.open_dataset(
complex_nums_nc4_filename, engine="netcdf4", auto_complex=True
)
# check the dtype
ds_nc4[da.name].dtype
```
```none
dtype('complex128')
```
#### WARNING
The `scipy` engine only supports NetCDF V3 and does *not* support complex arrays; writing with `engine="scipy"` raises a `TypeError`.
### Alternative: Manual Handling
If direct writing is not supported (e.g., targeting NetCDF3), you can manually
split the complex array into separate real and imaginary variables before saving:
```ipython3
complex_manual_filename = "complex_manual.nc"
```
```ipython3
# Write data to file
ds_manual = xr.Dataset(
{
f"{da.name}_real": da.real,
f"{da.name}_imag": da.imag,
}
)
ds_manual.to_netcdf(complex_manual_filename, engine="scipy") # Example
# Read data from file
ds = xr.open_dataset(complex_manual_filename, engine="scipy")
reconstructed = ds[f"{da.name}_real"] + 1j * ds[f"{da.name}_imag"]
```
### Recommendations
- Use `engine="netcdf4"` with `auto_complex=True` for full compliance and ease.
- Use `h5netcdf` for HDF5-based storage when interoperability with HDF5 is desired.
- For maximum legacy support (NetCDF3), manually handle real/imaginary components.
## See also
- [netCDF](io.md#io-netcdf) — full NetCDF I/O guide
- [NumPy complex numbers](https://numpy.org/doc/stable/user/basics.types.html#complex)
# computation.html.md
# Computation
The labels associated with [`DataArray`](../generated/xarray.DataArray.md#xarray.DataArray) and
[`Dataset`](../generated/xarray.Dataset.md#xarray.Dataset) objects enables some powerful shortcuts for
computation, notably including aggregation and broadcasting by dimension
names.
## Basic array math
Arithmetic operations with a single DataArray automatically vectorize (like
numpy) over all array values:
```ipython3
arr = xr.DataArray(
np.random.default_rng(0).random((2, 3)),
[("x", ["a", "b"]), ("y", [10, 20, 30])],
)
arr - 3
```
```none
<xarray.DataArray (x: 2, y: 3)> Size: 48B
array([[-2.36303831, -2.73021329, -2.95902648],
[-2.98347236, -2.18672976, -2.08724442]])
Coordinates:
\* x (x) <U1 8B 'a' 'b'
\* y (y) int64 24B 10 20 30
```ipython3
abs(arr)
```
```none
<xarray.DataArray (x: 2, y: 3)> Size: 48B
array([[0.63696169, 0.26978671, 0.04097352],
[0.01652764, 0.81327024, 0.91275558]])
Coordinates:
\* x (x) <U1 8B 'a' 'b'
\* y (y) int64 24B 10 20 30
You can also use any of numpy’s or scipy’s many [ufunc](https://numpy.org/doc/stable/reference/ufuncs.html) functions directly on
a DataArray:
```ipython3
np.sin(arr)
```
```none
<xarray.DataArray (x: 2, y: 3)> Size: 48B
array([[0.59475567, 0.26652587, 0.04096206],
[0.01652688, 0.72653812, 0.79119196]])
Coordinates:
\* x (x) <U1 8B 'a' 'b'
\* y (y) int64 24B 10 20 30
Use [`where()`](../generated/xarray.where.md#xarray.where) to conditionally switch between values:
```ipython3
xr.where(arr > 0, "positive", "negative")
```
```none
<xarray.DataArray (x: 2, y: 3)> Size: 192B
array([['positive', 'positive', 'positive'],
['positive', 'positive', 'positive']], dtype='<U8')
Coordinates:
\* x (x) <U1 8B 'a' 'b'
\* y (y) int64 24B 10 20 30
Use `@` to compute the [`dot()`](../generated/xarray.dot.md#xarray.dot) product:
```ipython3
arr @ arr
```
```none
<xarray.DataArray ()> Size: 8B array(1.97498828)
<xarray.DataArray (x: 2, y: 3)> Size: 48B
array([[0.64, 0.27, 0.04],
[0.02, 0.81, 0.91]])
Coordinates:
\* x (x) <U1 8B 'a' 'b'
\* y (y) int64 24B 10 20 30
```ipython3
arr.T
```
```none
<xarray.DataArray (y: 3, x: 2)> Size: 48B
array([[0.63696169, 0.01652764],
[0.26978671, 0.81327024],
[0.04097352, 0.91275558]])
Coordinates:
\* y (y) int64 24B 10 20 30
\* x (x) <U1 8B 'a' 'b'
```ipython3
intarr = xr.DataArray([0, 1, 2, 3, 4, 5])
intarr << 2 # only supported for int types
```
```none
<xarray.DataArray (dim_0: 6)> Size: 48B array([ 0, 4, 8, 12, 16, 20]) Dimensions without coordinates: dim_0
<xarray.DataArray (dim_0: 6)> Size: 48B array([0, 0, 1, 1, 2, 2]) Dimensions without coordinates: dim_0
<xarray.DataArray (x: 5)> Size: 5B array([False, False, True, True, False]) Dimensions without coordinates: x
<xarray.DataArray (x: 5)> Size: 5B array([ True, True, False, False, True]) Dimensions without coordinates: x
<xarray.DataArray ()> Size: 8B array(3)
<xarray.DataArray (x: 3)> Size: 24B array([0., 1., 2.]) Dimensions without coordinates: x
<xarray.DataArray (x: 5)> Size: 40B array([ 0., 1., -1., -1., 2.]) Dimensions without coordinates: x
<xarray.DataArray (x: 5)> Size: 40B array([0., 1., 1., 1., 2.]) Dimensions without coordinates: x
<xarray.DataArray (x: 5)> Size: 40B array([0., 1., 2., 2., 2.]) Dimensions without coordinates: x
<xarray.DataArray (x: 5)> Size: 40B
array([0. , 1. , 1.05, 1.45, 2. ])
Coordinates:
xx (x) float64 40B 0.0 1.0 1.1 1.9 3.0
Dimensions without coordinates: x<xarray.DataArray (y: 3)> Size: 24B array([0.65348932, 1.08305695, 0.9537291 ]) Coordinates: \* y (y) int64 24B 10 20 30
<xarray.DataArray ()> Size: 8B array(0.35793963)
<xarray.DataArray ()> Size: 8B array(0.01652764)
<xarray.DataArray ()> Size: 8B array(2.)
<xarray.DataArray (x: 3, y: 5)> Size: 120B
array([[0. , 0.5, 1. , 1.5, 2. ],
[2.5, 3. , 3.5, 4. , 4.5],
[5. , 5.5, 6. , 6.5, 7. ]])
Dimensions without coordinates: x, y<xarray.DataArray (x: 3, y: 5)> Size: 120B
array([[ nan, nan, 0.40824829, 0.40824829, 0.40824829],
[ nan, nan, 0.40824829, 0.40824829, 0.40824829],
[ nan, nan, 0.40824829, 0.40824829, 0.40824829]])
Dimensions without coordinates: x, y<xarray.DataArray (x: 3, y: 5)> Size: 120B
array([[nan, nan, 0.5, 1. , 1.5],
[nan, nan, 3. , 3.5, 4. ],
[nan, nan, 5.5, 6. , 6.5]])
Dimensions without coordinates: x, y<xarray.DataArray (x: 3, y: 5)> Size: 120B
array([[nan, 0.5, 1. , 1.5, nan],
[nan, 3. , 3.5, 4. , nan],
[nan, 5.5, 6. , 6.5, nan]])
Dimensions without coordinates: x, y<xarray.DataArray (x: 3, y: 5)> Size: 120B
array([[ nan, 0.25, 0.5 , 1. , 1.5 ],
[ nan, 2.75, 3. , 3.5 , 4. ],
[ nan, 5.25, 5.5 , 6. , 6.5 ]])
Dimensions without coordinates: x, y<xarray.DataArray (x: 3, y: 5)> Size: 120B
array([[0.25, 0.5 , 1. , 1.5 , 1.75],
[2.75, 3. , 3.5 , 4. , 4.25],
[5.25, 5.5 , 6. , 6.5 , 6.75]])
Dimensions without coordinates: x, y<xarray.DataArray (x: 3, y: 5)> Size: 120B
array([[ nan, 0.25, 0.5 , 1. , 1.5 ],
[1.25, 1.5 , 1.75, 2.25, 2.75],
[3.75, 4. , 4.25, 4.75, 5.25]])
Dimensions without coordinates: x, y<xarray.DataArray (x: 2, y: 3, x_win: 2, y_win: 3)> Size: 288B
array([[[[nan, nan, nan],
[nan, nan, 0. ]],
[[nan, nan, nan],
[0. , 0.5, 1. ]],
[[nan, nan, nan],
[1. , 1.5, 2. ]]],
[[[nan, nan, 2.5],
[nan, nan, 5. ]],
[[2.5, 3. , 3.5],
[5. , 5.5, 6. ]],
[[3.5, 4. , 4.5],
[6. , 6.5, 7. ]]]])
Dimensions without coordinates: x, y, x_win, y_win<xarray.DataArray (x: 2, y: 3)> Size: 48B
array([[ nan, nan, nan],
[ nan, 4.25, 5.25]])
Dimensions without coordinates: x, y<xarray.DataArray (x: 3, y: 5)> Size: 120B
array([[nan, nan, 0.5, 1. , 1.5],
[nan, nan, 3. , 3.5, 4. ],
[nan, nan, 5.5, 6. , 6.5]])
Dimensions without coordinates: x, y<xarray.DataArray ()> Size: 8B array(90.)
<xarray.DataArray ()> Size: 8B array(1.)
<xarray.DataArray ()> Size: 8B
array(1.)
Coordinates:
quantile float64 8B 0.5<xarray.DataArray ()> Size: 8B array(90.)
<xarray.DataArray ()> Size: 8B array(1.)
<xarray.DataArray ()> Size: 8B array(0.00688889)
<xarray.DataArray ()> Size: 8B array(0.08299933)
<xarray.DataArray ()> Size: 8B array(3.)
<xarray.DataArray ()> Size: 8B array(0.)
<xarray.DataArray ()> Size: 8B array(nan)
<xarray.DataArray (time: 364, x: 300)> Size: 874kB
array([[ 0. , 0.03343858, 0.06683976, ..., -0.48672119,
-0.51565952, -0.54402111],
[ 0. , 0.03343845, 0.06683951, ..., -0.48671934,
-0.51565756, -0.54401905],
[ 0. , 0.03343807, 0.06683875, ..., -0.4867138 ,
-0.51565169, -0.54401285],
...,
[ 0. , 0.0182217 , 0.03642301, ..., -0.26522911,
-0.28099849, -0.29645358],
[ 0. , 0.01814439, 0.03626848, ..., -0.26410385,
-0.27980632, -0.29519584],
[ 0. , 0.01806694, 0.03611368, ..., -0.26297658,
-0.27861203, -0.29393586]], shape=(364, 300))
Coordinates:
\* time (time) datetime64[us] 3kB 1999-12-15 1999-12-16 ... 2000-12-12
\* x (x) float64 2kB 0.0 0.03344 0.06689 0.1003 ... 9.9 9.933 9.967 10.0<xarray.DataArray (time: 52, x: 150)> Size: 62kB
array([[ 0.01671847, 0.08349886, 0.14990579, ..., -0.41198807,
-0.47195655, -0.52981418],
[ 0.01671269, 0.08347003, 0.14985403, ..., -0.41184582,
-0.47179359, -0.52963124],
[ 0.01670071, 0.08341016, 0.14974655, ..., -0.41155042,
-0.47145519, -0.52925136],
...,
[ 0.00968205, 0.04835611, 0.0868139 , ..., -0.23859177,
-0.2733209 , -0.30682759],
[ 0.00941742, 0.04703446, 0.08444113, ..., -0.23207067,
-0.26585059, -0.29844148],
[ 0.00914929, 0.04569531, 0.08203696, ..., -0.22546326,
-0.25828142, -0.2899444 ]], shape=(52, 150))
Coordinates:
\* time (time) datetime64[us] 416B 1999-12-18 1999-12-25 ... 2000-12-09
\* x (x) float64 1kB 0.01672 0.08361 0.1505 0.2174 ... 9.849 9.916 9.983<xarray.DataArray (time: 12, x: 150)> Size: 14kB
array([[ 0.01670121, 0.08341265, 0.14975103, ..., -0.41156272,
-0.47146929, -0.52926718],
[ 0.0165891 , 0.08285275, 0.14874584, ..., -0.40880017,
-0.46830462, -0.52571455],
[ 0.01636376, 0.08172729, 0.14672529, ..., -0.40324704,
-0.46194319, -0.51857326],
...,
[ 0.01183847, 0.05912615, 0.10614938, ..., -0.29173175,
-0.33419587, -0.37516528],
[ 0.01082401, 0.05405954, 0.09705329, ..., -0.26673283,
-0.30555813, -0.34301681],
[ 0.00973567, 0.04862391, 0.08729468, ..., -0.23991312,
-0.27483458, -0.30852683]], shape=(12, 150))
Coordinates:
\* time (time) datetime64[us] 96B 1999-12-29T12:00:00 ... 2000-11-23T12:...
\* x (x) float64 1kB 0.01672 0.08361 0.1505 0.2174 ... 9.849 9.916 9.983<xarray.DataArray (time: 52, x: 150)> Size: 62kB
array([[ 0.01671847, 0.08349886, 0.14990579, ..., -0.41198807,
-0.47195655, -0.52981418],
[ 0.01671269, 0.08347003, 0.14985403, ..., -0.41184582,
-0.47179359, -0.52963124],
[ 0.01670071, 0.08341016, 0.14974655, ..., -0.41155042,
-0.47145519, -0.52925136],
...,
[ 0.00968205, 0.04835611, 0.0868139 , ..., -0.23859177,
-0.2733209 , -0.30682759],
[ 0.00941742, 0.04703446, 0.08444113, ..., -0.23207067,
-0.26585059, -0.29844148],
[ 0.00914929, 0.04569531, 0.08203696, ..., -0.22546326,
-0.25828142, -0.2899444 ]], shape=(52, 150))
Coordinates:
\* time (time) datetime64[us] 416B 1999-12-15 1999-12-22 ... 2000-12-06
\* x (x) float64 1kB 0.01672 0.08361 0.1505 0.2174 ... 9.849 9.916 9.983<xarray.DataArray (x: 4)> Size: 32B array([100. , 91.11111111, 10.58479532, 10. ]) Coordinates: \* x (x) float64 32B 0.1 0.11 0.2 0.3
<xarray.DataArray (x: 4, y: 2)> Size: 64B
array([[200. , 200. ],
[182.22222222, 182.22222222],
[ 21.16959064, 21.16959064],
[ 20. , 20. ]])
Coordinates:
\* x (x) float64 32B 0.1 0.11 0.2 0.3
Dimensions without coordinates: y<xarray.DataArray (y: 2)> Size: 16B array([0.78, 0.98]) Dimensions without coordinates: y
<xarray.Dataset> Size: 64B
Dimensions: (degree: 2)
Coordinates:
\* degree (degree) int64 16B 1 0
Data variables:
x_matrix_rank int64 8B 2
x_singular_values (degree) float64 16B 1.358 0.3963
polyfit_coefficients (degree) float64 16B 4.0 3.0
polyfit_residuals float64 8B 1.799e-28<xarray.DataArray (x: 10)> Size: 80B array([ 3., 7., 11., 15., 19., 23., 27., 31., 35., 39.]) Dimensions without coordinates: x
<xarray.Dataset> Size: 10kB
Dimensions: (x: 100, param: 2, cov_i: 2, cov_j: 2)
Coordinates:
\* x (x) float64 800B -5.0 -4.9 -4.8 ... 4.7 4.8 4.9
\* param (param) <U2 16B 'a' 'xc'
\* cov_i (cov_i) <U2 16B 'a' 'xc'
\* cov_j (cov_j) <U2 16B 'a' 'xc'
Data variables:
var2_curvefit_coefficients (x, param) float64 2kB 3.0 -5.0 3.0 ... 3.0 4.9
var2_curvefit_covariance (x, cov_i, cov_j) float64 3kB 9.286e-14 ... 1...
var3_curvefit_coefficients (x, param) float64 2kB 0.9999 5.0 ... 1.0 -4.9
var3_curvefit_covariance (x, cov_i, cov_j) float64 3kB 5.825e-11 ... 1...
We can also fit multi-dimensional functions, and even use a wrapper function to
simultaneously fit a summation of several functions, such as this field containing
two gaussian peaks:
```ipython3
def gaussian_2d(coords, a, xc, yc, xalpha, yalpha):
x, y = coords
z = a * np.exp(
-np.square(x - xc) / 2 / np.square(xalpha)
- np.square(y - yc) / 2 / np.square(yalpha)
)
return z
def multi_peak(coords, *args):
z = np.zeros(coords[0].shape)
for i in range(len(args) // 5):
z += gaussian_2d(coords, *args[i * 5 : i * 5 + 5])
return z
x = np.arange(-5, 5, 0.1)
y = np.arange(-5, 5, 0.1)
X, Y = np.meshgrid(x, y)
n_peaks = 2
names = ["a", "xc", "yc", "xalpha", "yalpha"]
names = [f"{name}{i}" for i in range(n_peaks) for name in names]
Z = gaussian_2d((X, Y), 3, 1, 1, 2, 1) + gaussian_2d((X, Y), 2, -1, -2, 1, 1)
Z += np.random.normal(scale=0.1, size=Z.shape)
da = xr.DataArray(Z, dims=["y", "x"], coords={"y": y, "x": x})
da.curvefit(
coords=["x", "y"],
func=multi_peak,
param_names=names,
kwargs={"maxfev": 10000},
)
```
```none
<xarray.Dataset> Size: 2kB
Dimensions: (param: 10, cov_i: 10, cov_j: 10)
Coordinates:
\* param (param) <U7 280B 'a0' 'xc0' ... 'xalpha1' 'yalpha1'
\* cov_i (cov_i) <U7 280B 'a0' 'xc0' ... 'xalpha1' 'yalpha1'
\* cov_j (cov_j) <U7 280B 'a0' 'xc0' ... 'xalpha1' 'yalpha1'
Data variables:
curvefit_coefficients (param) float64 80B 3.0 1.004 1.003 ... 1.007 1.008
curvefit_covariance (cov_i, cov_j) float64 800B 3.362e-05 ... 2.125e-05
#### NOTE
This method replicates the behavior of [`scipy.optimize.curve_fit()`](https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.curve_fit.html#scipy.optimize.curve_fit).
## Broadcasting by dimension name
`DataArray` objects automatically align themselves (“broadcasting” in
the numpy parlance) by dimension name instead of axis order. With xarray, you
do not need to transpose arrays or insert dimensions of length 1 to get array
operations to work, as commonly done in numpy with [`numpy.reshape()`](https://numpy.org/doc/stable/reference/generated/numpy.reshape.html#numpy.reshape) or
[`numpy.newaxis`](https://numpy.org/doc/stable/reference/constants.html#numpy.newaxis).
This is best illustrated by a few examples. Consider two one-dimensional
arrays with different sizes aligned along different dimensions:
```ipython3
a = xr.DataArray([1, 2], [("x", ["a", "b"])])
a
```
```none
<xarray.DataArray (x: 2)> Size: 16B array([1, 2]) Coordinates: \* x (x) <U1 8B 'a' 'b'```ipython3 b = xr.DataArray([-1, -2, -3], [("y", [10, 20, 30])]) b ``` ```none
<xarray.DataArray (y: 3)> Size: 24B array([-1, -2, -3]) Coordinates: \* y (y) int64 24B 10 20 30
<xarray.DataArray (x: 2, y: 3)> Size: 48B
array([[-1, -2, -3],
[-2, -4, -6]])
Coordinates:
\* x (x) <U1 8B 'a' 'b'
\* y (y) int64 24B 10 20 30
Moreover, dimensions are always reordered to the order in which they first
appeared:
```ipython3
c = xr.DataArray(np.arange(6).reshape(3, 2), [b["y"], a["x"]])
c
```
```none
<xarray.DataArray (y: 3, x: 2)> Size: 48B
array([[0, 1],
[2, 3],
[4, 5]])
Coordinates:
\* y (y) int64 24B 10 20 30
\* x (x) <U1 8B 'a' 'b'
```ipython3
a + c
```
```none
<xarray.DataArray (x: 2, y: 3)> Size: 48B
array([[1, 3, 5],
[3, 5, 7]])
Coordinates:
\* x (x) <U1 8B 'a' 'b'
\* y (y) int64 24B 10 20 30
This means, for example, that you always subtract an array from its transpose:
```ipython3
c - c.T
```
```none
<xarray.DataArray (y: 3, x: 2)> Size: 48B
array([[0, 0],
[0, 0],
[0, 0]])
Coordinates:
\* y (y) int64 24B 10 20 30
\* x (x) <U1 8B 'a' 'b'
You can explicitly broadcast xarray data structures by using the
[`broadcast()`](../generated/xarray.broadcast.md#xarray.broadcast) function:
```ipython3
a2, b2 = xr.broadcast(a, b)
a2
```
```none
<xarray.DataArray (x: 2, y: 3)> Size: 48B
array([[1, 1, 1],
[2, 2, 2]])
Coordinates:
\* x (x) <U1 8B 'a' 'b'
\* y (y) int64 24B 10 20 30
```ipython3
b2
```
```none
<xarray.DataArray (x: 2, y: 3)> Size: 48B
array([[-1, -2, -3],
[-1, -2, -3]])
Coordinates:
\* x (x) <U1 8B 'a' 'b'
\* y (y) int64 24B 10 20 30
## Automatic alignment
Xarray enforces alignment between *index* [Coordinates](data-structures.md#coordinates) (that is,
coordinates with the same name as a dimension, marked by `*`) on objects used
in binary operations.
Similarly to pandas, this alignment is automatic for arithmetic on binary
operations. The default result of a binary operation is by the *intersection*
(not the union) of coordinate labels:
```ipython3
arr = xr.DataArray(np.arange(3), [("x", range(3))])
arr + arr[:-1]
```
```none
<xarray.DataArray (x: 2)> Size: 16B array([0, 2]) Coordinates: \* x (x) int64 16B 0 1
<xarray.DataArray (x: 1)> Size: 8B array([0]) Coordinates: \* x (x) int64 8B 0
<xarray.DataArray ()> Size: 8B
array(0)
Coordinates:
x int64 8B 0<xarray.DataArray ()> Size: 8B
array(1)
Coordinates:
x int64 8B 1<xarray.DataArray ()> Size: 8B array(1)
<xarray.DataArray ()> Size: 8B
array(1)
Coordinates:
x int64 8B 0<xarray.DataArray ()> Size: 8B
array(0)
Coordinates:
x int64 8B 0<xarray.Dataset> Size: 42B
Dimensions: (x: 3, y: 5)
Coordinates:
\* x (x) int64 24B 0 1 2
Dimensions without coordinates: y
Data variables:
x_and_y (x, y) bool 15B True True False True ... True False False False
x_only (x) bool 3B False True False<xarray.Dataset> Size: 48B
Dimensions: (y: 5)
Dimensions without coordinates: y
Data variables:
x_and_y (y) float64 40B -0.1779 0.449 -0.6525 0.2515 0.09179
x_only float64 8B -0.371<xarray.Dataset> Size: 168B
Dimensions: (x: 3, y: 5)
Coordinates:
\* x (x) int64 24B 0 1 2
Dimensions without coordinates: y
Data variables:
x_and_y (x, y) float64 120B 0.4281 0.9399 0.884 ... 0.7523 0.1212 0.3989
x_only (x) float64 24B 0.5093 0.2509 0.8548<xarray.Dataset> Size: 168B
Dimensions: (x: 3, y: 5)
Coordinates:
\* x (x) int64 24B 0 1 2
Dimensions without coordinates: y
Data variables:
x_and_y (x, y) float64 120B 0.4152 0.8075 -0.7733 ... -0.1209 -0.3884
x_only (x) float64 24B -0.4875 0.2483 -0.7544<xarray.Dataset> Size: 168B
Dimensions: (x: 3, y: 5)
Coordinates:
\* x (x) int64 24B 0 1 2
Dimensions without coordinates: y
Data variables:
x_and_y (x, y) float64 120B 0.4281 0.9399 -0.884 ... 1.248 1.879 1.601
x_only (x) float64 24B -0.5093 1.251 1.145<xarray.Dataset> Size: 168B
Dimensions: (x: 3, y: 5)
Coordinates:
\* x (x) int64 24B 0 1 2
Dimensions without coordinates: y
Data variables:
x_and_y (x, y) float64 120B 0.4281 0.9399 -0.884 ... -0.1212 -0.3989
x_only (x) float64 24B -100.5 -99.75 -100.9<xarray.DataArray (x: 4)> Size: 32B array([1, 0, 1, 4]) Dimensions without coordinates: x
<xarray.DataArray ()> Size: 8B array(3.74165739)
<xarray.Dataset> Size: 8MB
Dimensions: (time: 30, latitude: 180, longitude: 180)
Coordinates:
\* time (time) datetime64[us] 240B 2015-01-01 2015-01-02 ... 2015-01-30
\* latitude (latitude) float64 1kB 89.5 88.5 87.5 ... -87.5 -88.5 -89.5
\* longitude (longitude) int64 1kB 0 1 2 3 4 5 6 ... 174 175 176 177 178 179
Data variables:
temperature (time, latitude, longitude) float64 8MB 0.4691 ... -0.2467<xarray.Dataset> Size: 8MB
Dimensions: (time: 30, latitude: 180, longitude: 180)
Coordinates:
\* time (time) datetime64[us] 240B 2015-01-01 2015-01-02 ... 2015-01-30
\* latitude (latitude) float64 1kB 89.5 88.5 87.5 ... -87.5 -88.5 -89.5
\* longitude (longitude) int64 1kB 0 1 2 3 4 5 6 ... 174 175 176 177 178 179
Data variables:
temperature (time, latitude, longitude) float64 8MB 0.4521 ... -0.2442<xarray.DataArray 'temperature' (time: 30, latitude: 180, longitude: 180)> Size: 8MB 0.4691 -0.2829 -1.509 -1.136 1.212 ... -0.6995 -0.4183 0.8119 -0.2485 -0.2467 Coordinates: \* time (time) datetime64[us] 240B 2015-01-01 2015-01-02 ... 2015-01-30 \* latitude (latitude) float64 1kB 89.5 88.5 87.5 86.5 ... -87.5 -88.5 -89.5 \* longitude (longitude) int64 1kB 0 1 2 3 4 5 6 ... 174 175 176 177 178 179
<xarray.DataArray 'time' (time: 30)> Size: 240B 2015-01-01 2015-01-02 2015-01-03 2015-01-04 ... 2015-01-28 2015-01-29 2015-01-30 Coordinates: \* time (time) datetime64[us] 240B 2015-01-01 2015-01-02 ... 2015-01-30
<xarray.DataArray (time: 4, space: 3)> Size: 96B
array([[0.12696983, 0.96671784, 0.26047601],
[0.89723652, 0.37674972, 0.33622174],
[0.45137647, 0.84025508, 0.12310214],
[0.5430262 , 0.37301223, 0.44799682]], shape=(4, 3))
Coordinates:
\* time (time) datetime64[us] 32B 2000-01-01 2000-01-02 ... 2000-01-04
\* space (space) <U2 24B 'IA' 'IL' 'IN'
Only `data` is required; all of other arguments will be filled
in with default values:
```ipython3
xr.DataArray(data)
```
```none
<xarray.DataArray (dim_0: 4, dim_1: 3)> Size: 96B
array([[0.12696983, 0.96671784, 0.26047601],
[0.89723652, 0.37674972, 0.33622174],
[0.45137647, 0.84025508, 0.12310214],
[0.5430262 , 0.37301223, 0.44799682]], shape=(4, 3))
Dimensions without coordinates: dim_0, dim_1<xarray.DataArray (time: 4, space: 3)> Size: 96B
array([[0.12696983, 0.96671784, 0.26047601],
[0.89723652, 0.37674972, 0.33622174],
[0.45137647, 0.84025508, 0.12310214],
[0.5430262 , 0.37301223, 0.44799682]], shape=(4, 3))
Coordinates:
\* time (time) datetime64[us] 32B 2000-01-01 2000-01-02 ... 2000-01-04
\* space (space) <U2 24B 'IA' 'IL' 'IN'
As a dictionary:
```ipython3
xr.DataArray(
data,
coords={
"time": times,
"space": locs,
"const": 42,
"ranking": ("space", [1, 2, 3]),
},
dims=["time", "space"],
)
```
```none
<xarray.DataArray (time: 4, space: 3)> Size: 96B
array([[0.12696983, 0.96671784, 0.26047601],
[0.89723652, 0.37674972, 0.33622174],
[0.45137647, 0.84025508, 0.12310214],
[0.5430262 , 0.37301223, 0.44799682]], shape=(4, 3))
Coordinates:
\* time (time) datetime64[us] 32B 2000-01-01 2000-01-02 ... 2000-01-04
\* space (space) <U2 24B 'IA' 'IL' 'IN'
ranking (space) int64 24B 1 2 3
const int64 8B 42
As a dictionary with coords across multiple dimensions:
```ipython3
xr.DataArray(
data,
coords={
"time": times,
"space": locs,
"const": 42,
"ranking": (("time", "space"), np.arange(12).reshape(4, 3)),
},
dims=["time", "space"],
)
```
```none
<xarray.DataArray (time: 4, space: 3)> Size: 96B
array([[0.12696983, 0.96671784, 0.26047601],
[0.89723652, 0.37674972, 0.33622174],
[0.45137647, 0.84025508, 0.12310214],
[0.5430262 , 0.37301223, 0.44799682]], shape=(4, 3))
Coordinates:
\* time (time) datetime64[us] 32B 2000-01-01 2000-01-02 ... 2000-01-04
\* space (space) <U2 24B 'IA' 'IL' 'IN'
ranking (time, space) int64 96B 0 1 2 3 4 5 6 7 8 9 10 11
const int64 8B 42
If you create a `DataArray` by supplying a pandas
[`Series`](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html#pandas.Series), [`DataFrame`](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html#pandas.DataFrame) or
`pandas.Panel`, any non-specified arguments in the
`DataArray` constructor will be filled in from the pandas object:
```ipython3
df = pd.DataFrame({"x": [0, 1], "y": [2, 3]}, index=["a", "b"])
df.index.name = "abc"
df.columns.name = "xyz"
df
```
```none
xyz x y
abc
a 0 2
b 1 3
```
| xyz | x | y |
|---|---|---|
| abc | ||
| a | 0 | 2 |
| b | 1 | 3 |
<xarray.DataArray (abc: 2, xyz: 2)> Size: 32B
array([[0, 2],
[1, 3]])
Coordinates:
\* abc (abc) object 16B 'a' 'b'
\* xyz (xyz) object 16B 'x' 'y'<xarray.DataArray 'foo' (time: 4, space: 3)> Size: 96B
array([[0.12696983, 0.96671784, 0.26047601],
[0.89723652, 0.37674972, 0.33622174],
[0.45137647, 0.84025508, 0.12310214],
[0.5430262 , 0.37301223, 0.44799682]], shape=(4, 3))
Coordinates:
\* time (time) datetime64[us] 32B 2000-01-01 2000-01-02 ... 2000-01-04
\* space (space) <U2 24B 'IA' 'IL' 'IN'
Attributes:
units: meters
The [`rename()`](../generated/xarray.DataArray.rename.md#xarray.DataArray.rename) method is another option, returning a
new data array:
```ipython3
foo.rename("bar")
```
```none
<xarray.DataArray 'bar' (time: 4, space: 3)> Size: 96B
array([[0.12696983, 0.96671784, 0.26047601],
[0.89723652, 0.37674972, 0.33622174],
[0.45137647, 0.84025508, 0.12310214],
[0.5430262 , 0.37301223, 0.44799682]], shape=(4, 3))
Coordinates:
\* time (time) datetime64[us] 32B 2000-01-01 2000-01-02 ... 2000-01-04
\* space (space) <U2 24B '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:
```ipython3
foo.coords["time"]
```
```none
<xarray.DataArray 'time' (time: 4)> Size: 32B
array(['2000-01-01T00:00:00.000000', '2000-01-02T00:00:00.000000',
'2000-01-03T00:00:00.000000', '2000-01-04T00:00:00.000000'],
dtype='datetime64[us]')
Coordinates:
\* time (time) datetime64[us] 32B 2000-01-01 2000-01-02 ... 2000-01-04<xarray.DataArray 'time' (time: 4)> Size: 32B
array(['2000-01-01T00:00:00.000000', '2000-01-02T00:00:00.000000',
'2000-01-03T00:00:00.000000', '2000-01-04T00:00:00.000000'],
dtype='datetime64[us]')
Coordinates:
\* time (time) datetime64[us] 32B 2000-01-01 2000-01-02 ... 2000-01-04<xarray.Dataset> Size: 552B
Dimensions: (loc: 2, instrument: 3, time: 4)
Coordinates:
lon (loc) float64 16B -99.83 -99.32
lat (loc) float64 16B 42.25 42.21
\* instrument (instrument) <U8 96B 'manufac1' 'manufac2' 'manufac3'
\* time (time) datetime64[us] 32B 2014-09-06 ... 2014-09-09
reference_time datetime64[us] 8B 2014-09-05
Dimensions without coordinates: loc
Data variables:
temperature (loc, instrument, time) float64 192B 29.11 18.2 ... 9.063
precipitation (loc, instrument, time) float64 192B 4.562 5.684 ... 1.613
Here we pass [`xarray.DataArray`](../generated/xarray.DataArray.md#xarray.DataArray) objects or a pandas object as values
in the dictionary:
```ipython3
xr.Dataset(dict(bar=foo))
```
```none
<xarray.Dataset> Size: 152B
Dimensions: (time: 4, space: 3)
Coordinates:
\* time (time) datetime64[us] 32B 2000-01-01 2000-01-02 ... 2000-01-04
\* space (space) <U2 24B 'IA' 'IL' 'IN'
Data variables:
bar (time, space) float64 96B 0.127 0.9667 0.2605 ... 0.543 0.373 0.448
```ipython3
xr.Dataset(dict(bar=foo.to_pandas()))
```
```none
<xarray.Dataset> Size: 152B
Dimensions: (time: 4, space: 3)
Coordinates:
\* time (time) datetime64[us] 32B 2000-01-01 2000-01-02 ... 2000-01-04
\* space (space) object 24B 'IA' 'IL' 'IN'
Data variables:
bar (time, space) float64 96B 0.127 0.9667 0.2605 ... 0.543 0.373 0.448<xarray.DataArray 'temperature' (loc: 2, instrument: 3, time: 4)> Size: 192B
array([[[29.11241877, 18.20125767, 22.82990387, 32.92714559],
[29.94046392, 7.18177696, 22.60070734, 13.78914233],
[14.17424919, 18.28478802, 16.15234857, 26.63418806]],
[[21.0883018 , 15.97340013, 18.55090586, 17.66939462],
[26.95263259, 13.35873389, 17.50454161, 8.16723409],
[-5.42391853, 20.22894876, 21.91548959, 9.06267984]]],
shape=(2, 3, 4))
Coordinates:
lon (loc) float64 16B -99.83 -99.32
lat (loc) float64 16B 42.25 42.21
\* instrument (instrument) <U8 96B 'manufac1' 'manufac2' 'manufac3'
\* time (time) datetime64[us] 32B 2014-09-06 ... 2014-09-09
reference_time datetime64[us] 8B 2014-09-05
Dimensions without coordinates: loc
Valid keys include each listed coordinate and data variable.
Data and coordinate variables are also contained separately in the
[`data_vars`](../generated/xarray.Dataset.data_vars.md#xarray.Dataset.data_vars) and [`coords`](../generated/xarray.Dataset.coords.md#xarray.Dataset.coords)
dictionary-like attributes:
```ipython3
ds.data_vars
```
```none
Data variables:
temperature (loc, instrument, time) float64 192B 29.11 18.2 ... 9.063
precipitation (loc, instrument, time) float64 192B 4.562 5.684 ... 1.613
```
```ipython3
ds.coords
```
```none
Coordinates:
lon (loc) float64 16B -99.83 -99.32
lat (loc) float64 16B 42.25 42.21
* instrument (instrument) <xarray.Dataset> Size: 552B
Dimensions: (loc: 2, instrument: 3, time: 4)
Coordinates:
lon (loc) float64 16B -99.83 -99.32
lat (loc) float64 16B 42.25 42.21
\* instrument (instrument) <U8 96B 'manufac1' 'manufac2' 'manufac3'
\* time (time) datetime64[us] 32B 2014-09-06 ... 2014-09-09
reference_time datetime64[us] 8B 2014-09-05
Dimensions without coordinates: loc
Data variables:
temperature (loc, instrument, time) float64 192B 29.11 18.2 ... 9.063
precipitation (loc, instrument, time) float64 192B 4.562 5.684 ... 1.613
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`](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray) objects.
As a useful shortcut, you can use attribute style access for reading (but not
setting) variables and attributes:
```ipython3
ds.temperature
```
```none
<xarray.DataArray 'temperature' (loc: 2, instrument: 3, time: 4)> Size: 192B
array([[[29.11241877, 18.20125767, 22.82990387, 32.92714559],
[29.94046392, 7.18177696, 22.60070734, 13.78914233],
[14.17424919, 18.28478802, 16.15234857, 26.63418806]],
[[21.0883018 , 15.97340013, 18.55090586, 17.66939462],
[26.95263259, 13.35873389, 17.50454161, 8.16723409],
[-5.42391853, 20.22894876, 21.91548959, 9.06267984]]],
shape=(2, 3, 4))
Coordinates:
lon (loc) float64 16B -99.83 -99.32
lat (loc) float64 16B 42.25 42.21
\* instrument (instrument) <U8 96B 'manufac1' 'manufac2' 'manufac3'
\* time (time) datetime64[us] 32B 2014-09-06 ... 2014-09-09
reference_time datetime64[us] 8B 2014-09-05
Dimensions without coordinates: loc
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:
```ipython3
ds = xr.Dataset()
ds["temperature"] = (("loc", "instrument", "time"), temperature)
ds["temperature_double"] = (("loc", "instrument", "time"), temperature * 2)
ds["precipitation"] = (("loc", "instrument", "time"), precipitation)
ds.coords["lat"] = (("loc",), lat)
ds.coords["lon"] = (("loc",), lon)
ds.coords["time"] = pd.date_range("2014-09-06", periods=4)
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()`](../generated/xarray.Dataset.update.md#xarray.Dataset.update). Note that assigning a `DataArray` or pandas
object to a `Dataset` variable using `__setitem__` or `update` will
[automatically align](combining.md#update) the array(s) to the original
dataset’s indexes.
You can copy a `Dataset` by calling the [`copy()`](../generated/xarray.Dataset.copy.md#xarray.Dataset.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`](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#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_vars()`](../generated/xarray.Dataset.drop_vars.md#xarray.Dataset.drop_vars) methods to return a new `Dataset`. These
operations keep around coordinates:
```ipython3
ds[["temperature"]]
```
```none
<xarray.Dataset> Size: 264B
Dimensions: (loc: 2, instrument: 3, time: 4)
Coordinates:
lat (loc) float64 16B 42.25 42.21
lon (loc) float64 16B -99.83 -99.32
\* time (time) datetime64[us] 32B 2014-09-06 ... 2014-09-09
reference_time datetime64[us] 8B 2014-09-05
Dimensions without coordinates: loc, instrument
Data variables:
temperature (loc, instrument, time) float64 192B 29.11 18.2 ... 9.063<xarray.Dataset> Size: 456B
Dimensions: (loc: 2, instrument: 3, time: 4)
Coordinates:
lat (loc) float64 16B 42.25 42.21
lon (loc) float64 16B -99.83 -99.32
\* time (time) datetime64[us] 32B 2014-09-06 ... 2014-09-09
reference_time datetime64[us] 8B 2014-09-05
Dimensions without coordinates: loc, instrument
Data variables:
temperature (loc, instrument, time) float64 192B 29.11 ... 9.063
temperature_double (loc, instrument, time) float64 192B 58.22 ... 18.13<xarray.Dataset> Size: 456B
Dimensions: (loc: 2, instrument: 3, time: 4)
Coordinates:
lat (loc) float64 16B 42.25 42.21
lon (loc) float64 16B -99.83 -99.32
\* time (time) datetime64[us] 32B 2014-09-06 ... 2014-09-09
reference_time datetime64[us] 8B 2014-09-05
Dimensions without coordinates: loc, instrument
Data variables:
temperature_double (loc, instrument, time) float64 192B 58.22 ... 18.13
precipitation (loc, instrument, time) float64 192B 4.562 ... 1.613<xarray.Dataset> Size: 40B
Dimensions: (loc: 2)
Coordinates:
lat (loc) float64 16B 42.25 42.21
lon (loc) float64 16B -99.83 -99.32
reference_time datetime64[us] 8B 2014-09-05
Dimensions without coordinates: loc
Data variables:
\*empty\*<xarray.Dataset> Size: 840B
Dimensions: (loc: 2, instrument: 3, time: 4)
Coordinates:
lat (loc) float64 16B 42.25 42.21
lon (loc) float64 16B -99.83 -99.32
\* time (time) datetime64[us] 32B 2014-09-06 ... 2014-09-09
reference_time datetime64[us] 8B 2014-09-05
Dimensions without coordinates: loc, instrument
Data variables:
temperature (loc, instrument, time) float64 192B 29.11 ... 9.063
temperature_double (loc, instrument, time) float64 192B 58.22 ... 18.13
precipitation (loc, instrument, time) float64 192B 4.562 ... 1.613
temperature2 (loc, instrument, time) float64 192B 58.22 ... 18.13<xarray.Dataset> Size: 648B
Dimensions: (loc: 2, instrument: 3, time: 4)
Coordinates:
lat (loc) float64 16B 42.25 42.21
lon (loc) float64 16B -99.83 -99.32
\* time (time) datetime64[us] 32B 2014-09-06 ... 2014-09-09
reference_time datetime64[us] 8B 2014-09-05
Dimensions without coordinates: loc, instrument
Data variables:
temp (loc, instrument, time) float64 192B 29.11 ... 9.063
temperature_double (loc, instrument, time) float64 192B 58.22 ... 18.13
precip (loc, instrument, time) float64 192B 4.562 ... 1.613<xarray.Dataset> Size: 680B
Dimensions: (loc: 2, instrument: 3, day: 4)
Coordinates:
lat (loc) float64 16B 42.25 42.21
lon (loc) float64 16B -99.83 -99.32
\* day (day) int64 32B 6 7 8 9
time (day) datetime64[us] 32B 2014-09-06 ... 2014-09-09
reference_time datetime64[us] 8B 2014-09-05
Dimensions without coordinates: loc, instrument
Data variables:
temperature (loc, instrument, day) float64 192B 29.11 18.2 ... 9.063
temperature_double (loc, instrument, day) float64 192B 58.22 36.4 ... 18.13
precipitation (loc, instrument, day) float64 192B 4.562 ... 1.613<xarray.DataTree 'root'>
Group: /
Dimensions: ()
Data variables:
foo <U6 24B 'orange'
At this point we have created a single node datatree with no parent and no children.
```ipython3
print(dt.parent is None)
dt.children
```
```none
True
```
```none
Frozen({})
```
We can add a second node to this tree, assigning it to the parent node `dt`:
```ipython3
dataset2 = xr.Dataset({"bar": 0}, coords={"y": ("y", [0, 1, 2])})
dt2 = xr.DataTree(name="a", dataset=dataset2)
# Add the child Datatree to the root node
dt.children = {"child-node": dt2}
dt
```
```none
<xarray.DataTree 'root'>
Group: /
│ Dimensions: ()
│ Data variables:
│ foo <U6 24B 'orange'
└── Group: /child-node
Dimensions: (y: 3)
Coordinates:
\* y (y) int64 24B 0 1 2
Data variables:
bar int64 8B 0
More idiomatically you can create a tree from a dictionary of `Datasets` and
`DataTrees`. In this case we add a new node under `dt["child-node"]` by
providing the explicit path under `"child-node"` as the dictionary key:
```ipython3
# create a third Dataset
ds3 = xr.Dataset({"zed": np.nan})
# create a tree from a dictionary of DataTrees and Datasets
dt = xr.DataTree.from_dict({"/": dt, "/child-node/new-zed-node": ds3})
```
We have created a tree with three nodes in it:
```ipython3
dt
```
```none
<xarray.DataTree>
Group: /
│ Dimensions: ()
│ Data variables:
│ foo <U6 24B 'orange'
└── Group: /child-node
│ Dimensions: (y: 3)
│ Coordinates:
│ \* y (y) int64 24B 0 1 2
│ Data variables:
│ bar int64 8B 0
└── Group: /child-node/new-zed-node
Dimensions: ()
Data variables:
zed float64 8B nan
Consistency checks are enforced. For instance, if we try to create a cycle,
where the root node is also a child of a descendant, the constructor will raise
an ([`InvalidTreeError`](../generated/xarray.InvalidTreeError.md#xarray.InvalidTreeError)):
```ipython3
dt["child-node"].children = {"new-child": dt}
```
```ipythontb
InvalidTreeError: Cannot set parent, as intended parent is already a descendant of this node.
```
Alternatively you can also create a [`DataTree`](../generated/xarray.DataTree.md#xarray.DataTree) object from:
- A dictionary mapping directory-like paths to either [`DataTree`](../generated/xarray.DataTree.md#xarray.DataTree) nodes or data, using [`xarray.DataTree.from_dict()`](../generated/xarray.DataTree.from_dict.md#xarray.DataTree.from_dict),
- A well formed netCDF or Zarr file on disk with [`open_datatree()`](../generated/xarray.open_datatree.md#xarray.open_datatree). See [reading and writing files](io.md#io).
For data files with groups that do not align see
[`xarray.open_groups()`](../generated/xarray.open_groups.md#xarray.open_groups) or target each group individually
[`xarray.open_dataset(group='groupname')`](../generated/xarray.open_dataset.md#xarray.open_dataset). For
more information about coordinate alignment see [DataTree Inheritance](#datatree-inheritance)
### DataTree Contents
Like [`Dataset`](../generated/xarray.Dataset.md#xarray.Dataset), [`DataTree`](../generated/xarray.DataTree.md#xarray.DataTree) implements the python mapping interface,
but with values given by either [`DataArray`](../generated/xarray.DataArray.md#xarray.DataArray) objects or other
[`DataTree`](../generated/xarray.DataTree.md#xarray.DataTree) objects.
```ipython3
dt["child-node"]
```
```none
<xarray.DataTree 'child-node'>
Group: /child-node
│ Dimensions: (y: 3)
│ Coordinates:
│ \* y (y) int64 24B 0 1 2
│ Data variables:
│ bar int64 8B 0
└── Group: /child-node/new-zed-node
Dimensions: ()
Data variables:
zed float64 8B nan<xarray.DataArray 'foo' ()> Size: 24B
array('orange', dtype='<U6')
Iterating over keys will iterate over both the names of variables and child nodes.
We can also access all the data in a single node, and its inherited coordinates, through a dataset-like view
```ipython3
dt["child-node"].dataset
```
```none
<xarray.DatasetView> Size: 32B
Dimensions: (y: 3)
Coordinates:
\* y (y) int64 24B 0 1 2
Data variables:
bar int64 8B 0<xarray.Dataset> Size: 32B
Dimensions: (y: 3)
Coordinates:
\* y (y) int64 24B 0 1 2
Data variables:
bar int64 8B 0<xarray.DataTree 'root'>
Group: /
│ Dimensions: ()
│ Data variables:
│ foo <U6 24B 'orange'
└── Group: /child-node
│ Dimensions: (y: 3)
│ Coordinates:
│ \* y (y) int64 24B 0 1 2
│ Data variables:
│ bar int64 8B 0
└── Group: /child-node/new-zed-node
Dimensions: ()
Data variables:
zed float64 8B nan
To change the variables in a node of a [`DataTree`](../generated/xarray.DataTree.md#xarray.DataTree), you can use all the
standard dictionary methods, including `values`, `items`, `__delitem__`,
`get` and [`xarray.DataTree.update()`](../generated/xarray.DataTree.update.md#xarray.DataTree.update).
Note that assigning a [`DataTree`](../generated/xarray.DataTree.md#xarray.DataTree) object to a [`DataTree`](../generated/xarray.DataTree.md#xarray.DataTree) variable using
`__setitem__` or [`update()`](../generated/xarray.DataTree.update.md#xarray.DataTree.update) will [automatically align](combining.md#update) the
array(s) to the original node’s indexes.
If you copy a [`DataTree`](../generated/xarray.DataTree.md#xarray.DataTree) using the `copy()` function or the
[`xarray.DataTree.copy()`](../generated/xarray.DataTree.copy.md#xarray.DataTree.copy) method it will copy the subtree,
meaning that node and children below it, but no parents above it.
Like for [`Dataset`](../generated/xarray.Dataset.md#xarray.Dataset), this copy is shallow by default, but you can copy all the
underlying data arrays by calling `dt.copy(deep=True)`.
### DataTree Inheritance
DataTree implements a simple inheritance mechanism. Coordinates, dimensions and their
associated indices are propagated from downward starting from the root node to
all descendent nodes. Coordinate inheritance was inspired by the NetCDF-CF
inherited dimensions, but DataTree’s inheritance is slightly stricter yet
easier to reason about.
The constraint that this puts on a DataTree is that dimensions and indices that
are inherited must be aligned with any direct descendant node’s existing
dimension or index. This allows descendants to use dimensions defined in
ancestor nodes, without duplicating that information. But as a consequence, if
a dimension-name is defined in on a node and that same dimension-name
exists in one of its ancestors, they must align (have the same index and
size).
Some examples:
```ipython3
# Set up coordinates
time = xr.DataArray(data=["2022-01", "2023-01"], dims="time")
stations = xr.DataArray(data=list("abcdef"), dims="station")
lon = [-100, -80, -60]
lat = [10, 20, 30]
# Set up fake data
wind_speed = xr.DataArray(np.ones((2, 6)) * 2, dims=("time", "station"))
pressure = xr.DataArray(np.ones((2, 6)) * 3, dims=("time", "station"))
air_temperature = xr.DataArray(np.ones((2, 6)) * 4, dims=("time", "station"))
dewpoint = xr.DataArray(np.ones((2, 6)) * 5, dims=("time", "station"))
infrared = xr.DataArray(np.ones((2, 3, 3)) * 6, dims=("time", "lon", "lat"))
true_color = xr.DataArray(np.ones((2, 3, 3)) * 7, dims=("time", "lon", "lat"))
dt2 = xr.DataTree.from_dict(
{
"/": xr.Dataset(
coords={"time": time},
),
"/weather": xr.Dataset(
coords={"station": stations},
data_vars={
"wind_speed": wind_speed,
"pressure": pressure,
},
),
"/weather/temperature": xr.Dataset(
data_vars={
"air_temperature": air_temperature,
"dewpoint": dewpoint,
},
),
"/satellite": xr.Dataset(
coords={"lat": lat, "lon": lon},
data_vars={
"infrared": infrared,
"true_color": true_color,
},
),
},
)
dt2
```
```none
<xarray.DataTree>
Group: /
│ Dimensions: (time: 2)
│ Coordinates:
│ \* time (time) <U7 56B '2022-01' '2023-01'
├── Group: /weather
│ │ Dimensions: (station: 6, time: 2)
│ │ Coordinates:
│ │ \* station (station) <U1 24B 'a' 'b' 'c' 'd' 'e' 'f'
│ │ Data variables:
│ │ wind_speed (time, station) float64 96B 2.0 2.0 2.0 2.0 ... 2.0 2.0 2.0 2.0
│ │ pressure (time, station) float64 96B 3.0 3.0 3.0 3.0 ... 3.0 3.0 3.0 3.0
│ └── Group: /weather/temperature
│ Dimensions: (time: 2, station: 6)
│ Data variables:
│ air_temperature (time, station) float64 96B 4.0 4.0 4.0 4.0 ... 4.0 4.0 4.0
│ dewpoint (time, station) float64 96B 5.0 5.0 5.0 5.0 ... 5.0 5.0 5.0
└── Group: /satellite
Dimensions: (lat: 3, lon: 3, time: 2)
Coordinates:
\* lat (lat) int64 24B 10 20 30
\* lon (lon) int64 24B -100 -80 -60
Data variables:
infrared (time, lon, lat) float64 144B 6.0 6.0 6.0 6.0 ... 6.0 6.0 6.0
true_color (time, lon, lat) float64 144B 7.0 7.0 7.0 7.0 ... 7.0 7.0 7.0
Here there are four different coordinate variables, which apply to variables in the DataTree in different ways:
`time` is a shared coordinate used by both `weather` and `satellite` variables
`station` is used only for `weather` variables
`lat` and `lon` are only use for `satellite` images
Coordinate variables are inherited to descendent nodes, which is only possible because
variables at different levels of a hierarchical DataTree are always
aligned. Placing the `time` variable at the root node automatically indicates
that it applies to all descendent nodes. Similarly, `station` is in the base
`weather` node, because it applies to all weather variables, both directly in
`weather` and in the `temperature` sub-tree. Notice the inherited coordinates are
explicitly shown in the tree representation under `Inherited coordinates:`.
```ipython3
dt2["/weather"]
```
```none
<xarray.DataTree 'weather'>
Group: /weather
│ Dimensions: (time: 2, station: 6)
│ Coordinates:
│ \* station (station) <U1 24B 'a' 'b' 'c' 'd' 'e' 'f'
│ Inherited coordinates:
│ \* time (time) <U7 56B '2022-01' '2023-01'
│ Data variables:
│ wind_speed (time, station) float64 96B 2.0 2.0 2.0 2.0 ... 2.0 2.0 2.0 2.0
│ pressure (time, station) float64 96B 3.0 3.0 3.0 3.0 ... 3.0 3.0 3.0 3.0
└── Group: /weather/temperature
Dimensions: (time: 2, station: 6)
Data variables:
air_temperature (time, station) float64 96B 4.0 4.0 4.0 4.0 ... 4.0 4.0 4.0
dewpoint (time, station) float64 96B 5.0 5.0 5.0 5.0 ... 5.0 5.0 5.0
Accessing any of the lower level trees through the [`.dataset`](../generated/xarray.DataTree.dataset.md#xarray.DataTree.dataset) property
automatically includes coordinates from higher levels (e.g., `time` and
`station`):
```ipython3
dt2["/weather/temperature"].dataset
```
```none
<xarray.DatasetView> Size: 272B
Dimensions: (time: 2, station: 6)
Coordinates:
\* time (time) <U7 56B '2022-01' '2023-01'
\* station (station) <U1 24B 'a' 'b' 'c' 'd' 'e' 'f'
Data variables:
air_temperature (time, station) float64 96B 4.0 4.0 4.0 4.0 ... 4.0 4.0 4.0
dewpoint (time, station) float64 96B 5.0 5.0 5.0 5.0 ... 5.0 5.0 5.0
Similarly, when you retrieve a Dataset through [`to_dataset()`](../generated/xarray.DataTree.to_dataset.md#xarray.DataTree.to_dataset) , the inherited coordinates are
included by default unless you exclude them with the `inherit` flag:
```ipython3
dt2["/weather/temperature"].to_dataset()
```
```none
<xarray.Dataset> Size: 272B
Dimensions: (time: 2, station: 6)
Coordinates:
\* time (time) <U7 56B '2022-01' '2023-01'
\* station (station) <U1 24B 'a' 'b' 'c' 'd' 'e' 'f'
Data variables:
air_temperature (time, station) float64 96B 4.0 4.0 4.0 4.0 ... 4.0 4.0 4.0
dewpoint (time, station) float64 96B 5.0 5.0 5.0 5.0 ... 5.0 5.0 5.0
```ipython3
dt2["/weather/temperature"].to_dataset(inherit=False)
```
```none
<xarray.Dataset> Size: 192B
Dimensions: (time: 2, station: 6)
Dimensions without coordinates: time, station
Data variables:
air_temperature (time, station) float64 96B 4.0 4.0 4.0 4.0 ... 4.0 4.0 4.0
dewpoint (time, station) float64 96B 5.0 5.0 5.0 5.0 ... 5.0 5.0 5.0<xarray.Dataset> Size: 680B
Dimensions: (loc: 2, instrument: 3, time: 4)
Coordinates:
\* time (time) datetime64[us] 32B 2014-09-06 ... 2014-09-09
Dimensions without coordinates: loc, instrument
Data variables:
temperature (loc, instrument, time) float64 192B 29.11 ... 9.063
temperature_double (loc, instrument, time) float64 192B 58.22 ... 18.13
precipitation (loc, instrument, time) float64 192B 4.562 ... 1.613
lat (loc) float64 16B 42.25 42.21
lon (loc) float64 16B -99.83 -99.32
reference_time datetime64[us] 8B 2014-09-05
day (time) int64 32B 6 7 8 9<xarray.Dataset> Size: 680B
Dimensions: (loc: 2, instrument: 3, time: 4)
Coordinates:
lat (loc) float64 16B 42.25 42.21
lon (loc) float64 16B -99.83 -99.32
\* time (time) datetime64[us] 32B 2014-09-06 ... 2014-09-09
temperature (loc, instrument, time) float64 192B 29.11 ... 9.063
precipitation (loc, instrument, time) float64 192B 4.562 ... 1.613
day (time) int64 32B 6 7 8 9
reference_time datetime64[us] 8B 2014-09-05
Dimensions without coordinates: loc, instrument
Data variables:
temperature_double (loc, instrument, time) float64 192B 58.22 ... 18.13<xarray.DataArray 'temperature' (loc: 2, instrument: 3, time: 4)> Size: 192B
array([[[29.11241877, 18.20125767, 22.82990387, 32.92714559],
[29.94046392, 7.18177696, 22.60070734, 13.78914233],
[14.17424919, 18.28478802, 16.15234857, 26.63418806]],
[[21.0883018 , 15.97340013, 18.55090586, 17.66939462],
[26.95263259, 13.35873389, 17.50454161, 8.16723409],
[-5.42391853, 20.22894876, 21.91548959, 9.06267984]]],
shape=(2, 3, 4))
Coordinates:
\* time (time) datetime64[us] 32B 2014-09-06 2014-09-07 ... 2014-09-09
Dimensions without coordinates: loc, instrument<xarray.Dataset> Size: 104B
Dimensions: (loc: 2, time: 4)
Coordinates:
lat (loc) float64 16B 42.25 42.21
lon (loc) float64 16B -99.83 -99.32
\* time (time) datetime64[us] 32B 2014-09-06 ... 2014-09-09
day (time) int64 32B 6 7 8 9
reference_time datetime64[us] 8B 2014-09-05
Dimensions without coordinates: loc
Data variables:
\*empty\*<xarray.Dataset> Size: 80B
Dimensions: (time: 4, z: 1)
Coordinates:
\* time (time) datetime64[us] 32B 2014-09-06 ... 2014-09-09
day (time) int64 32B 6 7 8 9
\* z (z) int64 8B 10
reference_time datetime64[us] 8B 2014-09-05
Data variables:
\*empty\*<xarray.DataArray (spec: 4)> Size: 32B array([0.65310833, 0.2532916 , 0.46631077, 0.24442559]) Coordinates: \* spec (spec) object 32B MultiIndex \* band (spec) object 32B 'R' 'R' 'V' 'V' \* wn (spec) float64 32B 0.1 0.2 0.7 0.9
<xarray.DataArray 'band' (spec: 4)> Size: 32B [4 values with dtype=object] Coordinates: \* spec (spec) object 32B MultiIndex \* band (spec) object 32B 'R' 'R' 'V' 'V' \* wn (spec) float64 32B 0.1 0.2 0.7 0.9
<xarray.DataArray 'wn' (spec: 4)> Size: 32B [4 values with dtype=float64] Coordinates: \* spec (spec) object 32B MultiIndex \* band (spec) object 32B 'R' 'R' 'V' 'V' \* wn (spec) float64 32B 0.1 0.2 0.7 0.9
|
||||||||||||||||
| Format | coo |
|---|---|
| Data Type | float64 |
| Shape | (10, 10) |
| nnz | 14 |
| Density | 0.14 |
| Read-only | True |
| Size | 336 |
| Storage ratio | 0.42 |
<xarray.Dataset> Size: 496B
Dimensions: (x: 20, y: 10, z: 10)
Dimensions without coordinates: x, y, z
Data variables:
a (x) float64 160B dask.array<chunksize=(2,), meta=np.ndarray>
b (y, z) float64 336B <COO: nnz=14, fill_value=0.0>| Format | coo |
|---|---|
| Data Type | uint8 |
| Shape | (4, 4) |
| nnz | 4 |
| Density | 0.25 |
| Read-only | True |
| Size | 68 |
| Storage ratio | 4.25 |
| Format | coo |
|---|---|
| Data Type | uint8 |
| Shape | (4, 4) |
| nnz | 0 |
| Density | 0.0 |
| Read-only | True |
| Size | 0 |
| Storage ratio | 0.00 |
| Format | coo |
|---|---|
| Data Type | uint64 |
| Shape | (4,) |
| nnz | 4 |
| Density | 1.0 |
| Read-only | True |
| Size | 64 |
| Storage ratio | 2.00 |
| Format | coo |
|---|---|
| Data Type | uint64 |
| Shape | (4,) |
| nnz | 4 |
| Density | 1.0 |
| Read-only | True |
| Size | 64 |
| Storage ratio | 2.00 |
<xarray.DataArray (i: 4, j: 4)> Size: 68B <COO: shape=(4, 4), dtype=uint8, nnz=4, fill_value=0> Dimensions without coordinates: i, j
| Format | coo |
|---|---|
| Data Type | uint8 |
| Shape | (4, 4) |
| nnz | 4 |
| Density | 0.25 |
| Read-only | True |
| Size | 68 |
| Storage ratio | 4.25 |
<xarray.DataArray (i: 4)> Size: 64B <COO: shape=(4,), dtype=uint64, nnz=4, fill_value=0> Dimensions without coordinates: i
<xarray.DataArray (i: 4, j: 4)> Size: 16B
array([[1, 0, 0, 0],
[0, 1, 0, 0],
[0, 0, 1, 0],
[0, 0, 0, 1]], dtype=uint8)
Dimensions without coordinates: i, j<xarray.Dataset> Size: 144B
Dimensions: (x: 4, y: 3)
Coordinates:
\* x (x) int64 32B 10 20 30 40
letters (x) <U1 16B 'a' 'b' 'b' 'a'
Dimensions without coordinates: y
Data variables:
foo (x, y) float64 96B 0.127 0.9667 0.2605 0.8972 ... 0.543 0.373 0.448
If we groupby the name of a variable or coordinate in a dataset (we can also
use a DataArray directly), we get back a `GroupBy` object:
```ipython3
ds.groupby("letters")
```
```none
<xarray.Dataset> Size: 72B
Dimensions: (x: 2, y: 3)
Coordinates:
\* x (x) int64 16B 20 30
letters (x) <U1 8B 'b' 'b'
Dimensions without coordinates: y
Data variables:
foo (x, y) float64 48B 0.8972 0.3767 0.3362 0.4514 0.8403 0.1231
To group by multiple variables, see [this section](#groupby-multiple).
## Binning
Sometimes you don’t want to use all the unique values to determine the groups
but instead want to “bin” the data into coarser groups. You could always create
a customized coordinate, but xarray facilitates this via the
[`Dataset.groupby_bins()`](../generated/xarray.Dataset.groupby_bins.md#xarray.Dataset.groupby_bins) method.
```ipython3
x_bins = [0, 25, 50]
ds.groupby_bins("x", x_bins).groups
```
```none
{Interval(0, 25, closed='right'): [0, 1],
Interval(25, 50, closed='right'): [2, 3]}
```
The binning is implemented via [`pandas.cut()`](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.cut.html#pandas.cut), whose documentation details how
the bins are assigned. As seen in the example above, by default, the bins are
labeled with strings using set notation to precisely identify the bin limits. To
override this behavior, you can specify the bin labels explicitly. Here we
choose `float` labels which identify the bin centers:
```ipython3
x_bin_labels = [12.5, 37.5]
ds.groupby_bins("x", x_bins, labels=x_bin_labels).groups
```
```none
{np.float64(12.5): [0, 1], np.float64(37.5): [2, 3]}
```
## Apply
To apply a function to each group, you can use the flexible
[`core.groupby.DatasetGroupBy.map()`](../generated/xarray.core.groupby.DatasetGroupBy.map.md#xarray.core.groupby.DatasetGroupBy.map) method. The resulting objects are automatically
concatenated back together along the group axis:
```ipython3
def standardize(x):
return (x - x.mean()) / x.std()
arr.groupby("letters").map(standardize)
```
```none
<xarray.DataArray 'foo' (x: 4, y: 3)> Size: 96B
array([[-1.22977845, 1.93741005, -0.72624738],
[ 1.41979574, -0.46019243, -0.60657867],
[-0.19064205, 1.21397989, -1.3763625 ],
[ 0.33941723, -0.30180645, -0.01899499]])
Coordinates:
\* x (x) int64 32B 10 20 30 40
letters (x) <U1 16B 'a' 'b' 'b' 'a'
Dimensions without coordinates: y
GroupBy objects also have a [`core.groupby.DatasetGroupBy.reduce()`](../generated/xarray.core.groupby.DatasetGroupBy.reduce.md#xarray.core.groupby.DatasetGroupBy.reduce) method and
methods like [`core.groupby.DatasetGroupBy.mean()`](../generated/xarray.core.groupby.DatasetGroupBy.mean.md#xarray.core.groupby.DatasetGroupBy.mean) as shortcuts for applying an
aggregation function:
```ipython3
arr.groupby("letters").mean(dim="x")
```
```none
<xarray.DataArray 'foo' (letters: 2, y: 3)> Size: 48B
array([[0.33499802, 0.66986503, 0.35423642],
[0.6743065 , 0.6085024 , 0.22966194]])
Coordinates:
\* letters (letters) object 16B 'a' 'b'
Dimensions without coordinates: y<xarray.Dataset> Size: 64B
Dimensions: (x: 4)
Coordinates:
\* x (x) int64 32B 10 20 30 40
Data variables:
foo (x) float64 32B 0.3684 0.2554 0.2931 0.06957<xarray.Dataset> Size: 64B
Dimensions: (letters: 2, y: 3)
Coordinates:
\* letters (letters) object 16B 'a' 'b'
Dimensions without coordinates: y
Data variables:
foo (letters, y) float64 48B 0.127 0.9667 0.2605 0.8972 0.3767 0.3362<xarray.DataArray 'foo' (letters: 2)> Size: 16B array([0.45303315, 0.50415695]) Coordinates: \* letters (letters) object 16B 'a' 'b'
<xarray.Dataset> Size: 144B
Dimensions: (x: 4, y: 3)
Coordinates:
\* x (x) int64 32B 10 20 30 40
letters (x) <U1 16B 'a' 'b' 'b' 'a'
Dimensions without coordinates: y
Data variables:
foo (x, y) float64 96B -0.3261 0.5137 -0.1926 ... -0.08002 -0.005036
This last line is roughly equivalent to the following:
```default
results = []
for label, group in ds.groupby('letters'):
results.append(group - alt.sel(letters=label))
xr.concat(results, dim='x')
```
## Multidimensional Grouping
Many datasets have a multidimensional coordinate variable (e.g. longitude)
which is different from the logical grid dimensions (e.g. nx, ny). Such
variables are valid under the [CF conventions](https://cfconventions.org/cf-conventions/v1.6.0/cf-conventions.html#_two_dimensional_latitude_longitude_coordinate_variables). Xarray supports groupby
operations over multidimensional coordinate variables:
```ipython3
da = xr.DataArray(
[[0, 1], [2, 3]],
coords={
"lon": (["ny", "nx"], [[30, 40], [40, 50]]),
"lat": (["ny", "nx"], [[10, 10], [20, 20]]),
},
dims=["ny", "nx"],
)
da
```
```none
<xarray.DataArray (ny: 2, nx: 2)> Size: 32B
array([[0, 1],
[2, 3]])
Coordinates:
lon (ny, nx) int64 32B 30 40 40 50
lat (ny, nx) int64 32B 10 10 20 20
Dimensions without coordinates: ny, nx<xarray.DataArray (lon: 3)> Size: 24B array([0, 3, 3]) Coordinates: \* lon (lon) int64 24B 30 40 50
<xarray.DataArray (ny: 2, nx: 2)> Size: 32B
array([[ 0. , -0.5],
[ 0.5, 0. ]])
Coordinates:
lon (ny, nx) int64 32B 30 40 40 50
lat (ny, nx) int64 32B 10 10 20 20
Dimensions without coordinates: ny, nx<xarray.DataArray (lon_bins: 2)> Size: 16B array([3, 3]) Coordinates: \* lon_bins (lon_bins) interval[int64, right] 32B (0, 45] (45, 50]
<xarray.DataArray (ny: 2, nx: 2)> Size: 32B
array([[0, 1],
[2, 3]])
Coordinates:
\* ny (ny) int64 16B 0 1
\* nx (nx) int64 16B 0 1<xarray.DataArray (lat: 2, lon: 3)> Size: 48B
array([[ 0., 1., nan],
[nan, 2., 3.]])
Coordinates:
\* lat (lat) int64 16B 10 20
\* lon (lon) int64 24B 30 40 50<xarray.DataArray (lat: 2, lon: 3)> Size: 48B
array([[ 0., 1., nan],
[nan, 2., 3.]])
Coordinates:
\* lat (lat) int64 16B 10 20
\* lon (lon) int64 24B 30 40 50<xarray.Dataset> Size: 144B
Dimensions: (y: 3, x_bins: 2, letters: 2)
Coordinates:
\* x_bins (x_bins) interval[int64, right] 32B (5, 15] (15, 25]
\* letters (letters) object 16B 'a' 'b'
Dimensions without coordinates: y
Data variables:
foo (y, x_bins, letters) float64 96B 0.127 nan nan ... nan nan 0.3362<xarray.DataArray (x: 6)> Size: 48B
array([1, 4, 2, 5, 3, 6])
Coordinates:
label (x) <U1 24B 'a' 'a' 'b' 'b' 'c' 'c'
Dimensions without coordinates: x
For chunked array types (e.g. dask or cubed), shuffle may result in a more optimized communication pattern when compared to direct indexing by the appropriate indexer.
Shuffling also makes GroupBy operations on chunked arrays an embarrassingly parallel problem, and may significantly improve workloads that use `DatasetGroupBy.map()` or `DataArrayGroupBy.map()`.
# groupby.html.md
# GroupBy objects
## Dataset
| [`DatasetGroupBy`](../generated/xarray.core.groupby.DatasetGroupBy.md#xarray.core.groupby.DatasetGroupBy)(obj, groupers[, ...]) | |
|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------|
| [`DatasetGroupBy.map`](../generated/xarray.core.groupby.DatasetGroupBy.map.md#xarray.core.groupby.DatasetGroupBy.map)(func[, args, shortcut]) | Apply a function to each Dataset in the group and concatenate them together into a new Dataset. |
| [`DatasetGroupBy.reduce`](../generated/xarray.core.groupby.DatasetGroupBy.reduce.md#xarray.core.groupby.DatasetGroupBy.reduce)(func[, dim, axis, ...]) | Reduce the items in this group by applying func along some dimension(s). |
| [`DatasetGroupBy.assign`](../generated/xarray.core.groupby.DatasetGroupBy.assign.md#xarray.core.groupby.DatasetGroupBy.assign)(\*\*kwargs) | Assign data variables by group. |
| [`DatasetGroupBy.assign_coords`](../generated/xarray.core.groupby.DatasetGroupBy.assign_coords.md#xarray.core.groupby.DatasetGroupBy.assign_coords)([coords]) | Assign coordinates by group. |
| [`DatasetGroupBy.first`](../generated/xarray.core.groupby.DatasetGroupBy.first.md#xarray.core.groupby.DatasetGroupBy.first)([skipna, keep_attrs]) | Return the first element of each group along the group dimension |
| [`DatasetGroupBy.last`](../generated/xarray.core.groupby.DatasetGroupBy.last.md#xarray.core.groupby.DatasetGroupBy.last)([skipna, keep_attrs]) | Return the last element of each group along the group dimension |
| [`DatasetGroupBy.fillna`](../generated/xarray.core.groupby.DatasetGroupBy.fillna.md#xarray.core.groupby.DatasetGroupBy.fillna)(value) | Fill missing values in this object by group. |
| [`DatasetGroupBy.quantile`](../generated/xarray.core.groupby.DatasetGroupBy.quantile.md#xarray.core.groupby.DatasetGroupBy.quantile)(q[, dim, method, ...]) | Compute the qth quantile over each array in the groups and concatenate them together into a new array. |
| [`DatasetGroupBy.where`](../generated/xarray.core.groupby.DatasetGroupBy.where.md#xarray.core.groupby.DatasetGroupBy.where)(cond[, other]) | Return elements from self or other depending on cond. |
| [`DatasetGroupBy.all`](../generated/xarray.core.groupby.DatasetGroupBy.all.md#xarray.core.groupby.DatasetGroupBy.all)([dim, keep_attrs]) | Reduce this Dataset's data by applying `all` along some dimension(s). |
| [`DatasetGroupBy.any`](../generated/xarray.core.groupby.DatasetGroupBy.any.md#xarray.core.groupby.DatasetGroupBy.any)([dim, keep_attrs]) | Reduce this Dataset's data by applying `any` along some dimension(s). |
| [`DatasetGroupBy.count`](../generated/xarray.core.groupby.DatasetGroupBy.count.md#xarray.core.groupby.DatasetGroupBy.count)([dim, keep_attrs]) | Reduce this Dataset's data by applying `count` along some dimension(s). |
| [`DatasetGroupBy.cumsum`](../generated/xarray.core.groupby.DatasetGroupBy.cumsum.md#xarray.core.groupby.DatasetGroupBy.cumsum)([dim, skipna, keep_attrs]) | Reduce this Dataset's data by applying `cumsum` along some dimension(s). |
| [`DatasetGroupBy.cumprod`](../generated/xarray.core.groupby.DatasetGroupBy.cumprod.md#xarray.core.groupby.DatasetGroupBy.cumprod)([dim, skipna, keep_attrs]) | Reduce this Dataset's data by applying `cumprod` along some dimension(s). |
| [`DatasetGroupBy.max`](../generated/xarray.core.groupby.DatasetGroupBy.max.md#xarray.core.groupby.DatasetGroupBy.max)([dim, skipna, keep_attrs]) | Reduce this Dataset's data by applying `max` along some dimension(s). |
| [`DatasetGroupBy.mean`](../generated/xarray.core.groupby.DatasetGroupBy.mean.md#xarray.core.groupby.DatasetGroupBy.mean)([dim, skipna, keep_attrs]) | Reduce this Dataset's data by applying `mean` along some dimension(s). |
| [`DatasetGroupBy.median`](../generated/xarray.core.groupby.DatasetGroupBy.median.md#xarray.core.groupby.DatasetGroupBy.median)([dim, skipna, keep_attrs]) | Reduce this Dataset's data by applying `median` along some dimension(s). |
| [`DatasetGroupBy.min`](../generated/xarray.core.groupby.DatasetGroupBy.min.md#xarray.core.groupby.DatasetGroupBy.min)([dim, skipna, keep_attrs]) | Reduce this Dataset's data by applying `min` along some dimension(s). |
| [`DatasetGroupBy.prod`](../generated/xarray.core.groupby.DatasetGroupBy.prod.md#xarray.core.groupby.DatasetGroupBy.prod)([dim, skipna, ...]) | Reduce this Dataset's data by applying `prod` along some dimension(s). |
| [`DatasetGroupBy.std`](../generated/xarray.core.groupby.DatasetGroupBy.std.md#xarray.core.groupby.DatasetGroupBy.std)([dim, skipna, ddof, ...]) | Reduce this Dataset's data by applying `std` along some dimension(s). |
| [`DatasetGroupBy.sum`](../generated/xarray.core.groupby.DatasetGroupBy.sum.md#xarray.core.groupby.DatasetGroupBy.sum)([dim, skipna, min_count, ...]) | Reduce this Dataset's data by applying `sum` along some dimension(s). |
| [`DatasetGroupBy.var`](../generated/xarray.core.groupby.DatasetGroupBy.var.md#xarray.core.groupby.DatasetGroupBy.var)([dim, skipna, ddof, ...]) | Reduce this Dataset's data by applying `var` along some dimension(s). |
| [`DatasetGroupBy.dims`](../generated/xarray.core.groupby.DatasetGroupBy.dims.md#xarray.core.groupby.DatasetGroupBy.dims) | |
| [`DatasetGroupBy.groups`](../generated/xarray.core.groupby.DatasetGroupBy.groups.md#xarray.core.groupby.DatasetGroupBy.groups) | Mapping from group labels to indices. |
| [`DatasetGroupBy.shuffle_to_chunks`](../generated/xarray.core.groupby.DatasetGroupBy.shuffle_to_chunks.md#xarray.core.groupby.DatasetGroupBy.shuffle_to_chunks)([chunks]) | Sort or "shuffle" the underlying object. |
## DataArray
| [`DataArrayGroupBy`](../generated/xarray.core.groupby.DataArrayGroupBy.md#xarray.core.groupby.DataArrayGroupBy)(obj, groupers[, ...]) | |
|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------|
| [`DataArrayGroupBy.map`](../generated/xarray.core.groupby.DataArrayGroupBy.map.md#xarray.core.groupby.DataArrayGroupBy.map)(func[, args, shortcut]) | Apply a function to each array in the group and concatenate them together into a new array. |
| [`DataArrayGroupBy.reduce`](../generated/xarray.core.groupby.DataArrayGroupBy.reduce.md#xarray.core.groupby.DataArrayGroupBy.reduce)(func[, dim, axis, ...]) | Reduce the items in this group by applying func along some dimension(s). |
| [`DataArrayGroupBy.assign_coords`](../generated/xarray.core.groupby.DataArrayGroupBy.assign_coords.md#xarray.core.groupby.DataArrayGroupBy.assign_coords)([coords]) | Assign coordinates by group. |
| [`DataArrayGroupBy.first`](../generated/xarray.core.groupby.DataArrayGroupBy.first.md#xarray.core.groupby.DataArrayGroupBy.first)([skipna, keep_attrs]) | Return the first element of each group along the group dimension |
| [`DataArrayGroupBy.last`](../generated/xarray.core.groupby.DataArrayGroupBy.last.md#xarray.core.groupby.DataArrayGroupBy.last)([skipna, keep_attrs]) | Return the last element of each group along the group dimension |
| [`DataArrayGroupBy.fillna`](../generated/xarray.core.groupby.DataArrayGroupBy.fillna.md#xarray.core.groupby.DataArrayGroupBy.fillna)(value) | Fill missing values in this object by group. |
| [`DataArrayGroupBy.quantile`](../generated/xarray.core.groupby.DataArrayGroupBy.quantile.md#xarray.core.groupby.DataArrayGroupBy.quantile)(q[, dim, method, ...]) | Compute the qth quantile over each array in the groups and concatenate them together into a new array. |
| [`DataArrayGroupBy.where`](../generated/xarray.core.groupby.DataArrayGroupBy.where.md#xarray.core.groupby.DataArrayGroupBy.where)(cond[, other]) | Return elements from self or other depending on cond. |
| [`DataArrayGroupBy.all`](../generated/xarray.core.groupby.DataArrayGroupBy.all.md#xarray.core.groupby.DataArrayGroupBy.all)([dim, keep_attrs]) | Reduce this DataArray's data by applying `all` along some dimension(s). |
| [`DataArrayGroupBy.any`](../generated/xarray.core.groupby.DataArrayGroupBy.any.md#xarray.core.groupby.DataArrayGroupBy.any)([dim, keep_attrs]) | Reduce this DataArray's data by applying `any` along some dimension(s). |
| [`DataArrayGroupBy.count`](../generated/xarray.core.groupby.DataArrayGroupBy.count.md#xarray.core.groupby.DataArrayGroupBy.count)([dim, keep_attrs]) | Reduce this DataArray's data by applying `count` along some dimension(s). |
| [`DataArrayGroupBy.cumsum`](../generated/xarray.core.groupby.DataArrayGroupBy.cumsum.md#xarray.core.groupby.DataArrayGroupBy.cumsum)([dim, skipna, ...]) | Reduce this DataArray's data by applying `cumsum` along some dimension(s). |
| [`DataArrayGroupBy.cumprod`](../generated/xarray.core.groupby.DataArrayGroupBy.cumprod.md#xarray.core.groupby.DataArrayGroupBy.cumprod)([dim, skipna, ...]) | Reduce this DataArray's data by applying `cumprod` along some dimension(s). |
| [`DataArrayGroupBy.max`](../generated/xarray.core.groupby.DataArrayGroupBy.max.md#xarray.core.groupby.DataArrayGroupBy.max)([dim, skipna, keep_attrs]) | Reduce this DataArray's data by applying `max` along some dimension(s). |
| [`DataArrayGroupBy.mean`](../generated/xarray.core.groupby.DataArrayGroupBy.mean.md#xarray.core.groupby.DataArrayGroupBy.mean)([dim, skipna, keep_attrs]) | Reduce this DataArray's data by applying `mean` along some dimension(s). |
| [`DataArrayGroupBy.median`](../generated/xarray.core.groupby.DataArrayGroupBy.median.md#xarray.core.groupby.DataArrayGroupBy.median)([dim, skipna, ...]) | Reduce this DataArray's data by applying `median` along some dimension(s). |
| [`DataArrayGroupBy.min`](../generated/xarray.core.groupby.DataArrayGroupBy.min.md#xarray.core.groupby.DataArrayGroupBy.min)([dim, skipna, keep_attrs]) | Reduce this DataArray's data by applying `min` along some dimension(s). |
| [`DataArrayGroupBy.prod`](../generated/xarray.core.groupby.DataArrayGroupBy.prod.md#xarray.core.groupby.DataArrayGroupBy.prod)([dim, skipna, ...]) | Reduce this DataArray's data by applying `prod` along some dimension(s). |
| [`DataArrayGroupBy.std`](../generated/xarray.core.groupby.DataArrayGroupBy.std.md#xarray.core.groupby.DataArrayGroupBy.std)([dim, skipna, ddof, ...]) | Reduce this DataArray's data by applying `std` along some dimension(s). |
| [`DataArrayGroupBy.sum`](../generated/xarray.core.groupby.DataArrayGroupBy.sum.md#xarray.core.groupby.DataArrayGroupBy.sum)([dim, skipna, ...]) | Reduce this DataArray's data by applying `sum` along some dimension(s). |
| [`DataArrayGroupBy.var`](../generated/xarray.core.groupby.DataArrayGroupBy.var.md#xarray.core.groupby.DataArrayGroupBy.var)([dim, skipna, ddof, ...]) | Reduce this DataArray's data by applying `var` along some dimension(s). |
| [`DataArrayGroupBy.dims`](../generated/xarray.core.groupby.DataArrayGroupBy.dims.md#xarray.core.groupby.DataArrayGroupBy.dims) | |
| [`DataArrayGroupBy.groups`](../generated/xarray.core.groupby.DataArrayGroupBy.groups.md#xarray.core.groupby.DataArrayGroupBy.groups) | Mapping from group labels to indices. |
| [`DataArrayGroupBy.shuffle_to_chunks`](../generated/xarray.core.groupby.DataArrayGroupBy.shuffle_to_chunks.md#xarray.core.groupby.DataArrayGroupBy.shuffle_to_chunks)([chunks]) | Sort or "shuffle" the underlying object. |
## Grouper Objects
| [`groupers.BinGrouper`](../generated/xarray.groupers.BinGrouper.md#xarray.groupers.BinGrouper)(bins[, right, labels, ...]) | Grouper object for binning numeric data. |
|------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------|
| [`groupers.SeasonGrouper`](../generated/xarray.groupers.SeasonGrouper.md#xarray.groupers.SeasonGrouper)(seasons) | Allows grouping using a custom definition of seasons. |
| [`groupers.UniqueGrouper`](../generated/xarray.groupers.UniqueGrouper.md#xarray.groupers.UniqueGrouper)([labels]) | Grouper object for grouping by a categorical variable. |
## Resampler Objects
| [`groupers.SeasonResampler`](../generated/xarray.groupers.SeasonResampler.md#xarray.groupers.SeasonResampler)(seasons, \*[, ...]) | Allows grouping using a custom definition of seasons. |
|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------|
| [`groupers.SeasonResampler.compute_chunks`](../generated/xarray.groupers.SeasonResampler.compute_chunks.md#xarray.groupers.SeasonResampler.compute_chunks)(...) | Compute chunk sizes for this season resampler. |
| [`groupers.TimeResampler`](../generated/xarray.groupers.TimeResampler.md#xarray.groupers.TimeResampler)(freq[, closed, ...]) | Grouper object specialized to resampling the time coordinate. |
| [`groupers.TimeResampler.compute_chunks`](../generated/xarray.groupers.TimeResampler.compute_chunks.md#xarray.groupers.TimeResampler.compute_chunks)(...) | Compute chunk sizes for this time resampler. |
# help-diagram.html.md
# Getting Help
Navigating the wealth of resources available for Xarray can be overwhelming.
We’ve created this flow chart to help guide you towards the best way to get help, depending on what you’re working towards.
Also be sure to check out our [Frequently Asked Questions](faq.md#faq). and [How do I …](howdoi.md#howdoi) pages for solutions to common questions.
A major strength of Xarray is in the user community. Sometimes you might not yet have a concrete question but would simply like to connect with other Xarray users. We have a few accounts on different social platforms for that! [Social Media](socials.md#socials).
We look forward to hearing from you!
## Help Flowchart
## Flowchart links
- [Xarray Tutorials](https://tutorial.xarray.dev/)
- [Xarray Docs](https://docs.xarray.dev)
- [Stack Exchange](https://stackoverflow.com/questions/tagged/python-xarray)
- [Xarray Discussions](https://github.com/pydata/xarray/discussions)
- [OSSci Zulip](https://ossci.zulipchat.com/#narrow/channel/582428-Xarray)
- [Xarray Office Hours](https://github.com/pydata/xarray/discussions/categories/office-hours)
- [Pangeo Discourse](https://discourse.pangeo.io/)
- [Xarray Issues](https://github.com/pydata/xarray/issues)
- [Contributing to xarray](../contribute/contributing.md#contributing)
- [Developers meeting](../contribute/developers-meeting.md#developers-meeting)
# hierarchical-data.html.md
# Hierarchical data
## Why Hierarchical Data?
Many real-world datasets are composed of multiple differing components,
and it can often be useful to think of these in terms of a hierarchy of related groups of data.
Examples of data which one might want organise in a grouped or hierarchical manner include:
- Simulation data at multiple resolutions,
- Observational data about the same system but from multiple different types of sensors,
- Mixed experimental and theoretical data,
- A systematic study recording the same experiment but with different parameters,
- Heterogeneous data, such as demographic and metereological data,
or even any combination of the above.
Often datasets like this cannot easily fit into a single [`Dataset`](../generated/xarray.Dataset.md#xarray.Dataset) object,
or are more usefully thought of as groups of related [`Dataset`](../generated/xarray.Dataset.md#xarray.Dataset) objects.
For this purpose we provide the [`xarray.DataTree`](../generated/xarray.DataTree.md#xarray.DataTree) class.
This page explains in detail how to understand and use the different features
of the [`DataTree`](../generated/xarray.DataTree.md#xarray.DataTree) class for your own hierarchical data needs.
## Node Relationships
### Creating a Family Tree
The three main ways of creating a [`DataTree`](../generated/xarray.DataTree.md#xarray.DataTree) object are described briefly in [Creating a DataTree](data-structures.md#creating-a-datatree).
Here we go into more detail about how to create a tree node-by-node, using a famous family tree from the Simpsons cartoon as an example.
Let’s start by defining nodes representing the two siblings, Bart and Lisa Simpson:
```ipython3
bart = xr.DataTree(name="Bart")
lisa = xr.DataTree(name="Lisa")
```
Each of these node objects knows their own [`name`](../generated/xarray.DataTree.name.md#xarray.DataTree.name), but they currently have no relationship to one another.
We can connect them by creating another node representing a common parent, Homer Simpson:
```ipython3
homer = xr.DataTree(name="Homer", children={"Bart": bart, "Lisa": lisa})
```
Here we set the children of Homer in the node’s constructor.
We now have a small family tree where we can see how these individual Simpson family members are related to one another:
```ipython3
print(homer)
```
```none