From 6630c53626965a8741561c66a4a86565c9eeefcd Mon Sep 17 00:00:00 2001 From: Stephan Hoyer Date: Tue, 24 Jan 2017 21:49:53 -0800 Subject: [PATCH] Doc and build fixes for v0.9.0 Fixes GH858 Fixes GH925 --- doc/api.rst | 25 +++++++++++++------------ doc/combining.rst | 39 ++++++++++++++------------------------- doc/whats-new.rst | 37 ++++++++++++++++++++++++++----------- setup.py | 2 +- xarray/core/common.py | 2 +- xarray/core/dataarray.py | 16 +++++++--------- xarray/core/dataset.py | 12 ++++++------ xarray/core/extensions.py | 4 ++-- xarray/core/ops.py | 4 ++-- xarray/core/options.py | 19 ++++++++++++------- xarray/core/variable.py | 4 ++-- xarray/testing.py | 14 +++----------- xray.py | 8 -------- 13 files changed, 89 insertions(+), 97 deletions(-) delete mode 100644 xray.py diff --git a/doc/api.rst b/doc/api.rst index e9e23043481..7ac9b9f7c0e 100644 --- a/doc/api.rst +++ b/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,6 +461,16 @@ Plotting plot.pcolormesh plot.FacetGrid +Testing +======= + +.. autosummary:: + :toctree: generated/ + + testing.assert_equal + testing.assert_identical + testing.assert_allclose + Advanced API ============ @@ -466,7 +478,7 @@ Advanced API :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 diff --git a/doc/combining.rst b/doc/combining.rst index f08cdee2527..388cc2ba5f3 100644 --- a/doc/combining.rst +++ b/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 diff --git a/doc/whats-new.rst b/doc/whats-new.rst index 906e586a6a6..629905845b2 100644 --- a/doc/whats-new.rst +++ b/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 `_. - 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 `_. - Add checking of ``attr`` names and values when saving to netCDF, raising useful diff --git a/setup.py b/setup.py index 8e37e03b2f4..c78d8a6fc0f 100644 --- a/setup.py +++ b/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']}) diff --git a/xarray/core/common.py b/xarray/core/common.py index f81a8bde460..62384609f43 100644 --- a/xarray/core/common.py +++ b/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 = \ diff --git a/xarray/core/dataarray.py b/xarray/core/dataarray.py index 3f9313354a5..0b9b9a2d89d 100644 --- a/xarray/core/dataarray.py +++ b/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, diff --git a/xarray/core/dataset.py b/xarray/core/dataset.py index ab2852fd972..584d9671e54 100644 --- a/xarray/core/dataset.py +++ b/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): diff --git a/xarray/core/extensions.py b/xarray/core/extensions.py index ca43f37c79e..708e1729db5 100644 --- a/xarray/core/extensions.py +++ b/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) diff --git a/xarray/core/ops.py b/xarray/core/ops.py index 3516efe7321..a7367f7ebcf 100644 --- a/xarray/core/ops.py +++ b/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) diff --git a/xarray/core/options.py b/xarray/core/options.py index 65264bf4919..abae7427f9a 100644 --- a/xarray/core/options.py +++ b/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: diff --git a/xarray/core/variable.py b/xarray/core/variable.py index bd08acf4094..37e31400247 100644 --- a/xarray/core/variable.py +++ b/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): diff --git a/xarray/testing.py b/xarray/testing.py index c288239aefc..85927561138 100644 --- a/xarray/testing.py +++ b/xarray/testing.py @@ -44,10 +44,7 @@ def assert_equal(a, b): See also -------- - assert_identical - assert_allclose - xarray.Dataset.equals - xarray.DataArray.equals + assert_identical, assert_allclose, Dataset.equals, DataArray.equals, numpy.testing.assert_array_equal """ import xarray as xr @@ -75,10 +72,7 @@ def assert_identical(a, b): See also -------- - assert_equal - assert_allclose - xarray.Dataset.equals - xarray.DataArray.equals + assert_equal, assert_allclose, Dataset.equals, DataArray.equals """ import xarray as xr ___tracebackhide__ = True # noqa: F841 @@ -116,9 +110,7 @@ def assert_allclose(a, b, rtol=1e-05, atol=1e-08, decode_bytes=True): See also -------- - assert_identical - assert_equal - numpy.testing.assert_allclose + assert_identical, assert_equal, numpy.testing.assert_allclose """ import xarray as xr ___tracebackhide__ = True # noqa: F841 diff --git a/xray.py b/xray.py deleted file mode 100644 index 934890a96a2..00000000000 --- a/xray.py +++ /dev/null @@ -1,8 +0,0 @@ -import warnings -from xarray import * -from xarray import __version__ - -warnings.warn('xray has been renamed to xarray! Please install xarray to get ' - 'future releases, and update your imports from "import xray" to ' - '"import xarray as xr". See http://xarray.pydata.org for more ' - 'details.', DeprecationWarning)