Merge remote-tracking branch 'upstream/master'

Author: rabernat

.travis.yml

@@ -19,7 +19,7 @@ matrix:
   - python: 3.3
     env: UPDATE_ENV="conda remove netCDF4"
   - python: 3.4
-    env: UPDATE_ENV="conda install -c pandas bottleneck h5py cython dask matplotlib && pip install cyordereddict h5netcdf"
+    env: UPDATE_ENV="conda install -c pandas bottleneck h5py cython dask matplotlib seaborn && pip install cyordereddict h5netcdf"
   # don't require pydap tests to pass because the dap test server is unreliable
   - python: 2.7
     env: UPDATE_ENV="pip install pydap"

README.rst

@@ -115,5 +115,5 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
 
-xray includes portions of pandas and numpy. Their licenses are included in the
-licenses directory.
+xray includes portions of pandas, NumPy and Seaborn. Their licenses are
+included in the licenses directory.

doc/api-hidden.rst

@@ -27,12 +27,14 @@
    Dataset.count
    Dataset.dropna
    Dataset.fillna
+   Dataset.where
 
    core.groupby.DatasetGroupBy.assign
    core.groupby.DatasetGroupBy.assign_coords
    core.groupby.DatasetGroupBy.first
    core.groupby.DatasetGroupBy.last
    core.groupby.DatasetGroupBy.fillna
+   core.groupby.DatasetGroupBy.where
 
    Dataset.argsort
    Dataset.clip
@@ -66,11 +68,13 @@
    DataArray.count
    DataArray.dropna
    DataArray.fillna
+   DataArray.where
 
    core.groupby.DataArrayGroupBy.assign_coords
    core.groupby.DataArrayGroupBy.first
    core.groupby.DataArrayGroupBy.last
    core.groupby.DataArrayGroupBy.fillna
+   core.groupby.DataArrayGroupBy.where
 
    DataArray.argsort
    DataArray.clip

doc/api.rst

@@ -93,6 +93,8 @@ Indexing
    Dataset.loc
    Dataset.isel
    Dataset.sel
+   Dataset.isel_points
+   Dataset.sel_points
    Dataset.squeeze
    Dataset.reindex
    Dataset.reindex_like
@@ -129,6 +131,7 @@ Computation
 :py:attr:`~Dataset.count`
 :py:attr:`~Dataset.dropna`
 :py:attr:`~Dataset.fillna`
+:py:attr:`~Dataset.where`
 
 **ndarray methods**:
 :py:attr:`~Dataset.argsort`
@@ -144,6 +147,7 @@ Computation
 :py:attr:`~core.groupby.DatasetGroupBy.first`
 :py:attr:`~core.groupby.DatasetGroupBy.last`
 :py:attr:`~core.groupby.DatasetGroupBy.fillna`
+:py:attr:`~core.groupby.DatasetGroupBy.where`
 
 DataArray
 =========
@@ -202,6 +206,8 @@ Indexing
    DataArray.loc
    DataArray.isel
    DataArray.sel
+   DataArray.isel_points
+   DataArray.sel_points
    DataArray.squeeze
    DataArray.reindex
    DataArray.reindex_like
@@ -238,6 +244,7 @@ Computation
 :py:attr:`~DataArray.count`
 :py:attr:`~DataArray.dropna`
 :py:attr:`~DataArray.fillna`
+:py:attr:`~DataArray.where`
 
 **ndarray methods**:
 :py:attr:`~DataArray.argsort`
@@ -253,6 +260,7 @@ Computation
 :py:attr:`~core.groupby.DataArrayGroupBy.first`
 :py:attr:`~core.groupby.DataArrayGroupBy.last`
 :py:attr:`~core.groupby.DataArrayGroupBy.fillna`
+:py:attr:`~core.groupby.DataArrayGroupBy.where`
 
 Comparisons
 -----------
@@ -393,10 +401,10 @@ Plotting
 .. autosummary::
    :toctree: generated/
 
-   DataArray.plot
-   DataArray.plot_contourf
-   DataArray.plot_contour
-   DataArray.plot_hist
-   DataArray.plot_imshow
-   DataArray.plot_line
-   DataArray.plot_pcolormesh
+   plot.plot
+   plot.contourf
+   plot.contour
+   plot.hist
+   plot.imshow
+   plot.line
+   plot.pcolormesh

doc/conf.py

@@ -34,6 +34,7 @@
     print "no pandas"
 try:
     import matplotlib
+    matplotlib.use('Agg')
     print "matplotlib: %s, %s" % (matplotlib.__version__, matplotlib.__file__)
 except ImportError:
     print "no matplotlib"
@@ -42,6 +43,11 @@
     print "ipython: %s, %s" % (IPython.__version__, IPython.__file__)
 except ImportError:
     print "no ipython"
+try:
+    import seaborn
+    print "seaborn: %s, %s" % (seaborn.__version__, seaborn.__file__)
+except ImportError:
+    print "no seaborn"
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the

doc/examples/atlantic_noise.png

@@ -5,16 +5,18 @@
 
 nlat = 15
 nlon = 5
-atlantic = xray.DataArray(np.random.randn(nlat, nlon),
+arr = np.random.randn(nlat, nlon)
+arr[0, 0] = np.nan
+atlantic = xray.DataArray(arr,
         coords = (np.linspace(50, 20, nlat), np.linspace(-60, -20, nlon)),
         dims = ('latitude', 'longitude'))
 
-ax = plt.axes(projection=ccrs.PlateCarree())
+ax = plt.axes(projection=ccrs.Orthographic(-50, 30))
 
-atlantic.plot(ax=ax)
+atlantic.plot(ax=ax, origin='upper', aspect='equal',
+              transform=ccrs.PlateCarree())
 
-ax.set_ylim(0, 90)
-ax.set_xlim(-180, 30)
+ax.set_global()
 ax.coastlines()
 
 plt.savefig('atlantic_noise.png')

doc/examples/cartopy_atlantic.py

@@ -57,6 +57,7 @@ DataArray:
 
     Positional indexing deviates from the NumPy when indexing with multiple
     arrays like ``arr[[0, 1], [0, 1]]``, as described in :ref:`indexing details`.
+    See :ref:`pointwise indexing` for how to achieve this functionality in xray.
 
 xray also supports label-based indexing, just like pandas. Because
 we use a :py:class:`pandas.Index` under the hood, label based indexing is very
@@ -122,7 +123,8 @@ __ http://legacy.python.org/dev/peps/pep-0472/
 
 .. warning::
 
-    Do not try to assign values when using ``isel`` or ``sel``::
+    Do not try to assign values when using any of the indexing methods ``isel``,
+    ``isel_points``, ``sel`` or ``sel_points``::
 
         # DO NOT do this
         arr.isel(space=0) = 0
@@ -134,6 +136,35 @@ __ http://legacy.python.org/dev/peps/pep-0472/
         # this is safe
         arr[dict(space=0)] = 0
 
+.. _pointwise indexing:
+
+Pointwise indexing
+------------------
+
+xray pointwise indexing supports the indexing along multiple labeled dimensions
+using list-like objects. While :py:meth:`~xray.DataArray.isel` performs
+orthogonal indexing, the :py:meth:`~xray.DataArray.isel_points` method
+provides similar numpy indexing behavior as if you were using multiple
+lists to index an array (e.g. ``arr[[0, 1], [0, 1]]`` ):
+
+.. ipython:: python
+
+    # index by integer array indices
+    da = xray.DataArray(np.arange(56).reshape((7, 8)), dims=['x', 'y'])
+    da
+    da.isel_points(x=[0, 1, 6], y=[0, 1, 0])
+
+There is also :py:meth:`~xray.DataArray.sel_points`, which analogously
+allows you to do point-wise indexing by label:
+
+.. ipython:: python
+
+    times = pd.to_datetime(['2000-01-03', '2000-01-02', '2000-01-01'])
+    arr.sel_points(space=['IA', 'IL', 'IN'], time=times)
+
+The equivalent pandas method to ``sel_points`` is
+:py:meth:`~pandas.DataFrame.lookup`.
+
 Dataset indexing
 ----------------
 
@@ -145,13 +176,16 @@ simultaneously, returning a new dataset:
     ds = arr.to_dataset()
     ds.isel(space=[0], time=[0])
     ds.sel(time='2000-01-01')
+    ds2 = da.to_dataset()
+    ds2.isel_points(x=[0, 1, 6], y=[0, 1, 0], dim='points')
 
 Positional indexing on a dataset is not supported because the ordering of
 dimensions in a dataset is somewhat ambiguous (it can vary between different
 arrays). However, you can do normal indexing with labeled dimensions:
 
 .. ipython:: python
 
+
     ds[dict(space=[0], time=[0])]
     ds.loc[dict(time='2000-01-01')]
 
@@ -338,3 +372,33 @@ Indexing axes with monotonic decreasing labels also works, as long as the
 
     reversed_data = data[::-1]
     reversed_data.loc[3.1:0.9]
+
+Masking with ``where``
+----------------------
+
+Indexing methods on xray objects generally return a subset of the original data.
+However, it is sometimes useful to select an object with the same shape as the
+original data, but with some elements masked. To do this type of selection in
+xray, use :py:meth:`~xray.DataArray.where`:
+
+.. ipython:: python
+
+    arr = xray.DataArray(np.arange(16).reshape(4, 4), dims=['x', 'y'])
+    arr.where(arr.x + arr.y < 4)
+
+This is particularly useful for ragged indexing of multi-dimensional data,
+e.g., to apply a 2D mask to an image. Note that ``where`` follows all the
+usual xray broadcasting and alignment rules for binary operations (e.g.,
+``+``) between the object being indexed and the condition, as described in
+:ref:`comput`:
+
+.. ipython:: python
+
+    arr.where(arr.y < 2)
+
+Multi-dimensional indexing
+--------------------------
+
+Xray does not yet support efficient routines for generalized multi-dimensional
+indexing or regridding. However, we are definitely interested in adding support
+for this in the future (see :issue:`475` for the ongoing discussion).