• [ ] Attempt at fixing #8646
• [ ] Tests added
• [ ] User visible changes (including notable bug fixes) are documented in whats-new.rst
• [ ] New functions/methods are listed in api.rst

I've tried here re-implementing swap_dims using rename_dims, drop_indexes and set_xindex. This fixes the example in #8646 but unfortunately this fails at handling the pandas multi-index special case (i.e., a single non-dimension coordinate wrapping a pd.MultiIndex that is promoted to a dimension coordinate in swap-dims auto-magically results in a PandasMultiIndex with both dimension and level coordinates).

• [x] Closes #8887, and probably supersedes #8809
• [x] Tests added
• [ ] User visible changes (including notable bug fixes) are documented in whats-new.rst
• ~~New functions/methods are listed in api.rst~~

@slevang this should also make work your test case added in #8809. I haven't added it here, instead I added a basic check that should be enough.

I don't really understand why the serialization backends (zarr?) do not seem to work with the PandasMultiIndexingAdapter.__array__() implementation, which should normally coerce the multi-index levels into numpy arrays as needed. Anyway, I guess that coercing it early like in this PR doesn't hurt and may avoid the confusion of a non-indexed, isolated coordinate variable that still wraps a pandas.MultiIndex.

• [x] Closes #8628
• [x] Tests added
• [x] User visible changes (including notable bug fixes) are documented in whats-new.rst

• [x] Tests added
• [x] User visible changes (including notable bug fixes) are documented in whats-new.rst

After working more on Coordinates I realize that the default behavior of its constructor could be more consistent with other Xarray objects. This PR changes this default behavior such that:

• Pandas indexes are created for dimension coordinates if indexes=None (default). To create dimension coordinates with no index, just pass indexes={}.
• If another Coordinates object is passed as input, its indexes are also added to the new created object. Since we don't support alignment / merge here, the following call raises an error: xr.Coordinates(coords=xr.Coordinates(...), indexes={...}).

This PR introduces a breaking change since Coordinates are now exposed in v2023.8.0, which has just been released. It is a bit unfortunate but I think it may be OK for a fresh feature, especially if the next release will be soon after this one.

• [x] Closes #6633
• [ ] Tests added
• [ ] User visible changes (including notable bug fixes) are documented in whats-new.rst
• [ ] New functions/methods are listed in api.rst

This PR introduces a new boolean parameter set_indexes=True to xr.open_dataset(), which may be used to skip the creation of default (pandas) indexes when opening a dataset.

Currently works with the Zarr backend:

```python import numpy as np import xarray as xr

example dataset (real dataset may be much larger)

arr = np.random.random(size=1_000_000) xr.Dataset({"x": arr}).to_zarr("dataset.zarr")

xr.open_dataset("dataset.zarr", set_indexes=False, engine="zarr")

<xarray.Dataset>

Dimensions: (x: 1000000)

Coordinates:

x (x) float64 ...

Data variables:

empty

xr.open_zarr("dataset.zarr", set_indexes=False)

<xarray.Dataset>

Dimensions: (x: 1000000)

Coordinates:

x (x) float64 ...

Data variables:

empty

```

I'll add it to the other Xarray backends as well, but I'd like to get your thoughts about the API first.

1. Do we want to add yet another keyword parameter to xr.open_dataset()? There are already many...
2. Do we want to add this parameter to the BackendEntrypoint.open_dataset() API?
3. I'm afraid we must do it if we want this parameter in xr.open_dataset()
4. this would also make it possible skipping the creation of custom indexes (if any) in custom IO backends
5. con: if we require set_indexes in the signature in addition to the drop_variables parameter, this is a breaking change for all existing 3rd-party backends. Or should we group set_indexes with the other xarray decoder kwargs? This would feel a bit odd to me as setting indexes is different from decoding data.
6. Or should we leave this up to the backends?
7. pros: no breaking change, more flexible (3rd party backends may want to offer more control like choosing between custom indexes and default pandas indexes or skipping the creation of indexes by default)
8. cons: less discoverable, consistency is not enforced across 3rd party backends (although for such advanced case this is probably OK), not available by default in every backend.

Currently 1 and 2 are implemented in this PR, although as I write this comment I think that I would prefer 3. I guess this depends on whether we prefer open_*** vs. xr.open_dataset(engine="***") and unless I missed something there is still no real consensus about that? (e.g., #7496).

• Follow-up #8094
• [x] Closes #6481
• [x] User visible changes (including notable bug fixes) are documented in whats-new.rst

This PR should normally raise a warning each time when indexed coordinates are created implicitly from a pd.MultiIndex object.

I updated the tests to create coordinates explicitly using Coordinates.from_pandas_multiindex().

I also refactored some parts where a pd.MultiIndex could still be passed and promoted internally, with the exception of:

• swap_dims(): it should raise a warning! Right now the warning message is a bit confusing for this case, but instead of adding a special case we should probably deprecate the whole method? As it is suggested as a TODO comment... This method was to circumvent the limitations of dimension coordinates, which isn't needed anymore (rename_dims and/or set_xindex is equivalent and less confusing).
• xr.DataArray(pandas_obj_with_multiindex, dims=...): I guess it should raise a warning too?
• da.stack(z=...).groupby("z"): it shoudn't raise a warning, but this requires a (heavy?) refactoring of groupby. During building the "grouper" objects, grouper.group1d or grouper.unique_coord may still be built by extracting only the multi-index dimension coordinate. I'd greatly appreciate if anyone familiar with the groupby implementation could help me with this! @dcherian ?

• [x] Closes #7002
• [x] Tests added
• [x] User visible changes (including notable bug fixes) are documented in whats-new.rst

This PR relaxes some of the rules used in alignment for finding the indexes to compare or join together. Those indexes must still be of the same type and must relate to the same set of coordinates (and dimensions), but the order of coordinates is now ignored.

It is up to the index to implement the equal / join logic if it needs to care about that order.

Regarding pandas.MultiIndex, it seems that the level names are ignored when comparing indexes:

```python midx = pd.MultiIndex.from_product([["a", "b"], [0, 1]], names=("one", "two"))) midx2 = pd.MultiIndex.from_product([["a", "b"], [0, 1]], names=("two", "one"))

midx.equals(midx2) # True ```

However, in Xarray the names of the multi-index levels (and their order) matter since each level has its own xarray coordinate. In this PR, PandasMultiIndex.equals() and PandasMultiIndex.join() thus check that the level names match.

• Complements #8102
• [ ] Tests added
• [ ] User visible changes (including notable bug fixes) are documented in whats-new.rst
• [ ] New functions/methods are listed in api.rst

I don't think that we need to copy most API from Dataset / DataArray to Coordinates, but I find it convenient to have some relevant methods there too. For example, building Coordinates from scratch (with custom indexes) before passing the whole coords + indexes bundle around:

```python import dask.array as da import numpy as np import xarray as xr

coords = ( xr.Coordinates( coords={"x": da.arange(100_000_000), "y": np.arange(100)}, indexes={}, ) .set_xindex("x", DaskIndex) .set_xindex("y", xr.indexes.PandasIndex) )

ds = xr.Dataset(coords=coords)

<xarray.Dataset>

Dimensions: (x: 100000000, y: 100)

Coordinates:

* x (x) int64 dask.array<chunksize=(16777216,), meta=np.ndarray>

* y (y) int64 0 1 2 3 4 5 6 7 8 9 10 ... 90 91 92 93 94 95 96 97 98 99

Data variables:

empty

Indexes:

x DaskIndex

```

• [x] Closes #8166
• [ ] Tests added
• [ ] User visible changes (including notable bug fixes) are documented in whats-new.rst
• [ ] New functions/methods are listed in api.rst

I added both the unstack and dim arguments but we can change that.

• [ ] update DataArray.from_series()

I wanted to fix the following error with mypy 1.5:

xarray/core/dataset.py:505: error: Definition of "__eq__" in base class "DatasetOpsMixin" is incompatible with definition in base class "Mapping" [misc]

Which looks similar to https://github.com/python/mypy/issues/9319. It is weird that here it worked with mypy versions < 1.5, though.

I don't know if there is a better fix, but I thought that redefining __eq__ in Dataset would be a bit less dirty workaround than adding type: ignore in the class declaration.

• [ ] Tests added
• [ ] User visible changes (including notable bug fixes) are documented in whats-new.rst

This PR adds a future_no_mindex_dim_coord=False option that, if set to True, enables the future behavior of PandasMultiIndex (i.e., no added dimension coordinate with tuple values):

```python import xarray as xr

ds = xr.Dataset(coords={"x": ["a", "b"], "y": [1, 2]})

ds.stack(z=["x", "y"])

<xarray.Dataset>

Dimensions: (z: 4)

Coordinates:

* z (z) object MultiIndex

* x (z) <U1 'a' 'a' 'b' 'b'

* y (z) int64 1 2 1 2

Data variables:

empty

with xr.set_options(future_no_mindex_dim_coord=True): ds.stack(z=["x", "y"])

<xarray.Dataset>

Dimensions: (z: 4)

Coordinates:

* x (z) <U1 'a' 'a' 'b' 'b'

* y (z) int64 1 2 1 2

Dimensions without coordinates: z

Data variables:

empty

```

There are a few other things that we'll need to adapt or deprecate:

• Dropping multi-index dimension coordinate de-facto allows having several multi-indexes along the same dimension. Normally stack should already take this into account, but there may be other places where this is not yet supported or where we should raise an explicit error.
• Deprecate Dataset.reorder_levels: API is not compatible with the absence of dimension coordinate and several multi-indexes along the same dimension. I think it is OK to deprecate such edge case, which alternatively could be done by extracting the pandas index, updating it and then re-assign it to a the dataset with assign_coords(xr.Coordinates.from_pandas_multiindex(...))
• The text-based repr: in the example above, Dimensions without coordinate: z doesn't make much sense
• ... ?

I started updating the tests, although this will be much easier once #8140 is merged. This is something that we could also easily split into multiple PRs. It is probably OK if some features are (temporarily) breaking badly when setting future_no_mindex_dim_coord=True.

• [x] Tests added
• [x] User visible changes (including notable bug fixes) are documented in whats-new.rst
• [x] New functions/methods are listed in api.rst

This is consistent with the Dataset and DataArray assign methods (now that Coordinates is also exposed as public API).

This allows writing:

```python midx = pd.MultiIndex.from_arrays([["a", "a", "b", "b"], [0, 1, 0, 1]]) midx_coords = xr.Coordinates.from_pandas_multiindex(midx, "x")

ds = xr.Dataset(coords=midx_coords.assign(y=[1, 2])) ```

which is quite common (at least in the tests) and a bit nicer than

python ds = xr.Dataset(coords=midx_coords.merge({"y": [1, 2]}).coords)

• [ ] Closes #xxxx
• [ ] Tests added
• [ ] User visible changes (including notable bug fixes) are documented in whats-new.rst
• [ ] New functions/methods are listed in api.rst

The goal of this PR is to provide a more general solution to indexed coordinate variables, i.e., support arbitrary dimensions and/or duck arrays for those variables while at the same time prevent them from being updated in a way that would invalidate their index.

This would solve problems like the one mentioned here: https://github.com/pydata/xarray/issues/1650#issuecomment-1697237429

@shoyer I've tried to implement what you have suggested in https://github.com/pydata/xarray/pull/4979#discussion_r589798510. It would be nice indeed if eventually we could get rid of IndexVariable. It won't be easy to deprecate it until we finish the index refactor (i.e., all methods listed in #6293), though. Also, I didn't find an easy way to refactor that class as it has been designed too closely around a 1-d variable backed by a pandas.Index.

So the approach implemented in this PR is to keep using IndexVariable for PandasIndex until we can deprecate / remove it later, and for the other cases use Variable with data wrapped in a custom IndexedCoordinateArray object.

The latter solution (wrapper) doesn't always work nicely, though. For example, several methods of Variable expect that self._data directly returns a duck array (e.g., a dask array or a chunked duck array). A wrapped duck array will result in unexpected behavior there. We could probably add some checks / indirection or extend the wrapper API... But I wonder if there wouldn't be a more elegant approach?

More generally, which operations should we allow / forbid / skip for an indexed coordinate variable?

• Set array items in-place? Do not allow.
• Replace data? Do not allow.
• (Re)Chunk?
• Load lazy data?
• ... ?

(Note: we could add Index.chunk() and Index.load() methods in order to allow an Xarray index implement custom logic for the two latter cases like, e.g., convert a DaskIndex to a PandasIndex during load, see #8128).

cc @andersy005 (some changes made here may conflict with what you are refactoring in #8075).

• [ ] Closes #xxxx
• [ ] Tests added
• [ ] User visible changes (including notable bug fixes) are documented in whats-new.rst
• [ ] New functions/methods are listed in api.rst

As mentioned in #8124, it gives more control to custom Xarray indexes on what best to do when the Dataset / DataArray load() and chunk() counterpart methods are called.

PandasIndex.load() and PandasIndex.chunk() always return self (no action required).

For a DaskIndex, we might want to return a PandasIndex (or another non-lazy index) from load() and rebuild a DaskIndex object from chunk() (rechunk).

Another item in #719.

I added tests and updated the docs, so this is ready for review.

• [x] Closes #4091
• [x] Tests added

The message suggests using .expand_dims().

• [x] Closes many issues:
• [x] closes #1366
• [x] closes #1408
• [x] closes #2489
• [x] closes #3432
• [x] closes #4542
• [x] closes #4955
• [x] closes #5202
• [x] closes #5645
• [x] closes #5691
• [x] closes #5697
• [x] closes #5700
• [x] closes #5727
• [x] closes #5953
• [x] closes #6183
• [x] closes #6313
• [x] Tests added
• [x] Passes pre-commit run --all-files
• [x] User visible changes (including notable bug fixes) are documented in whats-new.rst
• New functions/methods are listed in api.rst (new Index and Indexes API not public yet)

Follow-up on #5636 (work in progress), supersedes #2195.

This is likely to be going big, sorry in advance! It'll be safer to make a release before merging this PR.

Current progress:

• [x] create (default) indexes using the Index classes
• [x] refactor default indexes created when 1st accessing .xindexes or .indexes
• [x] support for non-default indexes (no public API yet)
• [x] remove multi-index virtual coordinates (replace it by regular coordinates)
• [x] refactor internal (text / html) formatting functions
• [x] internal refactor of location-based selection (.isel())
• [x] internal refactor of label-based selection (.sel())
• [x] internal refactor of .rename()
• Some changes in behavior (see comments below)
  • see #4108
  • see #4107
  • see #4417
• [x] internal refactor of set_index / reset_index
• [x] internal refactor of stack / unstack
  • Some changes in behavior (see comments below)
• [x] internal refactor of Dataset.to_stacked_array
• [x] internal refactor of swap_dims
• [x] internal refactor of expand_dims
• [x] internal refactor of alignment
• [x] internal refactor of reindex and reindex_like
• [x] internal refactor of interp and interp_like
• [x] internal refactor of merge
• [x] internal refactor of concat
• [x] internal refactor of computation
• [x] internal refactor of copy
• [x] internal refactor of update, assign, __setitem__, del, drop_vars, etc.
  • updates must not corrupt multi-coordinate indexes
• [x] internal refactor of set_coords and reset_coords
• internal refactor of drop_sel and drop_isel (maybe later)
• [x] internal refactor of pad
• [x] internal refactor of shift
• [x] internal refactor of roll

TODO:

• [x] Uniformize Index API with Xarray's API
  • [x] rename Index.query() -> Index.sel()?
  • [x] rename PandasMultiIndex.from_product() -> PandasMultiIndex.stack()? Add Index.stack() and Index.unstack().
  • [x] remove Index.union() and Index.intersection()
• [x] Use Index.create_variables() internally
  • [x] remove PandasIndex.from_pandas_index() and PandasMultiIndex.from_pandas_index() (use constructor + .create_variables() instead)
• [x] Review where .xindexes is used and use private API instead (._indexes) if possible for speed
  • [x] requires that _indexes always returns a mapping
• [x] Use from __future__ import annotations in indexes.py
• [x] Re-activate default indexes invariant check (with opt-out for some tests)

In next PRs:

• custom Index.__repr__ and Index._repr_inline_
• add an Indexes section in DataArray / Dataset reprs
• update public API (set_index, reset_index, drop_indexes, Dataset and DataArray constructors, etc.)
• allow multi-dimensional variables with name in var.dims

• [x] Closes #5553
• [x] Tests added
• [x] Passes pre-commit run --all-files
• [x] User visible changes (including notable bug fixes) are documented in whats-new.rst

This implements option 3 (sort of) described in https://github.com/pydata/xarray/issues/5553#issue-933551030:

• the goal is to avoid wrapping an xarray.Index into an xarray.Variable and keep those two concepts distinct from each other.
• the xarray.Index.from_variables class constructor accepts a dictionary of xarray.Variable objects as argument and may (or should?) also return corresponding xarray.IndexVariable objects to ensure immutability.
• for PandasIndex, the new returned xarray.IndexVariable wraps the underlying pd.Index via a PandasIndexingAdapter (this reverts some changes made in #5102).
• for PandasMultiIndex, this PR adds PandasMultiIndexingAdapter so that we can wrap the pandas multi-index in separate coordinate variables objects: one for the dimension + one for each level. The level coordinates data internally hold a reference to the dimension coordinate data to avoid indexing the same underlying pd.MultiIndex for each of those coordinates (PandasMultiIndexingAdapter.__getitem__ is memoized for that purpose).

This is very much work in progress, I need to update (or revert) all related parts of Xarray's internals, update tests, etc. At this stage any comment on the approach described above is welcome.

• [x] Closes #7214
• [x] Closes #6392
• [x] xref #6633
• [x] Tests added
• [x] User visible changes (including notable bug fixes) are documented in whats-new.rst
• [x] New functions/methods are listed in api.rst

This is a rework of #7214. It follows the suggestions made in https://github.com/pydata/xarray/pull/7214#issuecomment-1295283938, https://github.com/pydata/xarray/pull/7214#issuecomment-1297046405 and https://github.com/pydata/xarray/pull/7214#issuecomment-1293774799:

• No indexes argument is added to Dataset.__init__, and the indexes argument of DataArray.__init__ is kept private (i.e., valid only if fastpath=True)
• When a Coordinates object is passed to a new Dataset or DataArray via the coords argument, both coordinate variables and indexes are copied/extracted and added to the new object
• This PR also adds ~~an IndexedCoordinates subclass~~ Coordinates public constructors used to create Xarray coordinates and indexes from non-Xarray objects. For example, the Coordinates.from_pandas_multiindex() class method creates a new set of index and coordinates from an existing pd.MultiIndex.

EDIT: IndexCoordinates has been merged with Coordinates

EDIT2: it ended up as a pretty big refactor with the promotion of Coordinates has a 2nd-class Xarray container that supports alignment like Dataset and DataArray. It is still quite advanced API, useful for passing coordinate variables and indexes around. Internally, Coordinates objects are still "virtual" containers (i.e., proxies for coordinate variables and indexes stored in their corresponding DataArray or Dataset objects). For now, a "stand-alone" Coordinates object created from scratch wraps a Dataset with no data variables.

Some examples of usage:

```python import pandas as pd import xarray as xr

midx = pd.MultiIndex.from_product([["a", "b"], [1, 2]], names=("one", "two"))

coords = xr.Coordinates.from_pandas_multiindex(midx, "x")

Coordinates:

* x (x) object MultiIndex

* one (x) object 'a' 'a' 'b' 'b'

* two (x) int64 1 2 1 2

ds = xr.Dataset(coords=coords)

<xarray.Dataset>

Dimensions: (x: 4)

Coordinates:

* x (x) object MultiIndex

* one (x) object 'a' 'a' 'b' 'b'

* two (x) int64 1 2 1 2

Data variables:

empty

ds_to_be_deprecated = xr.Dataset(coords={"x": midx}) ds_to_be_deprecated.identical(ds)

True

da = xr.DataArray([1, 2, 3, 4], dims="x", coords=ds.coords)

<xarray.DataArray (x: 4)>

array([1, 2, 3, 4])

Coordinates:

* x (x) object MultiIndex

* one (x) object 'a' 'a' 'b' 'b'

* two (x) int64 1 2 1 2

```

TODO:

• [x] update assign_coords too so it has the same behavior if a Coordinates object is passed?
• [x] How to avoid building any default index? It seems silly to add or use the indexes argument just for that purpose? ~~We could address that later.~~ Solution: wrap the coordinates dict in a Coordinates objects, e.g., ds = xr.Dataset(coords=xr.Coordinates(coords_dict)).

@shoyer, @dcherian, anyone -- what do you think about the approach proposed here? I'd like to check that with you before going further with tests, docs, etc.

• [x] Closes #6392
• [x] Closes #6633 ?
• [ ] Tests added
• [ ] User visible changes (including notable bug fixes) are documented in whats-new.rst
• [ ] New functions/methods are listed in api.rst

From https://github.com/pydata/xarray/issues/6392#issuecomment-1290454937:

I'm thinking of only accepting one or more instances of Indexes as indexes argument in the Dataset and DataArray constructors. The only exception is when fastpath=True a mapping can be given directly. Also, when an empty collection of indexes is passed this skips the creation of default pandas indexes for dimension coordinates.

• It is much easier to handle: just check that keys returned by Indexes.variables do no conflict with the coordinate names in the coords argument
• It is slightly safer: it requires the user to explicitly create an Indexes object, thus with less chance to accidentally provide coordinate variables and index objects that do not relate to each other (we could probably add some safe guards in the Indexes class itself)
• It is more convenient: an Xarray Index may provide a factory method that returns an instance of Indexes that we just need to pass as indexes, and we could also do something like ds = xr.Dataset(indexes=other_ds.xindexes)

• [x] Closes #7405
• [x] Closes #7588
• [x] Tests added
• [x] User visible changes (including notable bug fixes) are documented in whats-new.rst

This PR documents the API of the Index base class and adds a guide for creating custom indexes (reworked from https://hackmd.io/Zxw_zCa7Rbynx_iJu6Y3LA). Hopefully it will help anyone experimenting with this feature.

@pydata/xarray your feedback would be very much appreciated! I've been into this for quite some time, so there may be things that seem obvious to me but that you can still find very confusing or non-intuitive. It would then deserve some extra or better explanation.

More specifically, I'm open to any suggestion on how to better illustrate this with clear and succinct examples.

There are other parts of the documentation that still need to be updated regarding the indexes refactor (e.g., "dimension" coordinates, xindexes property, set/drop indexes, etc.). But I suggest to do that in separate PRs and focus here on creating custom indexes.

• [x] Closes #7563
• [x] Closes #8039
• [x] Closes #8056
• [x] Closes #7885
• [x] Closes #7921
• [x] Tests added
• [x] User visible changes (including notable bug fixes) are documented in whats-new.rst

This refactor should better handle multi-coordinate indexes when updating (or assigning) new coordinates.

It also fixes, better isolates and better warns a bunch of deprecated pandas multi-index special cases (i.e., directly passing pd.MultiIndex objects or updating a multi-index dimension coordinate). I very much look forward to seeing support for those cases dropped :).

• [x] Benchmark added
• [x] User visible changes (including notable bug fixes) are documented in whats-new.rst

May fix some performance regressions, e.g., see https://github.com/pydata/xarray/issues/7376#issuecomment-1352989233.

@ravwojdyla with this PR ds.assign(foo=~ds["d3"]) in your example should be much faster (on par with version 2022.3.0).

• [x] Closes
• [x] fixes #6946
• [x] fixes #6989
• [x] fixes #6959
• [x] fixes #6969
• [x] fixes #7036
• [x] Tests added
• [x] User visible changes (including notable bug fixes) are documented in whats-new.rst

Restore behavior prior to the explicit indexes refactor (i.e., refactored but without breaking changes).

TODO:

• [x] review set_index
• [x] review reset_index

For reset_index, the only behavior that is not restored here is the coordinate renamed with a _ suffix when dropping a single index. This was originally to prevent any coordinate with no index matching a dimension name, which is now irrelevant. That is a quite dirty workaround and I don't know who is relying on it (no complaints yet), but I'm open to restore it if needed (esp. considering that we may later deprecate reset_index completely in favor of drop_indexes #6971).

• [ ] Closes #xxxx
• [ ] Tests added
• [ ] User visible changes (including notable bug fixes) are documented in whats-new.rst
• [ ] New functions/methods are listed in api.rst

This PR adds a xarray.indexes.MultiPandasIndex helper class for building custom, meta-indexes that encapsulate multiple PandasIndex instances. Unlike PandasMultiIndex, the meta-index classes inheriting from this helper class may encapsulate loosely coupled (pandas) indexes, with coordinates of arbitrary dimensions (each coordinate must be 1-dimensional but an Xarray index may be created from coordinates with differing dimensions).

Early prototype in this notebook

TODO / TO FIX:

• How to allow custom __init__ options in subclasses be passed to all the type(self)(new_indexes) calls inside the MultiPandasIndex "base" class? This could be done via **kwargs passed through... However, mypy will certainly complain (Liskov Substitution Principle).
• Is MultiPandasIndex a good name for this helper class?

It allows passing options to the constructor of a custom Index subclass, in case there's any relevant build options to expose to users. This could for example be the distance metric chosen for an index based on sklearn.neighbors.BallTree, or the CRS definition for a geospatial index.

The **options arguments of Dataset.set_xindex() are passed through.

An alternative way would be to pass options via coordinate metadata, like the spatial_ref coordinate in rioxarray. Perhaps both alternatives may co-exist?

This PR also adds type annotations to set_xindex().

• [x] Closes #6849
• [x] Supersedes #6800
• [x] Tests added
• [x] User visible changes (including notable bug fixes) are documented in whats-new.rst
• [x] New functions/methods are listed in api.rst

This PR adds Dataset and DataArray .set_xindex and .drop_indexes methods (the latter is also discussed in #4366). I've cherry picked the relevant commits in the scipy22 branch and added a few more commits. This PR also allows passing build options to any Index.

Some comments and open questions:

• Should we make the index_cls argument of set_xindex optional?
• I.e., set_index(coord_names, index_cls=None, **options) where a pandas index is created by default (or a pandas multi-index if several coordinate names are given), provided that the coordinate(s) are valid 1-d candidates.

• This would be redundant with the existing set_index method, but this would be convenient if we later depreciate it.

• Should we depreciate set_index and reset_index? I think we should, but probably not at this point yet.

• There's a special case for multi-indexes where set_xindex(["foo", "bar"], PandasMultiIndex) adds a dimension coordinate in addition to the "foo" and "bar" level coordinates so that it is consistent with the rest of Xarray. I find it a bit annoying, though. Probably another motivation for depreciating this dimension coordinate.

• In this PR I also imported the Index base class in Xarray's root namespace.

• It is needed for custom indexes and it's just a little more convenient than importing it from xarray.core.indexes.
• Should we do the same for PandasIndex and PandasMultiIndex subclasses? Maybe if one wants to create a custom index inheriting from it. PandasMultiIndex factory methods could be also useful if we depreciate passing pd.MultiIndex objects as DataArray / Dataset coordinates.

• [x] Closes #6607
• [x] Closes #4107
• [x] Closes #6229
• [x] Tests added
• [x] User visible changes (including notable bug fixes) are documented in whats-new.rst

Current implemented "fix": raise a UserWarning and suggest using swap_dims (*)

Alternatively, we could:

• revert the breaking change (i.e., create the index again) and raise a DeprecationWarning instead
• raise an error instead of a warning

I don't have strong opinions on this, I'm happy to implement another alternative. The downside of reverting the breaking change now is that unfortunately it will introduce a breaking change in the next release., while workarounds are pretty straightforward.

(*) from https://github.com/pydata/xarray/issues/6607#issuecomment-1126587818, doing ds.set_coords(['lon']).rename(x='lon').set_index(lon='lon') is working too. With #6971, .set_xindex('lon') could work as well.

• [x] Closes #6987
• [x] Tests added

• [x] Closes #6836
• [x] Tests added
• [x] User visible changes (including notable bug fixes) are documented in whats-new.rst

• [x] Closes #6434
• [x] Tests added

• [x] Closes #7097
• [x] Tests added

@dcherian the DeprecationWarning was ignored by default for .assign_coords() because of https://github.com/pydata/xarray/pull/6798#discussion_r924653224. I changed it to FutureWarning so that it is shown for both .assign() and .assign_coords().

• [x] Closes #6852
• [x] Tests added
• [x] User visible changes (including notable bug fixes) are documented in whats-new.rst

• [x] Closes #7346
• [x] Tests added
• [x] User visible changes (including notable bug fixes) are documented in whats-new.rst

• [x] Closes #6838
• [ ] Tests added
• [ ] User visible changes (including notable bug fixes) are documented in whats-new.rst

This PR hopefully improves how are handled the labels that are provided for multi-index level coordinates in .sel().

More specifically, slices are handled in a cleaner way and it is now allowed to provide array-like labels.

PandasMultiIndex.sel() relies on the underlying pandas.MultiIndex methods like this:

• use get_loc when all levels are provided with each a scalar label (no slice, no array)
• always drops the index and returns scalar coordinates for each multi-index level
• use get_loc_level when only a subset of levels are provided with scalar labels only
• may collapse one or more levels of the multi-index (dropped levels result in scalar coordinates)
• if only one level remains: renames the dimension and the corresponding dimension coordinate
• use get_locs for all other cases.
• always keeps the multi-index and its coordinates (even if only one item or one level is selected)

This yields a predictable behavior: as soon as one of the provided labels is a slice or array-like, the multi-index and all its level coordinates are kept in the result.

Some cases illustrated below (I compare this PR with an older release due to the errors reported in #6838):

```python import xarray as xr import pandas as pd

midx = pd.MultiIndex.from_product([list("abc"), range(4)], names=("one", "two")) ds = xr.Dataset(coords={"x": midx})

<xarray.Dataset>

Dimensions: (x: 12)

Coordinates:

* x (x) object MultiIndex

* one (x) object 'a' 'a' 'a' 'a' 'b' 'b' 'b' 'b' 'c' 'c' 'c' 'c'

* two (x) int64 0 1 2 3 0 1 2 3 0 1 2 3

Data variables:

empty

```

```python ds.sel(one="a", two=0)

this PR

<xarray.Dataset>

Dimensions: ()

Coordinates:

x object ('a', 0)

one <U1 'a'

two int64 0

Data variables:

empty

v2022.3.0

<xarray.Dataset>

Dimensions: ()

Coordinates:

x object ('a', 0)

Data variables:

empty

```

```python ds.sel(one="a")

this PR:

<xarray.Dataset>

Dimensions: (two: 4)

Coordinates:

* two (two) int64 0 1 2 3

one <U1 'a'

Data variables:

empty

v2022.3.0

<xarray.Dataset>

Dimensions: (two: 4)

Coordinates:

* two (two) int64 0 1 2 3

Data variables:

empty

```

```python ds.sel(one=slice("a", "b"))

this PR

<xarray.Dataset>

Dimensions: (x: 8)

Coordinates:

* x (x) object MultiIndex

* one (x) object 'a' 'a' 'a' 'a' 'b' 'b' 'b' 'b'

* two (x) int64 0 1 2 3 0 1 2 3

Data variables:

empty

v2022.3.0

<xarray.Dataset>

Dimensions: (two: 8)

Coordinates:

* two (two) int64 0 1 2 3 0 1 2 3

Data variables:

empty

```

```python ds.sel(one="a", two=slice(1, 1))

this PR

<xarray.Dataset>

Dimensions: (x: 1)

Coordinates:

* x (x) object MultiIndex

* one (x) object 'a'

* two (x) int64 1

Data variables:

empty

v2022.3.0

<xarray.Dataset>

Dimensions: (x: 1)

Coordinates:

* x (x) MultiIndex

- one (x) object 'a'

- two (x) int64 1

Data variables:

empty

```

```python ds.sel(one=["b", "c"], two=[0, 2])

this PR

<xarray.Dataset>

Dimensions: (x: 4)

Coordinates:

* x (x) object MultiIndex

* one (x) object 'b' 'b' 'c' 'c'

* two (x) int64 0 2 0 2

Data variables:

empty

v2022.3.0

ValueError: Vectorized selection is not available along coordinate 'one' (multi-index level)

```

This adds PandasMultiIndexingAdapter._repr_html_ that can greatly speed-up the html repr of Xarray objects with multi-indexes.

This optimized _repr_html_ implementation is now used for formatting the array detailed view of all multi-index coordinates in the html repr, instead of converting the full index and each levels to numpy arrays before formatting them.

```python import xarray as xr

ds = xr.tutorial.load_dataset("air_temperature") da = ds["air"].stack(z=[...])

da.shape

(3869000,)

%timeit -n 1 -r 1 da.repr_html()

9.96 ms !

```

• [x] Closes #5529
• [x] User visible changes (including notable bug fixes) are documented in whats-new.rst

• [x] Closes #6381
• [x] Tests added

• [x] Closes #4041
• [x] Tests added
• [x] Passes isort -rc . && black . && mypy . && flake8
• [x] Fully documented, including whats-new.rst for all changes and api.rst for new API

This is not very elegant (actually plain text repr is already included in the notebook as text/plain mime type but it is ignored when text/html mime type is present), but it seems to work. I haven't found a better workaround.

I don't really know if this can be properly tested (I only added a basic test).

Steps to test this fix:

• To "untrust" a notebook: open an existing notebook with a simple editor, manually edit one output cell with a xarray object repr, and save the ipynb file.
• Open this notebook with the Notebook app, you should see the plain text repr.

This PR clears up the path for flexible indexes:

• it adds a new ~~IndexAdapter~~ Index base class that is meant to be inherited by all xarray-compatible indexes (built-in or 3rd-party)
• PandasIndexAdapter now inherits from ~~IndexAdapter~~ Index
• the xarray_obj.xindexes properties return Index (PandasIndexAdapter) instances. xarray_obj.indexes properties still return pandas.Index instances.

~~The latter is a breaking change, although I'm not sure if the indexes property has been made public yet.~~

This is still work in progress, there are many broken tests that are not fixed yet. (EDIT: all tests should be fixed now).

There's a lot of dirty fixes to avoid circular dependencies and in the many places where we still need direct access to the pandas.Index objects, but I'd expect that these will be cleaned-up further in the refactoring.

Xarray label-based data selection now relies on a newly added xarray.Index.query(self, labels: Dict[Hashable, Any]) -> Tuple[Any, Optional[None, Index]] method where:

• labels is a always a dictionary with coordinate name(s) as key(s) and the corresponding selection label(s) as values
• When calling .sel with some coordinate(s)/label(s) pairs, those are first grouped by index so that only the relevant pairs are passed to an Index.query
• the returned tuple contains the positional indexers and (optionally) a new index object

For a simple pd.Index, labels always corresponds to a 1-item dictionary like {'coord_name': label_values}, which is not very useful in this case, but this format is useful for pd.MultiIndex and will likely be for other, custom indexes.

Moving the label->positional indexer conversion logic into PandasIndex.query(), I've tried to separate pd.Index vs pd.MultiIndex concerns by adding a new PandasMultiIndex wrapper class (it will probably be useful for other things as well) and refactor the complex logic that was implemented in convert_label_indexer. Hopefully it is a bit clearer now.

Working towards a more flexible/generic system, we still need to figure out how to:

• pass index query extra arguments like method and tolerance for pd.Index but in a more generic way
• handle several positional indexers over multiple dimensions possibly returned by a custom "meta-index" (e.g., staggered grid index)
• handle the case of positional indexers returned from querying >1 indexes along the same dimension (e.g., multiple coordinates along x with a simple pd.Index)
• pandas indexes don't need information like the names or shapes of their corresponding coordinate(s) to perform label-based selection, but this kind of information will probably be needed for other indexes (we actually need it for advanced point-wise selection using tree-based indexes in xoak).

This could be done in follow-up PRs..

Side note: I've initially tried to return from xindexes items for multi-index levels as well (not only index dimensions), but it's probably wiser to save this for later (when we'll tackle the multi-index virtual coordinate refactoring) as there are many places in Xarray where this is clearly not expected.

Happy to hear your thoughts @pydata/xarray.

As a preliminary step before I take on the refactoring and implementation of flexible indexes in Xarray for the next few months, I reviewed the status of https://github.com/pydata/xarray/projects/1 and started compiling partially implemented or planned changes, thoughts, etc. into a single document that may serve as a basis for further discussion and implementation work.

It's still very much work in progress (I will update it regularly in the forthcoming days) and it is very open to discussion (we can use this PR for that)!

I'm not sure if Xarray's root folder is a good place for this document, though. We could move this into a new repository in xarray-contrib (that could also host other enhancement proposals) if that's necessary.

I'm looking forward to getting started on this and to getting your thoughts/feedback!

• [x] Closes #5384
• [x] Tests added
• [x] Passes pre-commit run --all-files
• [x] User visible changes (including notable bug fixes) are documented in whats-new.rst

• [x] Closes #6382
• [x] Tests added

• [x] Closes #6384
• [x] Tests added

• [x] Closes #6379
• [x] Tests added

• [x] Closes #6393
• [x] Tests added

• [x] Closes #6380
• [x] Tests added

• [x] Closes #6416
• [x] Tests added

• ~~Closes #xxxx~~
• [x] Tests added / passed
• [x] Passes git diff upstream/master | flake8 --diff
• [x] Fully documented, including whats-new.rst for all changes and api.rst for new API

~~In addition to Dataset repr, the error message also shows the output of Dataset.info() for both datasets.~~

~~This may not be the most elegant solution, but it is helpful when datasets only differ by their attributes attached to coordinates or data variables (not shown in repr). I'm open to any suggestion.~~

The report shows the differences for dimensions, data values (Variable and DataArray), coordinates, data variables and attributes (the latter only for testing.assert_identical).

There is currently not much tests for xarray.testing functions, but I'm willing to add more if needed.

Not sure if it's worth a what's new entry (EDIT: added one).

• [x] Closes #1722
• [x] Tests added / passed
• [x] Passes git diff upstream/master **/*py | flake8 --diff
• [x] Fully documented, including whats-new.rst for all changes and api.rst for new API

• [x] Closes #1627
• [ ] Tests added
• [ ] Tests passed
• [ ] Passes git diff upstream/master **/*py | flake8 --diff
• [ ] Fully documented, including whats-new.rst for all changes and api.rst for new API

This is work in progress, although the basic functionality is there. You can see a preview here: http://nbviewer.jupyter.org/gist/benbovy/3009f342fb283bd0288125a1f7883ef2

TODO:

• [ ] Add support for Multi-indexes
• [ ] Probably good to have some opt-in or fail back system in case where we (or users) know that the rendering will not work
• [ ] Add some tests

Nice to have (keep this for later):

• Clean-up CSS code and HTML template (track CSS subgrid support in browsers, this may simplify a lot the things here).
• Dynamically adapt cell widths (given the length of the names of variables and dimensions). Currently all cells have a fixed width. This is tricky, though, as we don't use a monospace font here.
• Integration with jupyterlab/notebook themes (CSS classes) and maybe allow custom CSS.
• Integration of Dask arrays HTML repr (+ integration of repr for other array backends).
• Maybe find a way (if possible) to include CSS only once in the notebook (currently it is included each time a xarray object is displayed in an output cell, which is not very nice).
• Review the rules for collapsing the Coordinates, Data variables and Attributes sections (maybe expose them as global options).
• Maybe also define some rules to collapse automatically the data section (DataArray and Variable) when the data repr is too long.
• Maybe add rich representation for Dataset.coords and Dataset.data_vars as well?

Make xarray-related projects more discoverable, as it has been suggested in xarray mailing-list.

Not a big change, but adds a little more clarity IMO.

I'm open to any suggestion for better section names and/or organization. Also I let "What's new" at the top, but not sure if "Getting started" is the right section.

• [x] Closes #1303
• [x] Tests added / passed
• [x] Passes git diff upstream/master | flake8 --diff (if we ignore messages for .rst files and "imported but not used" messages for xarray.__init__.py)
• [x] Fully documented, including whats-new.rst for all changes and api.rst for new API

Make xarray.core.variable.as_variable part of the public API and accessible as a top-level function: xarray.as_variable.

I changed the docstrings to follow the numpydoc format more closely.

I also removed the copy=False keyword arguments as apparently it was unused.

Implements 2, 4 and 5 in #719.

Demo:

``` In [1]: import numpy as np

In [2]: import pandas as pd

In [3]: import xarray as xr

In [4]: index = pd.MultiIndex.from_product((list('ab'), range(2)), ...: names= ('level_1', 'level_2'))

In [5]: da = xr.DataArray(np.random.rand(4, 4), coords={'x': index}, ...: dims=('x', 'y'), name='test')

In [6]: da Out[6]: <xarray.DataArray 'test' (x: 4, y: 4)> array([[ 0.15036153, 0.68974802, 0.40082234, 0.94451318], [ 0.26732938, 0.49598123, 0.8679231 , 0.6149102 ], [ 0.3313594 , 0.93857424, 0.73023367, 0.44069622], [ 0.81304837, 0.81244159, 0.37274953, 0.86405196]]) Coordinates: * level_1 (x) object 'a' 'a' 'b' 'b' * level_2 (x) int64 0 1 0 1 * y (y) int64 0 1 2 3

In [7]: da['level_1'] Out[7]: <xarray.DataArray 'level_1' (x: 4)> array(['a', 'a', 'b', 'b'], dtype=object) Coordinates: * level_1 (x) object 'a' 'a' 'b' 'b' * level_2 (x) int64 0 1 0 1

In [8]: da.sel(x='a', level_2=1) Out[8]: <xarray.DataArray 'test' (y: 4)> array([ 0.26732938, 0.49598123, 0.8679231 , 0.6149102 ]) Coordinates: x object ('a', 1) * y (y) int64 0 1 2 3

In [9]: da.sel(level_2=1) Out[9]: <xarray.DataArray 'test' (level_1: 2, y: 4)> array([[ 0.26732938, 0.49598123, 0.8679231 , 0.6149102 ], [ 0.81304837, 0.81244159, 0.37274953, 0.86405196]]) Coordinates: * level_1 (level_1) object 'a' 'b' * y (y) int64 0 1 2 3 ```

Some notes about the implementation: - I slightly modified Coordinate so that it allows setting different values for the names of the coordinate and its dimension. There is no breaking change. - I also added a Coordinate.get_level_coords method to get independent, single-index coordinates objects from a MultiIndex coordinate.

Remaining issues: - Coordinate.get_level_coords calls pandas.MultiIndex.get_level_values for each level and is itself called each time when indexing and for repr. This can be very costly!! It would be nice to return some kind of lazy index object instead of computing the actual level values. - repr replace a MultiIndex coordinate by its level coordinates. That can be confusing in some cases (see below). Maybe we can set a different marker than * for level coordinates.

``` In [6]: [name for name in da.coords] Out[6]: ['x', 'y']

In [7]: da.coords.keys() Out[7]: KeysView(Coordinates: * level_1 (x) object 'a' 'a' 'b' 'b' * level_2 (x) int64 0 1 0 1 * y (y) int64 0 1 2 3) `` -DataArray.level_1doesn't return anotherDataArray` object:

In [10]: da.level_1 Out[10]: <xarray.Coordinate 'level_1' (x: 4)> array(['a', 'a', 'b', 'b'], dtype=object) - Maybe we need to test the uniqueness of level names at DataArray or Dataset creation.

Of course still needs proper tests and docs...

Another item of #719.

An example:

``` python

index = pd.MultiIndex.from_product((list('ab'), range(10))) index.names= ('a_long_level_name', 'level_1') data = xr.DataArray(range(20), [('x', index)]) data <xarray.DataArray (x: 20)> array([ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19]) Coordinates: * x (x) object MultiIndex - a_long_level_name object 'a' 'a' 'a' 'a' 'a' 'a' 'a' 'a' 'a' 'a' 'b' ... - level_1 int64 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 ```

To be consistent with the displayed coordinates and/or data variables, it displays the actual used level values. Using the pandas.MultiIndex.get_level_values method would be expensive for big indexes, so I re-implemented it in xarray so that we can truncate the computation to the first x values, which is very cheap.

It still needs testing.

Maybe it would be nice to align the level values.

Follows #767.

This is incomplete (it still needs some tests and documentation updates), but it is working for both Dataset and DataArray objects. I also don't know if it is fully compatible with lazy indexing (Dask).

Using the example from #767:

In [4]: da.sel(band_wavenumber={'band': 'foo'}) Out[4]: <xarray.DataArray (wavenumber: 2)> array([ 0.00017, 0.00014]) Coordinates: * wavenumber (wavenumber) float64 4.05e+03 4.05e+03

As shown in this example, similarily to pandas, it automatically renames the dimension and assigns a new coordinate when the selection doesn't return a pd.MultiIndex (here it returns a pd.FloatIndex).

In some cases this behavior may be unwanted (??), so I added a drop_level keyword argument (if False it keeps the multi-index and doesn't change the dimension/coordinate names):

In [5]: da.sel(band_wavenumber={'band': 'foo'}, drop_level=False) Out[5]: <xarray.DataArray (band_wavenumber: 2)> array([ 0.00017, 0.00014]) Coordinates: * band_wavenumber (band_wavenumber) object ('foo', 4050.2) ('foo', 4050.3)

Note that it also works with DataArray.loc, but (for now) in that case it always returns the multi-index:

In [6]: da.loc[{'band_wavenumber': {'band': 'foo'}}] Out[6]: <xarray.DataArray (band_wavenumber: 2)> array([ 0.00017, 0.00014]) Coordinates: * band_wavenumber (band_wavenumber) object ('foo', 4050.2) ('foo', 4050.3)

This is however inconsistent with Dataset.sel and Dataset.loc that both apply drop_level=True by default, due to their different implementation. Two solutions: (1) make DataArray.loc apply drop_level by default, or (2) use drop_level=False by default everywhere.

Fixes #769.