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
|
|
required |
candidate
|
InputLike
|
|
required |
variable
|
str | tuple[str, str] | None
|
Variable name, or a pair (reference name, candidate name) when they
differ, for example |
None
|
region
|
RegionLike
|
|
None
|
period
|
tuple[Any, Any] | None
|
|
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 " |
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: |
'area'
|
area
|
DataArray | None
|
Cell area on the target grid (for example CMIP |
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 |
'contiguous'
|
metrics
|
Sequence[str | BaseMetric] | None
|
Names or BaseMetric instances. Defaults to
:data: |
None
|
samples
|
Sequence[str]
|
Which point sets to compute over; see :mod: |
DEFAULT_SAMPLES
|
names
|
tuple[str, str] | None
|
Display names (reference, candidate). |
None
|
compute
|
bool
|
True (default) computes every sample in one |
True
|
open_kwargs
|
Mapping[str, Any] | None
|
Passed to the xarray opener for paths and URLs (for example
|
None
|
Returns:
| Type | Description |
|---|---|
Comparison
|
|
Raises:
| Type | Description |
|---|---|
InputError
|
A reference or candidate is missing. climval never substitutes
random data; use :func: |
(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 |
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: |
candidate
property
¶
The aligned candidate field (on the target grid, in the reference's units).
compute ¶
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 ¶
One scalar value. Raises when the value has extra dimensions.
values ¶
All scalar metric values of one sample and group.
field ¶
The full Dataset of one sample (time series for 'space', maps for 'time').
to_dataframe ¶
Long table: sample, group, metric, value, units (plus any extra dims).
check ¶
Evaluate limits; see :func:climval.evaluate_thresholds.
demo ¶
Run :func:compare on :func:demo_data. The result is flagged synthetic.
demo_data ¶
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.