# Diagnose and fix xarray coordinate alignment (join) surprises
Use this when arithmetic on xarray objects returns fewer points than expected,
all-NaN results, a `ValueError` about alignment, or coordinates that vanish
after an operation. xarray aligns *index* coordinates automatically on every
binary op, and the default join is the **intersection** — most surprises trace
back to not knowing which join just ran. Classify the symptom first, then pick
the join.
## 1. Classify the symptom
**Result is smaller than either input.** This is normal: automatic alignment
uses the *intersection* of index coordinates, like pandas:
```python
arr = xr.DataArray(np.arange(3), [("x", range(3))])
arr + arr[:-1]
# 2-element DataArray result — x is now [0, 1], the intersection
```
If you expected the union, that is the entire bug: you wanted `join='outer'`.
**Result is all NaN (or far more NaN than expected).** Something forced an
outer-style expansion over coordinates that do not actually overlap:
- Float coordinates that *look* equal but differ in the last bits
(`0.1 + 0.2` style grids, or lon `0..359.9` vs `0..360`). The intersection is
empty, so an outer join is all NaN. Diagnose with
`np.array_equal(a.x.values, b.x.values)` and
`np.abs(a.x.values - b.x.values).max()`.
- You already widened the join (e.g. `arithmetic_join='outer'`) and the grids
genuinely don't overlap — then NaN is the honest answer, not a bug.
**`ValueError: arguments without labels along dimension 'x' cannot be aligned
because they have different dimension size(s) {2} than the size of the aligned
dimension labels: 3`.** One side has an *index* coordinate on `x` and the other
side has the dimension `x` with **no** coordinate labels at all. xarray cannot
align what has no labels, so it demands equal sizes. Fix: give the unlabeled
side a coordinate (`b = b.assign_coords(x=a.x)`), or strip the index from the
labeled side (`a = a.drop_indexes("x")`, which keeps `x` as a non-index
coordinate), then the op broadcasts positionally.
**Coordinates vanished after arithmetic.** Only *index* coordinates (same name
as a dimension, marked `*`) are aligned. Other coordinates are carried through
only if they don't conflict — **conflicting non-index coordinates are silently
dropped**:
```python
arr[0] - arr[1] # scalar coord 'x' differs (0 vs 1) → dropped from the result
```
If you need the conflicting coordinate, align explicitly and choose the
winner with `join='left'`/`'right'`, or reconcile the values first.
**In-place op (`+=`, `*=`) gave wrong results or raised.** There is *no*
automatic alignment for in-place operations — xarray deliberately avoids it so
in-place ops never need to change dtypes. Align first, then operate in place.
## 2. Take explicit control with `xr.align`
`xr.align` aligns any number of objects and returns them with matching indexes
and sizes, ready for math:
```python
a2, b2 = xr.align(a, b, join="outer") # union; non-overlapping → NaN
a2, b2 = xr.align(a, b, join="inner") # intersection (the arithmetic default)
a2, b2 = xr.align(a, b, join="left") # keep a's labels
a2, b2 = xr.align(a, b, join="right") # keep b's labels
a2, b2 = xr.align(a, b, join="exact") # raise ValueError unless indexes equal
a2, b2 = xr.align(a, b, join="override") # adopt a's indexes; sizes must match
```
Which to reach for:
- **Diagnosing**: `join='exact'` is the fail-fast probe. If it raises, your
indexes were never equal and every "mystery" result was silent alignment.
- **Same grid, float noise**: `join='override'` skips reindexing entirely and
adopts the first object's labels — but only when sizes already match. If
sizes differ, fix the grids; override would mislabel data.
- **Changing the arithmetic default for a block**:
```python
with xr.set_options(arithmetic_join="outer"):
result = a + b
```
Prefer explicit `xr.align` for code others will read; use the option for
interactive exploration.
- **Imposing one grid on another**: `b.reindex_like(a)` (fills missing with
NaN) or `b.reindex(x=new_labels)`.
- **Filling rather than erroring**: `a.combine_first(b)` keeps a's values and
fills its holes from b over the union of coordinates.
`xr.apply_ufunc` aligns its inputs too, and accepts `join=` /
`dataset_join=` kwargs for the same control.
## 3. Fix float-precision coordinate mismatch at the source
When two grids should be identical but aren't bitwise, don't paper over it
with `join='override'` in every script — round or rebuild the coordinate once,
at load:
```python
ds = ds.assign_coords(lon=np.round(ds.lon, 6))
# or rebuild a canonical grid and reindex onto it
ds = ds.reindex(lon=canonical_lon, method="nearest", tolerance=1e-6)
```
Then verify with `join='exact'`: it should pass silently from then on.
## 4. Performance: align once, outside loops
Every binary op re-runs alignment. Before loops or performance-critical code,
align explicitly once (or pack the arrays into one `Dataset`, which aligns at
construction) instead of paying the alignment cost per iteration.
## 5. Checklist
1. Symptom → join: shrunken result = inner (default); all-NaN = non-overlapping
labels after outer expansion; `ValueError` = one side has no index labels;
vanished coords = conflicting non-index coordinates dropped;
in-place weirdness = no alignment happens for `+=`.
2. Probe with `xr.align(a, b, join='exact')` to confirm indexes were the issue.
3. Choose the join explicitly: `outer` for unions, `left`/`right` to keep one
side's grid, `override` only for same-size float-noise grids,
`reindex_like` to impose a grid, `combine_first` to fill holes.
4. Fix noisy coordinates at load (round/reindex), then assert with
`join='exact'`.
5. Align once before loops; never rely on alignment inside in-place ops.