Dedicated documentation on Alignment?

[TomNicholas]

What is your issue?

I'm writing more documentation for DataTree, and was looking for an in-depth explanation of what Alignment actually is so I can refer to it, but I can't really find one?

The concept of alignment is referred to in multiple places, e.g.

• There is a brief definition of alignment in the terminology page,
• There's some explanation in the context of using .reindex(),
• Some more in the context of automatic alignment during broadcasting,
• Alignment of indexes is referred to in the documentation of xr.merge on the Combining page
• The closest thing to dedicated documentation I've found is in the explanation of Dataset.update() on the data structures page.
• The docstring for xr.align() has examples, but no narrative explanation.

But there doesn't appear to be a dedicated section on Alignment anywhere in the narrative docs (or even on the xarray tutorial site). I can't find any explanation of what it means for two Datasets not to align, for example.

This seems like a very fundamental concept to not have dedicated documentation with examples. Maybe I've just missed it?

cc @max-sixty @dcherian @shoyer @flamingbear

[dcherian]

Yeah its not great. I wrote some tutorial material here: https://tutorial.xarray.dev/fundamentals/02.3_aligning_data_objects.html

[TomNicholas]

I wrote some tutorial material here:

I was looking for that one! The content on that really fills a much-needed gap (and is really good). I think a dedicated page that explains what Broadcasting and Alignment are is what we are missing from the main docs.

[benbovy]

In general I find https://tutorial.xarray.dev/ really well done, it would definitely deserve more exposure / discoverability / integration with the main docs!