Doc cleanup

Author: shoyer

doc/api.rst

@@ -65,7 +65,7 @@ Dataset contents
    Dataset.copy
    Dataset.merge
    Dataset.rename
-   Dataset.drop_vars
+   Dataset.drop
    Dataset.set_coords
    Dataset.reset_coords
 
@@ -164,6 +164,7 @@ DataArray contents
    :toctree: generated/
 
    DataArray.rename
+   DataArray.drop
    DataArray.reset_coords
    DataArray.copy
 

doc/combining.rst

@@ -70,8 +70,8 @@ necessary.
 
 .. _merge:
 
-Merge and ``Dataset.__init__``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Merge
+~~~~~
 
 To combine variables and coordinates between multiple Datasets, you can use the
 :py:meth:`~xray.Dataset.merge` and :py:meth:`~xray.Dataset.update` methods.
@@ -102,8 +102,8 @@ used in the :py:class:`~xray.Dataset` constructor:
 
 .. _update:
 
-Update and ``__setitem__``
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+Update
+~~~~~~
 
 In contrast, update modifies a dataset in-place without checking for conflicts,
 and will overwrite any existing variables with new values:
@@ -159,8 +159,8 @@ are constant along those new dimensions:
 
 .. ipython:: python
 
-    left = Dataset(coords={'x': 0})
-    right = Dataset({'x': [0, 0, 0]})
+    left = xray.Dataset(coords={'x': 0})
+    right = xray.Dataset({'x': [0, 0, 0]})
     left.broadcast_equals(right)
 
 Like pandas objects, two xray objects are still equal or identical if they have

doc/examples/quick-overview.rst

@@ -2,9 +2,9 @@
 Quick overview
 ##############
 
-Here are some quick examples of what you can do with xray's
-:py:class:`~xray.DataArray` object. Everything is explained in much more
-detail in the rest of the documentation.
+Here are some quick examples of what you can do with :py:class:`xray.DataArray`
+objects. Everything is explained in much more detail in the rest of the
+documentation.
 
 To begin, import numpy, pandas and xray:
 
@@ -22,29 +22,27 @@ array or list, with optional *dimensions* and *coordinates*:
 
 .. ipython:: python
 
-   xray.DataArray(np.random.randn(2, 3))
-   xray.DataArray(np.random.randn(2, 3), [('x', ['a', 'b']), ('y', [-2, 0, 2])])
+    xray.DataArray(np.random.randn(2, 3))
+    data = xray.DataArray(np.random.randn(2, 3), [('x', ['a', 'b']), ('y', [-2, 0, 2])])
+    data
 
-You can also pass in pandas data structures directly:
+If you supply a pandas :py:class:`~pandas.Series` or
+:py:class:`~pandas.DataFrame`, metadata is copied directly:
 
 .. ipython:: python
 
-    df = pd.DataFrame(np.random.randn(2, 3), index=['a', 'b'], columns=[-2, 0, 2])
-    df.index.name = 'x'
-    df.columns.name = 'y'
-    foo = xray.DataArray(df, name='foo')
-    foo
+    xray.DataArray(pd.Series(range(3), index=list('abc'), name='foo'))
 
 Here are the key properties for a ``DataArray``:
 
 .. ipython:: python
 
     # like in pandas, values is a numpy array that you can modify in-place
-    foo.values
-    foo.dims
-    foo.coords['y']
+    data.values
+    data.dims
+    data.coords
     # you can use this dictionary to store arbitrary metadata
-    foo.attrs
+    data.attrs
 
 Indexing
 --------
@@ -55,16 +53,16 @@ pandas, because we borrow pandas' indexing machinery.
 .. ipython:: python
 
     # positional and by integer label, like numpy
-    foo[[0, 1]]
+    data[[0, 1]]
 
     # positional and by coordinate label, like pandas
-    foo.loc['a':'b']
+    data.loc['a':'b']
 
     # by dimension name and integer label
-    foo.isel(x=slice(2))
+    data.isel(x=slice(2))
 
     # by dimension name and coordinate label
-    foo.sel(x=['a', 'b'])
+    data.sel(x=['a', 'b'])
 
 Computation
 -----------
@@ -73,30 +71,43 @@ Data arrays work very similarly to numpy ndarrays:
 
 .. ipython:: python
 
-    foo + 10
-    np.sin(foo)
-    foo.T
-    foo.sum()
+    data + 10
+    np.sin(data)
+    data.T
+    data.sum()
 
 However, aggregation operations can use dimension names instead of axis
 numbers:
 
 .. ipython:: python
 
-    foo.mean(dim='x')
+    data.mean(dim='x')
 
-Arithmetic operations broadcast based on dimension name, so you don't need to
-insert dummy dimensions for alignment:
+Arithmetic operations broadcast based on dimension name. This means you don't
+need to insert dummy dimensions for alignment:
 
 .. ipython:: python
 
-    bar = xray.DataArray(np.random.randn(3), [foo.coords['y']])
-    zzz = xray.DataArray(np.random.randn(4), dims='z')
+    a = xray.DataArray(np.random.randn(3), [data.coords['y']])
+    b = xray.DataArray(np.random.randn(4), dims='z')
 
-    bar
-    zzz
+    a
+    b
 
-    bar + zzz
+    a + b
+
+It also means that in most cases you do not need to worry about the order of
+dimensions:
+
+.. ipython:: python
+
+    data - data.T
+
+Operations also align based on index labels:
+
+.. ipython:: python
+
+    data[:-1] - data[:1]
 
 GroupBy
 -------
@@ -105,10 +116,10 @@ xray supports grouped operations using a very similar API to pandas:
 
 .. ipython:: python
 
-    labels = xray.DataArray(['E', 'F', 'E'], [foo.coords['y']], name='labels')
+    labels = xray.DataArray(['E', 'F', 'E'], [data.coords['y']], name='labels')
     labels
-    foo.groupby(labels).mean('y')
-    foo.groupby(labels).apply(lambda x: x - x.min())
+    data.groupby(labels).mean('y')
+    data.groupby(labels).apply(lambda x: x - x.min())
 
 Convert to pandas
 -----------------
@@ -117,5 +128,26 @@ A key feature of xray is robust conversion to and from pandas objects:
 
 .. ipython:: python
 
-    foo.to_series()
-    foo.to_pandas()
+    data.to_series()
+    data.to_pandas()
+
+Datasets and NetCDF
+-------------------
+
+:py:class:`xray.Dataset` is a dict-like container of ``DataArray`` objects that share
+index labels and dimensions. It looks a lot like a netCDF file:
+
+.. ipython:: python
+
+    ds = data.to_dataset()
+    ds
+
+You can do almost everything you can do with ``DataArray`` objects with
+``Dataset`` objects if you prefer to work with multiple variables at once.
+
+Datasets also let you easily read and write netCDF files:
+
+.. ipython:: python
+
+    ds.to_netcdf('example.nc')
+    xray.open_dataset('example.nc')

doc/groupby.rst

@@ -109,7 +109,7 @@ This last line is roughly equivalent to the following::
 
     results = []
     for label, group in ds.groupby('letters'):
-        results.append(group - alt.sel(label))
+        results.append(group - alt.sel(x=label))
     xray.concat(results, dim='x')
 
 Squeezing

doc/installing.rst

@@ -19,7 +19,8 @@ Optional dependencies:
   internal operations with xray data structures
 
 Before you install xray, be sure you have the required dependencies (numpy and
-pandas) installed. The easiest way to do so is to use the
+pandas) installed. xray is a pure Python package, but its dependencies are not.
+The easiest way to get them installed is to use the
 `Anaconda python distribution <https://store.continuum.io/cshop/anaconda/>`__.
 
 To install xray, use pip::

doc/io.rst

@@ -73,31 +73,19 @@ We can save a Dataset to disk using the
 
 .. use verbatim because readthedocs doesn't have netCDF4 support
 
-.. ipython::
-    :verbatim:
+.. ipython:: python
 
-    In [1]: ds.to_netcdf('saved_on_disk.nc')
+    ds.to_netcdf('saved_on_disk.nc')
 
 By default, the file is saved as netCDF4.
 
 We can load netCDF files to create a new Dataset using the
 :py:func:`~xray.open_dataset` function:
 
-.. ipython::
-    :verbatim:
-
-    In [1]: ds_disk = xray.open_dataset('saved_on_disk.nc')
+.. ipython:: python
 
-    In [2]: ds_disk
-    Out[2]:
-    <xray.Dataset>
-    Dimensions:  (x: 4, y: 5)
-    Index Coordinates:
-        x        (x) int64 10 20 30 40
-        y        (y) datetime64[ns] 2000-01-01 2000-01-02 2000-01-03 2000-01-04 2000-01-05
-    Variables:
-        foo      (x, y) float64 0.127 0.9667 0.2605 0.8972 0.3767 0.3362 0.4514 0.8403 0.1231 ...
-        z        (x) |S1 'a' 'b' 'c' 'd'
+    ds_disk = xray.open_dataset('saved_on_disk.nc')
+    ds_disk
 
 A dataset can also be loaded from a specific group within a netCDF
 file. To load from a group, pass a ``group`` keyword argument to the
@@ -114,24 +102,22 @@ section below.
 
     xray's lazy loading of remote or on-disk datasets is often but not always
     desirable. Before performing computationally intense operations, it is
-    usually a good idea to load a dataset entirely into memory by using the
-    :py:meth:`~xray.Dataset.load_data` method:
-
-    .. ipython::
-        :verbatim:
-
-        In [1]: ds_disk.load_data()
+    usually a good idea to load a dataset entirely into memory by invoking the
+    :py:meth:`~xray.Dataset.load_data` method.
 
 Datasets have a :py:meth:`~xray.Dataset.close` method to close the associated
 netCDF file. However, it's often cleaner to use a ``with`` statement:
 
-.. ipython::
-    :verbatim:
+.. ipython:: python
+    :suppress:
+
+    ds_disk.close()
+
+.. ipython:: python
 
     # this automatically closes the dataset after use
-    In [100]: with xray.open_dataset('saved_on_disk.nc') as ds:
-    ...           print(ds.keys())
-    Out[100]: [u'foo', u'y', u'x', u'z']
+    with xray.open_dataset('saved_on_disk.nc') as ds:
+        print(ds.keys())
 
 .. note::
 
@@ -203,7 +189,7 @@ __ http://iri.columbia.edu/
       * X        (X) float32 -125.0 -124.958 -124.917 -124.875 -124.833 -124.792 -124.75 ...
       * T        (T) float32 -779.5 -778.5 -777.5 -776.5 -775.5 -774.5 -773.5 -772.5 -771.5 ...
       * Y        (Y) float32 49.9167 49.875 49.8333 49.7917 49.75 49.7083 49.6667 49.625 ...
-    Variables:
+    Data variables:
         ppt      (T, Y, X) float64 ...
         tdmean   (T, Y, X) float64 ...
         tmax     (T, Y, X) float64 ...

doc/whats-new.rst

@@ -62,6 +62,20 @@ Breaking changes
   These operations are lightning fast thanks to integration with bottleneck_,
   which is a new optional dependency for xray (numpy is used if bottleneck is
   not installed).
+- Scalar coordinates no longer conflict with constant arrays with the same
+  value (e.g., in arithmetic, merging datasets and concat), even if they have
+  different shape (:issue:`243`). For example, the coordinate ``c`` here
+  persists through arithmetic, even though it has different shapes on each
+  DataArray:
+
+  .. ipython:: python
+
+      a = xray.DataArray([1, 2], coords={'c': 0}, dims='x')
+      b = xray.DataArray([1, 2], coords={'c': ('x', [0, 0])}, dims='x')
+      (a + b).coords
+
+  This functionality can be controlled through the ``compat`` option, which
+  has also been added to the :py:class:`~xray.Dataset` constructor.
 - We have updated our use of the terms of "coordinates" and "variables". What
   were known in previous versions of xray as "coordinates" and "variables" are
   now referred to throughout the documentation as "coordinate variables" and
@@ -80,24 +94,35 @@ Breaking changes
       ds['t.season']
 
   Previously, it returned numbered seasons 1 through 4.
-- TODO: ``broadcast_equals`` method? ``drop`` method?
 
 .. _bottleneck: https://github.com/kwgoodman/bottleneck
 
 Enhancements
 ~~~~~~~~~~~~
 
-- Support for reindexing with a fill method. This will especially useful with
-  pandas 0.16, which will support ``method='nearest'``.
+- Support for :py:meth:`~xray.Dataset.reindex` with a fill method. This
+  provides a useful shortcut for upsampling:
+
+  .. ipython:: python
+
+      data = xray.DataArray([1, 2, 3], dims='x')
+      data.reindex(x=[0.5, 1, 1.5, 2, 2.5], method='pad')
+
+  This will be especially useful once pandas 0.16 is released, at which point
+  xray will immediately support reindexing with
+  `method='nearest' <https://github.com/pydata/pandas/pull/9258>`_.
 - Use functions that return generic ndarrays with DataArray.groupby.apply and
   Dataset.apply (:issue:`327` and :issue:`329`). Thanks Jeff Gerard!
-- Consolidated the functionality of `dumps` (writing a dataset to a netCDF file
-  as a bytestring) into the `to_netcdf` method (:issue:`333`).
-- `to_netcdf` now supports writing to groups in netCDF4 files (:issue:`333`).
-- `to_netcdf` now works when netcdf4-python is not installed as long as scipy
+- Consolidated the functionality of ``dumps`` (writing a dataset to a netCDF3
+  bytestring) into :py:meth:`~xray.Dataset.to_netcdf` (:issue:`333`).
+- :py:meth:`~xray.Dataset.to_netcdf` now supports writing to groups in netCDF4
+  files (:issue:`333`). It also now has a full docstring -- you should read it!
+- :py:func:`~xray.open_dataset` and :py:meth:`~xray.Dataset.to_netcdf` now
+  work on netCDF4 files when netcdf4-python is not installed as long as scipy
   is available (:issue:`333`).
-- The new :py:meth:`~xray.Dataset.drop` method makes it easy to drop explicitly
-  listed variables or index labels:
+- The new :py:meth:`xray.Dataset.drop <Dataset.drop>` and
+  :py:meth:`xray.DataArray.drop <DataArray.drop>` methods makes it easy to drop
+  explicitly listed variables or index labels:
 
   .. ipython:: python
 
@@ -109,6 +134,8 @@ Enhancements
       arr = xray.DataArray([1, 2, 3], coords=[('x', list('abc'))])
       arr.drop(['a', 'c'], dim='x')
 
+- The :py:meth:`~xray.Dataset.broadcast_equals` has been added to correspond to
+  the new ``compat`` option.
 - TODO: added a documentation example by Joe Hamman.
 
 Bug fixes