If join='exact', raise an error for non-aligned objects

`align` now supports ``join='exact'``, which raises `xarray.AlignmentError`
instead of aligning when indexes to be aligned are not equal.

This is useful for asserting that objects are identical instead of aligning in
xarray operations.

For example:

    ds1 = xarray.Dataset({'x': [0, 1]})
    ds2 = xarray.Dataset({'x': [1, 2]})
    xarray.merge([ds1, ds2], join='exact')
    # AlignmentError: indexes along dimension 'x' are not equal

Author: shoyer

doc/api.rst

@@ -474,6 +474,15 @@ Testing
    testing.assert_identical
    testing.assert_allclose
 
+Exceptions
+==========
+
+.. autosummary::
+   :toctree: generated/
+
+   AlignmentError
+   MergeError
+
 Advanced API
 ============
 

doc/whats-new.rst

@@ -30,6 +30,11 @@ Enhancements
   specified with `x=` or `y=`, the other dimension is now guessed. By
   `Vincent Noel <https://github.com/vnoel>`_.
 
+- :py:func:`~xarray.align` now supports ``join='exact'``, which raises
+  :py:class:`~xarray.AlignmentError` instead of aligning when indexes to be
+  aligned are not equal.
+  By `Stephan Hoyer <https://github.com/shoyer>`_.
+
 Added new method :py:meth:`~Dataset.assign_attrs` to ``DataArray`` and
 ``Dataset``, a chained-method compatible implementation of the
 ``dict.update`` method on attrs (:issue:`1281`).

xarray/__init__.py

@@ -1,7 +1,8 @@
+# flake8: noqa
 from __future__ import absolute_import
 from __future__ import division
 from __future__ import print_function
-from .core.alignment import align, broadcast, broadcast_arrays
+from .core.alignment import AlignmentError, align, broadcast, broadcast_arrays
 from .core.common import full_like, zeros_like, ones_like
 from .core.combine import concat, auto_combine
 from .core.extensions import (register_dataarray_accessor,

xarray/core/alignment.py

@@ -15,6 +15,10 @@
 from .variable import Variable, IndexVariable
 
 
+class AlignmentError(Exception):
+    """Error for when an operation cannot be done with non-aligned objects."""
+
+
 def _get_joiner(join):
     if join == 'outer':
         return functools.partial(functools.reduce, operator.or_)
@@ -24,6 +28,10 @@ def _get_joiner(join):
         return operator.itemgetter(0)
     elif join == 'right':
         return operator.itemgetter(-1)
+    elif join == 'exact':
+        # We cannot return a function to "align" in this case, because it needs
+        # access to the dimension name to give a good error message.
+        return None
     else:
         raise ValueError('invalid value for join: %s' % join)
 
@@ -47,13 +55,15 @@ def align(*objects, **kwargs):
     ----------
     *objects : Dataset or DataArray
         Objects to align.
-    join : {'outer', 'inner', 'left', 'right'}, optional
+    join : {'outer', 'inner', 'left', 'right', 'exact'}, optional
         Method for joining the indexes of the passed objects along each
         dimension:
         - 'outer': use the union of object indexes
         - 'inner': use the intersection of object indexes
         - 'left': use indexes from the first object with each dimension
         - 'right': use indexes from the last object with each dimension
+        - 'exact': raise `xarray.AlignmentError` instead of aligning when
+          indexes to be aligned are not equal
     copy : bool, optional
         If ``copy=True``, data in the return values is always copied. If
         ``copy=False`` and reindexing is unnecessary, or can be performed with
@@ -120,6 +130,10 @@ def align(*objects, **kwargs):
             if (any(not matching_indexes[0].equals(other)
                     for other in matching_indexes[1:]) or
                     dim in unlabeled_dim_sizes):
+                if join == 'exact':
+                    raise AlignmentError(
+                        'indexes along dimension {!r} are not equal'
+                        .format(dim))
                 index = joiner(matching_indexes)
                 joined_indexes[dim] = index
             else:

xarray/core/computation.py

@@ -599,6 +599,8 @@ def apply_ufunc(func, *args, **kwargs):
         - 'inner': use the intersection of object indexes
         - 'left': use indexes from the first object with each dimension
         - 'right': use indexes from the last object with each dimension
+        - 'exact': raise `xarray.AlignmentError` instead of aligning when
+          indexes to be aligned are not equal
     dataset_join : {'outer', 'inner', 'left', 'right'}, optional
         Method for joining variables of Dataset objects with mismatched
         data variables.

xarray/core/dataset.py

@@ -1833,13 +1833,14 @@ def merge(self, other, inplace=False, overwrite_vars=frozenset(),
             - 'no_conflicts': only values which are not null in both datasets
               must be equal. The returned dataset then contains the combination
               of all non-null values.
-        join : {'outer', 'inner', 'left', 'right'}, optional
+        join : {'outer', 'inner', 'left', 'right', 'exact'}, optional
             Method for joining ``self`` and ``other`` along shared dimensions:
 
             - 'outer': use the union of the indexes
             - 'inner': use the intersection of the indexes
             - 'left': use indexes from ``self``
             - 'right': use indexes from ``other``
+            - 'exact': error instead of aligning non-equal indexes
 
         Returns
         -------

xarray/core/merge.py

@@ -457,7 +457,7 @@ def merge(objects, compat='no_conflicts', join='outer'):
         - 'no_conflicts': only values which are not null in both datasets
           must be equal. The returned dataset then contains the combination
           of all non-null values.
-    join : {'outer', 'inner', 'left', 'right'}, optional
+    join : {'outer', 'inner', 'left', 'right', 'exact'}, optional
         How to combine objects with different indexes.
 
     Returns

xarray/core/ops.py

@@ -286,20 +286,28 @@ def fillna(data, other, join="left", dataset_join="left"):
 
     Parameters
     ----------
+    other : Dataset, dict, DataArray, Variable, numpy/dask array or scalar
+        Source of fill values to use to replace NaN.
     join : {'outer', 'inner', 'left', 'right'}, optional
         Method for joining the indexes of the passed objects along each
         dimension
         - 'outer': use the union of object indexes
         - 'inner': use the intersection of object indexes
         - 'left': use indexes from the first object with each dimension
         - 'right': use indexes from the last object with each dimension
+        - 'exact': raise `xarray.AlignmentError` instead of aligning when
+          indexes to be aligned are not equal
     dataset_join : {'outer', 'inner', 'left', 'right'}, optional
         Method for joining variables of Dataset objects with mismatched
         data variables.
         - 'outer': take variables from both Dataset objects
         - 'inner': take only overlapped variables
         - 'left': take only variables from the first object
         - 'right': take only variables from the last object
+
+    Returns
+    -------
+    Object of same type as this object with missing values filled.
     """
     from .computation import apply_ufunc
 

xarray/tests/test_dataset.py

@@ -1239,6 +1239,17 @@ def test_align(self):
         with self.assertRaises(TypeError):
             align(left, right, foo='bar')
 
+    def test_align_exact(self):
+        left = xr.Dataset(coords={'x': [0, 1]})
+        right = xr.Dataset(coords={'x': [1, 2]})
+
+        left1, left2 = xr.align(left, left, join='exact')
+        self.assertDatasetIdentical(left1, left)
+        self.assertDatasetIdentical(left2, left)
+
+        with self.assertRaises(xr.AlignmentError):
+            xr.align(left, right, join='exact')
+
     def test_align_exclude(self):
         x = Dataset({'foo': DataArray([[1, 2], [3, 4]], dims=['x', 'y'],
                                       coords={'x': [1, 2], 'y': [3, 4]})})

xarray/tests/test_merge.py

@@ -63,6 +63,12 @@ def test_merge_error(self):
         with self.assertRaises(xr.MergeError):
             xr.merge([ds, ds + 1])
 
+    def test_merge_alignment_error(self):
+        ds = xr.Dataset(coords={'x': [1, 2]})
+        other = xr.Dataset(coords={'x': [2, 3]})
+        with self.assertRaises(xr.AlignmentError):
+            xr.merge([ds, other], join='exact')
+
     def test_merge_no_conflicts_single_var(self):
         ds1 = xr.Dataset({'a': ('x', [1, 2]), 'x': [0, 1]})
         ds2 = xr.Dataset({'a': ('x', [2, 3]), 'x': [1, 2]})