From 954b8d0ce72eadba812821a2e64ae0ef4ceb2767 Mon Sep 17 00:00:00 2001 From: Stephan Hoyer Date: Wed, 16 May 2018 18:11:00 -0700 Subject: [PATCH] Doc updates for 0.10.4 release (#2138) * Doc updates for 0.10.4 release * Fix to_netcdf() with engine=h5netcdf entry in whatsnew --- doc/api.rst | 38 ++++++++++++++++++++++++++++++-------- doc/faq.rst | 14 +++++++++----- doc/whats-new.rst | 41 ++++++++++++++++++++++++----------------- 3 files changed, 63 insertions(+), 30 deletions(-) diff --git a/doc/api.rst b/doc/api.rst index ff708dc4c1b..a528496bb6a 100644 --- a/doc/api.rst +++ b/doc/api.rst @@ -496,6 +496,19 @@ DataArray methods DataArray.load DataArray.chunk +GroupBy objects +=============== + +.. autosummary:: + :toctree: generated/ + + core.groupby.DataArrayGroupBy + core.groupby.DataArrayGroupBy.apply + core.groupby.DataArrayGroupBy.reduce + core.groupby.DatasetGroupBy + core.groupby.DatasetGroupBy.apply + core.groupby.DatasetGroupBy.reduce + Rolling objects =============== @@ -509,18 +522,27 @@ Rolling objects core.rolling.DatasetRolling.construct core.rolling.DatasetRolling.reduce -GroupByObjects -============== +Resample objects +================ + +Resample objects also implement the GroupBy interface +(methods like ``apply()``, ``reduce()``, ``mean()``, ``sum()``, etc.). .. autosummary:: :toctree: generated/ - core.groupby.DataArrayGroupBy - core.groupby.DataArrayGroupBy.apply - core.groupby.DataArrayGroupBy.reduce - core.groupby.DatasetGroupBy - core.groupby.DatasetGroupBy.apply - core.groupby.DatasetGroupBy.reduce + core.resample.DataArrayResample + core.resample.DataArrayResample.asfreq + core.resample.DataArrayResample.backfill + core.resample.DataArrayResample.interpolate + core.resample.DataArrayResample.nearest + core.resample.DataArrayResample.pad + core.resample.DatasetResample + core.resample.DatasetResample.asfreq + core.resample.DatasetResample.backfill + core.resample.DatasetResample.interpolate + core.resample.DatasetResample.nearest + core.resample.DatasetResample.pad Custom Indexes ============== diff --git a/doc/faq.rst b/doc/faq.rst index 46f1e20f4e8..360cdb50791 100644 --- a/doc/faq.rst +++ b/doc/faq.rst @@ -1,3 +1,5 @@ +.. _faq: + Frequently Asked Questions ========================== @@ -129,8 +131,8 @@ What other netCDF related Python libraries should I know about? `netCDF4-python`__ provides a lower level interface for working with netCDF and OpenDAP datasets in Python. We use netCDF4-python internally in xarray, and have contributed a number of improvements and fixes upstream. xarray -does not yet support all of netCDF4-python's features, such as writing to -netCDF groups or modifying files on-disk. +does not yet support all of netCDF4-python's features, such as modifying files +on-disk. __ https://github.com/Unidata/netcdf4-python @@ -153,10 +155,12 @@ __ http://drclimate.wordpress.com/2014/01/02/a-beginners-guide-to-scripting-with We think the design decisions we have made for xarray (namely, basing it on pandas) make it a faster and more flexible data analysis tool. That said, Iris -and CDAT have some great domain specific functionality, and we would love to -have support for converting their native objects to and from xarray (see -:issue:`37` and :issue:`133`) +and CDAT have some great domain specific functionality, and xarray includes +methods for converting back and forth between xarray and these libraries. See +:py:meth:`~xarray.DataArray.to_iris` and :py:meth:`~xarray.DataArray.to_cdms2` +for more details. +.. _faq.other_projects: What other projects leverage xarray? ------------------------------------ diff --git a/doc/whats-new.rst b/doc/whats-new.rst index 1b696c4486d..fbe7fc5edca 100644 --- a/doc/whats-new.rst +++ b/doc/whats-new.rst @@ -31,33 +31,37 @@ What's New v0.10.4 (unreleased) -------------------- +The minor release includes a number of bug-fixes and backwards compatible +enhancements. A highlight is ``CFTimeIndex``, which offers support for +non-standard calendars used in climate modeling. + Documentation ~~~~~~~~~~~~~ -- `FAQ `_ now lists projects that leverage xarray. + +- New FAQ entry, :ref:`faq.other_projects`. By `Deepak Cherian `_. -- `Assigning values with indexing `_ now includes examples on how to select and assign values to a :py:class:`~xarray.DataArray`. +- :ref:`assigning_values` now includes examples on how to select and assign + values to a :py:class:`~xarray.DataArray` with ``.loc``. By `Chiara Lepore `_. - Enhancements ~~~~~~~~~~~~ -- Slight modification in `rolling` with dask.array and bottleneck. Also, fixed a bug in rolling an - integer dask array. - By `Keisuke Fujii `_. - Add an option for using a ``CFTimeIndex`` for indexing times with non-standard calendars and/or outside the Timestamp-valid range; this index enables a subset of the functionality of a standard - ``pandas.DatetimeIndex`` (:issue:`789`, :issue:`1084`, :issue:`1252`). + ``pandas.DatetimeIndex``. + See :ref:`CFTimeIndex` for full details. + (:issue:`789`, :issue:`1084`, :issue:`1252`) By `Spencer Clark `_ with help from `Stephan Hoyer `_. - Allow for serialization of ``cftime.datetime`` objects (:issue:`789`, :issue:`1084`, :issue:`2008`, :issue:`1252`) using the standalone ``cftime`` - library. By `Spencer Clark - `_. + library. + By `Spencer Clark `_. - Support writing lists of strings as netCDF attributes (:issue:`2044`). By `Dan Nowacki `_. -- :py:meth:`~xarray.Dataset.to_netcdf(engine='h5netcdf')` now accepts h5py +- :py:meth:`~xarray.Dataset.to_netcdf` with ``engine='h5netcdf'`` now accepts h5py encoding settings ``compression`` and ``compression_opts``, along with the NetCDF4-Python style settings ``gzip=True`` and ``complevel``. This allows using any compression plugin installed in hdf5, e.g. LZF @@ -66,7 +70,8 @@ Enhancements This greatly boosts speed and allows chunking on the core dims. The function now requires dask >= 0.17.3 to work on dask-backed data (:issue:`2074`). By `Guido Imperiale `_. -- ``plot.line()`` learned new kwargs: ``xincrease``, ``yincrease`` that change the direction of the respective axes. +- ``plot.line()`` learned new kwargs: ``xincrease``, ``yincrease`` that change + the direction of the respective axes. By `Deepak Cherian `_. - Added the ``parallel`` option to :py:func:`open_mfdataset`. This option uses @@ -85,14 +90,14 @@ Enhancements Bug fixes ~~~~~~~~~ -- Now raises an Error if a coordinate with wrong size is assigned to a - :py:class:`~xarray.DataArray`. (:issue:`2112`) +- ``ValueError`` is raised when coordinates with the wrong size are assigned to + a :py:class:`DataArray`. (:issue:`2112`) By `Keisuke Fujii `_. -- Fixed a bug in `rolling` with bottleneck. Also, fixed a bug in rolling an - integer dask array. (:issue:`2113`) +- Fixed a bug in :py:meth:`~xarary.DatasArray.rolling` with bottleneck. Also, + fixed a bug in rolling an integer dask array. (:issue:`2113`) By `Keisuke Fujii `_. - Fixed a bug where `keep_attrs=True` flag was neglected if - :py:func:`apply_func` was used with :py:class:`Variable`. (:issue:`2114`) + :py:func:`apply_ufunc` was used with :py:class:`Variable`. (:issue:`2114`) By `Keisuke Fujii `_. - When assigning a :py:class:`DataArray` to :py:class:`Dataset`, any conflicted non-dimensional coordinates of the DataArray are now dropped. @@ -100,7 +105,9 @@ Bug fixes By `Keisuke Fujii `_. - Better error handling in ``open_mfdataset`` (:issue:`2077`). By `Stephan Hoyer `_. -- ``plot.line()`` does not call ``autofmt_xdate()`` anymore. Instead it changes the rotation and horizontal alignment of labels without removing the x-axes of any other subplots in the figure (if any). +- ``plot.line()`` does not call ``autofmt_xdate()`` anymore. Instead it changes + the rotation and horizontal alignment of labels without removing the x-axes of + any other subplots in the figure (if any). By `Deepak Cherian `_. - Colorbar limits are now determined by excluding ±Infs too. By `Deepak Cherian `_.