From 44b9039d7a9f12d992349ad616396d195a3fcad5 Mon Sep 17 00:00:00 2001 From: Fabien Maussion Date: Sun, 5 Mar 2017 11:07:51 +0100 Subject: [PATCH 1/2] Clearer terminology for coordinate variables --- doc/data-structures.rst | 31 ++++++++++++++++++------------- 1 file changed, 18 insertions(+), 13 deletions(-) diff --git a/doc/data-structures.rst b/doc/data-structures.rst index 457e61967b8..6093a287d25 100644 --- a/doc/data-structures.rst +++ b/doc/data-structures.rst @@ -472,19 +472,24 @@ 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. Following the `CF conventions`_, +there are two types of coordinates in xarray: + +- **coordinate variables** 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. + +- **auxiliary coordinate variables** are variables that contain coordinate + data, but are not a coordinate variable. They can be of any dimension + (see :ref:`examples.multidim`), and there is no relationship between the + name of an auxiliary coordinate variable and the name(s) of its dimension(s). + Other than for indexing, xarray does not make any direct use of the values + associated with auxiliary coordinates. They are not used for alignment or + indexing, nor are they required to match when doing arithmetic + (see :ref:`coordinates math`). Modifying coordinates ~~~~~~~~~~~~~~~~~~~~~ From 3bc8e05f239deab1163f92a9018810ae571f5f3b Mon Sep 17 00:00:00 2001 From: Fabien Maussion Date: Mon, 6 Mar 2017 22:54:27 +0100 Subject: [PATCH 2/2] Update terms --- doc/data-structures.rst | 31 ++++++++++++++++++++++--------- 1 file changed, 22 insertions(+), 9 deletions(-) diff --git a/doc/data-structures.rst b/doc/data-structures.rst index 6093a287d25..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,25 +474,36 @@ objects in the ``coords`` attribute: ds.coords Unlike attributes, xarray *does* interpret and persist coordinates in -operations that transform xarray objects. Following the `CF conventions`_, -there are two types of coordinates in xarray: +operations that transform xarray objects. There are two types of coordinates +in xarray: -- **coordinate variables** are one dimensional coordinates with a name equal +- **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. -- **auxiliary coordinate variables** are variables that contain coordinate - data, but are not a coordinate variable. They can be of any dimension +- **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 an auxiliary coordinate variable and the name(s) of its dimension(s). - Other than for indexing, xarray does not make any direct use of the values - associated with auxiliary coordinates. They are not used for alignment or - indexing, nor are they required to match when doing arithmetic + 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 ~~~~~~~~~~~~~~~~~~~~~