Function combine_by_coords

xarray/structure/combine.py:798–1146

Attempt to auto-magically combine the given datasets (or data arrays) into one by using dimension coordinates. This function 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

(
    data_objects: Iterable[Dataset | DataArray] = [],
    compat: CompatOptions | CombineKwargDefault = _COMPAT_DEFAULT,
    data_vars: Literal["all", "minimal", "different"]
    | None
    | list[str]
    | CombineKwargDefault = _DATA_VARS_DEFAULT,
    coords: str | CombineKwargDefault = _COORDS_DEFAULT,
    fill_value: object = dtypes.NA,
    join: JoinOptions | CombineKwargDefault = _JOIN_DEFAULT,
    combine_attrs: CombineAttrsOptions = "no_conflicts",
)

def combine_by_coords(
    data_objects: Iterable[Dataset | DataArray] = [],
    compat: CompatOptions | CombineKwargDefault = _COMPAT_DEFAULT,
    data_vars: Literal["all", "minimal", "different"]
    | None
    | list[str]
    | CombineKwargDefault = _DATA_VARS_DEFAULT,
    coords: str | CombineKwargDefault = _COORDS_DEFAULT,
    fill_value: object = dtypes.NA,
    join: JoinOptions | CombineKwargDefault = _JOIN_DEFAULT,
    combine_attrs: CombineAttrsOptions = "no_conflicts",
) -> Dataset | DataArray:
    """

    Attempt to auto-magically combine the given datasets (or data arrays)
    into one by using dimension coordinates.

    This function 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 `combine_nested`).

    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
    ----------
    data_objects : Iterable of Datasets or DataArrays
        Data objects to combine.

    compat : {"identical", "equals", "broadcast_equals", "no_conflicts", "override"}, \
             default: "no_conflicts"
        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.
        - "override": skip comparing and pick variable from first dataset

    data_vars : {"minimal", "different", "all", None} or list of str, default: "all"