Improve the documentation of swap_dims (#3331)

* add an example to DataArray.swap_dims (and fix the documented return type) * add an example to Dataset.swap_dims * fix some errors in the swapped array's repr * remove a newline * mention changes in whatsnew
pydata · Sep 22, 2019 · a5fe56a · a5fe56a
1 parent 4617e68
commit a5fe56a
Show file tree

Hide file tree

Showing 3 changed files with 45 additions and 1 deletion.
diff --git a/doc/whats-new.rst b/doc/whats-new.rst
@@ -25,6 +25,10 @@ Bug fixes
   objects remain unaddressable by weakref in order to save memory.
   (:issue:`3317`) by `Guido Imperiale <https://github.com/crusaderky>`_.
 
+Documentation
+~~~~~~~~~~~~~
+- Add examples for :py:meth:`Dataset.swap_dims` and :py:meth:`DataArray.swap_dims`.
+  By `Justus Magin <https://github.com/keewis>`_.
 
 .. _whats-new.0.13.0:
 

diff --git a/xarray/core/dataarray.py b/xarray/core/dataarray.py
@@ -1453,9 +1453,26 @@ def swap_dims(self, dims_dict: Mapping[Hashable, Hashable]) -> "DataArray":
 
         Returns
         -------
-        swapped : Dataset
+        swapped : DataArray
             DataArray with swapped dimensions.
 
+        Examples
+        --------
+        >>> arr = xr.DataArray(data=[0, 1], dims="x",
+                               coords={"x": ["a", "b"], "y": ("x", [0, 1])})
+        >>> arr
+        <xarray.DataArray (x: 2)>
+        array([0, 1])
+        Coordinates:
+          * x        (x) <U1 'a' 'b'
+            y        (x) int64 0 1
+        >>> arr.swap_dims({"x": "y"})
+        <xarray.DataArray (y: 2)>
+        array([0, 1])
+        Coordinates:
+            x        (y) <U1 'a' 'b'
+          * y        (y) int64 0 1
+
         See Also
         --------
 

diff --git a/xarray/core/dataset.py b/xarray/core/dataset.py
@@ -2679,6 +2679,29 @@ def swap_dims(
         swapped : Dataset
             Dataset with swapped dimensions.
 
+        Examples
+        --------
+        >>> ds = xr.Dataset(data_vars={"a": ("x", [5, 7]), "b": ("x", [0.1, 2.4])},
+                            coords={"x": ["a", "b"], "y": ("x", [0, 1])})
+        >>> ds
+        <xarray.Dataset>
+        Dimensions:  (x: 2)
+        Coordinates:
+          * x        (x) <U1 'a' 'b'
+            y        (x) int64 0 1
+        Data variables:
+            a        (x) int64 5 7
+            b        (x) float64 0.1 2.4
+        >>> ds.swap_dims({"x": "y"})
+        <xarray.Dataset>
+        Dimensions:  (y: 2)
+        Coordinates:
+            x        (y) <U1 'a' 'b'
+          * y        (y) int64 0 1
+        Data variables:
+            a        (y) int64 5 7
+            b        (y) float64 0.1 2.4
+
         See Also
         --------