xarray.combine_by_coords

xarray.combine_by_coords(datasets, compat='no_conflicts', data_vars='all', coords='different', fill_value=<NA>)

Attempt to auto-magically combine the given datasets into one by using dimension coordinates.

This method attempts to combine a group of datasets along any number of dimensions into a single entity by inspecting coords and metadata and using a combination of concat and merge.

Will attempt to order the datasets such that the values in their dimension coordinates are monotonic along all dimensions. If it cannot determine the order in which to concatenate the datasets, it will raise a ValueError. Non-coordinate dimensions will be ignored, as will any coordinate dimensions which do not vary between each dataset.

Aligns coordinates, but different variables on datasets can cause it to fail under some scenarios. In complex cases, you may need to clean up your data and use concat/merge explicitly (also see manual_combine).

Works well if, for example, you have N years of data and M data variables, and each combination of a distinct time period and set of data variables is saved as its own dataset. Also useful for if you have a simulation which is parallelized in multiple dimensions, but has global coordinates saved in each file specifying the positions of points within the global domain.

Parameters
datasetssequence of xarray.Dataset

Dataset objects to combine.

compat{‘identical’, ‘equals’, ‘broadcast_equals’,

‘no_conflicts’}, optional

String indicating how to compare variables of the same name for potential conflicts:

  • ‘broadcast_equals’: all values must be equal when variables are broadcast against each other to ensure common dimensions.

  • ‘equals’: all values and dimensions must be the same.

  • ‘identical’: all values, dimensions and attributes must be the same.

  • ‘no_conflicts’: only values which are not null in both datasets must be equal. The returned dataset then contains the combination of all non-null values.

data_vars{‘minimal’, ‘different’, ‘all’ or list of str}, optional

Details are in the documentation of concat

coords{‘minimal’, ‘different’, ‘all’ or list of str}, optional

Details are in the documentation of concat

fill_valuescalar, optional

Value to use for newly missing values

Returns
combinedxarray.Dataset

See also

concat, merge, combine_nested

Examples

Combining two datasets using their common dimension coordinates. Notice they are concatenated based on the values in their dimension coordinates, not on their position in the list passed to combine_by_coords.

>>> x1
<xarray.Dataset>
Dimensions:         (x: 3)
Coords:
  * position        (x) int64   0 1 2
Data variables:
    temperature     (x) float64 11.04 23.57 20.77 ...

>>> x2
<xarray.Dataset>
Dimensions:         (x: 3)
Coords:
  * position        (x) int64   3 4 5
Data variables:
    temperature     (x) float64 6.97 8.13 7.42 ...

>>> combined = xr.combine_by_coords([x2, x1])
<xarray.Dataset>
Dimensions:         (x: 6)
Coords:
  * position        (x) int64   0 1 2 3 4 5
Data variables:
    temperature     (x) float64 11.04 23.57 20.77 ...