Combining two named DataArrays results in a Dataset (`combine_by_coords`)

[etienneschalk]

What happened?

When combining 2 DataArrays with a name 'name', I got a Dataset with a unique variable 'name' when I expected to get a DataArray. The DataArrays were named because they were extracted from Datasets.

What did you expect to happen?

I expected that combining two DataArrays would result in a Dataset, even if they have a name.

Minimal Complete Verifiable Example

Steps to reproduce

import xarray as xr 

xr.show_versions()

INSTALLED VERSIONS
------------------
commit: None
python: 3.13.1 (main, Feb 10 2025, 10:59:30) [GCC 9.4.0]
python-bits: 64
OS: Linux
OS-release: 5.15.0-139-generic
machine: x86_64
processor: x86_64
byteorder: little
LC_ALL: None
LANG: en_US.UTF-8
LOCALE: ('en_US', 'UTF-8')
libhdf5: None
libnetcdf: None

xarray: 2025.9.0
pandas: 2.3.2
numpy: 2.3.3
scipy: 1.16.1
netCDF4: None
pydap: None
h5netcdf: None
h5py: None
zarr: 3.1.2
cftime: None
nc_time_axis: None
iris: None
bottleneck: None
dask: 2025.9.0
distributed: None
matplotlib: 3.10.6
cartopy: None
seaborn: 0.13.2
numbagg: None
fsspec: 2025.9.0
cupy: None
pint: None
sparse: None
flox: None
numpy_groupies: None
setuptools: None
pip: 25.1.1
conda: None
pytest: 8.4.2
mypy: None
IPython: 9.5.0
sphinx: None

Case A: combining 2 unnamed DataArrays

Expected: 2 DataArrays produce 1 DataArray
Actual: OK

xda1 = xr.DataArray(data=[1], dims=["x"], coords={"x": [1]})
xda2 = xr.DataArray(data=[2], dims=["x"], coords={"x": [2]})
result = xr.combine_by_coords([xda1, xda2])
print(result)

<xarray.DataArray (x: 2)> Size: 16B
array([1, 2])
Coordinates:
  * x        (x) int64 16B 1 2

Case B: combining 2 named DataArrays extracted from Datasets

The 2 extracted DataArrays have a name 'name'.

xda1_from_dataset = xr.Dataset(data_vars={"name": xda1})["name"]
xda2_from_dataset = xr.Dataset(data_vars={"name": xda2})["name"]
print(xda1_from_dataset)
print(xda2_from_dataset)

<xarray.DataArray 'name' (x: 1)> Size: 8B
array([1])
Coordinates:
  * x        (x) int64 8B 1
<xarray.DataArray 'name' (x: 1)> Size: 8B
array([2])
Coordinates:
  * x        (x) int64 8B 2

Expected: 2 named DataArrays produce 1 named DataArray
Actual: the result is a Dataset with a variable 'name'

result = xr.combine_by_coords([xda1_from_dataset, xda2_from_dataset])
print(result)

<xarray.Dataset> Size: 32B
Dimensions:  (x: 2)
Coordinates:
  * x        (x) int64 16B 1 2
Data variables:
    name     (x) int64 16B 1 2

Squeezing does not transform the Dataset into DataArray

result = xr.combine_by_coords([xda1_from_dataset, xda2_from_dataset]).squeeze()
print(result)

<xarray.Dataset> Size: 32B
Dimensions:  (x: 2)
Coordinates:
  * x        (x) int64 16B 1 2
Data variables:
    name     (x) int64 16B 1 2

Only way is to manually select the name. It means the user needs to explicitly select the variable.

result = xr.combine_by_coords([xda1_from_dataset, xda2_from_dataset])["name"]
print(result)

<xarray.DataArray 'name' (x: 2)> Size: 16B
array([1, 2])
Coordinates:
  * x        (x) int64 16B 1 2

Is there something I missed regarding combine_by_coords?

The current behaviour astonished me. Imo combining 2 DataArrays, named or not, should produce a DataArray, not a Dataset, but maybe I'm wrong.

MVCE confirmation

• Minimal example — the example is as focused as reasonably possible to demonstrate the underlying issue in xarray.
• Complete example — the example is self-contained, including all data and the text of any traceback.
• Verifiable example — the example copy & pastes into an IPython prompt or Binder notebook, returning the result.
• New issue — a search of GitHub Issues suggests this is not a duplicate.
• Recent environment — the issue occurs with the latest version of xarray and its dependencies.

Relevant log output

Anything else we need to know?

No response

Environment

    INSTALLED VERSIONS
    ------------------
    commit: None
    python: 3.13.1 (main, Feb 10 2025, 10:59:30) [GCC 9.4.0]
    python-bits: 64
    OS: Linux
    OS-release: 5.15.0-139-generic
    machine: x86_64
    processor: x86_64
    byteorder: little
    LC_ALL: None
    LANG: en_US.UTF-8
    LOCALE: ('en_US', 'UTF-8')
    libhdf5: None
    libnetcdf: None
    
    xarray: 2025.9.0
    pandas: 2.3.2
    numpy: 2.3.3
    scipy: 1.16.1
    netCDF4: None
    pydap: None
    h5netcdf: None
    h5py: None
    zarr: 3.1.2
    cftime: None
    nc_time_axis: None
    iris: None
    bottleneck: None
    dask: 2025.9.0
    distributed: None
    matplotlib: 3.10.6
    cartopy: None
    seaborn: 0.13.2
    numbagg: None
    fsspec: 2025.9.0
    cupy: None
    pint: None
    sparse: None
    flox: None
    numpy_groupies: None
    setuptools: None
    pip: 25.1.1
    conda: None
    pytest: 8.4.2
    mypy: None
    IPython: 9.5.0
    sphinx: None

[jsignell]

Thanks for the clear writeup! This definitely felt like a bug to me but then I looked at the documentation and saw that this exact behavior is described in the docstring:

xarray/xarray/structure/combine.py

Lines 947 to 988 in 6470460

	You can also combine DataArray objects, but the behaviour will differ depending on
	whether or not the DataArrays are named. If all DataArrays are named then they will
	be promoted to Datasets before combining, and then the resultant Dataset will be
	returned, e.g.
	>>> named_da1 = xr.DataArray(
	... name="a", data=[1.0, 2.0], coords={"x": [0, 1]}, dims="x"
	... )
	>>> named_da1
	<xarray.DataArray 'a' (x: 2)> Size: 16B
	array([1., 2.])
	Coordinates:
	* x (x) int64 16B 0 1
	>>> named_da2 = xr.DataArray(
	... name="a", data=[3.0, 4.0], coords={"x": [2, 3]}, dims="x"
	... )
	>>> named_da2
	<xarray.DataArray 'a' (x: 2)> Size: 16B
	array([3., 4.])
	Coordinates:
	* x (x) int64 16B 2 3
	>>> xr.combine_by_coords([named_da1, named_da2])
	<xarray.Dataset> Size: 64B
	Dimensions: (x: 4)
	Coordinates:
	* x (x) int64 32B 0 1 2 3
	Data variables:
	a (x) float64 32B 1.0 2.0 3.0 4.0
	If all the DataArrays are unnamed, a single DataArray will be returned, e.g.
	>>> unnamed_da1 = xr.DataArray(data=[1.0, 2.0], coords={"x": [0, 1]}, dims="x")
	>>> unnamed_da2 = xr.DataArray(data=[3.0, 4.0], coords={"x": [2, 3]}, dims="x")
	>>> xr.combine_by_coords([unnamed_da1, unnamed_da2])
	<xarray.DataArray (x: 4)> Size: 32B
	array([1., 2., 3., 4.])
	Coordinates:
	* x (x) int64 32B 0 1 2 3
	Finally, if you attempt to combine a mix of unnamed DataArrays with either named

and discussed in this comment #5834 (comment)

In your case maybe the best workaround would be to unset the name before calling combine_by_coords:

xda1_from_dataset.name = None
xda2_from_dataset.name = None

[etienneschalk]

Yes indeed, I confirm that it work when resetting the name attributes:

xda1_from_dataset.name = None
xda2_from_dataset.name = None
result = xr.combine_by_coords([xda1_from_dataset, xda2_from_dataset])
assert isinstance(result, xr.DataArray)
print(result)

<xarray.DataArray (x: 2)> Size: 16B
array([1, 2])
Coordinates:
  * x        (x) int64 16B 1 2

Still, this is a bit weird to me, as I need to make a clear distinction between unnamed and named DataArrays, something static type checkers cannot be aware of.

Example when using pyright with "Inlay Hints" enabled:

It would have been nice to get type-safety, so getting a DataArray return type when feeding DataArrays, and getting a Dataset return type when feeding Datasets. This can force the users to write instance checks in the code to please static type checkers.

[shoyer]

It would have been nice to get type-safety, so getting a DataArray return type when feeding DataArrays, and getting a Dataset return type when feeding Datasets. This can force the users to write instance checks in the code to please static type checkers.

I agree, this feels quite sub-optimal to me. I would support a breaking change to make combine_by_coords type stable and always return a DataArray for DataArray inputs.

It may also be worth taking a look at the similar combine_nested.