xarray.core.variable.as_variable part of the public API

doc/api.rst

@@ -489,6 +489,7 @@ Advanced API
 
    Variable
    IndexVariable
+   as_variable
    register_dataset_accessor
    register_dataarray_accessor
 

doc/whats-new.rst

@@ -38,6 +38,10 @@ Enhancements
   to ``py.test`` (:issue:`1393`).
   By `Matthew Gidden <https://github.com/gidden>`_.
 
+- ``xarray.core.variable.as_variable`` is now part of the public API and
+  can be accessed using :py:meth:`~xarray.as_variable` (:issue:`1303`).
+  By `Benoit Bovy <https://github.com/benbovy>`_.
+
 Bug fixes
 ~~~~~~~~~
 

xarray/__init__.py

@@ -7,7 +7,7 @@
 from .core.combine import concat, auto_combine
 from .core.extensions import (register_dataarray_accessor,
                               register_dataset_accessor)
-from .core.variable import Variable, IndexVariable, Coordinate
+from .core.variable import as_variable, Variable, IndexVariable, Coordinate
 from .core.dataset import Dataset
 from .core.dataarray import DataArray
 from .core.merge import merge, MergeError

xarray/core/groupby.py

@@ -539,7 +539,7 @@ def _combine(self, applied, shortcut=False):
             combined = self._restore_dim_order(combined)
         if coord is not None:
             if shortcut:
-                combined._coords[coord.name] = as_variable(coord, copy=True)
+                combined._coords[coord.name] = as_variable(coord)
             else:
                 combined.coords[coord.name] = coord
         combined = self._maybe_restore_empty_groups(combined)

xarray/core/variable.py

@@ -28,14 +28,32 @@
     pass
 
 
-def as_variable(obj, name=None, copy=False):
-    """Convert an object into an Variable.
-
-    - If the object is already an `Variable`, return a shallow copy.
-    - Otherwise, if the object has 'dims' and 'data' attributes, convert
-      it into a new `Variable`.
-    - If all else fails, attempt to convert the object into an `Variable` by
-      unpacking it into the arguments for `Variable.__init__`.
+def as_variable(obj, name=None):
+    """Convert an object into a Variable.
+
+    Parameters
+    ----------
+    obj : object
+        Object to convert into a Variable.
+
+        - If the object is already a Variable, return a shallow copy.
+        - Otherwise, if the object has 'dims' and 'data' attributes, convert
+          it into a new Variable.
+        - If all else fails, attempt to convert the object into a Variable by
+          unpacking it into the arguments for creating a new Variable.
+    name : str, optional
+        If provided
+
+        - `obj` can be a 1D array, which is assumed to label coordinate values
+          along a dimension of this given name.
+        - Variables with name matching one of their dimensions are converted
+          into `IndexVariable` objects.
+
+    Returns
+    -------
+    var : Variable
+        The newly created variable.
+
     """
     # TODO: consider extending this method to automatically handle Iris and
     # pandas objects.
@@ -75,7 +93,7 @@ def as_variable(obj, name=None, copy=False):
                         'explicit list of dimensions: %r' % obj)
 
     if name is not None and name in obj.dims:
-        # convert the into an Index
+        # convert the Variable into an Index
         if obj.ndim != 1:
             raise ValueError(
                 '%r has more than 1-dimension and the same name as one of its '