Alignment¶
align ¶
Alignment: put a reference and a candidate on the same points.
:func:align runs these steps in order and records each one:
inputs: resolve DataArray, Dataset, path or URL (lazily, except CSV).coordinates: find lat, lon and time (CF aware), rename them, sort latitude ascending, detect curvilinear grids and station data.target_grid: by default the coarser of the two grids; station locations are always the target when one input is station data.longitude: express both inputs in one longitude frame (the target grid's convention, or a frame that keeps the region contiguous).region: cut the box (crossing the antimeridian if asked). The target grid is cut exactly; the grid that will be regridded keeps a margin of one cell and, for bilinear and nearest on a global grid when the box reaches the edge of the longitude frame, a wrapped column at each end, so interpolation at the edges has neighbours. The wrapped columns are added after the time step, so they are aggregated once, not per time step. Conservative remapping gets no wrapped columns; xESMF treats a global source as periodic instead.time: native frequencies (time bounds, frequency attribute or time steps), period, common frequency, aggregation with a coverage threshold and period matching across calendars (see :mod:climval.align.temporal).regrid: interpolate or remap onto the target grid, or sample the grid at station locations. A dask source is rechunked to whole horizontal fields first, so interpolation works on a few large chunks.region_mask: apply a regionmask polygon on the target grid.units: convert the candidate into the reference's units.missing: paired mask; a point counts only where both are valid.weights: cell area (given, or computed from cell bounds), cos(latitude) on request, or uniform for station data.
Inputs are cast to float64 (lazily for dask arrays), so lazy and eager runs of float32 data give the same values. The aligned dask arrays are rechunked to whole horizontal fields and dask's automatic chunk size along time, the same chunks for both inputs.
:func:align reads no data values. It reads coordinates and, when an input
is a Dataset or a file whose time, latitude or longitude bounds are 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.
Box
dataclass
¶
Box(lat: tuple[float, float] = (-90.0, 90.0), lon: tuple[float, float] | None = None, name: str | None = None)
A latitude and longitude box in degrees.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
lat
|
(south, north)
|
|
(-90.0, 90.0)
|
lon
|
(west, east)
|
Read eastward from |
None
|
name
|
str
|
|
None
|
MaskRegion
dataclass
¶
One region of a regionmask.Regions collection, used as a polygon mask.
mask ¶
Boolean mask on a rectilinear grid, True inside the region.
AlignedPair
dataclass
¶
AlignedPair(reference: DataArray, candidate: DataArray, weights: DataArray | None, steps: list[dict[str, Any]], inputs: dict[str, dict[str, Any]], variable: str, units: str | None, spatial_dims: tuple[str, ...], has_time: bool, frequency: str | None = None, options: dict[str, Any] = dict(), time_weights: DataArray | None = None)
The reference and candidate after alignment, on the same points.
reference and candidate share every coordinate and are NaN
wherever either one is missing. weights holds spatial weights on the
target grid (dims lat and/or lon) or None for uniform weights.
align ¶
align(reference: InputLike, candidate: InputLike, variable: str | tuple[str, str] | None = None, *, region: RegionLike = None, period: tuple[Any, Any] | None = None, regrid: str = 'bilinear', target: str | DataArray | Dataset = 'coarser', time: str = 'intersect', freq: str | None = None, min_coverage: float = DEFAULT_MIN_COVERAGE, units: str | Mapping[str, str] = 'convert', weights: str | DataArray | None = 'area', area: DataArray | None = None, open_kwargs: Mapping[str, Any] | None = None) -> AlignedPair
Align a candidate with a reference without reading data values; see module docs.
AlignedPair
dataclass
¶
AlignedPair(reference: DataArray, candidate: DataArray, weights: DataArray | None, steps: list[dict[str, Any]], inputs: dict[str, dict[str, Any]], variable: str, units: str | None, spatial_dims: tuple[str, ...], has_time: bool, frequency: str | None = None, options: dict[str, Any] = dict(), time_weights: DataArray | None = None)
The reference and candidate after alignment, on the same points.
reference and candidate share every coordinate and are NaN
wherever either one is missing. weights holds spatial weights on the
target grid (dims lat and/or lon) or None for uniform weights.