Explain name matching rules for dimension and non-dimension coordinates

[gwgundersen]

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.

[keewis]

I think this might fit into the assign_coords docstring. Thoughts?

[max-sixty]

I took another pass at this:

• When a DataArray is passed:
  • If it's > 1D, it's added as a non-dimension coordinate [is this right? what if it's name is the same as a dimension?]
  • If it's 1D and its name and dimension match, it's added as a dimensioned coordinate on that dimension
  • If it's 1D and its name and dimension don't match, it's added as a non-dimensiode coordinate
• When something list-like is passed — and so is 1D — it's added as a dimensioned coordinate on that dimension [possibly this can be compressed to something like "list-like is initially transformed to a DataArray with a matching dimension & name]

Note that I haven't tested these, so may well not be correct.

I think this might fit into the assign_coords docstring. Thoughts?

To what extent is this about assign_coords vs the DataArray & Dataset constructor? Are there any differences between passing something to each of those?