This arose as part of #3352. Xarray has important-to-understand name-matching rules for whether or not a coordinate array is a dimension coordinate or a non-dimension coordinate. To my knowledge, this is not in the documentation anywhere.
This is what I had, but we decided to remove it since it was overly complicated for a list of key terms; maybe it'll be helpful going forward:
Name matching rules: Xarray follows simple but important-to-understand name matching rules for dimensions and coordinates. Let arr be an array with an existing dimension x and assigned new coordinates new_coords. If new_coords is a list-like for e.g. [1, 2, 3] then they must be assigned a name that matches an existing dimension. For example, if arr.assign_coords({'x': [1, 2, 3]}).
However, if new_coords is a one-dimensional DataArray, then the rules are slightly more complex. In this case, if both new_coords's name and only dimension match any dimension name in arr.dims, it is assigned as a dimension coordinate to arr. If new_coords's name matches a name in arr.dims but its own dimension name does not, it is assigned as a non-dimension coordinate with name new_coords.dims[0] to arr. Otherwise, an exception is raised.
This arose as part of #3352. Xarray has important-to-understand name-matching rules for whether or not a coordinate array is a dimension coordinate or a non-dimension coordinate. To my knowledge, this is not in the documentation anywhere.
This is what I had, but we decided to remove it since it was overly complicated for a list of key terms; maybe it'll be helpful going forward: