diff --git a/doc/data-structures.rst b/doc/data-structures.rst index 457e61967b8..48c8e2d9874 100644 --- a/doc/data-structures.rst +++ b/doc/data-structures.rst @@ -199,6 +199,8 @@ Coordinates can also be set or removed by using the dictionary like syntax: del foo['ranking'] foo.coords +For more details, see :ref:`coordinates` below. + Dataset ------- @@ -472,19 +474,35 @@ objects in the ``coords`` attribute: ds.coords 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 :py:class:`~pandas.DataFrame` or -:py:class:`~pandas.Series`. Indeed, these "dimension" coordinates use a -:py:class:`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 :ref:`coordinates math`). +operations that transform xarray objects. There are two types of coordinates +in xarray: + +- **dimension coordinates** are one dimensional coordinates with a name equal + to their sole dimension (marked by ``*`` when printing a dataset or data + array). They are used for label based indexing and alignment, + like the ``index`` found on a pandas :py:class:`~pandas.DataFrame` or + :py:class:`~pandas.Series`. Indeed, these "dimension" coordinates use a + :py:class:`pandas.Index` internally to store their values. + +- **non-dimension coordinates** are variables that contain coordinate + data, but are not a dimension coordinate. They can be multidimensional + (see :ref:`examples.multidim`), and there is no relationship between the + name of a non-dimension coordinate and the name(s) of its dimension(s). + Non-dimension coordinates can be useful for indexing or plotting; otherwise, + xarray does not make any direct use of the values associated with them. + They are not used for alignment or automatic indexing, nor are they required + to match when doing arithmetic + (see :ref:`coordinates math`). + +.. note:: + + xarray's terminology differs from the `CF terminology`_, where the + "dimension coordinates" are called "coordinate variables", and the + "non-dimension coordinates" are called "auxiliary coordinate variables" + (see :issue:`1295` for more details). + +.. _CF terminology: http://cfconventions.org/cf-conventions/v1.6.0/cf-conventions.html#terminology + Modifying coordinates ~~~~~~~~~~~~~~~~~~~~~