Coordinate -> IndexVariable and other deprecations (#993)

* Coordinate -> IndexVariable and other deprecations

- Renamed the ``Coordinate`` class from xarray's low level API to
  ``IndexVariable``.
- Deprecated supplying ``coords`` as a dictionary to the ``DataArray``
  constructor without also supplying an explicit ``dims`` argument. The old
  behavior encouraged relying on the iteration order of dictionaries, which is
  a bad practice (GH727).
- Removed a number of methods deprecated since v0.7.0 or earlier:
  ``load_data``, ``vars``, ``drop_vars``, ``dump``, ``dumps`` and the
  ``variables`` keyword argument alias to ``Dataset``.

* Rename to_coord() -> to_index_variable()

Author: shoyer

doc/whats-new.rst

@@ -21,6 +21,22 @@ v0.9.0 (unreleased)
 Breaking changes
 ~~~~~~~~~~~~~~~~
 
+Deprecations
+~~~~~~~~~~~~
+
+- Renamed the ``Coordinate`` class from xarray's low level API to
+  :py:class:`~xarray.IndexVariable`. ``Variable.to_variable`` and
+  ``Variable.to_coord`` have been renamed to
+  :py:meth:`~xarray.Variable.to_base_variable` and
+  :py:meth:`~xarray.Variable.to_index_variable`.
+- Deprecated supplying ``coords`` as a dictionary to the ``DataArray``
+  constructor without also supplying an explicit ``dims`` argument. The old
+  behavior encouraged relying on the iteration order of dictionaries, which is
+  a bad practice (:issue:`727`).
+- Removed a number of methods deprecated since v0.7.0 or earlier:
+  ``load_data``, ``vars``, ``drop_vars``, ``dump``, ``dumps`` and the
+  ``variables`` keyword argument to ``Dataset``.
+
 Enhancements
 ~~~~~~~~~~~~
 

xarray/__init__.py

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

xarray/core/alignment.py

@@ -9,7 +9,7 @@
 from .common import _maybe_promote
 from .pycompat import iteritems, OrderedDict
 from .utils import is_full_slice, is_dict_like
-from .variable import Variable, Coordinate
+from .variable import Variable, IndexVariable
 
 
 def _get_joiner(join):
@@ -119,7 +119,7 @@ def reindex_variables(variables, indexes, indexers, method=None,
     variables : dict-like
         Dictionary of xarray.Variable objects.
     indexes : dict-like
-        Dictionary of xarray.Coordinate objects associated with variables.
+        Dictionary of xarray.IndexVariable objects associated with variables.
     indexers : dict
         Dictionary with keys given by dimension names and values given by
         arrays of coordinates tick labels. Any mis-matched coordinate values
@@ -200,8 +200,8 @@ def var_indexers(var, indexers):
     for name, var in iteritems(variables):
         if name in indexers:
             # no need to copy, because index data is immutable
-            new_var = Coordinate(var.dims, indexers[name], var.attrs,
-                                 var.encoding)
+            new_var = IndexVariable(var.dims, indexers[name], var.attrs,
+                                    var.encoding)
         else:
             assign_to = var_indexers(var, to_indexers)
             assign_from = var_indexers(var, from_indexers)

xarray/core/combine.py

@@ -6,7 +6,7 @@
 from .alignment import align
 from .merge import merge
 from .pycompat import iteritems, OrderedDict, basestring
-from .variable import Variable, as_variable, Coordinate, concat as concat_vars
+from .variable import Variable, as_variable, IndexVariable, concat as concat_vars
 
 
 def concat(objs, dim=None, data_vars='all', coords='different',
@@ -125,14 +125,14 @@ def _calc_concat_dim_coord(dim):
     if isinstance(dim, basestring):
         coord = None
     elif not hasattr(dim, 'dims'):
-        # dim is not a DataArray or Coordinate
+        # dim is not a DataArray or IndexVariable
         dim_name = getattr(dim, 'name', None)
         if dim_name is None:
             dim_name = 'concat_dim'
-        coord = Coordinate(dim_name, dim)
+        coord = IndexVariable(dim_name, dim)
         dim = dim_name
     elif not hasattr(dim, 'name'):
-        coord = as_variable(dim).to_coord()
+        coord = as_variable(dim).to_index_variable()
         dim, = coord.dims
     else:
         coord = dim

xarray/core/common.py

@@ -326,7 +326,7 @@ def groupby(self, group, squeeze=True):
 
         Parameters
         ----------
-        group : str, DataArray or Coordinate
+        group : str, DataArray or IndexVariable
             Array whose unique values should be used to group this array. If a
             string, must be the name of a variable contained in this dataset.
         squeeze : boolean, optional
@@ -353,7 +353,7 @@ def groupby_bins(self, group, bins, right=True, labels=None, precision=3,
 
         Parameters
         ----------
-        group : str, DataArray or Coordinate
+        group : str, DataArray or IndexVariable
             Array whose binned values should be used to group this array. If a
             string, must be the name of a variable contained in this dataset.
         bins : int or array of scalars

xarray/core/coordinates.py

@@ -177,8 +177,7 @@ class DataArrayCoordinates(AbstractCoordinates):
     """Dictionary like container for DataArray coordinates.
 
     Essentially an OrderedDict with keys given by the array's
-    dimensions and the values given by the corresponding xarray.Coordinate
-    objects.
+    dimensions and the values given by corresponding DataArray objects.
     """
     def __init__(self, dataarray):
         self._data = dataarray

xarray/core/dataarray.py

@@ -17,7 +17,7 @@
 from .coordinates import DataArrayCoordinates, Indexes
 from .dataset import Dataset
 from .pycompat import iteritems, basestring, OrderedDict, zip
-from .variable import (as_variable, Variable, as_compatible_data, Coordinate,
+from .variable import (as_variable, Variable, as_compatible_data, IndexVariable,
                        default_index_coordinate)
 from .formatting import format_item
 
@@ -39,11 +39,14 @@ def _infer_coords_and_dims(shape, coords, dims):
         if coords is not None and len(coords) == len(shape):
             # try to infer dimensions from coords
             if utils.is_dict_like(coords):
-                # TODO: deprecate this path
+                warnings.warn('inferring DataArray dimensions from dictionary '
+                              'like ``coords`` has been deprecated. Use an '
+                              'explicit list of ``dims`` instead.',
+                              FutureWarning, stacklevel=3)
                 dims = list(coords.keys())
             else:
                 for n, (dim, coord) in enumerate(zip(dims, coords)):
-                    coord = as_variable(coord, name=dims[n]).to_coord()
+                    coord = as_variable(coord, name=dims[n]).to_index_variable()
                     dims[n] = coord.name
         dims = tuple(dims)
     else:
@@ -142,7 +145,7 @@ class DataArray(AbstractArray, BaseDataObject):
     values : np.ndarray
         Access or modify DataArray values as a numpy array.
     coords : dict-like
-        Dictionary of Coordinate objects that label values along each dimension.
+        Dictionary of DataArray objects that label values along each dimension.
     name : str or None
         Name of this array.
     attrs : OrderedDict
@@ -197,7 +200,7 @@ def __init__(self, data, coords=None, dims=None, name=None,
                     coords = [data.index]
                 elif isinstance(data, pd.DataFrame):
                     coords = [data.index, data.columns]
-                elif isinstance(data, (pd.Index, Coordinate)):
+                elif isinstance(data, (pd.Index, IndexVariable)):
                     coords = [data]
                 elif isinstance(data, pd.Panel):
                     coords = [data.items, data.major_axis, data.minor_axis]
@@ -245,7 +248,7 @@ def _replace_indexes(self, indexes):
             return self
         coords = self._coords.copy()
         for name, idx in indexes.items():
-            coords[name] = Coordinate(name, idx)
+            coords[name] = IndexVariable(name, idx)
         obj = self._replace(coords=coords)
 
         # switch from dimension to level names, if necessary
@@ -535,12 +538,6 @@ def load(self):
         self._coords = new._coords
         return self
 
-    def load_data(self):  # pragma: no cover
-        warnings.warn('the DataArray method `load_data` has been deprecated; '
-                      'use `load` instead',
-                      FutureWarning, stacklevel=2)
-        return self.load()
-
     def copy(self, deep=True):
         """Returns a copy of this array.
 

xarray/core/dataset.py

@@ -20,7 +20,7 @@
 from .merge import (dataset_update_method, dataset_merge_method,
                     merge_data_and_coords)
 from .utils import Frozen, SortedKeysDict, maybe_wrap_array, hashable
-from .variable import (Variable, as_variable, Coordinate, broadcast_variables)
+from .variable import (Variable, as_variable, IndexVariable, broadcast_variables)
 from .pycompat import (iteritems, basestring, OrderedDict,
                        dask_array_type)
 from .combine import concat
@@ -157,7 +157,7 @@ class Dataset(Mapping, ImplementsDatasetReduce, BaseDataObject,
     groupby_cls = groupby.DatasetGroupBy
 
     def __init__(self, data_vars=None, coords=None, attrs=None,
-                 compat='broadcast_equals', **kwargs):
+                 compat='broadcast_equals'):
         """To load data from a file or file-like object, use the `open_dataset`
         function.
 
@@ -183,7 +183,7 @@ def __init__(self, data_vars=None, coords=None, attrs=None,
             Global attributes to save on this dataset.
         compat : {'broadcast_equals', 'equals', 'identical'}, optional
             String indicating how to compare variables of the same name for
-            potential conflicts:
+            potential conflicts when initializing this dataset:
 
             - 'broadcast_equals': all values must be equal when variables are
               broadcast against each other to ensure common dimensions.
@@ -196,14 +196,6 @@ def __init__(self, data_vars=None, coords=None, attrs=None,
         self._dims = {}
         self._attrs = None
         self._file_obj = None
-        if kwargs:
-            if 'variables' in kwargs:
-                data_vars = kwargs.pop('variables')
-                warnings.warn('`variables` kwarg is deprecated. Use '
-                              '`data_vars` instead.', stacklevel=2)
-            if kwargs:
-                raise TypeError(
-                    '{0} are not valid kwargs'.format(kwargs.keys()))
         if data_vars is None:
             data_vars = {}
         if coords is None:
@@ -326,12 +318,6 @@ def load(self):
 
         return self
 
-    def load_data(self):  # pragma: no cover
-        warnings.warn('the Dataset method `load_data` has been deprecated; '
-                      'use `load` instead',
-                      FutureWarning, stacklevel=2)
-        return self.load()
-
     @classmethod
     def _construct_direct(cls, variables, coord_names, dims=None, attrs=None,
                           file_obj=None):
@@ -398,7 +384,7 @@ def _replace_indexes(self, indexes):
             return self
         variables = self._variables.copy()
         for name, idx in indexes.items():
-            variables[name] = Coordinate(name, idx)
+            variables[name] = IndexVariable(name, idx)
         obj = self._replace_vars_and_dims(variables)
 
         # switch from dimension to level names, if necessary
@@ -641,13 +627,6 @@ def data_vars(self):
         """
         return DataVariables(self)
 
-    @property
-    def vars(self):  # pragma: no cover
-        warnings.warn('the Dataset property `vars` has been deprecated; '
-                      'use `data_vars` instead',
-                      FutureWarning, stacklevel=2)
-        return self.data_vars
-
     def set_coords(self, names, inplace=False):
         """Given names of one or more variables, set them as coordinates
 
@@ -781,9 +760,6 @@ def to_netcdf(self, path=None, mode='w', format=None, group=None,
         return to_netcdf(self, path, mode, format=format, group=group,
                          engine=engine, encoding=encoding)
 
-    dump = utils.function_alias(to_netcdf, 'dump')
-    dumps = utils.function_alias(to_netcdf, 'dumps')
-
     def __unicode__(self):
         return formatting.dataset_repr(self)
 
@@ -1303,7 +1279,10 @@ def swap_dims(self, dims_dict, inplace=False):
 
         for k, v in iteritems(self.variables):
             dims = tuple(dims_dict.get(dim, dim) for dim in v.dims)
-            var = v.to_coord() if k in result_dims else v.to_variable()
+            if k in result_dims:
+                var = v.to_index_variable()
+            else:
+                var = v.to_base_variable()
             var.dims = dims
             variables[k] = var
 
@@ -1326,7 +1305,7 @@ def _stack_once(self, dims, new_dim):
 
         idx = utils.multiindex_from_product_levels(
             [self.indexes[d] for d in dims], names=dims)
-        variables[new_dim] = Coordinate(new_dim, idx)
+        variables[new_dim] = IndexVariable(new_dim, idx)
 
         coord_names = set(self._coord_names) - set(dims) | set([new_dim])
 
@@ -1404,7 +1383,7 @@ def unstack(self, dim):
                     variables[name] = var
 
         for name, lev in zip(new_dim_names, index.levels):
-            variables[name] = Coordinate(name, lev)
+            variables[name] = IndexVariable(name, lev)
 
         coord_names = set(self._coord_names) - set([dim]) | set(new_dim_names)
 
@@ -1533,12 +1512,6 @@ def _drop_vars(self, names):
         coord_names = set(k for k in self._coord_names if k in variables)
         return self._replace_vars_and_dims(variables, coord_names)
 
-    def drop_vars(self, *names):  # pragma: no cover
-        warnings.warn('the Dataset method `drop_vars` has been deprecated; '
-                      'use `drop` instead',
-                      FutureWarning, stacklevel=2)
-        return self.drop(names)
-
     def transpose(self, *dims):
         """Return a new Dataset object with all array dimensions transposed.
 

xarray/core/formatting.py

@@ -99,7 +99,7 @@ def format_timestamp(t):
         datetime_str = unicode_type(pd.Timestamp(t))
     except OutOfBoundsDatetime:
         datetime_str = unicode_type(t)
-        
+
     try:
         date_str, time_str = datetime_str.split()
     except ValueError:
@@ -271,7 +271,7 @@ def indexes_repr(indexes):
 
 
 def array_repr(arr):
-    # used for DataArray, Variable and Coordinate
+    # used for DataArray, Variable and IndexVariable
     if hasattr(arr, 'name') and arr.name is not None:
         name_str = '%r ' % arr.name
     else:

xarray/core/groupby.py

@@ -10,7 +10,7 @@
 )
 from .pycompat import zip
 from .utils import peek_at, maybe_wrap_array, safe_cast_to_index
-from .variable import as_variable, Variable, Coordinate
+from .variable import as_variable, Variable, IndexVariable
 
 
 def unique_value_groups(ar, sort=True):
@@ -63,6 +63,7 @@ def _dummy_copy(xarray_obj):
                         dict((k, _get_fill_value(v.dtype))
                              for k, v in xarray_obj.coords.items()
                              if k not in xarray_obj.dims),
+                        dims=[],
                         name=xarray_obj.name,
                         attrs=xarray_obj.attrs)
     else:  # pragma: no cover
@@ -140,7 +141,7 @@ def __init__(self, obj, group, squeeze=False, grouper=None, bins=None,
         ----------
         obj : Dataset or DataArray
             Object to group.
-        group : DataArray or Coordinate
+        group : DataArray or IndexVariable
             1-dimensional array with the group values.
         squeeze : boolean, optional
             If "group" is a coordinate of object, `squeeze` controls whether
@@ -206,7 +207,7 @@ def __init__(self, obj, group, squeeze=False, grouper=None, bins=None,
             sbins = first_items.values.astype(np.int64)
             group_indices = ([slice(i, j) for i, j in zip(sbins[:-1], sbins[1:])] +
                              [slice(sbins[-1], None)])
-            unique_coord = Coordinate(group.name, first_items.index)
+            unique_coord = IndexVariable(group.name, first_items.index)
         elif group.name in obj.dims and bins is None:
             # assume that group already has sorted, unique values
             # (if using bins, the group will have the same name as a dimension
@@ -224,7 +225,7 @@ def __init__(self, obj, group, squeeze=False, grouper=None, bins=None,
             # look through group to find the unique values
             sort = bins is None
             unique_values, group_indices = unique_value_groups(group, sort=sort)
-            unique_coord = Coordinate(group.name, unique_values)
+            unique_coord = IndexVariable(group.name, unique_values)
 
         self.obj = obj
         self.group = group