Improve alignment checks

[benbovy]

• ClosesAlignment fails when multiple indexes are set along one common dimension #7695 and thus also fixes those long due issues
  • DataArray with multiple (Pandas)Indexes on the same dimension is impossible to align #8236
  • align fails when more than one xindex is set #8436
  • Objects with multiple identical xindexs on a dim aren't alignable #9474
  • Setting an xindex causes .where to fail #9697
• Tests added
• User visible changes (including notable bug fixes) are documented in whats-new.rst
• New functions/methods are listed in api.rst

The alignment error

ValueError: cannot re-index or align objects with conflicting indexes found for the following dimensions: 'time' (2 conflicting indexes)
Conflicting indexes may occur when
- they relate to different sets of coordinate and/or dimension names
- they don't have the same type
- they may be used to reindex data along common dimensions

was not user-friendly, sometimes too restrictive and is now gone!

---

The examples in the issues linked above now work, i.e., it is possible to align objects with multiple indexes found along one or more common dimensions as long as either

• no re-indexing is required along those dimensions
• Index.reindex_like() called for each index return matching indexers along those dimensions

So this example works too:

>>>ds1=xr.Dataset(coords={"x": [1, 2], "xb": ("x", [3, 4])}).set_xindex("xb")
>>>ds2=xr.Dataset(coords={"x": [1], "xb": ("x", [3])}).set_xindex("xb")
>>>xr.align(ds1, ds2, join="inner")
(<xarray.Dataset>Size: 16BDimensions: (x: 1)
Coordinates:
*x (x) int648B1*xb (x) int648B3Datavariables:
*empty*,
<xarray.Dataset>Size: 16BDimensions: (x: 1)
Coordinates:
*x (x) int648B1*xb (x) int648B3Datavariables:
*empty*)

A more user-friendly error is raised when indexers don't match:

>>>ds3=xr.Dataset(coords={"x": [1, 3], "xb": ("x", [2, 4])}).set_xindex("xb")
>>>xr.align(ds1, ds3, join="inner")
AlignmentError: cannotreindexoralignalongdimension'x'becauseofconflictingre-indexersreturnedbymultipleindexesfirstindex: PandasIndex(Index([3, 4], dtype='int64', name='xb'))
secondindex: PandasIndex(Index([1, 2], dtype='int64', name='x'))

[dcherian]

nice test!

[dcherian]

LGTM. Thanks!

This is an important fix, so lets merge ASAP.

The doctest simply needs updating from ValueError to AlignmentError AFAICT

[benbovy]

Will be cleaner to later have Xarray exceptions defined in their own module xarray.exceptions.AlignmentError (same for MergeError, etc.)