Doc and build fixes for v0.9.0

doc/api.rst

@@ -417,6 +417,7 @@ Dataset methods
    Dataset.from_dataframe
    Dataset.from_dict
    Dataset.close
+   Dataset.compute
    Dataset.load
    Dataset.chunk
    Dataset.filter_by_attrs
@@ -441,6 +442,7 @@ DataArray methods
    DataArray.from_series
    DataArray.from_cdms2
    DataArray.from_dict
+   DataArray.compute
    DataArray.load
    DataArray.chunk
 
@@ -459,14 +461,24 @@ Plotting
    plot.pcolormesh
    plot.FacetGrid
 
+Testing
+=======
+
+.. autosummary::
+   :toctree: generated/
+
+   testing.assert_equal
+   testing.assert_identical
+   testing.assert_allclose
+
 Advanced API
 ============
 
 .. autosummary::
    :toctree: generated/
 
    Variable
-   Coordinate
+   IndexVariable
    register_dataset_accessor
    register_dataarray_accessor
 
@@ -481,14 +493,3 @@ arguments for the ``from_store`` and ``dump_to_store`` Dataset methods:
    backends.H5NetCDFStore
    backends.PydapDataStore
    backends.ScipyDataStore
-
-
-Testing
-=======
-
-.. autosummary::
-   :toctree: generated/
-
-   testing.assert_equal
-   testing.assert_identical
-   testing.assert_allclose

doc/combining.rst

@@ -122,43 +122,32 @@ used in the :py:class:`~xarray.Dataset` constructor:
 Combine
 ~~~~~~~
 
-The instance method ``combine_first`` combines two datasets/data arrays and
-defaults to non-null values in the calling object, using values from the called
-object to fill holes.  The resulting coordinates are the union of coordinate labels.
-Vacant cells as a result of the outer-join are filled with nan.
-
-Mimics the behavior of ``pandas.Dataframe.combine_first``
-
-For data array,
+The instance method :py:meth:`~xarray.DataArray.combine_first` combines two
+datasets/data arrays and defaults to non-null values in the calling object,
+using values from the called object to fill holes.  The resulting coordinates
+are the union of coordinate labels. Vacant cells as a result of the outer-join
+are filled with ``NaN``. For example:
 
 .. ipython:: python
 
-    ar0 = DataArray([[0, 0], [0, 0]], [('x', ['a', 'b']), ('y', [-1, 0])])
-    ar1 = DataArray([[1, 1], [1, 1]], [('x', ['b', 'c']), ('y', [0, 1])])
-    ar2 = DataArray([2], [('x', ['d'])])
+    ar0 = xr.DataArray([[0, 0], [0, 0]], [('x', ['a', 'b']), ('y', [-1, 0])])
+    ar1 = xr.DataArray([[1, 1], [1, 1]], [('x', ['b', 'c']), ('y', [0, 1])])
     ar0.combine_first(ar1)
     ar1.combine_first(ar0)
-    ar0.combine_first(ar2)
-
-For datasets, ``ds0.combine_first(ds1)`` works similarly to ``xr.merge([ds0, ds1])``,
-except that ``xr.merge`` raises a ``MergeError`` when there are conflicting values
-in merging data variables, whereas ``.combine_first`` defaults to the calling object's values.
 
-.. ipython:: python
-
-    ds0 = Dataset({'a': ('x', [1, 2]), 'x': [0, 1]})
-    ds1 = Dataset({'a': ('x', [99, 3]), 'x': [1, 2]})
-    ds0.combine_first(ds1)
-    xr.merge([ds0, ds1])
+For datasets, ``ds0.combine_first(ds1)`` works similarly to
+``xr.merge([ds0, ds1])``, except that ``xr.merge`` raises ``MergeError`` when
+there are conflicting values in variables to be merged, whereas
+``.combine_first`` defaults to the calling object's values.
 
 .. _update:
 
 Update
 ~~~~~~
 
-In contrast to ``merge``, ``update`` modifies a dataset in-place without
-checking for conflicts, and will overwrite any existing variables with new
-values:
+In contrast to ``merge``, :py:meth:`~xarray.Dataset.update` modifies a dataset
+in-place without checking for conflicts, and will overwrite any existing
+variables with new values:
 
 .. ipython:: python
 

doc/whats-new.rst

@@ -15,17 +15,34 @@ What's New
 
 .. _whats-new.0.9.0:
 
-v0.9.0 (unreleased)
--------------------
+v0.9.0 (25 January 2017)
+------------------------
 
 This major release includes five months worth of enhancements and bug fixes from
-23 contributors, including some significant changes that are not fully backwards
+24 contributors, including some significant changes that are not fully backwards
 compatible. Highlights include:
 
-- Coordinates are now *optional* in the xarray data model, even for dimensions
+- Coordinates are now *optional* in the xarray data model, even for dimensions.
 - Changes to caching, lazy loading and pickling to improve xarray's experience
-  for parallel computing
-- Improvements for accessing and manipulating ``pandas.MultiIndex`` levels
+  for parallel computing.
+- Improvements for accessing and manipulating ``pandas.MultiIndex`` levels.
+- Many new methods and functions, including
+  :py:meth:`~DataArray.quantile`,
+  :py:meth:`~DataArray.cumsum`,
+  :py:meth:`~DataArray.cumprod`
+  :py:attr:`~DataArray.combine_first`
+  :py:meth:`~DataArray.set_index`,
+  :py:meth:`~DataArray.reset_index`,
+  :py:meth:`~DataArray.reorder_levels`,
+  :py:func:`~xarray.full_like`,
+  :py:func:`~xarray.zeros_like`,
+  :py:func:`~xarray.ones_like`
+  :py:func:`~xarray.open_dataarray`,
+  :py:meth:`~DataArray.compute`,
+  :py:meth:`Dataset.info`,
+  :py:func:`testing.assert_equal`,
+  :py:func:`testing.assert_identical`, and
+  :py:func:`testing.assert_allclose`.
 
 Breaking changes
 ~~~~~~~~~~~~~~~~
@@ -129,15 +146,13 @@ Deprecations
 Enhancements
 ~~~~~~~~~~~~
 
-- Added the xarray equivalent of `pandas.Dataframe.combine_first` as an instance
-  method to DataArray/Dataset objects, facilitated by the new `ops.fillna` with
-  `join` and `data_vars_join` options.
-  (see :ref:`combine`)
+- Added new method :py:meth:`~DataArray.combine_first` to ``DataArray`` and
+  ``Dataset``, based on the pandas method of the same name (see :ref:`combine`).
   By `Chun-Wei Yuan <https://github.com/chunweiyuan>`_.
 
 - Added the ability to change default automatic alignment (arithmetic_join="inner")
   for binary operations via :py:func:`~xarray.set_options()`
-  (see :ref:`automatic alignment`).
+  (see :ref:`math automatic alignment`).
   By `Chun-Wei Yuan <https://github.com/chunweiyuan>`_.
 
 - Add checking of ``attr`` names and values when saving to netCDF, raising useful

setup.py

@@ -141,4 +141,4 @@ def write_version_py(filename=None):
       tests_require=TESTS_REQUIRE,
       url=URL,
       packages=find_packages(),
-      package_data={'xarray': ['test/data/*', 'plot/default_colormap.csv']})
+      package_data={'xarray': ['tests/data/*', 'plot/default_colormap.csv']})

xarray/core/common.py

@@ -58,7 +58,7 @@ def wrapped_func(self, dim=None, keep_attrs=False, **kwargs):
 
     _reduce_extra_args_docstring = \
         """dim : str or sequence of str, optional
-            Dimension(s) over which to apply `func`.  By default `func` is
+            Dimension(s) over which to apply `{name}`.  By default `{name}` is
             applied over all dimensions."""
 
     _cum_extra_args_docstring = \

xarray/core/dataarray.py

@@ -825,8 +825,6 @@ def swap_dims(self, dims_dict):
             Dictionary whose keys are current dimension names and whose values
             are new names. Each value must already be a coordinate on this
             array.
-        inplace : bool, optional
-            If True, swap dimensions in-place. Otherwise, return a new object.
 
         Returns
         -------
@@ -1314,7 +1312,7 @@ def to_dict(self):
 
         See also
         --------
-        xarray.DataArray.from_dict
+        DataArray.from_dict
         """
         d = {'coords': {}, 'attrs': decode_numpy_dict_values(self.attrs),
              'dims': self.dims}
@@ -1359,8 +1357,8 @@ def from_dict(cls, d):
 
         See also
         --------
-        xarray.DataArray.to_dict
-        xarray.Dataset.from_dict
+        DataArray.to_dict
+        Dataset.from_dict
         """
         coords = None
         if 'coords' in d:
@@ -1710,7 +1708,7 @@ def dot(self, other):
 
         See also
         --------
-        np.tensordot(a, b, axes)
+        numpy.tensordot
 
         Examples
         --------
@@ -1761,14 +1759,14 @@ def quantile(self, q, dim=None, interpolation='linear', keep_attrs=False):
         Parameters
         ----------
         q : float in range of [0,1] (or sequence of floats)
-            Quantile to compute, which must be between 0 and 1
-            inclusive.
+            Quantile to compute, which must be between 0 and 1 inclusive.
         dim : str or sequence of str, optional
             Dimension(s) over which to apply quantile.
         interpolation : {'linear', 'lower', 'higher', 'midpoint', 'nearest'}
             This optional parameter specifies the interpolation method to
             use when the desired quantile lies between two data points
             ``i < j``:
+
                 * linear: ``i + (j - i) * fraction``, where ``fraction`` is
                   the fractional part of the index surrounded by ``i`` and
                   ``j``.
@@ -1792,7 +1790,7 @@ def quantile(self, q, dim=None, interpolation='linear', keep_attrs=False):
 
         See Also
         --------
-        np.nanpercentile, pd.Series.quantile, xr.Dataset.quantile
+        numpy.nanpercentile, pandas.Series.quantile, Dataset.quantile
         """
 
         ds = self._to_temp_dataset().quantile(q, dim=dim, keep_attrs=keep_attrs,

xarray/core/dataset.py

@@ -2286,7 +2286,7 @@ def to_dict(self):
 
         See also
         --------
-        xarray.Dataset.from_dict
+        Dataset.from_dict
         """
         d = {'coords': {}, 'attrs': decode_numpy_dict_values(self.attrs),
              'dims': dict(self.dims), 'data_vars': {}}
@@ -2338,8 +2338,8 @@ def from_dict(cls, d):
 
         See also
         --------
-        xarray.Dataset.to_dict
-        xarray.DataArray.from_dict
+        Dataset.to_dict
+        DataArray.from_dict
         """
 
         if not set(['coords', 'data_vars']).issubset(set(d)):
@@ -2645,14 +2645,14 @@ def quantile(self, q, dim=None, interpolation='linear',
         Parameters
         ----------
         q : float in range of [0,1] (or sequence of floats)
-            Quantile to compute, which must be between 0 and 1
-            inclusive.
+            Quantile to compute, which must be between 0 and 1 inclusive.
         dim : str or sequence of str, optional
             Dimension(s) over which to apply quantile.
         interpolation : {'linear', 'lower', 'higher', 'midpoint', 'nearest'}
             This optional parameter specifies the interpolation method to
             use when the desired quantile lies between two data points
             ``i < j``:
+
                 * linear: ``i + (j - i) * fraction``, where ``fraction`` is
                   the fractional part of the index surrounded by ``i`` and
                   ``j``.
@@ -2678,7 +2678,7 @@ def quantile(self, q, dim=None, interpolation='linear',
 
         See Also
         --------
-        np.nanpercentile, pd.Series.quantile, xr.DataArray.quantile
+        numpy.nanpercentile, pandas.Series.quantile, DataArray.quantile
         """
 
         if isinstance(dim, basestring):

xarray/core/extensions.py

@@ -98,7 +98,7 @@ def plot(self):
 
     See also
     --------
-    xarray.register_dataset_accessor
+    register_dataset_accessor
     """
     return _register_accessor(name, DataArray)
 
@@ -114,6 +114,6 @@ def register_dataset_accessor(name):
 
     See also
     --------
-    xarray.register_dataarray_accessor
+    register_dataarray_accessor
     """
     return _register_accessor(name, Dataset)

xarray/core/ops.py

@@ -431,7 +431,7 @@ def inject_reduce_methods(cls):
         func.__name__ = name
         func.__doc__ = _REDUCE_DOCSTRING_TEMPLATE.format(
             name=name, cls=cls.__name__,
-            extra_args=cls._reduce_extra_args_docstring)
+            extra_args=cls._reduce_extra_args_docstring.format(name=name))
         setattr(cls, name, func)
 
 
@@ -443,7 +443,7 @@ def inject_cum_methods(cls):
         func.__name__ = name
         func.__doc__ = _CUM_DOCSTRING_TEMPLATE.format(
             name=name, cls=cls.__name__,
-            extra_args=cls._cum_extra_args_docstring)
+            extra_args=cls._cum_extra_args_docstring.format(name=name))
         setattr(cls, name, func)
 
 

xarray/core/options.py

@@ -1,18 +1,23 @@
 from __future__ import absolute_import
 from __future__ import division
 from __future__ import print_function
-OPTIONS = {'display_width': 80,
-           'arithmetic_join': "inner"}
+
+
+OPTIONS = {
+    'display_width': 80,
+    'arithmetic_join': 'inner',
+}
 
 
 class set_options(object):
     """Set options for xarray in a controlled context.
 
-    Currently, the only supported options are:
-    1.) display_width: maximum terminal display width of data arrays.
-                       Default=80.
-    2.) arithmetic_join: dataarray/dataset alignment in binary operations.
-                         Default='inner'.
+    Currently supported options:
+
+    - ``display_width``: maximum display width for ``repr`` on xarray objects.
+      Default: ``80``.
+    - ``arithmetic_join``: DataArray/Dataset alignment in binary operations.
+      Default: ``'inner'``.
 
     You can use ``set_options`` either as a context manager:
 

xarray/core/variable.py

@@ -1067,8 +1067,8 @@ def quantile(self, q, dim=None, interpolation='linear'):
 
         See Also
         --------
-        np.nanpercentile, pd.Series.quantile,
-        xr.Dataset.quantile, xr.DataArray.quantile
+        numpy.nanpercentile, pandas.Series.quantile, Dataset.quantile,
+        DataArray.quantile
         """
 
         if isinstance(self.data, dask_array_type):