Skip to content

compare and Comparison

compare

compare(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, by: str | None = None, seasons: str = 'contiguous', metrics: Sequence[str | BaseMetric] | None = None, samples: Sequence[str] = DEFAULT_SAMPLES, names: tuple[str, str] | None = None, compute: bool = True, open_kwargs: Mapping[str, Any] | None = None) -> Comparison

Compare a candidate with a reference after aligning them.

Parameters:

Name Type Description Default
reference InputLike

xarray.DataArray, xarray.Dataset (with variable), a path or URL to NetCDF, Zarr or CSV (local, or remote through fsspec, for example gs:// or s3://; Zarr stores are recognised by a .zarr suffix or by their metadata), or a list of NetCDF paths. NetCDF and Zarr are opened with dask chunks and read chunk by chunk when the metrics are computed; CSV is read into memory. A CSV with latitude and longitude columns that do not form a full grid is station data (see :func:climval.align.align).

required
candidate InputLike

xarray.DataArray, xarray.Dataset (with variable), a path or URL to NetCDF, Zarr or CSV (local, or remote through fsspec, for example gs:// or s3://; Zarr stores are recognised by a .zarr suffix or by their metadata), or a list of NetCDF paths. NetCDF and Zarr are opened with dask chunks and read chunk by chunk when the metrics are computed; CSV is read into memory. A CSV with latitude and longitude columns that do not form a full grid is station data (see :func:climval.align.align).

required
variable str | tuple[str, str] | None

Variable name, or a pair (reference name, candidate name) when they differ, for example ("t2m", "tas"). Optional for single-variable inputs.

None
region RegionLike

climval.Box(lat=(s, n), lon=(w, e)) (w > e crosses the antimeridian), a dict with lat and lon, or a regionmask region such as "ar6.land:NEU". Applied before regridding.

None
period tuple[Any, Any] | None

(start, end) as "YYYY", "YYYY-MM" or "YYYY-MM-DD", read on calendar fields, so it means the same in every calendar.

None
regrid str

"bilinear" (default), "nearest" or "conservative" (needs xESMF; the only option for curvilinear grids, and the only one that averages a fine grid over coarse cells).

'bilinear'
target str | DataArray | Dataset

Grid to compare on: "coarser" (default: the grid with the larger cells), "reference", "candidate", or an xarray object holding the target grid. With station data the stations are the target.

'coarser'
time str

"intersect" (default) keeps the periods present in both; "exact" requires the same periods.

'intersect'
freq str | None

Common time frequency: "h" or "h" (for example "3h"), "D", "MS" (monthly) or "YS" (yearly). Defaults to the coarser native frequency of the two inputs. Native frequencies come from time bounds, then from a frequency attribute (CMIP vocabulary such as "mon", "day", "3hr"), then from the time steps. Declare it on an input with da.assign_attrs(frequency="mon") when the steps alone are ambiguous (one month per year, a single time step).

None
min_coverage float

Fraction (0 to 1] of a period's native steps that must hold a valid value, per grid cell, for its aggregated value to count. Default 0.8.

DEFAULT_MIN_COVERAGE
units str | Mapping[str, str]

"convert" (default) converts the candidate to the reference's units, "strict" requires equal units, "ignore" skips the check, or a dict {"reference": ..., "candidate": ...} declares units first.

'convert'
weights str | DataArray | None

"area" (default: the given or cell_measures area, else cell area computed from the target grid's latitude and longitude bounds; see :mod:climval.align.weights), "cos_lat", None for uniform weights, or a DataArray.

'area'
area DataArray | None

Cell area on the target grid (for example CMIP areacella).

None
by str | None

None, "season", "month" or "year": add per-group values.

None
seasons str

"contiguous" (default): December belongs to the following year's DJF and incomplete seasons are left out. "calendar": every December, January and February in the period form DJF, as in xarray's time.season grouping.

'contiguous'
metrics Sequence[str | BaseMetric] | None

Names or BaseMetric instances. Defaults to :data:climval.metrics.DEFAULT_METRICS.

None
samples Sequence[str]

Which point sets to compute over; see :mod:climval.metrics.engine. Default ("space_time", "climatology").

DEFAULT_SAMPLES
names tuple[str, str] | None

Display names (reference, candidate).

None
compute bool

True (default) computes every sample in one dask.compute call. False returns a lazy Comparison; call .compute() later.

True
open_kwargs Mapping[str, Any] | None

Passed to the xarray opener for paths and URLs (for example storage_options).

None

Returns:

Type Description
Comparison

Raises:

Type Description
InputError

A reference or candidate is missing. climval never substitutes random data; use :func:climval.demo for a demonstration.

(AlignmentError, UnitsError)

The inputs cannot be aligned as requested.

Comparison

Comparison(*, reference_name: str, candidate_name: str, aligned: AlignedPair, metrics: list[BaseMetric], samples: dict[str, Dataset], provenance: dict[str, Any], by: str | None, synthetic: bool = False)

Metric values for one candidate against one reference, with provenance.

Attributes:

Name Type Description
reference_name, candidate_name str
variable str

The reference's variable name.

units str or None

Units of the aligned data (the reference's units).

metrics list of BaseMetric
samples dict of str to xarray.Dataset

One Dataset per sample ("space_time", "climatology", "space", "time"), a variable per metric plus n_points, and a group dimension ("all" plus one entry per season, month or year).

aligned AlignedPair

The aligned reference and candidate, for inspection.

provenance dict

JSON-serialisable record of inputs, alignment steps and software.

synthetic bool

True only for :func:climval.demo results.

reference property

reference: DataArray

The aligned reference field.

candidate property

candidate: DataArray

The aligned candidate field (on the target grid, in the reference's units).

compute

compute() -> Comparison

Compute every metric and the aligned-value hashes in one dask.compute call.

dask shares the tasks that read and align the inputs between all samples and metrics, so each input chunk is read once. NumPy inputs were aligned in memory already.

value

value(metric: str, sample: str = 'space_time', group: str = 'all') -> float

One scalar value. Raises when the value has extra dimensions.

values

values(sample: str = 'space_time', group: str = 'all') -> dict[str, float]

All scalar metric values of one sample and group.

field

field(sample: str) -> xr.Dataset

The full Dataset of one sample (time series for 'space', maps for 'time').

rows

rows() -> list[dict[str, Any]]

Long-format rows for the scalar samples.

to_dataframe

to_dataframe() -> pd.DataFrame

Long table: sample, group, metric, value, units (plus any extra dims).

check

check(thresholds: Mapping[str, Mapping[str, Any]]) -> ThresholdResult

Evaluate limits; see :func:climval.evaluate_thresholds.

export

export(path: str | Path) -> None

Write .json, .html or .md, chosen by extension.

table

table() -> str

Plain-text table of the scalar values.

summary

summary() -> None

Print the values and the alignment steps.

demo

demo(seed: int = 0, **kwargs: Any) -> Comparison

Run :func:compare on :func:demo_data. The result is flagged synthetic.

demo_data

demo_data(seed: int = 0) -> tuple[xr.DataArray, xr.DataArray]

Small synthetic reference and candidate for demonstrations and tests.

The reference is a 4 degree global grid, longitude -180..180, latitude ascending, monthly means 2000 to 2004 in the standard calendar, in K. The candidate is a 5 degree grid, longitude 0..360, latitude descending, monthly means 1998 to 2003 in the 360_day calendar, in degC, with a warm bias of about 1 K and noise. Every alignment step has work to do.