documenting how xarray.dot() interacts with coordinates

[dhruvak001]

• Closes Document how dot interacts with coordinates #10899

Description

This PR addresses issue #10899 by documenting how xarray.dot() and DataArray.dot() interact with coordinates.

Previously, the documentation did not explain:

• How coordinates behave when arrays have coordinates in different orders
• What happens when coordinate values don't overlap
• Which coordinates appear in the output array

Changes

Enhanced xarray.dot() documentation (xarray/computation/computation.py)

Added a new "Coordinate Handling" subsection to the Notes that clearly explains:

• Coordinates are aligned based on their values, not their positional order
• Uses an inner join by default (only overlapping coordinate values are included)
• Non-overlapping coordinates are excluded from the computation
• Dimensions not involved in the summation retain their coordinates in the output
• How to use xr.set_options(arithmetic_join="exact") to require exact coordinate matching and raise errors on misalignment

Added three practical examples demonstrating:

1. Coordinate alignment by value: Shows that x["a", "b"] @ y["b", "a"] correctly aligns by coordinate value
2. Non-overlapping coordinates: Shows that only overlapping coordinate values participate in the dot product
3. Preserved output coordinates: Shows that non-summed dimensions retain their coordinates

Enhanced DataArray.dot() documentation (xarray/core/dataarray.py)

Added a Notes section explaining:

• The method aligns input arrays using an inner join
• Coordinates are matched by values, not order
• Cross-reference to xarray.dot() for detailed information

Added an example demonstrating coordinate alignment behavior.

Example Usage

import xarray as xr

# Coordinates aligned by value, not order
x = xr.DataArray([1, 10], coords=[("foo", ["a", "b"])])
y = xr.DataArray([2, 20], coords=[("foo", ["b", "a"])])
xr.dot(x, y)  # Returns 40 (1*20 + 10*2)

# Non-overlapping coordinates
x = xr.DataArray([1, 10], coords=[("foo", ["a", "b"])])
y = xr.DataArray([2, 30], coords=[("foo", ["b", "c"])])
xr.dot(x, y)  # Returns 20 (only "b" overlaps: 10*2)

# Preserved coordinates
x = xr.DataArray([[1, 2], [3, 4]], coords=[("time", [0, 1]), ("space", ["IA", "IL"])])
y = xr.DataArray([10, 20], coords=[("space", ["IA", "IL"])])
xr.dot(x, y, dim="space")  # Returns array with time coordinate preserved

[max-sixty]

thanks @dhruvak001

does dot differ from other methods? if not, we should just bolster the general docs...

[dhruvak001]

sure, I will update.

[dhruvak001]

@max-sixty Updated, review whenever you get time. Thanks!

[Copilot]

Pull request overview

This PR enhances the documentation for xarray.dot() and DataArray.dot() to clearly explain how these functions handle coordinate alignment, addressing issue #10899. The documentation now explicitly covers coordinate value-based alignment, inner join behavior, and how non-overlapping coordinates are handled.

• Added comprehensive "Coordinate Handling" subsection to xarray.dot() documentation explaining alignment behavior
• Enhanced DataArray.dot() with Notes section and coordinate alignment example
• Included three practical examples demonstrating value-based alignment, non-overlapping coordinates, and preserved output coordinates

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
xarray/computation/computation.py	Added "Coordinate Handling" subsection in Notes explaining value-based alignment, inner join behavior, and mathematical equivalence; added three examples demonstrating coordinate alignment scenarios
xarray/core/dataarray.py	Added Notes section explaining automatic coordinate alignment with cross-reference to xarray.dot(); added example showing coordinates aligned by values rather than order

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[max-sixty]

thanks @dhruvak001 !