Xarray terminology differs slightly from CF, mathematical conventions, and
pandas; so we’ve put together a glossary of its terms. Here,
refers to an xarray
DataArray in the examples. For more
complete examples, please consult the relevant documentation.
A multi-dimensional array with labeled or named dimensions.
DataArrayobjects add metadata such as dimension names, coordinates, and attributes (defined below) to underlying “unlabeled” data structures such as numpy and Dask arrays. If its optional
nameproperty is set, it is a named DataArray.
A dict-like collection of
DataArrayobjects with aligned dimensions. Thus, most operations that can be performed on the dimensions of a single
DataArraycan be performed on a dataset. Datasets have data variables (see Variable below), dimensions, coordinates, and attributes.
A NetCDF-like variable consisting of dimensions, data, and attributes which describe a single array. The main functional difference between variables and numpy arrays is that numerical operations on variables implement array broadcasting by dimension name. Each
DataArrayhas an underlying variable that can be accessed via
arr.variable. However, a variable is not fully described outside of either a
Variableclass is low-level interface and can typically be ignored. However, the word “variable” appears often enough in the code and documentation that is useful to understand.
In mathematics, the dimension of data is loosely the number of degrees of freedom for it. A dimension axis is a set of all points in which all but one of these degrees of freedom is fixed. We can think of each dimension axis as having a name, for example the “x dimension”. In xarray, a
DataArrayobject’s dimensions are its named dimension axes, and the name of the
i-th dimension is
arr.dims[i]. If an array is created without dimension names, the default dimension names are
dim_1, and so forth.
An array that labels a dimension or set of dimensions of another
DataArray. In the usual one-dimensional case, the coordinate array’s values can loosely be thought of as tick labels along a dimension. There are two types of coordinate arrays: dimension coordinates and non-dimension coordinates (see below). A coordinate named
xcan be retrieved from
DataArraycan have more coordinates than dimensions because a single dimension can be labeled by multiple coordinate arrays. However, only one coordinate array can be a assigned as a particular dimension’s dimension coordinate array. As a consequence,
len(arr.dims) <= len(arr.coords)in general.
- Dimension coordinate#
A one-dimensional coordinate array assigned to
arrwith both a name and dimension name in
arr.dims. Dimension coordinates are used for label-based indexing and alignment, like the index found on a
pandas.Series. In fact, dimension coordinates use
pandas.Indexobjects under the hood for efficient computation. Dimension coordinates are marked by
*when printing a
- Non-dimension coordinate#
A coordinate array assigned to
arrwith a name in
arr.coordsbut not in
arr.dims. These coordinates arrays can be one-dimensional or multidimensional, and they are useful for auxiliary labeling. As an example, multidimensional coordinates are often used in geoscience datasets when the data’s physical coordinates (such as latitude and longitude) differ from their logical coordinates. However, non-dimension coordinates are not indexed, and any operation on non-dimension coordinates that leverages indexing will fail. Printing
arr.coordswill print all of
arr’s coordinate names, with the corresponding dimension(s) in parentheses. For example,
coord_name (dim_name) 1 2 3 ....
An index is a data structure optimized for efficient selecting and slicing of an associated array. Xarray creates indexes for dimension coordinates so that operations along dimensions are fast, while non-dimension coordinates are not indexed. Under the hood, indexes are implemented as
pandas.Indexobjects. The index associated with dimension name
xcan be retrieved by
arr.indexes[x]. By construction,
len(arr.dims) == len(arr.indexes)
The names of dimensions, coordinates, DataArray objects and data variables can be anything as long as they are hashable. However, it is preferred to use
By definition, a scalar is not an array and when converted to one, it has 0 dimensions. That means that, e.g.,
strobjects are “scalar” while
- duck array#
Duck arrays are array implementations that behave like numpy arrays. They have to define the
ndimproperties. For integration with
__array_function__protocols are also required.