From 494d079f4ed8db1ae0fa8bd9473b71400ae844da Mon Sep 17 00:00:00 2001 From: Jon Thielen Date: Wed, 16 Oct 2019 19:16:35 -0500 Subject: [PATCH 1/4] Update Terminology page to account for multidimensional coordinates --- doc/terminology.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/terminology.rst b/doc/terminology.rst index 138a99740fe..ab4c8534045 100644 --- a/doc/terminology.rst +++ b/doc/terminology.rst @@ -27,15 +27,15 @@ Terminology ---- -**Coordinate:** An array that labels a dimension of another ``DataArray``. Loosely, the coordinate array's values can 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 ``x`` can be retrieved from ``arr.coords[x]``. A ``DataArray`` can have more coordinates than dimensions because a single dimension can be assigned 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. +**Coordinate:** An array that labels a dimension or set of dimensions of another ``DataArray``. In the one-dimensional case, the coordinate array's values can loosely be thought of as tick labels along a dimension, whereas :doc:`multidimensional coordinates are often used when the data's physical coordinates differ from their logical coordinates `. There are two types of coordinate arrays: *dimension coordinates* and *non-dimension coordinates* (see below). A coordinate named ``x`` can be retrieved from ``arr.coords[x]``. A ``DataArray`` can have more coordinates than dimensions because a single dimension can be assigned 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 coordinate array assigned to ``arr`` with 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 :py:class:`pandas.DataFrame` or :py:class:`pandas.Series`. In fact, dimension coordinates use :py:class:`pandas.Index` objects under the hood for efficient computation. Dimension coordinates are marked by ``*`` when printing a ``DataArray`` or ``Dataset``. +**Dimension coordinate:** A one-dimensional coordinate array assigned to ``arr`` with 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 :py:class:`pandas.DataFrame` or :py:class:`pandas.Series`. In fact, dimension coordinates use :py:class:`pandas.Index` objects under the hood for efficient computation. Dimension coordinates are marked by ``*`` when printing a ``DataArray`` or ``Dataset``. ---- -**Non-dimension coordinate:** A coordinate array assigned to ``arr`` with a name in ``arr.dims`` but a dimension name *not* in ``arr.dims``. These coordinate arrays are useful for auxiliary labeling. However, non-dimension coordinates are not indexed, and any operation on non-dimension coordinates that leverages indexing will fail. Printing ``arr.coords`` will print all of ``arr``'s coordinate names, with the assigned dimensions in parentheses. For example, ``coord_name (dim_name) 1 2 3 ...``. +**Non-dimension coordinate:** A coordinate array assigned to ``arr`` with a name in ``arr.coords`` but *not* in ``arr.dims``. These coordinates arrays can be one-dimensional or multidimensional, and they are useful for auxiliary labeling. However, non-dimension coordinates are not indexed, and any operation on non-dimension coordinates that leverages indexing will fail. Printing ``arr.coords`` will print all of ``arr``'s coordinate names, with the assigned dimension(s) in parentheses. For example, ``coord_name (dim_name) 1 2 3 ...``. ---- From 7ae9dbc55d04df038f9578412b0c6293bae33c5b Mon Sep 17 00:00:00 2001 From: Jon Thielen Date: Wed, 16 Oct 2019 19:26:39 -0500 Subject: [PATCH 2/4] Update xarray-docs conda environment file --- doc/contributing.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/contributing.rst b/doc/contributing.rst index 66e8377600e..028ec47e014 100644 --- a/doc/contributing.rst +++ b/doc/contributing.rst @@ -286,12 +286,12 @@ How to build the *xarray* documentation Requirements ~~~~~~~~~~~~ Make sure to follow the instructions on :ref:`creating a development environment above `, but -to build the docs you need to use the environment file ``doc/environment.yml``. +to build the docs you need to use the environment file ``ci/requirements/doc.yml``. .. code-block:: none # Create and activate the docs environment - conda env create -f doc/environment.yml + conda env create -f ci/requirements/doc.yml conda activate xarray-docs # or with older versions of Anaconda: From 408807c6df14b8e1933a11183b5a74a7943cbd96 Mon Sep 17 00:00:00 2001 From: Jon Thielen Date: Wed, 16 Oct 2019 19:59:08 -0500 Subject: [PATCH 3/4] Add change to whats-new.rst --- doc/whats-new.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/whats-new.rst b/doc/whats-new.rst index 2202c91408b..c21648aae33 100644 --- a/doc/whats-new.rst +++ b/doc/whats-new.rst @@ -25,6 +25,8 @@ Documentation :py:meth:`Dataset.resample` and explicitly state that a datetime-like dimension is required. (:pull:`3400`) By `Justus Magin `_. +- Update the terminology page to address multidimensional coordinates. (:pull:`3410`) + By `Jon Thielen `_. .. _whats-new.0.14.0: From 98044fb322ce167a3a3e262acc18869260b408a3 Mon Sep 17 00:00:00 2001 From: Jon Thielen Date: Tue, 22 Oct 2019 07:09:16 -0500 Subject: [PATCH 4/4] Modify example description for multidimensional coords based on suggestion --- doc/terminology.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/terminology.rst b/doc/terminology.rst index ab4c8534045..4ee56190d5f 100644 --- a/doc/terminology.rst +++ b/doc/terminology.rst @@ -27,7 +27,7 @@ Terminology ---- -**Coordinate:** An array that labels a dimension or set of dimensions of another ``DataArray``. In the one-dimensional case, the coordinate array's values can loosely be thought of as tick labels along a dimension, whereas :doc:`multidimensional coordinates are often used when the data's physical coordinates differ from their logical coordinates `. There are two types of coordinate arrays: *dimension coordinates* and *non-dimension coordinates* (see below). A coordinate named ``x`` can be retrieved from ``arr.coords[x]``. A ``DataArray`` can have more coordinates than dimensions because a single dimension can be assigned 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. +**Coordinate:** 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 ``x`` can be retrieved from ``arr.coords[x]``. A ``DataArray`` can 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. ---- @@ -35,7 +35,7 @@ Terminology ---- -**Non-dimension coordinate:** A coordinate array assigned to ``arr`` with a name in ``arr.coords`` but *not* in ``arr.dims``. These coordinates arrays can be one-dimensional or multidimensional, and they are useful for auxiliary labeling. However, non-dimension coordinates are not indexed, and any operation on non-dimension coordinates that leverages indexing will fail. Printing ``arr.coords`` will print all of ``arr``'s coordinate names, with the assigned dimension(s) in parentheses. For example, ``coord_name (dim_name) 1 2 3 ...``. +**Non-dimension coordinate:** A coordinate array assigned to ``arr`` with a name in ``arr.coords`` but *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 :doc:`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.coords`` will print all of ``arr``'s coordinate names, with the corresponding dimension(s) in parentheses. For example, ``coord_name (dim_name) 1 2 3 ...``. ----