Rename to_array to to_dataarray (#8438)

Author: max-sixty

doc/api.rst

@@ -603,7 +603,7 @@ Dataset methods
    Dataset.as_numpy
    Dataset.from_dataframe
    Dataset.from_dict
-   Dataset.to_array
+   Dataset.to_dataarray
    Dataset.to_dataframe
    Dataset.to_dask_dataframe
    Dataset.to_dict

doc/howdoi.rst

@@ -36,7 +36,7 @@ How do I ...
    * - rename a variable, dimension or coordinate
      - :py:meth:`Dataset.rename`, :py:meth:`DataArray.rename`, :py:meth:`Dataset.rename_vars`, :py:meth:`Dataset.rename_dims`,
    * - convert a DataArray to Dataset or vice versa
-     - :py:meth:`DataArray.to_dataset`, :py:meth:`Dataset.to_array`, :py:meth:`Dataset.to_stacked_array`, :py:meth:`DataArray.to_unstacked_dataset`
+     - :py:meth:`DataArray.to_dataset`, :py:meth:`Dataset.to_dataarray`, :py:meth:`Dataset.to_stacked_array`, :py:meth:`DataArray.to_unstacked_dataset`
    * - extract variables that have certain attributes
      - :py:meth:`Dataset.filter_by_attrs`
    * - extract the underlying array (e.g. NumPy or Dask arrays)

doc/user-guide/reshaping.rst

@@ -59,11 +59,11 @@ use :py:meth:`~xarray.DataArray.squeeze`
 Converting between datasets and arrays
 --------------------------------------
 
-To convert from a Dataset to a DataArray, use :py:meth:`~xarray.Dataset.to_array`:
+To convert from a Dataset to a DataArray, use :py:meth:`~xarray.Dataset.to_dataarray`:
 
 .. ipython:: python
 
-    arr = ds.to_array()
+    arr = ds.to_dataarray()
     arr
 
 This method broadcasts all data variables in the dataset against each other,
@@ -77,7 +77,7 @@ To convert back from a DataArray to a Dataset, use
 
     arr.to_dataset(dim="variable")
 
-The broadcasting behavior of ``to_array`` means that the resulting array
+The broadcasting behavior of ``to_dataarray`` means that the resulting array
 includes the union of data variable dimensions:
 
 .. ipython:: python
@@ -88,7 +88,7 @@ includes the union of data variable dimensions:
     ds2
 
     # the resulting array has 6 elements
-    ds2.to_array()
+    ds2.to_dataarray()
 
 Otherwise, the result could not be represented as an orthogonal array.
 
@@ -161,8 +161,8 @@ arrays as inputs. For datasets with only one variable, we only need ``stack``
 and ``unstack``, but combining multiple variables in a
 :py:class:`xarray.Dataset` is more complicated. If the variables in the dataset
 have matching numbers of dimensions, we can call
-:py:meth:`~xarray.Dataset.to_array` and then stack along the the new coordinate.
-But :py:meth:`~xarray.Dataset.to_array` will broadcast the dataarrays together,
+:py:meth:`~xarray.Dataset.to_dataarray` and then stack along the the new coordinate.
+But :py:meth:`~xarray.Dataset.to_dataarray` will broadcast the dataarrays together,
 which will effectively tile the lower dimensional variable along the missing
 dimensions. The method :py:meth:`xarray.Dataset.to_stacked_array` allows
 combining variables of differing dimensions without this wasteful copying while

doc/whats-new.rst

@@ -41,6 +41,12 @@ Deprecations
   this was one place in the API where dimension positions were used.
   (:pull:`8341`)
   By `Maximilian Roos <https://github.com/max-sixty>`_.
+- Rename :py:meth:`Dataset.to_array` to  :py:meth:`Dataset.to_dataarray` for
+  consistency with :py:meth:`DataArray.to_dataset` &
+  :py:func:`open_dataarray` functions. This is a "soft" deprecation — the
+  existing methods work and don't raise any warnings, given the relatively small
+  benefits of the change.
+  By `Maximilian Roos <https://github.com/max-sixty>`_.
 
 Bug fixes
 ~~~~~~~~~
@@ -6709,7 +6715,7 @@ Backwards incompatible changes
 Enhancements
 ~~~~~~~~~~~~
 
-- New ``xray.Dataset.to_array`` and enhanced
+- New ``xray.Dataset.to_dataarray`` and enhanced
   ``xray.DataArray.to_dataset`` methods make it easy to switch back
   and forth between arrays and datasets:
 
@@ -6720,8 +6726,8 @@ Enhancements
           coords={"c": 42},
           attrs={"Conventions": "None"},
       )
-      ds.to_array()
-      ds.to_array().to_dataset(dim="variable")
+      ds.to_dataarray()
+      ds.to_dataarray().to_dataset(dim="variable")
 
 - New ``xray.Dataset.fillna`` method to fill missing values, modeled
   off the pandas method of the same name:

xarray/core/common.py

@@ -1173,7 +1173,7 @@ def _dataset_indexer(dim: Hashable) -> DataArray:
                     var for var in cond if dim not in cond[var].dims
                 )
                 keepany = cond_wdim.any(dim=(d for d in cond.dims.keys() if d != dim))
-                return keepany.to_array().any("variable")
+                return keepany.to_dataarray().any("variable")
 
             _get_indexer = (
                 _dataarray_indexer if isinstance(cond, DataArray) else _dataset_indexer

xarray/core/computation.py

@@ -1603,7 +1603,9 @@ def cross(
     >>> ds_a = xr.Dataset(dict(x=("dim_0", [1]), y=("dim_0", [2]), z=("dim_0", [3])))
     >>> ds_b = xr.Dataset(dict(x=("dim_0", [4]), y=("dim_0", [5]), z=("dim_0", [6])))
     >>> c = xr.cross(
-    ...     ds_a.to_array("cartesian"), ds_b.to_array("cartesian"), dim="cartesian"
+    ...     ds_a.to_dataarray("cartesian"),
+    ...     ds_b.to_dataarray("cartesian"),
+    ...     dim="cartesian",
     ... )
     >>> c.to_dataset(dim="cartesian")
     <xarray.Dataset>

xarray/core/dataset.py

@@ -1502,7 +1502,7 @@ def __array__(self, dtype=None):
                 "cannot directly convert an xarray.Dataset into a "
                 "numpy array. Instead, create an xarray.DataArray "
                 "first, either with indexing on the Dataset or by "
-                "invoking the `to_array()` method."
+                "invoking the `to_dataarray()` method."
             )
 
     @property
@@ -5260,7 +5260,7 @@ def to_stacked_array(
         """Combine variables of differing dimensionality into a DataArray
         without broadcasting.
 
-        This method is similar to Dataset.to_array but does not broadcast the
+        This method is similar to Dataset.to_dataarray but does not broadcast the
         variables.
 
         Parameters
@@ -5289,7 +5289,7 @@ def to_stacked_array(
 
         See Also
         --------
-        Dataset.to_array
+        Dataset.to_dataarray
         Dataset.stack
         DataArray.to_unstacked_dataset
 
@@ -7019,7 +7019,7 @@ def assign(
 
         return data
 
-    def to_array(
+    def to_dataarray(
         self, dim: Hashable = "variable", name: Hashable | None = None
     ) -> DataArray:
         """Convert this dataset into an xarray.DataArray
@@ -7056,6 +7056,12 @@ def to_array(
 
         return DataArray._construct_direct(variable, coords, name, indexes)
 
+    def to_array(
+        self, dim: Hashable = "variable", name: Hashable | None = None
+    ) -> DataArray:
+        """Deprecated version of to_dataarray"""
+        return self.to_dataarray(dim=dim, name=name)
+
     def _normalize_dim_order(
         self, dim_order: Sequence[Hashable] | None = None
     ) -> dict[Hashable, int]:

xarray/core/groupby.py

@@ -251,6 +251,10 @@ def to_dataarray(self) -> DataArray:
             data=self.data, dims=(self.name,), coords=self.coords, name=self.name
         )
 
+    def to_array(self) -> DataArray:
+        """Deprecated version of to_dataarray."""
+        return self.to_dataarray()
+
 
 T_Group = Union["T_DataArray", "IndexVariable", _DummyGroup]
 

xarray/tests/test_concat.py

@@ -1070,10 +1070,10 @@ def test_concat_fill_value(self, fill_value) -> None:
     def test_concat_join_kwarg(self) -> None:
         ds1 = Dataset(
             {"a": (("x", "y"), [[0]])}, coords={"x": [0], "y": [0]}
-        ).to_array()
+        ).to_dataarray()
         ds2 = Dataset(
             {"a": (("x", "y"), [[0]])}, coords={"x": [1], "y": [0.0001]}
-        ).to_array()
+        ).to_dataarray()
 
         expected: dict[JoinOptions, Any] = {}
         expected["outer"] = Dataset(
@@ -1101,7 +1101,7 @@ def test_concat_join_kwarg(self) -> None:
 
         for join in expected:
             actual = concat([ds1, ds2], join=join, dim="x")
-            assert_equal(actual, expected[join].to_array())
+            assert_equal(actual, expected[join].to_dataarray())
 
     def test_concat_combine_attrs_kwarg(self) -> None:
         da1 = DataArray([0], coords=[("x", [0])], attrs={"b": 42})
@@ -1224,7 +1224,7 @@ def test_concat_preserve_coordinate_order() -> None:
 
 def test_concat_typing_check() -> None:
     ds = Dataset({"foo": 1}, {"bar": 2})
-    da = Dataset({"foo": 3}, {"bar": 4}).to_array(dim="foo")
+    da = Dataset({"foo": 3}, {"bar": 4}).to_dataarray(dim="foo")
 
     # concatenate a list of non-homogeneous types must raise TypeError
     with pytest.raises(

xarray/tests/test_dask.py

@@ -608,11 +608,11 @@ def test_to_dataset_roundtrip(self):
         v = self.lazy_array
 
         expected = u.assign_coords(x=u["x"])
-        self.assertLazyAndEqual(expected, v.to_dataset("x").to_array("x"))
+        self.assertLazyAndEqual(expected, v.to_dataset("x").to_dataarray("x"))
 
     def test_merge(self):
         def duplicate_and_merge(array):
-            return xr.merge([array, array.rename("bar")]).to_array()
+            return xr.merge([array, array.rename("bar")]).to_dataarray()
 
         expected = duplicate_and_merge(self.eager_array)
         actual = duplicate_and_merge(self.lazy_array)
@@ -1306,12 +1306,12 @@ def test_map_blocks_kwargs(obj):
     assert_identical(actual, expected)
 
 
-def test_map_blocks_to_array(map_ds):
+def test_map_blocks_to_dataarray(map_ds):
     with raise_if_dask_computes():
-        actual = xr.map_blocks(lambda x: x.to_array(), map_ds)
+        actual = xr.map_blocks(lambda x: x.to_dataarray(), map_ds)
 
-    # to_array does not preserve name, so cannot use assert_identical
-    assert_equal(actual, map_ds.to_array())
+    # to_dataarray does not preserve name, so cannot use assert_identical
+    assert_equal(actual, map_ds.to_dataarray())
 
 
 @pytest.mark.parametrize(
@@ -1376,8 +1376,8 @@ def test_map_blocks_template_convert_object():
     assert_identical(actual, template)
 
     ds = da.to_dataset()
-    func = lambda x: x.to_array().isel(x=[1])
-    template = ds.to_array().isel(x=[1, 5, 9])
+    func = lambda x: x.to_dataarray().isel(x=[1])
+    template = ds.to_dataarray().isel(x=[1, 5, 9])
     with raise_if_dask_computes():
         actual = xr.map_blocks(func, ds, template=template)
     assert_identical(actual, template)