Alignment¶
Most of the work in a model comparison, and most of the mistakes, come before
the metric. Two datasets rarely share a grid, a longitude convention, a
calendar, a time step or units, and missing values seldom fall on the same
points. climval does these steps explicitly, in a fixed order, and writes each
one into the result's provenance (result.provenance["steps"]).
climval.align(reference, candidate, ...) runs the steps without computing a
metric and returns an AlignedPair; climval.compare calls it and then
computes the metrics. On dask arrays every step is lazy and no data value is
read. Alignment reads coordinates and, when an input is a Dataset or a file
whose time, latitude or longitude bounds are stored as dask arrays, those
bounds variables, all of them in one small dask.compute call, because the
native frequency and the cell areas come from them. Inputs are cast to
float64, lazily, so lazy and eager runs of float32 data give the same values.
1. Inputs¶
Each side may be an xarray.DataArray, an xarray.Dataset with variable=,
a path or URL to NetCDF, Zarr or CSV, or a list of NetCDF paths. NetCDF and
Zarr paths and URLs open lazily with dask chunks (dask is a core dependency);
CSV tables are read into memory. A Zarr store is recognised by a .zarr
suffix (also .zarr-v3 and similar) or, without one, by its .zmetadata,
.zgroup or zarr.json, so Pangeo CMIP6 store URLs, which end in a version
directory, work as given. variable is one name, or a pair
(reference name, candidate name) when the names differ, for example
("t2m", "tas").
A CSV whose latitude and longitude columns do not form a full grid, or any
input with lat and lon on one shared dimension, is station data on a
station dimension. The gridded input is then sampled at the stations
(bilinear or nearest), and the stations are always the target.
Why: the comparison should start from the data you have, without a copy.
2. Coordinates¶
climval finds latitude, longitude and time through cf_xarray when it is
installed, otherwise through CF attributes (standard_name, units, axis)
and common names. They are renamed to lat, lon and time, and latitude is
sorted ascending. Two-dimensional latitude and longitude (a curvilinear grid)
is detected; such a grid can only be remapped with regrid="conservative"
(xESMF) and cannot be the target.
Why: every later step needs to know which dimension is which, and arithmetic in xarray aligns on coordinate names and values.
3. Target grid¶
The comparison happens on one grid: target="coarser" (default, the input
with larger cells, measured as latitude spacing times longitude spacing, so
one axis of the target can be finer than the other input's; the reference
when both are equal), "reference",
"candidate", or an xarray object that carries the grid. The other input is
regridded onto it. A curvilinear input can only be the source, so with
"coarser" the rectilinear input is the target. The target_grid step
records which grid was used.
Why: interpolating a coarse field onto a fine grid adds no information,
and the fine field then keeps small-scale detail that the coarse one cannot
have, which counts against the coarse model. The choice changes the numbers,
so it is recorded. When several models are scored against one reference with
the default, each model is compared on whichever of its grid and the
reference grid has the larger cells; pass target="reference" or a common grid when all of them
should share one.
4. Longitude¶
Both inputs are expressed in one longitude frame: the target grid's convention (0..360 or -180..180), or a frame that keeps the requested region in one piece when it crosses the 0 or 180 meridian.
Why: a box such as 10W to 40E is two separate pieces in a 0..360 grid.
5. Region¶
A climval.Box(lat=(south, north), lon=(west, east)) is cut before
regridding. west > east crosses the antimeridian. The target grid is cut
exactly. The grid that will be regridded keeps a margin of one cell, and for
bilinear and nearest a wrapped column at each end when it is global and the
box reaches the edge of the longitude frame, so the points at the edge of the
box have neighbours to interpolate from. The wrapped columns are added after
the time step, so they are aggregated once rather than split off every
native time step.
Conservative remapping gets no wrapped columns; xESMF treats a global source
as periodic instead. A regionmask region (for example
"ar6.land:NEU") contributes its bounding box here and its polygon mask after
regridding, on the target grid. See Regions.
Why: cutting first keeps the amount of data read small; the margin avoids extrapolation at the edges.
6. Time¶
The time step works on calendar fields, not timestamps. See Calendars and frequencies for the details.
- Each input's native frequency comes from its time bounds (
time_bnds, CFbounds), then afrequencyattribute (CMIP vocabulary such asmon,day,3hr, or a pandas alias), then the time steps. With bounds, steps are labelled by the midpoints of their intervals, so values stamped at the end of their interval count for the right day. When none of these tells the frequency (a single time step, one month per year, irregular steps), climval raises and asks forfreq=, time bounds or afrequencyattribute. - The
periodis selected on year, month and day, so("1995", "2014")means the same months in a360_day,noleapor standard calendar. - The common frequency is the coarser of the two native frequencies, or
freq=(never finer than either). Sub-daily data keep their step, written"<N>h"for a whole number of hours that divides 24: hourly against 3-hourly data is compared in 3-hour bins. - A finer input is aggregated to that frequency with a time mean (months
aggregated to years are weighted by their length). A period's value counts
only where at least
min_coverage(default 0.8) of its native steps hold a valid value, per grid cell; the rule is recorded. On dask arrays the time chunks are first made to hold whole periods; a regular sub-daily series (hourly to daily, say) is then summed with one task per chunk, and other series are resampled through flox, which also reduces chunk by chunk. The result is rechunked to whole horizontal fields and dask's automatic size along time. A year of hourly ERA5 at 0.25 degrees, in the time-series, tiled or one-hour-per-chunk layout, aggregates to days in a graph of tens of thousands of tasks. - Each period is labelled by its calendar fields (year and month for monthly
data) and only labels present in both inputs are kept. With no common
period climval raises
NoOverlapError.
Daily and sub-daily comparisons between a 360_day calendar and any other
calendar warn: days are matched by date label, so 30 February and every 31st
day drop out, and the same label sits at a different point of the seasonal
cycle. freq="MS" compares monthly means instead.
Why: a model month stamped on day 16 of a 360_day month and a reanalysis
month stamped on day 1 of a Gregorian month are the same month, and matching
timestamps would miss that.
7. Regridding¶
regrid="bilinear" (default) and "nearest" use xarray.interp.
"conservative" (first order, conservative_normed) always goes through
xESMF; it is the only option for curvilinear grids and the only one that
averages a fine grid over coarse cells. A source cell reaches half a spacing
beyond its centre, so target points in that half cell take the edge value;
target points farther out, or inside a hole in the source grid, become NaN.
climval does not extrapolate. When no target point lies on the source grid
along latitude or longitude, it raises NoOverlapError instead of returning
NaN values. Bilinear or nearest interpolation onto a coarser grid samples the
source at the target points; climval warns and suggests
regrid="conservative". A dask source is rechunked to whole horizontal
fields before interpolation, so a source stored in small spatial tiles does
not turn into millions of tiny chunks.
Why: bilinear interpolation is a reasonable default for smooth fields such as temperature; conservative remapping keeps area integrals and suits fluxes such as precipitation.
8. Units¶
The candidate is converted into the reference's units. Built in: K, degC and
degF; kg m-2 s-1, kg m-2 h-1, kg m-2 d-1, mm/h and mm/day; Pa and hPa;
fractions and percent. A bare C is the coulomb in UDUNITS and CF, so it is
rejected with a hint to write degC. pint handles
other units when installed. An unknown mismatch raises UnitsError unless you
pass units="ignore" or declare the units with
units={"reference": "K", "candidate": "degC"}. See Units.
Why: a difference between K and degC is a bias of 273.15, and it happens.
9. Missing values¶
A point counts only where both inputs are valid. Both fields are set to NaN wherever either one is missing.
Why: without a paired mask, a mean bias compares two different sets of points.
10. Weights¶
Every spatial mean is weighted. weights="area" (default) uses a cell area
field when one is given with area= or found through the reference's
cell_measures attribute and lies on the target grid. Otherwise it computes
the area of each cell from the target grid's latitude and longitude bounds
(lat_bnds and lon_bnds when the Dataset has them, else midpoints between
neighbouring centres, clipped at the poles; longitude bounds that wrap around
the seam, such as 358.75 to 1.25, count as 2.5 degrees):
On a uniform grid this is proportional to cos(latitude); on a Gaussian or
otherwise non-uniform grid it is not. weights="cos_lat" gives cos(latitude),
weights=None equal weights, and a DataArray is used as given (it must not
be negative). Station data get equal weights. The weights actually used are
recorded in the weights step.
For monthly and yearly comparisons each time step also carries a time weight, the length of its period in days in the reference's calendar, so a February counts less than a January wherever time steps are pooled. Daily and sub-daily steps count equally.
Why: on a latitude-longitude grid a cell at 70N covers about a third of the area of a cell at the equator.
Inspecting the alignment¶
pair = climval.align(reference, candidate, ("t2m", "tas"), region=box, period=("1995", "2014"))
pair.reference, pair.candidate, pair.weights
for line in climval.result.describe_steps(pair.steps):
print(line)
Aligned candidates on one common grid (for example all aligned with
target="reference") can be stacked along a new model dimension and passed
to compare; extra dimensions are kept. See
CMIP6 through intake-esm.