Skip to content

Alignment

align

Alignment: put a reference and a candidate on the same points.

:func:align runs these steps in order and records each one:

  1. inputs: resolve DataArray, Dataset, path or URL (lazily, except CSV).
  2. coordinates: find lat, lon and time (CF aware), rename them, sort latitude ascending, detect curvilinear grids and station data.
  3. target_grid: by default the coarser of the two grids; station locations are always the target when one input is station data.
  4. longitude: express both inputs in one longitude frame (the target grid's convention, or a frame that keeps the region contiguous).
  5. 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.
  6. 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).
  7. 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.
  8. region_mask: apply a regionmask polygon on the target grid.
  9. units: convert the candidate into the reference's units.
  10. missing: paired mask; a point counts only where both are valid.
  11. 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 west to east. west > east crosses the antimeridian. None keeps all longitudes.

None
name str
None

lon_width property

lon_width: float

Eastward width in degrees, 360 for all longitudes.

west property

west: float

West edge expressed in [-180, 180).

MaskRegion dataclass

MaskRegion(regions: Any, key: int | str)

One region of a regionmask.Regions collection, used as a polygon mask.

mask

mask(lat: ndarray, lon: ndarray) -> xr.DataArray

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.

time_weights class-attribute instance-attribute

time_weights: DataArray | None = None

Length in days of the period each time step stands for (monthly and yearly data).

to_dataset

to_dataset() -> xr.Dataset

Both aligned fields (and weights) in one Dataset for inspection.

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.

time_weights class-attribute instance-attribute

time_weights: DataArray | None = None

Length in days of the period each time step stands for (monthly and yearly data).

to_dataset

to_dataset() -> xr.Dataset

Both aligned fields (and weights) in one Dataset for inspection.