improve the documentation of the format parameter of .pint.dequantify (#127)

* update the parameter description and add examples

* update whats-new.rst

* update the PR number

* display the result of .dequantify variable by variable

Author: keewis

docs/whats-new.rst

@@ -11,6 +11,9 @@ What's new
 - convert the note about dimension coordinates saving their units in the attributes a
   warning (:issue:`124`, :pull:`126`)
   By `Justus Magin <https://github.com/keewis>`_.
+- improve the documentation on the ``format`` parameter of :py:meth:`Dataset.pint.dequantify`
+  and :py:meth:`DataArray.pint.dequantify` (:issue:`121`, :pull:`127`)
+  By `Justus Magin <https://github.com/keewis>`_.
 - use ``cf-xarray``'s unit registry in the plotting example (:issue:`107`, :pull:`128`).
   By `Justus Magin <https://github.com/keewis>`_.
 

pint_xarray/accessors.py

@@ -375,13 +375,39 @@ def dequantify(self, format=None):
         Parameters
         ----------
         format : str, optional
-            The format used for the string representations.
+            The format specification (as accepted by pint) used for the string
+            representations.
 
         Returns
         -------
         dequantified : DataArray
             DataArray whose array data is unitless, and of the type
             that was previously wrapped by `pint.Quantity`.
+
+        See Also
+        --------
+        https://pint.readthedocs.io/en/stable/tutorial.html#string-formatting
+
+        Examples
+        --------
+        >>> da = xr.DataArray([0, 1], dims="x")
+        >>> q = da.pint.quantify("m")
+        >>> q
+        <xarray.DataArray (x: 2)>
+        <Quantity([0 1], 'meter')>
+        Dimensions without coordinates: x
+        >>> q.pint.dequantify(format="P")
+        <xarray.DataArray (x: 2)>
+        array([0, 1])
+        Dimensions without coordinates: x
+        Attributes:
+            units:    meter
+        >>> q.pint.dequantify(format="~P")
+        <xarray.DataArray (x: 2)>
+        array([0, 1])
+        Dimensions without coordinates: x
+        Attributes:
+            units:    m
         """
         units = conversion.extract_unit_attributes(self.da)
         units.update(conversion.extract_units(self.da))
@@ -1027,13 +1053,58 @@ def dequantify(self, format=None):
         Parameters
         ----------
         format : str, optional
-            The format used for the string representations.
+            The format specification (as accepted by pint) used for the string
+            representations.
 
         Returns
         -------
         dequantified : Dataset
             Dataset whose data variables are unitless, and of the type
             that was previously wrapped by ``pint.Quantity``.
+
+        See Also
+        --------
+        https://pint.readthedocs.io/en/stable/tutorial.html#string-formatting
+
+        Examples
+        --------
+        >>> ds = xr.Dataset({"a": ("x", [0, 1]), "b": ("y", [2, 3, 4])})
+        >>> q = ds.pint.quantify({"a": "m", "b": "s"})
+        >>> q
+        <xarray.Dataset>
+        Dimensions:  (x: 2, y: 3)
+        Dimensions without coordinates: x, y
+        Data variables:
+            a        (x) int64 [m] 0 1
+            b        (y) int64 [s] 2 3 4
+
+        >>> d = q.pint.dequantify(format="P")
+        >>> d.a
+        <xarray.DataArray 'a' (x: 2)>
+        array([0, 1])
+        Dimensions without coordinates: x
+        Attributes:
+            units:    meter
+        >>> d.b
+        <xarray.DataArray 'b' (y: 3)>
+        array([2, 3, 4])
+        Dimensions without coordinates: y
+        Attributes:
+            units:    second
+
+        >>> d = q.pint.dequantify(format="~P")
+        >>> d.a
+        <xarray.DataArray 'a' (x: 2)>
+        array([0, 1])
+        Dimensions without coordinates: x
+        Attributes:
+            units:    m
+        >>> d.b
+        <xarray.DataArray 'b' (y: 3)>
+        array([2, 3, 4])
+        Dimensions without coordinates: y
+        Attributes:
+            units:    s
         """
         units = conversion.extract_unit_attributes(self.ds)
         units.update(conversion.extract_units(self.ds))