Skip to content

Metrics

Evaluate metrics on an aligned pair, per sample and per group.

A sample says which points a number is computed over:

space_time Every valid point in space and time pooled, each weighted by its spatial weight (cell area) times its time weight. One value per group. climatology The spatial pattern of the time-mean fields: both inputs are averaged over the (paired) time steps of the group first, with time weights, then compared over space with spatial weights. This is the usual Taylor diagram and Gleckler et al. (2008) statistic. One value per group. space The spatial pattern at each time step, giving a time series of values (dimension time). Not grouped. time Temporal statistics at each grid point, with time weights, giving maps (dimensions lat and lon). One map per group.

Time weights: for monthly and yearly comparisons each time step counts in proportion to the length of its period in days (in the reference's calendar), the same weighting climval uses to aggregate months into years. Daily and sub-daily steps count equally. The space_time and time samples and the time mean of climatology use these time weights.

Groups come from by: "season" (DJF, MAM, JJA, SON), "month" or "year". The group "all" holds the whole period and is always present. With seasons="contiguous" (default) a December belongs to the following year's DJF, and a season of a given year counts only when all three of its months are present, so partial winters at the start and end of the period are left out (recorded in the provenance). For daily and sub-daily data a month counts as present only when at least min_coverage (default 0.8) of its time steps are, so one day of December does not complete a DJF. seasons="calendar" pools every December, January and February in the period into DJF, whether or not they belong to one winter, as xarray's time.season does.

BaseMetric

Base for all metrics.

Attributes:

Name Type Description
name str

Key used in results and in the registry.

higher_is_better bool
units_kind str or None

"data" (units of the variable), "dimensionless", "percent", or None.

needs_full_sample bool

True for rank and quantile metrics, which need the whole sample at once (see the module notes on memory).

ratio_scale bool

True for metrics that divide by a reference value (KGE, percentile bias). :func:climval.compare gives them temperatures on an absolute scale.

reduce

reduce(reference: DataArray, candidate: DataArray, weights: DataArray, dims: Sequence[str]) -> xr.DataArray

Reduce over dims. Default: apply the NumPy compute per sample.

compute

compute(reference: ndarray, candidate: ndarray, weights: ndarray | None = None) -> float

Value for two NumPy arrays.

Both are flattened; points where either value or the weight is not finite are dropped; weights must not be negative and are normalised to sum to one over the remaining points.

get_metric

get_metric(name: str) -> BaseMetric

Metric by name or alias.

'percentile_bias_p' builds a percentile bias for any N from 0 to 100; write a decimal point as '_' or '.': 'percentile_bias_p99_9' is the 99.9th percentile (its name is 'percentile_bias_p99_9').

wmean

wmean(x: DataArray, w: DataArray, dims: Sequence[str]) -> xr.DataArray

Weighted mean over dims; points with zero weight do not count.