Why is stacking and then renaming raises a FutureWarning?

[doronbehar]

What is your issue?

Take this example:

#!/usr/bin/env python

import xarray as xr
import numpy as np

# Create a simple DataArray with 3 dimensions
da = xr.DataArray(
    np.random.rand(2, 3, 4),
    dims=['x', 'y', 'z'],
    coords={'x': [1, 2], 'y': [10, 20, 30], 'z': [100, 200, 300, 400]}
)

print("Original DataArray:")
print(da)

# Stack dimensions to create a MultiIndex
stacked = da.stack(combined=['x', 'y'])
print("\nStacked DataArray:")
print(stacked)

# Try to replace the MultiIndex coordinate with string values
# This should trigger the FutureWarning
string_coords = [f"({x},{y})" for x, y in stacked.combined.to_index()]

print("\nAttempting to assign string coordinates...")
# This raises a FutureWarning..
result = stacked.assign_coords({'combined': string_coords})
print("\nResult:")
print(result)

It raises the following warning:

FutureWarning: updating coordinate 'combined' with a PandasMultiIndex would leave the multi-index level coordinates ['x', 'y'] in an inconsistent state. This will raise an error in the future. Use `.drop_vars(['combined', 'x', 'y'])` before assigning new coordinate values.
  result = stacked.assign_coords({'combined': string_coords})

Whereas the following doesn't raise a FutureWarning:

result = stacked.assign_coords({
    'tmp_dim': ('combined', string_coords)
}).swap_dims({
    'combined': 'tmp_dim'
}).drop_vars(
    ['combined'] + ['x', 'y', 'z']
).rename({
    'tmp_dim': 'combined'
})

I was wondering: Why is that? Could we somehow make the first option not raise that warning? It seems to work as expected anyway.

[jsignell]

In the second example that you provide you are dropping the data_vars just as the warning suggests. Here is how you could achieve the same result without using a temporary variable name:

import xarray as xr
import numpy as np

# Create a simple DataArray with 3 dimensions
da = xr.DataArray(
    np.random.rand(2, 3, 4),
    dims=['x', 'y', 'z'],
    coords={'x': [1, 2], 'y': [10, 20, 30], 'z': [100, 200, 300, 400]}
)

# Stack dimensions to create a MultiIndex
stacked = da.stack(combined=['x', 'y'])

# construct the new string coordinates list from the MultiIndex
string_coords = [f"({x},{y})" for x, y in stacked.combined.to_index()]

# drop the MultiIndex before using the new string version as the coords
result = stacked .drop_vars(
    ['x', 'y', 'z', 'combined']
) .assign_coords(
    {'combined': string_coords}
)

This seems to be pretty much what the FutureWarning suggests doing. Do you think the text of the warning could be clearer?

[doronbehar]

Hmm I guess you are right. I also checked your suggestion with an xarray.Dataset, with multiple data variables and it worked too. It is kind of weird for me though, that we are using drop_vars over dimensions.

I also used a debugger and noticed that before using assign_coords, we have a dimention without coordinate, which is very confusing. However, I guess it makes sense that afterwards we are assigning the coordinates to this dimension?

[jsignell]

I also used a debugger and noticed that before using assign_coords, we have a dimension without coordinate, which is very confusing.

Yeah xarray is fine with dimensions that don't have coordinates. Xarray can also have multiple coordinates for the same dimension. That is what stacked has in your example.

However, I guess it makes sense that afterwards we are assigning the coordinates to this dimension?

Yeah exactly.

[doronbehar]

Hmm OK I see. Multiple coordinates with the same dimension makes sense to me - like for a temperature dimension can have coordinates in Kelvin, Celsius and Fahrenheit. However I never was in a situation where dimensions didn't have coordinates, and I've been using xarray for almost a year now. I do have some comments on the warning message though:

1. The usage of the term PandasMultiIndex is indeed correct, but I admit I didn't read fully the docs and I thought that this warning is raised from within xarray's usage of pandas, and not by xarray itself - not sure if this should be changed.
2. Due to the above, I didn't fully read the warning because I thought I have to come up with my own solution, which turned out to be not that far from the warning's suggestion.
3. The instruction to .drop_vars was weird for me, because I never used xarray with dimensions without coordinates. Maybe (and I'm really not sure about it), the warning should say something like this:

FutureWarning: updating coordinate 'combined' with a PandasMultiIndex would leave the multi-index level coordinates ['x', 'y'] in an inconsistent state. This will raise an error in the future. Use `.drop_vars(['combined', 'x', 'y'])` to first drop the coordinates' values, and then use `.assign_coords({'combined': ...})` to assign them new values.
  result = stacked.assign_coords({'combined': string_coords})

[jsignell]

I like that suggestion. One thing I found confusing when I first read the message was that the "a PandasMultiIndex" part is referring to the old value not the new value. We can't easily call out assign_coords in the spot in the codebase where this warning occurs because there are several paths that use this internal function. I'll open a PR with a slightly improved message:

FutureWarning: updating coordinate 'combined', which is a PandasMultiIndex, would leave the multi-index level coordinates ['x', 'y'] in an inconsistent state. This will raise an error in the future. Use `.drop_vars(['combined', 'x', 'y'])` to drop the coordinates' values before assigning new coordinate values.
  result = stacked.assign_coords({'combined': string_coords})