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

[shoyer]

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(coords={'x': [0, 1]})
ds2 = xarray.Dataset(coords={'x': [1, 2]})
xarray.merge([ds1, ds2], join='exact')
# AlignmentError: indexes along dimension 'x' are not equal

• tests added / passed
• passes git diff upstream/master | flake8 --diff
• whatsnew entry

[shoyer]

@pydata/xarray Any thoughts on this feature? Does it seem useful to you? Does the name join='exact' make sense?

[clarkfitzg]

Does it seem useful to you?

Yes, it's a nice sanity check.

Does the name join='exact' make sense?

Yes.

Any thoughts on this feature?

Is it worth introducing custom exception types into xarray? Seems like ValueError would be fine here. Then users can write this without having to know we use our own special exceptions:

try:
   xarray.merge([ds1, ds2], join='exact')
except ValueError:
   ...

Otherwise you'll probably want to change some others to AlignmentError for consistency.

[shoyer]

Is it worth introducing custom exception types into xarray?

My thought is that custom exception types make sense when the exception is effectively part of the API, though possibly it would make sense to have AlignmentError inherit from ValueError.

For example, the first part of a utility function my_custom_align might involve something like:

def is_aligned(*objects):
    try:
        xarray.align(*objects, join='exact')
    except AlignmentError:
        return False
    else:
        return True

(actually, perhaps we should write is_aligned ourselves!)

Or to log potential performance issues:

def align_but_log(*objects):
    try:
        aligned = xarray.align(*objects, join='exact')
    except AlignmentError:
        logging.warning('objects were not aligned')
        aligned = xarray.align(*objects)
    return aligned

Otherwise you'll probably want to change some others to AlignmentError for consistency.

I actually think every operation that automatically aligns already goes through xarray.align. Though it's probably worth double checking...

[clarkfitzg]

I'm thinking about some of the ones in alignment.py which are currently ValueError, for example: https://github.com/pydata/xarray/blob/master/xarray/core/alignment.py#L303

[rabernat]

Trying to understand how this relates to #1413...

Does align='exact' require the indices to be be compared value by value?

[shoyer]

Does align='exact' require the indices to be be compared value by value?

Yes, it does. It checks indexes for equality, and if they don't match it raises an error (rather than aligning).

[clarkfitzg]

This has been sitting for a little while... @shoyer please don't let my comment keep you from merging- it was more to note that this introduces custom error types.

[shoyer]

I switched from AlignmentError -> ValueError. We can always add an AlignmentError later subclassing from ValueError if we want it.

[shoyer]

In it goes! Thanks everyone for your feedback.