From 8ae029af1ea8682598f70040bd30d7ec8d7712b5 Mon Sep 17 00:00:00 2001 From: Keewis Date: Wed, 5 Aug 2020 15:47:42 +0200 Subject: [PATCH 01/27] extend the docs a bit --- docs/changelog.rst | 5 +++++ docs/contributing.rst | 12 ++++++++++++ docs/examples.rst | 2 ++ docs/index.rst | 27 ++++++++++++++++++++------- docs/installation.rst | 15 +++++++++++++++ 5 files changed, 54 insertions(+), 7 deletions(-) create mode 100644 docs/changelog.rst create mode 100644 docs/contributing.rst create mode 100644 docs/examples.rst create mode 100644 docs/installation.rst diff --git a/docs/changelog.rst b/docs/changelog.rst new file mode 100644 index 00000000..3e58a9f2 --- /dev/null +++ b/docs/changelog.rst @@ -0,0 +1,5 @@ +Changelog +========= + +0.1 (*unreleased*) +------------------ diff --git a/docs/contributing.rst b/docs/contributing.rst new file mode 100644 index 00000000..62d04e27 --- /dev/null +++ b/docs/contributing.rst @@ -0,0 +1,12 @@ +Contributing +============ +All development happens on `github `_. + +Linters / Autoformatters +------------------------ +In order to keep code consistent, we use + +- `Black `_ for standardized code formatting +- `blackdoc `_ for standardized code formatting in documentation +- `Flake8 `_ for general code quality +- `isort `_ for standardized order in imports. See also `flake8-isort `_. diff --git a/docs/examples.rst b/docs/examples.rst new file mode 100644 index 00000000..bac945d5 --- /dev/null +++ b/docs/examples.rst @@ -0,0 +1,2 @@ +Examples +======== diff --git a/docs/index.rst b/docs/index.rst index b526353b..e2865c90 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,13 +1,26 @@ -.. accessors documentation master file, created by - sphinx-quickstart on Thu Jul 2 01:49:50 2020. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. +pint-xarray +=========== +A convenience wrapper for using `pint`_ in `xarray`_ objects. -Welcome to accessors's documentation! -===================================== +.. _pint: https://pint.readthedocs.io/en/stable +.. _xarray: https://xarray.pydata.org/en/stable + +Documentation +------------- + +- :doc:`installation` +- :doc:`contributing` +- :doc:`examples` +- :doc:`changelog` +- :doc:`api` .. toctree:: - :maxdepth: 2 + :maxdepth: 1 :caption: Contents: + :hidden: + installation + changelog + examples api + contributing diff --git a/docs/installation.rst b/docs/installation.rst new file mode 100644 index 00000000..0e415163 --- /dev/null +++ b/docs/installation.rst @@ -0,0 +1,15 @@ +Installation +------------ +As there's no release, yet, ``pint-xarray`` can only be installed from +source, either directly from github: + +.. code:: sh + + python -m pip install git+https://github.com/xarray-contrib/pint-xarray + +or from a local copy: + +.. code:: sh + + git clone https://github.com/xarray-contrib/pint-xarray + python -m pip install ./pint-xarray From 6b3f5e4eb0afbb5c3f4287b96ce4e567905d607e Mon Sep 17 00:00:00 2001 From: Keewis Date: Wed, 5 Aug 2020 16:11:28 +0200 Subject: [PATCH 02/27] include a terminology page --- docs/index.rst | 4 +++- docs/terminology.rst | 9 +++++++++ 2 files changed, 12 insertions(+), 1 deletion(-) create mode 100644 docs/terminology.rst diff --git a/docs/index.rst b/docs/index.rst index e2865c90..ec064020 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -9,10 +9,11 @@ Documentation ------------- - :doc:`installation` -- :doc:`contributing` - :doc:`examples` - :doc:`changelog` +- :doc:`terminology` - :doc:`api` +- :doc:`contributing` .. toctree:: :maxdepth: 1 @@ -22,5 +23,6 @@ Documentation installation changelog examples + terminology api contributing diff --git a/docs/terminology.rst b/docs/terminology.rst new file mode 100644 index 00000000..6c091827 --- /dev/null +++ b/docs/terminology.rst @@ -0,0 +1,9 @@ +Terminology +=========== + +.. glossary:: + + unit-like : str or pint.Unit + A `pint`_ unit definition, as accepted by :py:class:`unit_registry.Unit `. + +.. _pint: https://pint.readthedocs.io/en/stable From 5823741937e385b5e3e289134b30bd70135a7edc Mon Sep 17 00:00:00 2001 From: Keewis Date: Wed, 5 Aug 2020 16:18:06 +0200 Subject: [PATCH 03/27] add xarray and pint to intersphinx --- docs/conf.py | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index b0235b56..29ff4426 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -77,4 +77,8 @@ # -- Options for intersphinx extension --------------------------------------- # Example configuration for intersphinx: refer to the Python standard library. -intersphinx_mapping = {"https://docs.python.org/3/": None} +intersphinx_mapping = { + "python": ("https://docs.python.org/3/", None), + "xarray": ("https://xarray.pydata.org/en/stable", None), + "pint": ("https://pint.readthedocs.io/en/stable", None), +} From 0b21b6534b64b766600edf95d6981aed80839c86 Mon Sep 17 00:00:00 2001 From: Keewis Date: Wed, 5 Aug 2020 16:18:23 +0200 Subject: [PATCH 04/27] use the new term to make the docstrings less ambiguous --- pint_xarray/accessors.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/pint_xarray/accessors.py b/pint_xarray/accessors.py index e86fcd13..47c76cb4 100644 --- a/pint_xarray/accessors.py +++ b/pint_xarray/accessors.py @@ -148,7 +148,7 @@ def quantify( Parameters ---------- - units : pint.Unit or str or mapping of hashable to pint.Unit or str, optional + units : unit-like or mapping of hashable to unit-like, optional Physical units to use for this DataArray. If a str or pint.Unit, will be used as the DataArray's units. If a dict-like, it should map a variable name to the desired @@ -275,7 +275,7 @@ def to(self, units=None, **unit_kwargs): Parameters ---------- - units : str or pint.Unit or mapping of hashable to str or pint.Unit, optional + units : unit-like or mapping of hashable to unit-like, optional The units to convert to. If a unit name or ``pint.Unit`` object, convert the DataArray's data. If a dict-like, it has to map a variable name to a unit name or ``pint.Unit`` @@ -440,7 +440,7 @@ def quantify( Parameters ---------- - units : mapping of hashable to pint.Unit or str, optional + units : mapping of hashable to unit-like, optional Physical units to use for particular DataArrays in this Dataset. It should map variable names to units (unit names or ``pint.Unit`` objects). If not provided, will try to @@ -532,7 +532,7 @@ def to(self, units=None, **unit_kwargs): Parameters ---------- - units : mapping of hashable to str or pint.Unit, optional + units : mapping of hashable to unit-like, optional Maps variable names to the unit to convert to. **unit_kwargs The kwargs form of ``units``. Can only be used for From 619b419bfc30e15edb303957a21affb60e626ad5 Mon Sep 17 00:00:00 2001 From: Keewis Date: Mon, 10 Aug 2020 00:22:12 +0200 Subject: [PATCH 05/27] update the docs requirements --- docs/requirements.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/requirements.txt b/docs/requirements.txt index 1b181900..4535b429 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,6 +1,6 @@ -pint>=0.13 -xarray>=0.15.1 -sphinx>=3.0 +pint>=0.14 +xarray>=0.16.0 +sphinx>=3.2 sphinx_rtd_theme nbsphinx sphinx-autosummary-accessors From 2bba2686c343ba958b3fc59bb8c1d4dbb30b0af3 Mon Sep 17 00:00:00 2001 From: Keewis Date: Mon, 10 Aug 2020 00:29:04 +0200 Subject: [PATCH 06/27] set up a mapping of type aliases --- docs/conf.py | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/conf.py b/docs/conf.py index 29ff4426..7bed39ad 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -74,6 +74,17 @@ napoleon_use_param = True napoleon_use_rtype = True +napoleon_type_aliases = { + "dict-like": ":term:`dict-like `", + "mapping": ":term:`mapping`", + "hashable": ":term:`hashable`", + # xarray + "Dataset": "~xarray.Dataset", + "DataArray": "~xarray.DataArray", + # pint / pint-xarray + "unit-like": ":term:`unit-like`", +} + # -- Options for intersphinx extension --------------------------------------- # Example configuration for intersphinx: refer to the Python standard library. From 61faa84536dd298b54304f26faf423d60e7cc110 Mon Sep 17 00:00:00 2001 From: Keewis Date: Mon, 10 Aug 2020 00:29:20 +0200 Subject: [PATCH 07/27] avoid the use of :param: as that will duplicate parameters when using "x, y : str" styled parameter documentation --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 7bed39ad..d40f31ff 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -71,7 +71,7 @@ autosummary_generate = True autodoc_typehints = "none" -napoleon_use_param = True +napoleon_use_param = False napoleon_use_rtype = True napoleon_type_aliases = { From 78c6abb532a30bbd5dbbf02e6fcd43f000cd2072 Mon Sep 17 00:00:00 2001 From: Keewis Date: Mon, 10 Aug 2020 00:33:51 +0200 Subject: [PATCH 08/27] expand the index page --- docs/conversion.rst | 2 ++ docs/creation.rst | 2 ++ docs/index.rst | 32 ++++++++++++++++++++++++++++---- 3 files changed, 32 insertions(+), 4 deletions(-) create mode 100644 docs/conversion.rst create mode 100644 docs/creation.rst diff --git a/docs/conversion.rst b/docs/conversion.rst new file mode 100644 index 00000000..b7a0edad --- /dev/null +++ b/docs/conversion.rst @@ -0,0 +1,2 @@ +Converting units +================ diff --git a/docs/creation.rst b/docs/creation.rst new file mode 100644 index 00000000..b5576f29 --- /dev/null +++ b/docs/creation.rst @@ -0,0 +1,2 @@ +Attaching units +=============== diff --git a/docs/index.rst b/docs/index.rst index ec064020..d69fc924 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -8,10 +8,37 @@ A convenience wrapper for using `pint`_ in `xarray`_ objects. Documentation ------------- +**Getting Started**: + - :doc:`installation` - :doc:`examples` -- :doc:`changelog` + +.. toctree:: + :maxdepth: 1 + :caption: Getting Started + :hidden: + + installation + examples + +**User Guide**: + - :doc:`terminology` +- :doc:`creation` +- :doc:`conversion` + +.. toctree:: + :maxdepth: 1 + :caption: User Guide + :hidden: + + creation + conversion + + +**Help & Reference**: + +- :doc:`changelog` - :doc:`api` - :doc:`contributing` @@ -20,9 +47,6 @@ Documentation :caption: Contents: :hidden: - installation changelog - examples - terminology api contributing From 133aeb52db48133ee313f5f75b55c1978d3a29c3 Mon Sep 17 00:00:00 2001 From: Keewis Date: Mon, 10 Aug 2020 00:45:04 +0200 Subject: [PATCH 09/27] fix a sidebar caption --- docs/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.rst b/docs/index.rst index d69fc924..ca9e55fc 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -44,7 +44,7 @@ Documentation .. toctree:: :maxdepth: 1 - :caption: Contents: + :caption: Help & Reference :hidden: changelog From 1f6c2df0486145c416d2ef6bf690677d22b21c59 Mon Sep 17 00:00:00 2001 From: Keewis Date: Mon, 10 Aug 2020 00:52:22 +0200 Subject: [PATCH 10/27] don't use a custom link text for pint.Unit --- docs/terminology.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/terminology.rst b/docs/terminology.rst index 6c091827..c800b0a4 100644 --- a/docs/terminology.rst +++ b/docs/terminology.rst @@ -4,6 +4,6 @@ Terminology .. glossary:: unit-like : str or pint.Unit - A `pint`_ unit definition, as accepted by :py:class:`unit_registry.Unit `. + A `pint`_ unit definition, as accepted by :py:class:`pint.Unit`. .. _pint: https://pint.readthedocs.io/en/stable From 59674a94cb6a034f85d6857663a28ab0e0d757c2 Mon Sep 17 00:00:00 2001 From: Keewis Date: Mon, 10 Aug 2020 00:53:40 +0200 Subject: [PATCH 11/27] move the type information from the definition to the description --- docs/terminology.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/terminology.rst b/docs/terminology.rst index c800b0a4..4fe6534d 100644 --- a/docs/terminology.rst +++ b/docs/terminology.rst @@ -3,7 +3,8 @@ Terminology .. glossary:: - unit-like : str or pint.Unit + unit-like A `pint`_ unit definition, as accepted by :py:class:`pint.Unit`. + May be either a :py:class:`str` or a :py:class:`pint.Unit` instance. .. _pint: https://pint.readthedocs.io/en/stable From 7cd582c8ee3502557f70e29151bca97e9e657e1d Mon Sep 17 00:00:00 2001 From: Keewis Date: Tue, 18 Aug 2020 01:55:28 +0200 Subject: [PATCH 12/27] add ipython to the used extensions --- docs/conf.py | 2 ++ docs/requirements.txt | 1 + 2 files changed, 3 insertions(+) diff --git a/docs/conf.py b/docs/conf.py index d40f31ff..1fbdf9f2 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -42,6 +42,8 @@ "sphinx.ext.autodoc", "sphinx.ext.napoleon", "sphinx_autosummary_accessors", + "IPython.sphinxext.ipython_directive", + "IPython.sphinxext.ipython_console_highlighting", ] # Add any paths that contain templates here, relative to this directory. diff --git a/docs/requirements.txt b/docs/requirements.txt index 4535b429..bd5b7715 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -2,5 +2,6 @@ pint>=0.14 xarray>=0.16.0 sphinx>=3.2 sphinx_rtd_theme +ipython nbsphinx sphinx-autosummary-accessors From 9583f49531a86f884f06edebabc6b108bb204e23 Mon Sep 17 00:00:00 2001 From: Keewis Date: Tue, 18 Aug 2020 01:55:48 +0200 Subject: [PATCH 13/27] add terminology to the toctree --- docs/index.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/index.rst b/docs/index.rst index ca9e55fc..452a61a0 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -32,6 +32,7 @@ Documentation :caption: User Guide :hidden: + terminology creation conversion From d38ed3d9d363c348269f6669f4b228f0a6e37a91 Mon Sep 17 00:00:00 2001 From: Keewis Date: Tue, 18 Aug 2020 01:57:29 +0200 Subject: [PATCH 14/27] add blackdoc to pre-commit --- .pre-commit-config.yaml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index b26da3d3..b2405792 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -10,6 +10,10 @@ repos: rev: stable hooks: - id: black + - repo: https://github.com/keewis/blackdoc + rev: stable + hooks: + - id: blackdoc - repo: https://gitlab.com/pycqa/flake8 rev: 3.8.1 hooks: From 1d8d414da511c7ee3cfc8fd69bc153d052d02845 Mon Sep 17 00:00:00 2001 From: Keewis Date: Tue, 18 Aug 2020 01:58:17 +0200 Subject: [PATCH 15/27] add a rough draft of the quantify howto-guide --- docs/creation.rst | 89 ++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 88 insertions(+), 1 deletion(-) diff --git a/docs/creation.rst b/docs/creation.rst index b5576f29..69785d30 100644 --- a/docs/creation.rst +++ b/docs/creation.rst @@ -1,2 +1,89 @@ +.. currentmodule:: xarray + +Creating and saving objects with units +====================================== + Attaching units -=============== +--------------- +.. ipython:: python + :suppress: + + import xarray as xr + +Usually, when loading data from disk we get a :py:class:`Dataset` or +:py:class:`DataArray` with units in attributes: + +.. ipython:: python + + ds = xr.tutorial.open_dataset("air_temperature") + da = ds.air + ds + da + +In order to get :py:class:`pint.Quantity` instances, we can use the +:py:meth:`Dataset.pint.quantify` or :py:meth:`DataArray.pint.quantify` methods: + +.. ipython:: python + :okexcept: + + ds.pint.quantify() + +As we can see, the dataset uses units like ``degree_north`` or ``degree_east``, +which `pint`_ doesn't know about. To fix that, we can override the units of +specific variables: + +.. ipython:: python + + ds.pint.quantify(lat="degree", lon="degree") + da.pint.quantify({"lat": "degree", "lon": "degree"}) + +Overriding works, even if there is no ``units`` attribute, so we could use this +to attach units to a ordinary :py:class:`Dataset`: + +.. ipython:: python + + temporary_ds = xr.Dataset({"a": ("x", [0, 5, 10])}, coords={"x": [1, 2, 3]}) + temporary_ds.pint.quantify({"a": "m"}) + +Of course, we could use :py:class:`pint.Unit` instances instead of strings to +specify units, too. If we wanted to change the units of the data of a +:py:class:`DataArray`, we could do so using the :py:attr:`DataArray.name` +attribute: + +.. ipython:: python + + da.pint.quantify({da.name: "J", "lat": "degree", "lon": "degree"}) + +However, `xarray`_ currently doesn't support `units in indexes`_, so the new units were set +as attributes. To really observe the changes the ``quantify`` methods make, we +have to first swap the dimensions: + +.. ipython:: python + + ds_with_units = ds.swap_dims({"lon": "x", "lat": "y"}).pint.quantify( + {"lat": "degree", "lon": "degree"} + ) + da_with_units = da.swap_dims({"lon": "x", "lat": "y"}).pint.quantify( + {"lat": "degree", "lon": "degree"} + ) + ds_with_units + da_with_units + +Saving with units +----------------- +In order to not lose the units when saving to disk, we first have to call the +:py:meth:`Dataset.pint.dequantify` and :py:meth:`DataArray.pint.dequantify` +methods: + +.. ipython:: python + + ds_with_units.pint.dequantify() + da_with_units.pint.dequantify() + +This will get the string representation of a :py:class:`pint.Unit` instance and +attach it as a ``units`` attribute. The data of the variable will now be +whatever `pint`_ wrapped. + +.. _pint: https://pint.readthedocs.org/en/stable +.. _xarray: https://xarray.pydata.org/en/stable +.. _units in indexes: https://github.com/pydata/xarray/issues/1603 From 79c3b3f1609824d2f39882d68831746ef0cd63f8 Mon Sep 17 00:00:00 2001 From: Keewis Date: Tue, 18 Aug 2020 02:03:54 +0200 Subject: [PATCH 16/27] add netcdf4 to the requirements --- docs/requirements.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/requirements.txt b/docs/requirements.txt index bd5b7715..6a0cf8f9 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,5 +1,6 @@ pint>=0.14 xarray>=0.16.0 +netCDF4 sphinx>=3.2 sphinx_rtd_theme ipython From 238918927ea6b00af90c57dbb3e3d111cde7e5ed Mon Sep 17 00:00:00 2001 From: Keewis Date: Tue, 18 Aug 2020 14:50:01 +0200 Subject: [PATCH 17/27] enable the type preprocessor --- docs/conf.py | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/conf.py b/docs/conf.py index 1fbdf9f2..84f6bc57 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -76,6 +76,7 @@ napoleon_use_param = False napoleon_use_rtype = True +napoleon_preprocess_types = True napoleon_type_aliases = { "dict-like": ":term:`dict-like `", "mapping": ":term:`mapping`", From ebb1ff793b9bdcf719ca918c2ede1a9950f9e3aa Mon Sep 17 00:00:00 2001 From: Keewis Date: Tue, 18 Aug 2020 14:52:16 +0200 Subject: [PATCH 18/27] use ipython prompts in the directives --- docs/creation.rst | 58 +++++++++++++++++++++++++---------------------- 1 file changed, 31 insertions(+), 27 deletions(-) diff --git a/docs/creation.rst b/docs/creation.rst index 69785d30..23427af4 100644 --- a/docs/creation.rst +++ b/docs/creation.rst @@ -13,61 +13,64 @@ Attaching units Usually, when loading data from disk we get a :py:class:`Dataset` or :py:class:`DataArray` with units in attributes: -.. ipython:: python +.. ipython:: + + In [1]: ds = xr.tutorial.open_dataset("air_temperature") + ...: ds - ds = xr.tutorial.open_dataset("air_temperature") - da = ds.air - ds - da + In [2]: da = ds.air + ...: da In order to get :py:class:`pint.Quantity` instances, we can use the :py:meth:`Dataset.pint.quantify` or :py:meth:`DataArray.pint.quantify` methods: -.. ipython:: python +.. ipython:: :okexcept: - ds.pint.quantify() + In [3]: ds.pint.quantify() As we can see, the dataset uses units like ``degree_north`` or ``degree_east``, which `pint`_ doesn't know about. To fix that, we can override the units of specific variables: -.. ipython:: python +.. ipython:: + + In [4]: ds.pint.quantify(lat="degree", lon="degree") - ds.pint.quantify(lat="degree", lon="degree") - da.pint.quantify({"lat": "degree", "lon": "degree"}) + In [5]: da.pint.quantify({"lat": "degree", "lon": "degree"}) Overriding works, even if there is no ``units`` attribute, so we could use this to attach units to a ordinary :py:class:`Dataset`: -.. ipython:: python +.. ipython:: - temporary_ds = xr.Dataset({"a": ("x", [0, 5, 10])}, coords={"x": [1, 2, 3]}) - temporary_ds.pint.quantify({"a": "m"}) + In [6]: temporary_ds = xr.Dataset({"a": ("x", [0, 5, 10])}, coords={"x": [1, 2, 3]}) + ...: temporary_ds.pint.quantify({"a": "m"}) Of course, we could use :py:class:`pint.Unit` instances instead of strings to specify units, too. If we wanted to change the units of the data of a :py:class:`DataArray`, we could do so using the :py:attr:`DataArray.name` attribute: -.. ipython:: python +.. ipython:: - da.pint.quantify({da.name: "J", "lat": "degree", "lon": "degree"}) + In [7]: da.pint.quantify({da.name: "J", "lat": "degree", "lon": "degree"}) However, `xarray`_ currently doesn't support `units in indexes`_, so the new units were set as attributes. To really observe the changes the ``quantify`` methods make, we have to first swap the dimensions: -.. ipython:: python +.. ipython:: + + In [8]: ds_with_units = ds.swap_dims({"lon": "x", "lat": "y"}).pint.quantify( + ...: {"lat": "degree", "lon": "degree"} + ...: ) + ...: ds_with_units - ds_with_units = ds.swap_dims({"lon": "x", "lat": "y"}).pint.quantify( - {"lat": "degree", "lon": "degree"} - ) - da_with_units = da.swap_dims({"lon": "x", "lat": "y"}).pint.quantify( - {"lat": "degree", "lon": "degree"} - ) - ds_with_units - da_with_units + In [9]: da_with_units = da.swap_dims({"lon": "x", "lat": "y"}).pint.quantify( + ...: {"lat": "degree", "lon": "degree"} + ...: ) + ...: da_with_units Saving with units ----------------- @@ -75,10 +78,11 @@ In order to not lose the units when saving to disk, we first have to call the :py:meth:`Dataset.pint.dequantify` and :py:meth:`DataArray.pint.dequantify` methods: -.. ipython:: python +.. ipython:: + + In [10]: ds_with_units.pint.dequantify() - ds_with_units.pint.dequantify() - da_with_units.pint.dequantify() + In [11]: da_with_units.pint.dequantify() This will get the string representation of a :py:class:`pint.Unit` instance and attach it as a ``units`` attribute. The data of the variable will now be From 9ca8d9f09066f1eb4a908f4ef2e4de9fbd86a82a Mon Sep 17 00:00:00 2001 From: Keewis Date: Tue, 18 Aug 2020 15:10:13 +0200 Subject: [PATCH 19/27] rephrase the reference to the github repository --- docs/contributing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing.rst b/docs/contributing.rst index 62d04e27..8d2bf6c5 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -1,6 +1,6 @@ Contributing ============ -All development happens on `github `_. +``pint-xarray`` is developed on `github `_. Linters / Autoformatters ------------------------ From 9dcf45df7e066c706dae9d3ddd38202ec6977849 Mon Sep 17 00:00:00 2001 From: Keewis Date: Tue, 18 Aug 2020 15:11:05 +0200 Subject: [PATCH 20/27] add a howto-guide for converting units --- docs/conversion.rst | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/docs/conversion.rst b/docs/conversion.rst index b7a0edad..292c3a50 100644 --- a/docs/conversion.rst +++ b/docs/conversion.rst @@ -1,2 +1,30 @@ +.. currentmodule:: xarray + Converting units ================ +.. ipython:: python + :suppress: + + import xarray as xr + +When working with :py:class:`Dataset` or :py:class:`DataArray` objects with +units, we frequently might want to convert the units. Suppose we have: + +.. ipython:: + + In [1]: ds = xr.Dataset( + ...: {"a": ("x", [4, 8, 12, 16])}, coords={"u": ("x", [10, 20, 30, 40])} + ...: ).pint.quantify({"a": "m", "u": "s"}) + ...: ds + + In [2]: da = ds.a + ...: da + +To convert the data to different units, we can use the +:py:meth:`Dataset.pint.to` and :py:meth:`DataArray.pint.to` methods: + +.. ipython:: + + In [3]: ds.pint.to(a="feet", u="ks") + + In [4]: da.pint.to({da.name: "nautical_mile", "u": "ms"}) From eed7d0478b6eacac43d3c2d73d1c838edd22fd45 Mon Sep 17 00:00:00 2001 From: Keewis Date: Tue, 18 Aug 2020 15:30:44 +0200 Subject: [PATCH 21/27] clean up the sphinx configuration a bit --- docs/conf.py | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 84f6bc57..d02214a4 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -70,9 +70,13 @@ # -- Extension configuration ------------------------------------------------- +# autosummary autosummary_generate = True + +# autodoc autodoc_typehints = "none" +# napoleon napoleon_use_param = False napoleon_use_rtype = True @@ -90,7 +94,6 @@ # -- Options for intersphinx extension --------------------------------------- -# Example configuration for intersphinx: refer to the Python standard library. intersphinx_mapping = { "python": ("https://docs.python.org/3/", None), "xarray": ("https://xarray.pydata.org/en/stable", None), From b241b9bbf3fb10755b620b12cef7dfedca2fc45d Mon Sep 17 00:00:00 2001 From: Keewis Date: Tue, 18 Aug 2020 15:32:39 +0200 Subject: [PATCH 22/27] configure extlinks --- docs/conf.py | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/conf.py b/docs/conf.py index d02214a4..4a83889b 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -29,6 +29,7 @@ project = "pint-xarray" author = f"{project} developers" copyright = f"{year}, {author}" +github_url = "https://github.com/xarray-contrib/pint-xarray" # -- General configuration --------------------------------------------------- @@ -38,6 +39,7 @@ # ones. extensions = [ "sphinx.ext.intersphinx", + "sphinx.ext.extlinks", "sphinx.ext.autosummary", "sphinx.ext.autodoc", "sphinx.ext.napoleon", @@ -70,6 +72,12 @@ # -- Extension configuration ------------------------------------------------- +# extlinks +extlinks = { + "issue": (f"{github_url}/issues/%s", "GH"), + "pull": (f"{github_url}/pull/%s", "PR"), +} + # autosummary autosummary_generate = True From 5b7a70f1f25a2d7d750c843a73cc02110ce3012e Mon Sep 17 00:00:00 2001 From: Keewis Date: Tue, 18 Aug 2020 15:32:52 +0200 Subject: [PATCH 23/27] add an item to the changelog --- docs/changelog.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/changelog.rst b/docs/changelog.rst index 3e58a9f2..870062d8 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -3,3 +3,4 @@ Changelog 0.1 (*unreleased*) ------------------ +- add documentation (:pull:`20`) From 99777b3f4a583b3059d8fc658606668f91bc2ff0 Mon Sep 17 00:00:00 2001 From: Keewis Date: Tue, 18 Aug 2020 15:36:35 +0200 Subject: [PATCH 24/27] add some text to the empty examples section --- docs/examples.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/examples.rst b/docs/examples.rst index bac945d5..76c315ca 100644 --- a/docs/examples.rst +++ b/docs/examples.rst @@ -1,2 +1,3 @@ Examples ======== +There are no examples yet. From ca6a8e7ae184781d27a8f827521448d218d162f9 Mon Sep 17 00:00:00 2001 From: Keewis Date: Sat, 22 Aug 2020 23:39:51 +0200 Subject: [PATCH 25/27] update the install instructions --- docs/installation.rst | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/docs/installation.rst b/docs/installation.rst index 0e415163..e454fe57 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -1,7 +1,18 @@ Installation ------------ -As there's no release, yet, ``pint-xarray`` can only be installed from -source, either directly from github: +Install from ``conda-forge``: + +.. code:: sh + + conda install -c conda-forge pint-xarray + +or from ``PyPI``: + +.. code:: sh + + python -m pip install pint-xarray + +or from source, either directly from github: .. code:: sh From 829d2be101487473e4d5f830dceb1158bf2f0c5f Mon Sep 17 00:00:00 2001 From: Keewis Date: Mon, 24 Aug 2020 17:11:37 +0200 Subject: [PATCH 26/27] avoid recommending a workflow that would break CF compliance --- docs/creation.rst | 28 ++++++++++++++++------------ 1 file changed, 16 insertions(+), 12 deletions(-) diff --git a/docs/creation.rst b/docs/creation.rst index 23427af4..ecf6c29e 100644 --- a/docs/creation.rst +++ b/docs/creation.rst @@ -15,32 +15,35 @@ Usually, when loading data from disk we get a :py:class:`Dataset` or .. ipython:: - In [1]: ds = xr.tutorial.open_dataset("air_temperature") + In [1]: ds = xr.Dataset( + ...: { + ...: "a": (("lon", "lat"), [[11.84, 3.12, 9.7], [7.8, 9.3, 14.72]]), + ...: "b": (("lon", "lat"), [[13, 2, 7], [5, 4, 9]], {"units": "m"}), + ...: }, + ...: coords={"lat": [10, 20, 30], "lon": [74, 76]}, + ...: ) ...: ds - In [2]: da = ds.air + In [2]: da = ds.b ...: da In order to get :py:class:`pint.Quantity` instances, we can use the :py:meth:`Dataset.pint.quantify` or :py:meth:`DataArray.pint.quantify` methods: .. ipython:: - :okexcept: In [3]: ds.pint.quantify() -As we can see, the dataset uses units like ``degree_north`` or ``degree_east``, -which `pint`_ doesn't know about. To fix that, we can override the units of -specific variables: +We can also override the units of a variable: .. ipython:: - In [4]: ds.pint.quantify(lat="degree", lon="degree") + In [4]: ds.pint.quantify(b="km") - In [5]: da.pint.quantify({"lat": "degree", "lon": "degree"}) + In [5]: da.pint.quantify({"b": "degree"}) Overriding works, even if there is no ``units`` attribute, so we could use this -to attach units to a ordinary :py:class:`Dataset`: +to attach units to a normal :py:class:`Dataset`: .. ipython:: @@ -48,9 +51,10 @@ to attach units to a ordinary :py:class:`Dataset`: ...: temporary_ds.pint.quantify({"a": "m"}) Of course, we could use :py:class:`pint.Unit` instances instead of strings to -specify units, too. If we wanted to change the units of the data of a -:py:class:`DataArray`, we could do so using the :py:attr:`DataArray.name` -attribute: +specify units, too. + +If we wanted to change the units of the data of a :py:class:`DataArray`, we +could do so using the :py:attr:`DataArray.name` attribute: .. ipython:: From 78c9e62768bb7453749576e0acff91e46e5f74dd Mon Sep 17 00:00:00 2001 From: Keewis Date: Wed, 26 Aug 2020 10:59:04 +0200 Subject: [PATCH 27/27] rename the changelog to whats-new --- docs/index.rst | 4 ++-- docs/{changelog.rst => whats-new.rst} | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) rename docs/{changelog.rst => whats-new.rst} (76%) diff --git a/docs/index.rst b/docs/index.rst index 452a61a0..b7bf628c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -39,7 +39,7 @@ Documentation **Help & Reference**: -- :doc:`changelog` +- :doc:`whats-new` - :doc:`api` - :doc:`contributing` @@ -48,6 +48,6 @@ Documentation :caption: Help & Reference :hidden: - changelog + whats-new api contributing diff --git a/docs/changelog.rst b/docs/whats-new.rst similarity index 76% rename from docs/changelog.rst rename to docs/whats-new.rst index 870062d8..190ca2dc 100644 --- a/docs/changelog.rst +++ b/docs/whats-new.rst @@ -1,5 +1,5 @@ -Changelog -========= +What's new +========== 0.1 (*unreleased*) ------------------