🍾 Xarray is now 10 years old! 🎉

xarray.concat

Contents

xarray.concat#

xarray.concat(objs, dim, data_vars='all', coords='different', compat='equals', positions=None, fill_value=<NA>, join='outer', combine_attrs='override')[source]#

Concatenate xarray objects along a new or existing dimension.

Parameters:
  • objs (sequence of Dataset and DataArray) – xarray objects to concatenate together. Each object is expected to consist of variables and coordinates with matching shapes except for along the concatenated dimension.

  • dim (Hashable or Variable or DataArray or pandas.Index) – Name of the dimension to concatenate along. This can either be a new dimension name, in which case it is added along axis=0, or an existing dimension name, in which case the location of the dimension is unchanged. If dimension is provided as a Variable, DataArray or Index, its name is used as the dimension to concatenate along and the values are added as a coordinate.

  • data_vars ({"minimal", "different", "all"} or list of Hashable, optional) –

    These data variables will be concatenated together:
    • “minimal”: Only data variables in which the dimension already appears are included.

    • “different”: Data variables which are not equal (ignoring attributes) across all datasets are also concatenated (as well as all for which dimension already appears). Beware: this option may load the data payload of data variables into memory if they are not already loaded.

    • “all”: All data variables will be concatenated.

    • list of dims: The listed data variables will be concatenated, in addition to the “minimal” data variables.

    If objects are DataArrays, data_vars must be “all”.

  • coords ({"minimal", "different", "all"} or list of Hashable, optional) –

    These coordinate variables will be concatenated together:
    • “minimal”: Only coordinates in which the dimension already appears are included.

    • “different”: Coordinates which are not equal (ignoring attributes) across all datasets are also concatenated (as well as all for which dimension already appears). Beware: this option may load the data payload of coordinate variables into memory if they are not already loaded.

    • “all”: All coordinate variables will be concatenated, except those corresponding to other dimensions.

    • list of Hashable: The listed coordinate variables will be concatenated, in addition to the “minimal” coordinates.

  • compat ({"identical", "equals", "broadcast_equals", "no_conflicts", "override"}, optional) – String indicating how to compare non-concatenated variables of the same name for potential conflicts. This is passed down to merge.

    • “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.

    • “override”: skip comparing and pick variable from first dataset

  • positions (None or list of integer arrays, optional) – List of integer arrays which specifies the integer positions to which to assign each dataset along the concatenated dimension. If not supplied, objects are concatenated in the provided order.

  • fill_value (scalar or dict-like, optional) – Value to use for newly missing values. If a dict-like, maps variable names to fill values. Use a data array’s name to refer to its values.

  • join ({"outer", "inner", "left", "right", "exact"}, optional) – String indicating how to combine differing indexes (excluding dim) in objects

    • “outer”: use the union of object indexes

    • “inner”: use the intersection of object indexes

    • “left”: use indexes from the first object with each dimension

    • “right”: use indexes from the last object with each dimension

    • “exact”: instead of aligning, raise ValueError when indexes to be aligned are not equal

    • “override”: if indexes are of same size, rewrite indexes to be those of the first object with that dimension. Indexes for the same dimension must have the same size in all objects.

  • combine_attrs ({"drop", "identical", "no_conflicts", "drop_conflicts", "override"} or callable(), default: "override") – A callable or a string indicating how to combine attrs of the objects being merged:

    • “drop”: empty attrs on returned Dataset.

    • “identical”: all attrs must be the same on every object.

    • “no_conflicts”: attrs from all objects are combined, any that have the same name must also have the same value.

    • “drop_conflicts”: attrs from all objects are combined, any that have the same name but different values are dropped.

    • “override”: skip comparing and copy attrs from the first dataset to the result.

    If a callable, it must expect a sequence of attrs dicts and a context object as its only parameters.

Returns:

concatenated (type of objs)

See also

merge

Examples

>>> da = xr.DataArray(
...     np.arange(6).reshape(2, 3), [("x", ["a", "b"]), ("y", [10, 20, 30])]
... )
>>> da
<xarray.DataArray (x: 2, y: 3)> Size: 48B
array([[0, 1, 2],
       [3, 4, 5]])
Coordinates:
  * x        (x) <U1 8B 'a' 'b'
  * y        (y) int64 24B 10 20 30
>>> xr.concat([da.isel(y=slice(0, 1)), da.isel(y=slice(1, None))], dim="y")
<xarray.DataArray (x: 2, y: 3)> Size: 48B
array([[0, 1, 2],
       [3, 4, 5]])
Coordinates:
  * x        (x) <U1 8B 'a' 'b'
  * y        (y) int64 24B 10 20 30
>>> xr.concat([da.isel(x=0), da.isel(x=1)], "x")
<xarray.DataArray (x: 2, y: 3)> Size: 48B
array([[0, 1, 2],
       [3, 4, 5]])
Coordinates:
  * x        (x) <U1 8B 'a' 'b'
  * y        (y) int64 24B 10 20 30
>>> xr.concat([da.isel(x=0), da.isel(x=1)], "new_dim")
<xarray.DataArray (new_dim: 2, y: 3)> Size: 48B
array([[0, 1, 2],
       [3, 4, 5]])
Coordinates:
    x        (new_dim) <U1 8B 'a' 'b'
  * y        (y) int64 24B 10 20 30
Dimensions without coordinates: new_dim
>>> xr.concat([da.isel(x=0), da.isel(x=1)], pd.Index([-90, -100], name="new_dim"))
<xarray.DataArray (new_dim: 2, y: 3)> Size: 48B
array([[0, 1, 2],
       [3, 4, 5]])
Coordinates:
    x        (new_dim) <U1 8B 'a' 'b'
  * y        (y) int64 24B 10 20 30
  * new_dim  (new_dim) int64 16B -90 -100